Which integrations are available for this server?

Provides Git repository information extraction including project URLs, branch detection, commit history analysis, and intelligent work time calculation based on actual development periods.

How do I use Iteration MCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Iteration MCP create a new iteration for the dashboard redesign project" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

MCP迭代管理工具

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

🚀 快速开始

安装配置

编译项目
npm install npm run build
配置钉钉应用信息 在 src/config.ts 文件中修改钉钉配置：
// 在 MCP_CONFIG 中更新以下信息 dingtalk: { appId: "your_actual_dingtalk_app_id", // 替换为实际的钉钉应用ID appSecret: "your_actual_dingtalk_app_secret" // 替换为实际的钉钉应用密钥 }
配置修改后重新编译：
npm run build
在 Cursor 中配置 MCP 编辑 Cursor 的 MCP 配置文件，添加：
{ "mcpServers": { "iteration": { "command": "/path/to/your/project/dist/index.js" } } }

基本使用流程

在 Cursor 中调用 check_login_status 检查登录状态
如未登录，调用 login_dingtalk 进行扫码登录
登录成功后，使用 create_iteration 开始5步交互式流程
使用 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文件中，并将。
{ "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认证
统一的
标准响应格式: {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

配置优先级：

iteration-mcp.config 文件（推荐）
git_info.config.json 文件（向后兼容）
git remote 自动检测（fallback）

工作目录检测机制

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

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

智能工时计算

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

主分支 (main/master)：

计算从第一次提交到当前时间的实际天数
例如：项目从2025-06-22开始，到2025-06-24 = 2天

特性分支：

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

计算规则：

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

🚀 二次开发指南

添加新工具

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

添加新API接口

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

修改流程步骤

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

🔍 调试技巧

启用详细日志

代码中已包含详细的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）
✅ 详细注释和文档

🎯 最佳实践

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