mcptesis — MCP server (solo lectura) sobre la base de flota

Servidor MCP que expone la base de datos del sistema de gestión de flota como tools de solo lectura. Lo consume el chatbot del backend (/api/chatbot), que corre el agent loop contra un LLM (vía OpenRouter) y usa estas tools para responder preguntas en lenguaje natural.

backend /api/chatbot  ──HTTP + Bearer──►  mcptesis (:4000/mcp)  ──SELECT──►  PostgreSQL (rol read-only)

Tools expuestas

Tool	Args	Qué hace
list_schema	—	Lista todas las tablas del schema public con columnas, tipos y FKs (cacheado).
describe_table	table	Detalle de una tabla puntual.
run_query	sql, max_rows?	Ejecuta una consulta SELECT/WITH y devuelve las filas en JSON.

Candados de solo lectura (defensa en profundidad)

1. Rol Postgres read-only — el server se conecta con DATABASE_URL_READONLY, un rol que solo tiene SELECT.
2. Validación estructural (src/guards.ts) — una sola sentencia, debe empezar con SELECT/WITH, sin ;, y rechaza palabras clave de escritura/DDL.
3. Transacción READ ONLY con statement_timeout y LIMIT forzado (src/db.ts).

Requisitos

• Node.js 20+ (probado en 22).
• Acceso a la base PostgreSQL del sistema de flota.

Setup

npm install
cp .env.example .env      # y completá los valores (ver abajo)

.env:

PORT=4000
DATABASE_URL_READONLY=postgresql://fleet_readonly:PASSWORD@host:5432/db
DB_SSL=true                 # true en Render/RDS
MCP_AUTH_TOKEN=<mismo token que el backend>
QUERY_TIMEOUT_MS=5000
MAX_ROWS=500

Crear el rol de solo lectura

Automático (usa un usuario owner para crear el rol):

ADMIN_DATABASE_URL="postgresql://OWNER:PASS@host:5432/db" \
READONLY_PASSWORD="una-password-fuerte" \
DB_SSL=true \
npm run create-readonly-role

O manual: ver sql/create_readonly_role.sql.

En bases administradas (Render) el usuario provisto puede no tener permiso para CREATE ROLE. Si es el caso, apuntá DATABASE_URL_READONLY a la conexión normal: los guards de la app fuerzan solo lectura igual (candados 2 y 3), aunque perdés el candado 1.

Correr

npm run dev      # desarrollo (tsx watch)
npm run build && npm start   # producción
npm run smoke    # con el server corriendo: lista tools + prueba list_schema/run_query

Health check: GET http://localhost:4000/health.

Estructura

src/
  config.ts         # env validado con zod
  db.ts             # pool pg + runReadOnlyQuery (txn read-only, timeout, limit)
  guards.ts         # validación SELECT-only
  introspection.ts  # esquema desde information_schema (cacheado)
  tools.ts          # registro de las 3 tools MCP
  server.ts         # McpServer + tools
  index.ts          # Express + Streamable HTTP transport + auth Bearer
scripts/
  create-readonly-role.ts
  smoke.ts
sql/
  create_readonly_role.sql