# MCP — Gestão de Serviços e Ordens de Serviço

Servidor MCP em Python que expõe CRUD de **Serviços** (catálogo) e **Ordens de Serviço (OS)** para uso conversacional via Claude Desktop / Claude Code. Implementa o [SPEC.md](SPEC.md) com o SDK oficial MCP (low-level `Server`, sem FastMCP), transporte **streamable HTTP** e persistência em **SQLite**.

## Arquitetura (camadas)

```
src/gestao_os/
├── main.py                  # Entrypoint: ASGI (Starlette + uvicorn), streamable HTTP em /mcp
├── server.py                # Montagem do Server MCP: instructions, list_tools, call_tool
├── database.py              # SQLite: schema e transações (FKs ativas)
├── errors.py                # AppError + códigos do contrato de erros (seção 7)
├── textutil.py              # Normalização case/accent-insensitive (RN01, RN13)
├── models/                  # Entidades: Servico, OrdemServico, OrdemServicoItem
├── repositories/            # Acesso a dados (SQL puro por entidade)
├── services/                # Regras de negócio (RN01–RN10)
└── tools/
    ├── definitions.py       # As 13 tools MCP com inputSchema e descriptions (seções 5 e 6)
    ├── handlers.py          # Validação de argumentos (RN12/RN15) e delegação aos services
    └── validation.py        # Helpers de validação: tipos, paginação (RN14), confirmação (RN12)
```

Fluxo de uma tool call: `server.call_tool` → `handlers` (presença/tipo/confirmação) → `services` (regras de negócio, transação) → `repositories` (SQL) → JSON estruturado de volta ao cliente. Erros de negócio retornam `{"erro": "<CODIGO>", "mensagem": "<pt-BR>"}`.

## Requisitos

- Python 3.11+
- Dependências: `mcp>=1.27`, `starlette`, `uvicorn`

## Instalação e execução

```powershell
pip install -e ".[dev]"

# inicia em http://127.0.0.1:8000/mcp (SQLite: .\gestao_os.db)
mcp-gestao-os

# opções
mcp-gestao-os --host 0.0.0.0 --port 8000 --db C:\dados\gestao_os.db
```

(Equivalente: `python -m gestao_os.main`.)

## Conectando o cliente

**Claude Code:**

```powershell
claude mcp add --transport http gestao-os http://127.0.0.1:8000/mcp
```

**Claude Desktop:** adicionar em *Settings → Connectors* (integração remota) apontando para `http://127.0.0.1:8000/mcp`, ou via proxy stdio no `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "gestao-os": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://127.0.0.1:8000/mcp"]
    }
  }
}
```

## Testes

```powershell
python -m pytest
```

A suíte cobre as regras de negócio RN01–RN14: unicidade case/accent-insensitive, snapshot de preço, recálculo de `valor_total`, imutabilidade de OS concluída/cancelada, mínimo de 1 item, confirmação de operações destrutivas, paginação etc.

## Tools expostas (13)

| Grupo | Tools |
|---|---|
| Serviços | `criar_servico`, `alterar_servico`, `excluir_servico`, `listar_servicos`, `buscar_servicos` |
| Ordens de Serviço | `criar_ordem_servico`, `alterar_ordem_servico`, `excluir_ordem_servico`, `listar_ordens_servico`, `consultar_ordem_servico` |
| Itens da OS | `adicionar_item_os`, `remover_item_os`, `alterar_quantidade_item_os` |

Regras conversacionais (desambiguação por busca, confirmação de destrutivas, nunca presumir dados) estão embutidas nas `instructions` do servidor e nas descriptions das tools, conforme a seção 6 do SPEC.