speckit-mcp-x

v3.2.5

Published

19 days ago

Model Context Protocol server for Speckit - AI-driven Spec-Driven Development with full automation

0High
0Medium
0Low

elliotding

mcp speckit specify ai development cursor model-context-protocol spec-driven-development

Speckit MCP Server

🚀 AI-Driven Spec-Driven Development for Cursor IDE

基于 spec-kit 的 MCP (Model Context Protocol) 服务器

安装 • 快速开始 • 文档 • Windows 支持 • 故障排查

📖 目录

✨ 特点

🚀 自动化工作流 - 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 秒）。

Windows 用户: 详细的 Windows 安装和配置指南请查看 WINDOWS-SUPPORT.md

✅ 优点

✨ 真正的一键安装 - 无需打开终端，无需手动命令
🔄 自动更新 - 始终使用最新版本（@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 会自动：

检查并安装依赖（uv、specify CLI）
初始化工作空间
执行 constitution（项目章程）
执行 specify（技术规范）
执行 plan（实施计划）
执行 tasks（任务分解）
🛑 自动暂停，询问用户是否继续
用户确认后执行 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 [email protected]

# Ubuntu/Debian
sudo apt install python3.11

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

问题：提示 mcp 包未安装

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

pip3 install mcp>=0.9.0

PIP 方式常见问题

Cursor 无法识别 Speckit

解决方案：

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

找不到 slash commands

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

初始化 speckit 工作空间

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

📊 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 负责：

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

跨平台支持

✅ macOS (darwin) - 完全支持
✅ Linux - 完全支持
✅ Windows (win32) - 完全支持
- 自动检测 Python (python, py)
- 使用 where 代替 which
- 支持 Git Bash / WSL 执行脚本

依赖管理

系统要求：
  - 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 开发。

如果这个项目对你有帮助，请给一个 ⭐ Star！

Made with ❤️ by Speckit MCP Team