Redmine

Um servidor MCP para interagir com o sistema de gerenciamento de projetos Redmine.

GitHub

Documentação

Servidor MCP Redmine

CI CodeQL

Um servidor Model Context Protocol (MCP) para integração com Redmine, construído com TypeScript seguindo a metodologia TDD. Este servidor permite que assistentes de IA interajam com instâncias do Redmine para gerenciar issues, projetos e usuários com recursos abrangentes de segurança e monitoramento.

Recursos

  • Gerenciamento de Issues: Criar, ler, atualizar e listar issues
  • Gerenciamento de Projetos: Listar e visualizar detalhes de projetos
  • Gerenciamento de Usuários: Listar e visualizar informações de usuários
  • Tratamento de Erros: Tratamento abrangente de erros com mensagens de erro significativas
  • Segurança de Tipos: Implementação completa em TypeScript com definições de tipos adequadas

Instalação

npm install
npm run build

Configuração

O servidor requer duas variáveis de ambiente:

  • REDMINE_BASE_URL: A URL base da sua instância do Redmine (ex.: https://redmine.example.com)
  • REDMINE_API_KEY: Sua chave de API do Redmine (encontrada nas configurações da sua conta)

Uso

Executando o Servidor

export REDMINE_BASE_URL="https://your-redmine-instance.com"
export REDMINE_API_KEY="your-api-key-here"
npm run dev

Compilando e Executando

npm run build
export REDMINE_BASE_URL="https://your-redmine-instance.com"
export REDMINE_API_KEY="your-api-key-here"
npm start

Implantação em Produção

# Build the project
npm run build

# Set production environment variables
export REDMINE_BASE_URL="https://your-redmine-instance.com"
export REDMINE_API_KEY="your-api-key-here"
export LOG_LEVEL="info"

# Start the server
npm start

Ferramentas Disponíveis

Ferramentas de Issues

  • list-issues: Lista issues com filtragem opcional

    • Parâmetros: project_id, status_id, assigned_to_id, limit, offset

  • create-issue: Cria uma nova issue

    • Obrigatório: project_id, subject
    • Opcional: description, tracker_id, status_id, priority_id, assigned_to_id

  • get-issue: Obtém detalhes de uma issue específica

    • Obrigatório: id

  • update-issue: Atualiza uma issue existente

    • Obrigatório: id
    • Opcional: subject, description, status_id, priority_id, assigned_to_id, done_ratio

Ferramentas de Projetos

  • list-projects: Lista todos os projetos

  • get-project: Obtém detalhes de um projeto específico

    • Obrigatório: id (pode ser ID numérico ou identificador de string)

Ferramentas de Usuários

  • list-users: Lista todos os usuários

  • get-user: Obtém detalhes de um usuário específico

    • Obrigatório: id

Desenvolvimento

Executando Testes

npm test

Executando Testes com Cobertura

npm run test:coverage

Executando em Modo de Observação

npm run test:watch

Linting

npm run lint

Verificação de Tipos

npm run typecheck

Limpar Diretório de Build

npm run clean

Referência da API

RedmineClient

O cliente principal para interagir com a API REST do Redmine.

const client = new RedmineClient({
  baseUrl: 'https://redmine.example.com',
  apiKey: 'your-api-key'
});

RedmineMcpServer

O servidor MCP que expõe a funcionalidade do Redmine como ferramentas MCP.

const server = new RedmineMcpServer({
  baseUrl: 'https://redmine.example.com',
  apiKey: 'your-api-key'
});

await server.start();

Tratamento de Erros

O servidor fornece tratamento abrangente de erros para cenários comuns:

  • Erros de autenticação (401): Chave de API inválida
  • Erros de autorização (403): Permissões insuficientes
  • Erros de não encontrado (404): Recurso não existe
  • Erros de validação (422): Dados inválidos fornecidos
  • Erros de servidor (500): Problemas internos do servidor
  • Erros de rede: Timeouts de conexão e problemas de rede
  • Validação de entrada: Validação no lado do cliente com mensagens de erro detalhadas

Registro

O servidor inclui registro estruturado com níveis configuráveis:

  • DEBUG: Informações detalhadas de execução e dados de requisição/resposta
  • INFO: Informações operacionais gerais (padrão)
  • WARN: Condições de aviso que não afetam a operação
  • ERROR: Condições de erro que exigem atenção

Configure o nível de log usando a variável de ambiente LOG_LEVEL:

export LOG_LEVEL="debug"  # For development
export LOG_LEVEL="info"   # For production (default)
export LOG_LEVEL="error"  # For minimal logging

Contribuindo

  1. Faça um fork do repositório
  2. Crie um branch de funcionalidade
  3. Faça suas alterações
  4. Adicione testes para novas funcionalidades
  5. Execute a suíte de testes
  6. Envie um pull request

Licença

Licença MIT