# MCP迭代管理工具

一个基于Model Context Protocol (MCP)的迭代管理工具，主要用于自动化收集和提交迭代信息到公司的CodeReview系统。支持钉钉扫码登录和交互式迭代创建流程。

## 🚀 快速开始

### 安装配置

1. **编译项目**

   ```bash
   npm install
   npm run build
   ```

2. **配置钉钉应用信息**
   在 `src/config.ts` 文件中修改钉钉配置：

   ```typescript
   // 在 MCP_CONFIG 中更新以下信息
   dingtalk: {
     appId: "your_actual_dingtalk_app_id",      // 替换为实际的钉钉应用ID
     appSecret: "your_actual_dingtalk_app_secret" // 替换为实际的钉钉应用密钥
   }
   ```

   配置修改后重新编译：

   ```bash
   npm run build
   ```

3. **在 Cursor 中配置 MCP**
   编辑 Cursor 的 MCP 配置文件，添加：

   ```json
   {
     "mcpServers": {
       "iteration": {
         "command": "/path/to/your/project/dist/index.js"
       }
     }
   }
   ```

### 基本使用流程

1. 在 Cursor 中调用 `check_login_status` 检查登录状态
2. 如未登录，调用 `login_dingtalk` 进行扫码登录
3. 登录成功后，使用 `create_iteration` 开始5步交互式流程
4. 使用 `submit_complete_iteration` 提交完整的迭代和CR申请单

## 👥 使用者指南（同事配置）

为了在你的本地环境中使用此MCP工具，请按照以下步骤进行一次性配置。

### 1. 环境准备

- **安装 Node.js**: 请确保你的电脑上已安装 Node.js (推荐LTS版本)。`npx`是Node.js自带的工具，我们需要它来运行此MCP工具。
  - 你可以通过在终端运行 `node -v` 来检查是否已安装。

### 2. 创建全局配置文件

这是最重要的一步，你需要创建一个全局配置文件来存放你的个人认证Token和API地址。

- **创建文件**:
  - 在你的**用户主目录**下，创建一个名为 `mcp-config.json` 的文件。
    - **macOS/Linux**: 文件路径应为 `~/.mcp-config.json`
    - **Windows**: 文件路径应为 `C:\\Users\\YourUsername\\.mcp-config.json`

- **配置文件内容**:
  - 将以下内容**完整复制**到你创建的`mcp-config.json`文件中，并**将`Authorization`的值替换为你自己的有效Token**。

  ```json
  {
    "api": {
      "baseUrl": "http://xx.xxxxx.com"
    },
    "auth": {
      "Authorization": "Bearer your_personal_token_here"
    }
  }
  ```

### 3. 在 Cursor 中配置

最后，告诉Cursor如何找到并运行这个工具。

- **添加工具配置**:
  - 将下面的JSON代码块添加到`"MCP"`的配置中。

  ```json
  "iteration-mcp-v2": {
      "name": "iteration-mcp-v2",
      "command": "npx",
      "args": [
          "-y",
          "@asthestarslept/iteration-mcp",
          "--workdir",
          "/path/to/your/project"
      ],
      "description": "用于创建和管理迭代的MCP工具"
  }
  ```
  
  > **重要提示**: 请将 `/path/to/your/project` 替换为您实际项目的绝对路径，例如：
  > - macOS/Linux: `/Users/yourname/projects/your-project-name`
  > - Windows: `C:\\Users\\yourname\\projects\\your-project-name`
  
- **保存并重启**: 保存文件，然后**重启Cursor**以加载新工具。

**配置完成！** 现在你可以在Cursor中通过 `@iteration-mcp-v2` 来使用这个工具了。

## 🔧 工具列表

### 认证工具

- `check_login_status`: 检查登录状态和系统信息
- `login_dingtalk`: 钉钉扫码登录

### 迭代管理工具  

- `create_iteration`: 5步交互式迭代创建流程
- `submit_complete_iteration`: 两阶段API提交

### 数据查询工具

- `get_user_list`: 获取用户列表（参与人员和审核人员）

## 📊 数据流程

### 5步迭代创建流程

```md
Step 1: start
├── 获取项目组列表 (getProjectList API)
├── 获取用户列表 (从缓存)
└── 显示选项供用户选择

Step 2: basic_info  
├── 收集基础信息（项目线、迭代名称、上线时间）
├── 自动检测工作目录 (MCP根目录机制)
├── 自动获取Git信息（项目URL、分支、项目名）
├── 智能计算预估工时（基于项目实际开发天数）
└── 存储到 sessionData.basicInfo

Step 3: project_info
├── 收集项目信息（文档链接、人员配置）  
├── 使用Git信息作为默认值
└── 存储到 sessionData.projectInfo

Step 4: modules
├── 收集模块信息（组件模块、功能模块）
├── 组装完整迭代数据
└── 生成JSON数据预览供确认

Step 5: submit (手动确认)
├── 用户手动确认数据正确性
├── 调用 submit_complete_iteration
└── 两阶段API提交
```

### 两阶段提交流程

```md
Stage 1: 创建迭代基础信息
├── POST /api/codeReview/createSprint
├── 获取迭代ID
└── 验证创建结果

Stage 2: 创建CR申请单
├── 数据格式转换（CRApplication → CRApplicationData）
├── POST /api/codeReview/createCrRequest  
├── 获取CR申请单ID
└── 更新本地缓存
```

## 🏗️ 项目架构

### 文件结构

```md
src/
├── index.ts          # 主服务器入口，MCP工具定义和路由
├── config.ts         # 配置管理，API端点定义
├── api.ts           # API调用管理，HTTP请求封装
├── cache.ts         # 本地缓存管理，用户数据存储
├── dingtalk.ts      # 钉钉认证模块，扫码登录
├── git-utils.ts     # Git信息工具，智能工时计算和项目信息获取
└── types.ts         # TypeScript类型定义
```

### 主要组件

#### IterationMCPServer (index.ts)

- **职责**: MCP服务器主类，处理所有工具请求
- **核心功能**: 工具注册和路由、多步骤迭代创建流程管理、会话状态管理、错误处理和响应格式化

#### APIManager (api.ts)

- **职责**: 封装所有API调用
- **核心功能**: 统一的HTTP请求处理、认证token管理、两阶段提交流程、数据格式转换

#### CacheManager (cache.ts)

- **职责**: 本地数据缓存和管理
- **核心功能**: 用户列表缓存（24小时有效期）、项目线历史记录、最近使用人员管理、OSS图片上传支持

#### DingTalkAuth (dingtalk.ts)

- **职责**: 钉钉扫码登录认证
- **核心功能**: 扫码登录流程、Token获取和管理、用户信息解析

## 🔑 关键技术点

### API接口规范

- **统一使用POST方法**
- **Bearer Token认证**
- **统一的`/api`前缀**
- **标准响应格式**: `{success: boolean, data: any, errorMsg?: string}`

### 数据格式转换

工具内部使用人性化的数据收集格式，提交时转换为API要求的格式：

- `componentModules` → `componentList`
- `functionModules` → `functionList`  
- 人员ID数组 → 逗号分隔字符串

### 错误处理策略

- **分层错误处理**: 工具级 → 方法级 → API级
- **详细错误信息**: 包含HTTP状态码、响应数据、堆栈信息
- **优雅降级**: 缓存更新失败不影响主流程

### 会话管理

使用`sessionData`对象维护多步骤流程的状态：

- 每次`start`步骤清空会话
- 各步骤数据独立存储
- 最后一步组装完整数据

## 📚 配置说明

### 全局配置

项目使用内置配置管理，所有配置都在 `src/config.ts` 中：

- **钉钉配置**：需要在代码中配置实际的 appId 和 appSecret
- **接口端点**：所有 API 端点都已预配置

如需修改 API 地址或端点，直接编辑 `src/config.ts` 文件。

### 项目级配置文件 (iteration-mcp.config)

工具支持在项目根目录创建 `iteration-mcp.config` 文件来配置项目特定信息：

```bash
# iteration-mcp.config
git_project_url=https://github.com/username/project-name
git_project_name=project-name
workdir=/path/to/project
```

**配置优先级**：
1. iteration-mcp.config 文件（推荐）
2. git_info.config.json 文件（向后兼容）
3. git remote 自动检测（fallback）

### 工作目录检测机制

工具使用MCP标准的roots机制自动检测工作目录：

1. **MCP客户端提供的workspace roots**（最高优先级）
2. 手动指定的workdir参数
3. 环境变量 (PWD, INIT_CWD)
4. process.cwd() (fallback)

### 智能工时计算

工具提供基于项目实际开发时间的智能工时计算：

**主分支 (main/master)**：
- 计算从第一次提交到当前时间的实际天数
- 例如：项目从2025-06-22开始，到2025-06-24 = 2天

**特性分支**：
- 优先使用分支从主分支分离的时间点计算
- 回退方案：使用分支第一次提交时间
- 最终回退：基于最近提交活动估算

**计算规则**：
- 最小工时：1天（取消了原来不合理的3天限制）
- 无上限限制（取消了原来的30天上限）
- 基于实际时间跨度，而非提交数量

## 🚀 二次开发指南

### 添加新工具

1. 在`setupHandlers()`的工具列表中添加定义
2. 在路由switch中添加case分支  
3. 实现对应的`handle*`方法
4. 更新类型定义（如需要）

### 添加新API接口

1. 在`config.ts`的`endpoints`中添加路径
2. 在`APIManager`中添加方法
3. 处理认证和错误
4. 更新类型定义

### 修改流程步骤

1. 更新`create_iteration`工具的`step`枚举
2. 在`handleCreateIteration`中添加新case
3. 实现对应的处理方法
4. 更新会话数据结构

## 🔍 调试技巧

### 启用详细日志

代码中已包含详细的console.log，可通过查看输出跟踪流程

### 使用测试工具

- `get_user_list`: 测试API连接和认证
- `check_login_status`: 查看系统状态

### 会话数据检查

在各步骤中输出`sessionData`内容，确认数据收集正确

## 📦 依赖说明

- `@modelcontextprotocol/sdk`: MCP协议实现
- `axios`: HTTP请求库
- `child_process`: Git命令执行
- `fs/path/os`: 文件系统和路径操作

## 🎯 开发状态

当前为生产版本，已实现：

- ✅ 基础 MCP Server 框架
- ✅ 钉钉登录流程（二维码生成）
- ✅ Token 本地存储管理
- ✅ 完整的5步迭代创建和提交流程
- ✅ 项目内配置管理
- ✅ 项目组选择功能
- ✅ 用户列表管理
- ✅ 两阶段API提交
- ✅ MCP标准roots机制工作目录检测
- ✅ iteration-mcp.config配置文件支持
- ✅ 智能工时计算（基于实际开发时间）
- ✅ 多格式配置文件读取（.config和.json）
- ✅ 详细注释和文档

## 🎯 最佳实践

1. **保持API调用的幂等性**
2. **合理使用缓存减少API调用**
3. **提供清晰的用户提示和错误信息**
4. **维护向后兼容性**
5. **及时更新文档和注释**