Polarion MCP Servers

Servidor MCP para integración con Polarion Application Lifecycle Management (ALM).

GitHub
40
Prueba este MCPPatrocinado

Documentación

Servidores MCP de Polarion

Este repositorio contiene implementaciones de servidores de Model Context Protocol (MCP) para la integración con Polarion Application Lifecycle Management (ALM).

Las herramientas MCP están disponibles para los work items de Polarion, incluyendo:

  • get_document_info: Obtiene metadatos y campos personalizados para un Documento de Polarion.
  • get_document_outline: Obtiene todos los encabezados de sección (tabla de contenidos) dentro de un Documento de Polarion.
  • get_document_revision_history: Obtiene el historial de revisiones para un documento/módulo de Polarion.
  • get_document_section: Obtiene el contenido de un encabezado de sección específico y sus sub-encabezados en un Documento de Polarion.
  • get_workitem: Obtiene el contenido de texto de un WorkItem. Opcionalmente recupera una revisión específica.
  • get_workitem_details: Obtiene información detallada de WorkItems, incluyendo campos estándar, campos personalizados y work items vinculados. Soporta trazabilidad con seguimiento recursivo de enlaces.
  • get_workitem_history: Obtiene el historial de revisiones de un WorkItem, incluyendo el contenido en cada revisión.
  • get_workitems_in_module: Consulta work items de un módulo/documento de Polarion usando SQL contra la relación REL_MODULE_WORKITEM.
  • list_custom_fields: Lista los campos personalizados disponibles para un tipo específico de WorkItem.
  • list_documents: Lista todos los Documentos en el Proyecto de Polarion. Opcionalmente filtra por nombre de espacio y/o título.
  • list_spaces: Lista todos los nombres de Espacios en el proyecto de Polarion.
  • list_workitem_types: Lista todos los tipos de WorkItem configurados para el proyecto actual.
  • search_in_document: Busca en un Documento de Polarion work items que coincidan con los términos de búsqueda.
  • search_workitems: Busca work items en todo el proyecto de Polarion usando contenido de texto.
  • search_workitems_sql (opt-in): Ejecuta una consulta SQL de solo lectura validada (un solo SELECT sobre WORKITEM proyectando C_PK) como filtro SQL:(…) de Polarion, para lecturas con muchos joins que Lucene plano no puede expresar. Se registra solo cuando SqlQueryTool:Enabled=true. Los resultados permanecen dentro del proyecto del endpoint. Ver RBAC.

Proyectos

  • PolarionRemoteMcpServer: Servidor MCP HTTP transmisible para instalaciones basadas en servidor. Sin estado, con autenticación OAuth 2.1 opcional y RBAC por llamador.
  • PolarionMcpServer: Servidor MCP basado en consola para integración de Polarion en instalaciones de estaciones de trabajo locales

Ejecución mediante Docker y Servidor Linux (Recomendado)

  1. Desde su servidor Linux, cree un directorio para su configuración y registros:

    mkdir -p /opt/polarion-mcp-server
cd /opt/polarion-mcp-server

  2. Extraiga la imagen de Docker:

    docker pull peakflames/polarion-remote-mcp-server

  3. Cree un archivo /opt/polarion-mcp-server/appsettings.json adaptado a su configuración de Polarion:

    {
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "ApiConsumers": {
    "Consumers": {
      "my_app": {
        "Name": "My Application",
        "ApplicationKey": "your-secure-api-key-here",
        "Active": true,
        "AllowedScopes": ["polarion:read"],
        "Description": "API consumer for my application"
      }
    }
  },
  "PolarionProjects": [
       {
           "ProjectUrlAlias": "starlight", 
           "Default": true,
           "SessionConfig": { 
               "ServerUrl": "https://polarion.int.mycompany.com/",
               "Username": "shared_user_read_only",
               "Password": "linear-Vietnam-FLIP-212824", 
               "ProjectId": "Starlight_Main", 
               "TimeoutSeconds": 60
           },
           "PolarionWorkItemTypes": [
             {
               "id": "requirement",
               "fields": ["custom_field_1", "priority", "severity"]
             },
             {
               "id": "defect",
               "fields": ["defect_type", "found_in_build"]
             }
           ]
       },
       {
           "ProjectUrlAlias": "octopus", 
           "Default": false,
           "SessionConfig": { 
               "ServerUrl": "https://polarion.int.mycompany.com/",
               "Username": "some_other_user",
               "Password": "linear-Vietnam-FLIP-212824", 
               "ProjectId": "octopus_gov", 
               "TimeoutSeconds": 60
           }
       },
       {
           "ProjectUrlAlias": "grogu", 
           "Default": false,
           "SessionConfig": { 
               "ServerUrl": "https://polarion-dev.int.mycompany.com/",
               "Username": "vader",
               "Password": "12345", 
               "ProjectId": "grogu_boss", 
               "TimeoutSeconds": 60
           }
       }
   ]
}

  4. Ejecute el contenedor de Docker:

    docker run -d \
  --name polarion-mcp-server \
  -p 8080:8080 \
  -v appsettings.json:/app/appsettings.json \
  peakflames/polarion-remote-mcp-server

  5. El servidor debería estar ejecutándose ahora. Los clientes MCP se conectarán usando una URL específica para el alias de configuración del proyecto deseado:

    1. Transporte HTTP transmisible: http://{{your-server-ip}}:8080/{ProjectUrlAlias}/mcp.

  6. El servidor también proporciona:

    • API REST: http://{{your-server-ip}}:8080/polarion/rest/v1/projects/{ProjectId}/... (usa SessionConfig.ProjectId)
      • Nota: Los endpoints de la API REST requieren autenticación mediante clave de API a través del encabezado X-API-Key
    • Documentación de la API: http://{{your-server-ip}}:8080/scalar/v1 (incluye interfaz de autenticación)
    • Verificación de estado: http://{{your-server-ip}}:8080/api/health

  7. 📢IMPORTANTE - No ejecute con instancias réplica del servidor, ya que la conexión de sesión no se compartirá entre réplicas.

Opciones de Configuración

Archivos de Configuración:

  • appsettings.json - Configuración base para despliegues de producción/servidor. Rastreado en git, y contiene solo valores predeterminados no secretos.
  • appsettings.Development.json - Sobrescribe la configuración base para desarrollo local. También rastreado en git (solo valores predeterminados no secretos) — tiene prioridad en modo Desarrollo. Cualquier variante que complete con credenciales reales permanece sin confirmar; ver .gitignore.
  • .env - Variables de entorno opcionales (copiar de .env.example), puede establecer POLARION_DEFAULT_PROJECT

El servidor usa un arreglo PolarionProjects en appsettings.json para definir una o más configuraciones de instancias de Polarion. Cada objeto en el arreglo representa una configuración distinta accesible mediante un alias de URL único.

Configuración de Nivel SuperiorDescripción
PolarionProjects(Arreglo) Contiene uno o más objetos de configuración de proyectos de Polarion.
McpAuth(Objeto, opcional) Autenticación de servidor de recursos OAuth 2.1 para el endpoint MCP. Desactivado por defecto.
Rbac(Objeto, opcional) Puerta de visibilidad de proyectos de Polarion por llamador para llamadas de herramientas MCP. Desactivado por defecto; requiere McpAuth.
Credentials(Objeto, opcional) Controla qué credencial de Polarion usa una llamada MCP aguas arriba. Por defecto usa el comportamiento actual de cuenta de servicio compartida.

Cada Objeto de Configuración de Proyecto:

ConfiguraciónDescripciónRequeridoPredeterminado
ProjectUrlAliasUna cadena única usada en la URL de conexión (/{ProjectUrlAlias}/mcp) para identificar esta configuración.SíN/A
Default(booleano) Si true, esta configuración se usa si el cliente se conecta sin especificar un ProjectUrlAlias. Solo una entrada puede ser true.Nofalse
SessionConfig(Objeto) Contiene los detalles de conexión específicos para esta instancia de Polarion.SíN/A
PolarionWorkItemTypes(Arreglo, Opcional) Define campos personalizados para recuperar para tipos específicos de WorkItem dentro de este proyecto. Cada objeto en el arreglo debe tener un id (cadena, ID de tipo de WorkItem) y fields (arreglo de cadenas, nombres de campos personalizados).NoLista Vacía

Detalles del Objeto SessionConfig:

ConfiguraciónDescripciónRequeridoPredeterminado
ServerUrlURL del servidor de Polarion (p. ej., "https://polarion.example.com/")SíN/A
UsernameNombre de usuario de Polarion con permisos apropiados.SíN/A
PasswordContraseña para el usuario de Polarion. (Considere alternativas seguras)SíN/A
ProjectIdEl ID real del proyecto de Polarion con el que interactuar.SíN/A
TimeoutSecondsTiempo de espera de conexión en segundos.No60

Anulación de Contraseña mediante Variable de Entorno

En lugar de colocar contraseñas en archivos de configuración, establezca la variable de entorno POLARION_PASSWORD. Cuando se establece, anula SessionConfig.Password para todos los proyectos configurados.

Ejemplo con Docker:

docker run -d \
  --name polarion-mcp-server \
  -p 8080:8080 \
  -e POLARION_PASSWORD=your-secret-password \
  -v appsettings.json:/app/appsettings.json \
  peakflames/polarion-remote-mcp-server

Esto funciona tanto para PolarionRemoteMcpServer (HTTP) como para PolarionMcpServer (stdio).

Nota: Se recomienda encarecidamente usar la variable de entorno POLARION_PASSWORD o métodos más seguros para almacenar credenciales (como User Secrets, Azure Key Vault, etc.) en lugar de colocar contraseñas en texto plano en appsettings.json.

Alineación con la Especificación de la API REST

La API REST está diseñada para alinearse con la especificación oficial de la API REST de Polarion disponible en https://testdrive.polarion.com/polarion/rest/v1/definition. Se mantiene una copia local de esta definición en docs/polarion-rest-vq-definition.json como referencia al implementar o extender endpoints.

Autenticación mediante Clave de API (Solo API REST)

Los endpoints de la API REST requieren autenticación mediante clave de API. Configure los consumidores de la API en la sección ApiConsumers de appsettings.json:

ConfiguraciónDescripciónRequerido
ApiConsumers.ConsumersDiccionario de configuraciones de consumidores claveado por ID de consumidorSí
NameNombre para mostrar del consumidor de la APISí
ApplicationKeyLa clave de API usada para autenticaciónSí
ActiveSi el consumidor está autorizado para autenticarseSí
AllowedScopesLista de alcances (p. ej., ["polarion:read"])Sí
DescriptionDescripción opcional del consumidorNo

Alcances Disponibles:

  • polarion:read - Acceso de lectura a todos los endpoints de la API REST

Uso:

curl -H "X-API-Key: your-api-key" http://localhost:8080/polarion/rest/v1/projects/{projectId}/spaces

Nota: Las verificaciones de estado (/api/health, /api/version) y la documentación de la API (/scalar/v1) no requieren autenticación. Los endpoints MCP tampoco requieren autenticación, solo mientras McpAuth:Enabled sea false (el valor predeterminado) — ver la siguiente sección.

Opcional: Autenticación MCP y Control de Acceso por Llamador

PolarionRemoteMcpServer admite dos características independientes, desactivadas por defecto, para el endpoint MCP:

  • Autenticación OAuth 2.1 (McpAuth:Enabled) — requiere un token de portador de un servidor de autorización externo antes de que se permita ejecutar un tools/call. Cada alias de proyecto servido publica sus propios metadatos de recurso protegido RFC 9728 en /.well-known/oauth-protected-resource/{alias}/mcp, de modo que un cliente MCP conforme pueda descubrir cómo autenticarse automáticamente.
  • RBAC por llamador (Rbac:Enabled) — además autoriza cada tools/call contra la membresía de proyecto de Polarion del usuario que llama, en lugar de que cada llamador autenticado comparta el mismo acceso. Requiere McpAuth:Enabled=true.

Ambas están false por defecto, y el comportamiento del servidor no cambia respecto a versiones anteriores a menos que las configure. Ver docs/authentication.md y docs/rbac.md para configuración, tablas de referencia de configuración y errores de validación al inicio.

Una tercera característica desactivada por defecto es la herramienta de consulta SQL:

ClavePredeterminadoEfecto
SqlQueryTool:EnabledfalseCuando true, registra la herramienta search_workitems_sql en ambos servidores. La herramienta está contenida en el proyecto (ver docs/rbac.md), por lo que no necesita regla RBAC por herramienta, pero expone un oráculo de sí/no sobre la existencia de datos en otros proyectos mediante joins pesados — déjela desactivada si ese residuo es inaceptable.

Configuración de Clientes MCP

Para configurar Cline:

  1. Abra la interfaz de configuración de MCP de Cline
  2. Haga clic en la pestaña "Servidores Remotos"
  3. Para cada ProjectUrlAlias en su appsettings.json al que el usuario quiera conectarse:
{
  "mcpServers": {
    ...
    ...

    "Polarion Starlight": {
      "autoApprove": [],
      "disabled": true,
      "timeout": 60,
      "url": "http://{{your-server-ip}}:8080/starlight/mcp",
      "transportType": "streamableHttp"
    },
    "Polarion Octopus": {
      "autoApprove": [],
      "disabled": true,
      "timeout": 60,
      "url": "http://{{your-server-ip}}:8080/octopus/mcp",
    "transportType": "streamableHttp"
    }
  ...
  ...
}
  1. Repita para cada ProjectUrlAlias al que quiera conectarse.

Para configurar Visual Studio Code:

Agregue la siguiente configuración a su archivo settings.json:

"servers": {
    "polarion-starlight": { // Use a descriptive key
        "type": "http",
        "url": "http://{{your-server-ip}}:8080/starlight/mcp", // Replace with your alias
        "env": {}
    },
    "polarion-octopus": { 
        "type": "http",
        "url": "http://{{your-server-ip}}:8080/octopus/mcp", // Replace with your alias
        "env": {}
    }
    // Add entries for each ProjectUrlAlias
}

O desde la CLI:

claude mcp add --transport http polarion-starlight http://{{your-server-ip}}:8080/starlight/mcp

Para Claude Desktop:

Claude Desktop aún no admite HTTP transmisible de forma nativa, pero puede usar un proxy con la siguiente adición al archivo claude_desktop_config.json:

{
  "mcpServers": {
    "polarion-remote": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://{{your-server-ip}}:8080/{ProjectUrlAlias}/mcp" // Replace {ProjectUrlAlias}
      ]
    }
    // Add entries for each ProjectUrlAlias, potentially using different keys like "polarion-starlight"
  }
}

Ejecución Local (stdio)

Para desarrollo local o uso en estación de trabajo, puede ejecutar el servidor MCP basado en stdio:

  1. Descargue el ejecutable apropiado para su plataforma desde la página de versiones
  2. Configure su cliente MCP para usar el transporte stdio con la ruta del ejecutable

Solución de Problemas

POST /{alias}/mcp devuelve 401 y el cliente nunca solicita iniciar sesión — confirme que el cliente implementa el flujo de descubrimiento OAuth de MCP (RFC 9728). Obtenga /.well-known/oauth-protected-resource/{alias}/mcp usted mismo; si eso devuelve 404, McpAuth:Enabled no está realmente true en el servidor en ejecución. Ver docs/authentication.md.

POST /{alias}/mcp devuelve 403 — el llamador se autenticó, pero le falta el alcance requerido o su ID de cliente OAuth no está en McpAuth:AllowedClientIds. Ver 401 vs 403. El servidor se niega a iniciar con un error de validación McpAuth o Rbac — cada mensaje indica la clave exacta a corregir; consulta las tablas de errores de validación en docs/authentication.md y docs/rbac.md.

Cada llamada a una herramienta MCP es denegada bajo RBAC — RBAC falla de forma cerrada por diseño. Configura Rbac:AuditOnly=true y lee el campo DecisionReason de los registros de auditoría de acceso; consulta docs/rbac.md#troubleshooting.

Contribuciones

Para desarrolladores que quieran contribuir o compilar desde el código fuente, consulta CONTRIBUTING.md.

Licencia

Consulta LICENSE para más detalles.