@universal-mcp-toolkit/server-supabase 0.1.0

package/.well-known/mcp-server.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json.schemastore.org/json",
+  "name": "supabase",
+  "title": "Supabase MCP Server",
+  "description": "Database, auth, storage, and function tools for Supabase.",
+  "version": "0.1.0",
+  "transports": [
+    "stdio",
+    "http+sse"
+  ],
+  "authentication": {
+    "mode": "environment-variables",
+    "required": [
+      "SUPABASE_URL",
+      "SUPABASE_KEY"
+    ]
+  },
+  "capabilities": {
+    "tools": true,
+    "resources": true,
+    "prompts": true
+  },
+  "packageName": "@universal-mcp-toolkit/server-supabase",
+  "homepage": "https://github.com/universal-mcp-toolkit/universal-mcp-toolkit#readme",
+  "tools": [
+    "list-tables",
+    "query-table",
+    "list-storage-buckets"
+  ],
+  "resources": [
+    "project-overview"
+  ],
+  "prompts": [
+    "incident-response"
+  ]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 universal-mcp-toolkit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,77 @@
+import * as _universal_mcp_toolkit_core from '@universal-mcp-toolkit/core';
+import { ToolkitServer, ToolkitServerMetadata } from '@universal-mcp-toolkit/core';
+import { z } from 'zod';
+
+type JsonPrimitive = boolean | number | string | null;
+interface JsonObject {
+    [key: string]: JsonValue;
+}
+type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+declare const supabaseFilterValueSchema: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>]>;
+declare const supabaseEnvShape: {
+    SUPABASE_URL: z.ZodString;
+    SUPABASE_KEY: z.ZodString;
+    SUPABASE_SCHEMA: z.ZodDefault<z.ZodString>;
+    SUPABASE_MAX_ROWS: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    SUPABASE_BUCKET_LIMIT: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+};
+type SupabaseEnv = z.infer<z.ZodObject<typeof supabaseEnvShape>>;
+type SupabaseFilterValue = z.infer<typeof supabaseFilterValueSchema>;
+interface SupabaseFilter {
+    column: string;
+    operator: "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "like" | "ilike" | "in" | "is";
+    value: SupabaseFilterValue;
+}
+interface SupabaseTableSummary {
+    schema: string;
+    name: string;
+    type: string;
+}
+interface SupabaseBucketSummary {
+    id: string;
+    name: string;
+    public: boolean;
+    fileSizeLimit: number | null;
+    allowedMimeTypes: string[] | null;
+    createdAt: string | null;
+}
+interface SupabaseClient {
+    listTables(input: {
+        schema: string;
+        limit: number;
+    }): Promise<{
+        schema: string;
+        tables: SupabaseTableSummary[];
+    }>;
+    queryTable(input: {
+        schema: string;
+        table: string;
+        select: string;
+        filters: readonly SupabaseFilter[];
+        limit: number;
+        orderBy?: string;
+        ascending: boolean;
+    }): Promise<{
+        schema: string;
+        table: string;
+        rows: JsonObject[];
+    }>;
+    listStorageBuckets(input: {
+        limit: number;
+    }): Promise<SupabaseBucketSummary[]>;
+}
+declare const metadata: ToolkitServerMetadata;
+declare const serverCard: _universal_mcp_toolkit_core.ToolkitServerCard;
+declare class SupabaseServer extends ToolkitServer {
+    private readonly env;
+    private readonly client;
+    constructor(env: SupabaseEnv, client: SupabaseClient);
+}
+interface CreateSupabaseServerOptions {
+    env?: SupabaseEnv;
+    client?: SupabaseClient;
+}
+declare function createServer(options?: CreateSupabaseServerOptions): SupabaseServer;
+declare function main(argv?: readonly string[]): Promise<void>;
+
+export { type CreateSupabaseServerOptions, type JsonObject, type JsonValue, type SupabaseBucketSummary, type SupabaseClient, type SupabaseEnv, type SupabaseFilter, type SupabaseFilterValue, SupabaseServer, type SupabaseTableSummary, createServer, main, metadata, serverCard };

package/dist/index.js

@@ -0,0 +1,394 @@
+// src/index.ts
+import { pathToFileURL } from "url";
+import {
+  HttpServiceClient,
+  ToolkitServer,
+  ValidationError,
+  createLogger,
+  createServerCard,
+  defineTool,
+  loadEnv,
+  parseRuntimeOptions,
+  runToolkitServer
+} from "@universal-mcp-toolkit/core";
+import { z } from "zod";
+var jsonValueSchema = z.lazy(
+  () => z.union([z.string(), z.number().finite(), z.boolean(), z.null(), z.array(jsonValueSchema), z.record(z.string(), jsonValueSchema)])
+);
+var jsonObjectSchema = z.record(z.string(), jsonValueSchema);
+var supabaseFilterValueSchema = z.union([
+  z.string(),
+  z.number().finite(),
+  z.boolean(),
+  z.null(),
+  z.array(z.union([z.string(), z.number().finite(), z.boolean(), z.null()]))
+]);
+var supabaseEnvShape = {
+  SUPABASE_URL: z.string().url(),
+  SUPABASE_KEY: z.string().min(1),
+  SUPABASE_SCHEMA: z.string().min(1).default("public"),
+  SUPABASE_MAX_ROWS: z.coerce.number().int().positive().max(200).default(50),
+  SUPABASE_BUCKET_LIMIT: z.coerce.number().int().positive().max(100).default(25)
+};
+var TOOL_NAMES = ["list-storage-buckets", "list-tables", "query-table"];
+var RESOURCE_NAMES = ["project-overview"];
+var PROMPT_NAMES = ["incident-response"];
+var tableRowSchema = z.object({
+  table_schema: z.string(),
+  table_name: z.string(),
+  table_type: z.string()
+}).passthrough();
+var listTablesResponseSchema = z.array(tableRowSchema);
+var queryRowsResponseSchema = z.array(jsonObjectSchema);
+var bucketRowSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  public: z.boolean().nullable().optional(),
+  file_size_limit: z.number().int().nonnegative().nullable().optional(),
+  allowed_mime_types: z.array(z.string()).nullable().optional(),
+  created_at: z.string().nullable().optional()
+}).passthrough();
+var listBucketsResponseSchema = z.array(bucketRowSchema);
+var metadata = {
+  id: "supabase",
+  title: "Supabase MCP Server",
+  description: "Database, auth, storage, and function tools for Supabase.",
+  version: "0.1.0",
+  packageName: "@universal-mcp-toolkit/server-supabase",
+  homepage: "https://github.com/universal-mcp-toolkit/universal-mcp-toolkit#readme",
+  repositoryUrl: "https://github.com/universal-mcp-toolkit/universal-mcp-toolkit",
+  envVarNames: ["SUPABASE_URL", "SUPABASE_KEY"],
+  transports: ["stdio", "sse"],
+  toolNames: TOOL_NAMES,
+  resourceNames: RESOURCE_NAMES,
+  promptNames: PROMPT_NAMES
+};
+var serverCard = createServerCard(metadata);
+function getProjectReference(urlValue) {
+  try {
+    const url = new URL(urlValue);
+    return url.hostname.split(".")[0] ?? url.hostname;
+  } catch {
+    return urlValue;
+  }
+}
+function formatScalarFilterValue(value) {
+  if (value === null) {
+    return "null";
+  }
+  if (typeof value === "boolean") {
+    return value ? "true" : "false";
+  }
+  return String(value);
+}
+function formatInMember(value) {
+  if (value === null) {
+    return "null";
+  }
+  if (typeof value === "string") {
+    const escaped = value.replace(/\\/gu, "\\\\").replace(/"/gu, '\\"');
+    return `"${escaped}"`;
+  }
+  if (typeof value === "boolean") {
+    return value ? "true" : "false";
+  }
+  return String(value);
+}
+function formatFilterExpression(filter) {
+  if (filter.operator === "in") {
+    if (!Array.isArray(filter.value)) {
+      throw new ValidationError("Supabase 'in' filters require an array value.");
+    }
+    return `in.(${filter.value.map((value) => formatInMember(value)).join(",")})`;
+  }
+  if (Array.isArray(filter.value)) {
+    throw new ValidationError(`Supabase filter operator '${filter.operator}' does not accept array values.`);
+  }
+  return `${filter.operator}.${formatScalarFilterValue(filter.value)}`;
+}
+var SupabaseRestClient = class extends HttpServiceClient {
+  constructor(env) {
+    super({
+      serviceName: "Supabase",
+      baseUrl: env.SUPABASE_URL,
+      logger: createLogger({ name: metadata.packageName }),
+      defaultHeaders: () => ({
+        apikey: env.SUPABASE_KEY,
+        authorization: `Bearer ${env.SUPABASE_KEY}`
+      })
+    });
+    this.env = env;
+  }
+  async listTables(input) {
+    const rows = await this.getJson("/rest/v1/tables", listTablesResponseSchema, {
+      headers: {
+        "accept-profile": "information_schema"
+      },
+      query: {
+        select: "table_schema,table_name,table_type",
+        table_schema: `eq.${input.schema}`,
+        order: "table_name.asc",
+        limit: input.limit
+      }
+    });
+    return {
+      schema: input.schema,
+      tables: rows.map((row) => ({
+        schema: row.table_schema,
+        name: row.table_name,
+        type: row.table_type
+      }))
+    };
+  }
+  async queryTable(input) {
+    const query = {
+      select: input.select,
+      limit: input.limit
+    };
+    if (input.orderBy) {
+      query.order = `${input.orderBy}.${input.ascending ? "asc" : "desc"}`;
+    }
+    for (const filter of input.filters) {
+      query[filter.column] = formatFilterExpression(filter);
+    }
+    const rows = await this.getJson(`/rest/v1/${encodeURIComponent(input.table)}`, queryRowsResponseSchema, {
+      headers: {
+        "accept-profile": input.schema
+      },
+      query
+    });
+    return {
+      schema: input.schema,
+      table: input.table,
+      rows
+    };
+  }
+  async listStorageBuckets(input) {
+    const rows = await this.getJson("/storage/v1/bucket", listBucketsResponseSchema);
+    return rows.slice(0, input.limit).map((row) => ({
+      id: row.id,
+      name: row.name,
+      public: row.public ?? false,
+      fileSizeLimit: row.file_size_limit ?? null,
+      allowedMimeTypes: row.allowed_mime_types ?? null,
+      createdAt: row.created_at ?? null
+    }));
+  }
+};
+var SupabaseServer = class extends ToolkitServer {
+  constructor(env, client) {
+    super(metadata);
+    this.env = env;
+    this.client = client;
+    this.registerTool(
+      defineTool({
+        name: "list-tables",
+        title: "List Supabase tables",
+        description: "List tables exposed through the Supabase REST API for a given schema.",
+        inputSchema: {
+          schema: z.string().min(1).default(this.env.SUPABASE_SCHEMA),
+          limit: z.number().int().positive().max(100).default(25)
+        },
+        outputSchema: {
+          schema: z.string(),
+          tableCount: z.number().int().nonnegative(),
+          tables: z.array(
+            z.object({
+              schema: z.string(),
+              name: z.string(),
+              type: z.string()
+            })
+          )
+        },
+        handler: async ({ limit, schema }, context) => {
+          const cappedLimit = Math.min(limit, this.env.SUPABASE_MAX_ROWS);
+          await context.log("info", `Listing Supabase tables for schema '${schema}'.`);
+          const result = await this.client.listTables({
+            schema,
+            limit: cappedLimit
+          });
+          return {
+            schema: result.schema,
+            tableCount: result.tables.length,
+            tables: result.tables
+          };
+        },
+        renderText: (output) => `${output.tableCount} tables found in Supabase schema ${output.schema}.`
+      })
+    );
+    this.registerTool(
+      defineTool({
+        name: "query-table",
+        title: "Query Supabase table",
+        description: "Query a Supabase table with select, filters, ordering, and row limits.",
+        inputSchema: {
+          schema: z.string().min(1).default(this.env.SUPABASE_SCHEMA),
+          table: z.string().min(1),
+          select: z.string().min(1).default("*"),
+          filters: z.array(
+            z.object({
+              column: z.string().min(1),
+              operator: z.enum(["eq", "neq", "gt", "gte", "lt", "lte", "like", "ilike", "in", "is"]),
+              value: supabaseFilterValueSchema
+            })
+          ).default([]),
+          limit: z.number().int().positive().max(200).default(25),
+          orderBy: z.string().min(1).optional(),
+          ascending: z.boolean().default(true)
+        },
+        outputSchema: {
+          schema: z.string(),
+          table: z.string(),
+          rowCount: z.number().int().nonnegative(),
+          rows: z.array(jsonObjectSchema)
+        },
+        handler: async ({ ascending, filters, limit, orderBy, schema, select, table }, context) => {
+          const cappedLimit = Math.min(limit, this.env.SUPABASE_MAX_ROWS);
+          await context.log("info", `Querying Supabase table ${schema}.${table}.`);
+          const request = {
+            schema,
+            table,
+            select,
+            filters,
+            limit: cappedLimit,
+            ascending
+          };
+          if (orderBy) {
+            request.orderBy = orderBy;
+          }
+          const result = await this.client.queryTable(request);
+          return {
+            schema: result.schema,
+            table: result.table,
+            rowCount: result.rows.length,
+            rows: result.rows
+          };
+        },
+        renderText: (output) => `${output.rowCount} row(s) returned from ${output.schema}.${output.table}.`
+      })
+    );
+    this.registerTool(
+      defineTool({
+        name: "list-storage-buckets",
+        title: "List Supabase storage buckets",
+        description: "List storage buckets available in the configured Supabase project.",
+        inputSchema: {
+          limit: z.number().int().positive().max(100).default(25)
+        },
+        outputSchema: {
+          bucketCount: z.number().int().nonnegative(),
+          buckets: z.array(
+            z.object({
+              id: z.string(),
+              name: z.string(),
+              public: z.boolean(),
+              fileSizeLimit: z.number().int().nonnegative().nullable(),
+              allowedMimeTypes: z.array(z.string()).nullable(),
+              createdAt: z.string().nullable()
+            })
+          )
+        },
+        handler: async ({ limit }, context) => {
+          const cappedLimit = Math.min(limit, this.env.SUPABASE_BUCKET_LIMIT);
+          await context.log("info", "Listing Supabase storage buckets.");
+          const buckets = await this.client.listStorageBuckets({ limit: cappedLimit });
+          return {
+            bucketCount: buckets.length,
+            buckets
+          };
+        },
+        renderText: (output) => `${output.bucketCount} storage bucket(s) available in Supabase.`
+      })
+    );
+    this.registerStaticResource(
+      "project-overview",
+      "supabase://project-overview",
+      {
+        title: "Supabase project overview",
+        description: "Project-level context including schema and storage bucket visibility.",
+        mimeType: "application/json"
+      },
+      async () => {
+        const tables = await this.client.listTables({
+          schema: this.env.SUPABASE_SCHEMA,
+          limit: Math.min(this.env.SUPABASE_MAX_ROWS, 20)
+        });
+        const buckets = await this.client.listStorageBuckets({
+          limit: Math.min(this.env.SUPABASE_BUCKET_LIMIT, 20)
+        });
+        return this.createJsonResource("supabase://project-overview", {
+          projectRef: getProjectReference(this.env.SUPABASE_URL),
+          url: this.env.SUPABASE_URL,
+          schema: this.env.SUPABASE_SCHEMA,
+          maxRows: this.env.SUPABASE_MAX_ROWS,
+          tables: tables.tables,
+          buckets
+        });
+      }
+    );
+    this.registerPrompt(
+      "incident-response",
+      {
+        title: "Supabase incident response",
+        description: "Prepare a structured response plan for a Supabase production incident.",
+        argsSchema: {
+          incident: z.string().min(1),
+          impactedArea: z.string().min(1).optional(),
+          recentErrors: z.string().min(1).optional()
+        }
+      },
+      async ({ impactedArea, incident, recentErrors }) => this.createTextPrompt(
+        [
+          "Prepare a Supabase incident response plan.",
+          `Incident: ${incident}`,
+          `Impacted area: ${impactedArea ?? "unknown"}`,
+          `Recent errors: ${recentErrors ?? "none provided"}`,
+          `Primary schema: ${this.env.SUPABASE_SCHEMA}`,
+          `Project ref: ${getProjectReference(this.env.SUPABASE_URL)}`,
+          "Use the Supabase tools to:",
+          "- confirm which tables and buckets are involved",
+          "- capture a bounded sample of affected rows",
+          "- distinguish schema, data, and storage symptoms",
+          "- document the safest immediate mitigation and follow-up checks"
+        ].join("\n")
+      )
+    );
+  }
+};
+function createServer(options = {}) {
+  const env = options.env ?? loadEnv(supabaseEnvShape);
+  const client = options.client ?? new SupabaseRestClient(env);
+  return new SupabaseServer(env, client);
+}
+async function main(argv = process.argv.slice(2)) {
+  const env = loadEnv(supabaseEnvShape);
+  const runtimeOptions = parseRuntimeOptions(argv);
+  await runToolkitServer(
+    {
+      createServer: () => createServer({ env }),
+      serverCard
+    },
+    runtimeOptions
+  );
+}
+function isMainModule() {
+  const entryPoint = process.argv[1];
+  if (!entryPoint) {
+    return false;
+  }
+  return import.meta.url === pathToFileURL(entryPoint).href;
+}
+if (isMainModule()) {
+  void main().catch((error) => {
+    const message = error instanceof Error ? error.message : "Unknown startup error.";
+    console.error(`Failed to start Supabase MCP server: ${message}`);
+    process.exitCode = 1;
+  });
+}
+export {
+  SupabaseServer,
+  createServer,
+  main,
+  metadata,
+  serverCard
+};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@universal-mcp-toolkit/server-supabase",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Database, auth, storage, and function tools for Supabase.",
+  "license": "MIT",
+  "bin": {
+    "server-supabase": "./dist/index.js",
+    "umt-supabase": "./dist/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Markgatcha/universal-mcp-toolkit.git"
+  },
+  "homepage": "https://github.com/Markgatcha/universal-mcp-toolkit#readme",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    ".well-known"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "developer-tools",
+    "typescript",
+    "supabase",
+    "database",
+    "auth",
+    "storage"
+  ],
+  "dependencies": {
+    "@supabase/supabase-js": "^2.99.0",
+    "@universal-mcp-toolkit/core": "0.1.0",
+    "zod": "^4.3.6"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsx watch src/index.ts",
+    "lint": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "clean": "rimraf dist"
+  }
+}