# Spec Coding MCP Server

[![npm version](https://badge.fury.io/js/spec-coding-mcp-server.svg)](https://badge.fury.io/js/spec-coding-mcp-server)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

## 🚀 快速开始

### 🔧 IDE 集成配置

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

首先在项目中安装包：

```bash
npm install spec-coding-mcp-server@latest
```

然后在 MCP 配置中使用：

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

**实际配置示例**：
```json
{
  "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: 全局安装

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

配置：
```json
{
  "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": {}
    }
  }
}
```

### 本地开发

```bash
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)
```bash
# 启动工作流
spec_coding_workflow_start

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

### 阶段 2: 需求收集 (Requirements Gathering)  
```bash
# 启动需求收集
spec_coding_requirements_start(sessionId, featureName)

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

### 阶段 3: 设计文档 (Design Document)
```bash
# 启动设计阶段
spec_coding_design_start(sessionId, featureName)

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

### 阶段 4: 任务规划 (Task Planning)
```bash  
# 启动任务规划
spec_coding_tasks_start(sessionId, featureName)

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

### 阶段 5: 任务执行 (Task Execution)
```bash
# 启动执行阶段
spec_coding_execute_start(sessionId, featureName)
```

## 🌐 国际化支持

### 环境变量配置

```bash
# 中文（默认）
export SPEC_CODING_LANG=zh

# 英文
export SPEC_CODING_LANG=en
```

### 支持的工具描述

| 工具名称 | 中文描述 | 英文描述 |
|---------|----------|----------|
| `spec_coding_workflow_start` | 启动规范化编程工作流 | Start Spec Coding Workflow |
| `spec_coding_feature_confirmed` | 确认功能定义并进入需求阶段 | Confirm feature definition and proceed to requirements phase |
| `spec_coding_requirements_start` | 启动需求收集阶段 | Start requirements gathering phase |
| `spec_coding_requirements_confirmed` | 确认需求收集并进入设计阶段 | Confirm requirements and proceed to design phase |
| `spec_coding_design_start` | 启动设计文档创建阶段 | Start design document creation phase |
| `spec_coding_design_confirmed` | 确认设计文档并进入任务规划阶段 | Confirm design document and proceed to task planning phase |
| `spec_coding_tasks_start` | 启动任务列表创建阶段 | Start task list creation phase |
| `spec_coding_tasks_confirmed` | 确认任务列表并进入执行阶段 | Confirm task list and proceed to execution phase |
| `spec_coding_execute_start` | 启动任务执行阶段 | Start task execution phase |

## 📁 项目结构

```
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`)

### 配置类

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

## 🧪 验证安装

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

```bash
[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 模板

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

### 本地开发

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

# 构建监听
npm run watch

# 类型检查
npx tsc --noEmit
```

## 📊 版本信息

- **当前版本**: 0.1.9
- **Node.js 要求**: >= 18.0.0
- **MCP SDK**: ^1.0.0
- **发布平台**: [npm](https://www.npmjs.com/package/spec-coding-mcp-server)

## 🤝 贡献指南

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 - 查看 [LICENSE](LICENSE) 文件了解详细信息

## 🔗 相关链接

- [NPM Package](https://www.npmjs.com/package/spec-coding-mcp-server)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [EARS 需求语法](https://alistairmavin.com/ears/)

---

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