db-semantic-mcp Oferece um Mapa Semântico Seguro para Agentes de IA

Agentes de IA estão obtendo acesso ao banco de dados antes de entenderem os bancos de dados.

Essa é a ordem errada.

Um banco de dados de produção real raramente é autoexplicativo. A tabela importante nem sempre é chamada orders. A tabela de clientes pode ser chamada t_bd_customer. Um campo pode carregar um código de status crítico para os negócios que só faz sentido se você conhecer o sistema por trás dele. Um armazém pode dividir dados operacionais brutos, dimensões limpas e fatos agregados em esquemas com nomes como ods, dw e staging. O esquema é tecnicamente visível, mas o significado não.

Então eu construí db-semantic-mcp: um pequeno servidor MCP que fornece aos agentes de codificação de IA um mapa semântico seguro de um banco de dados.

Ele expõe nomes de tabelas, tipos de coluna, comentários, linhas de exemplo e busca de esquema alimentada por LLM. Suporta PostgreSQL e SQL Server. Funciona com clientes de agentes compatíveis com MCP, como OpenCode, Claude Code, Cursor e ferramentas semelhantes.

Ele deliberadamente não executa SQL.

Essa fronteira é o ponto.

A camada ausente entre agentes e bancos de dados

A maioria das integrações de banco de dados para agentes começa com a execução de consultas. Dê à modelo uma string de conexão, adicione uma ferramenta SQL, talvez adicione um papel somente leitura e deixe-o fazer perguntas ao banco de dados.

Isso pode ser útil. Também é um grande primeiro passo.

Antes que um agente escreva ou execute uma consulta, ele precisa responder a perguntas mais básicas:

• Quais tabelas são relevantes?
• O que esses nomes de coluna significam?
• Qual esquema contém dados de origem e qual contém dados modelados?
• Este campo é um status de negócios, uma chave estrangeira, um marcador de soft-delete ou um detalhe de implementação interna?
• Quando um usuário diz "inventário", "contas a receber", "cliente" ou "WIP", quais tabelas o agente deve inspecionar?

Essas não são perguntas de execução de SQL. Elas são perguntas de compreensão do banco de dados.

db-semantic-mcp foca nessa camada. Ele dá ao agente estrutura suficiente para navegar pelo banco de dados sem transformar o banco de dados em uma superfície de controle remoto.

O que ele expõe

O servidor fornece quatro ferramentas MCP:

As três primeiras ferramentas são operações diretas de metadados e amostragem. Elas permitem que um agente inspecione o banco de dados da maneira que um desenvolvedor faria: listar tabelas, abrir uma tabela, olhar colunas, verificar algumas linhas.

A quarta ferramenta é onde a camada semântica importa.

search_schema combina um snapshot de esquema em cache com um arquivo Markdown opcional que descreve seus termos de negócios, convenções de nomenclatura e decisões de design do banco de dados. O modelo pode então resolver solicitações em linguagem natural, como:

recebíveis de cliente
inventário WIP
pedido de vendas
应收账款

nas tabelas e colunas que provavelmente são relevantes.

Isso é especialmente útil para bancos de dados onde os nomes das tabelas são tecnicamente consistentes, mas não óbvios para um agente. Bancos de dados ERP, sistemas legados do SQL Server e grandes esquemas de armazém frequentemente se enquadram nessa categoria.

O arquivo semântico é intencionalmente chato

Não há novo formato de ontologia para aprender. Não há banco de dados vetorial para implantar. Não há serviço de catálogo separado.

Você escreve um arquivo Markdown.

Por exemplo:

# Contexto Semântico do Banco de Dados

## Convenções de Nomenclatura

- `ods.*` tabelas contêm dados operacionais brutos.
- `dw.*` tabelas contêm tabelas de fatos e dimensões modeladas.
- `staging.*` tabelas são tabelas temporárias de ETL.

## Termos de Negócio

| Termo de negócio | Tabela(s) |
| --- | --- |
| Cliente | ods.bd_customer, dw.dim_customer |
| Inventário | dw.fact_inventory_snapshot |
| WIP / trabalho em progresso | dw.fact_wip_by_lot |

## Decisões de Design

- Valores monetários são armazenados em centavos inteiros.
- `_modified_at` colunas são marcas de sincronização incrementais.
- Soft deletes usam `doc_status = 'D'`.

Esse arquivo é carregado no prompt de busca de esquema. Ele é a ponte entre a estrutura física do banco de dados e o vocabulário que desenvolvedores ou usuários de negócios realmente usam.

A escolha de design importante é que a camada semântica permanece próxima à equipe. Ela pode viver ao lado do projeto. Pode ser revisada como documentação. Pode ser alterada sem reindexar um armazenamento vetorial ou migrar um sistema de metadados.

Por que não executar SQL?

Porque o primeiro primitivo seguro que um agente precisa não é sempre uma ferramenta de consulta.

Se um agente pode executar SQL arbitrário, mesmo SQL somente leitura, o problema de segurança se torna maior imediatamente. Você precisa pensar sobre permissões, acesso a nível de linha, custo de consulta, exfiltração de dados, logs de auditoria e injeção de prompt através de dados. Esses problemas são solucionáveis, mas não são gratuitos.

db-semantic-mcp adota uma posição mais restrita: dar ao agente visibilidade sobre a estrutura e o significado primeiro.

Isso torna a ferramenta útil em ambientes mais conservadores. Uma equipe pode se sentir confortável em expor metadados de tabela, comentários e algumas linhas de exemplo a um agente muito antes de se sentir confortável em dar ao agente uma superfície geral de execução de SQL. O servidor ainda se conecta ao banco de dados, então deve ser configurado com cuidado, mas seu limite de produto é intencionalmente menor.

O resultado não é uma plataforma de texto-para-SQL. É a camada antes do texto-para-SQL. Ajuda o agente a entender onde ele está.

Construído para bancos de dados reais, não esquemas de demonstração

A primeira implementação suportou PostgreSQL. A versão atual também suporta SQL Server através da mesma interface MCP.

O backend é selecionado a partir do esquema DATABASE_URL:

postgresql://user:pass@localhost:5432/mydb
sqlserver://user:pass@host:1433?database=mydb&encrypt=disable

Isso importa porque muitos dados valiosos de negócios não estão sentados em um banco de dados de aplicativo Postgres organizado. Eles estão no SQL Server. Eles estão em sistemas ERP. Eles estão em bancos de dados com milhares de tabelas, comentários inconsistentes, convenções de nomenclatura históricas e esquemas que apenas algumas pessoas dentro da empresa entendem.

Para esses bancos de dados, db-semantic-mcp inclui controles de cache, como filtros de esquema e filtros de prefixo de tabela. Se um banco de dados SQL Server contém milhares de tabelas, mas as tabelas de negócios úteis compartilham prefixos como t_pur_, t_sal_, t_stk_ ou t_bd_, o cache de esquema pode se concentrar nessas áreas.

Isso não é sobre tornar um banco de dados de brinquedo mais fácil de consultar. É sobre tornar bancos de dados reais bagunçados navegáveis por um agente sem fingir que eles são simples.