|
| 1 | +--- |
| 2 | +title: MCP Tool Plane Pilot |
| 3 | +plan_id: 20260626_mcp_tool_plane_pilot |
| 4 | +status: active |
| 5 | +level: standard |
| 6 | +created: 2026-06-26 |
| 7 | +updated: 2026-07-07 |
| 8 | +knowledge_sync: |
| 9 | + project: skip |
| 10 | + background: review |
| 11 | + design: review |
| 12 | + tasks: review |
| 13 | +archive_ready: false |
| 14 | +--- |
| 15 | + |
| 16 | +# MCP Tool Plane Pilot |
| 17 | + |
| 18 | +## Plan Snapshot |
| 19 | + |
| 20 | +- **Goal**: Add a narrow MCP tool plane for deterministic Sopify protocol reads/checks and one guarded low-level plan receipt write, without replacing prompt workflow, CLI, installer, or host adapters. |
| 21 | +- **Status**: Active. S1 read/check pilot and S2A `write_plan_receipt` are complete for Codex/Qoder observation; S2A go/no-go is `go`. |
| 22 | +- **Next**: Enter S3.1 as a Codex-only design step: produce the Codex MCP config matrix and registration boundary, then stop for review before implementation. |
| 23 | +- **Task**: Continue from `tasks.md` item 3.1; do not implement installer registration or enter finalize yet. |
| 24 | + |
| 25 | +## Context / Why |
| 26 | + |
| 27 | +Sopify is now Protocol-first and Convention-driven. Hosts read prompt/workflow rules, while deterministic protocol writes and receipts are handled by `sopify_writer` and local scripts. That keeps the system portable, but AI hosts still tend to invoke shell commands or hand-build file writes for protocol checks, state reads, and receipt writes. |
| 28 | + |
| 29 | +This plan tests whether a small MCP tool plane can reduce protocol misuse without expanding Sopify back into a runtime. The pilot is intentionally narrow: it exposes deterministic local capabilities as tools, while workflow judgment, checkpoint behavior, and user-facing decisions remain in host prompt and skill logic. |
| 30 | + |
| 31 | +This is a new plan because MCP sits at the boundary between CLI, prompt, hook, and protocol writer behavior. It needs its own pilot and go/no-go gates instead of being folded into a broad host-adapter rewrite. |
| 32 | + |
| 33 | +## Scope |
| 34 | + |
| 35 | +The current scope is: |
| 36 | + |
| 37 | +- Add `scripts/sopify_mcp_server.py` as a single-file stdio MCP server. |
| 38 | +- Expose S1 read/check tools: `sopify.get_active_plan`, `sopify.get_current_handoff`, `sopify.workspace_status_lite`, and `sopify.protocol_check`. |
| 39 | +- Add S2A `sopify.write_plan_receipt` only, guarded by active plan, matching plan id, existing `plan.md`, and no receipt overwrite. |
| 40 | +- Keep CLI, protocol checker, and `ProtocolStore` as the source of deterministic behavior. |
| 41 | +- Record manual observation signals in `tasks.md`. |
| 42 | + |
| 43 | +Out of scope for this plan stage: |
| 44 | + |
| 45 | +- Installer-driven MCP registration. |
| 46 | +- Host capability declaration changes. |
| 47 | +- `write_history_receipt`, `finalize_plan`, `set_active_plan`, or `set_current_handoff` MCP tools. |
| 48 | +- Rewriting analyze/design/develop workflow prompts as tools. |
| 49 | + |
| 50 | +## Approach |
| 51 | + |
| 52 | +Keep MCP as an AI tool plane, not as a workflow engine. |
| 53 | + |
| 54 | +The server stays in one file for the pilot and is structured into workspace resolution, pure business functions, and MCP binding. Read/check behavior delegates to existing `ProtocolStore` and `scripts.sopify_protocol_check.run_protocol_check`. The write tool delegates to `ProtocolStore.write_plan_receipt` after MCP-layer guards pass. |
| 55 | + |
| 56 | +S2A is intentionally smaller than the original S2 idea. It only exposes `write_plan_receipt` because finalize and history receipts need a clearer host-level decision boundary before they become safe tool operations. |
| 57 | + |
| 58 | +## Waves / Steps |
| 59 | + |
| 60 | +1. **S1 Build + Test**: Implement and validate read/check tools; observe Codex and Qoder behavior. |
| 61 | +2. **S2A Write Plan Receipt**: Implement one guarded receipt-writing tool and verify it through tests, stdio smoke, and manual host observation. |
| 62 | +3. **S3 Multi-host Registration**: Only after S2A proves useful and safe, design installer-assisted MCP config registration across supported hosts. |
| 63 | + |
| 64 | +Current execution is between S2A and S3. S1 is complete for Codex and Qoder. S2A implementation, unit tests, stdio smoke, and Qoder manual observation are complete. S3.1 is the next step and is limited to Codex registration design. |
| 65 | + |
| 66 | +## Key Decisions |
| 67 | + |
| 68 | +- MCP tools must expose deterministic capabilities only; reasoning-heavy workflow stays in prompt/skill layers. |
| 69 | +- S1 stays single-file and avoids a new `sopify_mcp/` package until the pilot proves value. |
| 70 | +- S2A exposes only `write_plan_receipt`, not finalization or history receipt tools. |
| 71 | +- `write_plan_receipt` must call `ProtocolStore.write_plan_receipt`; it must not hand-write JSON or Markdown. |
| 72 | +- Missing `state/active_plan.json`, mismatched plan id, missing active `plan.md`, or an existing receipt must fail closed with a structured error envelope. |
| 73 | +- S3 multi-host registration must start with a host-specific design step. Current next scope is Codex-only S3.1; other hosts remain matrix inputs, not implementation targets. |
| 74 | + |
| 75 | +## Constraints / Not-in-scope |
| 76 | + |
| 77 | +- Do not modify four host adapters in S1/S2A. |
| 78 | +- Do not change installer behavior before S3. |
| 79 | +- Do not add high-level workflow tools such as `approve_and_finalize` or `continue_and_finalize`. |
| 80 | +- Do not write or clear `.sopify/state/active_plan.json` from the MCP tool. |
| 81 | +- Do not treat Claude/Copilot compatibility observation as blocking S2A; record it as S3 input. |
| 82 | +- Do not enter finalize until receipt evidence and knowledge sync decisions are explicit. |
| 83 | + |
| 84 | +## Status / Progress |
| 85 | + |
| 86 | +Completed: |
| 87 | + |
| 88 | +- S1 read/check tool implementation and tests. |
| 89 | +- Codex and Qoder main observations for read/check behavior. |
| 90 | +- S2A scope reduction and guard design. |
| 91 | +- S2A `write_plan_receipt` implementation. |
| 92 | +- S2A unit coverage for success, missing active plan, non-active plan, duplicate receipt, missing `plan.md`, and invalid workspace error envelope. |
| 93 | +- S2A MCP stdio smoke for `write_plan_receipt`. |
| 94 | +- Qoder manual validation that the write tool does not encourage bypassing `required_host_action`, user instructions, or finalize intent branching. |
| 95 | + |
| 96 | +Pending: |
| 97 | + |
| 98 | +- Claude/Copilot compatibility observation as S3 input. |
| 99 | +- S3.1 Codex MCP config matrix and registration boundary. |
| 100 | +- S3 implementation, installer/doctor updates, and multi-host registration. |
| 101 | + |
| 102 | +## Next |
| 103 | + |
| 104 | +Start S3.1 with Codex only: |
| 105 | + |
| 106 | +- Map current Codex MCP config location and expected JSON/TOML shape. |
| 107 | +- Decide non-destructive registration behavior: opt-in, merge, backup, dry-run, and existing-server conflict handling. |
| 108 | +- Decide the dependency boundary for launching `scripts/sopify_mcp_server.py` from Codex. |
| 109 | +- Record the design in `design.md` / `tasks.md` and stop before code changes. |
0 commit comments