apex-mcp-framework

apex-mcp-framework

Framework MCP reutilizável que conecta um ERP a agentes Model Context Protocol via stdio (Python, SDK oficial mcp 1.x). Expõe capacidades de negócio — classificação de CNAEs, revisão jurídica de contratos, obrigações fiscais, financeiro, marketing com publicação real em Facebook/Instagram, WhatsApp e relatórios — como ferramentas MCP autenticadas.

Projeto derivado do Apex ERP Contábil. Este repositório é o home público do servidor MCP — a publicação nos registries (Smithery, Glama, mcp.so, registry oficial) aponta para cá.

✨ O que é um "framework" aqui?

Você não edita o núcleo do servidor para mudar comportamento. A estrutura é modular:

apex-mcp-framework/
├── pyproject.toml          # empacotamento (pip install -e .)
├── requirements.txt        # mcp>=1.0.0,<2.0.0 (API 1.x do SDK)
├── server.json             # metadados p/ registries MCP
├── src/apex_mcp/
│   ├── __main__.py         # python -m apex_mcp
│   ├── server.py           # servidor MCP (stdio) — raramente mexe
│   ├── config.py           # config via env (ERP_BASE, credenciais)
│   ├── http_client.py      # cliente HTTP com auth Bearer + refresh automático
│   └── tools.py            # ⭐ catálogo de ferramentas — É AQUI QUE VOCÊ ADICIONA
└── examples/
    └── mcp_client.py       # cliente MCP de exemplo

Para adicionar uma ferramenta nova, edite apenas src/apex_mcp/tools.py:

# 1) acrescente o Tool (o agente vê nome + descrição + schema)
Tool(name="minha_ferramenta", description="O que ela faz",
     inputSchema={"type": "object", "properties": {"campo": {"type": "string"}}, "required": ["campo"]}),

# 2) acrescente a rota (método, path na API do ERP)
"minha_ferramenta": ("POST", "/api/meu-modulo/acao", None),

Pronto — o servidor expõe automaticamente. Nenhum outro arquivo muda.

🚀 Instalação e execução

git clone https://github.com/ogconstrutorasp/apex-mcp-framework.git
cd apex-mcp-framework
pip install -r requirements.txt     # ou: pip install -e .
python -m apex_mcp                  # inicia o servidor (stdio)

Configuração (variáveis de ambiente):

Variável	Descrição	Padrão
ERP_BASE	URL base da API do ERP	http://localhost:3001 (produção: https://apex-contabil.vercel.app)
SUPABASE_URL	URL do Supabase (login da conta de serviço)	https://vebileaugzzrgnhgmvmr.supabase.co
SUPABASE_ANON_KEY	chave anon do Supabase	<anon-key>
ERP_MCP_EMAIL / ERP_MCP_PASSWORD	conta de serviço — o framework autentica com Bearer em todas as chamadas e renova o token sozinho	vazio (modo sem auth, avisa)

API key por tenant (x-api-key): consulte o painel do ERP (Fase 5 — máquina-a-máquina).

🔌 Conectar em um cliente MCP

Claude Desktop / qualquer cliente MCP:

{
  "mcpServers": {
    "apex-contabil": {
      "command": "python",
      "args": ["-m", "apex_mcp"]
    }
  }
}

🧰 Ferramentas (13)

classificar_cnae · revisar_contrato · consultar_saldo_cliente · consultar_cronograma_obrigacoes · gerar_post_marketing · publicar_post_agora · analytics_marketing · criar_campanha_meta · gerar_criativos_multiplataforma · enviar_whatsapp · alertas_pendentes · gerar_relatorio · enviar_notificacao

🧪 Testar localmente

python examples/mcp_client.py
# Handshake OK — 13 ferramentas:
#   - classificar_cnae: ...
#   ...

🌐 Catálogo público

• Metadados para registro: server.json
• Catálogo do ERP: https://apex-contabil.vercel.app/api/mcp/catalogo
• Guia de publicação nos registries: veja docs/PUBLICAR-MCP-REGISTRIES.md no repo do ERP.

🔒 Segurança

• O framework só expõe ferramentas do próprio ERP via API autenticada (Bearer de conta de serviço ou x-api-key por tenant) — nunca shell/arquivos arbitrários.
• Credenciais vêm somente de variáveis de ambiente; nada é commitado.
• O SDK está fixado em mcp<2 porque o servidor usa a API 1.x (Server.list_tools/call_tool), removida no 2.x.

📄 Licença

MIT — veja LICENSE.