规范工作流 MCP

一个模型上下文协议（MCP）服务器，为AI辅助软件开发提供结构化的规范驱动开发工作流工具，具有实时Web仪表板和VSCode扩展，可直接在开发环境中监控和管理项目进度。

📺 展示

🔄 审批系统演示

了解审批系统的工作原理：创建文档、通过仪表板请求审批、提供反馈并跟踪修订。

📊 仪表板和规范管理

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

功能特性

• 结构化开发工作流 - 顺序规范创建（需求 → 设计 → 任务）
• 实时Web仪表板 - 通过实时更新监控规范、任务和进度
• VSCode扩展 - 为VSCode开发者提供集成侧边栏仪表板
• 文档管理 - 从仪表板或扩展查看和管理所有规范文档
• 归档系统 - 组织已完成的规范以保持活跃项目的整洁
• 任务进度跟踪 - 可视化进度条和详细任务状态
• 审批工作流 - 完整的审批流程，包括批准、拒绝和修订请求
• 指导文档 - 项目愿景、技术决策和结构指导
• 声音通知 - 可配置的审批和任务完成音频提醒
• Bug工作流 - 完整的Bug报告和解决跟踪
• 模板系统 - 所有文档类型的预构建模板
• 跨平台 - 支持Windows、macOS和Linux

🌍 支持的语言

整个界面（仪表板、VSCode扩展）支持以下语言：

• 🇺🇸 英语 (en)
• 🇯🇵 日语 (ja) - 日本語
• 🇨🇳 中文 (zh) - 中文
• 🇪🇸 西班牙语 (es) - Español
• 🇧🇷 葡萄牙语 (pt) - Português
• 🇩🇪 德语 (de) - Deutsch
• 🇫🇷 法语 (fr) - Français
• 🇷🇺 俄语 (ru) - Русский
• 🇮🇹 意大利语 (it) - Italiano
• 🇰🇷 韩语 (ko) - 한국어
• 🇸🇦 阿拉伯语 (ar) - العربية

语言选择在仪表板和VSCode扩展设置中均可使用。

快速开始

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

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

   自动启动仪表板（随MCP服务器自动打开仪表板）：

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

   自定义端口：

   {
     "mcpServers": {
       "spec-workflow": {
         "command": "npx",
         "args": ["-y", "@al76/tools-and-spec-workflow-mcp@latest", "/path/to/your/project", "--AutoStartDashboard", "--port", "3456"]
       }
     }
   }

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

2. 选择您的界面：

   选项A：Web仪表板（CLI用户必需）

   # 仅仪表板模式（使用临时端口）
   npx -y @al76/tools-and-spec-workflow-mcp@latest /path/to/your/project --dashboard
   
   # 仅仪表板模式，自定义端口
   npx -y @al76/tools-and-spec-workflow-mcp@latest /path/to/your/project --dashboard --port 3000
   
   # 查看所有可用选项
   npx -y @al76/tools-and-spec-workflow-mcp@latest --help

   命令行选项：

   • --help - 显示全面的使用信息和示例
   • --dashboard - 运行仅仪表板模式（无MCP服务器）
   • --AutoStartDashboard - 随MCP服务器自动启动仪表板
   • --port <number> - 指定仪表板端口（1024-65535）。与--dashboard和--AutoStartDashboard都兼容
   • --config <path> - 使用自定义配置文件而不是默认位置。支持相对路径和绝对路径

   配置文件：

   您可以使用TOML配置文件来配置服务器。默认情况下，服务器会查找<project-dir>/.spec-workflow/config.toml，但您可以使用--config标志指定自定义位置。

   配置示例：

   # 项目目录（默认为当前目录）
   projectDir = "/path/to/your/project"
      
   # 仪表板端口（1024-65535）
   port = 3456
      
   # 随MCP服务器自动启动仪表板
   autoStartDashboard = true
      
   # 运行仅仪表板模式
   dashboardOnly = false
      
   # 界面语言（en, ja, zh, es, pt, de, fr, ru, it, ko, ar）
   lang = "en"

   使用自定义配置文件：

   # 使用自定义配置文件
   npx @al76/tools-and-spec-workflow-mcp --config ~/my-configs/spec.toml
      
   # 自定义配置与仪表板
   npx @al76/tools-and-spec-workflow-mcp --config ./dev-config.toml --dashboard
      
   # CLI参数仍会覆盖自定义配置
   npx @al76/tools-and-spec-workflow-mcp --config ./config.toml --port 4000

   配置优先级：

   1. 命令行参数（最高优先级）
   2. 自定义配置文件（如果使用--config指定）
   3. 默认配置文件（.spec-workflow/config.toml）
   4. 内置默认值（最低优先级）

   完整的配置示例文件及文档可在.spec-workflow/config.example.toml中找到。

   选项B：VSCode扩展（推荐VSCode用户使用）

   从VSCode市场安装**规范工作流MCP扩展**：

   1. 在包含.spec-workflow/的项目目录中打开VSCode
   2. 扩展会自动在VSCode内提供仪表板功能
   3. 通过活动栏中的规范工作流图标访问
   4. 无需单独的仪表板 - 一切都在您的IDE内运行

   扩展功能：

   • 集成侧边栏仪表板，具有实时更新
   • 用于组织已完成规范的归档系统
   • 使用VSCode原生对话框的完整审批工作流
   • 审批和完成的声音通知
   • 编辑器中用于审批和评论的上下文菜单操作

   重要提示： 对于CLI用户，Web仪表板是必需的。对于VSCode用户，扩展替代了单独Web仪表板的需要，同时直接在您的IDE中提供相同的功能。

使用方法

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

创建规范

• "为用户认证创建规范" - 为该功能创建完整的规范工作流
• "创建名为payment-system的规范" - 构建完整的需求 → 设计 → 任务
• "为@prd构建规范" - 获取您现有的PRD并从中创建完整的规范工作流
• "为购物车创建规范 - 包括添加到购物车、数量更新和结账集成" - 详细功能规范

获取信息

• "列出我的规范" - 显示所有规范及其当前状态
• "显示user-auth的进度" - 显示详细的进度信息

实施

• "执行user-auth规范中的任务1.2" - 运行您规范中的特定任务
• "从仪表板复制提示" - 使用仪表板任务列表中的"复制提示"按钮

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

MCP客户端设置

在您的Augment设置中配置：

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

添加到您的MCP配置中：

claude mcp add spec-workflow npx @al76/tools-and-spec-workflow-mcp@latest -- /path/to/your/project

重要提示：

• -y标志绕过npm提示以实现更流畅的安装
• --分隔符确保路径传递给spec-workflow脚本，而不是npx
• 将/path/to/your/project替换为您实际的项目目录路径

Windows替代方案（如果上述方法不起作用）：

claude mcp add spec-workflow cmd.exe /c "npx @al76/tools-and-spec-workflow-mcp@latest /path/to/your/project"

添加到claude_desktop_config.json：

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

或使用自动启动的仪表板：

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

添加到您的MCP服务器配置中：

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

添加到您的Continue配置中：

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

添加到您的Cursor设置中（settings.json）：

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

添加到您的opencode.json配置文件中（全局在~/.config/opencode/opencode.json或项目特定）：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "spec-workflow": {
      "type": "local",
      "command": ["npx", "-y", "@al76/tools-and-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 - 清理已完成的审批

用户界面

Web仪表板

Web仪表板是CLI用户的独立服务。每个项目都有自己的专用仪表板，运行在临时端口上。仪表板提供：

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

仪表板功能

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

VSCode扩展

VSCode扩展直接在您的IDE内提供所有仪表板功能：

• 侧边栏集成 - 从活动栏访问所有功能
• 归档管理 - 在活跃和已归档的规范之间切换
• 原生对话框 - 所有操作的VSCode确认对话框
• 编辑器集成 - 审批和评论的上下文菜单操作
• 声音通知 - 可配置的音频提醒
• 无外部依赖 - 完全在VSCode内工作

VSCode用户的扩展优势

• 单一环境 - 无需在浏览器和IDE之间切换
• 原生体验 - 使用VSCode的原生UI组件
• 更好的集成 - 上下文菜单操作和编辑器集成
• 简化设置 - 无需单独的仪表板服务

工作流过程

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仪表板监控进度

文件结构

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. Claude MCP配置与项目路径不工作

   • 确保您使用正确的语法：claude mcp add spec-workflow npx -y @al76/tools-and-spec-workflow-mcp@latest -- /path/to/your/project
   • --分隔符对于将路径传递给脚本而不是npx至关重要
   • 验证路径存在且可访问
   • 对于包含空格的路径，确保在您的shell中正确引用
   • 检查您的claude.json中生成的配置，确保路径出现在args数组中

2. 仪表板无法启动

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

3. 审批不工作

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

4. MCP服务器无法连接

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

5. 端口冲突

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

6. 仪表板不更新

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

获取帮助

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

许可证

GPL-3.0