{"id":47823677,"url":"https://github.com/lleontor705/forgespec-mcp","last_synced_at":"2026-04-12T04:03:05.104Z","repository":{"id":348183192,"uuid":"1195022514","full_name":"lleontor705/forgespec-mcp","owner":"lleontor705","description":"MCP Server for Spec-Driven Development (SDD) — contract validation, task board, and file reservation for multi-agent AI systems","archived":false,"fork":false,"pushed_at":"2026-04-12T02:16:38.000Z","size":112,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-12T02:25:49.118Z","etag":null,"topics":["ai","mcp","model-context-protocol","multi-agent","sdd","spec-driven-development","task-board"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lleontor705.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-29T05:31:02.000Z","updated_at":"2026-04-12T02:12:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/lleontor705/forgespec-mcp","commit_stats":null,"previous_names":["lleontor705/forgespec-mcp"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/lleontor705/forgespec-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lleontor705%2Fforgespec-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lleontor705%2Fforgespec-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lleontor705%2Fforgespec-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lleontor705%2Fforgespec-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lleontor705","download_url":"https://codeload.github.com/lleontor705/forgespec-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lleontor705%2Fforgespec-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31703501,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-11T21:17:31.016Z","status":"online","status_checked_at":"2026-04-12T02:00:06.763Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","mcp","model-context-protocol","multi-agent","sdd","spec-driven-development","task-board"],"created_at":"2026-04-03T19:18:14.725Z","updated_at":"2026-04-12T04:03:05.089Z","avatar_url":"https://github.com/lleontor705.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/logo.svg\" alt=\"ForgeSpec MCP\" width=\"450\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/npm/v/forgespec-mcp?style=flat-square\u0026color=blue\" alt=\"npm version\" /\u003e\n  \u003cimg src=\"https://img.shields.io/github/actions/workflow/status/lleontor705/forgespec-mcp/ci.yml?style=flat-square\u0026label=CI\" alt=\"CI\" /\u003e\n  \u003cimg src=\"https://img.shields.io/npm/l/forgespec-mcp?style=flat-square\" alt=\"license\" /\u003e\n  \u003cimg src=\"https://img.shields.io/node/v/forgespec-mcp?style=flat-square\" alt=\"node\" /\u003e\n  \u003cimg src=\"https://img.shields.io/npm/dm/forgespec-mcp?style=flat-square\" alt=\"downloads\" /\u003e\n\u003c/p\u003e\n\n# ForgeSpec MCP\n\n**The coordination backbone for multi-agent AI development.** ForgeSpec MCP is a [Model Context Protocol](https://modelcontextprotocol.io/) server that brings structured, auditable workflows to AI-powered software engineering through Spec-Driven Development (SDD).\n\n---\n\n## Why ForgeSpec?\n\nBuilding software with multiple AI agents (Claude, Codex, Gemini, etc.) introduces coordination challenges that don't exist in single-agent workflows:\n\n| Problem | Without ForgeSpec | With ForgeSpec |\n|---------|-------------------|----------------|\n| **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 |\n| **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 |\n| **Unstructured work** | Agents jump straight to code without specs, producing inconsistent results | 9-phase pipeline enforces propose -\u003e spec -\u003e design -\u003e implement flow |\n| **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 |\n| **No quality gates** | Code ships without validation against original requirements | Confidence thresholds block phase transitions until quality criteria are met |\n\n### Key Advantages\n\n- **Zero infrastructure** -- Embedded SQLite database, no external services required\n- **Universal compatibility** -- Works with any MCP client: Claude Code, Codex CLI, Gemini CLI, OpenClaw, and more\n- **Instant setup** -- One command to start: `npx -y forgespec-mcp`\n- **Battle-tested pipeline** -- 9 phases with confidence thresholds prevent premature phase transitions\n- **Audit trail** -- Every contract, task transition, and file reservation is logged with timestamps\n- **Cross-platform** -- Tested on Ubuntu, Windows, and macOS with Node 18, 20, and 22\n- **Cortex-ready** -- Native integration with [Cortex](https://github.com/lleontor705/cortex) for persistent memory and knowledge graph across sessions\n\n---\n\n## Recommended: Pair with Cortex\n\nForgeSpec manages the **workflow** (contracts, tasks, file locks). [**Cortex**](https://github.com/lleontor705/cortex) manages the **memory** (observations, knowledge graph, session continuity). Together they form a complete multi-agent coordination stack:\n\n```\n┌─────────────────────────────────────────────────────┐\n│                   MCP Clients                       │\n│   Claude Code  ·  Codex CLI  ·  Gemini CLI  · ...  │\n└──────────┬──────────────────────────┬───────────────┘\n           │                          │\n     ┌─────▼─────┐            ┌──────▼──────┐\n     │ ForgeSpec  │            │   Cortex    │\n     │  MCP       │◄──────────►│   MCP       │\n     │            │  artifact  │             │\n     │ Contracts  │  type:     │ Observations│\n     │ Task Board │  \"cortex\"  │ Knowledge   │\n     │ File Locks │            │ Graph       │\n     └────────────┘            └─────────────┘\n```\n\n- **ForgeSpec** validates and persists SDD contracts, manages task dependencies, prevents file conflicts\n- **Cortex** stores artifacts as observations, connects them via knowledge graph, enables session recovery\n- Artifacts saved with `type: \"cortex\"` are persisted to Cortex via `mem_save` and linked with `mem_relate`\n\nInstall both for the full experience:\n\n```bash\nclaude mcp add forgespec --transport stdio -- npx -y forgespec-mcp\nclaude mcp add cortex --transport stdio -- npx -y @anthropic/cortex-mcp\n```\n\n\u003e ForgeSpec works standalone without Cortex -- artifacts can also use `type: \"openspec\"` (filesystem) or `type: \"inline\"` (returned in response).\n\n---\n\n## Quick Start\n\n### Using npx (no installation required)\n\n```bash\nnpx -y forgespec-mcp\n```\n\n### Install globally\n\n```bash\nnpm install -g forgespec-mcp\n```\n\n### Verify installation\n\n```bash\nforgespec-mcp --help\n```\n\n---\n\n## Client Configuration\n\n### Claude Code\n\n```bash\nclaude mcp add forgespec --transport stdio -- npx -y forgespec-mcp\n```\n\n### Codex CLI (`~/.codex/config.toml`)\n\n```toml\n[mcp_servers.forgespec]\ncommand = \"npx\"\nargs = [\"-y\", \"forgespec-mcp\"]\n```\n\n### Gemini CLI (`settings.json`)\n\n```json\n{\n  \"mcpServers\": {\n    \"forgespec\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"forgespec-mcp\"]\n    }\n  }\n}\n```\n\n### OpenClaw (`openclaw.json`)\n\n```json5\nmcp: {\n  servers: {\n    forgespec: { command: \"npx\", args: [\"-y\", \"forgespec-mcp\"] }\n  }\n}\n```\n\n---\n\n## The SDD Pipeline\n\nForgeSpec enforces the **Spec-Driven Development** lifecycle -- a 9-phase pipeline that ensures AI agents work methodically rather than jumping straight to code.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/sdd-pipeline.svg\" alt=\"SDD Pipeline\" width=\"100%\" /\u003e\n\u003c/p\u003e\n\nEach phase has a **confidence threshold** that must be met before transitioning to the next:\n\n| Phase | Threshold | Purpose |\n|-------|-----------|---------|\n| `init` | 0.5 | Bootstrap project context and conventions |\n| `explore` | 0.5 | Investigate codebase, diagnose issues |\n| `propose` | 0.7 | Draft change proposal with scope and risks |\n| `spec` | 0.8 | Write detailed specifications with Given/When/Then |\n| `design` | 0.7 | Define architecture, data flows, file changes |\n| `tasks` | 0.8 | Decompose into dependency-ordered implementation tasks |\n| `apply` | 0.6 | Execute implementation (partial completion allowed) |\n| `verify` | 0.9 | Validate implementation against specs |\n| `archive` | 0.9 | Merge specs, generate retrospective |\n\n---\n\n## Tools Reference\n\nForgeSpec exposes **15 MCP tools** organized in three categories.\n\n### SDD Contract Tools (5)\n\nManage the development lifecycle with typed, validated contracts.\n\n| Tool | Description |\n|------|-------------|\n| `sdd_validate` | Validate a contract against phase schema with confidence check |\n| `sdd_save` | Validate and persist a contract to the database |\n| `sdd_get` | Retrieve a single contract by ID |\n| `sdd_list` | List contracts with optional project/phase filters |\n| `sdd_history` | Get phase transition history for a project |\n\n### Task Board Tools (8)\n\nSQLite-backed task management with dependency tracking and auto-unblocking.\n\n| Tool | Description |\n|------|-------------|\n| `tb_create_board` | Create a board with optional inline tasks (atomic, avoids N separate calls) |\n| `tb_add_task` | Add a task with priority, spec ref, criteria, and dependencies |\n| `tb_status` | Get board status with tasks grouped by status |\n| `tb_claim` | Claim a task (validates dependencies before assignment) |\n| `tb_update` | Update status and/or append timestamped notes (auto-unblocks dependents on done) |\n| `tb_unblocked` | List tasks ready to work on (all dependencies resolved) |\n| `tb_get` | Get full task details by ID |\n| `tb_list_boards` | List all boards (for discovery after context loss) |\n\n### File Reservation Tools (2)\n\nAdvisory file locking to prevent multi-agent edit conflicts.\n\n| Tool | Description |\n|------|-------------|\n| `file_reserve` | Reserve files/globs with TTL. Use `check_only: true` to check conflicts without reserving |\n| `file_release` | Release reservations (specific patterns or all) |\n\n---\n\n## Usage Examples\n\n### Example 1: Validate and save an SDD contract\n\nAn AI agent completing the \"propose\" phase saves its work as a validated contract:\n\n```jsonc\n// Tool: sdd_validate\n{\n  \"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\\\"}]}\"\n}\n\n// Response:\n{\n  \"valid\": true,\n  \"phase\": \"propose\",\n  \"confidence\": 0.85,\n  \"threshold\": 0.7,\n  \"meets_confidence\": true,\n  \"allowed_next_phases\": [\"spec\", \"design\", \"init\"],\n  \"warnings\": []\n}\n```\n\n```jsonc\n// Tool: sdd_save (after validation)\n{\n  \"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\\\":[]}\"\n}\n\n// Response:\n{\n  \"saved\": true,\n  \"id\": \"sdd_a1b2c3d4-...\",\n  \"phase\": \"propose\",\n  \"project\": \"my-app\"\n}\n```\n\n### Example 2: Create a task board and manage tasks\n\nSet up a board, add tasks with dependencies, and let agents claim work:\n\n```jsonc\n// Step 1: Create a board\n// Tool: tb_create_board\n{ \"project\": \"my-app\", \"name\": \"add-auth-service\" }\n// -\u003e { \"created\": true, \"board_id\": \"board_x7k9m2...\", \"project\": \"my-app\" }\n\n// Step 2: Add tasks with dependencies\n// Tool: tb_add_task\n{\n  \"board_id\": \"board_x7k9m2...\",\n  \"title\": \"Create JWT utility module\",\n  \"description\": \"Implement sign, verify, and refresh token functions\",\n  \"priority\": \"p0\",\n  \"spec_ref\": \"sdd/add-auth-service/spec\",\n  \"acceptance_criteria\": \"All token operations pass unit tests\",\n  \"dependencies\": []\n}\n// -\u003e { \"created\": true, \"task_id\": \"task_abc123...\", \"priority\": \"p0\" }\n\n// Tool: tb_add_task\n{\n  \"board_id\": \"board_x7k9m2...\",\n  \"title\": \"Build auth middleware\",\n  \"priority\": \"p1\",\n  \"acceptance_criteria\": \"Middleware validates tokens on protected routes\",\n  \"dependencies\": [\"task_abc123...\"]  // depends on JWT module\n}\n// -\u003e { \"created\": true, \"task_id\": \"task_def456...\" }\n\n// Step 3: Agent claims a task\n// Tool: tb_claim\n{ \"task_id\": \"task_abc123...\", \"agent\": \"implement-agent-1\" }\n// -\u003e { \"claimed\": true, \"task_id\": \"task_abc123...\", \"status\": \"in_progress\" }\n\n// Step 4: Mark task done (auto-unblocks dependents)\n// Tool: tb_update\n{ \"task_id\": \"task_abc123...\", \"status\": \"done\", \"notes\": \"JWT module complete with RS256 support\" }\n// -\u003e { \"updated\": true, \"unblocked_tasks\": [\"task_def456...\"] }\n// task_def456 automatically moves from \"backlog\" to \"ready\"\n```\n\n### Example 3: Prevent file conflicts between agents\n\nTwo agents working in parallel use file reservations to avoid conflicts:\n\n```jsonc\n// Agent 1 checks then reserves auth files (two-phase pattern)\n// Tool: file_reserve (check_only)\n{\n  \"patterns\": [\"src/auth/**\", \"src/middleware/auth.ts\"],\n  \"agent\": \"implement-agent-1\",\n  \"check_only\": true\n}\n// -\u003e { \"reserved\": false, \"has_conflicts\": false, \"conflicts\": [] }\n\n// No conflicts — proceed to reserve\n// Tool: file_reserve\n{\n  \"patterns\": [\"src/auth/**\", \"src/middleware/auth.ts\"],\n  \"agent\": \"implement-agent-1\",\n  \"ttl_minutes\": 30\n}\n// -\u003e { \"reserved\": true, \"has_conflicts\": false, \"expires_at\": \"2025-01-15T10:30:00.000Z\" }\n\n// Agent 2 checks before editing\n// Tool: file_reserve (check_only)\n{\n  \"patterns\": [\"src/auth/jwt.ts\"],\n  \"agent\": \"implement-agent-2\",\n  \"check_only\": true\n}\n// -\u003e { \"reserved\": false, \"has_conflicts\": true, \"conflicts\": [{ \"pattern\": \"src/auth/**\", \"held_by\": \"implement-agent-1\" }] }\n// Agent 2 knows to work on something else\n\n// Agent 1 finishes and releases\n// Tool: file_release\n{ \"agent\": \"implement-agent-1\" }\n// -\u003e { \"released\": true, \"count\": 2 }\n```\n\n### Example 4: Track project phase history\n\nReview how a change progressed through the pipeline:\n\n```jsonc\n// Tool: sdd_history\n{ \"project\": \"my-app\", \"limit\": 5 }\n\n// Response:\n{\n  \"project\": \"my-app\",\n  \"history\": [\n    { \"id\": \"sdd_...\", \"phase\": \"verify\", \"change_name\": \"add-auth-service\", \"status\": \"success\", \"confidence\": 0.92, \"created_at\": \"2025-01-15T10:45:00Z\" },\n    { \"id\": \"sdd_...\", \"phase\": \"apply\",  \"change_name\": \"add-auth-service\", \"status\": \"success\", \"confidence\": 0.78, \"created_at\": \"2025-01-15T10:30:00Z\" },\n    { \"id\": \"sdd_...\", \"phase\": \"tasks\",  \"change_name\": \"add-auth-service\", \"status\": \"success\", \"confidence\": 0.88, \"created_at\": \"2025-01-15T09:15:00Z\" },\n    { \"id\": \"sdd_...\", \"phase\": \"spec\",   \"change_name\": \"add-auth-service\", \"status\": \"success\", \"confidence\": 0.85, \"created_at\": \"2025-01-15T09:00:00Z\" },\n    { \"id\": \"sdd_...\", \"phase\": \"propose\",\"change_name\": \"add-auth-service\", \"status\": \"success\", \"confidence\": 0.85, \"created_at\": \"2025-01-15T08:30:00Z\" }\n  ]\n}\n```\n\n---\n\n## Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `FORGESPEC_DIR` | `~/.forgespec` | Directory for database storage |\n| `FORGESPEC_DB` | `~/.forgespec/forgespec.db` | Full path to SQLite database |\n\n---\n\n## Architecture\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/architecture.svg\" alt=\"Architecture\" width=\"700\" /\u003e\n\u003c/p\u003e\n\n```\nforgespec-mcp\n├── src/\n│   ├── index.ts              # Entry point: stdio transport\n│   ├── server.ts             # MCP server setup and tool registration\n│   ├── types/index.ts        # Zod schemas, phase config, type definitions\n│   ├── database/index.ts     # SQLite init, WAL mode, schema creation\n│   ├── tools/\n│   │   ├── sdd-contracts.ts  # 5 contract lifecycle tools\n│   │   ├── task-board.ts     # 8 task management tools\n│   │   └── file-reservation.ts # 2 file locking tools\n│   └── utils/id.ts           # Prefixed UUID generation\n└── tests/\n    ├── sdd-contracts.test.ts # Schema and phase transition tests\n    └── tools.test.ts         # Integration tests for all CRUD operations\n```\n\n**Tech stack:**\n- [Model Context Protocol SDK](https://github.com/modelcontextprotocol/typescript-sdk) -- MCP server framework\n- [better-sqlite3](https://github.com/WiseLibs/better-sqlite3) -- Embedded database with WAL mode\n- [Zod](https://github.com/colinhacks/zod) -- Runtime schema validation\n- [Vitest](https://vitest.dev/) -- Testing framework with v8 coverage\n\n---\n\n## Development\n\n```bash\n# Clone the repository\ngit clone https://github.com/lleontor705/forgespec-mcp.git\ncd forgespec-mcp\n\n# Install dependencies\nnpm install\n\n# Run in development mode (hot reload)\nnpm run dev\n\n# Run tests\nnpm test\n\n# Run tests in watch mode\nnpm run test:watch\n\n# Build for production\nnpm run build\n\n# Open MCP Inspector for debugging\nnpm run inspect\n```\n\n### Releasing a New Version\n\nForgeSpec uses [standard-version](https://github.com/conventional-changelog/standard-version) for automatic semantic versioning based on [Conventional Commits](https://www.conventionalcommits.org/).\n\n```bash\n# Commits determine the version bump automatically:\n#   fix: ...    -\u003e patch (1.2.0 -\u003e 1.2.1)\n#   feat: ...   -\u003e minor (1.2.0 -\u003e 1.3.0)\n#   feat!: ...  -\u003e major (1.2.0 -\u003e 2.0.0)\n\n# Create a release (bumps version, updates CHANGELOG, creates git tag)\nnpm run release\n\n# Or specify the bump type manually\nnpm run release -- --release-as minor\nnpm run release -- --release-as major\n\n# First release from current version\nnpm run release -- --first-release\n\n# Push with tags to trigger CI/CD\ngit push --follow-tags origin master\n```\n\nThe CI/CD pipeline then:\n1. Runs tests across Ubuntu/Windows/macOS with Node 18, 20, 22\n2. Waits for production environment approval\n3. Publishes to npm with provenance\n4. Creates a GitHub release with auto-generated notes\n\n---\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/my-feature`\n3. Use [Conventional Commits](https://www.conventionalcommits.org/) for your messages:\n   - `feat: add new tool for X`\n   - `fix: resolve race condition in file reservation`\n   - `docs: update usage examples`\n4. Run tests: `npm test`\n5. Push and open a Pull Request\n\n---\n\n## License\n\n[MIT](LICENSE) -- built by [lleontor705](https://github.com/lleontor705)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flleontor705%2Fforgespec-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flleontor705%2Fforgespec-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flleontor705%2Fforgespec-mcp/lists"}