# OpenSpec MCP
[](https://www.npmjs.com/package/openspec-mcp)
[OpenSpec](https://github.com/Fission-AI/OpenSpec) 的 MCP (Model Context Protocol) 服务器 - 规格驱动开发，支持实时仪表板和审批流程。
## 功能特性
- **MCP 工具**: 将 OpenSpec CLI 完整功能暴露为 MCP 工具
- **评审系统**: 添加、回复、解决 proposal/design 的评审意见
- **任务追踪**: 解析 tasks.md 并实时追踪进度
- **审批流程**: 请求、批准和拒绝变更提案
- **跨服务文档**: 在单服务项目中查看跨服务设计文档
- **Web 仪表板**: 可视化管理界面，支持 Markdown 渲染和实时更新
## 快速开始
### 1. 添加到 MCP 配置
**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"]
}
}
}
```
### 2. 在对话中使用
```
# 列出所有变更
"列出所有 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` | 智能审查变更及其关联规格 |
## 可用工具
### 指南与上下文 (Guides & Context)
| 工具 | 描述 |
| ------------------------------ | -------------------------- |
| `openspec_get_instructions` | 获取 AGENTS.md 使用指南 |
| `openspec_get_project_context` | 获取 project.md 项目上下文 |
| `openspec_ai_analyze_context` | AI 增强的上下文分析 |
### 管理类 (Management)
| 工具 | 描述 |
| ----------------------- | ---------------- |
| `openspec_list_changes` | 列出所有变更提案 |
| `openspec_list_specs` | 列出所有规格 |
| `openspec_show_change` | 显示变更详情 |
| `openspec_show_spec` | 显示规格详情 |
### 验证类 (Validation)
| 工具 | 描述 |
| -------------------------- | ------------ |
| `openspec_validate_change` | 验证单个变更 |
| `openspec_validate_spec` | 验证单个规格 |
| `openspec_validate_all` | 批量验证 |
### 归档类 (Archive)
| 工具 | 描述 |
| ------------------------- | -------------- |
| `openspec_archive_change` | 归档已完成变更 |
### 任务类 (Tasks)
| 工具 | 描述 |
| ------------------------------- | -------------------- |
| `openspec_get_tasks` | 获取任务列表和进度 |
| `openspec_update_task` | 更新任务状态 |
| `openspec_batch_update_tasks` | 批量更新任务状态 |
| `openspec_get_progress_summary` | 获取所有变更进度汇总 |
### 审批类 (Approval)
| 工具 | 描述 |
| --------------------------------- | ------------ |
| `openspec_get_approval_status` | 获取审批状态 |
| `openspec_request_approval` | 请求审批 |
| `openspec_approve_change` | 批准变更 |
| `openspec_reject_change` | 拒绝变更 |
| `openspec_list_pending_approvals` | 列出待审批项 |
### 评审类 (Reviews)
| 工具 | 描述 |
| ----------------------------------- | ------------------------------------ |
| `openspec_add_review` | 添加评审意见到 proposal/design/tasks |
| `openspec_list_reviews` | 列出评审意见（支持过滤） |
| `openspec_reply_review` | 回复评审意见 |
| `openspec_resolve_review` | 标记评审为已解决 |
| `openspec_get_review_summary` | 获取评审统计信息 |
| `openspec_check_approval_readiness` | 检查是否可以请求审批 |
### 评审自审类 (Critique)
| 工具 | 描述 |
| ------------------------------- | ---------------------------------- |
| `openspec_critique_proposal` | 评审 proposal/design，识别潜在问题 |
| `openspec_get_critique_history` | 获取评审历史记录 |
| `openspec_get_latest_critique` | 获取最新评审结果 |
### 质量检查类 (QA)
| 工具 | 描述 |
| ------------------------- | ------------------------------ |
| `openspec_run_qa` | 运行质量检查（类型/lint/测试） |
| `openspec_get_qa_status` | 获取 QA 状态 |
| `openspec_get_qa_history` | 获取 QA 历史记录 |
| `openspec_stop_qa` | 停止正在运行的 QA |
| `openspec_get_qa_summary` | 获取所有变更的 QA 汇总 |
### 上下文类 (Context)
| 工具 | 描述 |
| ------------------------------ | ----------------------------- |
| `openspec_analyze_context` | 分析项目上下文（技术栈/结构） |
| `openspec_get_context_summary` | 获取项目上下文摘要 |
### 模板类 (Templates)
| 工具 | 描述 |
| --------------------------- | -------------- |
| `openspec_list_templates` | 列出可用模板 |
| `openspec_create_change` | 从模板创建变更 |
| `openspec_preview_template` | 预览模板内容 |
### 生成器类 (Generator)
| 工具 | 描述 |
| ---------------------------- | -------------- |
| `openspec_prepare_proposal` | 准备提案结构 |
| `openspec_save_proposal` | 保存生成的提案 |
| `openspec_generate_proposal` | 从需求生成提案 |
### Hooks 类
| 工具 | 描述 |
| ---------------------- | ----------------- |
| `openspec_setup_hooks` | 设置项目 Git 钩子 |
### 跨服务类 (Cross-Service)
| 工具 | 描述 |
| ---------------------------------- | -------------- |
| `openspec_list_cross_service_docs` | 列出跨服务文档 |
| `openspec_read_cross_service_doc` | 读取跨服务文档 |
## 审批流程
```
draft -> pending_approval -> approved -> implementing -> completed -> archived
-> rejected -> draft (修改后重新提交)
```
审批记录存储在 `openspec/approvals/<change-id>.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 <number> 仪表板端口（默认：3000；占用时自动递增，0 为随机端口）
-V, --version 显示版本号
-h, --help 显示帮助
```
### 示例
```bash
# 仅 MCP 服务器（使用当前目录）
openspec-mcp
# MCP 服务器指定项目
openspec-mcp /path/to/project
# 仅仪表板
openspec-mcp --dashboard
# MCP 服务器 + 仪表板
openspec-mcp --with-dashboard
# 自定义端口启动仪表板
openspec-mcp --dashboard --port 8080
```
## Web 仪表板
仪表板提供可视化界面，用于管理变更、追踪任务和处理审批。
### 仪表板页面
| 路由 | 描述 |
| -------------- | ------------------ |
| `/` | 概览统计和最近变更 |
| `/changes` | 变更列表及进度 |
| `/changes/:id` | 变更详情和任务管理 |
| `/specs` | 浏览规格文档 |
| `/approvals` | 审批队列管理 |
### 功能亮点
- **实时更新**: 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
