Servidor de Priorización de Issues de GitHub para MCP

Un servidor del Protocolo de Contexto de Modelo (MCP) que permite a los asistentes de IA gestionar issues de GitHub con una puntuación de prioridad determinista y una selección segura para concurrencia.

Inicio rápido

# 1. Install from npm (recommended)
npm install -g mcp-git-issue-priority

# 2. Authenticate (if not already using GitHub CLI)
gh auth login

# 3. Add to Claude Code (~/.claude.json)

{
  "mcpServers": {
    "github-issue-priority": {
      "command": "mcp-git-issue-priority"
    }
  }
}

# 4. Restart Claude Code and verify
# The MCP tools should appear when you run /mcp

Related MCP server: Project Manager MCP

Características

• Selección de issues basada en prioridad: El algoritmo de puntuación determinista garantiza una priorización coherente de los issues entre sesiones.

• Bloqueo seguro para concurrencia: El bloqueo atómico basado en archivos evita que múltiples sesiones de IA seleccionen el mismo issue.

• Flujo de trabajo guiado: Flujo de trabajo de 8 fases (selección → investigación → rama → implementación → pruebas → confirmación → pr → revisión) con validación de transición.

• Etiquetado automático: Crea y gestiona etiquetas de prioridad (P0-P3), tipo (bug, feature, chore, docs) y estado.

• Detección de bloqueos obsoletos: Detecta y limpia automáticamente los bloqueos de procesos finalizados.

• Registro de auditoría: Registro en líneas JSON para todas las operaciones con una retención de 30 días.

Instalación

Requisitos previos

• Node.js 20+ - Descargar

• GitHub CLI (recomendado) - Instalar y ejecutar gh auth login

  • O bien: un token de acceso personal de GitHub con alcance repo

Instalar desde npm (recomendado)

npm install -g mcp-git-issue-priority

Instalar una versión específica

npm install -g mcp-git-issue-priority@1.0.0

Instalar desde el código fuente

git clone https://github.com/steiner385/mcp-git-issue-priority.git
cd mcp-git-issue-priority
npm install && npm link

Solución de problemas

Configuración

Autenticación de GitHub

El servidor admite dos métodos de autenticación:

Recomendado: GitHub CLI (automático)

Si tienes instalado y autenticado GitHub CLI, el servidor recupera automáticamente tu token:

# One-time setup
gh auth login

Este es el enfoque recomendado: no se requiere gestión manual de tokens.

Alternativa: Variable de entorno

Configura GITHUB_TOKEN con un token de acceso personal que tenga alcance repo:

export GITHUB_TOKEN="ghp_your_personal_access_token"

O configúralo en tus ajustes de MCP (ver más abajo).

Configuración de Claude Code

Añádelo a ~/.claude.json (global) o .claude/settings.json (proyecto):

{
  "mcpServers": {
    "github-issue-priority": {
      "command": "mcp-git-issue-priority"
    }
  }
}

¿Usas un token de acceso personal en lugar de GitHub CLI? Añade el token a la configuración:

{
  "mcpServers": {
    "github-issue-priority": {
      "command": "mcp-git-issue-priority",
      "env": {
        "GITHUB_TOKEN": "ghp_your_personal_access_token"
      }
    }
  }
}

Verificar la instalación

Después de reiniciar Claude Code:

1. Ejecuta /mcp para ver los servidores MCP disponibles

2. El servidor github-issue-priority debería aparecer con 13 herramientas

3. Prueba list_backlog en cualquier repositorio para confirmar que funciona

Herramientas disponibles

create_issue

Crea un nuevo issue de GitHub con etiquetas obligatorias de prioridad y tipo.

Arguments:
  - title (required): Issue title
  - body (optional): Issue description
  - priority (required): P0 (critical) | P1 (high) | P2 (medium) | P3 (low)
  - type (required): bug | feature | chore | docs
  - repository (required): "owner/repo" format

select_next_issue

Selecciona y bloquea el issue de mayor prioridad del backlog. Utiliza una puntuación determinista para garantizar una selección coherente.

Arguments:
  - repository (required): "owner/repo" format
  - type (optional): Filter by issue type
  - maxPriority (optional): Only consider issues at or above this priority

list_backlog

Enumera todos los issues abiertos en orden de prioridad sin adquirir bloqueos (solo lectura).

Arguments:
  - repository (required): "owner/repo" format
  - type (optional): Filter by issue type
  - limit (optional): Maximum issues to return (default: 20)

advance_workflow

Avanza el flujo de trabajo a la siguiente fase para un issue bloqueado.

Arguments:
  - issueNumber (required): Issue number to advance
  - targetPhase (required): research | branch | implementation | testing | commit | pr | review
  - repository (required): "owner/repo" format
  - testsPassed (optional): Required when advancing to 'commit' phase
  - prTitle (optional): Required for 'pr' phase
  - prBody (optional): Required for 'pr' phase
  - skipJustification (optional): Required if skipping phases

get_workflow_status

Obtén el estado actual del flujo de trabajo para los issues bloqueados.

Arguments:
  - issueNumber (optional): Specific issue number
  - repository (optional): "owner/repo" format

release_lock

Libera el bloqueo de un issue (al finalizar, abandonar o fusionar).

Arguments:
  - issueNumber (required): Issue number
  - reason (required): completed | abandoned | merged
  - repository (required): "owner/repo" format

force_claim

Fuerza la reclamación de un issue bloqueado por otra sesión (requiere confirmación).

Arguments:
  - issueNumber (required): Issue number to claim
  - confirmation (required): Must be exactly "I understand this may cause conflicts"
  - repository (required): "owner/repo" format

sync_backlog_labels

Detecta y, opcionalmente, corrige los issues a los que les faltan etiquetas obligatorias de prioridad/tipo/estado.

Arguments:
  - repository (required): "owner/repo" format
  - mode (optional): "report" (default) to list issues, "update" to apply labels
  - defaultPriority (optional): P0 | P1 | P2 | P3 (defaults to P2)
  - defaultType (optional): bug | feature | chore | docs (defaults to feature)

En modo informe, devuelve una lista de todos los issues a los que les faltan etiquetas con detalles sobre lo que falta.

En modo actualización, aplica etiquetas predeterminadas a los issues:

• Falta prioridad → priority:P2 (o el valor predeterminado especificado)

• Falta tipo → type:feature (o el valor predeterminado especificado)

• Falta estado → status:backlog

get_pr_status

Comprueba el estado de CI, el estado de aprobación y el estado de fusión de una solicitud de extracción.

Arguments:
  - repository (required): "owner/repo" format
  - prNumber (required): Pull request number to check

bulk_update_issues

Añade/elimina etiquetas y cierra/reabre múltiples issues a la vez.

Arguments:
  - repository (required): "owner/repo" format
  - issues (required): Array of issue numbers (1-50)
  - addLabels (optional): Labels to add
  - removeLabels (optional): Labels to remove
  - state (optional): "open" | "closed"

implement_batch

Comienza a implementar un lote de N issues en orden de prioridad. Devuelve el primer issue a implementar.

Arguments:
  - repository (required): "owner/repo" format
  - count (required): Number of issues to implement (1-10)
  - includeTypes (optional): Only include these issue types
  - excludeTypes (optional): Exclude these issue types
  - maxPriority (optional): Only P0, P1, etc.

batch_continue

Continúa la implementación por lotes. Espera a la fusión de la PR y luego devuelve el siguiente issue o la finalización.

Arguments:
  - batchId (required): Batch ID from implement_batch
  - prNumber (optional): PR number for current issue

get_workflow_analytics

Obtén análisis del flujo de trabajo basados en el tiempo: tiempo de ciclo, desglose de fases, informes de antigüedad.

Arguments:
  - repository (required): "owner/repo" format
  - period (optional): "7d" | "30d" | "90d" | "all" (default: 30d)

Algoritmo de puntuación de prioridad

Los issues se puntúan utilizando una fórmula determinista:

score = (basePoints + ageBonus) * blockingMultiplier * blockedPenalty

• Puntos base: P0=1000, P1=100, P2=10, P3=1

• Bono por antigüedad: +1 punto por día desde la creación (máximo 365)

• Multiplicador de bloqueo: 1.5x para issues con la etiqueta "blocking"

• Penalización por estar bloqueado: 0.1x para issues bloqueados por issues padres abiertos (a través de sub-issues de GitHub)

• Desempate: Gana la fecha de creación más antigua (FIFO)

Detección de dependencias

Los issues con issues padres abiertos (usando la función de sub-issues de GitHub) se despriorizan automáticamente con una penalización de 0.1x. Esto asegura que el trabajo bloqueado se desplace al final del backlog hasta que se resuelvan sus dependencias. Una vez que se cierra un issue padre, la prioridad del issue hijo vuelve a la normalidad.

Fases del flujo de trabajo

1. selection: Issue seleccionado y bloqueado

2. research: Comprensión del problema

3. branch: Rama de funcionalidad creada

4. implementation: Cambios de código en progreso

5. testing: Ejecución de pruebas y validación

6. commit: Cambios confirmados

7. pr: Solicitud de extracción creada

8. review: Esperando revisión/fusión

Almacenamiento de datos

Todos los datos se almacenan localmente en ~/.mcp-git-issue-priority/:

~/.mcp-git-issue-priority/
├── locks/          # Active lock files (.lockdata)
├── workflow/       # Workflow state files (.json)
└── logs/           # Audit logs (JSON Lines format)

Desarrollo

Compilación

npm run build

Pruebas

npm test

Lint

npm run lint

Verificación de tipos

npm run typecheck

Lanzamiento (Mantenedores)

Configuración única

1. Crea una cuenta de npm en https://www.npmjs.com/

2. Ve a https://www.npmjs.com/settings/tokens

3. Crea un token de "Automation" con permiso de "Publish"

4. Añádelo a GitHub: Settings → Secrets → Actions → New secret llamado NPM_TOKEN

Crear un lanzamiento

# Patch release (bug fixes): 1.0.0 → 1.0.1
npm version patch -m "Release v%s"
git push && git push --tags

# Minor release (new features): 1.0.0 → 1.1.0
npm version minor -m "Release v%s"
git push && git push --tags

# Major release (breaking changes): 1.0.0 → 2.0.0
npm version major -m "Release v%s"
git push && git push --tags

Al enviar una etiqueta (tag) se activa el flujo de trabajo de lanzamiento que:

• Ejecuta lint, compilación y pruebas

• Crea un lanzamiento en GitHub con el archivo tarball adjunto

• Publica en el registro de npm

Seguimiento de descargas

• GitHub: La página de lanzamientos muestra el recuento de descargas por activo .tgz

• npm: https://www.npmjs.com/package/mcp-git-issue-priority muestra las descargas semanales

Licencia

Licencia MIT - ver LICENSE para más detalles.

Contribución

¡Las contribuciones son bienvenidas! Por favor, consulta CONTRIBUTING.md para conocer las directrices.

Comentarios y soporte

¡Nos encantaría saber de ti! Tus comentarios ayudan a mejorar esta herramienta para todos.

• ¿Preguntas o ideas? Inicia una Discusión

• ¿Encontraste un error? Abre un issue

• ¿Solicitud de funcionalidad? Abre un issue con [Feature] en el título

• ¿Comentarios rápidos? Ejecuta mcp-git-issue-priority --feedback para abrir la página de comentarios

Comprueba los issues existentes antes de crear otros nuevos.