run402

Instructions

Implementation Reference

• src/tools/run-sql.ts:24-57 (handler)

  The main handler function that executes SQL queries against a provisioned project. Retrieves project credentials, makes an API request to the SQL endpoint, and formats the results as a markdown table.

  export async function handleRunSql(args: {
    project_id: string;
    sql: string;
  }): Promise<{ content: Array<{ type: "text"; text: string }>; isError?: boolean }> {
    const project = getProject(args.project_id);
    if (!project) return projectNotFound(args.project_id);
  
    const res = await apiRequest(`/admin/v1/projects/${args.project_id}/sql`, {
      method: "POST",
      rawBody: args.sql,
      headers: {
        "Content-Type": "text/plain",
        Authorization: `Bearer ${project.service_key}`,
      },
    });
  
    if (!res.ok) return formatApiError(res, "running SQL");
  
    const body = res.body as {
      status: string;
      schema: string;
      rows: Record<string, unknown>[];
      rowCount: number | null;
    };
  
    const table = formatMarkdownTable(body.rows);
    const lines = [
      `**${body.rows.length} row${body.rows.length !== 1 ? "s" : ""} returned** (schema: ${body.schema})`,
      ``,
      table,
    ];
  
    return { content: [{ type: "text", text: lines.join("\n") }] };
  }

• src/tools/run-sql.ts:6-9 (schema)

  Zod schema defining the input parameters: project_id (string) and sql (string) for the run_sql tool.

  export const runSqlSchema = {
    project_id: z.string().describe("The project ID to run SQL against"),
    sql: z.string().describe("SQL statement to execute (DDL or DML)"),
  };

• src/index.ts:72-77 (registration)

  Registration of the run_sql tool with the MCP server, providing the tool name, description, schema, and handler function.

  server.tool(
    "run_sql",
    "Execute SQL (DDL or queries) against a provisioned project. Returns results as a markdown table.",
    runSqlSchema,
    async (args) => handleRunSql(args),
  );

• src/tools/run-sql.ts:11-22 (helper)

  Helper function that formats SQL query results as a markdown table with headers, separators, and data rows.

  function formatMarkdownTable(rows: Record<string, unknown>[]): string {
    if (rows.length === 0) return "_0 rows returned_";
  
    const columns = Object.keys(rows[0]!);
    const header = `| ${columns.join(" | ")} |`;
    const separator = `| ${columns.map(() => "---").join(" | ")} |`;
    const body = rows.map(
      (row) => `| ${columns.map((c) => String(row[c] ?? "NULL")).join(" | ")} |`,
    );
  
    return [header, separator, ...body].join("\n");
  }