MCP + Ollama — consulta en lenguaje natural a una base de datos Postgres

Servidor MCP (Model Context Protocol) de solo lectura + backend agente local que traduce preguntas en portugués a consultas SQL seguras, usando un LLM local (Ollama) para decidir qué "tool" llamar. Los datos de ejemplo son ficticios: órdenes de servicio y clientes.

Cómo funciona

Usuário (interface web)
  ↓ pergunta em português
Backend agente (agent/server.js)
  ↓ roteamento determinístico (regex) OU decisão do LLM
Ollama (function calling, modelo qwen2.5:3b)
  ↓ escolhe uma tool + argumentos
Cliente MCP (agent/mcp-client.js)
  ↓ JSON-RPC via STDIO
Servidor MCP (src/server.js)
  ↓ SQL parametrizado, usuário somente-leitura
PostgreSQL

Puntos de seguridad que vale la pena destacar:

• El servidor MCP solo ejecuta SELECTs parametrizados; Postgres se conecta con un usuario dedicado (mcp_reader) que solo tiene GRANT SELECT, se ejecuta en transacción de solo lectura (default_transaction_read_only) y tiene un statement_timeout corto.

• Antes de llamar al LLM, el backend ya bloquea preguntas que piden escritura (agent/write-policy.js) — no depende de que el modelo se comporte bien.

• Siempre que la pregunta coincide con un patrón conocido (agent/os-routing.js, agent/client-routing.js), la tool y los argumentos se eligen por regla, no por el LLM — más predecible y más barato. El LLM solo decide libremente cuando la pregunta es ambigua.

Related MCP server: kond-royalties-agent

Requisitos

• Node.js 20+

• npm

• Docker y Docker Compose

• Ollama instalado localmente, con el modelo qwen2.5:3b

Paso a paso para ejecutar desde cero

1. Clonar e instalar dependencias

git clone https://github.com/leomc06/mcp-teste-llm2.git
cd mcp-teste-llm2
npm install

2. Configurar variables de entorno

cp .env.example .env

Edita .env y cambia los valores marcados como troque (usuario, contraseña y nombre de la base de datos Postgres, y la contraseña del usuario de solo lectura mcp_reader). El .env nunca se versiona — comprueba que no aparece en git status.

3. Levantar PostgreSQL

docker compose up -d

Esto crea el contenedor mcp-teste-llm y ejecuta automáticamente, en el primer arranque del volumen, el script db/init.sh — que crea las tablas, los datos de ejemplo y el usuario mcp_reader. Las migraciones están en db/migrations/ y se aplican en orden (001, 002, 003, ...) mediante \ir dentro de init.sh.

Si el contenedor ya existe de una ejecución anterior y añades una migración nueva, el init.sh no se ejecuta de nuevo solo (el volumen ya tiene datos). Aplica la migración manualmente:

docker compose exec -T postgres psql -U <POSTGRES_USER> -d <POSTGRES_DB> -f - < db/migrations/00X_nome.sql

4. Preparar Ollama

sudo systemctl start ollama
ollama pull qwen2.5:3b

5. Ejecutar los tests (opcional, pero recomendado)

npm test

Ejecuta node --check en todos los archivos y la suite node --test (solo lógica de enrutamiento y formateo, no necesita Postgres ni Ollama en funcionamiento).

6. Iniciar el backend agente

npm run start:agent

El backend levanta el servidor MCP automáticamente (vía STDIO), se conecta a Postgres y sirve la interfaz web. Accede:

http://127.0.0.1:3100

Haz preguntas como:

• "¿Qué OS están atrasadas?"

• "Lista las OS del responsable Carlos."

• "¿Cuántas OS ha resuelto el cliente Bruno Santos?"

• "¿Qué clientes están inactivos?"

7. Finalizar

En el terminal del backend, Ctrl+C (esto también cierra el servidor MCP hijo).

sudo systemctl stop ollama
docker compose stop   # para o Postgres sem apagar dados/volumes

Estructura del proyecto

src/server.js            servidor MCP: define as tools e faz as queries SQL
agent/server.js          backend HTTP: recebe a pergunta, orquestra tudo
agent/os-routing.js      roteamento por regex das perguntas sobre OS
agent/client-routing.js  roteamento por regex das perguntas sobre clientes
agent/tool-selector.js   junta as duas rotas e decide quais tools expor ao LLM
agent/agent-loop.js      loop de function calling com o Ollama
agent/mcp-client.js      cliente MCP + allowlist de tools permitidas
agent/write-policy.js    bloqueio de perguntas que pedem escrita
agent/response-formatter.js  formata o resultado das tools em texto
db/init.sh               script de inicialização do Postgres (roles, grants)
db/migrations/           migrations SQL, aplicadas em ordem
web/                      interface web estática
test/                     testes (node --test)
integration-agent.mjs     teste de integração ponta a ponta (precisa da stack de pé)

Ejecutando tests de integración

Con el backend (npm run start:agent) y Ollama ya en funcionamiento en otro terminal:

npm run test:integration

Tools disponibles

El servidor MCP expone tools de consulta sobre órdenes de servicio (buscar por número, listar abiertas/atrasadas/recientes, filtrar por estado, prioridad, responsable, solicitante o cliente, historial, resúmenes y tiempo medio de resolución) y sobre clientes (listar, listar inactivos/recientes, buscar por id/e-mail/nombre, dominios de e-mail, resúmenes). La lista completa y actualizada de las tools habilitadas para el agente está en allowedToolNames, al inicio de agent/mcp-client.js.