superlc/spec-coding-mcp-server

Spec Coding MCP Server

通过系统化的规格驱动开发工作流，将功能想法转化为可投入生产的代码。支持中英文国际化，提供完整的 MCP (Model Context Protocol) 工具集。

特别致谢：https://github.com/feiyun0112/spec-coding-mcp。因该项目基于 dot 开发，在 windows 上运行，故保留其核心功能，基于 nodejs 开发一个js 版本的。

🚀 快速开始

🔧 IDE 集成配置

方案 1: 本地安装 + Node 直接调用（推荐）

首先在项目中安装包：

npm install spec-coding-mcp-server@latest

然后在 MCP 配置中使用：

{
  "mcpServers": {
    "spec-coding-mcp-server": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "node",
      "args": [
        "/path/to/your/project/node_modules/spec-coding-mcp-server/dist/index.js"
      ],
      "env": {}
    }
  }
}

实际配置示例：

{
  "mcpServers": {
    "spec-coding-mcp-server": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "node",
      "args": [
        "/path/to/your/project/node_modules/spec-coding-mcp-server/dist/index.js"
      ],
      "env": {}
    }
  }
}

方案 2: 全局安装

npm install -g spec-coding-mcp-server@latest

配置：

{
  "mcpServers": {
    "spec-coding-mcp-server": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "node",
      "args": [
        "/Users/your-username/.nvm/versions/node/v18.x.x/lib/node_modules/spec-coding-mcp-server/dist/index.js"
      ],
      "env": {}
    }
  }
}

本地开发

git clone <repository-url>
cd spec-coding-mcp-server
npm install
npm run build
npm start

故障排除

1. NPX 方式卡住：使用本地安装 + node 直接调用
2. 路径问题：确保 Node.js 和包的路径正确
3. 权限问题：确保 IDE 有访问项目目录的权限
4. 版本问题：确保 Node.js >= 18.0.0
5. 重启 IDE：配置更改后需要完全重启 IDE

🌟 核心特性

• 📋 规格驱动开发：EARS 语法需求文档 + 结构化设计方案 + 可执行任务清单
• 🔄 完整工作流：从功能定义到代码实现的 5 个标准化阶段
• 🌐 国际化支持：通过 SPEC_CODING_LANG 环境变量支持中英文切换
• 📁 文件管理：自动生成和管理 Spec 文件夹结构
• 🔄 会话管理：支持多会话并发，自动超时清理
• 📊 日志记录：完整的操作日志和错误追踪

🎯 什么是规格驱动开发？

规格驱动开发（Spec-Driven Development） 是一种系统化的软件开发方法，通过标准化的规格文件将模糊需求转化为可执行、可跟踪、可验收的开发流程。

核心价值

• 摆脱氛围编程：从 "凭感觉" 的 Vibe Coding 转向工程化的开发过程
• 需求可追溯：每行代码都能追溯到具体的需求条目
• 质量可控：通过结构化文档确保开发质量和一致性
• 团队协作：标准化的文档格式便于团队沟通和知识传承

Spec 文件夹结构

每个功能模块对应一个 Spec 文件夹，包含 3 个核心文件：

.spec-coding/
└── feature-name/
    ├── requirements.md    # EARS 语法需求文档
    ├── design.md         # 技术设计方案
    └── tasks.md          # 可执行任务清单

🔧 工作流程

阶段 1: 功能定义 (Feature Define)

# 启动工作流
spec_coding_workflow_start

# 确认功能定义
spec_coding_feature_confirmed(sessionId, featureName, featureDetail)

阶段 2: 需求收集 (Requirements Gathering)

# 启动需求收集
spec_coding_requirements_start(sessionId, featureName)

# 确认需求文档
spec_coding_requirements_confirmed(sessionId, featureName)

阶段 3: 设计文档 (Design Document)

# 启动设计阶段
spec_coding_design_start(sessionId, featureName)

# 确认设计文档
spec_coding_design_confirmed(sessionId, featureName)

阶段 4: 任务规划 (Task Planning)

# 启动任务规划
spec_coding_tasks_start(sessionId, featureName)

# 确认任务清单
spec_coding_tasks_confirmed(sessionId, featureName)

阶段 5: 任务执行 (Task Execution)

# 启动执行阶段
spec_coding_execute_start(sessionId, featureName)

🌐 国际化支持

环境变量配置

# 中文（默认）
export SPEC_CODING_LANG=zh

# 英文
export SPEC_CODING_LANG=en

支持的工具描述

📁 项目结构

spec-coding-mcp-server/
├── src/
│   ├── models/              # 数据模型
│   │   ├── SessionState.ts
│   │   └── SpecCodingConfiguration.ts
│   ├── services/            # 核心服务
│   │   ├── SessionManager.ts
│   │   ├── FileService.ts
│   │   └── ContextManager.ts
│   ├── tools/               # MCP 工具集（9个工具）
│   │   ├── BaseI18nTool.ts
│   │   ├── WorkflowStartTool.ts
│   │   ├── FeatureConfirmedTool.ts
│   │   ├── RequirementsStartTool.ts
│   │   ├── RequirementsConfirmedTool.ts
│   │   ├── DesignStartTool.ts
│   │   ├── DesignConfirmedTool.ts
│   │   ├── TasksStartTool.ts
│   │   ├── TasksConfirmedTool.ts
│   │   └── ExecuteStartTool.ts
│   ├── i18n/                # 国际化支持
│   │   ├── index.ts
│   │   └── locales.ts
│   ├── exceptions/          # 异常处理
│   │   ├── SessionNotFoundException.ts
│   │   └── WrongStageException.ts
│   └── index.ts            # 主入口文件
├── prompts/                # Prompt 模板（中英文）
│   ├── FeatureDefine.md
│   ├── FeatureConfirmed.md
│   ├── RequirementsGathering.md
│   ├── RequirementsConfirmed.md
│   ├── CreateFeatureDesignDocument.md
│   ├── FeatureDesignDocumentConfirmed.md
│   ├── CreateTaskList.md
│   ├── TasksConfirmed.md
│   └── TaskExecution.md
├── dist/                   # 编译输出
└── package.json

⚙️ 配置选项

环境变量

• SPEC_CODING_LANG: 语言设置 (zh | en，默认: zh)
• NODE_ENV: 运行环境 (development | production)
• MCP_LOG_LEVEL: 日志级别 (error | warn | info | debug)

配置类

class SpecCodingConfiguration {
  promptsPath: string = 'prompts'        // Prompt 模板路径
  outputPath: string = '.spec-coding'    // 输出文件路径  
  sessionTimeout: number = 3600000       // 会话超时（1小时）
}

🧪 验证安装

启动服务器后，应该看到：

[INFO] Starting spec-coding-mcp-server v0.1.9...
[INFO] spec-coding-mcp-server started successfully  
[INFO] Registered 9 tools

在 MCP 客户端中验证：

1. 工具列表：应该显示 9 个 spec_coding_* 工具
2. 启动工作流：调用 spec_coding_workflow_start，获取会话 ID
3. 功能确认：使用会话 ID 调用 spec_coding_feature_confirmed

🔨 开发指南

添加新工具

1. 继承 BaseI18nTool 类
2. 在 locales.ts 中添加工具描述
3. 在 index.ts 中注册工具
4. 添加对应的 Prompt 模板

export class NewTool extends BaseI18nTool {
    protected toolKey = 'newTool' as const;
    
    public async execute(args: any): Promise<any> {
        // 工具逻辑
    }
}

本地开发

# 开发模式（热重载）
npm run dev

# 构建监听
npm run watch

# 类型检查
npx tsc --noEmit

📊 版本信息

• 当前版本: 0.1.9
• Node.js 要求: >= 18.0.0
• MCP SDK: ^1.0.0
• 发布平台: npm

🤝 贡献指南

1. Fork 项目
2. 创建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打开 Pull Request

📄 许可证

MIT License - 查看 文件了解详细信息

🔗 相关链接

• NPM Package
• Model Context Protocol
• EARS 需求语法

让 AI 编程更规范，让代码质量更可控！ 🎯