Update docs for MCP completion

- Move MCP plan to done
- Update README: MCP is a feature, fix endpoint count (42), update
  architecture description
- Update ARCHITECTURE.md: add MCP to diagrams, package structure,
  dependency flow, and derivation table
- Update docs/mcp.md: add whoami, task_ref, notifications, revised tips
- Update NOTES.md: mark MCP as complete

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: bricef

ARCHITECTURE.md

@@ -4,7 +4,7 @@ This document describes the current architecture of TaskFlow for developers work
 
 ## Overview
 
-TaskFlow is a task tracker with kanban boards and workflow state machines. The server is the single source of truth; all clients (CLI, TUI, simulator, future MCP) are pure HTTP consumers that import no server internals.
+TaskFlow is a task tracker with kanban boards and workflow state machines. The server is the single source of truth; all clients (CLI, TUI, MCP, simulator) are pure HTTP consumers that import no server internals.
 
 ```
 ┌──────────────────────────────────────────────────────────┐
@@ -34,9 +34,9 @@ TaskFlow is a task tracker with kanban boards and workflow state machines. The s
 │  Accepts model.Resource and model.Operation directly     │
 │  Handles path substitution, query params, auth           │
 └──────────────────────────────────────────────────────────┘
-        ▲              ▲              ▲
-        │              │              │
-      CLI            TUI         Simulator
+        ▲           ▲           ▲           ▲
+        │           │           │           │
+      CLI         TUI         MCP      Simulator
 ```
 
 ## Define once, derive everywhere
@@ -53,6 +53,7 @@ Each entry has an explicit `Name` (e.g. `task_list`, `board_create`) that serves
 | HTTP server | Routes, handler mapping, status codes |
 | OpenAPI spec | Paths, methods, parameters, schemas, operationIds |
 | CLI | Command tree (`<resource>_<action>` → group + subcommand), flags |
+| MCP server | Resources (taskflow:// URIs), tools (input schemas), descriptions |
 | httpclient | Path substitution, HTTP method, query string building |
 
 Named references are exported as package-level variables (`model.ResTaskList`, `model.OpTaskCreate`, etc.) so consumers reference domain types directly without string lookups.
@@ -70,6 +71,7 @@ internal/
 ├── transport/          Maps domain actions to HTTP semantics (method, status code)
 ├── httpclient/         Domain-aware HTTP client for all consumers
 ├── http/               HTTP server (routes, middleware, OpenAPI generation)
+├── mcp/                MCP server (tools + resources derived from model, notifications)
 ├── cli/                CLI (commands derived from model)
 ├── eventbus/           In-process pub/sub with ring-buffered subscriptions
 ├── tui/                Interactive terminal UI (Bubble Tea)
@@ -79,6 +81,7 @@ cmd/
 ├── taskflow-server/    Server binary
 ├── taskflow/           CLI binary
 ├── taskflow-tui/       TUI binary
+├── taskflow-mcp/       MCP server binary (stdio transport)
 ├── taskflow-seed/      Test data generator
 └── taskflow-sim/       Activity simulator
 ```
@@ -100,6 +103,7 @@ sqlite         — depends on model, repo (storage implementation)
 transport      — depends on model (HTTP method/status mapping)
 httpclient     — depends on model, transport, eventbus
 http           — depends on model, transport, service, taskflow, eventbus
+mcp            — depends on model, httpclient, eventbus
 cli            — depends on model, httpclient
 tui            — depends on model, httpclient, eventbus
 ```

NOTES.md

@@ -73,7 +73,7 @@ These features were identified during MCP planning and should be integrated into
 
 Great question. Here's what I'd want as an AI agent using TaskFlow:
 
-- [ ] MCP server interface. The PRD mentions it but it's not built yet. For me, an MCP tool interface would be the most natural way to interact — I could create tasks, transition them, and check board state without constructing HTTP requests. The operation definitions in model.Operations() could derive MCP tool definitions the same way they derive HTTP routes and CLI commands.
+- [x] MCP server interface. Tools and resources auto-derived from model.Operations() and model.Resources(). Notification piggyback delivers change awareness on tool responses. Task ref shorthand, whoami tool, and rich descriptions for agent guidance.
 
 - [x] Structured error responses with actionable context. The current error format is good ({"error": "invalid_transition", "message": "..."}) but when a transition fails, I'd love the response to include the available transitions so I can self-correct without a second round-trip:
 

README.md

@@ -39,18 +39,17 @@ taskflow-tui
 ## Features
 
 - HTTP API with auth (SHA-256 keys), RBAC, idempotency keys, and batch operations
-- 41 domain endpoints (18 Resources + 23 Operations) auto-derived from the model
+- 42 domain endpoints (19 Resources + 23 Operations) auto-derived from the model
 - OpenAPI 3.1 spec auto-generated at startup
 - CLI with commands derived from the same model
 - Interactive TUI with kanban, list, workflow graph, and live event stream — see **[TUI Reference](docs/tui.md)**
+- MCP server for AI agent integration (Claude Code, Aider, Cursor) with notification piggyback — see **[MCP Server](docs/mcp.md)**
 - Real-time event streaming (SSE) with before/after task snapshots
 - Webhook dispatch with HMAC-SHA256 signatures, retry, and delivery logging
 - HTML dashboard at `/dashboard`
 - Docker deployment with seed admin bootstrap
 
-- MCP server for AI agent integration (Claude Code, Aider, Cursor) — see **[MCP Server](docs/mcp.md)**
-
-See [docs/](docs/) for API, CLI, and TUI reference.
+See [docs/](docs/) for API, CLI, TUI, and MCP reference.
 
 ## Roles
 
@@ -111,7 +110,7 @@ Tasks are moved between states by name (e.g. `--transition start`), not by targe
 
 ## Architecture
 
-Operations are defined once in `model.Resources()` and `model.Operations()` and derived into HTTP routes, CLI commands, OpenAPI specs, and the shared `httpclient`. All clients (CLI, TUI, simulator) are pure HTTP consumers — they import no server internals.
+Operations are defined once in `model.Resources()` and `model.Operations()` and derived into HTTP routes, CLI commands, OpenAPI specs, MCP tools/resources, and the shared `httpclient`. All clients (CLI, TUI, MCP, simulator) are pure HTTP consumers — they import no server internals.
 
 See **[ARCHITECTURE.md](ARCHITECTURE.md)** for the full architectural reference: dependency flow, package responsibilities, event system, query param derivation, and design rationale.
 

docs/mcp.md

@@ -127,24 +127,54 @@ Tools are mutations that change state. Path parameters and body fields are passe
 | `webhook_update` | Update a webhook (admin) | `id`, fields to change |
 | `webhook_delete` | Delete a webhook (admin) | `id` |
 
-## Workflow Tips for Agents
+### Identity
 
-1. **Check available transitions** before transitioning: read the `workflow_get` resource for the board, then match the task's current state to available transitions.
+| Tool | Description |
+|------|-------------|
+| `whoami` | Returns your actor identity (name, role, type) |
 
-2. **Use `@me` for self-assignment**: when creating or updating tasks, use `@me` as the assignee value.
+## Convenience Features
 
-3. **Transition by name, not state**: pass the transition name (e.g. `start`, `submit`, `approve`), not the target state.
+### Task references
 
-4. **Board detail for full context**: use `board_detail` to get a complete snapshot of a board including all tasks with their comments, dependencies, and audit.
+Tools that take `slug` + `num` also accept a `task_ref` shorthand like `"platform/3"`. This is parsed in the MCP layer — the domain model is unchanged.
 
-5. **Task search across boards**: use `task_search` to find tasks across all boards by keyword.
+### Notifications
+
+The MCP server subscribes to the global event stream at startup. Events from other actors are buffered and piggybacked onto tool responses as a text block:
+
+```
+--- 2 notification(s) from other actors ---
+  [2026-04-01T10:15:00Z] alice moved platform/3 from backlog to in_progress
+  [2026-04-01T10:16:30Z] brice commented on platform/7
+```
+
+This gives the agent awareness of changes without polling. Notifications are cleared after delivery. If no events have arrived, tool responses are unchanged.
+
+## Tips for Agents
+
+1. **Use `task_detail`** instead of `task_get` when you need full context — it includes comments, dependencies, attachments, and audit in one request.
+
+2. **Use `whoami`** to discover your identity. This tells you your actor name, role, and type.
+
+3. **Use `@me`** as the assignee value when creating or updating tasks to assign to yourself.
+
+4. **Transition by name, not state**: pass the transition name (e.g. `start`, `submit`, `approve`), not the target state. On failure, the error includes available transitions.
+
+5. **Use `task_ref`** shorthand (e.g. `"platform/3"`) instead of separate `slug` and `num` for conciseness.
+
+6. **Use `task_search`** to find tasks across all boards by keyword, assignee, state, or priority.
 
 ## Architecture
 
 The MCP server is a thin adapter over `internal/httpclient`. Resources and tools are auto-derived from `model.Resources()` and `model.Operations()` — the same definitions that drive the HTTP API, CLI, and OpenAPI spec. No manual tool registration is needed.
 
 ```
 AI Agent ←→ taskflow-mcp (stdio) ←→ httpclient ←→ TaskFlow Server
+                                        │
+                                   Subscribe (events)
+                                        │
+                                   Notification buffer
 ```
 
-Each agent instance runs as a separate process with its own API key. The agent's identity comes from the API key — all actions are attributed to the corresponding actor in the audit trail.
+Each agent instance runs as a separate process with its own API key. The agent's identity is resolved at startup via `/me` and used to filter out self-events from the notification stream.