MCP迭代管理工具

Uma ferramenta de gerenciamento de iteração para automatizar a coleta e o envio de informações de iteração para um sistema CodeReview.

GitHub

Experimente este MCPPatrocinado

Documentação

MCP迭代管理工具

Uma ferramenta de gerenciamento de iterações baseada no Model Context Protocol (MCP), usada principalmente para coletar e enviar automaticamente informações de iterações para o sistema CodeReview da empresa. Suporta login por leitura de código QR do DingTalk e fluxo interativo de criação de iterações.

🚀 Início Rápido

Instalação e Configuração

Compilar o projeto
```
npm install
npm run build
```

Configurar as informações do aplicativo DingTalk Modifique a configuração do DingTalk no arquivo src/config.ts:

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

Após a modificação da configuração, recompile:

npm run build

Configurar o MCP no Cursor Edite o arquivo de configuração do MCP no Cursor e adicione:

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

Fluxo Básico de Uso

No Cursor, chame check_login_status para verificar o status de login
Se não estiver logado, chame login_dingtalk para fazer login via leitura de código QR
Após o login bem-sucedido, use create_iteration para iniciar o fluxo interativo de 5 etapas
Use submit_complete_iteration para enviar a iteração completa e o formulário de solicitação de CR

👥 Guia do Usuário (Configuração para Colegas)

Para usar esta ferramenta MCP no seu ambiente local, siga os passos abaixo para uma configuração única.

1. Preparação do Ambiente

Instalar Node.js: Certifique-se de que o Node.js esteja instalado no seu computador (recomenda-se a versão LTS). npx é uma ferramenta nativa do Node.js e precisamos dela para executar esta ferramenta MCP.
- Você pode verificar se está instalado executando node -v no terminal.

2. Criar o Arquivo de Configuração Global

Este é o passo mais importante: você precisa criar um arquivo de configuração global para armazenar seu token de autenticação pessoal e o endereço da API.

Criar o arquivo:
- No seu diretório home do usuário, crie um arquivo chamado mcp-config.json.
  - macOS/Linux: O caminho do arquivo deve ser ~/.mcp-config.json
  - Windows: O caminho do arquivo deve ser C:\\Users\\YourUsername\\.mcp-config.json
Conteúdo do arquivo de configuração:
- Copie integralmente o conteúdo abaixo para o arquivo mcp-config.json que você criou e substitua o valor de Authorization pelo seu próprio token válido.
```
{
  "api": {
    "baseUrl": "http://xx.xxxxx.com"
  },
  "auth": {
    "Authorization": "Bearer your_personal_token_here"
  }
}
```

3. Configurar no Cursor

Por fim, informe ao Cursor como encontrar e executar esta ferramenta.

Adicionar configuração da ferramenta:
- Adicione o bloco de código JSON abaixo à configuração de "MCP".
```
"iteration-mcp-v2": {
    "name": "iteration-mcp-v2",
    "command": "npx",
    "args": [
        "-y",
        "@asthestarslept/iteration-mcp",
        "--workdir",
        "/path/to/your/project"
    ],
    "description": "用于创建和管理迭代的MCP工具"
}
```
Aviso importante: Substitua /path/to/your/project pelo caminho absoluto do seu projeto real, por exemplo:
- macOS/Linux: /Users/yourname/projects/your-project-name
- Windows: C:\\Users\\yourname\\projects\\your-project-name
Salvar e reiniciar: Salve o arquivo e reinicie o Cursor para carregar a nova ferramenta.

Configuração concluída! Agora você pode usar esta ferramenta no Cursor por meio de @iteration-mcp-v2.

🔧 Lista de Ferramentas

Ferramentas de Autenticação

check_login_status: Verifica o status de login e informações do sistema
login_dingtalk: Login por leitura de código QR do DingTalk

Ferramentas de Gerenciamento de Iteração

create_iteration: Fluxo interativo de criação de iteração em 5 etapas
submit_complete_iteration: Envio de API em duas fases

Ferramentas de Consulta de Dados

get_user_list: Obtém a lista de usuários (participantes e revisores)

📊 Fluxo de Dados

Fluxo de Criação de Iteração em 5 Etapas

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

Fluxo de Envio em Duas Fases

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

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

🏗️ Arquitetura do Projeto

Estrutura de Arquivos

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

Componentes Principais

IterationMCPServer (index.ts)

Responsabilidade: Classe principal do servidor MCP, gerencia todas as solicitações de ferramentas
Funcionalidades principais: Registro e roteamento de ferramentas, gerenciamento do fluxo de criação de iteração em várias etapas, gerenciamento de estado de sessão, tratamento de erros e formatação de respostas

APIManager (api.ts)

Responsabilidade: Encapsula todas as chamadas de API
Funcionalidades principais: Tratamento unificado de solicitações HTTP, gerenciamento de token de autenticação, fluxo de envio em duas fases, conversão de formatos de dados

CacheManager (cache.ts)

Responsabilidade: Cache e gerenciamento de dados locais
Funcionalidades principais: Cache da lista de usuários (válido por 24 horas), histórico de linhas de projeto, gerenciamento de usuários recentes, suporte a upload de imagens OSS

DingTalkAuth (dingtalk.ts)

Responsabilidade: Autenticação por leitura de código QR do DingTalk
Funcionalidades principais: Fluxo de login por código QR, obtenção e gerenciamento de token, análise de informações do usuário

🔑 Pontos Técnicos Chave

Especificação da Interface de API

Uso unificado do método POST
Autenticação Bearer Token
Prefixo unificado /api
Formato de resposta padrão: {success: boolean, data: any, errorMsg?: string}

Conversão de Formatos de Dados

A ferramenta usa internamente um formato de coleta de dados amigável e converte para o formato exigido pela API no momento do envio:

componentModules → componentList
functionModules → functionList
Array de IDs de pessoas → string separada por vírgulas

Estratégia de Tratamento de Erros

Tratamento de erros em camadas: Nível de ferramenta → Nível de método → Nível de API
Informações de erro detalhadas: Inclui código de status HTTP, dados de resposta, informações de stack
Degradação graciosa: Falha na atualização do cache não afeta o fluxo principal

Gerenciamento de Sessão

Usa o objeto sessionData para manter o estado do fluxo em várias etapas:

Cada etapa de start limpa a sessão
Os dados de cada etapa são armazenados de forma independente
A última etapa monta os dados completos

📚 Instruções de Configuração

Configuração Global

O projeto usa gerenciamento de configuração integrado; todas as configurações estão em src/config.ts:

Configuração do DingTalk: É necessário configurar o appId e o appSecret reais no código
Endpoints da API: Todos os endpoints da API já estão pré-configurados

Para modificar o endereço ou os endpoints da API, edite diretamente o arquivo src/config.ts.

Arquivo de Configuração no Nível do Projeto (iteration-mcp.config)

A ferramenta suporta a criação de um arquivo iteration-mcp.config na raiz do projeto para configurar informações específicas do projeto:

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

Prioridade de configuração:

Arquivo iteration-mcp.config (recomendado)
Arquivo git_info.config.json (compatibilidade reversa)
Detecção automática do git remote (fallback)

Mecanismo de Detecção do Diretório de Trabalho

A ferramenta usa o mecanismo padrão de roots do MCP para detectar automaticamente o diretório de trabalho:

Workspace roots fornecidos pelo cliente MCP (maior prioridade)
Parâmetro workdir especificado manualmente
Variáveis de ambiente (PWD, INIT_CWD)
process.cwd() (fallback)

Cálculo Inteligente de Horas de Trabalho

A ferramenta fornece cálculo inteligente de horas de trabalho com base no tempo real de desenvolvimento do projeto:

Branch principal (main/master):

Calcula os dias reais desde o primeiro commit até o momento atual
Exemplo: projeto iniciado em 2025-06-22 até 2025-06-24 = 2 dias

Branch de feature:

Prioriza o cálculo usando o ponto em que o branch se separou do branch principal
Plano de contingência: usa o horário do primeiro commit do branch
Contingência final: estimativa baseada na atividade recente de commits

Regras de cálculo:

Horas mínimas: 1 dia (o limite irracional de 3 dias foi removido)
Sem limite máximo (o limite anterior de 30 dias foi removido)
Baseado no intervalo de tempo real, não na quantidade de commits

🚀 Guia de Desenvolvimento Secundário

Adicionar Nova Ferramenta

Adicione a definição na lista de ferramentas de setupHandlers()
Adicione o case no switch de roteamento
Implemente o método handle* correspondente
Atualize as definições de tipo (se necessário)

Adicionar Nova Interface de API

Adicione o caminho em endpoints de config.ts
Adicione o método em APIManager
Trate autenticação e erros
Atualize as definições de tipo

Modificar Etapas do Fluxo

Atualize a enumeração step da ferramenta create_iteration
Adicione um novo case em handleCreateIteration
Implemente o método de tratamento correspondente
Atualize a estrutura de dados da sessão

🔍 Dicas de Depuração

Ativar Logs Detalhados

O código já contém console.log detalhados; você pode acompanhar o fluxo visualizando a saída

Usar Ferramentas de Teste

get_user_list: Testa a conexão e autenticação da API
check_login_status: Visualiza o status do sistema

Verificação de Dados de Sessão

Em cada etapa, exiba o conteúdo de sessionData para confirmar que a coleta de dados está correta

📦 Dependências

@modelcontextprotocol/sdk: Implementação do protocolo MCP
axios: Biblioteca de solicitações HTTP
child_process: Execução de comandos Git
fs/path/os: Operações de sistema de arquivos e caminhos

🎯 Status de Desenvolvimento

Atualmente é a versão de produção, com as seguintes funcionalidades implementadas:

✅ Estrutura básica do servidor MCP
✅ Fluxo de login do DingTalk (geração de código QR)
✅ Gerenciamento de armazenamento local de tokens
✅ Fluxo completo de criação e envio de iteração em 5 etapas
✅ Gerenciamento de configuração dentro do projeto
✅ Seleção de grupo de projeto
✅ Gerenciamento de lista de usuários
✅ Envio de API em duas fases
✅ Detecção de diretório de trabalho via mecanismo padrão de roots do MCP
✅ Suporte ao arquivo de configuração iteration-mcp.config
✅ Cálculo inteligente de horas de trabalho (baseado no tempo real de desenvolvimento)
✅ Leitura de arquivos de configuração em múltiplos formatos (.config e .json)
✅ Comentários e documentação detalhados

🎯 Melhores Práticas

Manter a idempotência das chamadas de API
Usar cache de forma racional para reduzir chamadas de API
Fornecer prompts claros e mensagens de erro para o usuário
Manter compatibilidade reversa
Atualizar documentação e comentários regularmente