BlazeSQL MCP Server

Servidor MCP BlazeSQL

Este proyecto implementa un servidor de Protocolo de Contexto de Modelo (MCP) mediante @modelcontextprotocol/sdk que actúa como proxy para la API de Consultas en Lenguaje Natural de BlazeSQL. Permite que los clientes compatibles con MCP (como Cursor, Claude 3 con uso de herramientas, el Inspector de MCP, etc.) interactúen con BlazeSQL mediante lenguaje natural.

Características

• Construido utilizando la clase auxiliar McpServer moderna del SDK de MCP.
• Expone la API de consulta de lenguaje natural BlazeSQL como una herramienta MCP llamada blazesql_query .
• Utiliza zod para una validación robusta de los parámetros de entrada de la herramienta.
• Maneja la autenticación de clave API de forma segura a través de variables de entorno.
• Se comunica con los clientes utilizando el transporte stdio MCP estándar.

Diagrama de flujo de trabajo

Este diagrama muestra la secuencia de interacciones cuando un cliente usa la herramienta blazesql_query (Nota: la lógica del servidor interno ahora usa McpServer , lo que simplifica el registro de la herramienta en comparación con los controladores de bajo nivel que se muestran en el diagrama):

Prerrequisitos

• Node.js (versión LTS recomendada)
• Hilo (clásico o baya)
• Una cuenta BlazeSQL con una clave API (se requiere suscripción a Team Advanced para la API).
• Al menos una conexión de base de datos configurada en su cuenta BlazeSQL.
• Documentación de la API de consulta en lenguaje natural de BlazeSQL: https://help.blazesql.com/en/article/natural-language-query-api-1fgx4au/

Configuración

1. Clonar el repositorio:
   git clone <repository-url> cd blaze-sql-mcp-server
2. Dependencias de instalación:
   yarn install
   Esto instalará todas las dependencias necesarias, incluidas @modelcontextprotocol/sdk , dotenv y zod .
3. Configurar variables de entorno:
   • Copie el archivo de entorno de ejemplo:
     cp .env.sample .env
   • Edite el archivo .env :
     # .env BLAZE_API_KEY=YOUR_BLAZESQL_API_KEY_HERE
     Reemplace YOUR_BLAZESQL_API_KEY_HERE con su clave API real obtenida de la configuración de su cuenta BlazeSQL.

Ejecución del servidor

1. Construir el servidor: compilar el código TypeScript en JavaScript:
   yarn build
2. Ejecutar el servidor: Ejecute el código compilado:
   node build/index.js
   El servidor se iniciará y registrará los mensajes en stderr (podría ver "Clave API cargada correctamente...", etc.). Ahora está a la espera de una conexión de cliente MCP mediante la entrada/salida estándar (stdio).

Conexión de un cliente MCP

Este servidor utiliza el mecanismo de transporte stdio .

Uso del inspector MCP (recomendado para pruebas)

1. Asegúrese de que el servidor no esté ejecutándose por separado.
2. Ejecute el Inspector y dígale que inicie su servidor:
   npx @modelcontextprotocol/inspector node build/index.js
3. Se iniciará la interfaz de usuario del Inspector y se conectará automáticamente a su servidor.
4. Vaya a la pestaña "Herramientas" para interactuar con la herramienta blazesql_query .

Uso de clientes integrados (Cursor, Claude 3, etc.)

1. Inicie el servidor en una terminal:
   node build/index.js
2. Configurar el cliente: en la configuración de su cliente MCP, debe agregar una configuración de servidor personalizada.
   • Transporte: Seleccionar stdio .
   • Comando: Especifique el comando exacto para ejecutar el servidor. Debe proporcionar la ruta absoluta al nodo y la ruta absoluta al archivo build/index.js .
     • Ejemplo (macOS/Linux - ajuste las rutas según sea necesario): /usr/local/bin/node /Users/your_username/path/to/blaze-sql-mcp-server/build/index.js
     • Puedes encontrar la ruta al nodo usando which node en tu terminal.
     • Puede encontrar la ruta al proyecto usando pwd dentro del directorio del proyecto.
   • Guardar la configuración.
3. El cliente ahora debería poder conectarse a su servidor local y enumerar/utilizar sus herramientas.

Uso de la herramienta blazesql_query

Una vez conectado, el cliente puede llamar a la herramienta blazesql_query .

• Nombre de la herramienta: blazesql_query
• Argumentos:
  • db_id (cadena, obligatoria): El ID de la conexión a la base de datos de destino en su cuenta de BlazeSQL. Puede encontrar este ID en la aplicación web de BlazeSQL al administrar sus conexiones a la base de datos.
  • natural_language_request (string, required): La consulta que desea ejecutar, escrita en inglés simple (p. ej., "muéstrame el número total de usuarios"). (La entrada se valida con zod ).
• Ejemplo de llamada (utilizando la sintaxis mcp test para ilustración):
  call-tool blazesql_query --db_id "db_your_actual_db_id" --natural_language_request "What were the total sales last month?"
• Salida: si tiene éxito, la herramienta devuelve un solo bloque de contenido text que contiene:
  • La respuesta en lenguaje natural del agente BlazeSQL.
  • La consulta SQL generada dentro de una valla de código Markdown ( sql ... ).
  • Los datos resultan formateados como JSON dentro de un límite de código Markdown ( json ... ).

  Ejemplo de estructura dentro del bloque text :

  **Agent Response:** The total sales last month were $12345.67. **Generated SQL:** ```sql SELECT sum(sales_amount) FROM sales WHERE sale_date >= date('now', '-1 month');

  Resultado de los datos (JSON):

  [ { "sum(sales_amount)": 12345.67 } ]
  If unsuccessful, it returns a `text` content block containing the error message from the BlazeSQL API and marks the response as an error (`isError: true`).