From 78a12fbdf6c5a760a7df9029bbbfea7f23e5b174 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Wed, 29 Jul 2026 06:04:45 +0000 Subject: [PATCH] docs: expand meeting-notes MCP runbook with tool sequence Document concrete traverse-mcp steps for meeting-notes.process, sample transcript, client pointers, and smoke checks for required tool names. Co-authored-by: Enrico Piovesan --- apps/llm-mcp-reference/README.md | 1 + .../clients/claude-code/README.md | 1 + .../clients/claude-desktop/README.md | 3 +- .../clients/cursor/README.md | 1 + .../shared/workflows/meeting-notes.md | 123 ++++++++++++++++-- docs/llm-reference-apps-plan.md | 8 +- scripts/ci/llm_mcp_reference_smoke.sh | 8 ++ 7 files changed, 131 insertions(+), 14 deletions(-) diff --git a/apps/llm-mcp-reference/README.md b/apps/llm-mcp-reference/README.md index fdb4eb0..83b7ef0 100644 --- a/apps/llm-mcp-reference/README.md +++ b/apps/llm-mcp-reference/README.md @@ -34,6 +34,7 @@ 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**. +5. For transcripts, follow `shared/workflows/meeting-notes.md` — concrete `describe_server` → `execute_entrypoint` → `render_execution_report` sequence for `meeting-notes.process`. Optional bearer token (execution commands): diff --git a/apps/llm-mcp-reference/clients/claude-code/README.md b/apps/llm-mcp-reference/clients/claude-code/README.md index 38cb7e7..e3b7fde 100644 --- a/apps/llm-mcp-reference/clients/claude-code/README.md +++ b/apps/llm-mcp-reference/clients/claude-code/README.md @@ -7,6 +7,7 @@ 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). +6. For transcripts, follow [`../../shared/workflows/meeting-notes.md`](../../shared/workflows/meeting-notes.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 index 53b8a95..5d50e52 100644 --- a/apps/llm-mcp-reference/clients/claude-desktop/README.md +++ b/apps/llm-mcp-reference/clients/claude-desktop/README.md @@ -7,7 +7,8 @@ 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). +6. For transcripts, follow [`../../shared/workflows/meeting-notes.md`](../../shared/workflows/meeting-notes.md). ## Boundary -Claude must call MCP tools for business outcomes. Do not paste a “skill” that invents title/tags. +Claude must call MCP tools for business outcomes. Do not paste a “skill” that invents title/tags or meeting-notes fields. diff --git a/apps/llm-mcp-reference/clients/cursor/README.md b/apps/llm-mcp-reference/clients/cursor/README.md index a3079e0..51793b6 100644 --- a/apps/llm-mcp-reference/clients/cursor/README.md +++ b/apps/llm-mcp-reference/clients/cursor/README.md @@ -7,5 +7,6 @@ 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). +6. For meeting transcripts, follow [`../../shared/workflows/meeting-notes.md`](../../shared/workflows/meeting-notes.md) (tool sequence + sample transcript). 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/shared/workflows/meeting-notes.md b/apps/llm-mcp-reference/shared/workflows/meeting-notes.md index cbccd9a..f8d9f67 100644 --- a/apps/llm-mcp-reference/shared/workflows/meeting-notes.md +++ b/apps/llm-mcp-reference/shared/workflows/meeting-notes.md @@ -1,17 +1,122 @@ # Workflow runbook — meeting-notes -Equivalent to the **meeting-notes** OS shell: paste a transcript; show runtime-owned action items, decisions, follow-ups, summary. +Equivalent to the **meeting-notes** OS shell: paste a transcript; show runtime-owned **action items**, **decisions**, **follow-ups**, and **summary**. -## Capability +OS twins: [`apps/meeting-notes/`](../../../meeting-notes/) (Web / iOS / macOS / Android / Windows / Linux / CLI). -Discover and execute `meeting-notes.process` (or the workflow entrypoint that wraps it) via MCP. +## Capability / workflow -## Happy path +| Field | Value | +|---|---| +| App id | `meeting-notes` | +| Workflow / capability | `meeting-notes.process` | +| Input | `{ "transcript": "" }` (max length mirrors shells: **5000**) | +| Runtime-owned output | `action_items[]`, `decisions[]`, `follow_ups[]`, `summary` | -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. +Discover this entrypoint through `traverse-mcp` — do **not** hard-code private crate paths. Prefer the **governed workflow/entrypoint** the server lists for `meeting-notes.process`. -## Note +## Prerequisites (Mode A) -Full live wiring may land in ticket `llm-mcp-meeting-notes-workflow`. Until then this runbook is the contract for façades. +1. Traverse checkout with working `traverse-mcp` (see [MCP stdio server](https://github.com/traverse-framework/Traverse/blob/main/docs/mcp-stdio-server.md)). +2. Client MCP config from `clients//` pointing at: + +```bash +cargo run -p traverse-mcp -- stdio +``` + +3. System instructions include [`../prompts/system-boundary.md`](../prompts/system-boundary.md). + +Optional bearer token for execution commands: + +```bash +TRAVERSE_MCP_STDIO_BEARER_TOKEN="local-dev-secret" \ + cargo run -p traverse-mcp -- stdio +``` + +Pass the same token on `execute_entrypoint` / `render_execution_report` as `auth.bearer` or `bearer_token` when required. + +## Concrete MCP tool sequence + +Use the public stdio command surface in order: + +| Step | Tool | Purpose | +|---|---|---| +| 1 | `describe_server` | Confirm MCP is up and Mode A local trust is available | +| 2 | `list_content_groups` → `describe_content_group` | Orient on governed content (when groups are present) | +| 3 | `list_entrypoints` | Find the entrypoint whose id/name maps to **`meeting-notes.process`** | +| 4 | `describe_entrypoint` | Confirm input expects a **transcript** (or equivalent payload field) | +| 5 | `validate_entrypoint` | Validate payload shape before execute | +| 6 | `execute_entrypoint` | Submit `{ "transcript": "…" }` (or the schema field `describe_entrypoint` documents) | +| 7 | `render_execution_report` | Present the public execution report / structured output | + +### Example agent checklist (copy into a session) + +```text +1. Call describe_server. +2. Call list_entrypoints; select meeting-notes.process (or the entrypoint that wraps it). +3. Call describe_entrypoint on that id; note required input fields. +4. Call validate_entrypoint with a short transcript payload. +5. Call execute_entrypoint with the same payload. +6. Call render_execution_report for the returned execution. +7. Show ONLY runtime fields: action_items, decisions, follow_ups, summary. + If a field is missing, say it is missing — do not invent tasks or decisions. +``` + +### Sample transcript (for live smoke) + +```text +Alex: We need Wave 2 ports for iOS and Android by Friday. +Sam: Agreed — I'll own the Android Compose shell. +Alex: Decision: use the embedded runtime path only, no sidecar. +``` + +Expected **shape** (values come from the runtime, not this runbook): + +```json +{ + "action_items": [{ "task": "…", "owner": "…", "due": "…" }], + "decisions": [{ "text": "…", "made_by": "…" }], + "follow_ups": ["…"], + "summary": "…" +} +``` + +## Success looks like + +Same as the Web shell ([`MeetingResult`](../../../meeting-notes/web-react/src/components/MeetingResult.tsx)): + +- Summary string from runtime +- Action items list (task + optional owner/due) +- Decisions list (text + optional made_by) +- Follow-ups string list +- Trace / report may be shown when the tool returns it — never synthesize business rows + +## Failure + +If `validate_entrypoint` or `execute_entrypoint` fails, surface the tool error envelope. Do **not** invent action items, decisions, follow-ups, or a summary. + +## Optional client snippets + +### Cursor + +After [`../../clients/cursor/mcp.json.example`](../../clients/cursor/mcp.json.example) is installed: + +1. Apply system-boundary rules. +2. Paste the agent checklist above. +3. Ask: “Run meeting-notes.process on this transcript via MCP tools and show only runtime fields.” + +### Claude Desktop / Claude Code + +Same checklist after installing [`../../clients/claude-desktop/mcp.json.example`](../../clients/claude-desktop/mcp.json.example) or [`../../clients/claude-code/.mcp.json.example`](../../clients/claude-code/.mcp.json.example). Claude must call MCP tools — do not paste a skill that invents meeting notes. + +### ChatGPT / Grok + +Until dedicated adapters ship (`llm-mcp-chatgpt-adapter` / `llm-mcp-grok-adapter`), map Actions / tool-calling schemas 1:1 to the tool sequence table above. The model still must not invent structured fields. + +## Related tickets + +| Ticket ID | Role | +|---|---| +| `llm-mcp-reference-apps-plan` | Scaffold + plan (Done) | +| `llm-mcp-meeting-notes-workflow` | This runbook | +| `llm-mcp-claude-live-smoke` / `llm-mcp-cursor-live-smoke` | Live evidence against traverse-starter (and optionally this workflow) | diff --git a/docs/llm-reference-apps-plan.md b/docs/llm-reference-apps-plan.md index 43ae7f3..16c56fa 100644 --- a/docs/llm-reference-apps-plan.md +++ b/docs/llm-reference-apps-plan.md @@ -85,10 +85,10 @@ v1 documents **Mode A** only. Do not revive HTTP `traverse-cli serve` as the pro | 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-reference-apps-plan` | Plan + scaffold (this doc + tree) | Done (#238) | +| `llm-mcp-claude-live-smoke` | Live Claude Desktop/Code path against `traverse-starter` | Ready | +| `llm-mcp-cursor-live-smoke` | Live Cursor MCP path | Ready | +| `llm-mcp-meeting-notes-workflow` | Document + config for meeting-notes via MCP | In Progress | | `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 | diff --git a/scripts/ci/llm_mcp_reference_smoke.sh b/scripts/ci/llm_mcp_reference_smoke.sh index 0ddb8ec..0f19935 100755 --- a/scripts/ci/llm_mcp_reference_smoke.sh +++ b/scripts/ci/llm_mcp_reference_smoke.sh @@ -36,6 +36,14 @@ if ! rg -q 'do not invent' "$ROOT/apps/llm-mcp-reference/shared/prompts/system-b echo "FAIL: system-boundary.md must forbid inventing fields" fail=1 fi +# meeting-notes runbook must document concrete MCP tool sequence +MN="$ROOT/apps/llm-mcp-reference/shared/workflows/meeting-notes.md" +for needle in 'meeting-notes.process' 'describe_server' 'list_entrypoints' 'execute_entrypoint' 'render_execution_report' 'action_items'; do + if ! rg -q "$needle" "$MN"; then + echo "FAIL: meeting-notes.md must mention $needle" + fail=1 + fi +done if [ "$fail" -ne 0 ]; then echo "llm_mcp_reference_smoke: FAILED" exit 1