[한국어](README.ko.md) | [中文](README.zh.md) | **English** | [日本語](README.ja.md)

# 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](https://nodejs.org) 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:

```sh
/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`

<details>
<summary>Generate .vscode/mcp.json</summary>

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

```bash
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`:

```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).

</details>

<details>
<summary>MCP server only (one-click, direct skill invocation not available)</summary>

[<img src="https://img.shields.io/badge/VS_Code-Install%20MCP%20Server-0098FF?style=flat-square&logo=visualstudiocode" alt="Install in VS Code">](https://vscode.dev/redirect/mcp/install?name=io.github.blue03183%2Fspec-tools-mcp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22spec-tools-mcp%40latest%22%5D%2C%22env%22%3A%7B%7D%7D)
[<img src="https://img.shields.io/badge/VS_Code_Insiders-Install%20MCP%20Server-24bfa5?style=flat-square&logo=visualstudiocode" alt="Install in VS Code Insiders">](https://insiders.vscode.dev/redirect?url=vscode-insiders%253Amcp%252Finstall%253F%257B%2522name%2522%253A%2522io.github.blue03183%252Fspec-tools-mcp%2522%252C%2522config%2522%253A%257B%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522spec-tools-mcp%2540latest%2522%255D%252C%2522env%2522%253A%257B%257D%257D%257D)

</details>

---

**Codex CLI**

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

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

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

```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):

```bash
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`:

```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:

```bash
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:

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

<details>
<summary>Using a local installation path</summary>

First, install the package:

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

Then reference the local path in your config:

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

</details>

#### 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:

```json
{
  "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 | Description | Example |
|------|-------------|---------|
| `spec_init` | Initialize a new feature spec project | `Initialize dashboard with spec_init` |
| `spec_todo` | Analyze planning docs, run the requirement interview, and (if the change spans multiple modules) design `architecture.md` before generating `todo.md` | `Analyze requirements with spec_todo` |
| `spec_work` | Pick an execution mode, write a plan for a todo item → approve → implement → verify | `Work on T-01 with spec_work` |
| `get_rules` | Return one of the three rule documents — `spec-development-rules` (default), `codebase-wiki-authoring`, or `codebase-wiki` — selected via the `name` argument | `Show me the development rules` |
| `spec_status` | Show todo progress and pending approvals across all features | `Show current spec status` |
| `spec_handoff` | Generate a handoff document so another developer or session can resume immediately | `Create handoff doc for dashboard` |
| `spec_archive` | Move a completed feature from `projects/` to `archive/` | `Archive the dashboard feature` |
| `spec_search` | Return code locations and symbols from `_codebase/` (including the `generated/` index); with `query` returns only matching sections, without `query` returns `index.md` + a heading TOC | `Search for OrderService in codebase` |
| `spec_codebase_map` | Regenerate `_codebase/generated/` from source (regex-based, no LLM, 0 tokens) — file list, exported symbols, module dependency graph, directory tree | `Rebuild the codebase index` |

**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](docs/workflow.md) (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.

```sh
/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:

```bash
npx --yes spec-tools-mcp@latest
```

**Local install (`npm install --save-dev`)**

```bash
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](https://github.com/blue03183/spec-tools-mcp/issues). Pull requests are also greatly appreciated.

## License

MIT