BlazeSQL MCP Server

Servidor MCP BlazeSQL

Este proyecto implementa un servidor de Protocolo de Contexto de Modelo (MCP) 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

• Expone la API de consulta de lenguaje natural BlazeSQL como una herramienta MCP llamada blazesql_query .
• 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 utiliza la herramienta blazesql_query :

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
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 (cadena, obligatoria): la consulta que desea ejecutar, escrita en inglés simple (por ejemplo, "muéstrame el número total de usuarios").
• 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 bloque text que contiene la respuesta en lenguaje natural del agente BlazeSQL.
  • Un bloque code (lenguaje sql ) que contiene la consulta SQL generada y ejecutada por BlazeSQL.
  • Un bloque json que contiene los resultados de la consulta. Si no se realiza correctamente, devuelve un mensaje de error de MCP.