BlazeSQL MCP Server

Instructions

Implementation Reference

• src/index.ts:41-78 (handler)

  Tool handler function that destructures input params, calls queryBlazeSQL helper, formats the response with agent answer, SQL, and JSON data as Markdown text, or returns error content.

  async (params) => {
      const { db_id, natural_language_request } = params;
  
      // Input validation is handled by Zod schema above
  
      console.error(`Executing BlazeSQL query for DB ID: ${db_id}`);
      console.error(`Natural Language Request: "${natural_language_request}"`);
  
      // Call the BlazeSQL API function - apiKey is guaranteed non-null here
      const result: BlazeSQLResponse = await queryBlazeSQL(db_id, natural_language_request, apiKey!);
  
      if (result.success) {
          console.error("BlazeSQL query successful. Returning structured results as formatted text.");
  
          // Format the output into a single text block with Markdown
          const outputText = `**Agent Response:**\n${result.agent_response}\n\n**Generated SQL:**\n\`\`\`sql\n${result.query ?? "-- No SQL query returned"}\n\`\`\`\n\n**Data Result (JSON):**\n\`\`\`json\n${JSON.stringify(result.data_result ?? {}, null, 2)}\n\`\`\`\n`;
  
          // Return a single text content block
          return {
              content: [
                  {
                      type: "text",
                      text: outputText
                  }
              ]
          };
      } else {
          // Handle API errors - Throwing an error is standard for tool failures
          console.error(`BlazeSQL API Error (Code ${result.error_code}): ${result.error}`);
          // Return error message as text content
          return {
              content: [
                  { type: "text", text: `BlazeSQL API Error: ${result.error}` }
              ],
              isError: true // Indicate it's an error response
          };
      }
  }

• src/blazesql.ts:41-95 (helper)

  Core helper function implementing the HTTP request to BlazeSQL API, constructs request body, handles HTTP errors, parses JSON responses, and returns typed success/error objects.

  export async function queryBlazeSQL(
      dbId: string,
      naturalLanguageRequest: string,
      apiKey: string
  ): Promise<BlazeSQLResponse> {
      if (!apiKey) {
          throw new Error('BlazeSQL API key is missing. Ensure BLAZE_API_KEY is set in your environment.');
      }
  
      const requestBody: BlazeSQLRequest = {
          db_id: dbId,
          natural_language_request: naturalLanguageRequest,
          api_key: apiKey,
      };
  
      try {
          const response = await fetch(BLAZE_API_ENDPOINT, {
              method: 'POST',
              headers: {
                  'Content-Type': 'application/json',
              },
              body: JSON.stringify(requestBody),
          });
  
  
          if (!response.ok) {
              // Attempt to parse error response from Blaze, otherwise throw generic error
              try {
                  const errorData: BlazeSQLErrorResponse = await response.json() as BlazeSQLErrorResponse;
                   return { // Return a structured error matching BlazeSQLErrorResponse
                       success: false,
                       error: errorData.error || `HTTP error! status: ${response.status}`,
                       error_code: errorData.error_code || response.status,
                   };
              } catch (parseError) {
                   return { // Return a structured error matching BlazeSQLErrorResponse
                       success: false,
                       error: `HTTP error! status: ${response.status}. Failed to parse error response.`,
                       error_code: response.status,
                   };
              }
          }
  
          const data: BlazeSQLResponse = await response.json() as BlazeSQLResponse;
          return data;
  
      } catch (error) {
          console.error('Error querying BlazeSQL:', error);
           return { // Return a structured error matching BlazeSQLErrorResponse
               success: false,
               error: error instanceof Error ? error.message : 'An unknown error occurred during the API request.',
               error_code: 500, // Generic internal/network error
           };
      }
  }

• src/index.ts:36-39 (schema)

  Zod schema defining input parameters for the blazesql_query tool: db_id and natural_language_request.

  {
      db_id: z.string().describe("The ID of the BlazeSQL database connection to query."),
      natural_language_request: z.string().describe("The query expressed in natural language (e.g., 'show me total users per city').")
  },

• src/index.ts:34-79 (registration)

  Registers the 'blazesql_query' tool on the McpServer instance, specifying name, input schema, and handler function.

  server.tool(
      "blazesql_query", // Tool name
      {
          db_id: z.string().describe("The ID of the BlazeSQL database connection to query."),
          natural_language_request: z.string().describe("The query expressed in natural language (e.g., 'show me total users per city').")
      },
      // Tool handler function - TS should infer params type from raw shape now
      async (params) => {
          const { db_id, natural_language_request } = params;
  
          // Input validation is handled by Zod schema above
  
          console.error(`Executing BlazeSQL query for DB ID: ${db_id}`);
          console.error(`Natural Language Request: "${natural_language_request}"`);
  
          // Call the BlazeSQL API function - apiKey is guaranteed non-null here
          const result: BlazeSQLResponse = await queryBlazeSQL(db_id, natural_language_request, apiKey!);
  
          if (result.success) {
              console.error("BlazeSQL query successful. Returning structured results as formatted text.");
  
              // Format the output into a single text block with Markdown
              const outputText = `**Agent Response:**\n${result.agent_response}\n\n**Generated SQL:**\n\`\`\`sql\n${result.query ?? "-- No SQL query returned"}\n\`\`\`\n\n**Data Result (JSON):**\n\`\`\`json\n${JSON.stringify(result.data_result ?? {}, null, 2)}\n\`\`\`\n`;
  
              // Return a single text content block
              return {
                  content: [
                      {
                          type: "text",
                          text: outputText
                      }
                  ]
              };
          } else {
              // Handle API errors - Throwing an error is standard for tool failures
              console.error(`BlazeSQL API Error (Code ${result.error_code}): ${result.error}`);
              // Return error message as text content
              return {
                  content: [
                      { type: "text", text: `BlazeSQL API Error: ${result.error}` }
                  ],
                  isError: true // Indicate it's an error response
              };
          }
      }
  );

• src/blazesql.ts:7-29 (schema)

  TypeScript interfaces defining the BlazeSQL API request body, success response, error response, and union type used throughout the tool.

  export interface BlazeSQLRequest {
      db_id: string;
      natural_language_request: string;
      api_key: string;
  }
  
  export interface BlazeSQLSuccessResponse {
      success: true;
      message: string;
      query: string;
      agent_response: string;
      data_result: {
          [columnName: string]: (string | number | boolean | null)[];
      };
  }
  
  export interface BlazeSQLErrorResponse {
      success: false;
      error: string;
      error_code: number;
  }
  
  export type BlazeSQLResponse = BlazeSQLSuccessResponse | BlazeSQLErrorResponse;