CoreMCP

CoreMCP

Um servidor Model Context Protocol (MCP), escrito em Go, que expõe bancos de dados SQL como ferramentas e prompts MCP. Ele roda como um único binário estático, incorpora seus drivers e fala via stdio (para clientes MCP locais como Claude Desktop) ou um WebSocket de saída (para operação remota atrás de NAT).

Atualmente acompanha adaptadores MSSQL (SQL Server 2000+, ciente de collation Turkish_CI_AS) e PostgreSQL. Firebird está em andamento; MySQL está no roadmap.

Status

• Estável: adaptador MSSQL, adaptador PostgreSQL, transporte stdio, descoberta de esquema, ferramentas personalizadas, middleware de normalização NOLOCK / turco, modo de conexão WebSocket.
• Em andamento: adaptador Firebird (a factory atualmente retorna um erro de placeholder).
• Roadmap: MySQL, transporte HTTP, log de auditoria, cache de resultados de consulta.

Padrões

O CoreMCP é somente leitura por padrão. Omitir readonly em uma configuração de fonte deixa o modo somente SELECT ativo; você precisa definir readonly: false para habilitar execute_procedure. Mesmo assim, a postura recomendada é um usuário de banco dedicado com SELECT (e EXECUTE apenas nos procedimentos que você pretende expor) — defesa em profundidade em vez de confiar apenas na proteção do lado do servidor.

Instalação

Binário

Baixe da página de Releases — linux/amd64, linux/arm64, darwin/{amd64,arm64}, windows/amd64.

Instalador de uma linha (Linux/macOS):

curl -fsSL https://get.corebasehq.com | sh

Docker

docker pull y11t0/coremcp:latest

Imagem multi-arquitetura (linux/amd64, linux/arm64).

A partir do código-fonte

Requer Go 1.23+.

git clone https://github.com/corebasehq/coremcp.git
cd coremcp
go build -o coremcp ./cmd/coremcp

Configuração

coremcp.yaml no diretório de trabalho:

server:
  name: "coremcp-agent"
  version: "0.1.0"
  transport: "stdio"
  port: 8080

logging:
  level: "info"
  format: "json"

sources:
  - name: "my_database"
    type: "mssql"
    dsn: "sqlserver://username:password@localhost:1433?database=mydb&encrypt=disable"
    readonly: true
    no_lock: true            # READ UNCOMMITTED isolation (WITH (NOLOCK) equivalent)
    normalize_turkish: true  # Turkish character + mojibake normalization

Veja coremcp.example.yaml para um exemplo mais completo.

Formato DSN

MSSQL:

sqlserver://username:password@host:port?database=dbname&encrypt=disable

PostgreSQL:

postgresql://username:password@host:port/dbname?sslmode=disable

Adaptador dummy (para testes sem um banco real):

dummy://test

Opções de fonte

Opção	Tipo	Padrão	Descrição
name	string	—	Identificador único da fonte
type	string	—	Tipo de adaptador: mssql, postgres (ou postgresql), rest, graphql, dummy
dsn	string	—	String de conexão
readonly	bool	true	Somente SELECT no nível de configuração. Defina false explicitamente para permitir execute_procedure.
no_lock	bool	false	(Somente MSSQL) Executa SELECTs sob READ UNCOMMITTED. Equivalente a WITH (NOLOCK) em cada referência de tabela. Elimina a aquisição de bloqueio compartilhado em OLTP ocupado. Trade-off: leituras sujas possíveis.
normalize_turkish	bool	false	(Somente MSSQL) Middleware bidirecional. Saída: caracteres turcos dentro de literais de string SQL são convertidos para maiúsculas ASCII antes do envio da consulta ('Hüseyin' → 'HUSEYIN'). Entrada: mojibake Windows-1254 / Windows-1252 em strings de resultado é corrigido automaticamente. Destinado a bancos de dados ERP turcos legados em Turkish_CI_AS.

Exemplo: MSSQL com NOLOCK

sources:
  - name: "oltp_db"
    type: "mssql"
    dsn: "sqlserver://user:pass@localhost:1433?database=production&encrypt=disable"
    readonly: true
    no_lock: true

Exemplo: ERP turco legado

sources:
  - name: "erp_db"
    type: "mssql"
    dsn: "sqlserver://user:pass@localhost:1433?database=LOGO&encrypt=disable"
    readonly: true
    no_lock: true
    normalize_turkish: true

Como o middleware turco se comporta:

Model emite	Enviado ao DB	Porquê
WHERE ADI = 'Hüseyin'	WHERE ADI = 'HUSEYIN'	O ERP armazena nomes em ASCII maiúsculo
WHERE SEHIR LIKE '%şeker%'	WHERE SEHIR LIKE '%SEKER%'	Ş → S
WHERE SEHIR = 'İstanbul'	WHERE SEHIR = 'ISTANBUL'	İ → I

Correção de mojibake em linhas recebidas:

DB retorna	Corrigido	Causa
GÐKHAN	GĞKHAN	Byte Win-1254 0xD0 lido como Win-1252
ÝSTANBUL	İSTANBUL	Byte Win-1254 0xDD lido como Win-1252
ÞEHİR	ŞEHİR	Byte Win-1254 0xDE lido como Win-1252

Configuração de segurança

security:
  max_row_limit: 1000        # forced LIMIT cap
  enable_pii_masking: true
  pii_patterns:
    - name: "credit_card"
      pattern: '\b\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}\b'
      replacement: "****-****-****-****"
      enabled: true
    - name: "email"
      pattern: '\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b'
      replacement: "***@***.***"
      enabled: true
    - name: "turkish_id"
      pattern: '\b[1-9]\d{10}\b'
      replacement: "***********"
      enabled: true

O que isso habilita:

• Lexer ciente de T-SQL. Tokenizador personalizado fail-closed remove comentários e literais de string, depois classifica a declaração — apenas SELECT e WITH passam. DROP, ALTER, UPDATE, DELETE, TRUNCATE, EXEC, OPENROWSET, SELECT…INTO e similares são rejeitados antes de chegar ao banco. Payloads com múltiplas declarações (qualquer ; fora de strings/comentários) são fatais — ataques de consulta empilhada bloqueados independentemente do dialeto. Escolhido em vez de parsers SQL Go de terceiros (xwb1989/sqlparser, vitess, cockroachdb) porque eles falham fechados em dicas T-SQL e qualquer relaxamento "fall through to regex" é contornável via EX/**/EC e truques similares. Trate como uma camada, não a única — combine com um papel de banco com privilégios mínimos.
• Limite forçado de linhas. LIMIT é anexado (ou envolvido) em cada SELECT para que um modelo nunca transmita milhões de linhas de volta pelo protocolo.
• Mascaramento de PII. Pós-processamento baseado em regex nas strings de resultado antes de chegarem ao cliente.

Uso

O CoreMCP tem dois modos de operação.

1. Local (serve)

Para clientes MCP locais (Claude Desktop, etc.):

coremcp serve --config coremcp.yaml

stdio é o transporte padrão:

coremcp serve -t stdio

Configuração do Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "coremcp": {
      "command": "/path/to/coremcp",
      "args": ["serve", "-c", "/path/to/coremcp.yaml"],
      "env": {}
    }
  }
}

2. Remoto (connect)

connect abre um WebSocket de saída para um relay (tipicamente CoreBase Cloud) e serve tráfego MCP por ele. O agente nunca aceita conexões de entrada, então funciona em redes que não permitem 443 de entrada (chão de fábrica, VPCs corporativas, redes hospitalares).

coremcp connect --server="wss://api.corebasehq.com/ws/agent" --token="sk_xxx"

Flags:

-s, --server string              Relay WebSocket URL (required)
-t, --token string               Authentication token (required)
-a, --agent-id string            Agent ID (auto-generated if omitted)
-r, --max-reconnect int          Max reconnect attempts (default 10; 0 = infinite)
-d, --reconnect-delay duration   Delay between reconnect attempts (default 5s)

Exemplo, de longa duração:

./coremcp connect \
  --server="wss://api.corebasehq.com/ws/agent" \
  --token="sk_xxx" \
  --agent-id="site-istanbul-001" \
  --max-reconnect=0

Comandos de wire suportados pelo protocolo relay:

• run_sql — executar SQL
• get_schema — despejar esquema em cache
• list_sources — enumerar fontes configuradas
• health_check — liveness do agente
• config_sync — enviar configurações de fonte atualizadas para o agente em execução

Arquitetura

coremcp/
├── cmd/coremcp/       # CLI entry point
│   ├── main.go
│   ├── root.go
│   ├── serve.go       # stdio mode
│   └── connect.go     # WebSocket mode
├── pkg/
│   ├── adapter/       # Database adapters
│   │   ├── factory.go
│   │   ├── dummy/
│   │   └── mssql/
│   ├── config/
│   ├── core/          # Shared types, Source interface
│   ├── security/      # Query validation, PII masking
│   └── server/        # MCP server
└── coremcp.yaml

Ferramentas e prompts

Ferramentas integradas

query_database

SQL arbitrário contra uma fonte configurada.

• source_name (obrigatório)
• query (obrigatório)

list_tables

Tabelas com contagens de colunas, chaves primárias, contagens de chaves estrangeiras.

• source_name (obrigatório)

describe_table

Esquema completo para uma tabela: colunas, tipos, nulabilidade, PKs, FKs, comentários de coluna.

• source_name (obrigatório)
• table_name (obrigatório)

list_views

Todas as views com definições de coluna.

• source_name (obrigatório)

list_procedures

Procedimentos armazenados com nomes de parâmetros, tipos, modos (IN/OUT/INOUT) e um exemplo de chamada pronto para copiar.

• source_name (obrigatório)

execute_procedure

Chama um procedimento armazenado com parâmetros nomeados. Somente habilitado quando readonly: false.

• source_name (obrigatório)
• procedure_name (obrigatório)
• params (opcional) — objeto JSON de pares nome/valor

Hardening:

• Nome do procedimento validado contra ^[a-zA-Z_][a-zA-Z0-9_#@.]*$
• Nomes de parâmetros validados (alfanumérico + sublinhado)
• Valores vinculados via sql.Named — sem interpolação de string
• Rejeitado imediatamente quando a fonte é readonly: true

Exemplo:

{
  "source_name": "erp_db",
  "procedure_name": "sp_CiroHesapla",
  "params": "{\"StartDate\":\"2024-01-01\",\"EndDate\":\"2024-12-31\"}"
}

Ferramentas personalizadas

Defina consultas parametrizadas reutilizáveis como ferramentas MCP de primeira classe:

custom_tools:
  - name: "get_daily_sales"
    description: "Daily sales summary for a given date"
    source: "production_db"
    query: "SELECT * FROM orders WHERE DATE(created_at) = '{{date}}'"
    parameters:
      - name: "date"
        description: "Date in YYYY-MM-DD format"
        required: true

  - name: "get_top_customers"
    description: "Top N customers by order count"
    source: "production_db"
    query: "SELECT user_id, COUNT(*) AS order_count FROM orders GROUP BY user_id ORDER BY order_count DESC LIMIT {{limit}}"
    parameters:
      - name: "limit"
        description: "Number of customers to return"
        required: true
        default: "10"

Elas são expostas ao modelo com seu esquema de parâmetros declarado, para que o modelo possa chamá-las diretamente em vez de redescobrir o SQL a cada turno.

Prompt database_schema

Na inicialização, o CoreMCP conecta-se a cada fonte configurada, examina tabelas / colunas / chaves / relacionamentos e extrai comentários de coluna (ex.: MS_Description no MSSQL). O resultado é exposto como um único prompt MCP que prepara o modelo com contexto de esquema — incluindo os comentários — para que ele possa escrever consultas corretas sem despejos manuais de esquema em cada conversa.

Adicionando adaptadores

1. Crie pkg/adapter/yourdb/.
2. Implemente core.Source.
3. Registre em pkg/adapter/factory.go.

pkg/adapter/dummy/dummy.go é a implementação de referência mínima.

Roadmap

• Descoberta de esquema na inicialização
• Comentários / descrições de coluna
• Ferramentas integradas list_tables / describe_table
• Ferramentas parametrizadas personalizadas
• Lexer ciente de T-SQL para sanitização de consultas (fail-closed, rejeição de múltiplas declarações, sem parser de terceiros)
• Mascaramento de PII
• Limite forçado de linhas
• Modo WebSocket connect
• Reconexão automática
• Sincronização remota de configuração
• NOLOCK / READ UNCOMMITTED por fonte (MSSQL)
• Middleware de caracteres turcos + mojibake (MSSQL)
• Descoberta de views e procedimentos (list_views, list_procedures, execute_procedure)
• Adaptador PostgreSQL
• Adaptador Firebird (em andamento)
• Adaptador MySQL
• Transporte HTTP
• Cache de resultados de consulta
• Operações de escrita (com proteções explícitas de segurança)
• Log de auditoria
• Gerenciamento multi-agente
• Monitoramento em tempo real

Contribuindo

Veja CONTRIBUTING.md. Relatórios de segurança: SECURITY.md.

Licença

Apache License 2.0 — veja LICENSE.

Suporte

• Relatar um bug
• Solicitar um recurso
• Email: support@corebasehq.com

---

Sobre

O CoreMCP é o componente de gateway open-source e on-premise do CoreBase, uma plataforma de agentes de IA para os dados da sua empresa. Converse diretamente com seus bancos de dados e APIs, ou deixe agentes autônomos e acionados por eventos executarem automações de múltiplas etapas neles — bancos de dados (SQL Server 2000+, PostgreSQL), APIs REST e GraphQL, e mais de 50 conectores SaaS.

O CoreMCP é como esses agentes alcançam os sistemas atrás do seu firewall, incluindo os legados e on-premise que nada mais conecta: ele roda no seu próprio servidor, mantém as credenciais do banco localmente e conecta-se com zero-trust — apenas porta 443 de saída, sem portas de entrada. Além desse acesso, o CoreBase adiciona Unified Context e Query Memory: os relacionamentos de esquema, terminologia e padrões de consulta comprovados que transformam acesso bruto em respostas precisas.