Speckit MCP Server

---

📖 目录

• 特点
• 安装
  • NPX 方式（推荐）
  • PIP 方式
• 快速开始
• 可用工具
• 项目结构
• 使用示例
• 故障排查
• NPX vs PIP 对比
• 开发者指南
• 更多资源

---

✨ 特点

• 🚀 自动化工作流 - AI 自动处理依赖安装、项目初始化和完整开发流程
• 📋 标准化流程 - 严格遵循 spec-kit 的标准目录结构和工作流
• 🤖 AI 驱动 - 工具只提供指令，由 AI 根据上下文智能执行
• 🎯 简洁高效 - 避免长时间运行的脚本，保持流畅体验
• ⚡ 零配置安装 - 使用 NPX 方式，无需预先安装

---

📦 安装

🌟 方式一：NPX 安装（推荐，零配置）

无需任何预先安装，直接配置 Cursor 即可自动下载运行！

1. 配置 Cursor

编辑 MCP 配置文件：

• macOS: ~/.cursor/mcp.json
• Linux: ~/.config/cursor/mcp.json
• Windows: %APPDATA%\Cursor\mcp.json

添加以下配置：

{
  "mcpServers": {
    "speckit": {
      "command": "npx",
      "args": ["-y", "speckit-mcp-x@latest"]
    }
  }
}

2. 重启 Cursor

完全退出并重新启动 Cursor IDE。首次启动时会自动下载包（约 2-5 秒）。

✅ 优点

• ✨ 真正的一键安装 - 无需打开终端，无需手动命令
• 🔄 自动更新 - 始终使用最新版本（@latest）
• 🛡️ 零依赖烦恼 - 自动处理 Python 依赖
• ⚡ 按需下载 - 首次启动自动下载，后续使用缓存

---

方式二：PIP 安装（传统方式）

适合需要离线使用或自定义 Python 环境的用户。

1. 安装 Python 包

pip install speckit-mcp-x

2. 配置 Cursor

{
  "mcpServers": {
    "speckit": {
      "command": "python3",
      "args": ["-m", "speckit_mcp.server"]
    }
  }
}

3. 重启 Cursor

---

🚀 快速开始

验证安装

在 Cursor 中向 AI 说：

检查 speckit 安装状态

自动化创建项目

直接描述需求，AI 会自动执行完整流程：

用 speckit 创建一个在线教育平台，包括：
- 用户认证和管理
- 课程管理
- 视频播放
- 学习进度跟踪
- 支付功能

使用 Next.js + TypeScript + PostgreSQL

AI 会自动：

1. 检查并安装依赖（uv、specify CLI）
2. 初始化工作空间
3. 执行 constitution（项目章程）
4. 执行 specify（技术规范）
5. 执行 plan（实施计划）
6. 执行 tasks（任务分解）
7. 🛑 自动暂停，询问用户是否继续
8. 用户确认后执行 implement（代码实现）

⚠️ 重要：检查点机制

在 tasks 生成完成后，系统会自动暂停并询问用户：

Tasks have been generated. Please review:
- Constitution (memory/constitution.md)
- Specifications (specs/[feature]/spec.md)
- Plan (specs/[feature]/plan.md)
- Tasks (specs/[feature]/tasks.md)

Would you like to:
1. ✅ Proceed with implementation
2. 📝 Refine the plan or tasks
3. 🔄 Make other adjustments

你可以：

• 查看文档摘要：查看生成的文档摘要
• 继续实施：继续实施 或 开始 implement
• 修改文档：修改 plan，增加XXX功能
• 重新生成：重新生成 tasks

分步执行

也可以单独执行某个步骤：

执行 speckit 的 constitution 步骤

---

🛠️ 可用工具

自动化工具

工具	说明
speckit_auto_setup	自动检查并安装所有依赖
speckit_execute_command	读取并返回特定命令的指令（⚠️ tasks 后自动暂停）
speckit_full_workflow	提供完整工作流的步骤指南（包含检查点）
speckit_review_documents	生成文档摘要，帮助用户在检查点决策

基础工具

工具	说明
check_speckit_status	检查安装状态
install_speckit	安装 Speckit CLI
speckit_init	初始化工作空间
speckit_help	获取 CLI 帮助

命令管理

工具	说明
speckit_list_commands	列出所有可用命令
speckit_read_command	读取命令指令
speckit_run_script	执行 bash 脚本

文件管理

工具	说明
speckit_status	查看工作空间状态
speckit_list_files	列出所有文件
speckit_read_file	读取文件内容
speckit_write_file	写入文件内容

---

📁 目录结构

初始化后会创建标准的 spec-kit 目录结构：

your-project/
├── .specify/
│   ├── memory/
│   │   ├── constitution.md      # 项目章程
│   │   └── ...
│   ├── scripts/
│   │   └── bash/               # 辅助脚本
│   └── templates/              # 文档模板
├── .cursor/
│   └── commands/               # Cursor slash commands
│       ├── speckit.constitution.md
│       ├── speckit.specify.md
│       ├── speckit.plan.md
│       ├── speckit.tasks.md
│       └── speckit.implement.md
└── specs/
    └── [feature-name]/         # 功能规范目录
        ├── spec.md             # 规范文档
        ├── plan.md             # 实施计划
        └── tasks.md            # 任务清单

---

💡 使用示例

示例 1：查看项目状态

检查 speckit 项目状态

示例 2：查看可用命令

列出所有 speckit 命令

示例 3：读取特定文件

显示 constitution.md 的内容

示例 4：修改项目章程

帮我修改 constitution.md，添加代码审查流程的要求

---

🔧 故障排查

NPX 方式常见问题

问题：首次启动很慢

原因：NPX 正在下载包（仅首次）

解决方案：等待 2-5 秒，后续启动会使用缓存

问题：提示 Python 不存在

解决方案：

# macOS
brew install python@3.11

# Ubuntu/Debian
sudo apt install python3.11

# Windows
# 访问 https://www.python.org/downloads/

问题：提示 mcp 包未安装

解决方案：包装器会自动安装，如果失败，手动安装：

pip3 install mcp>=0.9.0

---

PIP 方式常见问题

Cursor 无法识别 Speckit

解决方案：

1. 确认已完全重启 Cursor（完全退出后重新打开）
2. 检查 ~/.cursor/mcp.json 配置语法是否正确
3. 验证 Python 3.10+ 已安装：python3 --version
4. 确认包已安装：pip list | grep speckit-mcp-x

找不到 slash commands

解决方案： 确认已运行初始化：

初始化 speckit 工作空间

然后检查 .cursor/commands/ 目录是否存在。

---

Windows 专项问题 (v3.1.0+ 已修复)

问题：Windows 上安装 speckit 遇到权限错误

错误信息：

error: failed to remove directory: Access is denied. (os error 5)

解决方案（v3.1.0 已自动修复）：

• ✅ 自动检测已安装：避免重复安装导致的权限冲突
• ✅ 自动添加 --force：Windows 上自动使用强制安装
• ✅ 友好错误提示：如果仍失败，会显示具体解决步骤

手动解决方法（如果自动修复失败）：

1. 关闭所有 Python/uv 相关进程
2. 以管理员身份运行 Cursor
3. 或手动运行：uv tool install specify-cli --from git+https://github.com/github/spec-kit.git --force

Windows 快速测试

验证 v3.1.0 修复是否生效：

# 1. 清理旧安装（可选）
uv tool uninstall specify-cli

# 2. 在 Cursor 中测试
检查 speckit 安装状态
安装 speckit

# 预期: ✅ 无权限错误，自动安装成功

Windows 完全兼容特性

特性	支持状态	说明
Python 检测	✅	自动检测 python, py 命令
命令检测	✅	使用 where 替代 which
Bash 脚本	✅	自动检测 Git Bash/WSL
UV Tool Install	✅ v3.1.0+	自动处理权限问题
路径支持	✅	完全支持 Windows 路径

详细 Windows 支持文档: 参见 speckit-mcp/WINDOWS-SUPPORT.md

---

📊 NPX vs PIP 对比

特性	NPX 方式	PIP 方式
安装步骤	1 步（配置）	2 步（安装+配置）
首次启动	自动下载（2-5秒）	立即运行
更新方式	自动（@latest）	手动 pip upgrade
技术门槛	零门槛	需懂终端命令
离线使用	✅ 首次下载后	✅ 安装后即可
推荐场景	大多数用户	开发者/离线环境

---

🔧 开发者指南

项目结构

speckit-mcp-x/
├── bin/
│   └── speckit-mcp-x.js        # Node.js 包装器（NPX 入口点）
├── python/
│   └── speckit_mcp/
│       ├── __init__.py
│       ├── __main__.py         # 支持 python -m 运行
│       └── server.py           # MCP Server 主程序
├── package.json                # NPM 包配置
├── pyproject.toml              # Python 包配置
├── README.md                   # 本文档
└── CHANGELOG.md                # 变更日志

本地开发

# 克隆仓库
git clone https://github.com/ElliotLion-ing/Speckit-mcp-x.git
cd speckit-mcp-x

# 测试 Node.js 包装器
node bin/speckit-mcp-x.js

# 本地打包测试
npm pack
npm install -g ./speckit-mcp-x-2.1.0.tgz
speckit-mcp-x

# 清理
npm uninstall -g speckit-mcp-x

发布到 NPM

🚀 一键发布（使用脚本，推荐）

项目提供了两个自动化脚本简化发布流程：

首次发布或重新发布当前版本：

./publish.sh

更新版本并发布：

./update.sh

update.sh 会自动：

• 更新 package.json 和 pyproject.toml 版本号
• 更新 CHANGELOG.md
• Git 提交并打标签
• 发布到 NPM

详见 SCRIPTS-GUIDE.md 了解更多。

---

手动发布

首次发布：

# 1. 清理临时文件
find . -name __pycache__ -type d -exec rm -rf {} + 2>/dev/null || true

# 2. 登录 NPM
npm login

# 3. 验证包内容
npm pack --dry-run

# 4. 发布
npm publish

# 5. 验证
npm info speckit-mcp-x
npx speckit-mcp-x@latest

更新版本：

# 自动更新版本号
npm version patch   # 2.1.0 -> 2.1.1 (bug 修复)
npm version minor   # 2.1.0 -> 2.2.0 (新功能)
npm version major   # 2.1.0 -> 3.0.0 (破坏性更新)

# 或手动编辑：
# - package.json: "version": "2.1.1"
# - pyproject.toml: version = "2.1.1"
# - 更新 CHANGELOG.md

# 提交并打标签
git add .
git commit -m "chore: bump version to 2.1.1"
git tag v2.1.1

# 发布
npm publish

# 推送到 GitHub
git push origin main --tags

测试流程

# 本地测试
npm pack
npx ./speckit-mcp-x-2.1.0.tgz

# 在 Cursor 中测试
# 编辑 ~/.cursor/mcp.json:
{
  "mcpServers": {
    "speckit-dev": {
      "command": "npx",
      "args": ["-y", "/full/path/to/speckit-mcp-x-2.1.0.tgz"]
    }
  }
}

技术实现

Node.js 包装器职责

bin/speckit-mcp-x.js 负责：

1. ✅ 检测 Python 版本（要求 3.10+）
2. ✅ 检查 mcp 包是否安装
3. ✅ 自动尝试安装缺失的依赖
4. ✅ 设置 PYTHONPATH 环境变量
5. ✅ 启动 Python MCP Server
6. ✅ 转发 stdin/stdout/stderr
7. ✅ 处理进程信号和优雅退出

跨平台支持

• ✅ macOS (darwin)
• ✅ Linux
• ✅ Windows (win32)

依赖管理

系统要求：
  - Node.js 14+（NPX 自带）
  - Python 3.10+（提示用户安装）
  - pip（Python 自带）

自动安装：
  - mcp>=0.9.0（包装器自动处理）

---

📚 更多资源

• 📖 Spec-Kit 官方仓库: https://github.com/github/spec-kit
• 📦 NPM 包页面: https://www.npmjs.com/package/speckit-mcp-x
• 🐛 问题反馈: 通过 GitHub Issues 报告
• 📝 变更日志: 查看 CHANGELOG.md

---

📄 License

MIT License - 详见 LICENSE 文件

---

🙏 致谢

本项目基于 GitHub 的 spec-kit 开发。

---