Metadata-Version: 2.5
Name: mcp-alm
Version: 1.0.4
Summary: MCP Server para IBM ALM/EWM (OSLC CCM + RM)
Project-URL: Homepage, https://github.com/dataprev/jandaia
Project-URL: Documentation, https://github.com/dataprev/jandaia/tree/main/alm/mcp
Author-email: JandaIA <jandaia@dataprev.gov.br>
License-Expression: MIT
Keywords: alm,change-management,ewm,ibm,mcp,oslc,requirements
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Requires-Dist: mcp<2.0.0,>=1.0.0
Requires-Dist: requests>=2.28.0
Requires-Dist: urllib3>=1.26.0
Description-Content-Type: text/markdown

# 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

```bash
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:

```ini
[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:

```json
{
  "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):

```json
{
  "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

```python
ccm_read_workitem(workitem_id="633739")
```

#### Classificar um IB

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

#### Criar um artefato RM

```python
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

```python
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`:

```bash
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.
