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

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

CI Publish PyPI Python 3.13+ License: MIT

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.

mcp-server-polarion demo

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

FerramentaDescrição
list_projectsLista projetos acessíveis
list_documentsLista documentos em um projeto
list_work_itemsLista work items em um projeto (consulta Lucene/SQL)
list_test_runsLista execuções de teste em um projeto (consulta Lucene, filtro de modelos)
get_test_runObtém detalhes da execução de teste, opcionalmente com o corpo do relatório HTML bruto
list_test_recordsLista os registros de execução de uma execução de teste, um por iteração de caso de teste
get_test_recordObtém o comentário de execução e a revisão do caso de teste de um registro de teste
get_sql_query_recipesBusca receitas SQL prontas para copiar e colar para consultas avançadas
get_html_recipesBusca modelos HTML do Polarion prontos para copiar e colar para edições de corpo HTML bruto
get_documentObtém metadados do documento, opcionalmente com o corpo HTML bruto
read_documentRenderiza um documento de ponta a ponta como Markdown
read_document_partsLista as partes estruturais de um documento com metadados de work item incorporados
get_work_itemObtém detalhes do work item com o corpo como HTML bruto
read_work_itemObtém detalhes do work item com o corpo como Markdown
list_work_item_linksLista os links de saída ou entrada de um work item
list_document_attachmentsLista os anexos de um documento com nome do arquivo, tamanho e autor
get_document_attachment_contentBusca um anexo de imagem para visualização (bitmap como imagem, SVG como texto)
list_work_item_attachmentsLista os anexos de um work item com nome do arquivo, tamanho e autor
get_work_item_attachment_contentBusca um anexo de imagem de work item para visualização (bitmap como imagem, SVG como texto)
list_test_record_attachmentsLista os anexos de um registro de teste com nome do arquivo, tamanho e autor
get_test_record_attachment_contentBusca um anexo de imagem de registro de teste para visualização (bitmap como imagem, SVG como texto)
list_document_commentsLista os comentários de um documento com relações de thread
list_work_item_commentsLista os comentários de um work item com relações de thread
list_document_enum_optionsResolve IDs de enum válidos para um campo de documento
list_work_item_enum_optionsResolve 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

FerramentaDescrição
create_work_itemsCria um ou mais work items em uma única requisição
update_work_itemsAtualiza campos, corpo ou status de workflow em um ou mais work items
create_documentCria um novo documento
update_documentAtualiza metadados do documento, corpo ou status de workflow
copy_documentCopia um documento para um novo nome, espaço ou projeto
create_test_runsCria uma ou mais execuções de teste, opcionalmente a partir de um modelo
create_test_recordsRegistra resultados de execução de casos de teste em uma execução de teste
update_test_runsAtualiza título, status, grupo ou campos personalizados em uma ou mais execuções de teste
update_test_recordsAtualiza resultado, comentário ou link de defeito em um ou mais registros de teste de uma execução de teste
create_work_item_linksCria um ou mais links de saída a partir de um work item de origem
update_work_item_linkAtualiza suspect / revision em um link de saída
delete_work_item_linksExclui um ou mais links de saída de um work item de origem
move_work_item_to_documentAnexa um work item a um documento em uma posição escolhida
move_work_item_from_documentDesanexa um work item de seu documento
create_document_attachmentsEnvia um ou mais arquivos locais como anexos de documento
create_work_item_attachmentsEnvia um ou mais arquivos locais como anexos de work item
create_test_record_attachmentsEnvia um ou mais arquivos locais como anexos de registro de teste
create_document_commentsAdiciona um ou mais comentários ou respostas a um documento
create_work_item_commentsAdiciona um ou mais comentários ou respostas a um work item
update_document_commentResolve ou reabre um comentário de documento
update_work_item_commentResolve 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ávelDescriçãoExemplo
POLARION_URLURL base da sua instância Polarionhttps://polarion.example.com
POLARION_TOKENToken de acesso pessoal para autenticaçãoyour-personal-access-token
POLARION_MAX_REQUESTS_PER_SECONDOpcional. 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.

Licença

MIT