OpenSpec MCP


OpenSpec 的 MCP (Model Context Protocol) 服务器 - 规格驱动开发，支持实时仪表板和审批流程。

功能特性

- MCP 工具: 将 OpenSpec CLI 完整功能暴露为 MCP 工具
- 评审系统: 添加、回复、解决 proposal/design 的评审意见
- 任务追踪: 解析 tasks.md 并实时追踪进度
- 审批流程: 请求、批准和拒绝变更提案
- 跨服务文档: 在单服务项目中查看跨服务设计文档
- Web 仪表板: 可视化管理界面，支持 Markdown 渲染和实时更新

快速开始

$3

Claude Code CLI（推荐，使用当前目录）:

``bash
claude mcp add openspec -- npx openspec-mcp
`

Claude Code CLI 带仪表板:

`bash
claude mcp add openspec -- npx openspec-mcp --with-dashboard
`

Claude Code CLI 指定项目路径:

`bash
claude mcp add openspec -- npx openspec-mcp /path/to/your/project
`

Claude Desktop / Cursor / 其他:

`json
{
"mcpServers": {
"openspec": {
"command": "npx",
"args": ["-y", "openspec-mcp"]
}
}
}
`

带仪表板:

`json
{
"mcpServers": {
"openspec": {
"command": "npx",
"args": ["-y", "openspec-mcp", "--with-dashboard"]
}
}
}
`

$3

`


列出所有变更

"列出所有 openspec 变更"

显示变更详情

"显示 add-user-auth 变更详情"

更新任务状态

"将 add-user-auth 中的任务 1.1 标记为完成"

请求审批

"向 @reviewer 请求审批 add-user-auth"
`

可用 Prompts (New!)

直接利用 Client 的 AI 能力 (Claude, Codex) 并结合上下文感知 Prompt。

| Prompt | 描述 |
| ----------------- | ------------------------ |
| analyze-project | 深度分析项目架构和技术栈 |
| review-change | 智能审查变更及其关联规格 |

可用工具

$3

| 工具 | 描述 |
| ------------------------------ | -------------------------- |
| openspec_get_instructions | 获取 AGENTS.md 使用指南 |
| openspec_get_project_context | 获取 project.md 项目上下文 |
| openspec_ai_analyze_context | AI 增强的上下文分析 |

$3

| 工具 | 描述 |
| ----------------------- | ---------------- |
| openspec_list_changes | 列出所有变更提案 |
| openspec_list_specs | 列出所有规格 |
| openspec_show_change | 显示变更详情 |
| openspec_show_spec | 显示规格详情 |

$3

| 工具 | 描述 |
| -------------------------- | ------------ |
| openspec_validate_change | 验证单个变更 |
| openspec_validate_spec | 验证单个规格 |
| openspec_validate_all | 批量验证 |

$3

| 工具 | 描述 |
| ------------------------- | -------------- |
| openspec_archive_change | 归档已完成变更 |

$3

| 工具 | 描述 |
| ------------------------------- | -------------------- |
| openspec_get_tasks | 获取任务列表和进度 |
| openspec_update_task | 更新任务状态 |
| openspec_batch_update_tasks | 批量更新任务状态 |
| openspec_get_progress_summary | 获取所有变更进度汇总 |

$3

| 工具 | 描述 |
| --------------------------------- | ------------ |
| openspec_get_approval_status | 获取审批状态 |
| openspec_request_approval | 请求审批 |
| openspec_approve_change | 批准变更 |
| openspec_reject_change | 拒绝变更 |
| openspec_list_pending_approvals | 列出待审批项 |

$3

| 工具 | 描述 |
| ----------------------------------- | ------------------------------------ |
| openspec_add_review | 添加评审意见到 proposal/design/tasks |
| openspec_list_reviews | 列出评审意见（支持过滤） |
| openspec_reply_review | 回复评审意见 |
| openspec_resolve_review | 标记评审为已解决 |
| openspec_get_review_summary | 获取评审统计信息 |
| openspec_check_approval_readiness | 检查是否可以请求审批 |

$3

| 工具 | 描述 |
| ------------------------------- | ---------------------------------- |
| openspec_critique_proposal | 评审 proposal/design，识别潜在问题 |
| openspec_get_critique_history | 获取评审历史记录 |
| openspec_get_latest_critique | 获取最新评审结果 |

$3

| 工具 | 描述 |
| ------------------------- | ------------------------------ |
| openspec_run_qa | 运行质量检查（类型/lint/测试） |
| openspec_get_qa_status | 获取 QA 状态 |
| openspec_get_qa_history | 获取 QA 历史记录 |
| openspec_stop_qa | 停止正在运行的 QA |
| openspec_get_qa_summary | 获取所有变更的 QA 汇总 |

$3

| 工具 | 描述 |
| ------------------------------ | ----------------------------- |
| openspec_analyze_context | 分析项目上下文（技术栈/结构） |
| openspec_get_context_summary | 获取项目上下文摘要 |

$3

| 工具 | 描述 |
| --------------------------- | -------------- |
| openspec_list_templates | 列出可用模板 |
| openspec_create_change | 从模板创建变更 |
| openspec_preview_template | 预览模板内容 |

$3

| 工具 | 描述 |
| ---------------------------- | -------------- |
| openspec_prepare_proposal | 准备提案结构 |
| openspec_save_proposal | 保存生成的提案 |
| openspec_generate_proposal | 从需求生成提案 |

$3

| 工具 | 描述 |
| ---------------------- | ----------------- |
| openspec_setup_hooks | 设置项目 Git 钩子 |

$3

| 工具 | 描述 |
| ---------------------------------- | -------------- |
| openspec_list_cross_service_docs | 列出跨服务文档 |
| openspec_read_cross_service_doc | 读取跨服务文档 |

审批流程

`
draft -> pending_approval -> approved -> implementing -> completed -> archived
-> rejected -> draft (修改后重新提交)
`

审批记录存储在 openspec/approvals/.json。

跨服务文档

对于共享 .cross-service/ 目录的多服务项目（如 Git worktree），在 proposal.md frontmatter 中配置：

`yaml
---
crossService:
rootPath: "../../../../.cross-service" # 相对于 change 目录的路径
documents:
- design.md
- flows.md
- services.yaml
archivePolicy: snapshot # 'snapshot'（默认）或 'reference'
---


你的 proposal 内容...


`

仪表板将显示 “Cross-Service” 标签页：

- design.md / flows.md: 渲染为 Markdown
- services.yaml: 可视化卡片视图，展示服务状态、变更列表和部署顺序

CLI 选项

`bash
openspec-mcp [path] [options]

参数:
path 项目目录路径（默认：当前目录）

选项:
--dashboard 仅启动 Web 仪表板（HTTP 模式）
--with-dashboard 启动 MCP 服务器并同时启动仪表板
-p, --port 仪表板端口（默认：3000；占用时自动递增，0 为随机端口）
-V, --version 显示版本号
-h, --help 显示帮助
`

$3

`bash


仅 MCP 服务器（使用当前目录）

openspec-mcp

MCP 服务器指定项目

openspec-mcp /path/to/project

仅仪表板

openspec-mcp --dashboard

MCP 服务器 + 仪表板

openspec-mcp --with-dashboard

自定义端口启动仪表板

openspec-mcp --dashboard --port 8080
`

Web 仪表板

仪表板提供可视化界面，用于管理变更、追踪任务和处理审批。

$3

| 路由 | 描述 |
| -------------- | ------------------ |
| / | 概览统计和最近变更 |
| /changes | 变更列表及进度 |
| /changes/:id | 变更详情和任务管理 |
| /specs | 浏览规格文档 |
| /approvals | 审批队列管理 |

$3

- 实时更新: WebSocket 连接实现进度和评审的实时更新
- 任务管理: 直接在 UI 中切换任务状态
- 审批操作: 带备注的批准/拒绝操作
- 进度可视化: 进度条和状态徽章
- 评审管理: 查看、解决和追踪评审，支持 Open/Resolved 切换
- 跨服务文档: 查看跨服务设计文档，services.yaml 可视化展示
- Markdown 渲染: Proposal 和 Design 内容完整支持 Markdown 渲染

开发

`bash


安装依赖

npm install

构建

npm run build

开发模式

npm run dev

运行测试

npm test
`

系统要求

- Node.js >= 20.0.0
- OpenSpec CLI (npm install -g @fission-ai/openspec`)

许可证

MIT