Self-Hosted Supabase MCP Server

Instructions

Implementation Reference

• src/tools/apply_migration.ts:38-77 (handler)

  The execute handler function that applies the provided SQL migration using a direct PG client within a transaction and records the migration in the supabase_migrations.schema_migrations table.

  execute: async (input: ApplyMigrationInput, context: ToolContext) => {
      const client = context.selfhostedClient;
  
      try {
          // Ensure pg is configured and available
          if (!client.isPgAvailable()) {
               throw new Error('Direct database connection (DATABASE_URL) is required for applying migrations but is not configured or available.');
          }
  
          await client.executeTransactionWithPg(async (pgClient: PoolClient) => {
              // 1. Execute the provided migration SQL
              console.error(`Executing migration SQL for version ${input.version}...`);
              await pgClient.query(input.sql);
              console.error('Migration SQL executed successfully.');
  
              // 2. Insert the record into the migrations table
              console.error(`Recording migration version ${input.version} in schema_migrations...`);
              await pgClient.query(
                  'INSERT INTO supabase_migrations.schema_migrations (version, name) ' +
                  'VALUES ($1, $2);',
                   [input.version, input.name ?? '']
               );
              console.error(`Migration version ${input.version} recorded.`);
          });
  
          return {
              success: true,
              version: input.version,
              message: `Migration ${input.version} applied successfully.`,
          };
      } catch (error: unknown) {
          const errorMessage = error instanceof Error ? error.message : String(error);
          console.error(`Failed to apply migration ${input.version}:`, errorMessage);
          // Return a structured error response recognized by handleSqlResponse if needed,
          // or let the SDK handle the thrown error.
          // Here, we'll just rethrow to let SDK handle it.
          // Alternatively, return { success: false, version: input.version, message: 'Failed: ' + errorMessage };
          throw new Error(`Failed to apply migration ${input.version}: ${errorMessage}`);
      }
  },

• src/tools/apply_migration.ts:6-11 (schema)

  Zod input schema and type for the apply_migration tool, defining version, optional name, and sql parameters.

  const ApplyMigrationInputSchema = z.object({
      version: z.string().describe("The migration version string (e.g., '20240101120000')."),
      name: z.string().optional().describe("An optional descriptive name for the migration."),
      sql: z.string().describe("The SQL DDL content of the migration."),
  });
  type ApplyMigrationInput = z.infer<typeof ApplyMigrationInputSchema>;

• src/tools/apply_migration.ts:14-18 (schema)

  Zod output schema for the apply_migration tool, including success boolean, version, and optional message.

  const ApplyMigrationOutputSchema = z.object({
      success: z.boolean(),
      version: z.string(),
      message: z.string().optional(),
  });

• src/tools/apply_migration.ts:32-78 (registration)

  Export of the applyMigrationTool object, defining the tool name, description, schemas, and execute handler.

  export const applyMigrationTool = {
      name: 'apply_migration',
      description: 'Applies a SQL migration script and records it in the supabase_migrations.schema_migrations table within a transaction.',
      inputSchema: ApplyMigrationInputSchema,
      mcpInputSchema: mcpInputSchema,
      outputSchema: ApplyMigrationOutputSchema,
      execute: async (input: ApplyMigrationInput, context: ToolContext) => {
          const client = context.selfhostedClient;
  
          try {
              // Ensure pg is configured and available
              if (!client.isPgAvailable()) {
                   throw new Error('Direct database connection (DATABASE_URL) is required for applying migrations but is not configured or available.');
              }
  
              await client.executeTransactionWithPg(async (pgClient: PoolClient) => {
                  // 1. Execute the provided migration SQL
                  console.error(`Executing migration SQL for version ${input.version}...`);
                  await pgClient.query(input.sql);
                  console.error('Migration SQL executed successfully.');
  
                  // 2. Insert the record into the migrations table
                  console.error(`Recording migration version ${input.version} in schema_migrations...`);
                  await pgClient.query(
                      'INSERT INTO supabase_migrations.schema_migrations (version, name) ' +
                      'VALUES ($1, $2);',
                       [input.version, input.name ?? '']
                   );
                  console.error(`Migration version ${input.version} recorded.`);
              });
  
              return {
                  success: true,
                  version: input.version,
                  message: `Migration ${input.version} applied successfully.`,
              };
          } catch (error: unknown) {
              const errorMessage = error instanceof Error ? error.message : String(error);
              console.error(`Failed to apply migration ${input.version}:`, errorMessage);
              // Return a structured error response recognized by handleSqlResponse if needed,
              // or let the SDK handle the thrown error.
              // Here, we'll just rethrow to let SDK handle it.
              // Alternatively, return { success: false, version: input.version, message: 'Failed: ' + errorMessage };
              throw new Error(`Failed to apply migration ${input.version}: ${errorMessage}`);
          }
      },
  }; 

• src/index.ts:103-103 (registration)

  Registration of the apply_migration tool in the availableTools object used by the MCP server.

  [applyMigrationTool.name]: applyMigrationTool as AppTool,