mcp-server-circleci

Servidor MCP de CircleCI

El Protocolo de Contexto de Modelo (MCP) es un nuevo protocolo estandarizado para gestionar el contexto entre grandes modelos de lenguaje (LLM) y sistemas externos. En este repositorio, ofrecemos un servidor MCP para CircleCI .

Esto le permite usar Cursor IDE, Windsurf, Copilot o cualquier cliente compatible con MCP para usar lenguaje natural y lograr cosas con CircleCI, por ejemplo:

• Find the latest failed pipeline on my branch and get logshttps://github.com/CircleCI-Public/mcp-server-circleci/wiki#circleci-mcp-server-with-cursor-ide

https://github.com/user-attachments/assets/3c765985-8827-442a-a8dc-5069e01edb74

Requisitos

• Token de la API de CircleCI: puedes generar uno a través de CircleCI. Obtén más información o haz clic aquí para acceder rápidamente.

Para la instalación de NPX:

• Gestor de paquetes pnpm: Más información
• Node.js >= v18.0.0

Para la instalación de Docker:

• Docker - Más información

Instalación

Cursor

Uso de NPX

Agregue lo siguiente a la configuración MCP de su cursor:

Usando Docker

Agregue lo siguiente a la configuración MCP de su cursor:

Código VS

Uso de NPX

Para instalar CircleCI MCP Server para VS Code en .vscode/mcp.json :

Usando Docker

Para instalar CircleCI MCP Server para VS Code en .vscode/mcp.json usando Docker:

Escritorio de Claude

Uso de NPX

Agregue lo siguiente a su claude_desktop_config.json:

Usando Docker

Agregue lo siguiente a su claude_desktop_config.json:

Para encontrar/crear este archivo, primero abra la configuración de escritorio de Claude. Luego, haga clic en "Desarrollador" en la barra izquierda del panel de Configuración y, a continuación, en "Editar configuración".

Esto creará un archivo de configuración en:

• macOS: ~/Biblioteca/Soporte de aplicaciones/Claude/claude_desktop_config.json
• Ventanas: %APPDATA%\Claude\claude_desktop_config.json

Consulte la guía a continuación para obtener más información sobre el uso de servidores MCP con Claude Desktop: https://modelcontextprotocol.io/quickstart/user

Claude Code

Uso de NPX

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

Usando Docker

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

Consulte la guía a continuación para obtener más información sobre el uso de servidores MCP con Claude Code: https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/tutorials#set-up-model-context-protocol-mcp

Windsurf

Uso de NPX

Agregue lo siguiente a su windsurf mcp_config.json:

Usando Docker

Agregue lo siguiente a su windsurf mcp_config.json:

Consulte la guía a continuación para obtener más información sobre el uso de servidores MCP con Windsurf: https://docs.windsurf.com/windsurf/mcp

Instalación mediante herrería

Para instalar CircleCI MCP Server para Claude Desktop automáticamente a través de Smithery :

Características

Herramientas compatibles

• get_build_failure_logsRecupera registros detallados de errores de las compilaciones de CircleCI. Esta herramienta se puede utilizar de tres maneras:
  1. Uso de Project Slug y Branch (flujo de trabajo recomendado):
     • Primero, enumera tus proyectos disponibles:
       • Utilice la herramienta list_followed_projects para obtener sus proyectos
       • Ejemplo: "Enumerar mis proyectos de CircleCI"
       • A continuación, seleccione el proyecto que tenga un projectSlug asociado.
       • Ejemplo: "Usemos mi-proyecto"
     • Luego, solicita recuperar los registros de errores de compilación para una rama específica:
       • Ejemplo: "Obtener errores de compilación para mi proyecto en la rama principal"
  2. Uso de las URL de CircleCI:
     • Proporcione una URL de trabajo fallido o una URL de canalización directamente
     • Ejemplo: "Obtener registros de https://app.circleci.com/pipelines/github/org/repo/123 "
  3. Uso del contexto del proyecto local:
     • Trabaja desde su espacio de trabajo local proporcionando:
       • Ruta raíz del espacio de trabajo
       • URL remota de Git
       • Nombre de la sucursal
     • Ejemplo: "Buscar el último pipeline fallido en mi rama actual"

  La herramienta devuelve registros formateados que incluyen:

  • Nombres de trabajos
  • Detalles de ejecución paso a paso
  • Mensajes de error y contexto

  Esto es particularmente útil para:

  • Depuración de compilaciones fallidas
  • Análisis de fallos de pruebas
  • Investigación de problemas de implementación
  • Acceso rápido a los registros de compilación sin salir de su IDE
• find_flaky_testsIdentifica pruebas inestables en tu proyecto CircleCI analizando el historial de ejecución de pruebas. Esto aprovecha la función de detección de pruebas inestables que se describe aquí: https://circleci.com/blog/introducing-test-insights-with-flaky-test-detection/#flaky-test-detectionEsta herramienta se puede utilizar de tres maneras:
  1. Uso de Project Slug (flujo de trabajo recomendado):
     • Primero, enumera tus proyectos disponibles:
       • Utilice la herramienta list_followed_projects para obtener sus proyectos
       • Ejemplo: "Enumerar mis proyectos de CircleCI"
       • A continuación, seleccione el proyecto que tenga un projectSlug asociado.
       • Ejemplo: "Usemos mi-proyecto"
     • Luego pide recuperar las pruebas fallidas:
       • Ejemplo: "Obtener pruebas inestables para mi proyecto"
  2. Usando la URL del proyecto CircleCI:
     • Proporcione la URL del proyecto directamente desde CircleCI
     • Ejemplo: "Encuentra pruebas inestables en https://app.circleci.com/pipelines/github/org/repo "
  3. Uso del contexto del proyecto local:
     • Trabaja desde su espacio de trabajo local proporcionando:
       • Ruta raíz del espacio de trabajo
       • URL remota de Git
     • Ejemplo: "Encontrar pruebas defectuosas en mi proyecto actual"

  La herramienta devuelve información detallada sobre pruebas inestables, que incluye:

  • Nombres de prueba y ubicaciones de archivos
  • Mensajes y contextos de fallo

  Esto le ayudará a:

  • Identifique pruebas no confiables en su conjunto de pruebas
  • Obtenga un contexto detallado sobre los fallos de las pruebas
  • Tome decisiones basadas en datos sobre mejoras en las pruebas
• get_latest_pipeline_statusRecupera el estado del último pipeline de una rama determinada. Esta herramienta se puede utilizar de tres maneras:
  1. Uso de Project Slug y Branch (flujo de trabajo recomendado):
     • Primero, enumera tus proyectos disponibles:
       • Utilice la herramienta list_followed_projects para obtener sus proyectos
       • Ejemplo: "Enumerar mis proyectos de CircleCI"
       • A continuación, seleccione el proyecto que tenga un projectSlug asociado.
       • Ejemplo: "Usemos mi-proyecto"
     • A continuación, solicita recuperar el último estado del pipeline para una rama específica:
       • Ejemplo: "Obtener el estado del último pipeline de mi proyecto en la rama principal"
  2. Usando la URL del proyecto CircleCI:
     • Proporcione la URL del proyecto directamente desde CircleCI
     • Ejemplo: "Obtener el estado del último pipeline para https://app.circleci.com/pipelines/github/org/repo "
  3. Uso del contexto del proyecto local:
     • Trabaja desde su espacio de trabajo local proporcionando:
       • Ruta raíz del espacio de trabajo
       • URL remota de Git
       • Nombre de la sucursal
     • Ejemplo: "Obtener el estado del último pipeline de mi proyecto actual"

  La herramienta devuelve un estado formateado del último pipeline:

  • Nombres de flujos de trabajo y su estado actual
  • Duración de cada flujo de trabajo
  • Marcas de tiempo de creación y finalización
  • Estado general del oleoducto

  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

  Esto es particularmente útil para:

  • Comprobación del estado del último pipeline
  • Obtener el estado del último pipeline para una sucursal específica
  • Comprobación rápida del estado del último pipeline sin salir del IDE
• get_job_test_resultsRecupera metadatos de pruebas para trabajos de CircleCI, lo que permite analizar los resultados sin salir del IDE. Esta herramienta se puede usar de tres maneras:
  1. Uso de Project Slug y Branch (flujo de trabajo recomendado):
     • Primero, enumera tus proyectos disponibles:
       • Utilice la herramienta list_followed_projects para obtener sus proyectos
       • Ejemplo: "Enumerar mis proyectos de CircleCI"
       • A continuación, seleccione el proyecto que tenga un projectSlug asociado.
       • Ejemplo: "Usemos mi-proyecto"
     • Luego solicita recuperar los resultados de la prueba para una rama específica:
       • Ejemplo: "Obtener resultados de pruebas para mi-proyecto en la rama principal"
  2. Usando la URL de CircleCI:
     • Proporcione una URL de CircleCI en cualquiera de estos formatos:
       • URL del trabajo: " https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def/jobs/789 "
       • URL del flujo de trabajo: " https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def "
       • URL de la canalización: " https://app.circleci.com/pipelines/github/org/repo/123 "
     • Ejemplo: "Obtener resultados de la prueba para https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def "
  3. Uso del contexto del proyecto local:
     • Trabaja desde su espacio de trabajo local proporcionando:
       • Ruta raíz del espacio de trabajo
       • URL remota de Git
       • Nombre de la sucursal
     • Ejemplo: "Obtener resultados de pruebas para mi proyecto actual en la rama principal"

  La herramienta devuelve información detallada de los resultados de la prueba:

  • Resumen de todas las pruebas (total, exitosas, fallidas)
  • Información detallada sobre las pruebas fallidas, incluyendo:
    • Nombre y clase de la prueba
    • Ubicación del archivo
    • Mensajes de error
    • Duración del tiempo de ejecución
  • Lista de pruebas exitosas con información de tiempo
  • Filtrar por resultado de pruebas

  Esto es particularmente útil para:

  • Análisis rápido de fallas de pruebas sin visitar la interfaz web de CircleCI
  • Identificación de patrones en fallos de pruebas
  • Encontrar pruebas lentas que podrían necesitar optimización
  • Comprobación de la cobertura de pruebas en todo el proyecto
  • Solución de problemas de pruebas inestables

  Nota: La herramienta requiere que los metadatos de prueba estén configurados correctamente en la configuración de CircleCI. Para obtener más información sobre cómo configurar la recopilación de metadatos de prueba, consulte: https://circleci.com/docs/collect-test-data/

• config_helperAsiste en las tareas de configuración de CircleCI proporcionando orientación y validación. Esta herramienta le ayuda a:
  1. Validar la configuración de CircleCI:
     • Comprueba su .circleci/config.yml en busca de errores de sintaxis y semántica
     • Ejemplo: "Validar mi configuración de CircleCI"

  La herramienta proporciona:

  • Resultados detallados de la validación
  • Recomendaciones de configuración

  Esto le ayudará a:

  • Detectar errores de configuración antes de enviar
  • Aprenda las mejores prácticas de configuración de CircleCI
  • Solucionar problemas de configuración
  • Implementar correctamente las funciones de CircleCI
• create_prompt_templateAyuda a generar plantillas de indicaciones estructuradas para aplicaciones con IA según los requisitos de las funciones. Esta herramienta:
  1. Convierte los requisitos de las funciones en indicaciones estructuradas:
     • Transforma los requisitos del usuario en plantillas de indicaciones optimizadas
     • Ejemplo: "Crear una plantilla de indicaciones para generar cuentos para dormir por edad y tema"

  La herramienta proporciona:

  • Una plantilla de mensaje estructurado
  • Un esquema de contexto que define los parámetros de entrada requeridos

  Esto le ayudará a:

  • Cree indicaciones efectivas para aplicaciones de IA
  • Estandarizar los parámetros de entrada para obtener resultados consistentes
  • Cree funciones robustas impulsadas por IA
• recommend_prompt_template_testsGenera casos de prueba para plantillas de indicaciones para garantizar que produzcan los resultados esperados. Esta herramienta:
  1. Proporciona casos de prueba para plantillas de indicaciones:
     • Crea diversos escenarios de prueba basados en su plantilla de solicitud y esquema de contexto
     • Ejemplo: "Generar pruebas para mi plantilla de indicaciones para el cuento antes de dormir"

  La herramienta proporciona:

  • Una serie de casos de prueba recomendados
  • Varias combinaciones de parámetros para probar la robustez de la plantilla

  Esto le ayudará a:

  • Validar la funcionalidad de la plantilla de solicitud
  • Asegúrese de que las respuestas de IA sean consistentes en todas las entradas
  • Identificar casos extremos y problemas potenciales
  • Mejorar la calidad general de las aplicaciones de IA
• list_followed_projectsEnumera todos los proyectos que el usuario sigue en CircleCI. Esta herramienta:
  1. Recupera y muestra proyectos:
     • Muestra todos los proyectos a los que el usuario tiene acceso y está siguiendo
     • Proporciona el nombre del proyecto y el projectSlug para cada entrada
     • Ejemplo: "Enumerar mis proyectos de CircleCI"

  La herramienta devuelve una lista formateada de proyectos, ejemplo de salida:

  Projects followed: 1. my-project (projectSlug: gh/organization/my-project) 2. another-project (projectSlug: gh/organization/another-project)

  Esto es particularmente útil para:

  • Identificar qué proyectos de CircleCI están disponibles para usted
  • Obtener el projectSlug necesario para otras herramientas de CircleCI
  • Seleccionar un proyecto para operaciones posteriores

  Nota: El projectSlug (no el nombre del proyecto) es necesario para muchas otras herramientas de CircleCI y se utilizará para aquellas llamadas de herramientas después de seleccionar un proyecto.

• run_pipelineActiva la ejecución de una canalización. Esta herramienta se puede usar de tres maneras:
  1. Uso de Project Slug y Branch (flujo de trabajo recomendado):
     • Primero, enumera tus proyectos disponibles:
       • Utilice la herramienta list_followed_projects para obtener sus proyectos
       • Ejemplo: "Enumerar mis proyectos de CircleCI"
       • A continuación, seleccione el proyecto que tenga un projectSlug asociado.
       • Ejemplo: "Usemos mi-proyecto"
     • Luego solicita ejecutar el pipeline para una rama específica:
       • Ejemplo: "Ejecutar la canalización para mi-proyecto en la rama principal"
  2. Usando la URL de CircleCI:
     • Proporcione una URL de CircleCI en cualquiera de estos formatos:
       • URL del trabajo: " https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def/jobs/789 "
       • URL del flujo de trabajo: " https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def "
       • URL de la canalización: " https://app.circleci.com/pipelines/github/org/repo/123 "
       • URL del proyecto con rama: " https://app.circleci.com/projects/github/org/repo?branch=main "
     • Ejemplo: "Ejecutar la canalización para https://app.circleci.com/pipelines/github/org/repo/123/workflows/abc-def "
  3. Uso del contexto del proyecto local:
     • Trabaja desde su espacio de trabajo local proporcionando:
       • Ruta raíz del espacio de trabajo
       • URL remota de Git
       • Nombre de la sucursal
     • Ejemplo: "Ejecutar la canalización de mi proyecto actual en la rama principal"

  La herramienta devuelve un enlace para monitorear la ejecución del pipeline.

  Esto es particularmente útil para:

  • Ejecución rápida de pipelines sin necesidad de visitar la interfaz web de CircleCI
  • Ejecución de tuberías desde una rama específica

Desarrollo

Empezando

1. Clonar el repositorio:
   git clone https://github.com/CircleCI-Public/mcp-server-circleci.git cd mcp-server-circleci
2. Instalar dependencias:
   pnpm install
3. Construir el proyecto:
   pnpm build

Construcción de un contenedor Docker

Puedes construir el contenedor Docker localmente usando:

Esto creará una imagen de Docker etiquetada como circleci:mcp-server-circleci que puedes usar con cualquier cliente MCP.

Para ejecutar el contenedor:

Desarrollo con MCP Inspector

La forma más sencilla de iterar en el servidor MCP es mediante el inspector MCP. Puede obtener más información sobre el inspector MCP en https://modelcontextprotocol.io/docs/tools/inspector

1. Inicie el servidor de desarrollo:
   pnpm watch # Keep this running in one terminal
2. En una terminal separada, inicie el inspector:
   pnpm inspector
3. Configurar el entorno:
   • Agregue su CIRCLECI_TOKEN a la sección Variables de entorno en la interfaz de usuario del inspector
   • El token necesita acceso de lectura a sus proyectos CircleCI
   • Opcionalmente, puede configurar la URL base de CircleCI. El valor predeterminado es https//circleci.com

Pruebas

• Ejecute el conjunto de pruebas:
  pnpm test
• Ejecutar pruebas en modo de observación durante el desarrollo:
  pnpm test:watch

Para obtener pautas de contribución más detalladas, consulte CONTRIBUTING.md