askDB MCP

Un servidor MCP que convierte preguntas de datos en lenguaje natural en el contexto de esquema que un LLM necesita para escribir SQL. No se conecta a tu base de datos y no genera SQL por sí mismo: recupera las definiciones de tabla correctas de tu índice de Pinecone y se las entrega al modelo que las solicite (Claude Code, Claude Desktop, ChatGPT, Cursor).

user question
   │
   ▼
Claude Code / ChatGPT ──calls──► askDB MCP ──semantic search──► Pinecone (ask-db)
   │                                  │
   │      relevant DDL + guardrails ◄─┘
   ▼
generated SQL

Herramientas

Cada respuesta incluye instrucciones que le indican al modelo que use solo las tablas y columnas devueltas, para que no invente nombres.

Configuración

npm install
npm run setup             # creates .env from the template
#                          → then put your PINECONE_API_KEY in .env
npm run doctor            # verify connection, field mapping and retrieval quality

¿Compartes esto con alguien? Envíale SETUP.md: cubre tanto ejecutarlo localmente como conectarse a una instancia alojada.

npm run doctor es el paso importante. Imprime la configuración del índice, los campos de metadatos que usan realmente tus registros y una búsqueda de ejemplo, para que puedas confirmar que el servidor está leyendo los campos correctos antes de conectarlo a un cliente.

npm run doctor       # connectivity + retrieval sanity check
npm run smoke        # drive the stdio server with a real MCP client
npm run smoke:http   # same over Streamable HTTP, with bearer auth

Conectar un cliente

Claude Code

La CLI, la aplicación de escritorio y las extensiones del IDE comparten una misma configuración, así que esto registra el servidor para los tres:

# from the repo root — records an absolute path, so it works in any folder
claude mcp add askdb --scope user -- node "$PWD\src\server.js"

Compruébalo con claude mcp list (askdb: ... ✓ Connected) y reinicia la aplicación de escritorio o la ventana del IDE: los servidores MCP se cargan al inicio.

El ámbito de usuario es deliberado: la idea es hacer preguntas sobre bases de datos mientras trabajas en tus otros repositorios. Un .mcp.json con ámbito de proyecto solo se resolvería cuando Claude Code se inicia desde la raíz de este repositorio, y definir askdb en ambos ámbitos haría que Claude Code advierta sobre el duplicado.

Claude Desktop / Cursor

Añade a claude_desktop_config.json (o a los ajustes MCP de Cursor):

{
  "mcpServers": {
    "askdb": {
      "command": "node",
      "args": ["D:\\working-directory\\AI\\askDB-mcp\\src\\server.js"]
    }
  }
}

Las credenciales provienen de .env junto al servidor, así que no van claves en la configuración del cliente.

ChatGPT

Los conectores de ChatGPT no pueden lanzar un proceso local: solo hablan MCP remoto sobre HTTP. Ejecuta el transporte HTTP y exponlo:

# set MCP_AUTH_TOKEN first: this endpoint serves your whole schema
MCP_AUTH_TOKEN=some-long-random-string npm run start:http

Luego apunta el conector a https://<tu-host>/mcp con una cabecera Authorization: Bearer <token>. Para una prueba rápida, haz un túnel (cloudflared tunnel --url http://localhost:3000); para algo duradero, alójalo correctamente: DEPLOY.md cubre Netlify de principio a fin. GET /health no requiere autenticación para las comprobaciones del balanceador de carga; /mcp requiere el token bearer siempre que MCP_AUTH_TOKEN esté definido.

El transporte HTTP no tiene estado (una instancia del servidor por solicitud), por lo que escala detrás de un balanceador de carga sin sesiones persistentes.

Alojamiento

Desplegado como dos funciones de Netlify: netlify.toml contiene los ajustes de compilación, así que importar el repositorio y definir PINECONE_API_KEY + MCP_AUTH_TOKEN es todo el trabajo. Paso a paso: DEPLOY.md.

Esto funciona sin reescribir el transporte porque WebStandardStreamableHTTPServerTransport del SDK de MCP acepta una Request y devuelve una Response, que es la firma de Netlify Functions v2, de modo que netlify/functions/mcp.mjs importa src/mcp.js sin cambios. El mismo archivo funciona en Cloudflare Workers, Deno o Bun; src/http.js cubre contenedores y máquinas virtuales.

GET /health no necesita token e informa si las variables de entorno requeridas llegaron (solo presencia, nunca valores): el sustituto serverless de leer un registro de inicio. /mcp falla de forma segura: sin MCP_AUTH_TOKEN definido devuelve 503 en lugar de servir tu esquema a internet.

Una vez que está en marcha, los compañeros no necesitan instalar nada: solo la URL y un token (SETUP.md, Ruta A).

Configuración

Todo es opcional excepto la clave de API. Consulta .env.example.

El servidor detecta automáticamente qué campos de metadatos usan tus registros y si el índice tiene embedding integrado, así que los valores predeterminados normalmente funcionan sin cambios.

Dos cosas que conviene saber

El modelo de embedding debe coincidir. Si EMBED_MODEL no es el modelo con el que se hizo el upsert del esquema, todas las puntuaciones caen a casi cero y los resultados son ruido: los vectores son efectivamente aleatorios entre sí. npm run doctor mostrará tablas no relacionadas que vuelven con puntuaciones alrededor de 0.01 en lugar de 0.8. Este índice se construyó con multilingual-e5-large.

Define DEFAULT_DATABASE si tu índice contiene varios entornos. Cuando el mismo esquema existe como *_live y *_test, una búsqueda sin ámbito devuelve ambas copias de cada tabla, quemando la mitad de los espacios de top_k en duplicados y permitiendo que el modelo mezcle entornos en una sola consulta.

Estructura