Sankhya Schema MCP

Servidor MCP (Model Context Protocol) que conecta o Claude Code e/ou o Codex CLI ao banco do Sankhya ERP, permitindo explorar tabelas, campos, índices, relacionamentos e executar queries SQL diretamente durante uma conversa.

Suporta os dois bancos distribuídos pela Sankhya no ambiente de desenvolvimento:

A escolha é feita por SANKHYA_DB_TYPE no .env — veja Configuração do banco.

---

Funcionalidades

Por que describe_table traz os valores dos campos

O comentário de coluna do catálogo vem vazio na base Sankhya (0 de 69.782 colunas medidas). A semântica mora no dicionário da aplicação, e é de lá que a tool tira a descrição (TDDCAM) e o domínio dos campos enumerados (TDDOPC):

| campo  | tipo        | nulo | descricao         | opcoes                                    |
| TIPMOV | VARCHAR2(1) | S    | Tipo de Movimento | P=Pedido de venda; V=Venda; C=Compra; ... |

Sem isso, quem escreve a query precisa adivinhar o literal do WHERE. Em TGFCAB.TIPMOV, V (Venda) e P (Pedido de venda) são ambos válidos — trocar um pelo outro devolve o documento errado sem levantar nenhum erro de SQL. E o mesmo nome de campo tem domínio diferente em tabelas diferentes: TIPMOV existe em 17 tabelas, com de 2 a 24 opções cada.

Por isso a saída não é resumida nem truncada: assertividade da resposta vem antes de economia de tokens.

O search_tables e o search_columns bebem da mesma fonte, para a etapa de descoberta não depender de adivinhação de nome:

search_tables("TGFCAB")            search_columns("CODPARC", "TGF")
| tabela    | linhas | descricao |            | tabela  | campo   | ... | descricao     |
| TGFCAB    | 95     | Entrada e Saída de …|  | TGFAAXN | CODPARC | ... | Parceiro      |
| TGFCABLIG | 0      | Auto relacionamentos …| | TGFACO | CODPARC | ... | Cód. Parceiro |

Tabela fora do dicionário (backup, temporária — 31% do catálogo) continua aparecendo, apenas sem verbete.

A lista de opções não esgota o dado gravado

O dicionário declara o que a aplicação oferece, não o que está gravado. Na base medida, TGFCAB.TIPMOV tem Z em 23 das 139 linhas sem constar em TDDOPC.

Na prática:

• Filtro por igualdade (WHERE TIPMOV = 'P'): use a lista de opcoes. É para isso que ela existe.
• Filtro exaustivo (IN, NOT IN) ou agrupamento por esse campo: confirme antes com table_sample ou um SELECT campo, COUNT(*) … GROUP BY. Montar IN (...) só com a lista declarada perde linha em silêncio.

Por isso o table_sample deixa sem rótulo o valor que não está no dicionário — é assim que ele se denuncia, em vez de passar por código válido.

---

Pré-requisitos

Windows adicional: PowerShell 7+ (pwsh) — Instalar aqui

Linux adicional (somente para Oracle):

sudo apt-get install -y curl unzip libaio1
# Ubuntu 24+: substituir libaio1 por libaio1t64

Para SQL Server, instale o driver à parte — ele fica fora do requirements.txt porque quem usa só Oracle não precisa dele, e a wheel do pymssql não existe para toda combinação de plataforma e versão de Python:

pip install -r requirements-sqlserver.txt

Não há dependência de sistema operacional: o pymssql traz o FreeTDS na própria wheel, ao contrário do pyodbc, que exigiria o msodbcsql.

---

Instalação rápida

Windows

git clone https://github.com/frshaka/sankhya-schema-mcp.git
cd sankhya-schema-mcp
pwsh -File setup.ps1

Linux

git clone https://github.com/frshaka/sankhya-schema-mcp.git
cd sankhya-schema-mcp
bash setup.sh

O script de setup executa automaticamente:

1. Menu de seleção dos CLIs onde registrar o MCP (Claude Code, Codex CLI ou ambos — default: Claude Code)
2. Download e extração do Oracle Instant Client 21c (do GitHub Releases — necessário só para Oracle)
3. Criação do ambiente virtual Python (.venv/)
4. Instalação das dependências (mcp, oracledb, python-dotenv)
5. Registro do servidor MCP nos CLIs escolhidos (Claude Code: ~/.claude.json / Codex: ~/.codex/config.toml)

Para pular o menu (automação), use a flag de CLI:

# Windows
pwsh -File setup.ps1 -Cli both     # claude | codex | both

# Linux
bash setup.sh --cli both           # claude | codex | both

Após o setup, configure as credenciais do banco no arquivo .env e reinicie o CLI escolhido.

Veja INSTALACAO.md para o guia completo passo a passo, configuração de credenciais e solução de problemas.

---

Configuração do banco

Copie o arquivo de exemplo e edite com suas credenciais:

cp .env.example .env

Escolhendo o banco

Duas chaves definem o destino:

O default é oracle de propósito: uma instalação existente continua funcionando sem tocar no .env. Valor desconhecido em SANKHYA_DB_TYPE faz o servidor falhar na subida, em vez de conectar no banco errado.

Oracle (.env):

SANKHYA_DB_TYPE=oracle
SANKHYA_DB_HOST=localhost
SANKHYA_DB_PORT=1521
# Conexão por SID (padrão). Para conectar por service name, use SANKHYA_DB_SERVICE_NAME (tem precedência).
SANKHYA_DB_SERVICE=XE
# SANKHYA_DB_SERVICE_NAME=ORCLPDB1
SANKHYA_DB_USER=SANKHYA
SANKHYA_DB_PASSWORD=developer

SQL Server (.env):

SANKHYA_DB_TYPE=sqlserver
SANKHYA_DB_HOST=localhost
SANKHYA_DB_PORT=1433
SANKHYA_DB_DATABASE=jiva
SANKHYA_DB_USER=SANKHYA
SANKHYA_DB_PASSWORD=developer

O arquivo .env está no .gitignore e nunca será versionado.

Configuração por projeto (override)

O .env acima é a configuração geral (usada por padrão em qualquer projeto). Para apontar o MCP a um banco diferente em um projeto específico, crie um arquivo .sankhya-mcp.env na raiz desse projeto (o diretório onde você abre o Claude Code).

Na inicialização, o MCP carrega primeiro o .env geral e, em seguida, o .sankhya-mcp.env do projeto — as variáveis do projeto sobrescrevem as do geral. Inclua apenas o que difere; o restante é herdado.

Isso vale também para o tipo de banco: dá para manter o .env geral no Oracle e apontar um projeto específico para o SQL Server — ou o contrário — sem mexer na configuração dos outros.

Exemplo de .sankhya-mcp.env em um projeto que conecta por service name:

SANKHYA_DB_HOST=10.100.56.7
SANKHYA_DB_SERVICE_NAME=MEUBANCO.EXEMPLO.COM.BR
SANKHYA_DB_USER=USUARIO_PROJETO
SANKHYA_DB_PASSWORD=senha_do_projeto

Exemplo de um projeto que roda contra o SQL Server, herdando o resto do .env geral:

SANKHYA_DB_TYPE=sqlserver
SANKHYA_DB_PORT=1433
SANKHYA_DB_DATABASE=jiva

Atenção: o .sankhya-mcp.env contém credenciais. Adicione-o ao .gitignore do projeto.

---

Verificação

Claude Code — reinicie e execute:

/mcp

O servidor sankhya-schema deve aparecer com status connected.

Codex CLI — reinicie e execute no terminal:

codex mcp list

O servidor sankhya-schema deve aparecer na lista. Na primeira chamada de tool, aprove quando solicitado (ou ajuste a approval_policy no ~/.codex/config.toml).

---

Exemplos de uso no chat

Descreva a tabela TGFCAB

Quais tabelas do Sankhya têm o campo CODPARC?

Mostre os índices de TGFDIN

Valide esta query:
SELECT CAB.NUNOTA, CAB.CODPARC, DIN.DTVENC
FROM TGFCAB CAB
JOIN TGFDIN DIN ON DIN.NUNOTA = CAB.NUNOTA
WHERE CAB.CODTIPOPER = 1

Liste os módulos disponíveis no schema

Busque a entidade "Parceiro"

---

Segurança

• Apenas SELECT é permitido — comandos DML/DDL (INSERT, UPDATE, DELETE, DROP etc.) são bloqueados por uma allowlist textual na aplicação
• A validação é textual e não cobre tudo: uma função que já existe no schema com PRAGMA AUTONOMOUS_TRANSACTION, chamada em SELECT pacote.funcao(x) FROM DUAL, grava mesmo assim
• A conexão é local — nenhum dado sai da máquina
• Credenciais ficam no .env local, fora do controle de versão
• SELECT ... INTO é rejeitado pela allowlist. No Oracle não é sintaxe válida em SQL puro; no SQL Server criaria tabela — escrita disfarçada de leitura, e lá não existe READ ONLY de sessão para recusá-la
• Como o usuário recomendado é somente-leitura e normalmente não é o dono das tabelas, defina SANKHYA_DB_SCHEMA com o schema onde elas moram (ver abaixo) — sem isso, parte das tools responde “objeto não existe”

---

Schema das tabelas (SANKHYA_DB_SCHEMA)

Nome de tabela sem qualificação é resolvido no schema do usuário conectado — vale para os dois bancos. Quando o login do MCP não é o dono das tabelas, o caso normal ao seguir a recomendação de usar um usuário somente-leitura, três tools param de funcionar:

⚠️ Sem o dicionário acessível, describe_table deixa de mostrar os domínios (TIPMOV = P-Pedido de venda; V-Venda; …) e quem escreve a query volta a ter que adivinhar o literal do WHERE. Configurar SANKHYA_DB_SCHEMA não é cosmético.

As demais tools leem as views de catálogo (ALL_TAB_COLUMNS/INFORMATION_SCHEMA.COLUMNS, ALL_TABLES/INFORMATION_SCHEMA.TABLES, …), que listam tudo que o usuário consegue ver independente do schema corrente, e não são afetadas.

A correção é informar o schema:

# .env (pasta do MCP) — padrão de todos os projetos
SANKHYA_DB_SCHEMA=SANKHYA

Com a variável definida, o MCP qualifica as quatro referências não qualificadas que existem — a amostra do table_sample e as três consultas ao TDDINS — passando a escrever SANKHYA.TGFCAB e SANKHYA.TDDINS. Ausente, os nomes saem crus e o comportamento é o anterior.

No Oracle, além disso, cada conexão recebe um ALTER SESSION SET CURRENT_SCHEMA. Isso não é necessário para as queries acima, que já vão qualificadas — serve ao run_query, cujo SQL é escrito por quem chama: com a sessão apontada, FROM TGFCAB funciona sem qualificar à mão.

No SQL Server não há equivalente de sessão: o schema padrão vem do mapeamento do login (ALTER USER ... WITH DEFAULT_SCHEMA), é persistente e exige privilégio, então não é papel deste servidor mexer nisso. Lá vale só o qualificador — e no run_query o nome precisa ser qualificado à mão (FROM SANKHYA.TGFCAB).

Para um projeto que precisa de outro schema, sobrescreva apenas ali com o .sankhya-mcp.env (ver INSTALACAO.md):

# .sankhya-mcp.env na raiz do projeto
SANKHYA_DB_SCHEMA=TESTE

Para uma consulta pontual em outro schema, qualifique no run_query: SELECT ... FROM TREINA.TGFCAB.

A segunda camada de proteção é mais fraca no SQL Server

Além da validação da aplicação, cada consulta roda dentro de uma transação de leitura. O que essa transação garante não é igual nos dois bancos — e a diferença é real, não uma formalidade:

Não existe no SQL Server um equivalente ao SET TRANSACTION READ ONLY do Oracle. BEGIN TRANSACTION com rollback garantido é o mais próximo disponível, mas é uma proteção de natureza diferente: ela desfaz, não impede. Verificado nesta base de desenvolvimento — dentro dessa transação o SQL Server aceitou SELECT ... INTO, UPDATE e INSERT sem reclamar; só o rollback da aplicação desfez.

Na prática isso significa que, no SQL Server:

• uma escrita chega a rodar no servidor antes de ser desfeita — com todos os efeitos colaterais que isso implica (triggers disparam, sequências e IDENTITY avançam, locks são tomados);
• se o processo do MCP morrer entre a escrita e o rollback, o SQL Server desfaz a transação ao derrubar a conexão — mas isso depende do servidor perceber a queda, não de a escrita ter sido barrada;
• a defesa que de fato impede a escrita é o privilégio do login.

Recomendação para SQL Server: conecte o MCP com um login mapeado apenas em db_datareader no database do Sankhya. É a única camada que impede a escrita em vez de desfazê-la, e é o que torna a proteção comparável à do Oracle. No Oracle a mesma recomendação vale (um usuário sem privilégio de escrita cobre o caso da função com AUTONOMOUS_TRANSACTION), mas lá o READ ONLY já cobre o caso comum sozinho.

---

Equivalências de catálogo entre os bancos

As tools respondem a mesma coisa nos dois bancos, lendo catálogos diferentes:

Notas:

• O dicionário Sankhya (TDDINS, TDDCAM, TDDOPC, TDDLIG) é da aplicação, não do catálogo: as queries que o usam (describe_table, get_foreign_keys, search_entities, resolução de EntityName) são idênticas nos dois bancos — só o placeholder de bind muda (:1 no Oracle, %s no pymssql).
• As opções de campo não são agregadas em SQL: LISTAGG (Oracle) e STRING_AGG (SQL Server) divergem, então a junção campo↔domínio acontece em Python, como já era feito no list_modules. Um caminho de código só para os dois bancos.
• TDDOPC.ORDEM é nula na maioria das linhas e os bancos discordam sobre onde o nulo entra na ordenação (Oracle joga para o fim, SQL Server para o começo). A query força a mesma ordem nos dois com um CASE.
• Comentários de coluna vêm vazios nos dois bancos nas bases distribuídas pela Sankhya (0 de 69.782 colunas no Oracle; nenhuma MS_Description no SQL Server). É por isso que a descrição exibida vem do dicionário, com o comentário do catálogo apenas como reserva.
• NULLABLE sai como Y/N no Oracle e YES/NO no SQL Server; a saída normaliza para S/N nos dois. Tipo, tamanho, precisão e escala são colapsados numa célula só (NUMBER(15,2), varchar(max)), o que também esconde a diferença entre DATA_LENGTH e CHARACTER_MAXIMUM_LENGTH.
• list_modules agrupa pelo prefixo de 3 caracteres (TGFCAB, TGFITE e TGFPAR contam para TGF), que é a convenção de nomenclatura do Sankhya; tabelas customizadas caem em AD_. Prefixo com uma tabela só fica de fora.
• O schema é tratado como dado nos dois bancos, nunca fixado na query: na base jiva distribuída pela Sankhya as tabelas ficam em SANKHYA (não em dbo). Quando a mesma tabela aparece em mais de um schema, o describe_table escolhe o do usuário conectado e avisa onde mais ela existe.

---

Estrutura do projeto

sankhya-schema-mcp/
├── src/
│   ├── server.py          # Servidor MCP: tools, formatação e validação
│   ├── dialects.py        # Queries, conexão e transação por banco (Oracle/SQL Server)
│   ├── updates.py         # Consulta de versão publicada e aviso de atualização
│   └── version.py         # Versão do projeto (fonte única)
├── tools/
│   ├── release.sh         # Validador de publicação (Linux/macOS)
│   └── release.ps1        # Validador de publicação (Windows)
├── instantclient/         # Oracle Instant Client (baixado pelo setup)
├── .venv/                 # Ambiente virtual Python (criado pelo setup)
├── .env                   # Credenciais do banco (não versionado)
├── .env.example           # Modelo de credenciais
├── start.ps1              # Script de inicialização (Windows)
├── start.sh               # Script de inicialização (Linux)
├── setup.ps1              # Instalador automático (Windows)
├── setup.sh               # Instalador automático (Linux)
├── update.ps1             # Atualização: código + dependências (Windows)
├── update.sh              # Atualização: código + dependências (Linux)
├── contrato_mcp.json      # O que o cliente MCP recebe, congelado para o teste
├── requirements.txt       # Dependências Python (Oracle, padrão)
├── requirements-sqlserver.txt  # Driver do SQL Server (opcional)
├── test_server.py         # Autoteste das funções puras (não requer banco)
├── CHANGELOG.md           # Histórico de versões
└── INSTALACAO.md          # Guia detalhado de instalação

---

Versões e atualização

A versão instalada fica em src/version.py e o histórico em CHANGELOG.md. Cada release é publicada como tag vX.Y.Z.

Como saber que saiu versão nova

O servidor consulta as tags publicadas no boot e, havendo versão maior, avisa você na primeira resposta da conversa. A consulta tem cache de 24h e timeout de 2s; sem rede, sem git ou sem acesso ao repositório, o servidor sobe normalmente e apenas não avisa.

Para consultar na hora, com o detalhe do que mudou:

check_updates

Como atualizar

O script baixa a versão publicada e reinstala as dependências (inclusive o driver do SQL Server, se estiver instalado):

# Windows
pwsh -NoProfile -File \update.ps1

# Linux/macOS
/update.sh

Pode rodar com o cliente MCP aberto; depois reinicie o cliente. Também dá para pedir ao assistente: o check_updates mostra o comando.

Quem atualizar só com git pull continua funcionando: o servidor detecta as dependências antigas, segue com elas e pede ao assistente que ofereça rodar o script.

Publicando uma versão (mantenedor)

Toda release publica release notes. É padrão do projeto, e o processo recusa publicar sem elas.

1. Escreva a seção da nova versão no CHANGELOG.md, no topo, descrevendo o que mudou.
2. Atualize __version__ em src/version.py com a mesma versão.
3. Rode o validador:

# Linux/macOS
tools/release.sh            # valida e cria a tag localmente
tools/release.sh --push     # valida, cria e publica

# Windows
pwsh tools/release.ps1
pwsh tools/release.ps1 -Push

O script recusa publicar quando:

Publicar exige o passo explícito (--push/-Push): uma tag no origin é irreversível na prática, porque outro clone pode já tê-la buscado.

Como as release notes são geradas

O push de uma tag v* dispara .github/workflows/release.yml, que extrai a seção correspondente do CHANGELOG e publica o release no GitHub com ela como corpo. O gatilho é a tag, não o script: uma tag empurrada à mão (git push origin v1.3.0) também gera as notas.

O CHANGELOG é a fonte única — o mesmo texto alimenta o release no GitHub e a tool check_updates. Se a seção estiver ausente ou vazia, o workflow falha em vez de publicar um release sem explicação.

# Ver as notas de uma versão sem publicar nada
python tools/release_notes.py 1.2.1

---

Ambiente de Desenvolvimento Local

Banco de Dados com Docker

A Sankhya distribui as duas imagens em developer.sankhya.com.br. Escolha uma e aponte o SANKHYA_DB_TYPE para ela.

Oracle — skdev-oracle

Criando o volume de dados

Antes de iniciar o container, crie um volume para garantir a persistência dos dados:

docker volume create skdev-oracle-volume

Iniciando o container

docker run -d --name skdev-oracle --shm-size=1g -p 1521:1521 -p 5500:5500 -v skdev-oracle-volume:/opt/oracle/oradata sankhyaimages/skdev-oracle:1.1.0

⚠️ A primeira inicialização pode levar de 20 a 30 minutos. Acompanhe o progresso com: docker logs -f skdev-oracle.

Credenciais de conexão

Use estas credenciais para conectar ao banco a partir do WPM ou de um cliente de banco de dados:

Parar e reiniciar o container

docker stop skdev-oracle    # parar
docker start skdev-oracle   # reiniciar

SQL Server — skdev-mssql

Criando o volume de dados

Antes de iniciar o container, crie um volume para garantir a persistência dos dados:

docker volume create skdev-mssql-volume

Iniciando o container

docker run -d --name skdev-mssql -p 1433:1433 -v skdev-mssql-volume:/var/opt/mssql sankhyaimages/skdev-mssql:1.1.0

⚠️ A primeira inicialização também leva de 20 a 30 minutos. Acompanhe com: docker logs -f skdev-mssql. O container está pronto quando o log mostra SQL Server is now ready for client connections.

Credenciais de conexão

Configuração correspondente no .env:

SANKHYA_DB_TYPE=sqlserver
SANKHYA_DB_PORT=1433
SANKHYA_DB_DATABASE=jiva

Parar e reiniciar o container

docker stop skdev-mssql    # parar
docker start skdev-mssql   # reiniciar

---

Servidor de Aplicação (WildFly)

Faça o download do WildFly 23.0 e extraia em um local de fácil acesso (ex: C:\wildfly ou /home/user/wildfly).

Inicie o servidor a partir da pasta bin do WildFly:

• Windows:

.\standalone.bat

• Linux:

./standalone.sh

Para manuais detalhados de instalação:

• Manual de Instalação em Linux
• Manual de Instalação em Windows

---

Configuração do WPM e Sankhya OM

1. Acesse o WPM no navegador: http://localhost:8080/wpm/
2. A senha padrão no primeiro acesso é admin — você será solicitado a alterá-la.
3. Na tela de configuração, insira os dados de conexão do banco configurado no Docker.
4. Após a conexão, o WPM permitirá que você baixe e instale a versão desejada do Sankhya OM. Escolha sempre a versão mais recente disponível.
5. Siga o processo de instalação. Ao final, seu ambiente estará pronto.

---

Licença

Uso interno para parceiros e desenvolvedores Sankhya.