Servidor MCP de Polarion

Un servidor de Model Context Protocol (MCP) de Polarion de código abierto, instalable y con protección contra escritura. Lee LiveDocs, elementos de trabajo y relaciones de seguimiento a través de los servicios web SOAP incluidos en la instalación de Polarion de destino, y realiza operaciones de creación, modificación y eliminación solo tras una confirmación explícita.

Windows ofrece instalación con un solo clic y cifrado de credenciales mediante DPAPI. Linux/macOS pueden ejecutarse manualmente con Node.js y variables de entorno. El repositorio no contiene ninguna cuenta, contraseña, token, cookie, dirección de servidor privada, ID de proyecto ni texto de requisitos.

Capacidades principales

Los límites de validación completos se describen en la matriz de cobertura funcional.

Related MCP server: permission-aware-mcp

Cómo funciona

El proceso MCP no extrae páginas web, no lee cookies del navegador ni elude los permisos de Polarion. La asociación automática del navegador solo se encarga de entregar la URL de la pestaña actual de Polarion al MCP; la lectura y escritura de los datos de requisitos se realiza íntegramente a través del SOAP MCP.

Instalación con un solo clic en Windows

Requisitos previos

• Windows 10/11

• Node.js 20 o superior

• Git

• Codex CLI (comando codex disponible)

• Un servidor Polarion accesible con /polarion/ws/services/*?wsdl abierto

• Una cuenta de Polarion o PAT con los permisos de proyecto correspondientes

1. Clonar

git clone https://github.com/suzike/polarion-mcp-server.git
cd polarion-mcp-server

2. Instalación y registro

Instalación interactiva:

.\scripts\install.ps1

El instalador:

1. Comprueba Node.js, npm y Codex CLI;

2. Ejecuta npm ci, compilación estricta y pruebas;

3. Pregunta por la dirección de Polarion y el método de autenticación;

4. Solicita la contraseña o PAT en el aviso de credenciales seguras de Windows;

5. Realiza una copia de seguridad del ~/.codex/config.toml existente;

6. Registra el MCP polarion a nivel de usuario;

7. Verifica que Codex puede leer la nueva configuración.

Ejemplo de configuración no interactiva (las credenciales se siguen introduciendo mediante el aviso seguro):

.\scripts\install.ps1 `
  -BaseUrl "https://polarion.example.com/polarion" `
  -DefaultProject "MY_PROJECT" `
  -DefaultDocumentLocation "Requirements/Software Requirements" `
  -AuthMode password `
  -Force

Reinicie Codex después de la instalación.

3. Comprobar el entorno

.\scripts\doctor.ps1
codex mcp get polarion

Gestión de credenciales

Las credenciales nunca entran en el repositorio ni en config.toml. El flujo de instalación de Windows escribe por defecto:

%LOCALAPPDATA%\PolarionMcp\credentials.json

donde el secreto se cifra con DPAPI de Windows vinculado al usuario actual de Windows, y la ACL del archivo deshabilita la herencia y solo permite el acceso al usuario actual. Al iniciar el MCP, el launcher inyecta temporalmente el secreto en el entorno del proceso hijo y lo elimina inmediatamente al salir.

Restablecer credenciales:

.\scripts\setup-credentials.ps1 -AuthMode password
# 或
.\scripts\setup-credentials.ps1 -AuthMode access_token

Algunos servidores de Polarion pueden tener deshabilitado el inicio de sesión SOAP con PAT. En ese caso, use autenticación por contraseña o contacte con el administrador para habilitar la autenticación AccessToken.

Uso

Después de reiniciar Codex, puede decir directamente:

检查 Polarion 连接状态。
读取项目 MY_PROJECT 的需求文档 Requirements/Software Requirements。
读取工作项 REQ-123，并列出它的追踪链接。
查询 MY_PROJECT 中状态为 approved 的 requirement，最多返回 20 条。

Asociación automática del proyecto del navegador actual

En un Host MCP con control del navegador, puede decir:

读取当前浏览器打开的 Polarion 文档前 20 条需求。

El Host obtiene #/project/{projectId}/... de la URL de la pestaña activa y pasa la URL completa al parámetro polarion_url de la herramienta. El MCP valida que la URL sea del mismo origen que el servicio de Polarion configurado y resuelve automáticamente la ubicación del proyecto y del documento wiki.

Si el Host no tiene capacidades de navegador, hay varias pestañas que no se pueden distinguir, o la pestaña actual no es Polarion, proporcione explícitamente project_id.

Creación, modificación y eliminación

Las herramientas de escritura no permiten usar un proyecto predeterminado de forma silenciosa. Debe pasarse explícitamente project_id o polarion_url, y proporcionar un valor de confirmación preciso:

Ejemplo de conversación:

在 MY_PROJECT 创建一条 task，标题为“接口检查”。执行前先给我预览并询问确认。

El Host debe mostrar primero el proyecto, el tipo, el título y la descripción; solo después de que el usuario confirme explícitamente se pasa la cadena de confirmación. Polarion seguirá aplicando los permisos de la cuenta, la configuración de tipos, el flujo de trabajo y las comprobaciones de auditoría.

Ejecución manual y otros Hosts MCP

Compilación:

npm ci
npm run build

En Windows se recomienda el launcher seguro:

$env:POLARION_BASE_URL = "https://polarion.example.com/polarion"
$env:POLARION_PROJECT_ID = "MY_PROJECT"          # 可选
$env:POLARION_NODE_PATH = (Get-Command node).Source
.\scripts\start-secure.ps1

En Linux/macOS, las variables de entorno pueden ser proporcionadas por un gestor de contraseñas o un gestor de procesos, y luego ejecutar:

export POLARION_BASE_URL="https://polarion.example.com/polarion"
export POLARION_AUTH_MODE="access_token"
export POLARION_ACCESS_TOKEN="$(your-secret-manager read polarion-token)"
node dist/index.js

No escriba secretos en archivos .env con seguimiento ni en la configuración JSON del MCP.

Actualización y desinstalación

Actualización:

git pull --ff-only
npm ci
npm test
npm run build

Desregistrar pero conservar las credenciales cifradas:

.\scripts\uninstall.ps1

Eliminar también las credenciales cifradas del usuario actual de Windows:

.\scripts\uninstall.ps1 -RemoveCredentials

Verificación y desarrollo

npm test                 # 严格编译 + 单元/契约测试
npm run smoke            # MCP 协议和 8 个工具清单
npm audit --omit=dev     # 生产依赖漏洞检查

Las pruebas de integración de autenticación requieren configurar manualmente parámetros de destino no secretos:

$env:POLARION_BASE_URL = "https://polarion.example.com/polarion"
$env:POLARION_TEST_PROJECT_ID = "SANDBOX_PROJECT"
$env:POLARION_TEST_DOCUMENT_LOCATION = "Requirements/Test Document"
$env:POLARION_TEST_WORK_ITEM_ID = "REQ-1"
npm run integration:secure

Las autopruebas de escritura reales se rechazan por defecto. Solo configure después de recibir autorización explícita y elegir un proyecto desechable:

$env:POLARION_TEST_PROJECT_ID = "SANDBOX_PROJECT"
$env:POLARION_CONFIRM_LIVE_WRITE_TEST = "CREATE_UPDATE_DELETE:SANDBOX_PROJECT"
npm run integration:write-self-test

Esta prueba crea un elemento temporal a nivel de proyecto, lo modifica y lo elimina; no añade elementos a un LiveDoc por iniciativa propia. No ejecute autopruebas de escritura sobre documentos de requisitos oficiales.

Condiciones y limitaciones conocidas

• polarion_query_work_items requiere el permiso de consulta SOAP correspondiente; algunas cuentas pueden leer IDs conocidos directamente, pero no pueden ejecutar consultas Lucene globales.

• Los tipos de elemento de trabajo, estados y flujos de trabajo varían según el proyecto de Polarion; la herramienta de creación no ofrece un tipo predeterminado genérico.

• La solicitud SOAP para crear en un LiveDoc tiene pruebas de contrato, pero no se ha realizado una validación destructiva en documentos oficiales antes de su publicación.

• La asociación automática del navegador actual la orquesta el Host MCP; no es el MCP el que lee directamente el navegador.

• El script de instalación DPAPI de Windows solo es compatible con Windows; en otros sistemas use variables de entorno o integre su propio llavero del sistema.

Documentación

• Instalación y resolución de problemas

• Arquitectura

• Matriz de cobertura funcional

• Referencia de parámetros de herramientas

• Modelo de seguridad

• Registro de cambios

• Guía de contribución

• Política de seguridad

Licencia

MIT © 2026 suzike