docs(specs): mcp-server-scope — focused MCP server for attune-gui (draft)

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)

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": "<valid-value>"}`. 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