forgespec-mcp
MCP Server for Spec-Driven Development (SDD) — contract validation, task board management, and file reservation for multi-agent AI systems.
Works with any MCP-compatible client: Claude Code, Codex CLI, Gemini CLI, OpenClaw, and more.
Features
- SDD Contract Validation — Enforce typed contracts across a 9-phase development pipeline
- Task Board — SQLite-backed task management with dependency tracking and auto-unblocking
- File Reservation — Advisory file locking to prevent multi-agent conflicts
Quick Start
Using npx (no installation required)
npx -y forgespec-mcp
Install globally
npm install -g forgespec-mcp
Configuration
Claude Code
claude mcp add forgespec --transport stdio -- npx -y forgespec-mcp
Codex CLI (~/.codex/config.toml)
[mcp_servers.forgespec]
command = "npx"
args = ["-y", "forgespec-mcp"]
Gemini CLI (settings.json)
{
"mcpServers": {
"forgespec": {
"command": "npx",
"args": ["-y", "forgespec-mcp"]
}
}
}
OpenClaw (openclaw.json)
mcp: {
servers: {
forgespec: { command: "npx", args: ["-y", "forgespec-mcp"] }
}
}
Tools
SDD Contract Tools
| Tool | Description |
|---|---|
sdd_validate | Validate an SDD contract against phase schema |
sdd_save | Validate and persist a contract |
sdd_history | Get phase transition history for a project |
sdd_phases | Get all phases with transitions and confidence thresholds |
Task Board Tools
| Tool | Description |
|---|---|
board_create | Create a new task board |
board_status | Get board status with tasks grouped by status |
board_list | List all boards |
task_add | Add a task with priority, spec ref, and acceptance criteria |
task_claim | Claim a task (checks dependencies) |
task_update | Update task status (auto-unblocks dependents) |
task_unblocked | List tasks ready to work on |
File Reservation Tools
| Tool | Description |
|---|---|
file_reserve | Reserve files/globs with TTL |
file_check | Check for conflicts |
file_release | Release reservations |
SDD Pipeline
The 9-phase Spec-Driven Development lifecycle:
init → explore → propose → spec → design → tasks → apply → verify → archive
Each phase has confidence thresholds and allowed transitions enforced by the contract validator.
| Phase | Confidence Threshold | Can Transition To |
|---|---|---|
| init | 0.5 | explore, propose |
| explore | 0.5 | propose, spec |
| propose | 0.7 | spec, design, init |
| spec | 0.8 | design, tasks |
| design | 0.7 | tasks, spec |
| tasks | 0.8 | apply |
| apply | 0.6 | verify, tasks |
| verify | 0.9 | archive, apply |
| archive | 0.9 | — |
Environment Variables
| Variable | Default | Description |
|---|---|---|
FORGESPEC_DIR | ~/.forgespec | Database directory |
FORGESPEC_DB | ~/.forgespec/forgespec.db | Full database path |
Development
git clone https://github.com/lleontor705/forgespec-mcp.git
cd forgespec-mcp
npm install
npm run dev # Run with tsx (hot reload)
npm test # Run tests
npm run build # Compile TypeScript
npm run inspect # Open MCP Inspector
License
MIT