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 destacar:

• El servidor MCP solo ejecuta SELECTs parametrizados; el 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 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 las variables de entorno

cp .env.example .env

Edite .env y cambie 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 está versionado — compruebe que no aparece en git status.

3. Levantar el PostgreSQL

docker compose up -d

Esto crea el contenedor mcp-teste-llm y ejecuta automáticamente, en la primera subida 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 del init.sh.

Si el contenedor ya existe de una ejecución anterior y agregas una migración nueva, el init.sh no se vuelve a ejecutar (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 o Ollama

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

5. Ejecutar las pruebas (opcional, pero recomendado)

npm test

Ejecuta node --check en todos los archivos y la suite node --test (solo lógica de enrutamiento y formato, no necesita que el Postgres ni el Ollama estén activos).

6. Iniciar el backend del agente

npm run start:agent

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

http://127.0.0.1:3100

Haz preguntas como:

• "¿Cuáles OS están atrasadas?"

• "Lista las OS del responsable Carlos."

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

• "¿Quiénes son los clientes inactivos?"

7. Finalizar

En la terminal del backend, presiona 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é)

Ejecución de las pruebas de integración

Con el backend (npm run start:agent) y el Ollama ya activos en otra terminal:

npm run test:integration

Herramientas disponibles

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