docs: MCP integration section in README (mcp-server-scope Phase 5) (#54)

Closes tasks 5.1–5.3 of docs/specs/mcp-server-scope/.

Adds a "## MCP integration" section to the README between
Architecture and Security:

  - One-paragraph framing (read-mostly tool surface, same data the
    dashboard renders, mcp is a core dep so no extra install)
  - Five-tool table with one-line descriptions and the JSON envelope
    contract
  - Wiring snippet — copy-paste .mcp.json for Claude Code
  - Cross-link to attune-ai's ops-specs-features spec as the
    human-side complement (per task 5.3)

Marks 5.1–5.3 done in tasks.md. CHANGELOG entry under Unreleased.

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: silversurfer562

CHANGELOG.md

@@ -7,6 +7,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Added
 
+- **MCP server — Phase 5 docs.** New "## MCP integration" section
+  in the README covers install, the five tools at a glance, the
+  `.mcp.json` snippet for wiring `attune-gui-mcp` into Claude Code,
+  and a cross-link to attune-ai's complementary `ops-specs-features`
+  spec. Completes the [mcp-server-scope](docs/specs/mcp-server-scope/)
+  spec's Phase 5.
 - **MCP server — Phase 2 tools.** Five read-mostly tools wired
   on top of the Phase 1 scaffold, each returning a
   JSON-serializable envelope with `{"success": bool, ...}`:

README.md

@@ -215,6 +215,55 @@ needs editor-grade interactivity — rich text editing, real-time conflict
 resolution, multi-file refactor previews. Inline actions, polling, and
 form-driven dashboards stay server-rendered.
 
+## MCP integration
+
+attune-gui ships an MCP server (`attune-gui-mcp`) that exposes a small,
+read-mostly tool surface for Claude Code and other MCP clients. Same
+data the dashboard renders — specs and living docs — but addressable
+programmatically. `mcp>=0.9.0` is a core dependency, so `pip install
+attune-gui` is enough to get both the dashboard and the MCP server.
+
+### Tools
+
+| Tool | What it returns |
+|---|---|
+| `gui_list_specs` | All feature specs across configured roots (federated). Each tagged with project, root, phase, status. |
+| `gui_get_spec` | All phase-file contents (`requirements.md` / `design.md` / `tasks.md`) for one spec. |
+| `gui_get_spec_status` | The `**Status**:` value for one phase. Default: most-advanced phase. |
+| `gui_list_living_docs` | Doc registry — generated docs the workspace tracks, with status (current/stale/missing) and persona. |
+| `gui_get_living_doc` | One living-doc's file content. Path-traversal guarded. |
+
+Every tool returns a JSON envelope shaped `{"success": bool, ...}`.
+See [`docs/specs/mcp-server-scope/`](docs/specs/mcp-server-scope/) for
+the scope decisions and tool schemas.
+
+### Wiring into Claude Code
+
+Add to your project's `.mcp.json` (or `~/.claude/mcp.json` for global):
+
+```json
+{
+  "mcpServers": {
+    "attune-gui": {
+      "command": "attune-gui-mcp"
+    }
+  }
+}
+```
+
+The server boots on stdio and logs to
+`<tmpdir>/attune-gui/attune-gui-mcp.log` so the MCP transport stays
+clean. Restart Claude Code after editing the config; the five tools
+appear under the `attune-gui` server in `/mcp`.
+
+### Related work
+
+attune-ai's [ops-specs-features](https://github.com/Smart-AI-Memory/attune-ai/blob/main/docs/specs/ops-specs-features/decisions.md)
+spec is the complement to this one: that work brings attune-gui's
+spec views into the attune-ai ops dashboard for humans; this MCP
+server exposes the same views to agents. Both serve the spec-driven
+workflow, just for different clients.
+
 ## Security notes
 
 This is a **single-user, local-only** app. Not designed for multi-user

docs/specs/mcp-server-scope/tasks.md

@@ -52,11 +52,11 @@ Each tool:
 
 ## Phase 5 — Docs
 
-- [ ] **5.1** README section: "MCP integration" — how to
+- [x] **5.1** README section: "MCP integration" — how to
       configure Claude Code to use the server
-- [ ] **5.2** Example `.mcp.json` snippet showing
+- [x] **5.2** Example `.mcp.json` snippet showing
       `attune-gui-mcp` registered
-- [ ] **5.3** Cross-link with attune-ai's
+- [x] **5.3** Cross-link with attune-ai's
       ops-specs-features spec (the two complement each other)
 
 ## Out of scope