Self-Hosted Supabase MCP Server

Instructions

Implementation Reference

• src/tools/list_migrations.ts:31-51 (handler)

  The main handler function that executes the tool logic: queries the database for applied migrations using a SQL statement and processes the response.

  execute: async (input: ListMigrationsInput, context: ToolContext) => {
      const client = context.selfhostedClient;
  
      // SQL to query the Supabase migrations table
      const listMigrationsSql = `
          SELECT
              version,
              name,
              inserted_at
          FROM
              supabase_migrations.schema_migrations
          ORDER BY
              version
      `;
  
      // This table might not exist if migrations haven't been run
      // The RPC call will handle the error, which handleSqlResponse will catch
      const result = await executeSqlWithFallback(client, listMigrationsSql, true);
  
      return handleSqlResponse(result, ListMigrationsOutputSchema);
  },

• src/tools/list_migrations.ts:7-11 (schema)

  Zod schema defining the output structure: an array of migration objects containing version, name, and inserted_at.

  const ListMigrationsOutputSchema = z.array(z.object({
      version: z.string(),
      name: z.string(),
      inserted_at: z.string(), // Keep as string from DB
  }));

• src/tools/list_migrations.ts:14-15 (schema)

  Zod schema for input (empty object since no parameters required) and inferred type.

  const ListMigrationsInputSchema = z.object({});
  type ListMigrationsInput = z.infer<typeof ListMigrationsInputSchema>;

• src/tools/list_migrations.ts:25-52 (registration)

  The tool object definition including name, description, schemas, and execute handler, exported for use in the MCP server.

  export const listMigrationsTool = {
      name: 'list_migrations',
      description: 'Lists applied database migrations recorded in supabase_migrations.schema_migrations table.',
      inputSchema: ListMigrationsInputSchema,
      mcpInputSchema: mcpInputSchema,
      outputSchema: ListMigrationsOutputSchema,
      execute: async (input: ListMigrationsInput, context: ToolContext) => {
          const client = context.selfhostedClient;
  
          // SQL to query the Supabase migrations table
          const listMigrationsSql = `
              SELECT
                  version,
                  name,
                  inserted_at
              FROM
                  supabase_migrations.schema_migrations
              ORDER BY
                  version
          `;
  
          // This table might not exist if migrations haven't been run
          // The RPC call will handle the error, which handleSqlResponse will catch
          const result = await executeSqlWithFallback(client, listMigrationsSql, true);
  
          return handleSqlResponse(result, ListMigrationsOutputSchema);
      },
  }; 

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

  Registers the listMigrationsTool in the availableTools map used to populate MCP server capabilities.

  [listMigrationsTool.name]: listMigrationsTool as AppTool,