한국어 | 中文 | 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.

Related MCP server: MCP SDD Server

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

Use auto-configure to generate .vscode/mcp.json:

npx spec-tools-mcp init

VS Code's MCP server runs inside the VSCode Extension Host, not the terminal, so npx and node may not be recognized. Explicitly specify command and env PATH in .vscode/mcp.json:

{
  "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"
      }
    }
  }
}

Run which npx to get the npx path, and echo $PATH to get the PATH value.

After refreshing the IDE window, go to Extensions → MCP Servers - Installed, right-click spec-tools-mcp, and select Start Server to start it manually.

Note: If you reload the IDE window, you must restart the server manually (it does not restart automatically).

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"]
    }
  }
}

First, install the package:

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

Then reference the local path in your config:

{
  "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 proposes a module map for the project-wide codebase wiki at ai-spec/_codebase/ and, once you approve it, calls spec_codebase_map to build the mechanical index. It also sets up IDE-specific context hooks (Claude Code, Codex, Copilot, Cursor) so the assistant is nudged to check _codebase/ before scanning source.

spec_todo
Run after planning documents are ready. Analyzes files in docs/, runs a one-question-at-a-time requirement interview, and writes requirement.md — including an ID-tagged 제약 조건 (constraints) table that later documents reference by ID. If the change is a cross-module structural change (new data-access layer, library swap, a pattern repeated across 3+ tasks), it drafts architecture.md first and gets it approved before decomposing todo.md — so task boundaries follow a reviewed structure rather than an ad-hoc one.

spec_work
Use when starting implementation or resuming a prior session. First asks you to choose an execution mode: review each plan (approve every plan.md individually) or run the whole list (your mode choice acts as one-time pre-approval for the remaining tasks). Either way it enforces a plan → approval → code gate: writes tasks/T-NN-plan.md first, blocks implementation until approved, and records an Approval Baseline (snapshot of requirement.md/architecture.md/the todo item at approval time) so a later edit to any of those correctly invalidates a stale approval. When implementation starts, the agent immediately marks the todo item as [ ] IN PROGRESS — so even if the session is cut off mid-task, the next session can identify and resume by diffing the plan's declared file list against actual code state (no separate progress-tracking file needed). Completed tasks accumulate into a single feature-level summary.md instead of a per-task log. 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 development protocol. spec-development-rules (the default) covers the R1–R9 procedure; codebase-wiki-authoring covers wiki file formats and update rules (needed only when writing to _codebase/); codebase-wiki covers how to read the wiki and trace why a piece of code looks the way it does. Loading only the document actually needed keeps sessions that aren't touching the wiki lighter.

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 the goal, todo status, the last completed entry from summary.md, and the in-progress task's planned changes 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.

spec_codebase_map
Rebuilds _codebase/generated/ — the mechanically-derived half of the wiki (file lists, exported symbols, module dependency graph, directory tree). It's regex-based with no LLM involved, so it's essentially free to call and is re-run before every read of the wiki rather than freshness-checked. The other half of the wiki (module map, module-specific patterns, conventions, gotchas) is judgment-based and written by the agent, never by this tool.

6. Workflow

Visual diagram: Full workflow diagram (labels in Korean)

1. Initialize the project with spec_init

   • Creates an ai-spec/projects/{project-name}/ folder with requirement.md template and optional docs/ folder

   • Proposes a module map for ai-spec/_codebase/ and, once approved, calls spec_codebase_map to build the mechanical index (file list, symbols, dependency graph)

   • Sets up IDE context hooks (Claude Code / Codex / Copilot / Cursor) if the corresponding config directory exists

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 runs a one-question-at-a-time interview, then writes requirement.md (including an ID-tagged constraints table) — 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

   • If the change is a cross-module structural change, drafts architecture.md (structural decisions, rejected alternatives, migration strategy) and asks for approval before decomposing tasks — so task boundaries follow a reviewed structure, not an ad-hoc one. Skipped entirely for single-module changes

   • 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 first asks you to pick an execution mode: review each plan individually, or run the whole list with your mode choice standing as one-time pre-approval for the rest

   • AI writes tasks/T-NN-plan.md for the selected task and asks for your approval (unless the batch mode already covers it)

   • You review the plan file directly — to request changes, write your feedback in the User Feedback section, then reply 수정 (revise)

   • Reply 승인 (approve) or 진행해 (proceed), or set Approval Status to [승인] directly, to start implementation. On approval the server also stamps an Approval Baseline — the current mtimes of requirement.md/architecture.md plus a snapshot of the todo item — so editing any of those later correctly invalidates the approval instead of silently going stale

   • The server enforces the approval gate: unless the plan 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 by diffing the plan's declared changes against actual code state

   • Deviations from the plan are appended to the plan's 구현 중 변경 (implementation changes) log with a tag ([실패]/[확인]/[변경 대상 추가]/…) rather than silently overwritten, so the reasoning survives

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 determines the remaining scope by comparing the plan's change log against the real codebase (git status/git diff) — no separate progress file to go stale

   • _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. Each completed task appends a section to the feature-level summary.md — the single place a reviewer reads to see everything that changed and why

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

   • spec_handoff generates a concise summary of the goal, todo status, the last completed summary.md entry, and the in-progress task's planned changes

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                    # module map (human/agent-approved), project overview, key flows
│   ├─ last-synced.md              # change-tracing index: judgment doc → trigger (spec-work <feature>/T-NN, …)
│   ├─ modules/
│   │   └─ <domain>.md             # per-domain: role + module-specific patterns (judgment-authored)
│   ├─ conventions.md              # shared conventions, naming rules, architecture patterns
│   ├─ gotchas.md                  # implicit constraints & gotchas (human-authored / code-verified)
│   ├─ .mapignore                  # (optional) paths to exclude from the index that .gitignore can't express
│   └─ generated/                  # mechanically produced by spec_codebase_map — never hand-edited
│       ├─ summary.md              # scan scope, exclusions, per-module symbol-extraction coverage
│       ├─ dependencies.md         # module dependency graph (import-level, SSOT)
│       ├─ tree.md                 # directory tree
│       └─ modules/<domain>.md     # per-module file list, exported symbols, external deps
├─ 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), incl. an ID-tagged constraints table
        ├─ architecture.md         # (conditional) cross-task structural decisions + rejected alternatives — only for changes spanning multiple modules
        ├─ preview.html            # UI mockup (generated when UI changes are included)
        ├─ todo.md                 # task list generated by AI
        ├─ summary.md              # feature-level change log — one section appended per completed task
        ├─ docs/                   # original planning files (PDF, images, etc.)
        └─ tasks/
            └─ T-NN-plan.md        # per-task design intent, implementation approach, approval status (E2E tasks: T-NNE-plan.md)

_codebase/ role: split into two kinds of files. generated/** is rebuilt from scratch on every spec_codebase_map call (regex-based, no LLM, effectively free) and should never be hand-edited — anything wrong there is fixed by correcting the module map, not the file. Everything else is judgment-authored by the agent (or, for gotchas.md, a human) and only changes when the underlying judgment changes. This split means file/symbol/dependency data is always current without token cost, while the harder-to-derive knowledge (why a module is bounded the way it is, what pattern it follows) persists across sessions.

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]

• tasks/T-NN-plan.md — an Approval Status line followed by [대기] (pending) or [승인] (approved); if missing or malformed, spec_work blocks implementation to fail safe. An approved plan also carries an Approval Baseline recording the inputs it was approved against

• requirement.md — keep the ## 기능 목표 (goal) heading so spec_handoff can extract the feature goal

Specs written before this format (per-task <T-NN>-<summary>/{plan.md,update.md} folders) keep working — spec_work falls back to the legacy path when tasks/T-NN-plan.md doesn't exist, and the bundled skills migrate them on first touch. See get_rules (name: "spec-development-rules") → "포맷 계약" for the full contract, and → "기존 spec 하위 호환" for the migration rules.

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.

• _codebase/ is shared across all features. If multiple developers work on the same module at the same time, git merge conflicts can happen on generated/** — don't hand-merge those, just re-run spec_codebase_map after the merge and let it regenerate from the merged code (it's a pure function of source, so a merged result is the only correct one). index.md/modules/**/conventions.md/gotchas.md/last-synced.md are judgment-authored and merge normally.

• 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.

• _codebase/generated/ is fully rebuilt on every spec_codebase_map call rather than freshness-checked against git — the scan is regex-based with no LLM involved, so re-running it costs a few hundred milliseconds and 0 tokens, and it writes a file only when the content actually changed (so it won't invalidate an assistant's prompt cache on a no-op run). This works the same with or without git; without git it falls back to walking the filesystem directly (.gitignore is then not honored, so use .mapignore to compensate).

• 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