mcp-server-polarion
Polarion ALM MCP server para Claude, Cursor & Copilot — ler e escrever documentos, itens de trabalho e links de rastreabilidade
Documentação
mcp-server-polarion
Fale com seu Polarion — a IA lê, escreve e reorganiza documentos, work items, execuções de teste e links de rastreabilidade.
Recursos · Início rápido · Ferramentas · Exemplos de prompts · Configuração
Um servidor Model Context Protocol (MCP) para Polarion ALM, construído para instâncias reais: toda operação de escrita suporta dry_run, guardas validam campos e valores de enum antes de qualquer commit, e as requisições são ritmadas conforme um limite de taxa que você configura para sua instância — para que um assistente de IA possa trabalhar em dados de produção sem surpresas.

Recursos
- 46 ferramentas cobrindo leitura e escrita em documentos, work items, execuções de teste, links de rastreabilidade, comentários e anexos.
- Leitura — renderiza documentos como Markdown, busca com Lucene ou SQL, percorre links de entrada/saída, resolve opções de enum.
- Escrita — cria e atualiza work items, documentos e execuções de teste, gerencia links, reorganiza a estrutura de documentos, publica comentários.
- Escritas seguras — toda ferramenta de escrita suporta
dry_run, e guardas pré-escrita validam campos, valores de enum e alvos de link antes de atingir o Polarion. - Compatível com seu servidor — as requisições são serializadas e ritmadas conforme um limite de taxa configurável, com novas tentativas automáticas em respostas 429/5xx.
- Feito para LLMs — async estrito, totalmente tipado, paginação em toda ferramenta de listagem, docstrings escritas como manual do assistente.
Início rápido
Requer Polarion 2506+ e uv — veja Pré-requisitos. Caminho mais rápido — Claude Code:
claude mcp add mcp-server-polarion \
-e POLARION_URL=https://polarion.example.com \
-e POLARION_TOKEN=your-personal-access-token \
-- uvx mcp-server-polarion
Outros clientes (VS Code, Claude Desktop, Cursor) — veja Configuração do cliente.
Ferramentas
Leitura
| Ferramenta | Descrição |
|---|---|
list_projects | Lista projetos acessíveis |
list_documents | Lista documentos em um projeto |
list_work_items | Lista work items em um projeto (consulta Lucene/SQL) |
list_test_runs | Lista execuções de teste em um projeto (consulta Lucene, filtro de modelos) |
get_test_run | Obtém detalhes da execução de teste, opcionalmente com o corpo do relatório HTML bruto |
list_test_records | Lista os registros de execução de uma execução de teste, um por iteração de caso de teste |
get_test_record | Obtém o comentário de execução e a revisão do caso de teste de um registro de teste |
get_sql_query_recipes | Busca receitas SQL prontas para copiar e colar para consultas avançadas |
get_html_recipes | Busca modelos HTML do Polarion prontos para copiar e colar para edições de corpo HTML bruto |
get_document | Obtém metadados do documento, opcionalmente com o corpo HTML bruto |
read_document | Renderiza um documento de ponta a ponta como Markdown |
read_document_parts | Lista as partes estruturais de um documento com metadados de work item incorporados |
get_work_item | Obtém detalhes do work item com o corpo como HTML bruto |
read_work_item | Obtém detalhes do work item com o corpo como Markdown |
list_work_item_links | Lista os links de saída ou entrada de um work item |
list_document_attachments | Lista os anexos de um documento com nome do arquivo, tamanho e autor |
get_document_attachment_content | Busca um anexo de imagem para visualização (bitmap como imagem, SVG como texto) |
list_work_item_attachments | Lista os anexos de um work item com nome do arquivo, tamanho e autor |
get_work_item_attachment_content | Busca um anexo de imagem de work item para visualização (bitmap como imagem, SVG como texto) |
list_test_record_attachments | Lista os anexos de um registro de teste com nome do arquivo, tamanho e autor |
get_test_record_attachment_content | Busca um anexo de imagem de registro de teste para visualização (bitmap como imagem, SVG como texto) |
list_document_comments | Lista os comentários de um documento com relações de thread |
list_work_item_comments | Lista os comentários de um work item com relações de thread |
list_document_enum_options | Resolve IDs de enum válidos para um campo de documento |
list_work_item_enum_options | Resolve IDs de enum válidos para um campo de work item |
Todas as ferramentas de listagem suportam paginação via parâmetros page_size (1–100) e page_number.
Escrita
| Ferramenta | Descrição |
|---|---|
create_work_items | Cria um ou mais work items em uma única requisição |
update_work_items | Atualiza campos, corpo ou status de workflow em um ou mais work items |
create_document | Cria um novo documento |
update_document | Atualiza metadados do documento, corpo ou status de workflow |
copy_document | Copia um documento para um novo nome, espaço ou projeto |
create_test_runs | Cria uma ou mais execuções de teste, opcionalmente a partir de um modelo |
create_test_records | Registra resultados de execução de casos de teste em uma execução de teste |
update_test_runs | Atualiza título, status, grupo ou campos personalizados em uma ou mais execuções de teste |
update_test_records | Atualiza resultado, comentário ou link de defeito em um ou mais registros de teste de uma execução de teste |
create_work_item_links | Cria um ou mais links de saída a partir de um work item de origem |
update_work_item_link | Atualiza suspect / revision em um link de saída |
delete_work_item_links | Exclui um ou mais links de saída de um work item de origem |
move_work_item_to_document | Anexa um work item a um documento em uma posição escolhida |
move_work_item_from_document | Desanexa um work item de seu documento |
create_document_attachments | Envia um ou mais arquivos locais como anexos de documento |
create_work_item_attachments | Envia um ou mais arquivos locais como anexos de work item |
create_test_record_attachments | Envia um ou mais arquivos locais como anexos de registro de teste |
create_document_comments | Adiciona um ou mais comentários ou respostas a um documento |
create_work_item_comments | Adiciona um ou mais comentários ou respostas a um work item |
update_document_comment | Resolve ou reabre um comentário de documento |
update_work_item_comment | Resolve ou reabre um comentário de work item |
Exemplos de prompts
Descoberta e busca
"Liste os projetos aos quais tenho acesso e mostre os documentos do projeto MCPT com seus tipos."
"Liste os documentos no espaço 'Specifications' do projeto MCPT."
"Encontre todos os requisitos aprovados no projeto MCPT cujo título começa com 'Auth' e mostre-me o documento proprietário de cada um."
"Pesquise no projeto MCPT por work items onde o campo personalizado 'verification_method' é 'Test' — consulte as receitas SQL primeiro se precisar de um join."
"Encontre todos os work items no módulo SRS do projeto MCPT que foram alterados no último sprint."
Leitura e resumo
"Leia o documento SRS do projeto MCPT e resuma cada requisito em aberto."
"Mostre-me o esboço estrutural do documento SRS — títulos e os work items sob cada um."
"Leia o work item MCPT-042 como Markdown e explique o que ele pede."
"Mostre os links de saída e entrada para MCPT-042 e sinalize qualquer tarefa filha ainda em aberto."
"Quais requisitos no documento SRS não têm um link de retorno 'verifies' de um caso de teste?"
"Liste as threads de comentários em aberto no documento SRS e quem iniciou cada uma."
Criação e edição
"Crie uma tarefa no projeto MCPT intitulada 'Refatorar módulo de autenticação' e vincule-a a MCPT-042 como 'relates_to'."
"Crie três work items de caso de teste no projeto MCPT a partir desta lista de verificação e vincule cada um a MCPT-042 como 'verifies'."
"Adicione um novo requisito sob a seção 3.2 do documento SRS com o corpo que acabei de redigir."
"Atualize a descrição de MCPT-042 com o texto revisado que vou colar, mantendo a formatação existente."
"Adicione um comentário no documento SRS pedindo ao proprietário para esclarecer a seção 4 e depois responda à thread T-12 marcando-a como resolvida."
"Crie uma execução de teste REG-SPRINT-7 no projeto MCPT a partir do modelo 'Regression' com status 'open'."
Workflow e reorganização
"Liste os valores de status válidos para um defeito no projeto MCPT e depois mova MCPT-077 para 'in_review'."
"Aumente a prioridade de MCPT-042 para 90, defina a severidade como 'major' e aprove o workflow."
"Altere MCPT-201 de tarefa para requisito e reaplique seu status anterior."
"Mova MCPT-201 para o documento SRS logo após MCPT-150."
"Desanexe MCPT-077 de seu documento para que eu possa retrabalhá-lo como uma tarefa independente."
"Marque o link 'blocks' de MCPT-042 para MCPT-099 como suspeito e depois exclua o link 'relates_to' obsoleto para MCPT-010."
Configuração
Pré-requisitos
Polarion 2506 ou superior é necessário. Versões anteriores não possuem os endpoints da API REST dos quais este servidor depende.
Este servidor é distribuído como um pacote Python e requer uv para executar.
Instale o uv (se ainda não estiver instalado):
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
Ou via pip:
pip install uv
Nenhuma outra instalação é necessária — uvx mcp-server-polarion baixa e executa o servidor automaticamente.
Variáveis de ambiente
| Variável | Descrição | Exemplo |
|---|---|---|
POLARION_URL | URL base da sua instância Polarion | https://polarion.example.com |
POLARION_TOKEN | Token de acesso pessoal para autenticação | your-personal-access-token |
POLARION_MAX_REQUESTS_PER_SECOND | Opcional. Limite de taxa de requisições do lado do cliente — aumente para corresponder ao throttle da sua implantação, ou defina 0 para desativar o ritmo. Escritas mantêm uma pausa extra fixa independentemente (padrão: 1) | 1 |
Para gerar um Token de acesso pessoal, abra o Polarion, clique no seu nome de usuário e vá para My Account → Personal Access Tokens.
Configuração do cliente
VS Code (GitHub Copilot)
Adicione a .vscode/mcp.json:
{
"servers": {
"mcp-server-polarion": {
"type": "stdio",
"command": "uvx",
"args": ["mcp-server-polarion"],
"env": {
"POLARION_URL": "https://polarion.example.com",
"POLARION_TOKEN": "your-personal-access-token"
}
}
}
}
Claude Desktop
Adicione a claude_desktop_config.json:
{
"mcpServers": {
"mcp-server-polarion": {
"command": "uvx",
"args": ["mcp-server-polarion"],
"env": {
"POLARION_URL": "https://polarion.example.com",
"POLARION_TOKEN": "your-personal-access-token"
}
}
}
}
Cursor
Adicione às configurações MCP do Cursor:
{
"mcpServers": {
"mcp-server-polarion": {
"command": "uvx",
"args": ["mcp-server-polarion"],
"env": {
"POLARION_URL": "https://polarion.example.com",
"POLARION_TOKEN": "your-personal-access-token"
}
}
}
}
Claude Code
Registre via o comando claude mcp add:
claude mcp add mcp-server-polarion \
-e POLARION_URL=https://polarion.example.com \
-e POLARION_TOKEN=your-personal-access-token \
-- uvx mcp-server-polarion
Contribuindo
Relatórios de bugs e pull requests são bem-vindos — veja CONTRIBUTING.md para convenções de branch, commit e revisão.