# 工具描述国际化支持

本项目实现了工具描述文案的中英文切换功能，通过环境变量控制语言设置。

## 功能特性

- ✅ 支持中文（zh-CN）和英文（en-US）两种语言
- ✅ 通过环境变量 `SPEC_CODING_LANG` 控制语言
- ✅ 默认使用中文，无需额外配置
- ✅ 类型安全的国际化 API

## 环境变量配置

### 使用中文（默认）
```bash
# 不设置环境变量，或设置为中文
export SPEC_CODING_LANG=zh
# 或
export SPEC_CODING_LANG=zh-CN
```

### 使用英文
```bash
export SPEC_CODING_LANG=en
# 或
export SPEC_CODING_LANG=en-US
```

## API 使用

### 基础 API

```typescript
import { getCurrentLocale, getToolName, getToolDescription, getToolMessages } from './src/i18n/index.js';

// 获取当前语言环境
const locale = getCurrentLocale(); // 'zh-CN' | 'en-US'

// 获取工具名称
const name = getToolName('startWorkflow');

// 获取工具描述
const description = getToolDescription('startWorkflow');

// 获取完整的工具信息
const messages = getToolMessages('startWorkflow');
console.log(messages.name, messages.description);
```

### 在工具类中使用

```typescript
import { Tool } from '@modelcontextprotocol/sdk/types.js';
import { getToolMessages } from '../i18n/index.js';

export class MyTool {
    public getToolDefinition(): Tool {
        const messages = getToolMessages('startWorkflow');
        
        return {
            name: messages.name,
            description: messages.description,
            inputSchema: {
                type: 'object',
                properties: {},
                additionalProperties: false
            }
        };
    }
}
```

## 支持的工具

目前支持以下工具的国际化：

| 工具键名 | 中文描述 | 英文描述 |
|---------|---------|---------|
| `startWorkflow` | 启动规范化编程工作流 | Start Spec Coding Workflow |
| `featureConfirmed` | 确认功能定义并进入需求阶段 | Confirm the feature definition and proceed to the requirements phase |
| `requirementsStart` | 启动需求收集阶段 | Start the requirements gathering phase |
| `requirementsConfirmed` | 确认需求收集并进入设计阶段 | Confirm the requirements gathering and proceed to the design phase |
| `designStart` | 启动设计文档创建阶段 | Start the design document creation phase |
| `designConfirmed` | 确认设计文档并进入任务规划阶段 | Confirm the design document and proceed to the task planning phase |
| `tasksStart` | 启动任务列表创建阶段 | Start the task list creation phase |
| `tasksConfirmed` | 确认任务列表并进入执行阶段 | Confirm the task list and proceed to the execution phase |
| `executeStart` | 启动任务执行阶段 | Start the task execution phase |

## 测试

运行国际化功能测试：

```bash
# 编译 TypeScript 文件
npx tsc src/i18n/*.ts --outDir dist/i18n --module commonjs --target es2020 --moduleResolution node

# 运行测试
node src/test-i18n.js
```

## 文件结构

```
src/
├── i18n/
│   ├── locales.ts          # 语言包定义
│   └── index.ts           # 国际化 API
├── examples/
│   └── i18n-tool-example.ts  # 使用示例
└── test-i18n.js          # 功能测试
```

## 扩展新语言

要添加新语言支持，请：

1. 在 `src/i18n/locales.ts` 中添加新的语言包
2. 更新 `SupportedLocale` 类型定义
3. 在 `getCurrentLocale()` 函数中添加环境变量判断逻辑

## 注意事项

- 环境变量在应用启动时读取，运行时修改需要重启应用
- 所有工具名称保持英文不变，只有描述支持多语言
- 类型定义确保编译时安全，防止使用不存在的工具键名

---

## 在 IDE 中通过 npx 启动 MCP Server（推荐）

无需本地安装，直接使用 npx 拉起 MCP 服务器，适用于 CodeBuddy、Cursor、Claude Desktop、Continue 等支持 stdio 的编辑器。

- 前置条件
  - Node >= 18
  - 包已发布到 npm（spec-coding-mcp-server）

- 标准配置（stdio MCP）
  - command: npx
  - args: ["-y", "spec-coding-mcp-server@latest"]
  - cwd: 项目根目录
  - env: { "NODE_ENV": "production", "MCP_LOG_LEVEL": "info" }

### 配置示例（通用）

```json
{
  "mcpServers": {
    "spec-coding-mcp-server": {
      "command": "npx",
      "args": ["-y", "spec-coding-mcp-server@latest"],
      "cwd": "/path/to/your/project",
      "env": {
        "NODE_ENV": "production",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}
```

- 常见问题与排查
  - IDE 未继承 PATH 导致找不到 npx：将 command 改为绝对路径
    - 例如："/Users/你的用户名/.nvm/versions/node/v18.x.x/bin/npx"
  - 网络限制导致 npx 拉取失败：改为本地安装并使用 node 执行 bin
    - command: node
    - args: ["/path/to/node_modules/.bin/spec-coding-mcp-server"]
  - macOS 权限：在“隐私与安全性”中允许编辑器访问项目目录
  - 修改配置后，需要完全退出并重启 IDE，确保 MCP 进程重新拉起

- 验证步骤
  1) 在 IDE 的 MCP 日志中看到“started successfully”
  2) initialize 响应包含 capabilities.tools.listChanged=true
  3) tools/list 返回 9 个工具
  4) 调用 spec_coding_workflow_start（无参），从返回文本提取 session_id
  5) 调用 spec_coding_feature_confirmed，传入 sessionId、featureName、featureDetail