한국어 | 中文 | English | 日本語

Spec-Tools-MCP

A centralized MCP server that provides spec-driven AI agent skills, rules, and prompts across projects.

AI agents tend to lose context as conversations grow long. Spec-Tools-MCP solves this by keeping all decisions, requirements, and progress in markdown files — not in chat history — so any session can resume exactly where it left off.

Prerequisites

Node.js v18 or later (LTS recommended). The MCP server is launched via npx, and the codebase-wiki context hooks installed by spec-init run with node, so Node.js must be available on your PATH. Verify with node -v.

Background

Most spec-based development MCPs store their working files (plan.md, todo.md, etc.) at a fixed location in the project root. This works fine for a single developer working on one feature at a time, but breaks down quickly when:

• Multiple developers are working on different features in the same repository simultaneously
• Multiple sub-projects are in flight at once and you need to switch between them or hand off work to a teammate

Because the spec files live at the root level, everything collides — one developer's todo.md overwrites another's, and it becomes impossible to tell which plan belongs to which work stream.

Spec-Tools-MCP was built specifically for this scenario. Each feature gets its own isolated folder under ai-spec/projects/<feature>/, so multiple developers or sub-projects can progress independently in the same repository without interfering with each other. Work can be handed off or resumed by any team member simply by pointing to the right feature folder.

Usage

Call skills directly from any project via MCP — no file copying required.

1. IDE Setup

Claude Code

Install the MCP server and Skills together as a plugin:

/plugin marketplace add blue03183/spec-tools-mcp
/plugin install spec-tools-mcp@spec-tools-mcp-marketplace

Restart Claude Code to activate. Verify with /mcp or /skills.

VS Code / GitHub Copilot

To call skills directly in Copilot chat, use the plugin install method. Installing only the MCP server adds a prefix (blu_) to all tool names and prevents direct skill invocation from the chat panel.

Install as a plugin (MCP server + Skills bundled):

1. Open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P)
2. Run Chat: Install Plugin From Source
3. Paste: https://github.com/blue03183/spec-tools-mcp

npx spec-tools-mcp init

{
  "servers": {
    "spec-tools-mcp": {
      "type": "stdio",
      "command": "/Users/{username}/.nvm/versions/node/v24.11.0/bin/npx",
      "args": ["-y", "spec-tools-mcp@latest"],
      "env": {
        "PATH": "/Users/{username}/.nvm/versions/node/v24.11.0/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

Codex CLI

Install via CLI: (If Codex CLI is not installed, install it first: npm install -g @openai/codex)

codex mcp add spec-tools-mcp -- npx -y spec-tools-mcp@latest

Or configure manually (.codex/config.toml):

[mcp_servers.spec-tools-mcp]
command = "npx"
args = ["-y", "spec-tools-mcp@latest"]

If project settings are not applied, add to global config with vi ~/.codex/config.toml.

Kiro

Auto-configure from your project root (requires a .kiro folder to already exist):

npx spec-tools-mcp init

This creates .kiro/settings/mcp.json with the server configuration. If the .kiro folder does not exist yet, create it first (open the project in Kiro), then run init.

Or configure manually by creating .kiro/settings/mcp.json:

{
  "mcpServers": {
    "spec-tools-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "spec-tools-mcp"],
      "env": {}
    }
  }
}

After saving, restart Kiro or reload the MCP server from the Kiro feature panel (MCP Servers → spec-tools-mcp → Start Server). Verify the connection by asking: What MCP tools are available?

Cursor / Other IDEs

Auto-configure from your project root:

npx spec-tools-mcp init

Detects Claude Code, Cursor, VS Code, and Kiro automatically and writes the correct config file for each.

Or add manually to your MCP config file:

{
  "servers": {
    "spec-tools-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "spec-tools-mcp@latest"]
    }
  }
}

npm install spec-tools-mcp --save-dev

{
  "servers": {
    "spec-tools-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["./node_modules/spec-tools-mcp/mcp-server/index.js"]
    }
  }
}

2. Custom spec directory (optional)

By default, spec files are stored under ai-spec/ at the project root. To use a different path, set the SPEC_ROOT_DIR environment variable:

{
  "mcpServers": {
    "spec-tools-mcp": {
      "command": "npx",
      "args": ["-y", "spec-tools-mcp@latest"],
      "env": { "SPEC_ROOT_DIR": "my-specs" }
    }
  }
}

3. Restart & Verify

After adding the MCP configuration, restart your AI agent (reload the IDE window or restart the chat session) so the new server is picked up.

Verify the connection by asking the AI:

What MCP tools are available?

Or call get_rules directly:

get_rules

If the server is connected, the AI will list the eight tools (spec_init, spec_todo, spec_work, get_rules, spec_status, spec_handoff, spec_archive, spec_search) or return the development rules document.

4. How to Use Skills

Once the MCP server is connected, request skills in natural language from the AI chat.

VS Code (GitHub Copilot — Agent mode)

Switch Copilot Chat to Agent mode, then make requests naturally, or use # commands to call skills directly:

#spec_init dashboard
#spec_todo dashboard
#spec_work T-01

Claude Code (CLI)

Make requests directly in the Claude Code chat:

Initialize dashboard with spec_init
Analyze requirements with spec_todo
Work on T-01 with spec_work

5. Available Tools

Tool roles and expected effects

spec_init
Call when starting a new feature. Creates an isolated workspace under ai-spec/projects/<feature>/ so multiple features or developers can work in the same repository without file conflicts. Also creates or incrementally updates the project-wide codebase wiki at ai-spec/_codebase/ — on first run it analyzes the full codebase; on subsequent runs it re-analyzes only the files that changed since the last sync.

spec_todo
Run after planning documents are ready. Analyzes files in docs/, writes requirement.md, and generates a simple task list in todo.md — acting as a human review checkpoint before any implementation begins.

spec_work
Use when starting implementation or resuming a prior session. Enforces a plan → approval → code gate: writes plan.md first, blocks implementation until a human approves. When implementation starts, the agent immediately marks the todo item as [ ] IN PROGRESS — so even if the session is cut off mid-task (e.g. token limit), the next session can identify and resume the in-progress task. Each step is recorded in update.md for fine-grained resumption. Code locations are read from _codebase/ rather than re-scanning the workspace, and any new findings are written back to _codebase/ immediately.

get_rules
Call when the AI needs to recall the full development protocol. Returns the entire spec-development-rules.md to ensure the AI follows the correct spec-driven workflow.

spec_status
Use when multiple features are in flight and you need a project-wide view. Shows todo completion rates with a clear distinction between in-progress (IN PROGRESS) and not-yet-started (TODO) items, plus any plans awaiting approval — so nothing falls through the cracks.

spec_handoff
Use when handing off work to a teammate or pausing a feature for an extended period. Compiles goals, todo status, and key code locations into a single document so the next session or developer can resume without re-scanning the codebase.

spec_archive
Call once a feature is fully complete. Moves the feature folder to ai-spec/archive/, keeping projects/ clean and limited to active work. Blocked if any todo item is still incomplete or if an archive folder with the same name already exists.

spec_search
Use when you need to look up file locations or symbols cached in _codebase/ without opening the files manually. Pass a query keyword to return only the matching sections — this is the token-efficient way to use it. Calling it without a query returns only index.md plus a heading table of contents for the other wiki files (not the full dump), so you can see what exists and then query for details.

6. Workflow

1. Initialize the project with spec_init

   • Creates an ai-spec/projects/{project-name}/ folder with requirement.md template and optional docs/ folder
   • Creates or updates the shared codebase wiki at ai-spec/_codebase/ (full analysis on first run; incremental update on subsequent runs based on git changes)

2. Upload planning documents (optional)

   • Copy PDF, images, or other planning files into ai-spec/projects/{project-name}/docs/

3. Run spec_todo to analyze docs and generate spec files

   • Reads docs and writes requirement.md — AI asks you to review before continuing
   • If UI changes are included, AI generates a preview.html mockup and opens it in a browser for review before generating tasks
   • Generates a simple task list todo.md (T-01, T-02, …)
   • Tasks needing end-to-end verification (screen flows, API integration) also get a paired E2E item (e.g. T-01E) that runs only after its implementation task (T-01) is complete
   • If requirement.md already exists, analyzed content is appended below existing requirements

4. Run spec_work to implement each task

   • AI writes plan.md for the selected task and asks for your approval
   • You review the plan file directly — to request changes, write your feedback in the User Feedback section of plan.md, then reply 수정 (revise)
   • Reply 승인 (approve) or 진행해 (proceed), or set the Approval Status in plan.md to [승인] directly, to start implementation
   • The server enforces the approval gate: unless plan.md shows Approval Status = [승인], spec_work returns a block notice instead of the implementation procedure, so no code is written until you approve. The gate also applies when you omit the todo argument (the server resolves the active todo), and it fails safe — if the Approval Status line is missing or malformed, implementation is blocked rather than allowed
   • As the very first action when implementation starts, the agent marks the todo item [ ] IN PROGRESS — if the session is interrupted (e.g. token limit), the next session can detect and resume the in-progress task
   • Progress is recorded in update.md as each step completes

5. Resume anytime by starting a new session and calling spec_work again

   • AI checks todo.md for any IN PROGRESS item first and jumps directly to that task, then resumes from the first incomplete item in update.md
   • _codebase/ provides accumulated code location and pattern knowledge so the AI doesn't re-scan the codebase from scratch on each session or feature

6. Repeat steps 3–4 for each subsequent task

7. When handing off work to another developer, request a handoff document

   • spec_handoff generates a concise summary of goals, todo status, current progress, and key code locations

8. When a feature is complete, archive it to keep projects/ clean

   • spec_archive moves the folder to ai-spec/archive/ — blocked if any todo is still incomplete or an archive folder with the same name already exists

7. Generated Folder Structure

ai-spec
├─ _codebase/                      # project-wide codebase wiki (shared across all features)
│   ├─ index.md                    # full directory map, tech stack, module-path mapping table
│   ├─ last-synced.md              # last analysis timestamp (git hash + trigger)
│   ├─ modules/
│   │   └─ <domain>.md             # per-domain: key files, core APIs, patterns, dependencies
│   ├─ conventions.md              # shared conventions, naming rules, architecture patterns
│   └─ gotchas.md                  # implicit constraints & gotchas (human-authored / code-verified)
├─ templates/                      # (optional) custom templates
│   ├─ requirement.md              # custom requirement template
│   └─ todo.md                     # custom todo template
└─ projects/
    └─ <feature>                   # per-feature project folder
        ├─ requirement.md          # requirements document (Single Source of Truth)
        ├─ preview.html            # UI mockup (generated when UI changes are included)
        ├─ todo.md                 # task list generated by AI
        ├─ docs/                   # original planning files (PDF, images, etc.)
        └─ <T-number>-<summary>/   # per-task folder
            ├─ plan.md             # design intent, implementation approach, approval status
            └─ update.md           # implementation progress log + review checklist

_codebase/ role: The AI records file locations, schemas, and patterns it discovers here — shared across all features. Unlike a per-feature cache, _codebase/ accumulates knowledge over time: each new feature and each completed task adds to it. The longer a project runs, the less redundant exploration is needed.

Custom templates: Place ai-spec/templates/requirement.md or ai-spec/templates/todo.md to use your own template format instead of the built-in defaults.

Format contract: The spec_status, spec_work, spec_handoff, and spec_archive tools parse these files, so custom templates must preserve the parsed structure:

• todo.md — each item starts with a ## [T-NN] title heading and includes a 상태 (status) line with [ ] TODO, [ ] IN PROGRESS, or [x]
• plan.md — an Approval Status line followed by [대기] (pending) or [승인] (approved); if missing or malformed, spec_work blocks implementation to fail safe
• requirement.md — keep the ## 기능 목표 (goal) heading so spec_handoff can extract the feature goal

See get_rules → "포맷 계약 (도구 파싱 의존)" for the full contract.

8. Notes

• ai-spec/_codebase/ serves as the persistent codebase knowledge base. Once populated by spec_init, subsequent features and tasks reference it instead of re-scanning the workspace — significantly reducing token usage as the project grows.
• When context grows too long, AI accuracy can degrade. It is recommended to start a new session for each TODO item. Pass the task number directly (e.g. spec_work T-02) to jump straight to that item.
• The _codebase/ incremental sync uses git (git log <last-hash>..HEAD) to re-analyze only changed files. In a non-git project (or one with no commits) the git comparison is skipped — spec_init falls back to judging affected modules directly or re-analyzing fully, and last-synced.md records the git hash as N/A.
• Token efficiency: start a new session per TODO item (long context degrades accuracy and inflates cost), call spec_search with a query rather than dumping the whole wiki, and keep _codebase/ entries concise and table-centric so search and discovery stay cheap as the project grows.
• Reusing skill context: just like get_rules is fetched once per session, a skill already in context is not re-fetched. spec_work is the exception because it must be re-called to check the approval gate — on those re-calls pass skill_loaded=true so the server returns only the gate decision and omits the skill body. The bundled skills instruct the agent to do this automatically.

Updating

When a new version is released, update according to how you installed it.

Claude Code

Re-run the install commands to replace the current version with the latest.

/plugin marketplace add blue03183/spec-tools-mcp
/plugin install spec-tools-mcp@spec-tools-mcp-marketplace

VS Code / GitHub Copilot (plugin)

Follow the same steps as the initial installation. The existing plugin will be replaced with the latest version.

1. Open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P)
2. Run Chat: Install Plugin From Source
3. Paste the same URL: https://github.com/blue03183/spec-tools-mcp

npx-based setups (Codex CLI, Cursor, other IDEs)

Configurations using npx -y automatically fetch the latest version each time the server starts. No manual action needed.

If an older cached version persists, refresh it with:

npx --yes spec-tools-mcp@latest

Local install (npm install --save-dev)

npm update spec-tools-mcp

After updating, restart your AI agent.

Contributing

Contributions are always welcome! If you find a bug or have a feature request, please open an issue. Pull requests are also greatly appreciated.

License

MIT