MCP迭代管理工具

Una herramienta de gestión de iteraciones para automatizar la recopilación y el envío de información de iteraciones a un sistema CodeReview.

GitHub

Prueba este MCPPatrocinado

Documentación

MCP迭代管理工具

Una herramienta de gestión de iteraciones basada en el Protocolo de Contexto de Modelos (MCP), utilizada principalmente para recopilar y enviar automáticamente información de iteraciones al sistema CodeReview de la empresa. Admite inicio de sesión mediante escaneo de código con DingTalk y un flujo interactivo de creación de iteraciones.

🚀 Inicio rápido

Instalación y configuración

Compilar el proyecto
```
npm install
npm run build
```

Configurar la información de la aplicación DingTalk Modifica la configuración de DingTalk en el archivo src/config.ts:

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

Después de modificar la configuración, vuelve a compilar:

npm run build

Configurar MCP en Cursor Edita el archivo de configuración de MCP en Cursor y añade:

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

Flujo de uso básico

En Cursor, llama a check_login_status para verificar el estado de inicio de sesión
Si no has iniciado sesión, llama a login_dingtalk para iniciar sesión mediante escaneo de código
Después de iniciar sesión correctamente, usa create_iteration para comenzar el flujo interactivo de 5 pasos
Usa submit_complete_iteration para enviar la solicitud completa de iteración y CR

👥 Guía para usuarios (configuración para compañeros)

Para usar esta herramienta MCP en tu entorno local, sigue los siguientes pasos para realizar una configuración única.

1. Preparación del entorno

Instalar Node.js: Asegúrate de tener Node.js instalado en tu computadora (se recomienda la versión LTS). npx es una herramienta incluida con Node.js, la necesitamos para ejecutar esta herramienta MCP.
- Puedes verificar si está instalado ejecutando node -v en la terminal.

2. Crear el archivo de configuración global

Este es el paso más importante: debes crear un archivo de configuración global para almacenar tu token de autenticación personal y la dirección de la API.

Crear el archivo:
- En tu directorio de usuario principal, crea un archivo llamado mcp-config.json.
  - macOS/Linux: La ruta del archivo debe ser ~/.mcp-config.json
  - Windows: La ruta del archivo debe ser C:\\Users\\YourUsername\\.mcp-config.json
Contenido del archivo de configuración:
- Copia completamente el siguiente contenido en el archivo mcp-config.json que creaste, y reemplaza el valor de Authorization con tu propio token válido.
```
{
  "api": {
    "baseUrl": "http://xx.xxxxx.com"
  },
  "auth": {
    "Authorization": "Bearer your_personal_token_here"
  }
}
```

3. Configurar en Cursor

Finalmente, indícale a Cursor cómo encontrar y ejecutar esta herramienta.

Agregar la configuración de la herramienta:
- Agrega el siguiente bloque de código JSON a la configuración de "MCP".
```
"iteration-mcp-v2": {
    "name": "iteration-mcp-v2",
    "command": "npx",
    "args": [
        "-y",
        "@asthestarslept/iteration-mcp",
        "--workdir",
        "/path/to/your/project"
    ],
    "description": "用于创建和管理迭代的MCP工具"
}
```
Nota importante: Reemplaza /path/to/your/project con la ruta absoluta de tu proyecto real, por ejemplo:
- macOS/Linux: /Users/yourname/projects/your-project-name
- Windows: C:\\Users\\yourname\\projects\\your-project-name
Guardar y reiniciar: Guarda el archivo y luego reinicia Cursor para cargar la nueva herramienta.

¡Configuración completada! Ahora puedes usar esta herramienta en Cursor a través de @iteration-mcp-v2.

🔧 Lista de herramientas

Herramientas de autenticación

check_login_status: Verifica el estado de inicio de sesión e información del sistema
login_dingtalk: Inicio de sesión mediante escaneo de código con DingTalk

Herramientas de gestión de iteraciones

create_iteration: Flujo interactivo de creación de iteraciones en 5 pasos
submit_complete_iteration: Envío de API en dos fases

Herramientas de consulta de datos

get_user_list: Obtiene la lista de usuarios (participantes y revisores)

📊 Flujo de datos

Flujo de creación de iteraciones en 5 pasos

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

Flujo de envío en dos fases

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

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

🏗️ Arquitectura del proyecto

Estructura de archivos

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

Componentes principales

IterationMCPServer (index.ts)

Responsabilidad: Clase principal del servidor MCP, maneja todas las solicitudes de herramientas
Funciones principales: Registro y enrutamiento de herramientas, gestión del flujo de creación de iteraciones en múltiples pasos, gestión del estado de sesión, manejo de errores y formato de respuestas

APIManager (api.ts)

Responsabilidad: Encapsula todas las llamadas a la API
Funciones principales: Manejo unificado de solicitudes HTTP, gestión de tokens de autenticación, flujo de envío en dos fases, conversión de formatos de datos

CacheManager (cache.ts)

Responsabilidad: Caché y gestión de datos locales
Funciones principales: Caché de lista de usuarios (validez de 24 horas), historial de líneas de proyecto, gestión de usuarios recientes, soporte para carga de imágenes OSS

DingTalkAuth (dingtalk.ts)

Responsabilidad: Autenticación mediante escaneo de código con DingTalk
Funciones principales: Flujo de inicio de sesión por escaneo, obtención y gestión de tokens, análisis de información de usuario

🔑 Puntos técnicos clave

Especificación de la interfaz API

Uso uniforme del método POST
Autenticación Bearer Token
Prefijo unificado /api
Formato de respuesta estándar: {success: boolean, data: any, errorMsg?: string}

Conversión de formatos de datos

La herramienta utiliza internamente un formato de recopilación de datos amigable para el usuario, que se convierte al formato requerido por la API al enviar:

componentModules → componentList
functionModules → functionList
Matriz de IDs de usuarios → Cadena separada por comas

Estrategia de manejo de errores

Manejo de errores por capas: Nivel de herramienta → Nivel de método → Nivel de API
Información de error detallada: Incluye código de estado HTTP, datos de respuesta, información de pila
Degradación elegante: La falla en la actualización de caché no afecta el flujo principal

Gestión de sesiones

Se utiliza el objeto sessionData para mantener el estado de los flujos de múltiples pasos:

Cada paso de start limpia la sesión
Los datos de cada paso se almacenan de forma independiente
El último paso ensambla los datos completos

📚 Instrucciones de configuración

Configuración global

El proyecto utiliza gestión de configuración integrada; toda la configuración se encuentra en src/config.ts:

Configuración de DingTalk: Se deben configurar el appId y appSecret reales en el código
Puntos finales de la API: Todos los puntos finales de la API están preconfigurados

Si necesitas modificar la dirección o los puntos finales de la API, edita directamente el archivo src/config.ts.

Archivo de configuración a nivel de proyecto (iteration-mcp.config)

La herramienta admite la creación de un archivo iteration-mcp.config en el directorio raíz del proyecto para configurar información específica del proyecto:

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

Prioridad de configuración:

Archivo iteration-mcp.config (recomendado)
Archivo git_info.config.json (compatibilidad hacia atrás)
Detección automática de git remote (respaldo)

Mecanismo de detección del directorio de trabajo

La herramienta utiliza el mecanismo estándar de roots de MCP para detectar automáticamente el directorio de trabajo:

Roots del espacio de trabajo proporcionados por el cliente MCP (mayor prioridad)
Parámetro workdir especificado manualmente
Variables de entorno (PWD, INIT_CWD)
process.cwd() (respaldo)

Cálculo inteligente de horas de trabajo

La herramienta proporciona un cálculo inteligente de horas de trabajo basado en el tiempo real de desarrollo del proyecto:

Rama principal (main/master):

Calcula los días reales desde el primer commit hasta el momento actual
Ejemplo: El proyecto comenzó el 2025-06-22 y hasta el 2025-06-24 = 2 días

Rama de características:

Prioriza el cálculo desde el punto en que la rama se separó de la rama principal
Plan de respaldo: Usa el tiempo del primer commit de la rama
Respaldo final: Estimación basada en la actividad reciente de commits

Reglas de cálculo:

Horas mínimas: 1 día (se eliminó el límite irrazonable de 3 días anterior)
Sin límite máximo (se eliminó el límite superior de 30 días anterior)
Basado en el lapso de tiempo real, no en la cantidad de commits

🚀 Guía de desarrollo secundario

Agregar nuevas herramientas

Agrega la definición en la lista de herramientas de setupHandlers()
Agrega el caso correspondiente en el switch de enrutamiento
Implementa el método handle* correspondiente
Actualiza las definiciones de tipos (si es necesario)

Agregar nuevas interfaces API

Agrega la ruta en endpoints de config.ts
Agrega el método en APIManager
Maneja la autenticación y los errores
Actualiza las definiciones de tipos

Modificar pasos del flujo

Actualiza la enumeración step de la herramienta create_iteration
Agrega un nuevo caso en handleCreateIteration
Implementa el método de manejo correspondiente
Actualiza la estructura de datos de la sesión

🔍 Consejos de depuración

Habilitar registros detallados

El código ya incluye console.log detallados; puedes rastrear el flujo revisando la salida

Usar herramientas de prueba

get_user_list: Prueba la conexión y autenticación de la API
check_login_status: Consulta el estado del sistema

Verificación de datos de sesión

Muestra el contenido de sessionData en cada paso para confirmar que la recopilación de datos sea correcta

📦 Dependencias

@modelcontextprotocol/sdk: Implementación del protocolo MCP
axios: Biblioteca de solicitudes HTTP
child_process: Ejecución de comandos Git
fs/path/os: Operaciones de sistema de archivos y rutas

🎯 Estado de desarrollo

Actualmente es la versión de producción, ya implementada:

✅ Marco básico del servidor MCP
✅ Flujo de inicio de sesión con DingTalk (generación de código QR)
✅ Gestión de almacenamiento local de tokens
✅ Flujo completo de creación y envío de iteraciones en 5 pasos
✅ Gestión de configuración dentro del proyecto
✅ Función de selección de grupo de proyecto
✅ Gestión de lista de usuarios
✅ Envío de API en dos fases
✅ Detección de directorio de trabajo mediante el mecanismo estándar de roots de MCP
✅ Soporte para archivo de configuración iteration-mcp.config
✅ Cálculo inteligente de horas de trabajo (basado en tiempo real de desarrollo)
✅ Lectura de archivos de configuración en múltiples formatos (.config y .json)
✅ Comentarios y documentación detallados

🎯 Mejores prácticas

Mantener la idempotencia de las llamadas a la API
Usar el caché de manera razonable para reducir llamadas a la API
Proporcionar mensajes claros al usuario e información de errores
Mantener la compatibilidad hacia atrás
Actualizar oportunamente la documentación y los comentarios