GitHub Actions

Un servidor MCP para la API de GitHub Actions, que permite a los asistentes de IA gestionar

Documentación

Servidor MCP de GitHub Actions

⚠️ Aviso de Archivo: Este repositorio será archivado pronto, ya que el servidor MCP oficial de GitHub está añadiendo soporte para Actions. Consulta github/github-mcp-server#491 para más detalles sobre la implementación oficial.

Servidor MCP para la API de GitHub Actions, que permite a los asistentes de IA gestionar y operar flujos de trabajo de GitHub Actions. Compatible con múltiples asistentes de codificación con IA, incluyendo Claude Desktop, Codeium y Windsurf.

Características

Gestión Completa de Flujos de Trabajo: Listar, ver, activar, cancelar y volver a ejecutar flujos de trabajo
Análisis de Ejecuciones de Flujos de Trabajo: Obtén información detallada sobre las ejecuciones de flujos de trabajo y sus trabajos
Manejo Integral de Errores: Mensajes de error claros con detalles mejorados
Validación Flexible de Tipos: Comprobación robusta de tipos con manejo elegante de variaciones de la API
Diseño Centrado en la Seguridad: Manejo de tiempos de espera, limitación de velocidad y validación estricta de URL

Herramientas

list_workflows
- Listar flujos de trabajo en un repositorio de GitHub
- Entradas:
  - owner (cadena): Propietario del repositorio (usuario u organización)
  - repo (cadena): Nombre del repositorio
  - page (número opcional): Número de página para la paginación
  - perPage (número opcional): Resultados por página (máx. 100)
- Devuelve: Lista de flujos de trabajo en el repositorio
get_workflow
- Obtener detalles de un flujo de trabajo específico
- Entradas:
  - owner (cadena): Propietario del repositorio (usuario u organización)
  - repo (cadena): Nombre del repositorio
  - workflowId (cadena o número): El ID del flujo de trabajo o nombre de archivo
- Devuelve: Información detallada sobre el flujo de trabajo
get_workflow_usage
- Obtener estadísticas de uso de un flujo de trabajo
- Entradas:
  - owner (cadena): Propietario del repositorio (usuario u organización)
  - repo (cadena): Nombre del repositorio
  - workflowId (cadena o número): El ID del flujo de trabajo o nombre de archivo
- Devuelve: Estadísticas de uso, incluidos los minutos facturables
list_workflow_runs
- Listar todas las ejecuciones de flujos de trabajo para un repositorio o un flujo de trabajo específico
- Entradas:
  - owner (cadena): Propietario del repositorio (usuario u organización)
  - repo (cadena): Nombre del repositorio
  - workflowId (cadena o número opcional): El ID del flujo de trabajo o nombre de archivo
  - actor (cadena opcional): Filtrar por usuario que activó el flujo de trabajo
  - branch (cadena opcional): Filtrar por rama
  - event (cadena opcional): Filtrar por tipo de evento
  - status (cadena opcional): Filtrar por estado
  - created (cadena opcional): Filtrar por fecha de creación (AAAA-MM-DD)
  - excludePullRequests (booleano opcional): Excluir ejecuciones activadas por PR
  - checkSuiteId (número opcional): Filtrar por ID de suite de verificación
  - page (número opcional): Número de página para la paginación
  - perPage (número opcional): Resultados por página (máx. 100)
- Devuelve: Lista de ejecuciones de flujos de trabajo que coinciden con los criterios
get_workflow_run
- Obtener detalles de una ejecución de flujo de trabajo específica
- Entradas:
  - owner (cadena): Propietario del repositorio (usuario u organización)
  - repo (cadena): Nombre del repositorio
  - runId (número): El ID de la ejecución del flujo de trabajo
- Devuelve: Información detallada sobre la ejecución específica del flujo de trabajo
get_workflow_run_jobs
- Obtener trabajos para una ejecución de flujo de trabajo específica
- Entradas:
  - owner (cadena): Propietario del repositorio (usuario u organización)
  - repo (cadena): Nombre del repositorio
  - runId (número): El ID de la ejecución del flujo de trabajo
  - filter (cadena opcional): Filtrar trabajos por estado de finalización ('latest', 'all')
  - page (número opcional): Número de página para la paginación
  - perPage (número opcional): Resultados por página (máx. 100)
- Devuelve: Lista de trabajos en la ejecución del flujo de trabajo
trigger_workflow
- Activar una ejecución de flujo de trabajo
- Entradas:
  - owner (cadena): Propietario del repositorio (usuario u organización)
  - repo (cadena): Nombre del repositorio
  - workflowId (cadena o número): El ID del flujo de trabajo o nombre de archivo
  - ref (cadena): La referencia para ejecutar el flujo de trabajo (rama, etiqueta o SHA)
  - inputs (objeto opcional): Parámetros de entrada para el flujo de trabajo
- Devuelve: Información sobre la ejecución del flujo de trabajo activada
cancel_workflow_run
- Cancelar una ejecución de flujo de trabajo
- Entradas:
  - owner (cadena): Propietario del repositorio (usuario u organización)
  - repo (cadena): Nombre del repositorio
  - runId (número): El ID de la ejecución del flujo de trabajo
- Devuelve: Estado de la operación de cancelación
rerun_workflow
- Volver a ejecutar un flujo de trabajo
- Entradas:
  - owner (cadena): Propietario del repositorio (usuario u organización)
  - repo (cadena): Nombre del repositorio
  - runId (número): El ID de la ejecución del flujo de trabajo
- Devuelve: Estado de la operación de re-ejecución

Uso con Asistentes de Codificación con IA

Este servidor MCP es compatible con múltiples asistentes de codificación con IA, incluyendo Claude Desktop, Codeium y Windsurf.

Claude Desktop

Primero, asegúrate de haber compilado el proyecto (consulta la sección Compilación a continuación). Luego, añade lo siguiente a tu claude_desktop_config.json:

{
  "mcpServers": {
    "github-actions": {
      "command": "node",
      "args": [
        "<path-to-mcp-server>/dist/index.js"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}

Codeium

Añade la siguiente configuración a tu archivo de configuración MCP de Codeium (normalmente en ~/.codeium/windsurf/mcp_config.json en sistemas basados en Unix o %USERPROFILE%\.codeium\windsurf\mcp_config.json en Windows):

{
  "mcpServers": {
    "github-actions": {
      "command": "node",
      "args": [
        "<path-to-mcp-server>/dist/index.js"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}

Windsurf

Windsurf utiliza el mismo formato de configuración que Codeium. Añade el servidor a tu configuración MCP de Windsurf como se muestra arriba para Codeium.

Compilación

Unix/Linux/macOS

Clona el repositorio y compila:

git clone https://github.com/ko1ynnky/github-actions-mcp-server.git
cd github-actions-mcp-server
npm install
npm run build

Windows

Para sistemas Windows, utiliza el comando de compilación específico para Windows:

git clone https://github.com/ko1ynnky/github-actions-mcp-server.git
cd github-actions-mcp-server
npm install
npm run build:win

Alternativamente, puedes usar el archivo por lotes incluido:

run-server.bat [optional-github-token]

Esto creará los archivos necesarios en el directorio dist que necesitarás para ejecutar el servidor MCP.

Instrucciones Específicas para Windows

Requisitos previos

Node.js (v14 o superior)
npm (v6 o superior)

Ejecutar el Servidor en Windows

Usando el archivo por lotes (método más simple):
```
run-server.bat [optional-github-token]
```
Esto verificará si la compilación existe, compilará si es necesario e iniciará el servidor.
Usando npm directamente:
```
npm run start
```

Configurar el Token de Acceso Personal de GitHub en Windows

Para una funcionalidad completa y evitar la limitación de velocidad, debes configurar tu Token de Acceso Personal de GitHub.

Opciones:

Pásalo como parámetro al archivo por lotes:
```
run-server.bat your_github_token_here
```

Configúralo como variable de entorno:

set GITHUB_PERSONAL_ACCESS_TOKEN=your_github_token_here
npm run start

Solución de Problemas en Windows

Si encuentras problemas:

Errores de compilación: Asegúrate de que TypeScript esté instalado correctamente.
```
npm install -g typescript
```
Problemas de permisos: Asegúrate de ejecutar los comandos en un símbolo del sistema con permisos adecuados.
Errores de Node.js: Verifica que estás usando una versión compatible de Node.js.
```
node --version
```

Ejemplos de Uso

Listar flujos de trabajo en un repositorio:

const result = await listWorkflows({
  owner: "your-username",
  repo: "your-repository"
});

Activar un flujo de trabajo:

const result = await triggerWorkflow({
  owner: "your-username",
  repo: "your-repository",
  workflowId: "ci.yml",
  ref: "main",
  inputs: {
    environment: "production"
  }
});

Solución de Problemas

Problemas Comunes

Errores de Autenticación:
- Asegúrate de que tu token de GitHub tenga los permisos correctos
- Verifica que el token esté configurado correctamente como variable de entorno
Limitación de Velocidad:
- El servidor implementa limitación de velocidad para evitar alcanzar los límites de la API de GitHub
- Si encuentras errores de límite de velocidad, reduce la frecuencia de las solicitudes
Errores de Validación de Tipos:
- Las respuestas de la API de GitHub a veces pueden diferir de los esquemas esperados
- El servidor implementa validación flexible para manejar la mayoría de las variaciones
- Si encuentras errores persistentes, abre un issue

Licencia

Este servidor MCP está licenciado bajo la Licencia MIT.