MCP迭代管理工具

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

🚀 快速开始

安装配置

1. 编译项目

   npm install
   npm run build
   

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

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

   配置修改后重新编译：

   npm run build
   

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

   {
     "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。

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

3. 在 Cursor 中配置

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

• 添加工具配置:

  • 将下面的JSON代码块添加到"MCP"的配置中。

  "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步迭代创建流程

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提交

两阶段提交流程

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

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

🏗️ 项目架构

文件结构

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 文件来配置项目特定信息：

# 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. 及时更新文档和注释