# 工具描述国际化 - 使用指南

## 功能概述

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

## 🚀 快速开始

### 环境变量配置

```bash
# 使用中文（默认，无需设置）
export SPEC_CODING_LANG=zh
# 或
export SPEC_CODING_LANG=zh-CN

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

### 快速测试

```bash
# 测试中文环境（默认）
node src/test-i18n.mjs

# 测试英文环境
SPEC_CODING_LANG=en node src/test-i18n.mjs

# 完整演示
node src/final-demo.mjs
```

## 📋 支持的工具列表

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

## 💻 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');
// 中文环境：启动规范化编程工作流
// 英文环境：Start Spec Coding Workflow

// 获取完整的工具信息
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
            }
        };
    }
}
```

### 使用基础工具类（可选）

```typescript
import { BaseI18nTool } from './tools/BaseI18nTool.js';

export class MyTool extends BaseI18nTool {
    protected toolKey = 'startWorkflow' as const;
    
    constructor() {
        super();
    }

    public getTool(): Tool {
        return super.getToolDefinition({
            type: 'object',
            properties: {},
            additionalProperties: false
        });
    }
}
```

## 📁 项目结构

```
src/
├── i18n/
│   ├── locales.ts          # 语言包定义（中英文文案）
│   └── index.ts           # 国际化 API 函数
├── tools/
│   ├── BaseI18nTool.ts    # 国际化基础工具类（可选）
│   └── WorkflowStartTool.ts # 示例：已更新支持国际化
├── examples/
│   └── i18n-tool-example.ts  # 完整使用示例
├── test-i18n.mjs         # 功能测试脚本
├── final-demo.mjs        # 完整演示脚本
└── dist/i18n/            # 编译后的 JavaScript 文件
```

## ✅ 功能特性

1. **环境变量驱动**：通过 `SPEC_CODING_LANG` 控制语言
2. **默认中文**：无需配置即可使用中文
3. **类型安全**：完整的 TypeScript 类型约束
4. **易于扩展**：添加新语言只需更新语言包
5. **向后兼容**：不影响现有工具的正常使用
6. **全工具覆盖**：所有9个工具完整支持国际化
7. **统一基类**：所有工具继承 BaseI18nTool 确保一致性

## 🔧 编译和运行

### 编译 TypeScript

```bash
# 编译国际化模块
npx tsc src/i18n/*.ts --outDir dist/i18n --module es2020 --target es2020 --moduleResolution node
```

### 测试验证

```bash
# 基础功能测试
node src/test-i18n.mjs

# 英文环境测试
SPEC_CODING_LANG=en node src/test-i18n.mjs

# 完整演示（包含所有9个工具）
node src/final-demo.mjs
```

## 🎯 测试验证结果

✅ **中文环境测试通过**
- 默认语言环境：zh-CN
- 工具描述正确显示为中文

✅ **英文环境测试通过**  
- 环境变量 SPEC_CODING_LANG=en 生效
- 工具描述正确切换为英文

✅ **API 功能完整**
- getCurrentLocale() 正确返回当前语言
- getToolDescription() 返回对应语言的描述
- getToolMessages() 返回完整的工具信息

✅ **类型安全验证**
- TypeScript 编译无错误
- 完整的类型约束和智能提示

## 📝 注意事项

1. **环境变量时效**：环境变量在应用启动时读取，运行时修改需要重启应用
2. **工具名称固定**：所有工具名称保持英文不变，只有描述支持多语言
3. **类型检查**：使用 TypeScript 确保编译时安全，防止使用不存在的工具键名
4. **模块格式**：编译为 ES 模块格式，支持现代 JavaScript 环境

## 🚀 扩展指南

### 添加新工具

在 `src/i18n/locales.ts` 中添加新条目：

```typescript
export const zhCN: LocaleMessages = {
    tools: {
        // 现有工具...
        newTool: {
            name: "spec_coding_new_tool",
            description: "新工具的中文描述"
        }
    }
};

export const enUS: LocaleMessages = {
    tools: {
        // 现有工具...
        newTool: {
            name: "spec_coding_new_tool", 
            description: "English description for new tool"
        }
    }
};
```

### 添加新语言

1. 创建新的语言包（如日语）：
```typescript
export const jaJP: LocaleMessages = {
    tools: {
        startWorkflow: {
            name: "spec_coding_workflow_start",
            description: "スペックコーディングワークフローを開始"
        }
        // ...其他工具
    }
};
```

2. 更新类型定义：
```typescript
export type SupportedLocale = 'zh-CN' | 'en-US' | 'ja-JP';
```

3. 更新语言检测逻辑：
```typescript
export function getCurrentLocale(): SupportedLocale {
    const envLang = process.env.SPEC_CODING_LANG;
    
    if (envLang === 'ja' || envLang === 'ja-JP') {
        return 'ja-JP';
    }
    // 其他语言判断...
}
```

## 🎉 总结

工具描述国际化功能已完全实现并通过测试验证：

- ✅ 支持中英文切换
- ✅ 环境变量 SPEC_CODING_LANG 控制  
- ✅ 默认中文，无需配置
- ✅ **所有9个工具完整支持国际化**
- ✅ 类型安全的 TypeScript API
- ✅ 统一的 BaseI18nTool 基类架构
- ✅ 易于扩展和维护

**已完成国际化的工具列表：**
1. WorkflowStartTool - 启动工作流
2. FeatureConfirmedTool - 确认功能定义  
3. RequirementsStartTool - 启动需求收集
4. RequirementsConfirmedTool - 确认需求收集
5. DesignStartTool - 启动设计文档创建
6. DesignConfirmedTool - 确认设计文档
7. TasksStartTool - 启动任务列表创建
8. TasksConfirmedTool - 确认任务列表
9. ExecuteStartTool - 启动任务执行

通过简单的环境变量设置，即可实现所有工具描述文案的无缝切换，为不同语言环境的用户提供更好的使用体验。

---

## IDE integration: Start MCP Server via npx

Use npx to launch the MCP server (no local install required). Works in CodeBuddy, Cursor, Claude Desktop, Continue, etc.

- Prerequisites
  - Node >= 18
  - Package published to npm: spec-coding-mcp-server

- Recommended config (stdio MCP):
  - command: npx
  - args: ["-y", "spec-coding-mcp-server@latest"]
  - cwd: your project root
  - env: { "NODE_ENV": "production", "MCP_LOG_LEVEL": "info" }

### Cursor / CodeBuddy / Claude / Continue example

```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"
      }
    }
  }
}
```

- Troubleshooting
  - If npx is not found, use absolute path (some IDEs do not inherit PATH):
    - e.g. "/Users/<you>/.nvm/versions/node/v18.x.x/bin/npx"
  - If network blocks npm, install locally and use node to run the bin:
    - command: node
    - args: ["/path/to/node_modules/.bin/spec-coding-mcp-server"]
  - macOS privacy: allow IDE to access the project directory
  - After configuration, fully restart the IDE to reload MCP process

- Verification
  1) Check IDE MCP logs: "started successfully", initialize returns capabilities.tools.listChanged=true
  2) tools/list should show 9 tools
  3) Call spec_coding_workflow_start (no args), then use returned session_id to call spec_coding_feature_confirmed