Redmine

Un servidor MCP para interactuar con el sistema de gestión de proyectos Redmine.

GitHub

Documentación

Servidor MCP de Redmine

CI CodeQL

Un servidor de Protocolo de Contexto de Modelo (MCP) para la integración con Redmine, construido con TypeScript siguiendo la metodología TDD. Este servidor permite a los asistentes de IA interactuar con instancias de Redmine para gestionar incidencias, proyectos y usuarios con características integrales de seguridad y monitoreo.

Características

  • Gestión de Incidencias: Crear, leer, actualizar y listar incidencias
  • Gestión de Proyectos: Listar y ver detalles de proyectos
  • Gestión de Usuarios: Listar y ver información de usuarios
  • Manejo de Errores: Manejo integral de errores con mensajes significativos
  • Seguridad de Tipos: Implementación completa en TypeScript con definiciones de tipos adecuadas

Instalación

npm install
npm run build

Configuración

El servidor requiere dos variables de entorno:

  • REDMINE_BASE_URL: La URL base de tu instancia de Redmine (por ejemplo, https://redmine.example.com)
  • REDMINE_API_KEY: Tu clave de API de Redmine (se encuentra en la configuración de tu cuenta)

Uso

Ejecutar el Servidor

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

Compilar y Ejecutar

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

Despliegue en Producción

# 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

Herramientas Disponibles

Herramientas de Incidencias

  • list-issues: Listar incidencias con filtrado opcional

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

  • create-issue: Crear una nueva incidencia

    • Requeridos: project_id, subject
    • Opcionales: description, tracker_id, status_id, priority_id, assigned_to_id

  • get-issue: Obtener detalles de una incidencia específica

    • Requerido: id

  • update-issue: Actualizar una incidencia existente

    • Requerido: id
    • Opcionales: subject, description, status_id, priority_id, assigned_to_id, done_ratio

Herramientas de Proyectos

  • list-projects: Listar todos los proyectos

  • get-project: Obtener detalles de un proyecto específico

    • Requerido: id (puede ser un ID numérico o un identificador de cadena)

Herramientas de Usuarios

  • list-users: Listar todos los usuarios

  • get-user: Obtener detalles de un usuario específico

    • Requerido: id

Desarrollo

Ejecutar Pruebas

npm test

Ejecutar Pruebas con Cobertura

npm run test:coverage

Ejecutar en Modo de Observación

npm run test:watch

Linting

npm run lint

Verificación de Tipos

npm run typecheck

Limpiar Directorio de Compilación

npm run clean

Referencia de la API

RedmineClient

El cliente principal para interactuar con la API REST de Redmine.

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

RedmineMcpServer

El servidor MCP que expone la funcionalidad de Redmine como herramientas MCP.

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

await server.start();

Manejo de Errores

El servidor proporciona un manejo integral de errores para escenarios comunes:

  • Errores de autenticación (401): Clave de API inválida
  • Errores de autorización (403): Permisos insuficientes
  • Errores de no encontrado (404): El recurso no existe
  • Errores de validación (422): Datos proporcionados inválidos
  • Errores del servidor (500): Problemas internos del servidor
  • Errores de red: Tiempos de espera de conexión y problemas de red
  • Validación de entrada: Validación del lado del cliente con mensajes de error detallados

Registro de Actividades

El servidor incluye registro estructurado con niveles configurables:

  • DEBUG: Información detallada de ejecución y datos de solicitud/respuesta
  • INFO: Información operativa general (predeterminado)
  • WARN: Condiciones de advertencia que no afectan la operación
  • ERROR: Condiciones de error que requieren atención

Configure el nivel de registro usando la variable de entorno LOG_LEVEL:

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

Contribuciones

  1. Haga un fork del repositorio
  2. Cree una rama de características
  3. Realice sus cambios
  4. Agregue pruebas para la nueva funcionalidad
  5. Ejecute el conjunto de pruebas
  6. Envíe una solicitud de extracción

Licencia

Licencia MIT