forgespec-mcp
ForgeSpec MCP
多智能体 AI 开发的协调骨干。 ForgeSpec MCP 是一个 Model Context Protocol 服务器,通过规范驱动开发 (SDD) 为 AI 驱动的软件工程带来结构化、可审计的工作流程。
为什么选择 ForgeSpec?
使用多个 AI 智能体(Claude、Codex、Gemini 等)构建软件会引入单智能体工作流程中不存在的协调挑战:
问题 | 没有 ForgeSpec | 使用 ForgeSpec |
冲突编辑 | 两个智能体同时修改同一个文件,导致合并冲突和工作丢失 | 带有 TTL 的文件预留系统在冲突发生前阻止冲突 |
缺乏共享上下文 | 每个智能体独立工作;一个智能体的决策对其他智能体不可见 | 合同验证在所有阶段创建共享审计跟踪 |
非结构化工作 | 智能体直接跳到代码编写而没有规范,导致结果不一致 | 9 阶段流水线强制执行“提议 -> 规范 -> 设计 -> 实现”流程 |
进度丢失 | 如果智能体在任务中途失败,无法从中断处恢复 | 基于 SQLite 的任务板持久化状态;任何智能体都可以从另一个智能体停止的地方继续 |
缺乏质量门禁 | 代码在未根据原始需求进行验证的情况下发布 | 置信度阈值在满足质量标准之前阻止阶段转换 |
核心优势
零基础设施 -- 内置 SQLite 数据库,无需外部服务
通用兼容性 -- 适用于任何 MCP 客户端:Claude Code、Codex CLI、Gemini CLI、OpenClaw 等
即时设置 -- 一条命令启动:
npx -y forgespec-mcp久经考验的流水线 -- 9 个阶段及置信度阈值,防止过早的阶段转换
审计跟踪 -- 每个合同、任务转换和文件预留都带有时间戳记录
跨平台 -- 在 Ubuntu、Windows 和 macOS 上使用 Node 18、20 和 22 进行过测试
Cortex 就绪 -- 与 Cortex 原生集成,实现跨会话的持久化记忆和知识图谱
Related MCP server: Specky
推荐:与 Cortex 搭配使用
ForgeSpec 管理工作流程(合同、任务、文件锁)。Cortex 管理记忆(观察、知识图谱、会话连续性)。它们共同构成了一个完整的多智能体协调栈:
┌─────────────────────────────────────────────────────┐
│ MCP Clients │
│ Claude Code · Codex CLI · Gemini CLI · ... │
└──────────┬──────────────────────────┬───────────────┘
│ │
┌─────▼─────┐ ┌──────▼──────┐
│ ForgeSpec │ │ Cortex │
│ MCP │◄──────────►│ MCP │
│ │ artifact │ │
│ Contracts │ type: │ Observations│
│ Task Board │ "cortex" │ Knowledge │
│ File Locks │ │ Graph │
└────────────┘ └─────────────┘ForgeSpec 验证并持久化 SDD 合同,管理任务依赖,防止文件冲突
Cortex 将工件存储为观察,通过知识图谱连接它们,实现会话恢复
使用
type: "cortex"保存的工件通过mem_save持久化到 Cortex,并使用mem_relate进行关联
安装两者以获得完整体验:
claude mcp add forgespec --transport stdio -- npx -y forgespec-mcp
claude mcp add cortex --transport stdio -- npx -y @anthropic/cortex-mcpForgeSpec 可以独立于 Cortex 工作 -- 工件也可以使用
type: "openspec"(文件系统)或type: "inline"(在响应中返回)。
快速入门
使用 npx(无需安装)
npx -y forgespec-mcp全局安装
npm install -g forgespec-mcp验证安装
forgespec-mcp --help客户端配置
Claude Code
claude mcp add forgespec --transport stdio -- npx -y forgespec-mcpCodex 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"] }
}
}SDD 流水线
ForgeSpec 强制执行规范驱动开发生命周期 —— 一个 9 阶段的流水线,确保 AI 智能体有条不紊地工作,而不是直接跳到代码编写。
每个阶段都有一个置信度阈值,必须在转换到下一阶段之前达到:
阶段 | 阈值 | 目的 |
| 0.5 | 引导项目上下文和约定 |
| 0.5 | 调查代码库,诊断问题 |
| 0.7 | 起草包含范围和风险的变更提议 |
| 0.8 | 编写带有 Given/When/Then 的详细规范 |
| 0.7 | 定义架构、数据流、文件变更 |
| 0.8 | 分解为依赖排序的实现任务 |
| 0.6 | 执行实现(允许部分完成) |
| 0.9 | 根据规范验证实现 |
| 0.9 | 合并规范,生成回顾 |
工具参考
ForgeSpec 提供了分为三类的 15 个 MCP 工具。
SDD 合同工具 (5)
使用类型化、经过验证的合同管理开发生命周期。
工具 | 描述 |
| 根据阶段模式验证合同并进行置信度检查 |
| 验证合同并将其持久化到数据库 |
| 按 ID 获取单个合同 |
| 列出合同,支持可选的项目/阶段过滤器 |
| 获取项目的阶段转换历史 |
任务板工具 (8)
基于 SQLite 的任务管理,具有依赖跟踪和自动解锁功能。
工具 | 描述 |
| 创建一个带有可选内联任务的看板(原子操作,避免 N 次单独调用) |
| 添加带有优先级、规范引用、标准和依赖项的任务 |
| 获取看板状态,任务按状态分组 |
| 认领任务(在分配前验证依赖项) |
| 更新状态和/或附加带时间戳的备注(完成后自动解锁依赖项) |
| 列出可执行的任务(所有依赖项已解决) |
| 按 ID 获取完整任务详情 |
| 列出所有看板(用于上下文丢失后的发现) |
文件预留工具 (2)
建议性文件锁定,防止多智能体编辑冲突。
工具 | 描述 |
| 使用 TTL 预留文件/glob。使用 |
| 释放预留(特定模式或全部) |
使用示例
示例 1:验证并保存 SDD 合同
完成“propose”阶段的 AI 智能体将其工作保存为经过验证的合同:
// 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"
}示例 2:创建任务板并管理任务
设置看板,添加带有依赖项的任务,并让智能体认领工作:
// 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"示例 3:防止智能体之间的文件冲突
并行工作的两个智能体使用文件预留来避免冲突:
// 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 }示例 4:跟踪项目阶段历史
回顾变更在流水线中的进展情况:
// 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" }
]
}环境变量
变量 | 默认值 | 描述 |
|
| 数据库存储目录 |
|
| SQLite 数据库的完整路径 |
架构
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技术栈:
Model Context Protocol SDK -- MCP 服务器框架
better-sqlite3 -- 具有 WAL 模式的嵌入式数据库
Zod -- 运行时模式验证
Vitest -- 具有 v8 覆盖率的测试框架
开发
# 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发布新版本
ForgeSpec 使用 standard-version 进行基于 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 masterCI/CD 流水线随后会:
在 Ubuntu/Windows/macOS 上使用 Node 18、20、22 运行测试
等待生产环境批准
发布到带有来源证明的 npm
创建带有自动生成说明的 GitHub 发布
贡献
Fork 本仓库
创建功能分支:
git checkout -b feature/my-feature在提交信息中使用 Conventional Commits:
feat: add new tool for Xfix: resolve race condition in file reservationdocs: update usage examples
运行测试:
npm test推送并提交 Pull Request
许可证
MIT -- 由 lleontor705 构建
Available Tools
30 toolsfile_releaseBIdempotent
Release file reservations held by an agent.
Inputs: agent (required), actor, task_id, lease_id, +9 more.
file_renewB
Renew an active direct-v1 file lease with matching task-attempt authority and revision.
Inputs: actor (required), task_id (required), lease_id (required), attempt_id (required), +8 more.
file_reserveAIdempotent
Reserve files or glob patterns to prevent conflicts between agents. Use check_only=true to check for conflicts without reserving. Reservations expire after TTL.
Inputs: patterns (required), actor, agent, task_id, +12 more.
forgespec_capabilitiesForgeSpec CapabilitiesCRead-onlyIdempotent
Negotiate ForgeSpec coordination mode, schemas, independently versioned features, and limits.
Inputs: client, required, requested_mode. Returns: modes, limits, server, schemas, +3 more
forgespec_healthARead-onlyIdempotent
Get server health diagnostics, database integrity status, system time, active leases, and version telemetry.
Inputs: no named parameters.
sdd_getARead-onlyIdempotent
Get a single SDD contract by ID. Returns full contract data.
Inputs: contract_id (required).
sdd_historyARead-onlyIdempotent
Get the SDD phase history for a project. Shows all contract transitions in chronological order.
Inputs: project (required), limit, phase, cursor, +3 more.
sdd_listARead-onlyIdempotent
List all SDD contracts with optional filters by project and phase.
Inputs: limit, phase, project.
sdd_saveBIdempotent
Validate and persist an SDD contract. Records the phase transition for project traceability.
Inputs: contract (required), actor, api_version, schema_version, +5 more.
sdd_validateARead-onlyIdempotent
Validate an SDD contract against the phase schema. Returns validation result with confidence check and allowed transitions.
Inputs: contract (required).
tb_add_taskB
Add a task to an existing board. Every task should reference a spec and have acceptance criteria.
Inputs: title (required), board_id (required), actor, gates, +12 more.
tb_approveA
Record an immutable direct-v1 approval decision with asserted provenance for a declared task gate. Asserted provenance is not authentication.
Inputs: actor (required), gate_id (required), task_id (required), decision (required), +9 more.
tb_audit_logARead-onlyIdempotent
Query historical audit trail of authority grants, revocations, and approval decisions.
Inputs: actor, limit, board_id, event_type.
tb_batch_statusC
Query bounded direct-v1 task status summaries for recovery without messaging.
Inputs: actor (required), board_id (required), limit, ready, +9 more.
tb_claimB
Claim a task for execution. Only claims tasks in 'ready' status with all dependencies resolved.
Inputs: agent (required), task_id (required), api_version, lease_seconds, +4 more.
tb_create_boardA
Create a new task board for a project. Optionally include tasks inline to create board + all tasks in a single atomic call (avoids N separate tb_add_task calls).
Inputs: name (required), project (required), actor, tasks, +5 more.
tb_eventsC
Query authorized immutable direct-v1 event deltas in stable revision order.
Inputs: actor (required), board_id (required), limit, cursor, +7 more.
tb_getA
Get full details of a single task by ID.
Inputs: task_id (required).
tb_grantAIdempotent
Create an attenuated, expiring task-authority grant. Requires exact task-authority@1.0.0 negotiation.
Inputs: actor (required), resource (required), operation (required), capability (required), +4 more.
tb_handoffCIdempotent
Create a reference-only attenuated handoff. Requires exact task-authority@1.0.0 negotiation.
Inputs: refs (required), actor (required), toActor (required), resource (required), +5 more.
tb_heartbeatC
Renew an active direct-v1 task attempt lease.
Inputs: actor (required), task_id (required), attempt_id (required), api_version (required), +6 more.
tb_list_boardsA
List task boards, optionally filtered by project. With actor plus direct-v1 context (coordination_mode/api_version/schema_version 1.0.0), also lists direct-v1 boards the actor owns or holds an active grant on. Use this to discover board IDs after context loss.
Inputs: actor, project, capability, api_version, +2 more.
tb_queryD
Query a stable, bounded, authorized direct-v1 task snapshot.
Inputs: actor (required), board_id (required), limit, ready, +9 more.
tb_recover_claimsB
Recover expired direct-v1 attempts. Tasks require explicit requeue afterward.
Inputs: actor (required), board_id (required), api_version (required), schema_version (required), +6 more.
tb_requeueC
Explicitly requeue a recovered direct-v1 task.
Inputs: actor (required), reason (required), task_id (required), api_version (required), +6 more.
tb_revokeADestructiveIdempotent
Append an authority revocation without changing board ownership. Requires exact task-authority@1.0.0 negotiation.
Inputs: actor (required), grantId (required), capability (required), idempotencyKey (required), +2 more.
tb_set_dependenciesB
Atomically replace a direct-v1 task's normalized same-board dependency set.
Inputs: actor (required), task_id (required), board_id (required), api_version (required), +6 more.
tb_statusB
Get the current status of a task board with all tasks grouped by status.
Inputs: board_id (required).
tb_unblockedB
List all tasks that are ready to be worked on (no unresolved dependencies).
Inputs: board_id (required), actor, capability, api_version, +2 more.
tb_updateA
Update a task's status and/or append notes. Moving to 'done' requires 'in_progress' or 'in_review'. Notes are stored as timestamped entries.
Inputs: task_id (required), actor, notes, status, +9 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 30 tools
Many tools share the tb_ prefix and cover overlapping task/status surfaces (tb_status, tb_batch_status, tb_query, tb_unblocked, tb_get), but descriptions generally carve out distinct purposes: current board status, batch recovery summaries, direct-v1 snapshots, ready work lists, and individual task detail. The authority and recovery tools are also distinguishable, though the high number of task-query variants still leaves real room for mis-selection.
The set consistently uses snake_case domain prefixes (tb_, file_, sdd_, forgespec_), which helps, but the action structure is mixed. Some names are verb+object, while others are bare states or nouns like tb_status, tb_heartbeat, and tb_unblocked, making the surface less predictable than a uniform verb_noun pattern.
At 30 tools, this server is past the 25-tool threshold and packing several separate concerns—task boards, file reservations, SDD contracts, authority grants, audit, health, and capabilities—into one surface. Each tool may serve a purpose, but the aggregate surface feels heavy and harder to navigate for an agent.
The main workflows appear broadly covered: task boards have create/add/update/status/dependency/claim/recovery support; SDD docs have validate/save/get/list/history; and file reservations have reserve/release/renew. Minor gaps, like no explicit board archive/delete or no direct reservation listing, may be intentional for audit-oriented design and agents can work around them.
Maintenance
Related MCP Connectors
Spec-driven development for AI coding agents: live requirements, stories and traceability over MCP
Project management shared by people and AI agents, with persistent project state through MCP.
Spec-driven development MCP server: 8 phases, bi-directional traceability, 7 quality gates.
Hosted MCP server and Agent Skills for specs, engineering threads, and project memory.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables spec-driven development workflows with AI assistants, providing tools for managing specification lifecycles, task dependencies, code navigation, testing, and automated reviews through a unified CLI and MCP interface.4MIT
- AlicenseAqualityCmaintenanceAn MCP server for Spec-Driven Development that transforms natural language ideas and meeting transcripts into structured, production-grade specifications using EARS notation. It automates a 7-phase pipeline to generate project artifacts like requirements, architecture designs, and task lists directly to disk.5823 npm21MIT
- AlicenseNot gradedqualityCmaintenanceCentralized MCP server for spec-driven AI agent workflows, enabling isolated feature management, task tracking, and implementation with handoff and archiving capabilities across multiple projects and developers.20 npm1MIT
- AlicenseNot gradedqualityDmaintenanceTransforms AI agents into spec-driven product engineers by managing the software project lifecycle through requirements, design, implementation, and archiving phases with state-aware MCP tools.5 npmMIT