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;