Sankhya MCP

Conjunto de servidores MCP (Model Context Protocol) que conectam agentes de IA ao ERP Sankhya através da sua API pública.

Monorepo open source (MIT) com um núcleo compartilhado e vários servidores MCP divididos por domínio funcional. Cada servidor roda e é publicado de forma independente — você carrega apenas os domínios que precisa, reduzindo o número de tools no contexto do agente.

⚠️ Aviso de segurança (leia antes de usar)

Este é um projeto público. Leve a sério:

• Credenciais ficam só no servidor, em variáveis de ambiente. Nunca vão para o contexto do LLM, logs ou mensagens de erro (há redação automática de segredos).

• Default é sandbox. Produção exige opt-in explícito (SANKHYA_ENV=production).

• Escrita é protegida: há um modo read-only global e um modo dry-run que mostra o payload que seria enviado sem executar.

• SQL livre (DbExplorerSP.executeQuery) é desabilitado por padrão. Habilite só com plena consciência dos riscos (SANKHYA_ALLOW_RAW_SQL=true).

• Nunca commite .env com credenciais reais.

Related MCP server: Harpia Omnichannel MCP

Arquitetura

sankhya-mcp/
├── packages/
│   ├── core/                 # auth OAuth, HTTP client, gestão/cache de token,
│   │                         # helpers de payload, erros tipados, redação de segredos
│   └── data-dictionary/      # entidades, campos, PKs, mapeamento tabela↔entidade
├── servers/
│   ├── mcp-core/             # tools genéricas + resources do dicionário (REFERÊNCIA)
│   ├── mcp-vendas/           # pedidos, NF-e/NFC-e, CF-e/SAT, caixa, preços, sugestões
│   ├── mcp-financeiro/       # cadastros e movimentos financeiros, baixas, contas
│   ├── mcp-suprimentos/      # produtos, estoque
│   ├── mcp-rh/               # HCM: funcionários, admissão, cadastros de pessoal
│   └── mcp-cadastros/        # clientes, contatos, naturezas, centros de resultado
├── examples/                 # configs de cliente MCP e docker-compose
└── ...                       # turbo, tsconfig base, eslint/prettier, etc.

Stack: TypeScript estrito (ESM/NodeNext), @modelcontextprotocol/sdk, pnpm workspaces + Turborepo, zod, vitest, ESLint + Prettier.

Estratégia de tools (importante)

Em vez de mapear 1 endpoint = 1 tool (o que explodiria o contexto), usamos:

• Tools genéricas com a entidade/serviço como parâmetro — query_entity, load_record, save_record cobrem centenas de endpoints de leitura/escrita.

• Tools de negócio com semântica própria, onde há regras (ex.: incluir nota, faturar pedido, baixar título) — implementadas nos servidores de domínio.

• Resources para descoberta de schema (dicionário de dados), em vez de virar tools.

Como a API Sankhya funciona (resumo)

• Auth: OAuth 2.0 Client Credentials. POST /authenticate com client_id + client_secret (form) + header X-Token, grant_type=client_credentials. Retorna um JWT usado como Authorization: Bearer. O core cacheia e renova o token automaticamente antes de expirar.

• Ambientes: Produção https://api.sankhya.com.br/ e Sandbox https://api.sandbox.sankhya.com.br/ (credenciais/tokens independentes).

• Serviços genéricos via Gateway: …/gateway/v1/{modulo}/service.sbr?serviceName={servico}&outputType=json. Principais: CRUDServiceProvider.loadRecords / loadRecord / saveRecord (upsert pela PK — a API não usa PUT) e DbExplorerSP.executeQuery.

• Módulos: mge (cadastros/dados gerais) e mgecom (movimentações comerciais). Serviços são exclusivos de cada módulo.

📌 Muitos serviços/entidades nativos do ERP não estão na doc oficial (são descobertos via DevTools). Por isso o dicionário de dados é extensível em runtime: a comunidade registra novos mapeamentos via @sankhya-mcp/data-dictionary sem alterar o core. Veja EntityRegistry.

Servidor de referência: mcp-core

Variáveis de ambiente

Veja .env.example.

Começando

Requisitos: Node ≥ 20 e pnpm 10+.

pnpm install
pnpm build      # compila todos os pacotes (Turborepo respeita as dependências)
pnpm test       # testes unitários (foco no core: auth e payloads)
pnpm lint       # ESLint

Rodar um servidor isoladamente

Cada servidor é um executável MCP via stdio. Após pnpm build:

SANKHYA_CLIENT_ID=... \
SANKHYA_CLIENT_SECRET=... \
SANKHYA_X_TOKEN=... \
SANKHYA_ENV=sandbox \
node servers/mcp-core/dist/index.js

Os servidores publicados expõem binários (sankhya-mcp-core, sankhya-mcp-vendas, …), então também podem ser iniciados via npx @sankhya-mcp/mcp-core.

Validar credenciais (preflight)

Antes da demo/PoC, confirme que as credenciais de sandbox funcionam e que há dados de exemplo. Após pnpm build:

cp .env.example .env   # preencha SANKHYA_CLIENT_ID / _SECRET / _X_TOKEN (sandbox)
pnpm validate:credentials

A ferramenta confirma que POST /authenticate retorna um JWT e que existem produtos/parceiros no ambiente. Nenhum segredo é impresso. Detalhes, opções e boas práticas de armazenamento seguro em docs/credenciais-sandbox.md.

Conectar a um cliente MCP

Exemplo para Claude Desktop (carregando apenas os domínios desejados):

{
  "mcpServers": {
    "sankhya-core": {
      "command": "npx",
      "args": ["-y", "@sankhya-mcp/mcp-core"],
      "env": {
        "SANKHYA_CLIENT_ID": "...",
        "SANKHYA_CLIENT_SECRET": "...",
        "SANKHYA_X_TOKEN": "...",
        "SANKHYA_ENV": "sandbox",
      },
    },
  },
}

Mais exemplos (incluindo Docker e uso do build local) em examples/.

Docker

docker build -f servers/mcp-core/Dockerfile -t sankhya-mcp-core .
docker run --rm -i \
  -e SANKHYA_CLIENT_ID=... -e SANKHYA_CLIENT_SECRET=... -e SANKHYA_X_TOKEN=... \
  sankhya-mcp-core

Pacote @sankhya-mcp/core (uso programático)

import { createRuntimeFromEnv } from '@sankhya-mcp/core';

const { client } = createRuntimeFromEnv();

const produtos = await client.loadRecords({
  entity: 'Produto',
  fields: ['CODPROD', 'DESCRPROD'],
  criteria: { expression: 'this.ATIVO = ?', parameters: [{ value: 'S' }] },
  offsetPage: 0,
});

Contribuindo

• Commits semânticos (feat:, fix:, docs:…).

• Testes unitários no core são prioridade (auth e montagem de payloads).

• Não invente campos/endpoints. Onde faltar detalhe, deixe um TODO apontando para a doc (https://developer.sankhya.com.br/reference/...) e registre mapeamentos no @sankhya-mcp/data-dictionary.

• Como adicionar um servidor de domínio: use servers/mcp-core como molde (tools genéricas + resources) e os stubs de domínio como ponto de partida.

Roadmap dos servidores de domínio

Os servidores de domínio são esqueletos funcionais com uma tool de exemplo cada, prontos para receber as tools de negócio (cada src/index.ts lista seu roadmap): incluir/faturar nota (vendas), baixar título (financeiro), ajustar estoque (suprimentos), admitir funcionário (RH), incluir cliente/contato (cadastros), etc.

Licença

MIT.