MCP Server para IBM ALM/EWM

Servidor MCP (Model Context Protocol) que expõe operações de leitura e escrita no IBM ALM/EWM, permitindo que agentes AI interajam diretamente com work items (CCM) e requisitos (RM).

Funcionalidades

CCM (Change Management)

• ccm_read_workitem — Lê um work item pelo número
• ccm_classify_workitem — Classifica IB como MIGRACAO/CORRETIVA/MELHORIA
• ccm_create_workitem — Cria IB ou Tarefa
• ccm_update_workitem — Atualiza título/descrição
• ccm_create_workitem_with_children — Cria IB com tasks filhas (planejamento)

RM (Requirements Management)

• rm_read_artifact — Lê artefato RM pela URI
• rm_create_artifact — Cria requisito (HF, EL, ET, REG)
• rm_update_artifact — Atualiza artefato existente
• rm_check_duplicate — Verifica duplicidade de título

Discovery

• discover_project — Discovery completo de uma Project Area
• list_workitem_types — Lista tipos de work item (CCM)
• list_artifact_types — Lista tipos de artefato (RM)
• list_iterations — Lista sprints/iterações
• list_folders — Lista pastas RM
• list_shape_fields — Lista campos de um shape

Instalação

Pré-requisitos

1. Python 3.11+ com pip
2. Credenciais do IBM ALM configuradas

Instalar dependências

cd alm/mcp
pip install -r requirements.txt

Configurar credenciais

Crie o arquivo de credenciais:

SO	Caminho
Linux/Mac	~/.config/mcp-elm-requisitos/alm.properties
Windows	%APPDATA%\mcp-elm-requisitos\alm.properties

Conteúdo:

[DEFAULT]
server = https://alm.SEU-SERVIDOR
user = SEU_USUARIO
password = SUA_SENHA

⚠️ Nunca versione credenciais! O arquivo alm.properties está no .gitignore.

Configuração no Kiro

Adicione ao arquivo .kiro/settings/mcp.json do projeto:

{
  "mcpServers": {
    "alm": {
      "command": "python",
      "args": ["-m", "alm.mcp.server"],
      "cwd": "/caminho/para/jandaia",
      "env": {
        "PYTHONPATH": "/caminho/para/jandaia/alm/mcp"
      }
    }
  }
}

Ou usando uvx (após publicar no PyPI):

{
  "mcpServers": {
    "alm": {
      "command": "uvx",
      "args": ["mcp-alm"]
    }
  }
}

Uso

Configuração da Project Area

Antes de usar os tools de escrita, configure o arquivo pa_<projeto>.json:

1. Execute o discovery para descobrir a estrutura:

   discover_project(project_area="NOME DA PA")
   

2. Preencha o pa_<projeto>.json com as URLs descobertas (ver pa_template.json)

3. Use os tools passando o caminho do config:

   ccm_create_workitem(config_path="alm/pa_meu-projeto.json", type="IB", title="...")
   

Exemplos de uso

Ler um work item

ccm_read_workitem(workitem_id="633739")

Classificar um IB

ccm_classify_workitem(workitem_id="633739", config_path="alm/pa_pab-batch.json")

Criar um artefato RM

rm_create_artifact(
    config_path="alm/pa_pab-batch.json",
    type="HF",
    title="HF - Consultar Benefícios",
    description_html="<p>História de usuário...</p>",
    module="GESTAO"
)

Criar IB com tasks

ccm_create_workitem_with_children(
    config_path="alm/pa_pab-batch.json",
    parent={
        "title": "[Exportação] Implementar novo job de exportação",
        "description_html": "<p>Descrição do IB...</p>",
        "iteration": "sprint_01"
    },
    children=[
        {"title": "[BE] Implementar ExportacaoJobConfig"},
        {"title": "[BE] Implementar ExportacaoStepConfig"},
        {"title": "[QA] Criar testes do job de exportação"}
    ]
)

Estrutura do módulo

alm/mcp/
├── __init__.py          # Versão do módulo
├── server.py            # Servidor MCP (entry point)
├── auth.py              # Autenticação JTS e sessão HTTP
├── common.py            # Namespaces, helpers e discovery compartilhados
├── ccm_tools.py         # Tools de work items (CCM)
├── rm_tools.py          # Tools de requisitos (RM)
├── discovery_tools.py   # Tools de discovery
├── requirements.txt     # Dependências Python
└── README.md            # Esta documentação

Troubleshooting

Erro de autenticação

Falha na autenticação — verifique usuário/senha no alm.properties

• Verifique se o arquivo alm.properties existe no caminho correto
• Verifique se as credenciais estão corretas
• Confirme que o usuário tem acesso à Project Area

Sessão expirada

Sessão expirada ou sem acesso — servidor retornou página HTML

O servidor retornou HTML em vez de XML/JSON. Causas comuns:

• Credenciais inválidas
• Usuário sem acesso à PA
• Sessão expirou (reconecte)

Project Area não encontrada

Project Area não encontrada: NOME DA PA

• Verifique o nome exato da PA (case-sensitive em alguns servidores)
• Use discover_project para listar PAs disponíveis

Tipo não configurado

Tipo 'IB' não configurado no pa.json

Execute o discovery e configure os tipos no pa_<projeto>.json:

list_workitem_types(config_path="alm/pa_projeto.json")

Contribuindo

1. Mantenha o código em common.py para funções reutilizáveis
2. Siga o padrão de retorno: string formatada para o agente
3. Adicione docstrings com Args e Returns
4. Atualize a versão em __init__.py ao fazer mudanças

Licença

Uso interno Dataprev — parte do kit JandaIA.