From cbd332dc26bb93453d296545263897555ec53960 Mon Sep 17 00:00:00 2001 From: GeneAI Date: Mon, 11 May 2026 09:19:21 -0400 Subject: [PATCH] =?UTF-8?q?docs(specs):=20mcp-server-scope=20=E2=80=94=20f?= =?UTF-8?q?ocused=20MCP=20server=20for=20attune-gui=20(draft)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit attune-help and attune-author both expose MCP servers; attune-gui does not. Claude Code can't programmatically query attune-gui's data (specs, living docs, telemetry). Spec proposes a deliberately small MCP server with ~5 read-mostly tools mirroring existing FastAPI routes (gui_list_specs, gui_get_spec, gui_get_spec_status, gui_list_living_docs, gui_get_living_doc). Optional write tool: gui_set_spec_status (mirror of existing PUT route). Pairs with attune-ai's ops-specs-features spec (#230) — that one brings specs into attune ops dashboard for human viewing; this one exposes them to MCP for agent querying. Same workflow, different clients. Status: Draft. Gated on PR #30 stabilization + ops-specs-features gate clearing + no active CI debt. Identified during the 2026-05-11 attune-workspace Monday briefing. --- docs/specs/mcp-server-scope/decisions.md | 98 ++++++++++++++++++++++++ docs/specs/mcp-server-scope/tasks.md | 67 ++++++++++++++++ 2 files changed, 165 insertions(+) create mode 100644 docs/specs/mcp-server-scope/decisions.md create mode 100644 docs/specs/mcp-server-scope/tasks.md diff --git a/docs/specs/mcp-server-scope/decisions.md b/docs/specs/mcp-server-scope/decisions.md new file mode 100644 index 0000000..0979aed --- /dev/null +++ b/docs/specs/mcp-server-scope/decisions.md @@ -0,0 +1,98 @@ +# Decisions — MCP server for attune-gui (scope) + +**Status:** Draft (2026-05-11) — gated on briefing-followup batch +**Owner:** Patrick + +--- + +## Problem + +attune-help and attune-author both expose MCP servers +(`attune_help.mcp`, `attune_author.mcp.server`). attune-gui +does not. Its surface is FastAPI routes + frontend, which means +Claude Code (and other MCP clients) can't programmatically +query attune-gui's data — specs, living docs, telemetry, +federated views. + +This creates an asymmetry: every other attune package exposes +its key operations as MCP tools; attune-gui is the only one +that doesn't. + +## Decision + +Add a focused MCP server to attune-gui exposing a **deliberately +small** set of read-mostly tools. Don't replicate every FastAPI +route — pick the ones a Claude Code session would actually +want. + +## What's in scope (initial) + +Read-only or low-impact tools: + +- `gui_list_specs` — federated multi-root spec listing + (mirror of the FastAPI route from PR #30) +- `gui_get_spec` — fetch decisions.md / tasks.md / design.md / + requirements.md content for a spec +- `gui_get_spec_status` — current `**Status**:` line for a + spec's phase files +- `gui_list_living_docs` — enumerate living-docs templates +- `gui_get_living_doc` — fetch a specific living-docs + template's content + +Optional write tools (gated): + +- `gui_set_spec_status` — flip a spec's status (already + available via FastAPI; mirror to MCP for parity) + +## What's NOT in scope + +- Editing template content (covered by the GUI editor; not + Claude Code's job) +- Anthropic API passthrough — gui doesn't call Anthropic + directly anyway (verified 2026-05-11) +- Authentication / multi-tenant features +- Real-time WebSocket / SSE streaming +- Search / RAG over living-docs — that's attune-rag's job + +## Alternatives considered + +1. **No MCP server** — current state. attune-gui is + dashboard-only, accessible to humans not agents. Real cost: + Claude Code session can't surface attune-gui content + without screenshots or paste. +2. **Wrap every FastAPI route as an MCP tool** — too much + surface; many routes are frontend-internal. MCP should be + the agent-facing API, not the GUI's full API. +3. **Add MCP to attune-rag instead** (since rag is the + data-richest sibling) — different problem. attune-rag's + data IS its API; attune-gui's data is structured/spec- + centric and benefits more from being agent-readable. + +## Acceptance criteria + +- `attune_gui mcp-serve` entry point that starts a stdio MCP + server +- ~5 tools listed above implemented, each with a clear + schema and docstring +- Integration test exercising at least 2 tools end-to-end +- Compatible with the same Claude Code MCP configuration + pattern as attune-help / attune-author + +## Execution gate + +Not urgent. Don't start until: + +1. attune-gui's federated specs feature (PR #30) is stable +2. attune-ai's [#230 ops-specs-features](https://github.com/Smart-AI-Memory/attune-ai/pull/230) execution gate clears + (since the two specs touch related territory) +3. No active CI debt in attune-gui + +The two specs (attune-ai #230 and this one) complement each +other: #230 brings specs into attune ops dashboard for human +viewing; this spec exposes specs to MCP for agent querying. +Both serve the spec-driven workflow but for different +clients. + +--- + +(per-phase decisions appended as work happens) diff --git a/docs/specs/mcp-server-scope/tasks.md b/docs/specs/mcp-server-scope/tasks.md new file mode 100644 index 0000000..ad2f1fb --- /dev/null +++ b/docs/specs/mcp-server-scope/tasks.md @@ -0,0 +1,67 @@ +# Tasks — MCP server for attune-gui + +## Phase 1 — Scaffold + +- [ ] **1.1** Add `mcp>=0.9.0` to `[project.optional-dependencies].mcp` + in pyproject.toml (mirror attune-help / attune-author pattern) +- [ ] **1.2** Create `sidecar/attune_gui/mcp/__init__.py` and + `sidecar/attune_gui/mcp/server.py` +- [ ] **1.3** Add `attune-gui-mcp = "attune_gui.mcp.server:main"` + to `[project.scripts]` +- [ ] **1.4** Start server on stdio per the MCP server pattern + used by sibling packages + +## Phase 2 — Implement core tools + +For each: + +- [ ] **2.1** `gui_list_specs` — wrap existing + `routes/cowork_specs.py` GET handler +- [ ] **2.2** `gui_get_spec` — wrap existing per-spec read +- [ ] **2.3** `gui_get_spec_status` — extract `**Status**:` + line from a phase file +- [ ] **2.4** `gui_list_living_docs` — wrap existing + living-docs listing route +- [ ] **2.5** `gui_get_living_doc` — wrap existing + living-doc content read + +Each tool: +- Has a clear schema (input + output) +- Has a docstring that Claude can read to decide when to + invoke +- Handles path validation (consistent with existing route + protection) + +## Phase 3 — Optional write tool + +- [ ] **3.1** `gui_set_spec_status` — wrap the existing + PUT route. Same body shape: + `{"status": ""}`. Same validation. Honor + any read-only flag on the server. + +## Phase 4 — Integration test + +- [ ] **4.1** Test that starts the MCP server, queries + `gui_list_specs`, and asserts the result matches the + FastAPI route's response on the same data +- [ ] **4.2** Same for `gui_get_spec` against a known fixture + spec + +## Phase 5 — Docs + +- [ ] **5.1** README section: "MCP integration" — how to + configure Claude Code to use the server +- [ ] **5.2** Example `.mcp.json` snippet showing + `attune-gui-mcp` registered +- [ ] **5.3** Cross-link with attune-ai's + ops-specs-features spec (the two complement each other) + +## Out of scope + +- Authentication / API tokens — local stdio MCP doesn't need it +- Streaming responses — start with one-shot tool calls only +- Multi-root federation in MCP — Phase 1 lists local specs; + cross-root listing can be a follow-up +- Editing template content via MCP — covered by GUI editor +- Replacing the FastAPI surface — MCP is additive, not a + replacement