Skip to main content
Glama

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-mcp

ForgeSpec 可以独立于 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-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"] }
  }
}

SDD 流水线

ForgeSpec 强制执行规范驱动开发生命周期 —— 一个 9 阶段的流水线,确保 AI 智能体有条不紊地工作,而不是直接跳到代码编写。

每个阶段都有一个置信度阈值,必须在转换到下一阶段之前达到:

阶段

阈值

目的

init

0.5

引导项目上下文和约定

explore

0.5

调查代码库,诊断问题

propose

0.7

起草包含范围和风险的变更提议

spec

0.8

编写带有 Given/When/Then 的详细规范

design

0.7

定义架构、数据流、文件变更

tasks

0.8

分解为依赖排序的实现任务

apply

0.6

执行实现(允许部分完成)

verify

0.9

根据规范验证实现

archive

0.9

合并规范,生成回顾


工具参考

ForgeSpec 提供了分为三类的 15 个 MCP 工具。

SDD 合同工具 (5)

使用类型化、经过验证的合同管理开发生命周期。

工具

描述

sdd_validate

根据阶段模式验证合同并进行置信度检查

sdd_save

验证合同并将其持久化到数据库

sdd_get

按 ID 获取单个合同

sdd_list

列出合同,支持可选的项目/阶段过滤器

sdd_history

获取项目的阶段转换历史

任务板工具 (8)

基于 SQLite 的任务管理,具有依赖跟踪和自动解锁功能。

工具

描述

tb_create_board

创建一个带有可选内联任务的看板(原子操作,避免 N 次单独调用)

tb_add_task

添加带有优先级、规范引用、标准和依赖项的任务

tb_status

获取看板状态,任务按状态分组

tb_claim

认领任务(在分配前验证依赖项)

tb_update

更新状态和/或附加带时间戳的备注(完成后自动解锁依赖项)

tb_unblocked

列出可执行的任务(所有依赖项已解决)

tb_get

按 ID 获取完整任务详情

tb_list_boards

列出所有看板(用于上下文丢失后的发现)

文件预留工具 (2)

建议性文件锁定,防止多智能体编辑冲突。

工具

描述

file_reserve

使用 TTL 预留文件/glob。使用 check_only: true 仅检查冲突而不进行预留

file_release

释放预留(特定模式或全部)


使用示例

示例 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" }
  ]
}

环境变量

变量

默认值

描述

FORGESPEC_DIR

~/.forgespec

数据库存储目录

FORGESPEC_DB

~/.forgespec/forgespec.db

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

技术栈:


开发

# 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 master

CI/CD 流水线随后会:

  1. 在 Ubuntu/Windows/macOS 上使用 Node 18、20、22 运行测试

  2. 等待生产环境批准

  3. 发布到带有来源证明的 npm

  4. 创建带有自动生成说明的 GitHub 发布


贡献

  1. Fork 本仓库

  2. 创建功能分支:git checkout -b feature/my-feature

  3. 在提交信息中使用 Conventional Commits:

    • feat: add new tool for X

    • fix: resolve race condition in file reservation

    • docs: update usage examples

  4. 运行测试:npm test

  5. 推送并提交 Pull Request


许可证

MIT -- 由 lleontor705 构建

Available Tools

30 tools
file_releaseB
Idempotent

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_reserveA
Idempotent

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 CapabilitiesC
Read-onlyIdempotent

Negotiate ForgeSpec coordination mode, schemas, independently versioned features, and limits.

Inputs: client, required, requested_mode. Returns: modes, limits, server, schemas, +3 more

forgespec_healthA
Read-onlyIdempotent

Get server health diagnostics, database integrity status, system time, active leases, and version telemetry.

Inputs: no named parameters.

sdd_getA
Read-onlyIdempotent

Get a single SDD contract by ID. Returns full contract data.

Inputs: contract_id (required).

sdd_historyA
Read-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_listA
Read-onlyIdempotent

List all SDD contracts with optional filters by project and phase.

Inputs: limit, phase, project.

sdd_saveB
Idempotent

Validate and persist an SDD contract. Records the phase transition for project traceability.

Inputs: contract (required), actor, api_version, schema_version, +5 more.

sdd_validateA
Read-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_logA
Read-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_grantA
Idempotent

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_handoffC
Idempotent

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_revokeA
DestructiveIdempotent

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

    C2.7/5.0

    Scored across 30 tools

    Disambiguation3/5

    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.

    Naming Consistency3/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      4
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      An 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.
      58
      23 npm
      21
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Centralized 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 npm
      1
      MIT