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

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

npx -y forgespec-mcp

npm install -g forgespec-mcp@1.4.0

forgespec-mcp --help
forgespec-mcp --version

claude mcp add forgespec --transport stdio -- npx -y forgespec-mcp

[mcp_servers.forgespec]
command = "npx"
args = ["-y", "forgespec-mcp"]

{
  "mcpServers": {
    "forgespec": {
      "command": "npx",
      "args": ["-y", "forgespec-mcp"]
    }
  }
}

mcp: {
  servers: {
    forgespec: { command: "npx", args: ["-y", "forgespec-mcp"] }
  }
}

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

// 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"

// 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 }

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

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

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

# Install the locked dependency tree
npm ci

# 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

# 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