QuestLLens

Dale ojos de IA a tus series temporales

El servidor MCP de QuestDB autodocumentado que convierte cualquier instancia de QuestDB en una fuente de conocimiento rica y consultable para agentes de IA, con conocimiento de primera clase de particiones, símbolos, claves de deduplicación, estado de WAL, salud de ingesta y disposición de almacenamiento.

Primeros pasos · Herramientas · Configuración · Docker · Seguridad · Contexto de dominio

¿Por qué QuestLLens?

Los modelos de IA son potentes, pero son ciegos a tu base de datos de series temporales. No conocen tu timestamp designado, tu estrategia de particionado, la cardinalidad de tus símbolos ni qué tablas van con retraso en la aplicación de WAL.

QuestLLens lo soluciona. Conecta cualquier instancia de QuestDB a asistentes de IA mediante el Model Context Protocol (MCP), dándoles 18 herramientas diseñadas a medida para descubrir, comprender y consultar tus datos, de forma segura, en modo de solo lectura y con cero riesgo de escrituras accidentales.

Cómo se relaciona con el servidor MCP integrado de QuestDB

QuestDB incluye su propio servidor MCP en la Web Console, y para el trabajo interactivo en tu escritorio es la mejor herramienta: tiene cuadernos, gráficos, consulta de documentación de SQL/funciones y traspaso bidireccional con la consola que ya tienes abierta. Úsala para eso.

Resuelve un problema distinto al de esta herramienta:

Recurre a QuestLLens cuando el agente no esté en tu navegador: un asistente sin interfaz, un contenedor detrás de un túnel, un punto final compartido del equipo, o en cualquier lugar donde necesites una garantía estricta de solo lectura en lugar de una configuración de permisos.

Qué hace diferente a QuestLLens

• Nativo de series temporales — A diferencia de los servidores MCP SQL genéricos, QuestLLens habla QuestDB. Los timestamps designados, las particiones de tiempo, la capacidad de símbolos, las claves de deduplicación y el estado de WAL son conceptos de primera clase sobre los que tu asistente de IA puede razonar.

• Autodocumentado — Extrae automáticamente metadatos de tablas, tipos de columna, particiones, índices y definiciones de vistas materializadas. Tu asistente de IA entiende tu esquema como lo hace tu equipo.

• Consciente del dominio — Inyecta un archivo markdown sencillo con contexto de negocio (qué significan las tablas, patrones comunes de SAMPLE BY, trampas) y QuestLLens lo integra en cada respuesta de herramienta.

• No invasivo — Se conecta a cualquier instancia de QuestDB mediante el protocolo de cable estándar de PostgreSQL. Sin agentes, sin extensiones, sin cambios de configuración en QuestDB. Solo un usuario de solo lectura.

• Seguridad ante todo — Defensa en profundidad: bloqueo de palabras clave SQL ajustado a toda la superficie DDL de QuestDB, tiempos de espera de sentencias, límites de filas y OAuth opcional con limitación de velocidad. Tus datos permanecen seguros.

Related MCP server: django-mcp-sql

Primeros pasos

Requisitos previos

• Node.js 20+

• QuestDB 7.4+ (cualquier instancia alojada o autogestionada: las tablas WAL se convirtieron en el valor predeterminado en 7.4)

• Un usuario de QuestDB con privilegios SELECT (se recomienda solo lectura; consulta Seguridad)

Inicio rápido (npm)

# Clone and install
git clone https://github.com/DMDuFresne/questllens.git
cd questllens
npm install

# Configure
cp .env.example .env
cp context.md.example context.md
# Edit .env with your QUESTDB_URL

# Build and run
npm run build
npm start

QuestLLens ahora se ejecuta en http://localhost:3000 con el punto final MCP en /mcp.

Inicio rápido (Docker)

docker run -p 3000:3000 \
  -e QUESTDB_URL="postgresql://admin:quest@host:8812/qdb" \
  ghcr.io/dmdufresne/questllens:1.0.0

Conectar con Claude Desktop

Añade QuestLLens a tu configuración de Claude Desktop:

{
  "mcpServers": {
    "questllens": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

Con OAuth habilitado:

{
  "mcpServers": {
    "questllens": {
      "url": "http://localhost:3000/mcp",
      "authorizationUrl": "http://localhost:3000/oauth/authorize",
      "tokenUrl": "http://localhost:3000/oauth/token",
      "registrationUrl": "http://localhost:3000/oauth/register"
    }
  }
}

Conectar con Claude Code

{
  "mcpServers": {
    "questllens": {
      "type": "url",
      "url": "http://localhost:3000/mcp"
    }
  }
}

Habilidades

skills/ incluye cuatro habilidades de Claude que enseñan a Claude a manejar QuestLLens en lugar de adivinar los nombres de las herramientas:

Copia los cuatro directorios de skills/ a .claude/skills/ de tu proyecto (o donde tu cliente cargue las habilidades) para que estén disponibles; Claude Code mostrará automáticamente la adecuada según las frases de activación del frontmatter de cada habilidad.

Herramientas

QuestLLens expone 18 herramientas MCP organizadas en seis categorías. Las herramientas se diseñaron pensando primero en los agentes de IA: salida en markdown para densidad de tokens, descripciones que explican cuándo usar cada una y diagnósticos compuestos que responden preguntas en una sola ida y vuelta en lugar de tres.

Consulta

Descubrimiento de esquema

Exploración de datos

Almacenamiento y particiones

Operaciones

Servidor

Configuración

QuestLLens se configura mediante variables de entorno. Crea un archivo .env o pásalas directamente.

Obligatorias

Las credenciales PG-wire predeterminadas de QuestDB son admin / quest en el puerto 8812. Cámbialas y crea un usuario de solo lectura; consulta Seguridad.

Opcionales

Opciones de OAuth (al ejecutar con --oauth)

Docker

Pull

docker pull ghcr.io/dmdufresne/questllens:1.0.0

Build

docker build -t questllens .

Run

# Without OAuth (local development, trusted networks)
docker run -p 3000:3000 \
  -e QUESTDB_URL="postgresql://readonly:password@host:8812/qdb" \
  questllens

# With OAuth (production, Claude Desktop)
docker run -p 3000:3000 \
  -e QUESTDB_URL="postgresql://readonly:password@host:8812/qdb" \
  -e MCP_AUTH_PASSWORD="your-secure-password" \
  questllens node dist/index.js --oauth

# With custom domain context
docker run -p 3000:3000 \
  -e QUESTDB_URL="postgresql://readonly:password@host:8812/qdb" \
  -v ./my-context.md:/app/context.md \
  -e DOMAIN_CONTEXT_FILE="context.md" \
  questllens

Docker Compose

services:
  questllens:
    image: ghcr.io/dmdufresne/questllens:1.0.0
    ports:
      - "3000:3000"
    environment:
      QUESTDB_URL: postgresql://readonly:password@questdb:8812/qdb
      MAX_ROWS: 500
    volumes:
      - ./context.md:/app/context.md
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
    restart: unless-stopped

Detalles de la imagen

• Base: node:20-alpine (compilación multi-etapa)

• Tamaño: ~80MB

• Usuario: No root (nodejs:1001)

• Comprobación de salud: Integrada mediante el endpoint /health

Seguridad

La notificación de vulnerabilidades y lo que está o no dentro del alcance se encuentran en SECURITY.md. La versión breve: la garantía de solo lectura y el flujo de OAuth están dentro del alcance; cualquier cosa accesible con acceso de lectura legítimamente concedido no lo está: usa un rol de base de datos con privilegios mínimos.

QuestLLens es de solo lectura por diseño y usa defensa en profundidad. La capa de aplicación no es suficiente por sí sola: un rol de base de datos de solo lectura y el aislamiento de red son obligatorios, no opcionales. Las secciones siguientes describen cada capa.

Obligatorio: Rol de base de datos de solo lectura

QuestDB no respeta BEGIN READ ONLY de PostgreSQL. La base de datos es tu única barrera de escritura aplicable. Ejecuta QuestLLens con un usuario de solo lectura:

QuestDB Enterprise (RBAC por usuario):

CREATE USER questllens_readonly WITH PASSWORD 'your-secure-password';
GRANT SELECT ON ALL TABLES TO questllens_readonly;

QuestDB Open Source (aún sin RBAC por usuario):

OSS carece de RBAC por usuario, por lo que la capa de aplicación no puede aislar completamente las escrituras. Mitigaciones obligatorias:

1. Cambia las credenciales predeterminadas admin/quest de inmediato.

2. Aísla por red el puerto PG-wire (8812) para que solo QuestLLens pueda alcanzarlo. No lo expongas a estaciones de trabajo de operadores ni a otros servicios.

3. Ejecuta QuestLLens detrás de OAuth (--oauth) para que los clientes MCP también estén controlados en la capa de aplicación.

Si no puedes cumplir (1) y (2), no ejecutes QuestLLens contra una instancia OSS de producción.

Ruta de solo lectura en la capa de aplicación (defensa en profundidad)

Cada sentencia SQL proporcionada por el usuario pasa por un tokenizador real (maneja '…' con escapes '', $tag$…$tag$, --, /* */) y se comprueba contra:

• Lista de permitidos del verbo inicial — solo se aceptan SELECT, WITH, EXPLAIN, SHOW o TABLES.

• Rechazo de múltiples sentencias — cualquier cosa después de un ; se rechaza. La ruta de consulta simple de pg-wire ejecuta múltiples sentencias; la comprobación de seguridad hace que sea imposible alcanzarla.

• Escaneo de palabras clave prohibidas en la entrada tokenizada — INSERT · UPDATE · DELETE · DROP · CREATE · ALTER · TRUNCATE · RENAME · REINDEX · VACUUM · BACKUP · SNAPSHOT · COPY · ATTACH · DETACH · GRANT · REVOKE · SET · RESET · RESUME · SUSPEND · CHECKPOINT · CANCEL · KILL · SQUASH · CONVERT · DEDUP · REFRESH · CALL · EXECUTE · PREPARE · DEALLOCATE. Como la entrada está tokenizada, WHERE message LIKE '%DROP%' no activa el escaneo.

Las consultas de introspección internas (tables(), wal_tables(), SHOW CREATE TABLE, …) omiten la comprobación de seguridad mediante un indicador explícito internal: true en el cliente de base de datos. Cada punto de llamada interna es un punto de auditoría; la entrada del usuario nunca llega a esa ruta.

Tiempos de espera de sentencias

El statement_timeout por consulta se vuelve a aplicar en cada extracción de conexión (QuestDB no tiene SET LOCAL), por lo que una llamada interna anterior no puede dejar un valor obsoleto en una conexión agrupada. Predeterminado: 30 segundos.

Límites de filas

Los resultados se limitan a un máximo configurable (predeterminado: 1000 filas) con una advertencia de truncamiento.

OAuth (cuando --oauth está habilitado)

Al ejecutar con --oauth, QuestLLens proporciona:

• RFC 7591 Registro dinámico de clientes

• PKCE S256 — obligatorio cuando el cliente envía un code_challenge; el verificador se comprueba en el endpoint de tokens con comparación de tiempo constante

• Vinculación del código de autorización — el código está vinculado a su client_id y redirect_uri; cualquier discrepancia en el canje se rechaza

• Validación de URI de redirección — solo se aceptan URIs registradas; el esquema está restringido a https (o http://localhost/127.0.0.1 para desarrollo)

• Lista blanca CORS — MCP_ALLOWED_ORIGINS (separada por comas) fija qué orígenes de navegador pueden llamar al servidor. Si se deja vacía, permite cualquier origen, lo cual es seguro aquí porque cada ruta de herramienta requiere un token Bearer en lugar de una cookie — una página de origen cruzado no tiene ninguna credencial ambiental que usar. Establézcala cuando quiera restringir los orígenes del navegador

• Límite de velocidad en los intentos de contraseña (5 por 15 minutos por defecto)

• Comparación de contraseñas segura frente a temporización

• Validación de token Bearer en todos los endpoints MCP; los tokens caducados se eliminan del almacén en memoria

• Página de consentimiento autocontenida — la página de inicio de sesión no carga fuentes, scripts ni recursos de terceros, por lo que una solicitud de autenticación nunca filtra una petición a una CDN

• Cabeceras de seguridad en cada respuesta — Content-Security-Policy: default-src 'none' (solo estilos en línea, frame-ancestors 'none', base-uri 'none'), además de X-Content-Type-Options, X-Frame-Options: DENY, Referrer-Policy: no-referrer y Cross-Origin-Opener-Policy. Sin form-action: el 302 del formulario de consentimiento va al redirect_uri registrado del cliente, que para un cliente nativo es un puerto de bucle local — un origen diferente que los navegadores bloquean bajo form-action 'self'. El destino de la redirección se restringe en su lugar en el servidor, contra las URIs registradas del cliente

• Límite de 1 MB en el cuerpo de la solicitud tanto en cuerpos JSON como codificados en formulario

Los tokens y los códigos de autorización se mantienen en memoria; no sobreviven a un reinicio del servidor. Persístalos externamente si necesita sesiones de larga duración entre reinicios.

Detrás de un proxy o túnel: establezca TRUST_PROXY_HEADERS=true, o el limitador de velocidad verá cada solicitud como proveniente de la única dirección del proxy y los inicios de sesión fallidos de un atacante bloquearán a todos los clientes. Solo actívelo cuando ese proxy sea la única ruta al servidor.

Contexto del dominio

Esta es el arma secreta de QuestLLens. Mientras que la introspección de esquemas le dice a la IA qué aspecto tienen sus tablas, el contexto del dominio le dice qué significan — y, para datos de series temporales, cómo consultarlas bien.

Cómo funciona

Copie la plantilla y describa la lógica de negocio de su base de datos, y luego apunte QuestLLens hacia ella:

cp context.md.example context.md

context.md está en gitignore — es donde reside su conocimiento de dominio propietario, por lo que nunca se confirma en el repositorio.

# Via environment variable
DOMAIN_CONTEXT_FILE=context.md

# Or inline
DOMAIN_CONTEXT="This database stores sensor telemetry from industrial PLCs. Use SAMPLE BY for downsampled queries; never SELECT * across more than 1 hour of raw data."

QuestLLens inyecta este contexto en las descripciones de las herramientas, para que su asistente de IA entienda su dominio desde la primera interacción.

Ejemplo de context.md

# Industrial Telemetry Database

## Key Concepts
- Every table is partitioned by **DAY** with designated timestamp `ts`
- The `device_id` column is a SYMBOL — always filter on it before time ranges
- We use `LATEST ON ts PARTITION BY device_id` to get the most recent reading per device
- Hot data lives in the last 7 days; older partitions are detached to cold storage

## Common Queries
- 1-minute downsample: `SELECT ts, avg(value) FROM readings SAMPLE BY 1m`
- Latest per device: `SELECT * FROM readings LATEST ON ts PARTITION BY device_id`
- Aligned multi-sensor: `ASOF JOIN` on `ts`

## Gotchas
- The `value` column is in raw ADC counts, not engineering units — multiply by `scale` from `device_config`
- `ts` is always UTC; the device-local time is in `local_ts`
- Never run `SELECT *` on the `raw_packets` table — it's billions of rows

Qué se enriquece

El contexto del dominio se integra en:

• La descripción de la herramienta query (para que la IA escriba mejor SQL)

• Los resultados de get_partitions y describe_table --with_time_range (para que la IA entienda el ciclo de vida de los datos)

• La salida de describe_table --with_symbol_stats (para que la IA respete las restricciones de cardinalidad)

• Las respuestas de descubrimiento de esquemas (para que la IA haga mejores preguntas de seguimiento)

Referencia de la API

Comprobación de estado

GET /health

Devuelve el estado del servidor y la versión:

{
  "status": "healthy",
  "server": "questllens",
  "version": "1.0.0"
}

Endpoint MCP

POST /mcp          → JSON-RPC 2.0 request
GET  /mcp          → Server-Sent Events (SSE) stream
DELETE /mcp        → Session termination

Toda la comunicación MCP utiliza Streamable HTTP Transport con gestión de sesiones mediante la cabecera mcp-session-id.

Endpoints OAuth (cuando --oauth está habilitado)

GET  /.well-known/oauth-protected-resource  → Resource metadata
GET  /.well-known/oauth-authorization-server → Server metadata
POST /oauth/register                         → Dynamic client registration
GET  /oauth/authorize                        → Login form
POST /oauth/authorize                        → Authenticate
POST /oauth/token                            → Token exchange

Desarrollo

# Install dependencies
npm install

# Run in dev mode (hot reload)
npm run dev

# Run with OAuth in dev mode
npm run dev:oauth

# Type check
npm run typecheck

# Run tests (read-only SQL boundary, config validation, identifier quoting)
npm test

# Build for production
npm run build

Estructura del proyecto

src/
├── index.ts                       # Entry point
├── config.ts                      # Environment config with Zod validation
├── server.ts                      # Express + MCP server, OAuth, session management
├── database/
│   ├── client.ts                  # PG-wire connection pool, query execution
│   ├── schema-loader.ts           # QuestDB introspection + cache (auto-refresh on miss)
│   └── sql-safety.ts              # Lexer + allowlist enforcing the read-only path
├── tools/
│   ├── index.ts                   # Executor re-exports
│   ├── _util.ts                   # Shared identifier quoting
│   ├── query.ts                   # Execute SELECT queries (markdown output)
│   ├── explain-query.ts           # QuestDB EXPLAIN
│   ├── suggest-sample-by.ts       # Pick a SAMPLE BY interval for a target bucket count
│   ├── list-tables.ts             # Tables with TS / partitioning / WAL flags
│   ├── describe-table.ts          # Table or MV detail (with optional time range / symbol stats)
│   ├── search-columns.ts          # Cross-table column search
│   ├── get-create-table.ts        # Round-trippable CREATE TABLE / CREATE MATERIALIZED VIEW
│   ├── get-table-params.ts        # Per-table ingestion knobs (o3MaxLag, maxUncommittedRows, ttl)
│   ├── refresh-schema.ts          # Manual cache reload (auto-refresh on miss is the default)
│   ├── get-partitions.ts          # Partition list with from/to filter and summary mode
│   ├── get-storage-summary.ts     # Top-N tables by disk (parquet vs native)
│   ├── get-sample-data.ts         # Sample rows with optional columns/where projection
│   ├── get-table-stats.ts         # Per-column null % + distinct (single batched SQL)
│   ├── get-wal-status.ts          # WAL apply state, lag, suspended tables
│   ├── get-ingestion-health.ts    # Composite WAL lag + latest-row staleness diagnostic
│   ├── get-running-queries.ts     # query_activity() wrapper
│   ├── get-mv-dependencies.ts     # Materialized view graph (forward + reverse)
│   └── server-info.ts             # Version, build, feature detection
├── descriptions/
│   ├── generator.ts               # Dynamic description builder
│   └── static.ts                  # Static description blocks
├── types/
│   └── index.ts                   # TypeScript interfaces
└── ...

tests/
├── sql-safety.test.ts             # Read-only boundary: verbs, literals, injection shapes
├── config.test.ts                 # Env parsing, limits, domain-context loading
└── identifiers.test.ts            # quoteIdent breakout attempts

skills/                            # Claude skills — copy into .claude/skills/
├── questllens-using/
├── questllens-explore-a-database/
├── questllens-health-check/
└── questllens-tune-a-query/

El CI ejecuta la comprobación de tipos, las pruebas y la compilación en Node 20 y 22, luego construye la imagen y verifica que el límite de solo lectura se mantiene contra un contenedor QuestDB en vivo (consulte .github/workflows/ci.yml).

Casos de uso

Compatibilidad

QuestLLens funciona con cualquier cliente compatible con MCP:

• Claude Desktop (con o sin OAuth)

• Claude Code (CLI)

• Cursor / Windsurf / VS Code (mediante extensiones MCP)

• Clientes MCP personalizados (cualquier cliente que implemente la especificación MCP)

Y con cualquier despliegue de QuestDB:

• QuestDB Open Source 7.4+

• QuestDB Enterprise (recomendado — habilita RBAC por usuario)

• QuestDB Cloud

• Docker autogestionado, Kubernetes o metal desnudo

get_mv_dependencies y la rama de vistas materializadas de describe_table / get_create_table requieren QuestDB 8.x. get_running_queries requiere una versión de QuestDB que exponga query_activity(). Ejecute server_info para ver qué admite la instancia conectada. Todas las demás herramientas son compatibles con 7.4+.

Solución de problemas

"Connection refused" en el puerto 8812

QuestLLens se conecta mediante el protocolo de cable de PostgreSQL en el puerto 8812, no mediante la API HTTP en 9000. Asegúrese de que el listener PG-wire esté habilitado (pg.enabled=true en server.conf) y sea accesible.

"Permission denied" en la introspección de esquemas

QuestLLens usa las funciones del sistema de QuestDB (tables(), table_columns(), wal_tables(), table_partitions(), materialized_views()). En QuestDB OSS están disponibles para cualquier usuario autenticado. En QuestDB Enterprise, asegúrese de que a su rol se le hayan concedido los privilegios de lectura necesarios:

GRANT SELECT ON ALL TABLES TO questllens_readonly;

get_mv_dependencies devuelve vacío

Las vistas materializadas requieren QuestDB 8.x. Si está en 7.x, esta herramienta devolverá un resultado vacío con un aviso — actualice a 8.0+ para usar MV.

get_wal_status muestra "WAL not enabled"

Las tablas WAL se convirtieron en el valor predeterminado en QuestDB 7.4. Las tablas creadas en versiones anteriores pueden seguir siendo no-WAL; aparecerán en list_tables con wal_enabled = false y no se incluirán en get_wal_status.

Los cambios de esquema no se reflejan

QuestLLens almacena en caché los metadatos del esquema. Espere al siguiente ciclo de actualización (predeterminado: 5 minutos) o llame a refresh_schema para actualizar la caché MCP inmediatamente.

El inicio de sesión OAuth falla

Compruebe que MCP_AUTH_PASSWORD está establecida y que el limitador de velocidad no se ha activado (5 intentos por 15 minutos por defecto). Consulte los registros del servidor para más detalles.

Licencia

Apache-2.0. Libre de usar, modificar y distribuir con atribución; incluye una concesión explícita de patentes. Consulte LICENSE para los términos y NOTICE para las licencias de dependencias de terceros, el aviso de marca comercial de QuestDB y la exclusión de activos de marca de Abelara — los logotipos y el material gráfico de marca no están cubiertos por Apache-2.0.

Proporcionado "tal cual" sin garantía de ningún tipo — úselo bajo su propio riesgo.

Construido por Abelara

QuestLLens forma parte del conjunto de herramientas de Abelara para IA industrial y computación en el borde, junto con PgLLens para PostgreSQL.

Informar de un error · Solicitar una función · Más información