Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@al76/tools-and-spec-workflow-mcp) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

规范工作流 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扩展设置中均可使用。

快速开始

添加到您的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客户端可能无法从当前目录启动服务器。

选择您的界面：

选项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 Code

在您的Augment设置中配置：

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

Claude Code CLI

添加到您的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

添加到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"]
    }
  }
}

Cline/Claude Dev

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

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

Continue IDE扩展

添加到您的Continue配置中：

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

Cursor IDE

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

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

OpenCode

添加到您的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

故障排除

常见问题

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数组中
仪表板无法启动
- 确保在启动仪表板服务时使用--dashboard标志
- 仪表板必须与MCP服务器分开启动
- 检查控制台输出中的仪表板URL和任何错误消息
- 如果使用--port，确保端口号有效（1024-65535）且未被其他应用程序使用
审批不工作
- 验证仪表板与MCP服务器一起运行
- 仪表板是文档审批和任务跟踪所必需的
- 检查两个服务都指向相同的项目目录
MCP服务器无法连接
- 验证配置中的文件路径是否正确
- 确保项目已使用npm run build构建
- 检查Node.js是否在您的系统PATH中可用
端口冲突
- 如果收到"端口已被使用"错误，请尝试使用--port <different-number>使用不同端口
- 使用netstat -an | find ":3000"（Windows）或lsof -i :3000（macOS/Linux）检查端口使用情况
- 省略--port参数以自动使用可用的临时端口
仪表板不更新
- 仪表板使用WebSocket进行实时更新
- 如果连接丢失，请刷新浏览器
- 检查控制台是否有JavaScript错误

获取帮助

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

许可证

GPL-3.0

JSPM

@al76/tools-and-spec-workflow-mcp