规格套件MCP

Name: 规格套件MCP
Author: lsendel

作者：lsendel7 星标更新：2025-10-26

安装使用来源：spider==github.com

项目介绍

技术文档摘要

Spec-Kit MCP 服务器

通过 GitHub Spec-Kit 工具包，使 AI 编码助手能够使用基于规范的开发实践的 MCP 服务器。

特性

🎯 100% Spec-Kit 覆盖率: 完整的基于规范的开发所需的全部 10 个工具
🚀 MCP 协议: 完整实现 JSON-RPC 2.0 协议用于 AI 代理
⚡ 高性能: 使用 Rust 和 Tokio 实现异步 I/O
🔧 双重安装方式: 通过 cargo 或 npx 安装
🛡️ 类型安全: 全面的类型系统并带有验证
📚 全面文档: 教程、示例和配置指南
🌐 多编辑器支持: Claude Code、Cursor、Windsurf、VS Code 等
🧪 生产就绪: 测试、记录和部署

快速开始

安装

通过 Cargo（推荐）

快速、可靠且离线可用：

cargo install spec-kit-mcp

优点：

✅ 启动最快
✅ 离线可用
✅ 最可靠
✅ 支持全平台（macOS Intel/ARM，Linux）

通过 npm/npx

适用于 Node.js 用户：

# 全局安装
npm install -g @lsendel/spec-kit-mcp

# 或使用 npx（首次使用时下载）
npx @lsendel/spec-kit-mcp

优点：

✅ 对 Node.js 用户熟悉
✅ 自动下载预构建二进制文件
✅ npx 始终使用最新版本

先决条件

Python 3.11+: 由 GitHub spec-kit 所需
uv 包管理器: 运行 spec-kit 所需（从 https://docs.astral.sh/uv/ 安装）
GitHub Spec-Kit: 不需要单独安装 - MCP 服务器使用 uvx 直接运行 spec-kit
Node.js 18+: 如果使用 npx 安装方法
Git: 用于版本控制操作

注意: spec-kit CLI 不在 PyPI 上提供。MCP 服务器通过 uvx --from git+https://github.com/github/spec-kit.git 自动运行它。

使用 Claude Code 配置

Claude Code 支持两种配置 MCP 服务器的方法：

方法 1: 使用 Cargo 二进制文件（推荐）

首先通过 cargo 安装：

cargo install spec-kit-mcp

然后配置 ~/.config/claude-code/mcp.json：

{
  "mcpServers": {
    "spec-kit": {
      "command": "spec-kit-mcp",
      "args": [],
      "env": {}
    }
  }
}

优点：

✅ 启动最快（<100ms）
✅ 离线可用
✅ 最可靠
✅ 支持所有平台（macOS Intel/ARM，Linux）

方法 2: 使用 npx（无需安装）

创建或编辑 ~/.config/claude-code/mcp.json：

{
  "mcpServers": {
    "spec-kit": {
      "command": "npx",
      "args": ["-y", "@lsendel/spec-kit-mcp"],
      "env": {}
    }
  }
}

优点：

✅ 无需安装
✅ 始终使用最新版本
✅ 适合尝试使用

注意: 首次运行可能较慢，因为它会下载二进制文件。

验证配置

在编辑配置文件后重启 Claude Code
在 Claude Code 中测试 MCP 工具：

列出所有可用的 MCP 工具

你应该看到列出的 10 个 spec-kit 工具：

speckit_init
speckit_check
speckit_constitution
speckit_specify
speckit_plan
speckit_tasks
speckit_implement
speckit_clarify
speckit_analyze
speckit_checklist

尝试一个简单的命令：

使用 speckit_check 验证我的开发环境

配置故障排除

问题: 重启后工具未出现

解决方案：

检查配置文件位置：cat ~/.config/claude-code/mcp.json
验证 JSON 语法：cat ~/.config/claude-code/mcp.json | jq
查看 Claude Code 日志：~/.config/claude-code/logs/
对于 npx 方法，确保 Node.js 已安装：node --version
对于二进制方法，验证安装：which spec-kit-mcp

问题: spec-kit-mcp: 命令未找到（方法 2）

解决方案：

使用方法 1（npx），或者
将 npm 全局 bin 添加到 PATH：export PATH="$PATH:$(npm config get prefix)/bin"

需要其他编辑器的帮助吗？ 请参阅完整的配置指南，包括 Cursor、Windsurf、VS Code 等。

📚 文档

快速链接

📖 全面教程 - 适用于所有技能水平的分步指南
💡 示例 - 现实项目示例
⚙️ 配置指南 - 不同 AI 助手的设置
🚀 使用指南 - 详细的使用文档

学习资源

新接触 Spec-Kit？ 从这里开始：

构建 API？ 查看：

教程 2: 构建 REST API
博客 API 示例 - 生产就绪的 API 示例

团队协作？

可用工具

MCP 服务器提供了 10 个 spec-kit 工具以完成整个工作流程：

1. `speckit_init`

初始化一个新的 spec-kit 项目，具有正确的结构。

{
  "project_name": "my-project",
  "project_path": "."
}

2. `speckit_constitution`

创建项目治理原则和技术标准。

{
  "principles": "简洁性，性能，安全性",
  "constraints": "必须支持 Python 3.11+",
  "output_path": "./speckit.constitution"
}

3. `speckit_specify`

定义需求和用户故事（“是什么”）。

{
  "requirements": "支持 OAuth2 的用户认证系统",
  "user_stories": "作为用户，我希望可以使用 Google 登录...",
  "output_path": "./speckit.specify"
}

4. `speckit_plan`

创建技术实施计划（“如何做”）。

{
  "spec_file": "./speckit.specify",
  "tech_stack": "Rust + Tokio",
  "output_path": "./speckit.plan"
}

5. `speckit_tasks`

根据计划生成可执行的任务列表。

{
  "plan_file": "./speckit.plan",
  "breakdown_level": "中等",
  "output_path": "./speckit.tasks"
}

6. `speckit_implement`

根据任务列表执行实施。

{
  "task_file": "./speckit.tasks",
  "context": "使用 Rust 和 async/await",
  "output_dir": "./src"
}

7. `speckit_clarify`

请求对模糊的需求或规范进行澄清。

{
  "spec_file": "./speckit.specify",
  "questions": "我们应该如何处理边缘情况？"
}

8. `speckit_analyze`

分析代码的质量、合规性和技术债务。

{
  "target_path": "./src",
  "check_constitution": true,
  "output_format": "markdown"
}

9. `speckit_check`

验证所需工具是否已安装以进行 spec-kit 开发。

{
  "check_speckit": true,
  "check_git": true,
  "check_ai_tools": true
}

10. `speckit_checklist`

生成审查检查清单以验证实施的完整性。

{
  "spec_file": "./speckit.specify",
  "task_file": "./speckit.tasks",
  "output_path": "./checklist.md"
}

查看所有工具的实际操作: 请参阅示例目录中的完整工作流程

使用示例

这是一个使用 Claude Code 的完整工作流程示例：

用户: 初始化一个新的名为 "user-auth" 的 spec-kit 项目

Claude: [使用 speckit_init 工具]
✓ 项目已在 ./user-auth 初始化

用户: 创建一个专注于安全性和简洁性的宪法

Claude: [使用 speckit_constitution 工具]
✓ 宪法已在 ./speckit.constitution 创建

用户: 规定 OAuth2 认证的需求

Claude: [使用 speckit_specify 工具]
✓ 规范已在 ./speckit.specify 创建

用户: 使用 Rust 和 OAuth2 库创建技术计划

Claude: [使用 speckit_plan 工具]
✓ 技术计划已在 ./speckit.plan 创建

用户: 生成详细的任务列表

Claude: [使用 speckit_tasks 工具]
✓ 任务列表已在 ./speckit.tasks 创建
  发现了 15 个可执行任务

架构

AI 代理（Claude Code、Cursor 等）
    ↓
MCP 协议（通过 stdio 的 JSON-RPC 2.0）
    ↓
Spec-Kit MCP 服务器（Rust/Tokio）
    ↓
工具注册表及调度器
    ↓
Spec-Kit CLI 集成层
    ↓
Spec-Kit Python CLI（子进程）
    ↓
文件系统（speckit.* 文件）

开发

从源代码构建

git clone https://github.com/yourusername/spec-kit-mcp.git
cd spec-kit-mcp
cargo build --release

运行测试

cargo test

运行服务器

# 使用默认设置
cargo run

# 使用自定义日志级别
cargo run -- --log-level debug

# 使用自定义 CLI 路径
cargo run -- --cli-path /path/to/specify

# 使用自定义超时时间
cargo run -- --timeout 600

项目结构

spec-kit-mcp/
├── src/
│   ├── main.rs              # 二进制入口点
│   ├── lib.rs               # 库根目录
│   ├── mcp/                 # MCP 协议实现
│   │   ├── types.rs         # JSON-RPC 类型
│   │   ├── protocol.rs      # 协议处理器
│   │   ├── transport.rs     # Stdio 传输
│   │   └── server.rs        # MCP 服务器
│   ├── speckit/             # Spec-kit CLI 集成
│   │   ├── cli.rs           # 命令执行
│   │   └── errors.rs        # 错误类型
│   └── tools/               # MCP 工具
│       ├── mod.rs           # 工具注册表
│       ├── init.rs          # speckit_init 工具
│       ├── constitution.rs  # speckit_constitution 工具
│       ├── specify.rs       # speckit_specify 工具
│       ├── plan.rs          # speckit_plan 工具
│       └── tasks.rs         # speckit_tasks 工具
├── Cargo.toml               # Rust 包清单
└── README.md                # 本文件

贡献

欢迎贡献！请参阅 CONTRIBUTING.md 获取指南。

开发工作流

分叉仓库
创建功能分支：git checkout -b feature/my-feature
进行更改
运行测试：cargo test
运行 clippy：cargo clippy
格式化代码：cargo fmt
使用常规提交：git commit -m "feat: 添加新功能"
推送并创建拉取请求

发展路线图

当前版本（0.1.0）

✅ 实现了全部 10 个 spec-kit 工具（100% 覆盖率）
✅ 支持 MCP 协议（JSON-RPC 2.0）
✅ 双重分发（cargo + npx）
✅ 全面的错误处理
✅ 完整的教程和示例
✅ 主要编辑器的配置指南
✅ 发布到 crates.io 和 npm

未来版本

v0.2.0

增强工具参数和验证
配置文件支持（.speckit-mcp.toml）
常见项目类型的模板系统
性能优化和缓存
Windows 平台支持
基于 Web 的工具输出可视化

v0.3.0

通过 Server-Sent Events (SSE) 远程 MCP
项目可视化的 Web UI 控制面板
模板市场集成
团队协作功能（共享宪法）
指标和分析控制面板
插件系统以支持自定义工具

性能

冷启动: <500ms
工具调用: <200ms（不包括 spec-kit CLI 执行）
内存使用: <50MB 基线
并发请求: 10+

兼容性

AI 编码助手

✅ Claude Code
✅ Cursor
✅ GitHub Copilot（带 MCP 支持）
✅ 任何 MCP 兼容客户端

平台

✅ macOS（Intel 和 ARM）
✅ Linux（x86_64）
⏳ Windows（计划中）

故障排除

Spec-Kit CLI 未找到

错误: spec-kit CLI 未找到！

解决方案: 确保已安装 uv 包管理器：

# 检查是否已安装 uv
uv --version

# 如果未安装，安装 uv（macOS/Linux）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 或使用 pip
pip install uv

# 测试 spec-kit 访问
uvx --from git+https://github.com/github/spec-kit.git specify check

注意: spec-kit CLI 不作为独立包提供。MCP 服务器直接从 GitHub 运行它。

Python 版本太旧

解决方案: 升级到 Python 3.11 或更高版本：

# 检查版本
python3 --version

# 安装 Python 3.11+（macOS 使用 Homebrew）
brew install python@3.11

权限被拒绝

解决方案: 确保二进制文件是可执行的：

chmod +x $(which spec-kit-mcp)

常见问题

Q: 我需要单独安装 spec-kit 吗？ A: 是的，MCP 服务器需要 spec-kit Python CLI 已安装。

Q: 我可以不使用 Claude Code 就使用这个吗？ A: 可以！它可以与任何 MCP 兼容的 AI 编码助手一起使用。

Q: 这可以在离线状态下使用吗？ A: 是的，如果通过 cargo 安装。npx 版本需要互联网连接进行初始下载。

Q: 这与直接使用 spec-kit 有什么不同？ A: 这个 MCP 服务器允许 AI 代理自动使用 spec-kit，简化了工作流程。

许可证

此项目采用双重许可：

MIT 许可证（LICENSE-MIT 或 http://opensource.org/licenses/MIT）
Apache 许可证 2.0（LICENSE-APACHE 或 http://www.apache.org/licenses/LICENSE-2.0）

你可以选择其中任何一个许可证来使用。

规格套件MCP

项目介绍

技术文档摘要

Spec-Kit MCP 服务器

特性

快速开始

安装

通过 Cargo（推荐）

通过 npm/npx

先决条件

使用 Claude Code 配置

方法 1: 使用 Cargo 二进制文件（推荐）

方法 2: 使用 npx（无需安装）

验证配置

配置故障排除

📚 文档

快速链接

学习资源

可用工具

1. speckit_init

2. speckit_constitution

3. speckit_specify

4. speckit_plan

5. speckit_tasks

6. speckit_implement

7. speckit_clarify

8. speckit_analyze

9. speckit_check

10. speckit_checklist

使用示例

架构

开发

从源代码构建

运行测试

运行服务器

项目结构

贡献

开发工作流

发展路线图

当前版本（0.1.0）

未来版本

v0.2.0

v0.3.0

性能

兼容性

AI 编码助手

平台

故障排除

Spec-Kit CLI 未找到

Python 版本太旧

权限被拒绝

常见问题

许可证

1. `speckit_init`

2. `speckit_constitution`

3. `speckit_specify`

4. `speckit_plan`

5. `speckit_tasks`

6. `speckit_implement`

7. `speckit_clarify`

8. `speckit_analyze`

9. `speckit_check`

10. `speckit_checklist`