Spec Workflow MCP

🚀 规范工作流MCP

这是一个模型上下文协议（MCP）服务器，为人工智能辅助软件开发提供结构化的规范驱动开发工作流工具。其特色在于具备一个实时的Web仪表盘，可用于监控和管理项目进度。

🚀 快速开始

1. 添加到您的AI工具配置中（请参阅下面的MCP客户端设置）：

   {
     "mcpServers": {
       "spec-workflow": {
         "command": "npx",
         "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
       }
     }
   }
   

   注意：可以不指定项目路径，但某些MCP客户端可能无法从当前目录启动服务器。

2. 启动Web仪表盘（必需）：

   # 默认（使用临时端口）
   npx -y @pimzino/spec-workflow-mcp@latest /path/to/your/project --dashboard
   
   # 自定义端口
   npx -y @pimzino/spec-workflow-mcp@latest /path/to/your/project --dashboard --port 3000
   
   # 替代语法
   npx -y @pimzino/spec-workflow-mcp@latest /path/to/your/project --dashboard --port=8080
   

   选项：

   • --dashboard - 启动Web仪表盘（必需）
   • --port <number> - 可选的自定义端口（1024 - 65535）。如果未指定，将使用临时端口

   ⚠️ 重要提示

   仪表盘对于工作流的正常运行是必需的。没有它：

   • 文档审批将无法工作
   • 任务进度跟踪将被禁用
   • 规范状态更新将不可用
   • 审批系统将无法正常工作

   注意：MCP服务器和仪表盘现在是独立的服务。您必须同时运行两者：用于AI工具集成的MCP服务器和用于工作流管理、审批和进度跟踪的仪表盘。

✨ 主要特性

• 结构化开发工作流 - 按顺序创建规范（需求 → 设计 → 任务）
• 实时Web仪表盘 - 通过实时更新监控规范、任务和进度
• 文档管理 - 从仪表盘查看和管理所有规范文档
• 任务进度跟踪 - 可视化进度条和详细的任务状态
• 指导文档 - 项目愿景、技术决策和结构指导
• 缺陷工作流 - 完整的缺陷报告和解决跟踪
• 模板系统 - 所有文档类型的预建模板
• 跨平台 - 可在Windows、macOS和Linux上运行

💻 使用示例

基础用法

您可以在对话中简单提及 spec-workflow 或您为MCP服务器指定的任何名称。AI将自动处理完整的工作流，或者您可以使用以下示例提示：

创建规范

• "Create a spec for user authentication" - 为该功能创建完整的规范工作流
• "Create a spec called payment-system" - 构建完整的需求 → 设计 → 任务
• "Build a spec for @prd" - 使用您现有的PRD创建完整的规范工作流
• "Create a spec for shopping-cart - include add to cart, quantity updates, and checkout integration" - 详细的功能规范

获取信息

• "List my specs" - 显示所有规范及其当前状态
• "Show me the user-auth progress" - 显示详细的进度信息

实施

• "Execute task 1.2 in spec user-auth" - 运行规范中的特定任务
• Copy prompts from dashboard - 使用仪表盘任务列表中的“Copy Prompt”按钮

代理会自动处理审批工作流、任务管理，并引导您完成每个阶段。

📚 详细文档

MCP客户端设置

{
  "mcpServers": {
    "spec-workflow": {
      "command": "npx",
      "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
    }
  }
}

claude mcp add spec-workflow npx @pimzino/spec-workflow-mcp@latest /path/to/your/project

{
  "mcpServers": {
    "spec-workflow": {
      "command": "npx",
      "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
    }
  }
}

{
  "mcpServers": {
    "spec-workflow": {
      "command": "npx",
      "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
    }
  }
}

{
  "mcpServers": {
    "spec-workflow": {
      "command": "npx",
      "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
    }
  }
}

{
  "mcp.servers": {
    "spec-workflow": {
      "command": "npx",
      "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "spec-workflow": {
      "type": "local",
      "command": ["npx", "-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"],
      "enabled": true
    }
  }
}

注意：将 /path/to/your/project 替换为您希望规范工作流运行的项目目录的实际路径。

可用工具

工作流指南

• spec-workflow-guide - 规范驱动工作流过程的完整指南
• steering-guide - 创建项目指导文档的指南

规范管理

• create-spec-doc - 创建/更新规范文档（需求、设计、任务）
• spec-list - 列出所有带有状态信息的规范
• spec-status - 获取特定规范的详细状态
• manage-tasks - 用于规范实施的全面任务管理

上下文和模板

• get-template-context - 获取所有文档类型的Markdown模板
• get-steering-context - 获取项目指导上下文和指导
• get-spec-context - 获取特定规范的上下文

指导文档

• create-steering-doc - 创建项目指导文档（产品、技术、结构）

审批系统

• request-approval - 请求用户对文档进行审批
• get-approval-status - 检查审批状态
• delete-approval - 清理已完成的审批

工作流过程

1. 项目设置（推荐）

steering-guide → create-steering-doc (product, tech, structure)

创建基础文档以指导您的项目开发。

2. 功能开发

spec-workflow-guide → create-spec-doc → [review] → implementation

按顺序进行：需求 → 设计 → 任务 → 实施

3. 实施支持

• 使用 get-spec-context 获取详细的实施上下文
• 使用 manage-tasks 跟踪任务完成情况
• 通过Web仪表盘监控进度

Web仪表盘

仪表盘是一个独立的服务，必须与MCP服务器一起手动启动。每个项目都有自己在临时端口上运行的专用仪表盘。仪表盘提供：

• 实时项目概览 - 规范和进度的实时更新
• 文档查看器 - 阅读需求、设计和任务文档
• 任务进度跟踪 - 可视化进度条和任务状态
• 指导文档 - 快速访问项目指导
• 暗模式 - 自动启用以提高可读性

仪表盘特性

• 规范卡片 - 每个规范的概述，带有状态指示器
• 文档导航 - 在需求、设计和任务之间切换
• 任务管理 - 查看任务进度并复制实施提示
• 实时更新 - 通过WebSocket连接实现实时项目状态更新

🔧 技术细节

文件结构

your-project/
  .spec-workflow/
    steering/
      product.md        # 产品愿景和目标
      tech.md          # 技术决策
      structure.md     # 项目结构指南
    specs/
      {spec-name}/
        requirements.md # 需要构建的内容
        design.md      # 如何构建
        tasks.md       # 实施分解
    approval/
      {spec-name}/
        {document-id}.json # 审批状态跟踪

开发

# 安装依赖
npm install

# 构建项目
npm run build

# 在开发模式下运行（自动重新加载）
npm run dev

# 启动生产服务器
npm start

# 清理构建工件
npm run clean

故障排除

常见问题

1. 仪表盘未启动

   • 确保在启动仪表盘服务时使用了 --dashboard 标志
   • 仪表盘必须与MCP服务器分开启动
   • 检查控制台输出以获取仪表盘URL和任何错误消息
   • 如果使用 --port，确保端口号有效（1024 - 65535）且未被其他应用程序使用

2. 审批无法工作

   • 验证仪表盘是否与MCP服务器一起运行
   • 仪表盘对于文档审批和任务跟踪是必需的
   • 检查两个服务是否指向同一项目目录

3. MCP服务器未连接

   • 验证配置中的文件路径是否正确
   • 确保项目已使用 npm run build 进行构建
   • 检查系统路径中是否有Node.js

4. 端口冲突

   • 如果收到“端口已被使用”错误，请使用 --port <different-number> 尝试不同的端口
   • 使用 netstat -an | find ":3000"（Windows）或 lsof -i :3000（macOS/Linux）检查端口使用情况
   • 省略 --port 参数以自动使用可用的临时端口

5. 仪表盘未更新

   • 仪表盘使用WebSocket进行实时更新
   • 如果连接丢失，请刷新浏览器
   • 检查控制台是否有任何JavaScript错误

获取帮助

• 查看 问题 页面以了解已知问题
• 使用提供的模板创建新问题
• 使用工具中的工作流指南获取分步说明

📄 许可证

GPL - 3.0

⭐ 星标历史

📺 展示

🔄 审批系统演示

查看审批系统的工作方式：创建文档、通过仪表盘请求审批、提供反馈并跟踪修订。

📊 仪表盘和规范管理

探索实时仪表盘：查看规范、跟踪进度、导航文档并监控开发工作流。

☕ 支持本项目