MCP GitHub Project Manager

Gestión de proyectos de GitHub impulsada por IA con trazabilidad completa de requisitos.

Documentación

MCP GitHub Project Manager

Un servidor integral del Model Context Protocol (MCP) que proporciona capacidades avanzadas de gestión de proyectos de GitHub con gestión de tareas impulsada por IA y trazabilidad completa de requisitos. Transforma tus ideas de proyecto en tareas accionables con seguimiento integral de extremo a extremo, desde requisitos de negocio hasta la implementación.

Descripción general

Este servidor implementa el Model Context Protocol para proporcionar una gestión integral de proyectos de GitHub con capacidades avanzadas de IA. Más allá de la gestión de proyectos tradicional, ofrece generación de tareas impulsada por IA, trazabilidad de requisitos y planificación inteligente de proyectos a través de la API GraphQL de GitHub, manteniendo el estado y manejando errores según las especificaciones de MCP.

🚀 ¿Qué lo hace especial?

Impulsado por IA: Transforma ideas de proyecto en PRD completos y tareas accionables utilizando múltiples proveedores de IA
Trazabilidad completa: Seguimiento integral de extremo a extremo desde requisitos de negocio → características → casos de uso → tareas
Análisis inteligente: Análisis de complejidad impulsado por IA, estimación de esfuerzo y recomendaciones de tareas
Estándares profesionales: Documentación de requisitos conforme a IEEE 830 con gestión de cambios de nivel empresarial

Inicio rápido

Usando NPM

# Install the package globally
npm install -g mcp-github-project-manager

# Set up your environment variables
export GITHUB_TOKEN="your_github_token"
export GITHUB_OWNER="your_github_username_or_organization"
export GITHUB_REPO="your_repository_name"

# Run the MCP server
mcp-github-project-manager

Usando Docker

# Build the Docker image
docker build -t mcp-github-project-manager .

# Run with environment variables
docker run -it \
  -e GITHUB_TOKEN=your_github_token \
  -e GITHUB_OWNER=your_github_username_or_organization \
  -e GITHUB_REPO=your_repository_name \
  mcp-github-project-manager

Para más detalles sobre el uso de Docker, consulta DOCKER.md.

Características clave

🤖 Gestión de tareas impulsada por IA

Generación de PRD (generate_prd): Transforma ideas de proyecto en Documentos de Requisitos de Producto completos
Desglose inteligente de tareas (parse_prd): Análisis de PRD impulsado por IA para convertirlos en tareas de desarrollo accionables
Adición inteligente de características (add_feature): Agrega nuevas características con análisis automático de impacto y generación de tareas
Análisis de complejidad de tareas (analyze_task_complexity): Análisis detallado de IA sobre complejidad de tareas, estimación de esfuerzo y evaluación de riesgos
Recomendaciones de próximas tareas (get_next_task): Recomendaciones impulsadas por IA para la priorización óptima de tareas
Expansión de tareas (expand_task): Desglosa automáticamente tareas complejas en subtareas manejables
Mejora de PRD (enhance_prd): Mejora PRD existentes con análisis de brechas y mejoras impulsadas por IA

🎯 Generación mejorada de contexto de tareas

Contexto basado en trazabilidad (Predeterminado): Contexto enriquecido de la trazabilidad de requisitos sin dependencia de IA
Contexto mejorado con IA (Opcional): Contexto integral de negocio, técnico y de implementación usando IA
Niveles de contexto configurables: Elige entre profundidad de contexto mínima, estándar y completa
Contexto de negocio: Extrae objetivos de negocio, impacto en el usuario y métricas de éxito
Contexto técnico: Analiza restricciones técnicas, decisiones de arquitectura y puntos de integración
Orientación de implementación: Recomendaciones paso a paso generadas por IA para la implementación
Referencias contextuales: Enlaces a secciones relevantes del PRD, características y especificaciones técnicas
Criterios de aceptación mejorados: Criterios detallados y comprobables con métodos de verificación
Degradación elegante: Funciona perfectamente sin claves de IA, recurre al contexto basado en trazabilidad

🔗 Trazabilidad completa de requisitos

Seguimiento de extremo a extremo (create_traceability_matrix): Trazabilidad completa desde requisitos de negocio del PRD → características → casos de uso → tareas
Enlaces bidireccionales: Trazabilidad bidireccional completa con análisis de impacto
Gestión de casos de uso: Generación y seguimiento profesional de casos de uso actor-objetivo-escenario
Análisis de cobertura: Métricas integrales de cobertura con identificación de brechas
Detección de tareas huérfanas: Identifica tareas sin enlaces a requisitos
Análisis de impacto de cambios: Rastrea cambios de requisitos y su impacto en todos los niveles

📊 Soporte multi-proveedor de IA

Anthropic Claude: Proveedor principal de IA para razonamiento complejo
OpenAI GPT: Proveedor alternativo con soporte de respaldo
Google Gemini: Capacidades adicionales de IA
Perplexity: Tareas de investigación y análisis
Respaldo automático: Cambio fluido entre proveedores

🏗️ Gestión de proyectos principal

Gestión de proyectos: Crea y gestiona Proyectos de GitHub (v2)
Issues e hitos: Operaciones CRUD completas con filtrado avanzado
Planificación de sprints: Planifica y gestiona sprints de desarrollo con asistencia de IA
Campos y vistas personalizados: Crea diferentes vistas (tablero, tabla, cronograma, hoja de ruta)
Versionado de recursos: Caché inteligente y bloqueo optimista

⚡ Características avanzadas

Implementación MCP: Cumplimiento completo de la especificación MCP con validación Zod
Integración con GitHub: Integración con la API GraphQL con limitación de velocidad inteligente
Sincronización en tiempo real: Sincronización bidireccional con GitHub
Integración de webhooks: Actualizaciones en tiempo real mediante webhooks de GitHub
Seguimiento de progreso: Métricas integrales e informes de progreso
Sistema de eventos: Rastrea y reproduce eventos del proyecto

Instalación

Opción 1: Instalar desde npm (recomendado)

# Install the package globally
npm install -g mcp-github-project-manager

# Or install in your project
npm install mcp-github-project-manager

Opción 2: Instalar desde el código fuente

# Clone the repository
git clone https://github.com/kunwarVivek/mcp-github-project-manager.git
cd mcp-github-project-manager

# Install dependencies
npm install
# or
pnpm install

# Build the project
npm run build

Configurar variables de entorno

# Copy the example environment file
cp .env.example .env

# Edit .env with your GitHub token and details

Configuración

Variables de entorno requeridas

Configuración de GitHub

GITHUB_TOKEN=your_github_token
GITHUB_OWNER=repository_owner
GITHUB_REPO=repository_name

El token de GitHub requiere estos permisos:

repo (Acceso completo al repositorio)
project (Acceso a proyectos)
write:org (Acceso a la organización)

Configuración del proveedor de IA

Se requiere al menos un proveedor de IA para las funciones impulsadas por IA:

# Primary AI providers (at least one required)
ANTHROPIC_API_KEY=your_anthropic_api_key_here
OPENAI_API_KEY=your_openai_api_key_here
GOOGLE_API_KEY=your_google_api_key_here
PERPLEXITY_API_KEY=your_perplexity_api_key_here

# AI Model Configuration (optional - uses defaults if not specified)
AI_MAIN_MODEL=claude-3-5-sonnet-20241022
AI_RESEARCH_MODEL=perplexity-llama-3.1-sonar-large-128k-online
AI_FALLBACK_MODEL=gpt-4o
AI_PRD_MODEL=claude-3-5-sonnet-20241022

# AI Task Generation Configuration (optional)
MAX_TASKS_PER_PRD=50
DEFAULT_COMPLEXITY_THRESHOLD=7
MAX_SUBTASK_DEPTH=3
AUTO_DEPENDENCY_DETECTION=true
AUTO_EFFORT_ESTIMATION=true

# Enhanced Task Context Generation Configuration (optional)
ENHANCED_TASK_GENERATION=true
AUTO_CREATE_TRACEABILITY=true
AUTO_GENERATE_USE_CASES=true
AUTO_CREATE_LIFECYCLE=true
ENHANCED_CONTEXT_LEVEL=standard
INCLUDE_BUSINESS_CONTEXT=false
INCLUDE_TECHNICAL_CONTEXT=false
INCLUDE_IMPLEMENTATION_GUIDANCE=false

Configuración del proveedor de IA

Anthropic Claude

Regístrate en Anthropic Console
Crea una clave de API
Establece ANTHROPIC_API_KEY en tu entorno

OpenAI

Regístrate en OpenAI Platform
Crea una clave de API
Establece OPENAI_API_KEY en tu entorno

Google Gemini

Regístrate en Google AI Studio
Crea una clave de API
Establece GOOGLE_API_KEY en tu entorno

Perplexity

Regístrate en Perplexity API
Crea una clave de API
Establece PERPLEXITY_API_KEY en tu entorno

Uso

Como herramienta de línea de comandos

Si se instala globalmente:

# Start the MCP server using stdio transport
mcp-github-project-manager

# Start with environment variables
GITHUB_TOKEN=your_token mcp-github-project-manager

# Start with command line arguments
mcp-github-project-manager --token=your_token --owner=your_username --repo=your_repo

# Use a specific .env file
mcp-github-project-manager --env-file=.env.production

# Show verbose output
mcp-github-project-manager --verbose

# Display help information
mcp-github-project-manager --help

Ejecución desde el código fuente con TypeScript

Si estás desarrollando o ejecutando desde el código fuente:

# Run directly with ts-node
node --loader ts-node/esm src/index.ts

# Run with command line arguments
node --loader ts-node/esm src/index.ts --token=your_token --owner=your_username --repo=your_repo

# Use the npm dev script (watches for changes)
npm run dev

# Display help information
node --loader ts-node/esm src/index.ts --help

Opciones de línea de comandos

Opción	Corta	Descripción
`--token <token>`	`-t`	Token de acceso personal de GitHub
`--owner <owner>`	`-o`	Propietario del repositorio de GitHub (usuario u organización)
`--repo <repo>`	`-r`	Nombre del repositorio de GitHub
`--env-file <path>`	`-e`	Ruta al archivo .env (predeterminado: .env en la raíz del proyecto)
`--verbose`	`-v`	Habilita el registro detallado
`--help`	`-h`	Muestra información de ayuda
`--version`		Muestra información de versión

Los argumentos de línea de comandos tienen prioridad sobre las variables de entorno.

Como módulo de Node.js

import { Server } from "mcp-github-project-manager";

// Create and start an MCP server instance
const server = new Server({
  transport: "stdio", // or "http" for HTTP server
  config: {
    githubToken: process.env.GITHUB_TOKEN,
    githubOwner: process.env.GITHUB_OWNER,
    githubRepo: process.env.GITHUB_REPO
  }
});

server.start();

Integración con clientes MCP

// Example using an MCP client library
import { McpClient } from "@modelcontextprotocol/client";
import { spawn } from "child_process";

// Create a child process running the MCP server
const serverProcess = spawn("mcp-github-project-manager", [], {
  env: { ...process.env, GITHUB_TOKEN: "your_token" }
});

// Connect the MCP client to the server
const client = new McpClient({
  transport: {
    type: "process",
    process: serverProcess
  }
});

// Call MCP tools
const result = await client.callTool("create_project", {
  title: "My Project",
  description: "A new GitHub project"
});

Para más ejemplos, consulta la Guía de usuario y el directorio examples/.

Ejemplos de uso de herramientas de IA

Flujo de trabajo completo del proyecto

# 1. Generate PRD from project idea
generate_prd({
  "projectIdea": "AI-powered task management system with real-time collaboration",
  "projectName": "TaskAI Pro",
  "author": "product-team",
  "complexity": "high",
  "timeline": "6 months",
  "includeResearch": true
})

# 2. Parse PRD and generate tasks with traceability
parse_prd({
  "prdContent": "<generated PRD content>",
  "maxTasks": 30,
  "createTraceabilityMatrix": true,
  "includeUseCases": true,
  "projectId": "task-ai-pro"
})

# 3. Get next task recommendations
get_next_task({
  "sprintCapacity": 40,
  "teamSkills": ["react", "node.js", "typescript"],
  "maxComplexity": 7,
  "includeAnalysis": true
})

# 4. Analyze complex tasks
analyze_task_complexity({
  "taskTitle": "Implement real-time collaboration",
  "taskDescription": "Build WebSocket-based real-time collaboration with conflict resolution",
  "teamExperience": "mixed",
  "includeBreakdown": true,
  "includeRisks": true
})

# 5. Break down complex tasks
expand_task({
  "taskTitle": "Build analytics dashboard",
  "taskDescription": "Create comprehensive analytics dashboard with AI insights",
  "currentComplexity": 8,
  "targetComplexity": 3,
  "includeEstimates": true,
  "includeDependencies": true
})

Flujo de trabajo de adición de características

# Add new feature with complete lifecycle
add_feature({
  "featureIdea": "Advanced Analytics Dashboard",
  "description": "Real-time analytics with custom charts and AI-powered insights",
  "requestedBy": "product-manager",
  "businessJustification": "Increase user engagement and provide actionable insights",
  "targetUsers": ["project-managers", "team-leads", "executives"],
  "autoApprove": true,
  "expandToTasks": true,
  "createLifecycle": true
})

# This automatically creates:
# ✅ Business requirement analysis
# ✅ Use cases with actor-goal-scenario structure
# ✅ Tasks with complete traceability links
# ✅ Lifecycle tracking for all tasks

Trazabilidad de requisitos

# Create comprehensive traceability matrix
create_traceability_matrix({
  "projectId": "task-ai-pro",
  "prdContent": "<PRD content>",
  "features": [...],
  "tasks": [...],
  "validateCompleteness": true
})

# Output includes:
# ✅ Business Requirements → Features → Use Cases → Tasks
# ✅ Bidirectional traceability links
# ✅ Coverage analysis with gap identification
# ✅ Orphaned task detection
# ✅ Unimplemented requirement tracking

Generación mejorada de contexto de tareas

# Default: Traceability-based context (fast, no AI required)
parse_prd({
  "prdContent": "<PRD content>",
  "enhancedGeneration": true,
  "contextLevel": "standard"
})

# Enhanced: AI-powered comprehensive context
parse_prd({
  "prdContent": "<PRD content>",
  "enhancedGeneration": true,
  "contextLevel": "full",
  "includeBusinessContext": true,
  "includeTechnicalContext": true,
  "includeImplementationGuidance": true
})

# Performance optimized: Minimal context for speed
parse_prd({
  "prdContent": "<PRD content>",
  "enhancedGeneration": true,
  "contextLevel": "minimal",
  "includeBusinessContext": false,
  "includeTechnicalContext": false,
  "includeImplementationGuidance": false
})

Niveles de generación de contexto:

Mínimo: Solo contexto básico de trazabilidad (más rápido)
Estándar: Trazabilidad + contexto básico de negocio (predeterminado)
Completo: Contexto completo mejorado con IA e orientación de implementación

El contexto de tareas generado incluye:

Contexto de negocio: Por qué importa la tarea, impacto en el usuario, métricas de éxito
Contexto de característica: Información de la característica principal, historias de usuario, valor de negocio
Contexto técnico: Restricciones, decisiones de arquitectura, puntos de integración
Orientación de implementación: Recomendaciones paso a paso, mejores prácticas, errores comunes
Criterios de aceptación mejorados: Métodos de verificación detallados y prioridades
Referencias contextuales: Enlaces a secciones relevantes del PRD y especificaciones técnicas

🧪 Pruebas de generación de contexto mejorado

La funcionalidad de generación de contexto mejorado incluye una cobertura de pruebas integral:

Archivos de prueba creados:

src/__tests__/TaskContextGenerationService.test.ts - Pruebas del servicio principal de generación de contexto
src/__tests__/TaskGenerationService.enhanced.test.ts - Pruebas de integración de generación de tareas mejoradas
src/__tests__/ParsePRDTool.enhanced.test.ts - Pruebas de generación de contexto a nivel de herramienta

Cobertura de pruebas:

Generación de contexto basada en trazabilidad (comportamiento predeterminado)
Generación de contexto mejorada con IA (cuando la IA está disponible)
Respaldo elegante cuando los servicios de IA no están disponibles
Validación de configuración y manejo de variables de entorno
Manejo de errores y pruebas de resiliencia
Pruebas de integración con el pipeline existente de generación de tareas

Ejecución de pruebas de generación de contexto:

# Run all AI-related tests (includes context generation)
npm run test:ai

# Run specific context generation tests
npm test -- --testPathPattern="TaskContextGeneration"
npm test -- --testPathPattern="enhanced"

# Run all tests
npm test

🧪 Suite integral de pruebas E2E

El MCP GitHub Project Manager incluye una suite integral de pruebas de extremo a extremo que prueba todas las herramientas MCP a través de la interfaz MCP real con llamadas API simuladas y reales.

Cobertura de pruebas:

✅ 40+ Herramientas de gestión de proyectos de GitHub - Operaciones CRUD completas para proyectos, hitos, issues, sprints, etiquetas y más
✅ 8 Herramientas de gestión de tareas con IA - Generación de PRD, análisis de tareas, análisis de complejidad, gestión de características y trazabilidad
✅ Integración de flujos de trabajo complejos - Flujos de trabajo multi-herramienta y escenarios reales de gestión de proyectos
✅ Pruebas de API reales - Pruebas opcionales con APIs reales de GitHub e IA
✅ Validación de esquemas - Validación integral de argumentos para todas las herramientas
✅ Manejo de errores - Manejo elegante de errores y pruebas de recuperación

Inicio rápido:

# Run comprehensive E2E tests (mocked APIs)
npm run test:e2e:tools

# Run with real APIs (requires credentials)
npm run test:e2e:tools:real

# Use the interactive test runner
npm run test:e2e:runner

# Run specific test categories
npm run test:e2e:tools:github     # GitHub tools only
npm run test:e2e:tools:ai         # AI tools only
npm run test:e2e:tools:workflows  # Integration workflows

Opciones del ejecutor de pruebas:

# Interactive test runner with options
node scripts/run-e2e-tests.js --help

# Examples:
node scripts/run-e2e-tests.js --real-api --github-only
node scripts/run-e2e-tests.js --build --verbose --timeout 120
node scripts/run-e2e-tests.js --ai-only --real-api

Configuración del entorno para pruebas de API reales:

API de GitHub (requerida para herramientas de GitHub):

GITHUB_TOKEN=ghp_your_github_token
GITHUB_OWNER=your-github-username
GITHUB_REPO=your-test-repository

APIs de IA (requeridas para herramientas de IA):

# At least one AI API key required
ANTHROPIC_API_KEY=sk-ant-your-anthropic-key
OPENAI_API_KEY=sk-your-openai-key
GOOGLE_API_KEY=your-google-ai-key
PERPLEXITY_API_KEY=pplx-your-perplexity-key

Habilitar pruebas de API reales:

E2E_REAL_API=true npm run test:e2e:tools:real

Características de las pruebas:

Validación de registro de herramientas - Verifica que todas las herramientas estén registradas correctamente con esquemas adecuados
Cumplimiento del protocolo MCP - Asegura que todas las herramientas sigan la especificación MCP
Validación del formato de respuesta - Valida que las respuestas de las herramientas coincidan con los formatos esperados
Pruebas de integración de flujos de trabajo - Prueba flujos de trabajo complejos multi-herramienta
Gestión de credenciales - Manejo elegante de credenciales faltantes
Monitoreo de rendimiento - Rastrea el rendimiento de ejecución de las herramientas
Pruebas integrales de errores - Valida el manejo de errores y la recuperación

Documentación:

📖 Guía integral de pruebas E2E - Documentación detallada de pruebas
🔧 Configuración de pruebas - Configuración de Jest para pruebas E2E
🛠️ Utilidades de prueba - Utilidades de prueba reutilizables La suite de pruebas E2E garantiza que todas las herramientas MCP funcionen correctamente tanto de forma individual como en flujos de trabajo complejos, proporcionando confianza en la fiabilidad e integración de todo el sistema.

Escenarios de prueba cubiertos:

✅ Contexto basado en trazabilidad por defecto (sin necesidad de IA)
✅ Generación de contexto de negocio mejorado con IA
✅ Generación de contexto técnico mejorado con IA
✅ Generación de guía de implementación
✅ Fusión de contextos y resolución de conflictos
✅ Manejo de errores y degradación gradual
✅ Validación de configuración y valores predeterminados
✅ Validación de parámetros a nivel de herramienta
✅ Integración con el sistema de trazabilidad existente

Instalación en Asistentes de IA

Instalar en Claude

Para instalar el servidor MCP en Claude Desktop:

{
  "mcpServers": {
    "github-project-manager": {
      "command": "npx",
      "args": ["-y", "mcp-github-project-manager"],
      "env": {
        "GITHUB_TOKEN": "your_github_token",
        "GITHUB_OWNER": "your_username",
        "GITHUB_REPO": "your_repo",
        "ANTHROPIC_API_KEY": "your_anthropic_api_key",
        "OPENAI_API_KEY": "your_openai_api_key",
        "GOOGLE_API_KEY": "your_google_api_key",
        "PERPLEXITY_API_KEY": "your_perplexity_api_key"
      }
    }
  }
}

Para Claude Code CLI, ejecute:

claude mcp add github-project-manager -- npx -y mcp-github-project-manager

Instalar en Roocode

Añada esto a su configuración de Roocode:

{
  "mcpServers": {
    "github-project-manager": {
      "command": "npx",
      "args": ["-y", "mcp-github-project-manager"],
      "env": {
        "GITHUB_TOKEN": "your_github_token",
        "GITHUB_OWNER": "your_username",
        "GITHUB_REPO": "your_repo"
      }
    }
  }
}

Instalar en Windsurf

Añada esto al archivo de configuración MCP de Windsurf:

{
  "mcpServers": {
    "github-project-manager": {
      "command": "npx",
      "args": ["-y", "mcp-github-project-manager"],
      "env": {
        "GITHUB_TOKEN": "your_github_token",
        "GITHUB_OWNER": "your_username",
        "GITHUB_REPO": "your_repo"
      }
    }
  }
}

Consulte Documentación de Windsurf MCP para más información.

Instalar en VS Code

Añada esto al archivo de configuración MCP de VS Code:

{
  "servers": {
    "github-project-manager": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-github-project-manager"],
      "env": {
        "GITHUB_TOKEN": "your_github_token",
        "GITHUB_OWNER": "your_username",
        "GITHUB_REPO": "your_repo"
      }
    }
  }
}

Consulte Documentación de VS Code MCP para más información.

Instalar en Cursor

Añada esto al archivo de configuración MCP de Cursor:

{
  "mcpServers": {
    "github-project-manager": {
      "command": "npx",
      "args": ["-y", "mcp-github-project-manager"],
      "env": {
        "GITHUB_TOKEN": "your_github_token",
        "GITHUB_OWNER": "your_username",
        "GITHUB_REPO": "your_repo"
      }
    }
  }
}

Consulte Documentación de Cursor MCP para más información.

Usando Docker

Si prefiere ejecutar el servidor MCP en un contenedor Docker:

Construir la imagen Docker:

Cree un Dockerfile en el directorio de su proyecto:

FROM node:18-alpine

WORKDIR /app

# Install the package globally
RUN npm install -g mcp-github-project-manager

# Default command to run the server
CMD ["mcp-github-project-manager"]

Construya la imagen:

docker build -t github-project-manager-mcp .

Configurar su cliente MCP:

Actualice la configuración de su cliente MCP para usar el comando Docker:

{
  "mcpServers": {
    "github-project-manager": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "github-project-manager-mcp"],
      "env": {
        "GITHUB_TOKEN": "your_github_token",
        "GITHUB_OWNER": "your_username",
        "GITHUB_REPO": "your_repo"
      }
    }
  }
}

Solución de problemas

Problemas comunes

Errores de módulo no encontrado

Si encuentra problemas de resolución de módulos, intente usar bunx en lugar de npx:

{
  "mcpServers": {
    "github-project-manager": {
      "command": "bunx",
      "args": ["-y", "mcp-github-project-manager"]
    }
  }
}

Configuración específica para Windows

En Windows, es posible que necesite usar cmd para ejecutar el comando:

{
  "mcpServers": {
    "github-project-manager": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "mcp-github-project-manager"
      ]
    }
  }
}

Problemas de permisos

Si encuentra problemas de permisos, asegúrese de que su token de GitHub tenga los permisos requeridos enumerados en la sección de Configuración.

Arquitectura

El servidor sigue los principios de Arquitectura Limpia con capas distintas:

Capa de Dominio: Entidades centrales, interfaces de repositorio y esquemas Zod
Capa de Infraestructura: Integración e implementaciones de la API de GitHub
Capa de Servicios: Coordinación de la lógica de negocio
Capa MCP: Definiciones de herramientas y manejo de solicitudes

Consulte ARCHITECTURE.md para documentación detallada de la arquitectura.

Contribuciones

¡Las contribuciones son bienvenidas! Consulte CONTRIBUTING.md para conocer las pautas.

Haga un fork del repositorio
Cree una rama de funcionalidad: git checkout -b feature/amazing-feature
Confirme sus cambios: git commit -m 'Add some amazing feature'
Envíe a la rama: git push origin feature/amazing-feature
Abra una Solicitud de Extracción

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulte el archivo LICENSE para más detalles.

Referencias

Estado Actual

Funcionalidades Principales

Funcionalidad	Estado	Notas
Creación de Proyectos	✅ Completa	Soporte completo para proyectos v2
Gestión de Hitos	✅ Completa	Operaciones CRUD implementadas
Planificación de Sprints	✅ Completa	Incluye seguimiento de métricas
Gestión de Incidencias	✅ Completa	Con soporte de campos personalizados
Versionado de Recursos	✅ Completa	Con bloqueo optimista y validación de esquemas
Integración de Webhooks	📅 Planificada	Actualizaciones en tiempo real

Funcionalidades Impulsadas por IA

Funcionalidad	Estado	Notas
Generación de PRD	✅ Completa	Soporte de IA multi-proveedor con creación integral de PRD
Generación de Tareas	✅ Completa	Análisis de PRD impulsado por IA en tareas accionables
Adición de Funcionalidades	✅ Completa	Adición inteligente de funcionalidades con análisis de impacto
Análisis de Complejidad de Tareas	✅ Completo	Análisis detallado de IA con evaluación de riesgos
Recomendaciones de Tareas	✅ Completo	Recomendaciones de próximas tareas impulsadas por IA
Expansión de Tareas	✅ Completa	Desglose de tareas complejas en subtareas
Mejora de PRD	✅ Completa	Mejora de PRD impulsada por IA y análisis de brechas
Trazabilidad de Requisitos	✅ Completa	Matriz de trazabilidad de extremo a extremo con análisis de cobertura

Trazabilidad de Requisitos

Funcionalidad	Estado	Notas
Extracción de Requisitos de Negocio	✅ Completa	Extracción de objetivos de PRD y métricas de éxito
Generación de Casos de Uso	✅ Completa	Estructura actor-objetivo-escenario con alternativas
Enlaces de Trazabilidad	✅ Completo	Enlaces bidireccionales con análisis de impacto
Análisis de Cobertura	✅ Completo	Identificación de brechas y detección de tareas huérfanas
Seguimiento de Cambios	✅ Completo	Análisis de impacto de cambios de requisitos
Seguimiento de Verificación	✅ Completo	Mapeo de casos de prueba y estado de verificación

Implementación MCP

Componente	Estado	Notas
Definiciones de Herramientas	✅ Completo	Todas las herramientas principales implementadas con validación Zod
Gestión de Recursos	✅ Completa	Operaciones CRUD completas con versionado
Seguridad	✅ Completa	Validación de tokens y verificación de alcances
Manejo de Errores	✅ Completo	Según especificaciones MCP
Transporte	✅ Completo	Soporte Stdio y HTTP

Mejoras Recientes

Sistema de Recursos Mejorado:
- Se añadió validación de esquemas Zod para todos los tipos de recursos
- Se implementó el seguimiento de relaciones entre recursos
- Se creó un ResourceFactory centralizado para acceso consistente a recursos
Integración Mejorada con la API de GitHub:
- Se añadió limitación de velocidad inteligente con regulación automática
- Se implementó soporte de paginación para APIs REST y GraphQL
- Se mejoró el manejo de errores con tipos de error específicos
Sistema Avanzado de Herramientas:
- Se creó un registro de definiciones de herramientas con validación Zod
- Se implementó formato estandarizado de respuestas de herramientas
- Se añadió documentación basada en ejemplos para todas las herramientas
Formato de Respuestas Enriquecido:
- Se añadió soporte para múltiples tipos de contenido (JSON, Markdown, HTML, Texto)
- Se implementaron actualizaciones de progreso para operaciones de larga duración
- Se añadió soporte de paginación para conjuntos de resultados grandes

Brechas Funcionales Identificadas

A pesar de las mejoras recientes, aún existen las siguientes brechas funcionales que están priorizadas para desarrollo futuro:

Estrategia de Caché Persistente:
- Aunque ResourceCache proporciona caché en memoria, carece de persistencia entre reinicios del servidor
- No hay caché distribuida para implementaciones de múltiples instancias
- Faltan políticas de expulsión de caché para la gestión de memoria
Procesamiento de Eventos en Tiempo Real:
- No hay integración de webhooks para actualizaciones en tiempo real desde GitHub
- Falta un sistema de suscripción basado en eventos para clientes
- Falta soporte de eventos enviados por el servidor (SSE) para actualizaciones en streaming
Funcionalidades Avanzadas de GitHub Projects v2:
- Soporte limitado para tipos de campos personalizados y validación
- Integración incompleta con los tipos de campo más recientes de Projects v2 de GitHub
- Falta gestión de reglas de automatización
Optimización del Rendimiento:
- No hay agrupación de consultas para recursos relacionados
- Falta actualización en segundo plano para recursos de acceso frecuente
- Prebúsqueda incompleta para recursos relacionados
Visualización de Datos y Generación de Informes:
- No hay generadores de visualización integrados para métricas
- Faltan capacidades de generación de informes
- Análisis limitado de datos de series temporales

Consulte docs/mcp/gaps-analysis.md para el estado detallado de implementación.

Documentación

Guía de Usuario - Instrucciones detalladas de uso
Referencia de API - Documentación integral de herramientas
Tutoriales - Guías paso a paso
Ejemplos - Ejemplos de código para tareas comunes
Arquitectura - Arquitectura y diseño del sistema
Contribuciones - Pautas de desarrollo
Documentación MCP - Detalles específicos de MCP

Documentación Interactiva

Para una exploración interactiva de la API, abra el Explorador de API en su navegador.

Desarrollo

Pruebas

# Unit tests
npm test

# Integration tests
npm run test:integration

# End-to-end tests
npm run test:e2e

Calidad de Código

# Lint code
npm run lint

# Type check
npm run type-check

# Format code
npm run format

Contribuciones

¡Damos la bienvenida a contribuciones al Servidor MCP de GitHub Project Manager! Consulte nuestra Guía de Contribuciones para más detalles sobre:

Licencia

MIT