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

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:

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:

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

Testes

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)

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.