使用说明

Spec-Kit MCP 服务器

MCP服务器，它使AI编码助手能够通过（该服务器）采用规格驱动的开发实践 GitHub Spec-Kit（可译为“GitHub规范工具包”或根据具体语境调整为更贴切的名称）工具包。

特性/特点

🎯 100% 规格套件覆盖全部10种工具，助力实现完全基于规范的开发
🚀 MCP协议为AI代理提供完整的JSON-RPC 2.0实现
⚡ 高性能使用Rust和Tokio构建，支持异步I/O
🔧 双重安装通过以下方式安装 cargo 或者 npx
🛡️ 类型安全带有验证功能的综合类型系统
📚 完整文档教程、示例和配置指南
🌐 支持多编辑器克劳德代码（此处可能为特定语境下的名称，直译可能不准确，若指具体软件或项目需具体情境判断）、Cursor、风帆冲浪（此处“Windsurf”若指软件或工具则应译为相应名称，若指运动则为风帆冲浪）、VS Code 及更多
🧪 准备就绪，可投入生产测试、记录并部署

快速入门

安装

（推荐使用）Via Cargo（货运渠道）

快速、可靠，支持离线工作：

cargo install spec-kit-mcp

优点：

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

通过 npm/npx

对于Node.js用户：

# Global installation
npm install -g @lsendel/spec-kit-mcp

# Or use with npx (downloads on first use)
npx @lsendel/spec-kit-mcp

优点：

✅ Node.js 用户熟悉
✅ 自动下载预编译的二进制文件
✅ npx 总是使用最新版本

先决条件

**Python 3.11+（或 Python 3.11及以上版本）**由GitHub规范工具包（spec-kit）要求
UV包管理器需要运行 spec-kit（请从 https://docs.astral.sh/uv/ 安装）
**GitHub Spec-Kit（可译为“GitHub规范工具包”或“GitHub规格工具集”，具体译名可根据上下文或产品特性微调）**无需单独安装——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代码进行配置

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": {}
    }
  }
}

优点：

✅ 启动速度最快（<100毫秒）
✅ 离线工作
✅ 最可靠
✅ 支持所有平台（macOS Intel/ARM，Linux）

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

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

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

优点：

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

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

验证配置

重启Claude代码 编辑配置文件后
测试MCP工具 在克劳德代码中：

List all available MCP tools

你应该看到列出了10个规格套件工具：

speckit_init 翻译为中文是“speckit 初始化”。
speckit_check 翻译为中文是“检查speckit（或特定功能/设置）”。不过，具体翻译可能需要根据上下文来确定“speckit”在这里的具体含义，因为“speckit”本身不是一个通用的英文单词，可能是某个特定软件、系统或功能的名称。如果“speckit”是某个特定领域的术语或专有名词，那么翻译时可能需要保留其原样或根据具体情况进行适当调整
“speckit_constitution” 可以翻译为“Speckit 宪章”或“Speckit 宪法”，具体取决于上下文和该词在特定语境中的含义。如果“Speckit”是一个特定组织、项目或系统的名称，那么“speckit_constitution”很可能指的是该组织、项目或系统的指导原则或基本规则
speckit_specify 翻译为中文是“指定speckit（的参数或选项）”。不过，这里的“speckit”可能是一个特定领域或软件中的术语，没有具体的上下文可能难以给出更准确的翻译。如果“speckit”是某个特定软件或工具的名称，那么“speckit_specify”可能指的是在该软件或工具中指定某些参数、选项或配置的功能。在没有具体上下文的情况下，这个翻译是一个较为通用的解释
speckit_plan 可以翻译为“规格计划”或“配置计划”，具体取决于上下文中的使用场景。如果是指对产品或项目的规格进行规划，那么“规格计划”更为贴切；如果是指对配置或设置进行规划，则“配置计划”更为合适
speckit_tasks（可译为“Speckit任务”或根据具体上下文意译为更贴切的名称，如“小斑点任务”等，但通常保留原样以指代特定系统或框架中的任务集）
speckit_implement（可译为“speckit的实现”或根据具体上下文调整为更贴切的表述）
speckit_clarify 可以翻译为“澄清speckit（或具体指某事物/情况）”。不过，这个翻译比较直译，具体翻译可能需要根据上下文来调整，以更准确地表达原句的含义。如果“speckit”是一个特定的术语或品牌名，那么可能需要保留原样或根据具体情况做适当调整
speckit_analyze 翻译为中文是“speckit分析”。不过，具体翻译可能需要根据“speckit”在上下文中的具体含义来调整，因为“speckit”本身可能是一个特定领域或应用中的术语。如果“speckit”没有特定含义，那么“speckit分析”就是较为通用的翻译
speckit检查清单

尝试一个简单的命令：

Use speckit_check to verify my development environment

故障排除配置

问题重启后工具未出现

解决方案:

检查配置文件位置： 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: command not found （方法2）

解决方案：

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

需要帮助其他编辑吗？ 查看完整配置指南适用于Cursor、Windsurf、VS Code等更多工具。

📚 文档

快速链接

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

学习资源

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

构建API吗？ 退房：

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

与团队合作吗？

可用工具

MCP服务器为完整工作流提供了10个规范套件工具：

1. `speckit_init`

初始化一个具有适当结构的新spec-kit项目。

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

2. `speckit_constitution`

制定项目管理原则和开发标准。

{
  "principles": "Simplicity, Performance, Security",
  "constraints": "Must support Python 3.11+",
  "output_path": "./speckit.constitution"
}

3. `speckit_specify`

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

{
  "requirements": "User authentication system with OAuth2 support",
  "user_stories": "As a user, I want to login with 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": "medium",
  "output_path": "./speckit.tasks"
}

6. `speckit_implement`

根据任务清单执行实施。

{
  "task_file": "./speckit.tasks",
  "context": "Using Rust with async/await",
  "output_dir": "./src"
}

7. `speckit_clarify`

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

{
  "spec_file": "./speckit.specify",
  "questions": "How should we handle edge cases?"
}

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: Initialize a new spec-kit project called "user-auth"

Claude: [Uses speckit_init tool]
✓ Project initialized at ./user-auth

User: Create a constitution focusing on security and simplicity

Claude: [Uses speckit_constitution tool]
✓ Constitution created at ./speckit.constitution

User: Specify requirements for OAuth2 authentication

Claude: [Uses speckit_specify tool]
✓ Specification created at ./speckit.specify

User: Create a technical plan using Rust and OAuth2 libraries

Claude: [Uses speckit_plan tool]
✓ Technical plan created at ./speckit.plan

User: Generate detailed tasks

Claude: [Uses speckit_tasks tool]
✓ Task list created at ./speckit.tasks
  Found 15 actionable tasks

建筑

AI Agent (Claude Code, Cursor, etc.)
    ↓
MCP Protocol (JSON-RPC 2.0 over stdio)
    ↓
Spec-Kit MCP Server (Rust/Tokio)
    ↓
Tool Registry & Dispatcher
    ↓
Spec-Kit CLI Integration Layer
    ↓
Spec-Kit Python CLI (subprocess)
    ↓
File System (speckit.* artifacts)

发展

从源代码构建

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

运行测试

cargo test

运行服务器

# With default settings
cargo run

# With custom log level
cargo run -- --log-level debug

# With custom CLI path
cargo run -- --cli-path /path/to/specify

# With custom timeout
cargo run -- --timeout 600

项目结构

spec-kit-mcp/
├── src/
│   ├── main.rs              # Binary entry point
│   ├── lib.rs               # Library root
│   ├── mcp/                 # MCP protocol implementation
│   │   ├── types.rs         # JSON-RPC types
│   │   ├── protocol.rs      # Protocol handler
│   │   ├── transport.rs     # Stdio transport
│   │   └── server.rs        # MCP server
│   ├── speckit/             # Spec-kit CLI integration
│   │   ├── cli.rs           # Command execution
│   │   └── errors.rs        # Error types
│   └── tools/               # MCP tools
│       ├── mod.rs           # Tool registry
│       ├── init.rs          # speckit_init tool
│       ├── constitution.rs  # speckit_constitution tool
│       ├── specify.rs       # speckit_specify tool
│       ├── plan.rs          # speckit_plan tool
│       └── tasks.rs         # speckit_tasks tool
├── Cargo.toml               # Rust package manifest
└── README.md                # This file

贡献；做出贡献

欢迎投稿！请参阅 CONTRIBUTING.md 翻译为中文是：“贡献指南.md” 或 “贡献规范.md”。这个文件通常用于说明如何向某个项目或组织做出贡献，包括提交代码、报告问题、参与讨论等相关的指南或规范作为指南。

开发工作流程

为仓库创建分支
创建一个特性分支： git checkout -b feature/my-feature
做出你的更改
运行测试： cargo test
运行 clippy： cargo clippy
格式代码： cargo fmt
使用规范提交进行提交： git commit -m "feat: add new feature"
推送并创建一个拉取请求

路线图

当前版本（0.1.0）

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

未来版本

v0.2.0

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

版本0.3.0

[ ] 通过服务器发送事件（SSE）远程管理控制协议（MCP）
[ ] 用于项目可视化的Web用户界面仪表板
[ ] 模板市场集成
[ ] 团队协作功能（共享章程）
[ ] 指标与分析仪表板
[ ] 自定义工具的插件系统

演出

冷启动小于500毫秒
工具调用<200毫秒（不包括spec-kit CLI执行时间）
内存使用量<50MB 基线
并发请求10多个

兼容性

AI编码助手

✅ 克劳德代码
✅ 光标
✅ GitHub Copilot（支持MCP）
✅ 任何兼容MCP的客户端

平台

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

故障排除

未找到Spec-Kit CLI

Error: spec-kit CLI not found!

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

# Check if uv is installed
uv --version

# If not installed, install uv (macOS/Linux)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or using pip
pip install uv

# Test spec-kit access
uvx --from git+https://github.com/github/spec-kit.git specify check

注规范套件CLI（spec-kit CLI）不作为一个独立包提供。MCP服务器使用 uvx 直接从GitHub运行它。

Python版本过旧

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

# Check version
python3 --version

# Install Python 3.11+ (macOS with Homebrew)
brew install python@3.11

权限被拒绝

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

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

常见问题解答（FAQ）

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

问：我可以不用Claude Code就使用这个吗？ A: 是的！它与任何兼容MCP的人工智能编码助手都能配合使用。

问：这个功能在离线状态下能使用吗？ A: 是的，如果是通过包管理器安装的话。npx 版本需要网络来进行初始下载。

问：这与直接使用规格套件相比如何？ A: 这台MCP服务器使AI代理能够自动使用规范套件，从而简化了工作流程。

许可证

该项目采用双重许可，具体如下：

MIT 许可证（许可协议-MIT（麻省理工学院许可协议）或者 http://opensource.org/licenses/MIT
Apache许可证2.0（许可证-Apache（或：Apache许可证）或 http://www.apache.org/licenses/LICENSE-2.0）

您可以选择任一许可用于您的使用。

致谢

GitHub Spec-Kit（可译为“GitHub规范工具包”或“GitHub规格工具集”） - 基于规范的底层开发工具包
模型上下文协议 - 促进人工智能工具集成的协议
Anthropic Claude（注：此处“Anthropic”可能是指与“Anthropic”公司相关的一个模型或项目名，但直接翻译为“人类（的）克劳德”并不准确，因为“Anthropic”在此上下文中可能是一个特定名称或品牌，所以直接保留原名） - 促成这种整合的AI助手
Rust 社区 - 提供优秀的异步工具（Tokio、Serde 等）

链接

**Crates.io（注：这通常指的是一个用于发布和管理Rust语言包的网站，直接翻译为“Rust包仓库.io”或保持原名以体现其特定含义）**https://crates.io/crates/spec-kit-mcp 的中文翻译可以是：“https://crates.io 上的 spec-kit-mcp 库页面”。不过，通常我们直接保留网址的原样，因为网址本身在中文语境下也是通用的，只是在解释或说明时可能会加上一些描述性文字。所以，如果只是单纯翻译这个网址，可以保持原样；如果是在说明中提及，可以加上“（库页面）”之类的描述
**Docs.rs（注：这通常是一个用于托管Rust语言文档的平台名称，直接翻译可能无法完全传达其特定含义，但在此处按字面意思翻译为“文档点R点S”并不合适，实际使用时可保持原样或根据上下文解释为“Rust文档托管平台Docs.rs”）**https://docs.rs/spec-kit-mcp（该网址可译为：“Rust文档库中的spec-kit-mcp页面”，但通常网址本身不直接翻译，这里仅描述其内容）
GitHubhttps://github.com/yourusername/spec-kit-mcp（注：此网址为示例，实际用户名和项目名可能不同，翻译时保持网址原样）
问题https://github.com/yourusername/spec-kit-mcp/issues 的中文翻译可以是：“https://github.com/你的用户名/spec-kit-mcp/issues（问题页面）”。不过，为了更自然地表达，我们通常会说：“这是 GitHub 上你的用户名（替换为实际用户名）的 spec-kit-mcp 项目的 Issues 页面。” 但直接翻译链接部分，保持原样加上中文解释即可，如上所示
**Spec-Kit 翻译成中文是“规格套件”或“配置工具包”**https://github.com/github/spec-kit（译文：https://github.com/github/spec-kit，注：该网址本身为英文，无需翻译，但在此上下文中，若需说明其内容或用途，可译为“GitHub上的spec-kit仓库”）

使用说明

Spec-Kit MCP 服务器

特性/特点

快速入门

安装

（推荐使用）Via Cargo（货运渠道）

通过 npm/npx

先决条件

使用Claude代码进行配置

方法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

版本0.3.0

演出

兼容性

AI编码助手

平台

故障排除

未找到Spec-Kit CLI

Python版本过旧

权限被拒绝

常见问题解答（FAQ）

许可证

致谢

链接

相关 MCP

自主代理操作系统

规范工作流MCP服务器

规范驱动开发服务器

市场数据分析工具

规范驱动开发服务器

AI辅助编程规划器

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`