spec-coding-mcp

<p align="center"> <img src="./docs/public/favicon.svg" width="96" height="96" alt="Spec Coding MCP logo" /> </p> <h1 align="center">Spec Coding MCP</h1> <p align="center"> <strong>A local MCP workflow for spec coding tools used with AI</strong> </p> <p align="center"> Review specs first, execute tasks, and then write implementation facts back to the project. </p> <p align="center"> <a href="https://spec.xyun.dev/">Documentation and Website</a> · <a href="https://spec.xyun.dev/guide/getting-started">Quick Start</a> · <a href="https://spec.xyun.dev/guide/mcp-tools">MCP Tools</a> · <a href="https://www.npmjs.com/package/@dev_xiaoyun/spec-coding-mcp">npm Package</a> </p> <p align="center"> <a href="https://www.npmjs.com/package/@dev_xiaoyun/spec-coding-mcp"><img alt="npm version" src="https://img.shields.io/npm/v/%40dev_xiaoyun%2Fspec-coding-mcp?style=flat-square&color=0f766e" /></a> <a href="https://github.com/xy200303/spec-coding-mcp/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/xy200303/spec-coding-mcp/ci.yml?branch=main&style=flat-square&label=CI" /></a> <a href="https://github.com/xy200303/spec-coding-mcp/actions/workflows/deploy-docs.yml"><img alt="Docs" src="https://img.shields.io/github/actions/workflow/status/xy200303/spec-coding-mcp/deploy-docs.yml?branch=main&style=flat-square&label=docs" /></a> <img alt="Node 22 plus" src="https://img.shields.io/badge/node-22%2B-3c873a?style=flat-square" /> <img alt="MCP server" src="https://img.shields.io/badge/MCP-server-334155?style=flat-square" /> <a href="./LICENSE"><img alt="License MIT" src="https://img.shields.io/badge/license-MIT-b45309?style=flat-square" /></a> </p> <p align="center"> <code>npm install -g @dev_xiaoyun/spec-coding-mcp</code> <br /> <code>specc init</code> </p> --- Spec Coding MCP is a local MCP service for **spec coding**. The core idea is simple: write or review a small specification first, then let AI modify code and tests according to the specification. It no longer attempts to permanently document the entire system or maintain complex CRDT states. ## Goals - Infer `specs/` directory from old projects without specs, making it easier for users to review the current system. - Users develop by modifying or adding specs before development. - Users can split tasks using TODO lists, and the model executes in the order of unchecked items. - The tool injects global engineering quality constraints into the model context, enforcing code style, project structure, and UI intuition. - The tool enforces adherence to KISS, YAGNI, Clean Code, Clean Architecture, DDD, Fail Fast, SOLID, SoC, and Boy Scout Rule. - The tool prevents layer mixing, excessive abstraction, and unnecessary complexity, organizing code into a structure suitable for large projects and human readability. - The tool enforces business uncertainty confirmation: when encountering amounts, rates, settlements, accounts, refunds, discounts, taxes, state machine transitions, concurrency, idempotence, retries, rollbacks, or unclear rules or role behavior inconsistencies, it must pause and confirm with the user. - The tool prohibits relying on intuition to guess business rules; when unclear, it must clarify where it is unclear and provide 2-3 possible explanations, waiting for user confirmation before proceeding. - Codex reads active specs and implements code and tests according to the latest specifications. - After verification, specs are archived to `done/`. ## Directory Structure ```text specs/ README.md review/ source-inventory.md index.md *.md active/ *.md todo/ *.md done/ *.md templates/ feature.md bugfix.md removal.md ``` - `review/`: Current code facts derived from source code, typically in the state of `source-derived/current-code`, for user review. - `active/`: Specs being implemented or about to be implemented. - `todo/`: Lightweight executable TODO lists, suitable for temporary tasks, splitting steps, or supplementing implementation sequences. - `done/`: Implemented and verified specs. - `templates/`: Templates for new specs. ## MCP Tools | Tool | Function | |---|---| | `spec_generate_agents` | Generate or update `AGENTS.md` in the project root directory | | `spec_init` | Initialize `specs/` directory and templates | | `spec_generate_from_source` | Infer review specs from existing source code | | `spec_create` | Create active specs based on user descriptions | | `spec_todo` | Create executable TODO lists based on user descriptions | | `spec_list` | List review, active, todo, and done specs | | `spec_context` | Return specs, TODOs, engineering constraints, and optional search clues; does not scan source code by default | | `spec_checkpoint` | Record completed TODOs, changed files, verification results, actual behavior, risks, and blockers after implementation | | `spec_review_result` | Structurally record completed TODOs, blockers, verification commands, associated files, and actual behavior | | `spec_done` | Move verified specs to done and retain final actual behavior records | ## Recommended Workflow ### Generate Project Manual 1. Before any code or document changes, call `spec_context`. 2. Call `spec_generate_agents`. 3. Check `AGENTS.md` in the project root directory. 4. Start development with `AGENTS.md`, `specs/`, and TODO. ### First Access for Old Systems 1. Call `spec_generate_from_source`. 2. User reads `specs/review/source-inventory.md` and `specs/review/*.md`. 3. User modifies inferred content to actual business specs. 4. When development is needed, move the target spec to `specs/active/` or let `spec_context` read the specified file. 5. Codex modifies code and tests according to specs. 6. After verification, call `spec_done`. ### New Demand Development 1. Before any code or document changes, call `spec_context`. 2. Call `spec_create` to generate active specs based on user descriptions. 3. User reviews and modifies `specs/active/*.md`. 4. If tasks need to be split, call `spec_todo` or write `## TODO` in specs. 5. Call `spec_context` again to confirm current specs, TODOs, and engineering constraints. 6. Codex implements code and tests in the order of specs and unchecked TODOs. 7. After phased completion, call `spec_checkpoint` to record completion. 8. After verification, call `spec_done`. `spec_context` uses `contextMode: "workflow"` by default, outputting only task flow, specs/TODOs, and constraints. When source code clues are needed, use `contextMode: "hints"` explicitly; use `contextMode: "full"` for complete source code scanning clues. These clues are just search entries, not fact sources; models must read relevant files to confirm before modification. ### Write Operation Hard Constraints `spec_create`, `spec_todo`, `spec_generate_agents`, `spec_checkpoint`, `spec_review_result`, and `spec_done` all require calling `spec_context` first. If `spec_context` is skipped, these write operations will fail directly and prompt to read model context first. ### TODO Driven Tasks TODOs can be placed in `specs/todo/*.md` or written in active specs as `## TODO`: ```md ## TODO - [ ] Locate user detail interface and test. - [ ] Add disabled state field. - [ ] Update verification command and record result. ``` `spec_context` extracts all unchecked TODOs, requiring models to execute in order; after completion, mark corresponding tasks as `[x]`, or retain unchecked tasks with explanations for blockers. ### Checkpoint Closed Loop `spec_checkpoint` is used to write implementation facts back to specs or TODO files: - Completion summary - Completed and automatically checked TODOs - Changed files - Verification commands and results - Actual behavior records: business branch conditions, default parameter behavior, boundary processing results - Structured `behaviorRecords`: scenario, condition, result, default behavior, boundary processing, verification, and associated files - Known risks `spec_done` renders structured behavior records as `## Final Behavior Contract`. If no `behaviorRecords` are provided, the tool prompts to supplement branch conditions, default parameter behavior, boundary processing, and verification results in next steps. - Blockers It is suitable for phased development in complex projects, allowing the next AI or human to see what has been completed, verified, and what remains. `spec_review_result` is more inclined to "phase result reporting," recording completed and unfinished TODOs, verification results, changed files, risks, and blockers, suitable for complex project handover. ### Global Engineering Quality Constraints The single source of truth for engineering quality constraints is in `src/templates/constraints.ts`, and Markdown rendering is unified by `src/templates/markdown.ts`. `spec_context`, `AGENTS.md`, spec templates, and TODO templates should all output the same set of rules through this template module, avoiding inconsistent long lists maintained separately by README, AGENTS, and context. The current prompt protocol is divided into three layers: - Hard Rules: Fail Fast, risk confirmation, file top comments, prohibition of layer mixing, prohibition of meaningless abstraction, performance and resource bottom line. - Recommended Practices: KISS, YAGNI, Clean Code, Human Readable, Clean Architecture, DDD, SOLID, SoC, test-first, mature library first, local small step refactoring, AI-generated and human-maintainable. - Business Confirmation Rules: amounts, rates, settlements, accounts, refunds, discounts, taxes, state machine transitions, concurrency, idempotence, retries, rollbacks, or unclear rules or role behavior inconsistencies must be confirmed with the user, not allowed to guess based on intuition. - Current Task Protocol: how the current task must read `spec_context`, execute TODOs, record checkpoints, and archive done. The prompt protocol is jointly generated by `src/templates/constraints.ts`, `src/templates/prompt-protocol.ts`, and `src/templates/markdown.ts`. ## Installation ```bash npm install -g @dev_xiaoyun/spec-coding-mcp specc init ``` `specc init` scans the local Codex, Claude Code, OpenCode, Cursor, Continue, and Windsurf, and lets you choose to register MCP. Manual configuration of Codex is recommended using Node direct connection entry: ```toml [mcp_servers.spec-coding] command = "C:\\nvm4w\\nodejs\\node.exe" args = ["C:\\nvm4w\\nodejs\\node_modules\\@dev_xiaoyun\\spec-coding-mcp\\dist\\index.js", "serve"] ``` Paths need to be adjusted according to your Node global installation directory. ## Local Development ```bash npm install npm test ``` Test entry: - `npm run build`: TypeScript build. - `npm run unit`: fine-grained unit tests, covering TODO parsing, checkpoint writeback, MCP guard, and registration compatible contracts. - `npm run smoke`: end-to-end smoke test, covering spec, AGENTS, CLI, and registration main process. - `npm run release:check`: pre-release contract check, covering version, CLI/MCP startup parameters, and key document descriptions. - `npm run verify`: run build, unit, smoke, release:check in sequence. - `npm test`: equivalent to `npm run verify`. Start MCP server: ```bash specc serve ``` or: ```bash node dist/index.js serve ``` ## Release It is recommended to use GitHub Actions' `Prepare npm release` workflow to release new versions: 1. Open `Actions` -> `Prepare npm release` -> `Run workflow`. 2. Enter the target version number, e.g., `0.2.4`. 3. With `dry_run=false`, CI automatically synchronizes `package.json` and `package-lock.json`, runs verification, submits version changes, and creates a `vX.Y.Z` tag. 4. The tag triggers the `Publish npm` workflow to complete npm release. The npm release workflow uses GitHub Actions secret `NPM_TOKEN`. Before release, configure the `NPM_TOKEN` with release permissions in the repository secrets. If a tag has been created by a failed release but npm has not been released, select `replace_existing_tag` in `Prepare npm release` to let CI delete and rebuild the same version tag, without needing to upgrade the version number for failed attempts. You can also run locally before release: ```bash npm run verify ``` The `Publish npm` workflow checks if `vX.Y.Z` matches the `package.json` version, runs `npm run verify`, and then executes npm publish. When triggered manually, `dry_run=false` will publish for real. ## Design Boundaries Spec Coding MCP does not do these things: - Does not attempt to permanently document the entire system. - Does not track strong consistent states for each functional point and code location. - Does not use user-written IDs or change logs. - Does not disguise unfinished development states as completed.