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.

Related MCP server: MySQL MCP Server

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):

sequenceDiagram
    participant Client as MCP Client (e.g., Cursor)
    participant Server as BlazeSQL MCP Server (index.ts)
    participant Env as Environment (.env)
    participant BlazeAPI as BlazeSQL API

    Client->>Server: ListTools Request (via stdio)
    Server-->>Client: ListTools Response (tools: [blazesql_query]) (via stdio)

    Client->>Server: CallTool Request (blazesql_query, db_id, nl_request) (via stdio)
    Server->>Env: Read BLAZE_API_KEY
    Env-->>Server: BLAZE_API_KEY
    Server->>BlazeAPI: POST /natural_language_query_api (apiKey, db_id, nl_request)
    BlazeAPI->>BlazeAPI: Process Query (NL->SQL, Execute)
    BlazeAPI-->>Server: HTTPS Response (JSON: agent_response, query, data_result OR error)
    Server->>Server: Format Response (Agent response, SQL, and data into single text block)
    Server-->>Client: CallTool Response (content: [{type: text, text: formattedMarkdown}]) (via stdio)

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`).