ForgeSpec MCP

The coordination backbone for multi-agent AI development. ForgeSpec MCP is a Model Context Protocol server that brings structured, auditable workflows to AI-powered software engineering through Spec-Driven Development (SDD).

---

Why ForgeSpec?

Building software with multiple AI agents (Claude, Codex, Gemini, etc.) introduces coordination challenges that don't exist in single-agent workflows:

Problem	Without ForgeSpec	With ForgeSpec
Conflicting edits	Two agents modify the same file simultaneously, causing merge conflicts and lost work	File reservation system with TTL prevents conflicts before they happen
No shared context	Each agent works in isolation; one agent's decisions are invisible to others	Contract validation creates a shared audit trail across all phases
Unstructured work	Agents jump straight to code without specs, producing inconsistent results	9-phase pipeline enforces propose -> spec -> design -> implement flow
Lost progress	If an agent fails mid-task, there's no way to resume from where it left off	SQLite-backed task board persists state; any agent can pick up where another stopped
No quality gates	Code ships without validation against original requirements	Confidence thresholds block phase transitions until quality criteria are met

Key Advantages

• Zero infrastructure -- Embedded SQLite database, no external services required
• Universal compatibility -- Works with any MCP client: Claude Code, Codex CLI, Gemini CLI, OpenClaw, and more
• Instant setup -- One command to start: npx -y forgespec-mcp
• Battle-tested pipeline -- 9 phases with confidence thresholds prevent premature phase transitions
• Audit trail -- Every contract, task transition, and file reservation is logged with timestamps
• Cross-platform -- Tested on Ubuntu, Windows, and macOS with Node 18, 20, and 22
• Cortex-ready -- Native integration with Cortex for persistent memory and knowledge graph across sessions

---

Recommended: Pair with Cortex

ForgeSpec manages the workflow (contracts, tasks, file locks). Cortex manages the memory (observations, knowledge graph, session continuity). Together they form a complete multi-agent coordination stack:

┌─────────────────────────────────────────────────────┐
│                   MCP Clients                       │
│   Claude Code  ·  Codex CLI  ·  Gemini CLI  · ...  │
└──────────┬──────────────────────────┬───────────────┘
           │                          │
     ┌─────▼─────┐            ┌──────▼──────┐
     │ ForgeSpec  │            │   Cortex    │
     │  MCP       │◄──────────►│   MCP       │
     │            │  artifact  │             │
     │ Contracts  │  type:     │ Observations│
     │ Task Board │  "cortex"  │ Knowledge   │
     │ File Locks │            │ Graph       │
     └────────────┘            └─────────────┘

• ForgeSpec validates and persists SDD contracts, manages task dependencies, prevents file conflicts
• Cortex stores artifacts as observations, connects them via knowledge graph, enables session recovery
• Artifacts saved with type: "cortex" are persisted to Cortex via mem_save and linked with mem_relate

Install both for the full experience:

claude mcp add forgespec --transport stdio -- npx -y forgespec-mcp
claude mcp add cortex --transport stdio -- npx -y @anthropic/cortex-mcp

ForgeSpec works standalone without Cortex -- artifacts can also use type: "openspec" (filesystem) or type: "inline" (returned in response).

---

Quick Start

Using npx (no installation required)

npx -y forgespec-mcp

Install globally

npm install -g forgespec-mcp

Verify installation

forgespec-mcp --help

---

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

---

The SDD Pipeline

ForgeSpec enforces the Spec-Driven Development lifecycle -- a 9-phase pipeline that ensures AI agents work methodically rather than jumping straight to code.

Each phase has a confidence threshold that must be met before transitioning to the next:

Phase	Threshold	Purpose
init	0.5	Bootstrap project context and conventions
explore	0.5	Investigate codebase, diagnose issues
propose	0.7	Draft change proposal with scope and risks
spec	0.8	Write detailed specifications with Given/When/Then
design	0.7	Define architecture, data flows, file changes
tasks	0.8	Decompose into dependency-ordered implementation tasks
apply	0.6	Execute implementation (partial completion allowed)
verify	0.9	Validate implementation against specs
archive	0.9	Merge specs, generate retrospective

---

Tools Reference

ForgeSpec exposes 15 MCP tools organized in three categories.

SDD Contract Tools (5)

Manage the development lifecycle with typed, validated contracts.

Tool	Description
sdd_validate	Validate a contract against phase schema with confidence check
sdd_save	Validate and persist a contract to the database
sdd_get	Retrieve a single contract by ID
sdd_list	List contracts with optional project/phase filters
sdd_history	Get phase transition history for a project

Task Board Tools (8)

SQLite-backed task management with dependency tracking and auto-unblocking.

Tool	Description
tb_create_board	Create a board with optional inline tasks (atomic, avoids N separate calls)
tb_add_task	Add a task with priority, spec ref, criteria, and dependencies
tb_status	Get board status with tasks grouped by status
tb_claim	Claim a task (validates dependencies before assignment)
tb_update	Update status and/or append timestamped notes (auto-unblocks dependents on done)
tb_unblocked	List tasks ready to work on (all dependencies resolved)
tb_get	Get full task details by ID
tb_list_boards	List all boards (for discovery after context loss)

File Reservation Tools (2)

Advisory file locking to prevent multi-agent edit conflicts.

Tool	Description
file_reserve	Reserve files/globs with TTL. Use check_only: true to check conflicts without reserving
file_release	Release reservations (specific patterns or all)

---

Usage Examples

Example 1: Validate and save an SDD contract

An AI agent completing the "propose" phase saves its work as a validated contract:

// Tool: sdd_validate
{
  "contract": "{\"phase\":\"propose\",\"change_name\":\"add-auth-service\",\"project\":\"my-app\",\"status\":\"success\",\"confidence\":0.85,\"executive_summary\":\"Add JWT-based authentication service with login, logout, and token refresh endpoints. Affects 4 files in src/auth/.\",\"artifacts_saved\":[{\"topic_key\":\"sdd/add-auth-service/proposal\",\"type\":\"cortex\"}],\"next_recommended\":[\"spec\",\"design\"],\"risks\":[{\"description\":\"Token storage strategy needs security review\",\"level\":\"medium\"}]}"
}

// Response:
{
  "valid": true,
  "phase": "propose",
  "confidence": 0.85,
  "threshold": 0.7,
  "meets_confidence": true,
  "allowed_next_phases": ["spec", "design", "init"],
  "warnings": []
}

// Tool: sdd_save (after validation)
{
  "contract": "{\"phase\":\"propose\",\"change_name\":\"add-auth-service\",\"project\":\"my-app\",\"status\":\"success\",\"confidence\":0.85,\"executive_summary\":\"Add JWT-based authentication service...\",\"next_recommended\":[\"spec\",\"design\"],\"risks\":[]}"
}

// Response:
{
  "saved": true,
  "id": "sdd_a1b2c3d4-...",
  "phase": "propose",
  "project": "my-app"
}

Example 2: Create a task board and manage tasks

Set up a board, add tasks with dependencies, and let agents claim work:

// Step 1: Create a board
// Tool: tb_create_board
{ "project": "my-app", "name": "add-auth-service" }
// -> { "created": true, "board_id": "board_x7k9m2...", "project": "my-app" }

// Step 2: Add tasks with dependencies
// Tool: tb_add_task
{
  "board_id": "board_x7k9m2...",
  "title": "Create JWT utility module",
  "description": "Implement sign, verify, and refresh token functions",
  "priority": "p0",
  "spec_ref": "sdd/add-auth-service/spec",
  "acceptance_criteria": "All token operations pass unit tests",
  "dependencies": []
}
// -> { "created": true, "task_id": "task_abc123...", "priority": "p0" }

// Tool: tb_add_task
{
  "board_id": "board_x7k9m2...",
  "title": "Build auth middleware",
  "priority": "p1",
  "acceptance_criteria": "Middleware validates tokens on protected routes",
  "dependencies": ["task_abc123..."]  // depends on JWT module
}
// -> { "created": true, "task_id": "task_def456..." }

// Step 3: Agent claims a task
// Tool: tb_claim
{ "task_id": "task_abc123...", "agent": "implement-agent-1" }
// -> { "claimed": true, "task_id": "task_abc123...", "status": "in_progress" }

// Step 4: Mark task done (auto-unblocks dependents)
// Tool: tb_update
{ "task_id": "task_abc123...", "status": "done", "notes": "JWT module complete with RS256 support" }
// -> { "updated": true, "unblocked_tasks": ["task_def456..."] }
// task_def456 automatically moves from "backlog" to "ready"

Example 3: Prevent file conflicts between agents

Two agents working in parallel use file reservations to avoid conflicts:

// Agent 1 checks then reserves auth files (two-phase pattern)
// Tool: file_reserve (check_only)
{
  "patterns": ["src/auth/**", "src/middleware/auth.ts"],
  "agent": "implement-agent-1",
  "check_only": true
}
// -> { "reserved": false, "has_conflicts": false, "conflicts": [] }

// No conflicts — proceed to reserve
// Tool: file_reserve
{
  "patterns": ["src/auth/**", "src/middleware/auth.ts"],
  "agent": "implement-agent-1",
  "ttl_minutes": 30
}
// -> { "reserved": true, "has_conflicts": false, "expires_at": "2025-01-15T10:30:00.000Z" }

// Agent 2 checks before editing
// Tool: file_reserve (check_only)
{
  "patterns": ["src/auth/jwt.ts"],
  "agent": "implement-agent-2",
  "check_only": true
}
// -> { "reserved": false, "has_conflicts": true, "conflicts": [{ "pattern": "src/auth/**", "held_by": "implement-agent-1" }] }
// Agent 2 knows to work on something else

// Agent 1 finishes and releases
// Tool: file_release
{ "agent": "implement-agent-1" }
// -> { "released": true, "count": 2 }

Example 4: Track project phase history

Review how a change progressed through the pipeline:

// Tool: sdd_history
{ "project": "my-app", "limit": 5 }

// Response:
{
  "project": "my-app",
  "history": [
    { "id": "sdd_...", "phase": "verify", "change_name": "add-auth-service", "status": "success", "confidence": 0.92, "created_at": "2025-01-15T10:45:00Z" },
    { "id": "sdd_...", "phase": "apply",  "change_name": "add-auth-service", "status": "success", "confidence": 0.78, "created_at": "2025-01-15T10:30:00Z" },
    { "id": "sdd_...", "phase": "tasks",  "change_name": "add-auth-service", "status": "success", "confidence": 0.88, "created_at": "2025-01-15T09:15:00Z" },
    { "id": "sdd_...", "phase": "spec",   "change_name": "add-auth-service", "status": "success", "confidence": 0.85, "created_at": "2025-01-15T09:00:00Z" },
    { "id": "sdd_...", "phase": "propose","change_name": "add-auth-service", "status": "success", "confidence": 0.85, "created_at": "2025-01-15T08:30:00Z" }
  ]
}

---

Environment Variables

Variable	Default	Description
FORGESPEC_DIR	~/.forgespec	Directory for database storage
FORGESPEC_DB	~/.forgespec/forgespec.db	Full path to SQLite database

---

Architecture

forgespec-mcp
├── src/
│   ├── index.ts              # Entry point: stdio transport
│   ├── server.ts             # MCP server setup and tool registration
│   ├── types/index.ts        # Zod schemas, phase config, type definitions
│   ├── database/index.ts     # SQLite init, WAL mode, schema creation
│   ├── tools/
│   │   ├── sdd-contracts.ts  # 5 contract lifecycle tools
│   │   ├── task-board.ts     # 8 task management tools
│   │   └── file-reservation.ts # 2 file locking tools
│   └── utils/id.ts           # Prefixed UUID generation
└── tests/
    ├── sdd-contracts.test.ts # Schema and phase transition tests
    └── tools.test.ts         # Integration tests for all CRUD operations

Tech stack:

• Model Context Protocol SDK -- MCP server framework
• better-sqlite3 -- Embedded database with WAL mode
• Zod -- Runtime schema validation
• Vitest -- Testing framework with v8 coverage

---

Development

# Clone the repository
git clone https://github.com/lleontor705/forgespec-mcp.git
cd forgespec-mcp

# Install dependencies
npm install

# Run in development mode (hot reload)
npm run dev

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Build for production
npm run build

# Open MCP Inspector for debugging
npm run inspect

Releasing a New Version

ForgeSpec uses standard-version for automatic semantic versioning based on Conventional Commits.

# Commits determine the version bump automatically:
#   fix: ...    -> patch (1.2.0 -> 1.2.1)
#   feat: ...   -> minor (1.2.0 -> 1.3.0)
#   feat!: ...  -> major (1.2.0 -> 2.0.0)

# Create a release (bumps version, updates CHANGELOG, creates git tag)
npm run release

# Or specify the bump type manually
npm run release -- --release-as minor
npm run release -- --release-as major

# First release from current version
npm run release -- --first-release

# Push with tags to trigger CI/CD
git push --follow-tags origin master

The CI/CD pipeline then:

1. Runs tests across Ubuntu/Windows/macOS with Node 18, 20, 22
2. Waits for production environment approval
3. Publishes to npm with provenance
4. Creates a GitHub release with auto-generated notes

---

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Use Conventional Commits for your messages:
   • feat: add new tool for X
   • fix: resolve race condition in file reservation
   • docs: update usage examples
4. Run tests: npm test
5. Push and open a Pull Request

---

License

MIT -- built by lleontor705