From 9bf666e38cd598aaaff629596eaed9021c207724 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Wed, 29 Jul 2026 05:55:40 +0000 Subject: [PATCH] =?UTF-8?q?feat:=20add=20LLM=20MCP=20reference=20fa=C3=A7a?= =?UTF-8?q?des=20plan=20and=20scaffold?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Spec and scaffold Claude/Cursor/ChatGPT/Grok MCP client façades that invoke Traverse workflows via traverse-mcp instead of prompt skills. Co-authored-by: Enrico Piovesan --- AGENTS.md | 1 + README.md | 3 +- apps/llm-mcp-reference/README.md | 63 ++++++++++ .../clients/chatgpt/README.md | 20 +++ .../clients/claude-code/.mcp.json.example | 12 ++ .../clients/claude-code/README.md | 12 ++ .../clients/claude-desktop/README.md | 13 ++ .../clients/claude-desktop/mcp.json.example | 12 ++ .../clients/cursor/README.md | 11 ++ .../clients/cursor/mcp.json.example | 12 ++ apps/llm-mcp-reference/clients/grok/README.md | 14 +++ .../shared/prompts/system-boundary.md | 15 +++ .../shared/workflows/meeting-notes.md | 17 +++ .../shared/workflows/traverse-starter.md | 21 ++++ docs/adopted-platform-clients.md | 4 +- docs/llm-reference-apps-plan.md | 114 ++++++++++++++++++ docs/production-reference-plan.md | 3 +- scripts/ci/llm_mcp_reference_smoke.sh | 43 +++++++ scripts/ci/repository_checks.sh | 3 + 19 files changed, 390 insertions(+), 3 deletions(-) create mode 100644 apps/llm-mcp-reference/README.md create mode 100644 apps/llm-mcp-reference/clients/chatgpt/README.md create mode 100644 apps/llm-mcp-reference/clients/claude-code/.mcp.json.example create mode 100644 apps/llm-mcp-reference/clients/claude-code/README.md create mode 100644 apps/llm-mcp-reference/clients/claude-desktop/README.md create mode 100644 apps/llm-mcp-reference/clients/claude-desktop/mcp.json.example create mode 100644 apps/llm-mcp-reference/clients/cursor/README.md create mode 100644 apps/llm-mcp-reference/clients/cursor/mcp.json.example create mode 100644 apps/llm-mcp-reference/clients/grok/README.md create mode 100644 apps/llm-mcp-reference/shared/prompts/system-boundary.md create mode 100644 apps/llm-mcp-reference/shared/workflows/meeting-notes.md create mode 100644 apps/llm-mcp-reference/shared/workflows/traverse-starter.md create mode 100644 docs/llm-reference-apps-plan.md create mode 100755 scripts/ci/llm_mcp_reference_smoke.sh diff --git a/AGENTS.md b/AGENTS.md index d5a4cd2..82deec7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -24,6 +24,7 @@ gh project item-list 2 --owner traverse-framework --format json --limit 300 \ | `registry-ref-full-kit-cutover` | **Done** (#235) | All six primary components use `registry_ref` | | `meeting-notes-wave2-os-ports` | **Done** (#236) | iOS + macOS + Windows + Android meeting-notes embeds | | `consume-product-wasm-agents` | **Done** (#227) | Digest-pinned Traverse-published starter agents | +| `llm-mcp-reference-apps-plan` | **In Progress** | LLM MCP façades plan + scaffold (`apps/llm-mcp-reference/`) | Full gap table + wave notes: [`docs/production-reference-plan.md`](docs/production-reference-plan.md). diff --git a/README.md b/README.md index b366a97..09a0134 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ UI examples for [Traverse](https://github.com/traverse-framework/Traverse). **You need:** Node.js 24+ (see `.nvmrc`) and a local [Traverse](https://github.com/traverse-framework/Traverse) clone — set `TRAVERSE_REPO` and run the sync script for your platform before the app can load WASM. **Success looks like:** submit a note and see title, tags, note type, next action, and status filled in by the runtime (the UI does not invent those fields). -> **Agents / LLMs:** this repo is UI-only — render runtime fields, never compute business output. Claim work via [`AGENTS.md`](AGENTS.md). Authoring the capability a UI here consumes? See [traverse-framework/claude-skills](https://github.com/traverse-framework/claude-skills) for a Claude Skill covering contract authoring, composition, and validation. +> **Agents / LLMs:** this repo is UI-only — render runtime fields, never compute business output. Claim work via [`AGENTS.md`](AGENTS.md). For **LLM product façades** that call Traverse workflows via MCP (instead of prompt skills), see [`apps/llm-mcp-reference/`](apps/llm-mcp-reference/) and [`docs/llm-reference-apps-plan.md`](docs/llm-reference-apps-plan.md). Authoring capabilities? See [traverse-framework/claude-skills](https://github.com/traverse-framework/claude-skills). --- @@ -31,6 +31,7 @@ UI examples for [Traverse](https://github.com/traverse-framework/Traverse). | macOS demo | [`apps/macos-demo/`](apps/macos-demo/) | | Browser consumer façade | [`apps/browser-consumer/`](apps/browser-consumer/) | | youaskm3 starter kit | [`apps/youaskm3-starter-kit/`](apps/youaskm3-starter-kit/) | +| LLM MCP façades (Claude/ChatGPT/Grok/Cursor) | [`apps/llm-mcp-reference/`](apps/llm-mcp-reference/) — plan: [`docs/llm-reference-apps-plan.md`](docs/llm-reference-apps-plan.md) | --- diff --git a/apps/llm-mcp-reference/README.md b/apps/llm-mcp-reference/README.md new file mode 100644 index 0000000..fdb4eb0 --- /dev/null +++ b/apps/llm-mcp-reference/README.md @@ -0,0 +1,63 @@ +# LLM MCP reference façades + +Secondary App-References tier: **LLM product façades** that call Traverse **workflows/capabilities** through MCP instead of encoding business logic in prompt “skills”. + +Plan: [`docs/llm-reference-apps-plan.md`](../../docs/llm-reference-apps-plan.md) + +## Layout + +```text +apps/llm-mcp-reference/ + README.md ← this file + shared/ + prompts/system-boundary.md + workflows/traverse-starter.md + workflows/meeting-notes.md + clients/ + claude-desktop/ + claude-code/ + cursor/ + chatgpt/ + grok/ +``` + +## Quick start (Mode A — local MCP stdio) + +1. Clone Traverse next to this repo and build/run the MCP server: + +```bash +export TRAVERSE_REPO="$(cd ../Traverse && pwd)" # adjust path +cd "$TRAVERSE_REPO" +cargo run -p traverse-mcp -- stdio +``` + +2. Point your LLM client at that command using the example config in `clients//`. +3. Paste `shared/prompts/system-boundary.md` into the agent/system instructions. +4. Follow `shared/workflows/traverse-starter.md` — submit a note via tools; **only display runtime fields**. + +Optional bearer token (execution commands): + +```bash +TRAVERSE_MCP_STDIO_BEARER_TOKEN="local-dev-secret" \ + cargo run -p traverse-mcp -- stdio +``` + +## Boundary + +| Allowed in this tree | Forbidden | +|---|---| +| MCP configs, adapter notes, workflow runbooks | Computing title/tags/recommendations in prompts | +| Rendering/summarizing **runtime JSON** for humans | Private Traverse crate imports | +| Linking to registry/`registry_ref` capabilities | Treating HTTP `serve` as the OS-shell production path | + +## Validation + +```bash +bash scripts/ci/llm_mcp_reference_smoke.sh +``` + +## Upstream docs + +- [MCP stdio server](https://github.com/traverse-framework/Traverse/blob/main/docs/mcp-stdio-server.md) +- [Packaged MCP artifact](https://github.com/traverse-framework/Traverse/blob/main/docs/packaged-traverse-mcp-server-artifact.md) +- [youaskm3 canonical MCP client path](https://github.com/traverse-framework/Traverse/blob/main/docs/youaskm3-canonical-mcp-client-path.md) diff --git a/apps/llm-mcp-reference/clients/chatgpt/README.md b/apps/llm-mcp-reference/clients/chatgpt/README.md new file mode 100644 index 0000000..d5d9f28 --- /dev/null +++ b/apps/llm-mcp-reference/clients/chatgpt/README.md @@ -0,0 +1,20 @@ +# ChatGPT — Traverse workflow façade + +ChatGPT’s integration surface evolves (Custom GPTs, Actions, MCP support where offered). This folder is the **App-Refs equivalent** of an OS client README: how to bind ChatGPT to Traverse **without** turning the GPT instructions into a business-logic skill. + +## v1 approach + +1. Run Traverse MCP stdio locally (or a future hosted MCP gateway — not specified here). +2. If the product supports MCP, point it at the same command shape as [`../claude-desktop/mcp.json.example`](../claude-desktop/mcp.json.example). +3. If only HTTP Actions are available, map Actions to a **thin gateway** that calls the same capabilities the MCP server would (gateway is Traverse/App ops — not invented field math in the GPT). +4. Always include [`../../shared/prompts/system-boundary.md`](../../shared/prompts/system-boundary.md) in GPT instructions. +5. Success criteria: same as [`../../shared/workflows/traverse-starter.md`](../../shared/workflows/traverse-starter.md). + +## Non-goals (this slice) + +- Publishing a store GPT +- Re-implementing validate/process/summarize in the GPT prompt + +## Follow-on ticket + +`llm-mcp-chatgpt-adapter` — concrete Actions schema or MCP wiring once the product API is stable for this kit. diff --git a/apps/llm-mcp-reference/clients/claude-code/.mcp.json.example b/apps/llm-mcp-reference/clients/claude-code/.mcp.json.example new file mode 100644 index 0000000..df29206 --- /dev/null +++ b/apps/llm-mcp-reference/clients/claude-code/.mcp.json.example @@ -0,0 +1,12 @@ +{ + "mcpServers": { + "traverse": { + "command": "cargo", + "args": ["run", "-p", "traverse-mcp", "--", "stdio"], + "cwd": "/ABS/PATH/TO/Traverse", + "env": { + "TRAVERSE_REPO": "/ABS/PATH/TO/Traverse" + } + } + } +} diff --git a/apps/llm-mcp-reference/clients/claude-code/README.md b/apps/llm-mcp-reference/clients/claude-code/README.md new file mode 100644 index 0000000..38cb7e7 --- /dev/null +++ b/apps/llm-mcp-reference/clients/claude-code/README.md @@ -0,0 +1,12 @@ +# Claude Code — Traverse MCP façade + +## Setup + +1. Ensure Traverse builds: `cargo run -p traverse-mcp -- stdio` from the Traverse root. +2. Copy [`.mcp.json.example`](.mcp.json.example) to your project or user MCP config as supported by Claude Code. +3. Set absolute `cwd` / `TRAVERSE_REPO`. +4. Load [`../../shared/prompts/system-boundary.md`](../../shared/prompts/system-boundary.md). +5. Run [`../../shared/workflows/traverse-starter.md`](../../shared/workflows/traverse-starter.md). + +Companion authoring skill (contracts only — not product business logic): +https://github.com/traverse-framework/claude-skills diff --git a/apps/llm-mcp-reference/clients/claude-desktop/README.md b/apps/llm-mcp-reference/clients/claude-desktop/README.md new file mode 100644 index 0000000..53b8a95 --- /dev/null +++ b/apps/llm-mcp-reference/clients/claude-desktop/README.md @@ -0,0 +1,13 @@ +# Claude Desktop — Traverse MCP façade + +## Setup + +1. Install/build Traverse so `cargo run -p traverse-mcp -- stdio` works. +2. Copy [`mcp.json.example`](mcp.json.example) into Claude Desktop’s MCP config (merge with existing servers). +3. Replace `TRAVERSE_REPO` paths with your absolute Traverse checkout. +4. Add [`../../shared/prompts/system-boundary.md`](../../shared/prompts/system-boundary.md) to the project/custom instructions. +5. Follow [`../../shared/workflows/traverse-starter.md`](../../shared/workflows/traverse-starter.md). + +## Boundary + +Claude must call MCP tools for business outcomes. Do not paste a “skill” that invents title/tags. diff --git a/apps/llm-mcp-reference/clients/claude-desktop/mcp.json.example b/apps/llm-mcp-reference/clients/claude-desktop/mcp.json.example new file mode 100644 index 0000000..df29206 --- /dev/null +++ b/apps/llm-mcp-reference/clients/claude-desktop/mcp.json.example @@ -0,0 +1,12 @@ +{ + "mcpServers": { + "traverse": { + "command": "cargo", + "args": ["run", "-p", "traverse-mcp", "--", "stdio"], + "cwd": "/ABS/PATH/TO/Traverse", + "env": { + "TRAVERSE_REPO": "/ABS/PATH/TO/Traverse" + } + } + } +} diff --git a/apps/llm-mcp-reference/clients/cursor/README.md b/apps/llm-mcp-reference/clients/cursor/README.md new file mode 100644 index 0000000..a3079e0 --- /dev/null +++ b/apps/llm-mcp-reference/clients/cursor/README.md @@ -0,0 +1,11 @@ +# Cursor — Traverse MCP façade + +## Setup + +1. Traverse checkout with working `traverse-mcp`. +2. Copy [`mcp.json.example`](mcp.json.example) into Cursor MCP settings (or project `.cursor`/MCP config as applicable). +3. Fix absolute paths. +4. Apply [`../../shared/prompts/system-boundary.md`](../../shared/prompts/system-boundary.md) in rules/instructions. +5. Exercise [`../../shared/workflows/traverse-starter.md`](../../shared/workflows/traverse-starter.md). + +Cursor agents working **in this repo** still claim OS tickets via `AGENTS.md`; this façade is for **product** workflows through Traverse MCP, not for replacing Project 2 claim locks. diff --git a/apps/llm-mcp-reference/clients/cursor/mcp.json.example b/apps/llm-mcp-reference/clients/cursor/mcp.json.example new file mode 100644 index 0000000..df29206 --- /dev/null +++ b/apps/llm-mcp-reference/clients/cursor/mcp.json.example @@ -0,0 +1,12 @@ +{ + "mcpServers": { + "traverse": { + "command": "cargo", + "args": ["run", "-p", "traverse-mcp", "--", "stdio"], + "cwd": "/ABS/PATH/TO/Traverse", + "env": { + "TRAVERSE_REPO": "/ABS/PATH/TO/Traverse" + } + } + } +} diff --git a/apps/llm-mcp-reference/clients/grok/README.md b/apps/llm-mcp-reference/clients/grok/README.md new file mode 100644 index 0000000..200288b --- /dev/null +++ b/apps/llm-mcp-reference/clients/grok/README.md @@ -0,0 +1,14 @@ +# Grok — Traverse workflow façade + +Grok / xAI tool-calling should bind to Traverse capabilities the same way OS shells do: **tools execute workflows; the model does not invent structured business fields**. + +## v1 approach + +1. Prefer MCP if/when the client supports stdio or remote MCP compatible with `traverse-mcp`. +2. Otherwise document tool schemas that forward to a thin gateway over Traverse public APIs (same boundary as ChatGPT Actions). +3. System prompt: [`../../shared/prompts/system-boundary.md`](../../shared/prompts/system-boundary.md). +4. Workflow: [`../../shared/workflows/traverse-starter.md`](../../shared/workflows/traverse-starter.md). + +## Follow-on ticket + +`llm-mcp-grok-adapter` — concrete tool schema + smoke once the integration path is chosen. diff --git a/apps/llm-mcp-reference/shared/prompts/system-boundary.md b/apps/llm-mcp-reference/shared/prompts/system-boundary.md new file mode 100644 index 0000000..6c70641 --- /dev/null +++ b/apps/llm-mcp-reference/shared/prompts/system-boundary.md @@ -0,0 +1,15 @@ +# System boundary — Traverse LLM façade + +You are a **façade** over the Traverse runtime. You do **not** invent business outcomes. + +## Rules + +1. Use MCP / Traverse tools to **discover, validate, and execute** capabilities or workflows. +2. When presenting results, only report fields returned by the runtime (for example title, tags, noteType, suggestedNextAction, status, action items). If a field is missing, say it is missing — **do not invent it**. +3. Do not re-implement starter / doc-approval / meeting-notes pipelines in natural language “skills”. +4. If the tool fails or the runtime is offline, report the tool error. Do not fabricate a successful structured result. +5. Prefer deterministic tool execution over long chain-of-thought process control. + +## Why + +The same WASM capabilities power OS reference apps (Web, iOS, Android, …). Keeping logic in Traverse makes outcomes **deterministic across models** and **cheaper in tokens**. diff --git a/apps/llm-mcp-reference/shared/workflows/meeting-notes.md b/apps/llm-mcp-reference/shared/workflows/meeting-notes.md new file mode 100644 index 0000000..cbccd9a --- /dev/null +++ b/apps/llm-mcp-reference/shared/workflows/meeting-notes.md @@ -0,0 +1,17 @@ +# Workflow runbook — meeting-notes + +Equivalent to the **meeting-notes** OS shell: paste a transcript; show runtime-owned action items, decisions, follow-ups, summary. + +## Capability + +Discover and execute `meeting-notes.process` (or the workflow entrypoint that wraps it) via MCP. + +## Happy path + +1. Provide a short transcript as tool input. +2. Display only runtime list/structured fields from the result. +3. Do not invent action items the runtime did not return. + +## Note + +Full live wiring may land in ticket `llm-mcp-meeting-notes-workflow`. Until then this runbook is the contract for façades. diff --git a/apps/llm-mcp-reference/shared/workflows/traverse-starter.md b/apps/llm-mcp-reference/shared/workflows/traverse-starter.md new file mode 100644 index 0000000..62a4a4d --- /dev/null +++ b/apps/llm-mcp-reference/shared/workflows/traverse-starter.md @@ -0,0 +1,21 @@ +# Workflow runbook — traverse-starter + +Equivalent to the **traverse-starter** OS shell: submit a short note; show runtime-owned metadata. + +## Capability / workflow + +Use the Traverse MCP server’s discovery/description tools to locate the starter note pipeline (validate → process → summarize or the published `traverse-starter.*` capabilities). Prefer executing the **governed workflow/entrypoint** the server exposes rather than free-form multi-step prompting. + +## Happy path + +1. Confirm MCP server is reachable (`describe_server` / discovery). +2. Execute with a note string input (example: `"Ship the MCP façade docs tomorrow"`). +3. Render **only** runtime fields from the execution report (e.g. title, tags, noteType, suggestedNextAction, status / validation issues / summary when present). + +## Success looks like + +Same as Web starter: structured fields filled by the runtime, not by the model. + +## Failure + +If execution fails, show the tool error. Do not invent a title/tags payload. diff --git a/docs/adopted-platform-clients.md b/docs/adopted-platform-clients.md index f999c77..0fb3a8b 100644 --- a/docs/adopted-platform-clients.md +++ b/docs/adopted-platform-clients.md @@ -7,7 +7,7 @@ This repository is the **canonical home** for checked-in application UI, platfor | Tier | Apps | What “done” means | |---|---|---| | **Primary product shells** | `traverse-starter`, `doc-approval`, `meeting-notes` | Embedded (or showcase-track embed) production path; digest pin; SDK doubles; production DoD on PRs; Linux-runnable slices of `embedded_smoke` are merge-blocking | -| **Adopted / secondary** | paths in the table below | Lighter maintenance; demo/kit smokes only; **not** hard-fail slices of `embedded_smoke` | +| **Adopted / secondary** | paths in the table below + `apps/llm-mcp-reference/` | Lighter maintenance; demo/kit smokes only; **not** hard-fail slices of `embedded_smoke` | | **Debugger** | `trace-explorer` | Not a product shell — embedded Trace API companion (`embed-trace-explorer`) | Do **not** copy `react-demo` / Expedition demo patterns into primary shells without an explicit caveat that those apps are secondary kits, not the Phase 3/4 production reference. @@ -21,6 +21,7 @@ Ownership boundary (Traverse [#703](https://github.com/traverse-framework/Traver | `apps/macos-demo/` | Reference Apps | [`apps/macos-demo/`](../apps/macos-demo/) | | `apps/react-demo/` | Reference Apps | [`apps/react-demo/`](../apps/react-demo/) | | `apps/youaskm3-starter-kit/` | Reference Apps | [`apps/youaskm3-starter-kit/`](../apps/youaskm3-starter-kit/) | +| `apps/llm-mcp-reference/` (new) | Reference Apps | [`apps/llm-mcp-reference/`](../apps/llm-mcp-reference/) — LLM MCP façades; [`llm-reference-apps-plan.md`](llm-reference-apps-plan.md) | | Runtime fixtures / manifests | Traverse | `examples/` in Traverse (not adopted) | Shared fixture for native demos: [`fixtures/expedition-runtime-session.json`](../fixtures/expedition-runtime-session.json). @@ -33,6 +34,7 @@ Shared fixture for native demos: [`fixtures/expedition-runtime-session.json`](.. | macOS demo | `bash scripts/ci/macos_demo_smoke.sh` | | React demo | `bash scripts/ci/react_demo_smoke.sh` | | youaskm3 starter | `bash scripts/ci/youaskm3_starter_kit_smoke.sh` | +| LLM MCP reference | `bash scripts/ci/llm_mcp_reference_smoke.sh` | | React live adapter | `TRAVERSE_REPO=… bash scripts/ci/react_demo_live_adapter_smoke.sh` | | Browser consumer live | `TRAVERSE_REPO=… bash scripts/ci/browser_consumer_package_smoke.sh` | diff --git a/docs/llm-reference-apps-plan.md b/docs/llm-reference-apps-plan.md new file mode 100644 index 0000000..43ae7f3 --- /dev/null +++ b/docs/llm-reference-apps-plan.md @@ -0,0 +1,114 @@ +# LLM reference façades (MCP) — plan + +## Purpose + +Extend App-References beyond OS UI shells with **reference façades for major LLM products** (Claude, ChatGPT, Grok, Cursor, and similar). + +These façades are the LLM equivalent of `traverse-starter` / `meeting-notes` clients: + +| OS ref app | LLM ref façade | +|---|---| +| Swift / React / WinUI shell | Claude Desktop / Cursor / ChatGPT / Grok client config | +| Submits input → renders runtime fields | Invokes MCP tools → presents runtime JSON (no invented business fields) | +| Embedded WASM host | Traverse **MCP stdio server** (`traverse-mcp`) over the same capabilities/workflows | + +**Core thesis:** prefer Traverse **workflows/capabilities** over traditional prompt “skills” for business logic. The model handles language and intent; **deterministic logic runs in Traverse** (local embed or a host you control) → more repeatable outcomes and **lower token cost**. + +## Architecture boundary (locked) + +```text +┌─────────────────────────────┐ +│ LLM product (Claude/…) │ language, tool selection, UX +└──────────────┬──────────────┘ + │ MCP (stdio / product adapter) +┌──────────────▼──────────────┐ +│ apps/llm-mcp-reference/ │ App-Refs façade (configs, prompts, docs) +│ — no business field math — │ +└──────────────┬──────────────┘ + │ tools: discover / execute / report +┌──────────────▼──────────────┐ +│ Traverse traverse-mcp │ façade over runtime authority +└──────────────┬──────────────┘ + │ +┌──────────────▼──────────────┐ +│ Registry capabilities + │ WASM agents + workflows (SoT) +│ workflows (e.g. starter) │ +└─────────────────────────────┘ +``` + +Rules (same as OS shells): + +1. **No business logic in the façade** — do not compute title/tags/recommendations in prompts or client code. +2. **Public Traverse surfaces only** — MCP package + public docs; no private runtime crates. +3. **Same catalog as OS apps** — `registry_ref` / published capabilities (e.g. `traverse-starter.*`, `meeting-notes.process`). +4. **Secondary tier** — not merge-blocking `embedded_smoke`; lighter smoke proves scaffold integrity. + +## Why not “skills”? + +| Traditional skill | Traverse workflow via MCP | +|---|---| +| Behavior re-negotiated in tokens each turn | Contract + WASM + workflow are versioned and tested | +| Drift across models/vendors | Same capability digest for Claude, Cursor, ChatGPT adapters | +| High token use for process control | Model supplies input; runtime returns structured fields | +| Hard to CI | Capability validation + MCP smoke already exist upstream | + +Skills remain useful for **authoring guidance** (e.g. [claude-skills](https://github.com/traverse-framework/claude-skills) for contract writing). They are **not** the place to implement product business rules that OS shells already get from WASM. + +## Reference clients in this repo + +Canonical tree: [`apps/llm-mcp-reference/`](../apps/llm-mcp-reference/). + +| Client folder | Product shape | v1 deliverable | +|---|---|---| +| `clients/claude-desktop/` | Claude Desktop MCP config | `mcp.json.example` + README | +| `clients/claude-code/` | Claude Code / CLI MCP | `.mcp.json.example` + README | +| `clients/cursor/` | Cursor MCP | `mcp.json.example` + README | +| `clients/chatgpt/` | ChatGPT (Custom GPT / Actions; MCP where available) | Adapter notes + tool mapping | +| `clients/grok/` | Grok / xAI tool calling | Adapter notes + tool mapping | + +Shared: + +- `shared/prompts/system-boundary.md` — mandatory “runtime owns fields” instruction +- `shared/workflows/*.md` — which starter workflows to call and what success looks like + +## Runtime host modes + +| Mode | When | Notes | +|---|---|---| +| **A. MCP stdio → local Traverse** (v1 default) | Developer laptop / agent IDE | `cargo run -p traverse-mcp -- stdio` with `TRAVERSE_REPO` | +| **B. MCP → embedded host in a sidecar process** | Stronger product isolation | Future; align with Spec 520 prepare/cache | +| **C. Remote MCP gateway** | Multi-tenant SaaS | Future; needs auth/tenancy — not this slice | + +v1 documents **Mode A** only. Do not revive HTTP `traverse-cli serve` as the production architecture for primary OS shells; MCP stdio is a **separate agent façade**, not a replacement for embedded Web/iOS/Android clients. + +## Phased tickets (Project 2) + +| Ticket ID | Intent | Status intent | +|---|---|---| +| `llm-mcp-reference-apps-plan` | Plan + scaffold (this doc + tree) | This ticket | +| `llm-mcp-claude-live-smoke` | Live Claude Desktop/Code path against `traverse-starter` | Follow-on Ready when plan merges | +| `llm-mcp-cursor-live-smoke` | Live Cursor MCP path | Follow-on | +| `llm-mcp-meeting-notes-workflow` | Document + config for meeting-notes via MCP | Follow-on | +| `llm-mcp-chatgpt-adapter` | ChatGPT Actions/GPT mapping (or MCP when shipped) | Future / Ready when API stable | +| `llm-mcp-grok-adapter` | Grok tool-calling mapping | Future / Ready when API stable | +| `llm-mcp-embedded-host` | Mode B embedded prepare/cache for MCP host | Blocked on Traverse Spec 520 implement | + +## Success criteria (plan slice) + +- A new contributor can open `apps/llm-mcp-reference/README.md` and understand LLM façades vs OS shells. +- Example MCP configs point at `traverse-mcp` stdio without inventing business logic. +- Board/docs list LLM façades as an explicit secondary tier. + +## Non-goals + +- Replacing primary OS product shells +- Prompt-only implementations of starter/doc-approval/meeting-notes pipelines +- Shipping store listings for ChatGPT plugins in this slice +- Multi-tenant hosted MCP SaaS + +## Related + +- Traverse MCP stdio: https://github.com/traverse-framework/Traverse/blob/main/docs/mcp-stdio-server.md +- youaskm3 MCP client path: https://github.com/traverse-framework/Traverse/blob/main/docs/youaskm3-canonical-mcp-client-path.md +- OS getting started: [`getting-started-embedded.md`](getting-started-embedded.md) +- Production plan: [`production-reference-plan.md`](production-reference-plan.md) diff --git a/docs/production-reference-plan.md b/docs/production-reference-plan.md index a3ee245..440c273 100644 --- a/docs/production-reference-plan.md +++ b/docs/production-reference-plan.md @@ -37,13 +37,14 @@ Related: | Digest sync | **Shared core + thin per-platform wrappers** — see [`runtime-bundle-sync.md`](runtime-bundle-sync.md) | Decision B | | Showcase rollout | **Wave 1:** Web + Linux/CLI (+ Android if stable); **Wave 2:** Windows + Apple | Decision C | | Product agents | Digest-pinned Traverse-published starter agents (`consume-product-wasm-agents` Done) | Gap capture | +| LLM MCP façades | **Secondary reference tier** — Claude/ChatGPT/Grok/Cursor configs invoke Traverse workflows via MCP; not prompt-skills for business logic — see [`llm-reference-apps-plan.md`](llm-reference-apps-plan.md) | Decision D | ### Primary vs secondary (locked) | Tier | Apps | Smoke / CI bar | |---|---|---| | **Primary product shells** | `traverse-starter`, `doc-approval`, `meeting-notes` | Production DoD; Linux-runnable `embedded_smoke` hard-fail | -| **Adopted / secondary** | `react-demo`, `android-demo`, `macos-demo`, `browser-consumer`, `youaskm3-starter-kit` | Lighter demo smokes only — **not** merge-blocking `embedded_smoke` targets | +| **Adopted / secondary** | `react-demo`, `android-demo`, `macos-demo`, `browser-consumer`, `youaskm3-starter-kit`, `llm-mcp-reference` | Lighter demo smokes only — **not** merge-blocking `embedded_smoke` targets | | **Debugger** | `trace-explorer` | Embedded Trace API companion — not a product shell to copy | Canonical narrative: [`adopted-platform-clients.md`](adopted-platform-clients.md) · front door: root `README.md`. diff --git a/scripts/ci/llm_mcp_reference_smoke.sh b/scripts/ci/llm_mcp_reference_smoke.sh new file mode 100755 index 0000000..0ddb8ec --- /dev/null +++ b/scripts/ci/llm_mcp_reference_smoke.sh @@ -0,0 +1,43 @@ +#!/usr/bin/env bash +# Scaffold integrity smoke for LLM MCP reference façades (secondary tier). +set -euo pipefail +ROOT="$(cd "$(dirname "$0")/../.." && pwd)" +fail=0 +need() { + if [ ! -e "$ROOT/$1" ]; then + echo "FAIL: missing $1" + fail=1 + else + echo "OK: $1" + fi +} +need docs/llm-reference-apps-plan.md +need apps/llm-mcp-reference/README.md +need apps/llm-mcp-reference/shared/prompts/system-boundary.md +need apps/llm-mcp-reference/shared/workflows/traverse-starter.md +need apps/llm-mcp-reference/shared/workflows/meeting-notes.md +need apps/llm-mcp-reference/clients/claude-desktop/README.md +need apps/llm-mcp-reference/clients/claude-desktop/mcp.json.example +need apps/llm-mcp-reference/clients/claude-code/README.md +need apps/llm-mcp-reference/clients/claude-code/.mcp.json.example +need apps/llm-mcp-reference/clients/cursor/README.md +need apps/llm-mcp-reference/clients/cursor/mcp.json.example +need apps/llm-mcp-reference/clients/chatgpt/README.md +need apps/llm-mcp-reference/clients/grok/README.md +# Configs must mention traverse-mcp, not invent business fields +if ! rg -q 'traverse-mcp' "$ROOT/apps/llm-mcp-reference/clients/claude-desktop/mcp.json.example"; then + echo "FAIL: claude-desktop mcp example must reference traverse-mcp" + fail=1 +fi +if rg -n -i 'invent (title|tags)|compute business' "$ROOT/apps/llm-mcp-reference/shared/prompts/system-boundary.md" >/dev/null; then + : # optional; boundary doc forbids inventing — ensure forbid language exists +fi +if ! rg -q 'do not invent' "$ROOT/apps/llm-mcp-reference/shared/prompts/system-boundary.md"; then + echo "FAIL: system-boundary.md must forbid inventing fields" + fail=1 +fi +if [ "$fail" -ne 0 ]; then + echo "llm_mcp_reference_smoke: FAILED" + exit 1 +fi +echo "llm_mcp_reference_smoke: PASS" diff --git a/scripts/ci/repository_checks.sh b/scripts/ci/repository_checks.sh index f1469de..4584813 100644 --- a/scripts/ci/repository_checks.sh +++ b/scripts/ci/repository_checks.sh @@ -102,6 +102,8 @@ check "apps/browser-consumer/index.js" "browser check "apps/macos-demo/Package.swift" "macos-demo Package.swift" check "apps/react-demo/src/main.js" "react-demo main" check "apps/youaskm3-starter-kit/README.md" "youaskm3 starter kit" +check "apps/llm-mcp-reference/README.md" "LLM MCP reference façades" +check "docs/llm-reference-apps-plan.md" "LLM reference apps plan" check "fixtures/expedition-runtime-session.json" "expedition runtime fixture" check "docs/adopted-platform-clients.md" "adopted platform clients doc" check "docs/production-playbook.md" "production playbook" @@ -110,6 +112,7 @@ check "scripts/ci/android_demo_smoke.sh" "android check "scripts/ci/macos_demo_smoke.sh" "macos demo smoke" check "scripts/ci/react_demo_smoke.sh" "react demo smoke" check "scripts/ci/youaskm3_starter_kit_smoke.sh" "youaskm3 starter smoke" +check "scripts/ci/llm_mcp_reference_smoke.sh" "LLM MCP reference smoke" check "scripts/ci/react_demo_live_adapter_smoke.sh" "react demo live smoke" check "scripts/ci/browser_consumer_package_smoke.sh" "browser consumer live smoke"