# apex-mcp-framework

<!-- mcp-name: io.github.ogconstrutorasp/apex-contabil -->

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](https://github.com/ogconstrutorasp/Apex-Contabil). 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`:

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

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

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

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

## 🌐 Catálogo público

- Metadados para registro: [`server.json`](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](LICENSE).