内容
# 规范工作流 MCP（madmatt112 分叉）
一个用于结构化规范驱动开发的模型上下文协议（MCP）服务器，带有实时仪表板和 VSCode 扩展。
## 分叉通知
这是 [Pimzino/spec-workflow-mcp](https://github.com/Pimzino/spec-workflow-mcp) 的一个硬分叉，于 **2026-03-13** 从上游版本 `2.2.6` 分叉而来。它 **不跟踪上游**，也不会被合并回上游。所有问题/拉取请求都应针对此仓库提出。
`.spec-workflow/` 目录布局、工具名称、配置键和 `SPEC_WORKFLOW_HOME` 环境变量与上游保持相同，因此上游 `2.2.x` 的现有状态可以直接迁移。
## 本分叉新增功能
上游版本中没有的四个功能：
- **对抗性审查** — 对规范文档（需求/设计/任务/管理/分解）进行自动对立审查。生成并执行针对规范内容的对抗性提示，调用全新的 CLI 子代理（默认为 Claude CLI；可配置为任何 LLM CLI）。
- **规范分解** — 强制的工作流阶段，要求在实施前进行任务分解。全新的 `decomposition-guide` 工具与仪表板集成，并具备对抗性审查资格。
- **延迟决策跟踪器** — 全新的 `deferrals` 工具和仪表板 UI，用于记录在规范编写过程中故意推迟的决策。
- **任务审查** — 全新的 `review-task` 和 `get-task-review` 工具，调用全新的仪表板代理，审查已完成的任务实现，然后再标记为完成。
## 关键功能
- **结构化开发工作流** — 顺序规范创建（需求 → 设计 → 任务），并带有强制的分解阶段。
- **实时网页仪表板** — 监控规范、任务和进度，实时更新。
- **VSCode 扩展** — 集成侧边栏仪表板（需从源代码构建此分叉；参见下方）。
- **审批工作流** — 完整的审批流程，带有修订和对抗性审查。
- **任务进度跟踪** — 直观的进度条和详细的狀態。
- **实施日志** — 可搜索的日志，记录所有任务实施情况，并附带代码统计信息。
## 🚀 快速入门
### 步骤 1：添加到您的 AI 工具
将以下内容添加到您的 MCP 配置中（参见下方客户端特定设置）：
```json
{
"mcpServers": {
"spec-workflow": {
"command": "npx",
"args": ["-y", "@madmatt112org/spec-workflow-mcp@latest", "/path/to/your/project"]
}
}
}
```
### 步骤 2：选择您的界面
**选项 A：网页仪表板** （CLI 用户必填）
启动仪表板（默认在 5000 端口运行）：
```bash
npx -y @madmatt112org/spec-workflow-mcp@latest --dashboard
```
仪表板将在以下地址可访问：http://localhost:5000
> **注意：** 仅需一个仪表板实例。所有项目都将连接到同一个仪表板。
**选项 B：VSCode 扩展** （需从源代码构建）
该分叉的扩展尚未发布到 VSCode 市场。需从源代码构建并侧载：
```bash
cd vscode-extension
npm install
npm run package # 生成 .vsix 文件
code --install-extension spec-workflow-mcp-<version>.vsix
```
## 📝 使用方法
只需在对话中提及 spec-workflow：
- **"为用户身份验证创建规范"** — 创建完整规范工作流
- **"列出我的规范"** — 显示所有规范及其状态
- **"执行用户身份验证规范中的任务 1.2"** — 运行特定任务
[查看更多示例 →](docs/PROMPTING-GUIDE.md)
## 🔧 MCP 客户端设置
<details>
<summary><strong>增强代码</strong></summary>
在 Augment 设置中配置：
```json
{
"mcpServers": {
"spec-workflow": {
"command": "npx",
"args": ["-y", "@madmatt112org/spec-workflow-mcp@latest", "/path/to/your/project"]
}
}
}
```
</details>
<details>
<summary><strong>Claude 代码 CLI</strong></summary>
将以下内容添加到您的 MCP 配置中：
```bash
claude mcp add spec-workflow npx @madmatt112org/spec-workflow-mcp@latest -- /path/to/your/project
```
**重要注意事项：**
- `-y` 标志绕过 npm 提示，以实现更流畅的安装
- `--` 分隔符确保路径被传递给 spec-workflow 脚本，而不是 npx
- 将 `/path/to/your/project` 替换为实际项目目录路径
**适用于 Windows 的替代方案（如果上述方法不起作用）：**
```bash
claude mcp add spec-workflow cmd.exe /c "npx @madmatt112org/spec-workflow-mcp@latest /path/to/your/project"
```
</details>
<details>
<summary><strong>Claude 桌面版</strong></summary>
将以下内容添加到 `claude_desktop_config.json` 中：
```json
{
"mcpServers": {
"spec-workflow": {
"command": "npx",
"args": ["-y", "@madmatt112org/spec-workflow-mcp@latest", "/path/to/your/project"]
}
}
}
```
> **重要：** 在启动 MCP 服务器之前，单独使用 `--dashboard` 运行仪表板。
</details>
<details>
<summary><strong>Cline/Claude 开发版</strong></summary>
将以下内容添加到您的 MCP 服务器配置中：
```json
{
"mcpServers": {
"spec-workflow": {
"command": "npx",
"args": ["-y", "@madmatt112org/spec-workflow-mcp@latest", "/path/to/your/project"]
}
}
}
```
</details>
<details>
<summary><strong>Continue IDE 扩展</strong></summary>
将以下内容添加到您的 Continue 配置中：
```json
{
"mcpServers": {
"spec-workflow": {
"command": "npx",
"args": ["-y", "@madmatt112org/spec-workflow-mcp@latest", "/path/to/your/project"]
}
}
}
```
</details>
<details>
<summary><strong>Cursor IDE</strong></summary>
将以下内容添加到您的 Cursor 设置（`settings.json`）中：
```json
{
"mcpServers": {
"spec-workflow": {
"command": "npx",
"args": ["-y", "@madmatt112org/spec-workflow-mcp@latest", "/path/to/your/project"]
}
}
}
```
</details>
<details>
<summary><strong>OpenCode</strong></summary>
将以下内容添加到您的 `opencode.json` 配置文件中：
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"spec-workflow": {
"type": "local",
"command": ["npx", "-y", "@madmatt112org/spec-workflow-mcp@latest", "/path/to/your/project"],
"enabled": true
}
}
}
```
</details>
<details>
<summary><strong>Windsurf</strong></summary>
将以下内容添加到您的 `~/.codeium/windsurf/mcp_config.json` 配置文件中：
```json
{
"mcpServers": {
"spec-workflow": {
"command": "npx",
"args": ["-y", "@madmatt112org/spec-workflow-mcp@latest", "/path/to/your/project"]
}
}
}
```
</details>
<details>
<summary><strong>Codex</strong></summary>
将以下内容添加到您的 `~/.codex/config.toml` 配置文件中：
```toml
[mcp_servers.spec-workflow]
command = "npx"
args = ["-y", "@madmatt112org/spec-workflow-mcp@latest", "/path/to/your/project"]
```
</details>
## 🐳 Docker 部署
在 Docker 容器中运行仪表板，以实现隔离部署：
```bash
# 使用 Docker Compose（推荐）
cd containers
docker-compose up --build
# 或使用 Docker CLI
docker build -f containers/Dockerfile -t spec-workflow-mcp .
docker run -p 5000:5000 -v "./workspace/.spec-workflow:/workspace/.spec-workflow:rw" spec-workflow-mcp
```
仪表板将在以下地址可访问：http://localhost:5000
[查看 Docker 设置指南 →](containers/README.md)
## 🔒 安全
Spec-Workflow MCP 包括适用于企业环境的企业级安全功能：
### ✅ 已实施的安全控制
| 功能 | 描述 |
|---------|-------------|
| **本地绑定** | 默认绑定到 `127.0.0.1`，防止网络暴露 |
| **速率限制** | 每个客户端每分钟 120 次请求，自动清理 |
| **审计日志** | 带有时间戳、操作者、操作和结果的结构化 JSON 日志 |
| **安全标头** | X-Content-Type-Options、X-Frame-Options、X-XSS-Protection、CSP、Referrer-Policy |
| **CORS 保护** | 默认情况下限制为本地主机源 |
| **Docker 强化** | 非 root 用户、只读文件系统、删除功能、资源限制 |
### ⚠️ 尚未实施
| 功能 | 解决方法 |
|---------|------------|
| **HTTPS/TLS** | 使用带有 TLS 证书的反向代理（nginx、Apache） |
| **用户身份验证** | 使用带有基本身份验证或 OAuth2 代理的反向代理进行 SSO |
### 用于外部/网络访问
如果您需要将仪表板暴露到 localhost 以外，我们建议：
1. **将仪表板保留在 localhost** (`127.0.0.1`)
2. **使用 nginx 或 Apache** 作为反向代理，配置：
- TLS/HTTPS 终止
- 基本身份验证或 OAuth2
3. **配置防火墙规则** 以限制访问
```nginx
# 示例 nginx 反向代理，带有身份验证
server {
listen 443 ssl;
server_name dashboard.example.com;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
auth_basic "Dashboard Access";
auth_basic_user_file /etc/nginx/.htpasswd;
location / {
proxy_pass http://127.0.0.1:5000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}
```
[查看 Docker 安全指南 →](containers/README.md#security-configuration)
## 🔒 沙箱环境
对于沙箱环境（例如，带有 `sandbox_mode=workspace-write` 的 Codex CLI），其中 `$HOME` 是只读的，请使用 `SPEC_WORKFLOW_HOME` 环境变量将全局状态文件重定向到可写位置：
```bash
SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @madmatt112org/spec-workflow-mcp@latest /workspace
```
[查看配置指南 →](docs/CONFIGURATION.md#environment-variables)
## ⚙️ 审查者配置
仪表板对抗性审查和任务审查子代理从 `.spec-workflow/adversarial-settings.json` 读取每个运行者的配置。本节涵盖 **runner/model** 键；同一个文件还包含由仪表板管理的键（`requiredPhases`、`customPreamble`、`reviewMethodology`、`responseMethodology`），详见 [docs/CONFIGURATION.md](docs/CONFIGURATION.md#adversarial-review-settings)。运行者配置使用 **分组的每个运行者形状**，带有传统的顶级后备：
```json
{
"adversarial": { "model": "claude-opus-4-7" },
"taskReview": { "model": "claude-haiku-4-5" },
"features": { "typecheck": true },
"model": "claude-sonnet-4-6",
"cli": "claude",
"cliArgs": ["--print", "--output-format", "stream-json", "--verbose"]
}
```
- `adversarial.model` / `taskReview.model` — 每个运行者的模型覆盖。分组形状自然地扩展为未来的每个运行者设置（例如 `cliArgs`），无需配置迁移。
- `model` — 传统顶级后备，在运行者的每个运行者覆盖不存在时使用。永久有效；没有废除时间表。
- `features.typecheck` — `review-task action: prepare` 运行的 `tsc --noEmit` 预计算的布尔开关。默认启用；设置为 `false` 以禁用。
- `cli` / `cliArgs` — 用于生成两个运行者的全局 CLI 命令和参数。暂不支持每个运行者的覆盖。
**优先级阶梯**（每个运行者）：每个运行者覆盖（`adversarial.model` / `taskReview.model`）> 传统顶级 `model` > 未定义（不传递 `--model` 标志；应用 CLI 默认值）。
**空字符串清除覆盖**: 设置 `adversarial.model: ""` 或 `taskReview.model: ""` 被视为“显式清除”——运行者回退到传统 `model`，或如果传统模型不存在，则回退到未定义。这是记录在案的禁用每个运行者覆盖的方法，而无需删除键。
### 重试行为
当从仪表板重试审查时，重试运行者重用 **初始运行调用的模型**，从先前的运行者作业中查找。这保持了审查的每次和重试尝试之间的遥测和计费一致性。暂不支持每次重试的模型覆盖。
**服务器重启后备**: 如果仪表板服务器在初始审查和重试之间重启，则先前的运行者作业已消失（作业存储在内存映射中，该映射在重启之间不保留）。重试处理程序回退到从当前设置中重新解析模型，并记录 `[spec-workflow] retry: prior job not found in runner, re-resolving model from settings` 每个进程一次。这是记录在案的降级行为；在 v1 中，不会跨重启保留作业。
只有 `model` 在重试之间固定；`cli` 和 `cliArgs` 始终反映当前设置，因此在初始运行和重试之间编辑 `cliArgs` 会导致重试使用编辑后的 `cliArgs`，同时仍使用初始运行的 `model`。
如果您在初始运行和重试之间升级 CLI 二进制或 `claude-cli` 包，并且初始运行的模型名称不再有效（已弃用、重命名），则重试将在生成的进程中失败，出现 CLI 的“未知模型”错误 — 通过清除先前的作业（触发新的初始运行，或重启仪表板服务器以清除内存映射）进行恢复。
## 📚 文档
- [配置指南](docs/CONFIGURATION.md) - 命令行选项、配置文件
- [用户指南](docs/USER-GUIDE.md) - 全面的使用示例
- [工作流流程](docs/WORKFLOW.md) - 开发工作流和最佳实践
- [自主使用](docs/AUTONOMOUS-USAGE.md) - 非交互式 / 无头操作
- [接口指南](docs/INTERFACES.md) - 仪表板和 VSCode 扩展详细信息
- [提示指南](docs/PROMPTING-GUIDE.md) - 高级提示示例
- [工具参考](docs/TOOLS-REFERENCE.md) - 完整的工具文档
- [开发](docs/DEVELOPMENT.md) - 贡献和开发设置
- [故障排除](docs/TROUBLESHOOTING.md) - 常见问题和解决方案
## 📁 项目结构
```
your-project/
.spec-workflow/
approvals/
archive/
spec-decomposition/
specs/
steering/
templates/
user-templates/
config.example.toml
```
## 🛠️ 开发
```bash
# 安装依赖
npm install
# 构建项目
npm run build
# 在开发模式下运行
npm run dev
```
[查看开发指南 →](docs/DEVELOPMENT.md)
## 📦 发布到 npm
该软件包通过手动分发的 GitHub Actions 工作流发布到 npm。运行之前会进行三个关卡的测试。
### 版本来源
`package.json` 的 `version` 是唯一的真相来源。没有自动增量。使用 `npm version`（推荐）或直接编辑 `package.json：
```bash
npm version patch # 3.0.0 → 3.0.1，也会创建 git 标签 v3.0.1
npm version minor # 3.0.0 → 3.1.0
npm version major # 3.0.0 → 4.0.0
```
`scripts/sync-plugin-version.js` 在版本号更新后，会同步 `.claude-plugin/*.json` 清单版本号。在提交版本号更新后，运行 `npm run sync:plugin-version` 以更新清单；CI 运行 `npm run check:plugin-version`，如果版本号漂移，则失败。
### 发布关卡
`Publish to npm` 工作流（`.github/workflows/npm-publish.yml`）按顺序运行三个作业 - 每个步骤都必须通过，发布作业才能运行：
1. **`test`** - 调用 `ci.yml`（类型检查、构建、插件版本同步检查、完整的 vitest 套件）。
2. **`preflight`**：
- **注册表唯一性**：如果 `package.json` 版本已经发布，则中止。
- **git 标签检查**：需要一个指向确切提交的 `v<version>` 标签。
3. **`publish`** - `npm publish --access public --tag <input>`.
### 发布步骤
```bash
# 1. 增量版本 + 创建匹配的 git 标签
npm version patch # 或 minor / major
# 2. 将提交和标签一起推送
git push origin main --follow-tags
# 3. 触发工作流
# GitHub → Actions → “发布到 npm” → “运行工作流”
# 标签输入：latest（或 beta / next 用于预发布路由）
```
`tag` 输入控制 npm 分发标签，而不是版本号。对于第一次谨慎发布，使用 `next` 分发，然后再进行推广：
```bash
npm dist-tag add @madmatt112org/spec-workflow-mcp@<version> latest
```
### 所需机密
在 `设置 → 机密和变量 → 操作` 中设置：
- `NPM_TOKEN` - 具有 `@madmatt112org/*` 读写权限的 npm 粒度访问令牌。必须为 npm 账户启用 2FA 发布。
### 常见故障模式
| 错误 | 原因 | 修复 |
|---|---|---|
| `Version X.Y.Z is already published` | 忘记增量 | `npm version patch` 然后重新分发 |
| `Expected git tag vX.Y.Z does not exist` | 缺少标签或未推送 | `git tag v<ver>` 然后 `git push origin v<ver>` |
| `Tag points at <sha> but workflow is running on <sha>` | 标签位于不同提交 | 移动标签 (`git tag -f v<ver>`) 或从标记的提交运行 |
| `403 Forbidden` 来自 `npm publish` 的消息 | 令牌缺乏作用域权限，或组织成员资格错误 | 重新生成令牌，作用域为 `@madmatt112org/*` |
| CI 中的 `check:plugin-version` 失败 | 清单版本漂移 | `npm run sync:plugin-version`，提交，然后推送 |
## 📄 许可证
GPL-3.0
## 致谢
最初从 [Pimzino/spec-workflow-mcp](https://github.com/Pimzino/spec-workflow-mcp) 在版本 `2.2.6` 处分叉而来。上游没有响应功能请求，因此此分叉以 GPL-3.0 许可证（与上游相同）独立推进。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器