CircleCI-Public/mcp-server-circleciPlease refer to the latest official releases for information GitHub Homepage

Servidor MCP de CircleCI - Una implementación de servidor profesional diseñada específicamente para el Protocolo de Contexto de Modelo, utilizada para integrar flujos de trabajo de desarrollo de CircleCI

Apache-2.0TypeScript 50CircleCI-Publicmcp-server-circleci Last Updated: 2025-06-23

Introducción al Proyecto del Servidor MCP de CircleCI

Resumen del Proyecto

El servidor MCP de CircleCI es una implementación de servidor especializada diseñada para el Protocolo de Contexto del Modelo (MCP), con el objetivo de integrar los flujos de trabajo de desarrollo de CircleCI. Este proyecto sirve como puente entre la infraestructura de CircleCI y el Protocolo de Contexto del Modelo, proporcionando una experiencia de desarrollo mejorada impulsada por la IA.

Este servidor permite que herramientas de IA como Cursor, Claude Code, Windsurf, etc., comprendan su sistema de construcción. Se basa en el Protocolo de Contexto del Modelo (MCP), un estándar ligero que permite a los agentes impulsados por LLM obtener datos estructurados de sistemas externos.

Funcionalidades Principales

Herramientas y Funciones Principales

1. get_build_failure_logs

Recupera los registros detallados de fallos de construcción de CircleCI. Esta herramienta admite dos métodos de uso:

Usando la URL de CircleCI:

Proporcione directamente la URL del trabajo fallido o la URL de la canalización.
Ejemplo: "Obtener los registros de https://app.circleci.com/pipelines/github/org/repo/123"

Usando el contexto del proyecto local:

Trabaje desde un espacio de trabajo local proporcionando la siguiente información:
- Ruta raíz del espacio de trabajo
- URL remota de Git
- Nombre de la rama
Ejemplo: "Encontrar la canalización fallida más reciente en mi rama actual"

Los registros formateados devueltos incluyen:

Nombre del trabajo
Detalles de la ejecución paso a paso
Mensajes de error y contexto

2. find_flaky_tests

Identifica las pruebas inestables en un proyecto de CircleCI analizando el historial de ejecución de pruebas. Admite dos métodos de uso:

Usando la URL del proyecto de CircleCI:

Proporcione directamente la URL del proyecto desde CircleCI.
Ejemplo: "Encontrar pruebas inestables en https://app.circleci.com/pipelines/github/org/repo"

Usando el contexto del proyecto local:

Trabaje desde un espacio de trabajo local proporcionando la ruta raíz del espacio de trabajo y la URL remota de Git.

Devuelve información detallada sobre las pruebas inestables, incluyendo:

Nombre de la prueba y ubicación del archivo
Mensajes de error y contexto

3. get_latest_pipeline_status

Recupera el estado de la canalización más reciente para una rama dada. La herramienta devuelve un estado formateado de la canalización más reciente:

Nombre del flujo de trabajo y su estado actual
Duración de cada flujo de trabajo
Marcas de tiempo de creación y finalización
Estado general de la canalización

Ejemplo de salida:

--- 
Workflow: build 
Status: success 
Duration: 5 minutes 
Created: 4/20/2025, 10:15:30 AM 
Stopped: 4/20/2025, 10:20:45 AM 
--- 
Workflow: test 
Status: running 
Duration: unknown 
Created: 4/20/2025, 10:21:00 AM 
Stopped: in progress

4. get_job_test_results

Recupera los metadatos de las pruebas de un trabajo de CircleCI, lo que le permite analizar los resultados de las pruebas sin salir de su IDE.

Devuelve información detallada de los resultados de las pruebas:

Resumen de todas las pruebas (total, éxito, fallo)
Detalles de las pruebas fallidas, incluyendo:
- Nombre de la prueba y clase
- Ubicación del archivo
- Mensaje de error
- Duración del tiempo de ejecución
Lista de pruebas exitosas con información de tiempo

5. config_helper

Asiste con las tareas de configuración de CircleCI, proporcionando orientación y validación. Esta herramienta le ayuda a:

Validar la configuración de CircleCI:
- Comprueba si su .circleci/config.yml tiene errores sintácticos y semánticos.
- Ejemplo: "Validar mi configuración de CircleCI"

Proporciona:

Resultados de validación detallados
Recomendaciones de configuración

6. create_prompt_template

Genera plantillas de indicaciones estructuradas basadas en los requisitos de las funciones, para aplicaciones habilitadas para IA. Esta herramienta:

Convierte los requisitos de las funciones en indicaciones estructuradas:
- Traduce las necesidades del usuario en plantillas de indicaciones optimizadas.
- Ejemplo: "Crear una plantilla de indicación para generar cuentos para dormir por edad y tema"

7. recommend_prompt_template_tests

Genera casos de prueba para plantillas de indicaciones, asegurando que produzcan los resultados esperados.

Instalación y Configuración

Requisitos del Sistema

Administrador de paquetes pnpm - Más información
Node.js >= v18.0.0
Token de API de CircleCI - Puede generar uno a través de CircleCI. Más información o haga clic aquí para un acceso rápido

IDEs y Herramientas Compatibles

Cursor IDE

Añada lo siguiente a su configuración MCP de Cursor:

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci"],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com" // Opcional - Solo necesario para clientes con despliegues locales
      }
    }
  }
}

VS Code

Instale el servidor MCP de CircleCI en .vscode/mcp.json:

{
  // 💡 La entrada se solicita en el primer inicio del servidor y luego VS Code la almacena de forma segura
  "inputs": [
    {
      "type": "promptString",
      "id": "circleci-token",
      "description": "Token de API de CircleCI",
      "password": true
    }
  ],
  "servers": {
    "circleci-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci"],
      "env": {
        "CIRCLECI_TOKEN": "${input:circleci-token}"
      }
    }
  }
}

Claude Desktop

Añada lo siguiente a su claude_desktop_config.json:

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci"],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com" // Opcional - Solo necesario para clientes con despliegues locales
      }
    }
  }
}

Ubicación del archivo de configuración:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Claude Code

Después de instalar Claude Code, ejecute el siguiente comando:

claude mcp add circleci-mcp-server -e CIRCLECI_TOKEN=your-circleci-token -- npx -y @circleci/mcp-server-circleci

Windsurf

Añada lo siguiente a su mcp_config.json de Windsurf:

{
  "mcpServers": {
    "circleci-mcp-server": {
      "command": "npx",
      "args": ["-y", "@circleci/mcp-server-circleci"],
      "env": {
        "CIRCLECI_TOKEN": "your-circleci-token",
        "CIRCLECI_BASE_URL": "https://circleci.com" // Opcional - Solo necesario para clientes con despliegues locales
      }
    }
  }
}

Instalación Automática

Instale automáticamente el servidor MCP de CircleCI para Claude Desktop a través de Smithery:

npx -y @smithery/cli install @CircleCI-Public/mcp-server-circleci --client claude

Desarrollo y Contribución

Configuración de Desarrollo Local

Clonar el repositorio:

git clone https://github.com/CircleCI-Public/mcp-server-circleci.git
cd mcp-server-circleci

Instalar dependencias:

pnpm install

Construir el proyecto:

pnpm build

Desarrollar con el Inspector MCP

La forma más sencilla de iterar en el servidor MCP es utilizando el Inspector MCP.

Iniciar el servidor de desarrollo:

pnpm watch # Mantener en ejecución en una terminal

Iniciar el inspector en una terminal separada:

pnpm inspector

Configurar el entorno:
- Añada su CIRCLECI_TOKEN en la sección de variables de entorno de la interfaz de usuario del inspector.
- El token necesita permisos de lectura para su proyecto de CircleCI.
- Opcionalmente, configure su URL base de CircleCI, que por defecto es https://circleci.com.

Pruebas

Ejecutar el conjunto de pruebas:

pnpm test

Ejecutar pruebas en modo de vigilancia durante el desarrollo:

pnpm test:watch

Casos de Uso

Esta herramienta es particularmente útil para:

Depurar construcciones fallidas
Analizar fallos de pruebas
Investigar problemas de despliegue
Acceder rápidamente a los registros de construcción sin salir del IDE
Comprobar el estado de las canalizaciones más recientes
Identificar pruebas no fiables en el conjunto de pruebas
Tomar decisiones basadas en datos para mejorar las pruebas

Ventajas del Proyecto

El servidor MCP de CircleCI está diseñado para apoyar los momentos prácticos del ciclo de vida del desarrollo. Ya sea que esté revisando una construcción fallida, depurando un despliegue fallido o monitoreando una rama crítica, ayuda a su asistente a comprender los fallos y sugerir soluciones en segundos, sin necesidad de cambiar de contexto.

Al integrar este servidor MCP, los desarrolladores pueden:

Interactuar con CircleCI usando lenguaje natural
Obtener información de construcción en un entorno de desarrollo familiar
Diagnosticar y resolver rápidamente problemas de CI/CD
Mejorar la eficiencia del flujo de trabajo de desarrollo

Recursos Relacionados

Para obtener una guía de contribución más detallada, consulte el archivo CONTRIBUTING.md en el proyecto.