@aliyun-rds/supabase-mcp-server 1.0.2 → 1.0.3

package/README.md

@@ -56,7 +56,7 @@ For example, when you ask an AI assistant "List all tables in my database", it w
 The easiest way to use this server is via npx, which requires no installation:
 
 ```bash
-npx @lemontreen/rds-supabase-mcp-server --url http://localhost:8000 --anon-key YOUR_ANON_KEY
+npx @aliyun-rds/supabase-mcp-server --url http://localhost:8000 --anon-key YOUR_ANON_KEY
 ```
 
 ### Method 2: Installing via Smithery
@@ -72,7 +72,7 @@ npx -y @smithery/cli install @HenkDz/selfhosted-supabase-mcp --client claude
 Install the package globally:
 
 ```bash
-npm install -g @lemontreen/rds-supabase-mcp-server
+npm install -g @aliyun-rds/supabase-mcp-server
 supabase-mcp --url http://localhost:8000 --anon-key YOUR_ANON_KEY
 ```
 
@@ -118,11 +118,39 @@ The server requires configuration details for your Supabase instance. These can
 *   `--db-url <url>` or `DATABASE_URL=<url>`: The direct PostgreSQL connection string for your Supabase database (e.g., `postgresql://postgres:password@localhost:5432/postgres`). Required for tools needing direct database access or transactions (`apply_migration`, Auth tools, Storage tools, querying `pg_catalog`, etc.).
 *   `--jwt-secret <secret>` or `SUPABASE_AUTH_JWT_SECRET=<secret>`: Your Supabase project's JWT secret. Needed for tools like `verify_jwt_secret`.
 *   `--tools-config <path>`: Path to a JSON file specifying which tools to enable (whitelist). If omitted, all tools defined in the server are enabled. The file should have the format `{"enabledTools": ["tool_name_1", "tool_name_2"]}`.
+*   `--enable-rag-agent` or `ENABLE_RAG_AGENT=true`: Enable RAG Agent MCP integration. When enabled, this server will connect to a rag-agent MCP server and expose its tools alongside the Supabase tools. The host and port are extracted from `--url`, and `--anon-key` is used as the API key for rag-agent.
+
+### RAG Agent Integration
+
+This server can integrate with [rag-agent-mcp](https://pypi.org/project/rag-agent-mcp/) to provide RAG (Retrieval-Augmented Generation) capabilities alongside your Supabase database tools.
+
+**How it works:**
+- When `--enable-rag-agent` is set, the server automatically connects to a rag-agent MCP server
+- The host and port are extracted from your `--url` parameter (e.g., `http://8.161.141.95:80` → host: `8.161.141.95`, port: `80`)
+- The `--anon-key` value is used as the API key for authenticating with rag-agent
+- All rag-agent tools are prefixed with `rag_` to avoid naming conflicts (e.g., `rag_search`, `rag_index`)
+
+**Example configuration:**
+```bash
+npx @aliyun-rds/supabase-mcp-server \
+  --url http://8.161.141.95:80 \
+  --anon-key "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." \
+  --enable-rag-agent
+```
+
+**Requirements:**
+- `uvx` must be installed on your system
+- `rag-agent-mcp` package must be available via `uvx`
+- The rag-agent service must be running at the specified host and port
 
 ### Important Notes:
 
 *   **`execute_sql` Helper Function:** Many tools rely on a `public.execute_sql` function within your Supabase database for secure and efficient SQL execution via RPC. The server attempts to check for this function on startup. If it's missing *and* a `service-key` (or `SUPABASE_SERVICE_ROLE_KEY`) *and* `db-url` (or `DATABASE_URL`) are provided, it will attempt to create the function and grant necessary permissions. If creation fails or keys aren't provided, tools relying solely on RPC may fail.
 *   **Direct Database Access:** Tools interacting directly with privileged schemas (`auth`, `storage`) or system catalogs (`pg_catalog`) generally require the `DATABASE_URL` to be configured for a direct `pg` connection.
+*   **Database URL Special Characters:** If your database password or username contains special characters (such as `#`, `$`, etc.), they need to be properly URL encoded to prevent connection issues. The server automatically handles common special characters in the database URL:
+    *   `#` is automatically encoded as `%23`
+    *   `$` is automatically encoded as `%24`
+    *   Note: The `@` symbol is not encoded as it serves as a delimiter in the URL between credentials and hostname
 
 ## Using with AI Assistant Tools
 
@@ -134,10 +162,10 @@ The server requires configuration details for your Supabase instance. These can
     ```json
     {
       "mcpServers": {
-        "selfhosted-supabase": { 
+        "selfhosted-supabase": {
           "command": "npx",
           "args": [
-            "@lemontreen/rds-supabase-mcp-server",
+            "@aliyun-rds/supabase-mcp-server",
             "--url",
             "<your-supabase-url>", // e.g., "http://localhost:8000"
             "--anon-key",
@@ -151,13 +179,47 @@ The server requires configuration details for your Supabase instance. These can
             "<your-jwt-secret>",
             // Optional - Whitelist specific tools
             "--tools-config",
-            "<path-to-tools-config.json>"
+            "<path-to-tools-config.json>",
+            // Optional - Enable RAG Agent integration
+            "--enable-rag-agent"
           ]
         }
       }
     }
     ```
 
+**Example with RAG Agent integration:**
+
+If you want to use this server with both Supabase and RAG Agent tools, configure it like this:
+
+```json
+{
+  "mcpServers": {
+    "remote-selfhosted-supabase": {
+      "command": "ssh",
+      "args": [
+        "root@8.161.141.95",
+        "cd /root/selfhosted-supabase-mcp && node dist/index.js",
+        "--url",
+        "http://8.161.141.95:80",
+        "--anon-key",
+        "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJvbGUiOiJhbm9uIiwiaWF0IjoxNzYwNDIwNjM5LCJleHAiOjEzMjcxMDYwNjM5fQ.ZV2geUEdh096snzWaCnKXFTyQbyJxLbur8zZooZkY88",
+        "--service-key",
+        "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJvbGUiOiJzZXJ2aWNlX3JvbGUiLCJpYXQiOjE3NjA0MjA2MzksImV4cCI6MTMyNzEwNjA2Mzl9.4wqKCLqJqQqQqQqQqQqQqQqQqQqQqQqQqQqQqQqQqQQ",
+        "--enable-rag-agent"
+      ]
+    }
+  }
+}
+```
+
+In this configuration:
+- The server runs on a remote machine via SSH
+- It connects to Supabase at `http://8.161.141.95:80`
+- RAG Agent integration is enabled and will connect to the same host:port
+- Both Supabase and RAG Agent tools will be available to your AI assistant
+    ```
+
 ### Claude for Desktop
 
 For Claude Desktop, you can add the following to your configuration:

package/dist/index.js

@@ -167,6 +167,25 @@ var SelfhostedSupabaseClient = class _SelfhostedSupabaseClient {
       client?.release();
     }
   }
+  /**
+   * Encodes special characters in database URL to prevent parsing errors
+   * Handles characters like #, $ that may cause issues with pg library
+   */
+  encodeDatabaseUrl(url) {
+    try {
+      const parsedUrl = new URL(url);
+      if (parsedUrl.username) {
+        parsedUrl.username = encodeURIComponent(parsedUrl.username);
+      }
+      if (parsedUrl.password) {
+        parsedUrl.password = encodeURIComponent(parsedUrl.password);
+      }
+      return parsedUrl.toString();
+    } catch (error) {
+      console.error("Database URL contains special characters. Applying basic encoding (excluding @).");
+      return url.replace(/#/g, "%23").replace(/\$/g, "%24");
+    }
+  }
   /**
    * Ensures the pg connection pool is initialized.
    * Should be called before accessing this.pgPool.
@@ -177,7 +196,8 @@ var SelfhostedSupabaseClient = class _SelfhostedSupabaseClient {
       throw new Error("DATABASE_URL is not configured. Cannot initialize pg pool.");
     }
     console.error("Initializing pg pool...");
-    this.pgPool = new Pool({ connectionString: this.options.databaseUrl });
+    const encodedDbUrl = this.encodeDatabaseUrl(this.options.databaseUrl);
+    this.pgPool = new Pool({ connectionString: encodedDbUrl });
     this.pgPool.on("error", (err, client) => {
       console.error("PG Pool Error: Unexpected error on idle client", err);
     });
@@ -1485,7 +1505,7 @@ var updateAuthUserTool = {
 };
 
 // src/index.ts
-import { z as z23 } from "zod";
+import { z as z24 } from "zod";
 
 // src/tools/list_storage_buckets.ts
 import { z as z20 } from "zod";
@@ -1695,9 +1715,157 @@ var list_realtime_publications_default = listRealtimePublicationsTool;
 // src/index.ts
 import * as fs from "node:fs";
 import * as path from "node:path";
+
+// src/integrations/rag-agent-client.ts
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+var RagAgentClient = class {
+  config;
+  client = null;
+  tools = [];
+  constructor(config) {
+    this.config = config;
+  }
+  /**
+   * Initialize connection to rag-agent MCP server and fetch tools
+   */
+  async initialize() {
+    console.error("Initializing RAG Agent MCP client...");
+    try {
+      this.client = new Client(
+        {
+          name: "supabase-mcp-rag-agent-client",
+          version: "1.0.0"
+        },
+        {
+          capabilities: {}
+        }
+      );
+      const env = {};
+      for (const [key, value] of Object.entries(process.env)) {
+        if (value !== void 0 && !["http_proxy", "https_proxy", "HTTP_PROXY", "HTTPS_PROXY", "all_proxy", "ALL_PROXY", "no_proxy", "NO_PROXY"].includes(key)) {
+          env[key] = value;
+        }
+      }
+      env.NO_PROXY = "*";
+      env.no_proxy = "*";
+      const transport = new StdioClientTransport({
+        command: "uvx",
+        args: [
+          "--from",
+          "rag-agent-mcp",
+          "rag-agent",
+          "--host",
+          this.config.host,
+          "--port",
+          this.config.port.toString(),
+          "--api-key",
+          this.config.apiKey
+        ],
+        env
+      });
+      await this.client.connect(transport);
+      console.error("Connected to RAG Agent MCP server");
+      const response = await this.client.listTools();
+      this.tools = response.tools.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema
+      }));
+      console.error(`Loaded ${this.tools.length} tools from RAG Agent MCP server`);
+      console.error(`RAG Agent tools: ${this.tools.map((t) => t.name).join(", ")}`);
+    } catch (error) {
+      console.error("Failed to initialize RAG Agent MCP client:", error);
+      throw error;
+    }
+  }
+  /**
+   * Get the list of available tools from rag-agent
+   */
+  getTools() {
+    return this.tools;
+  }
+  /**
+   * Call a tool on the rag-agent MCP server
+   */
+  async callTool(name, args) {
+    if (!this.client) {
+      throw new Error("RAG Agent client not initialized");
+    }
+    try {
+      const response = await this.client.callTool({
+        name,
+        arguments: args
+      });
+      if (response.content && Array.isArray(response.content)) {
+        const textContent = response.content.filter((item) => item.type === "text").map((item) => "text" in item ? item.text : "").join("\n");
+        try {
+          return JSON.parse(textContent);
+        } catch {
+          return textContent;
+        }
+      }
+      return response;
+    } catch (error) {
+      console.error(`Error calling RAG Agent tool ${name}:`, error);
+      throw error;
+    }
+  }
+  /**
+   * Close the connection to rag-agent MCP server
+   */
+  async close() {
+    if (this.client) {
+      await this.client.close();
+      this.client = null;
+      console.error("RAG Agent MCP client closed");
+    }
+  }
+};
+async function createRagAgentClient(config) {
+  const client = new RagAgentClient(config);
+  await client.initialize();
+  return client;
+}
+
+// src/integrations/rag-agent-tools.ts
+import { z as z23 } from "zod";
+function wrapRagAgentTool(ragTool, ragClient) {
+  const inputSchema2 = z23.any();
+  return {
+    name: `rag_${ragTool.name}`,
+    // Prefix with 'rag_' to avoid naming conflicts
+    description: ragTool.description || `RAG Agent tool: ${ragTool.name}`,
+    inputSchema: inputSchema2,
+    mcpInputSchema: ragTool.inputSchema,
+    outputSchema: z23.any(),
+    execute: async (input, context) => {
+      context.log(`Calling RAG Agent tool: ${ragTool.name}`, "info");
+      try {
+        const result = await ragClient.callTool(ragTool.name, input);
+        return result;
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        context.log(`Error calling RAG Agent tool ${ragTool.name}: ${errorMessage}`, "error");
+        throw new Error(`RAG Agent tool error: ${errorMessage}`);
+      }
+    }
+  };
+}
+function wrapAllRagAgentTools(ragClient) {
+  const tools = ragClient.getTools();
+  const wrappedTools = {};
+  for (const tool of tools) {
+    const wrapped = wrapRagAgentTool(tool, ragClient);
+    wrappedTools[wrapped.name] = wrapped;
+  }
+  return wrappedTools;
+}
+
+// src/index.ts
 async function main() {
   const program = new Command();
-  program.name("self-hosted-supabase-mcp").description("MCP Server for self-hosted Supabase instances").option("--url <url>", "Supabase project URL", process.env.SUPABASE_URL).option("--anon-key <key>", "Supabase anonymous key", process.env.SUPABASE_ANON_KEY).option("--service-key <key>", "Supabase service role key (optional)", process.env.SUPABASE_SERVICE_ROLE_KEY).option("--db-url <url>", "Direct database connection string (optional, for pg fallback)", process.env.DATABASE_URL).option("--jwt-secret <secret>", "Supabase JWT secret (optional, needed for some tools)", process.env.SUPABASE_AUTH_JWT_SECRET).option("--workspace-path <path>", "Workspace root path (for file operations)", process.cwd()).option("--tools-config <path>", 'Path to a JSON file specifying which tools to enable (e.g., { "enabledTools": ["tool1", "tool2"] }). If omitted, all tools are enabled.').parse(process.argv);
+  program.name("self-hosted-supabase-mcp").description("MCP Server for self-hosted Supabase instances").option("--url <url>", "Supabase project URL", process.env.SUPABASE_URL).option("--anon-key <key>", "Supabase anonymous key", process.env.SUPABASE_ANON_KEY).option("--service-key <key>", "Supabase service role key (optional)", process.env.SUPABASE_SERVICE_ROLE_KEY).option("--db-url <url>", "Direct database connection string (optional, for pg fallback)", process.env.DATABASE_URL).option("--jwt-secret <secret>", "Supabase JWT secret (optional, needed for some tools)", process.env.SUPABASE_AUTH_JWT_SECRET).option("--workspace-path <path>", "Workspace root path (for file operations)", process.cwd()).option("--tools-config <path>", 'Path to a JSON file specifying which tools to enable (e.g., { "enabledTools": ["tool1", "tool2"] }). If omitted, all tools are enabled.').option("--enable-rag-agent", "Enable RAG Agent MCP integration (uses --url host:port and --anon-key as API key)", process.env.ENABLE_RAG_AGENT === "true").parse(process.argv);
   const options = program.opts();
   if (!options.url) {
     console.error("Error: Supabase URL is required. Use --url or SUPABASE_URL.");
@@ -1717,6 +1885,24 @@ async function main() {
       jwtSecret: options.jwtSecret
     });
     console.error("Supabase client initialized successfully.");
+    let ragAgentClient = null;
+    if (options.enableRagAgent) {
+      try {
+        console.error("RAG Agent integration enabled, initializing...");
+        const urlObj = new URL(options.url);
+        const host = urlObj.hostname;
+        const port = urlObj.port ? parseInt(urlObj.port, 10) : urlObj.protocol === "https:" ? 443 : 80;
+        ragAgentClient = await createRagAgentClient({
+          host,
+          port,
+          apiKey: options.anonKey
+        });
+        console.error("RAG Agent client initialized successfully.");
+      } catch (error) {
+        console.error("Failed to initialize RAG Agent client:", error);
+        console.error("Continuing without RAG Agent integration...");
+      }
+    }
     const availableTools = {
       // Cast here assumes tools will implement AppTool structure
       [listTablesTool.name]: listTablesTool,
@@ -1741,6 +1927,11 @@ async function main() {
       [list_storage_objects_default.name]: list_storage_objects_default,
       [list_realtime_publications_default.name]: list_realtime_publications_default
     };
+    if (ragAgentClient) {
+      const ragTools = wrapAllRagAgentTools(ragAgentClient);
+      Object.assign(availableTools, ragTools);
+      console.error(`Added ${Object.keys(ragTools).length} RAG Agent tools to available tools.`);
+    }
     let registeredTools = { ...availableTools };
     const toolsConfigPath = options.toolsConfig;
     let enabledToolNames = null;
@@ -1847,7 +2038,7 @@ async function main() {
       } catch (error) {
         console.error(`Error executing tool ${toolName}:`, error);
         let errorMessage = `Error executing tool ${toolName}: `;
-        if (error instanceof z23.ZodError) {
+        if (error instanceof z24.ZodError) {
           errorMessage += `Input validation failed: ${error.errors.map((e) => `${e.path.join(".")}: ${e.message}`).join(", ")}`;
         } else if (error instanceof Error) {
           errorMessage += error.message;
@@ -1864,6 +2055,20 @@ async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error("MCP Server connected to stdio.");
+    const cleanup = async () => {
+      console.error("Shutting down...");
+      if (ragAgentClient) {
+        await ragAgentClient.close();
+      }
+    };
+    process.on("SIGINT", async () => {
+      await cleanup();
+      process.exit(0);
+    });
+    process.on("SIGTERM", async () => {
+      await cleanup();
+      process.exit(0);
+    });
   } catch (error) {
     console.error("Failed to initialize or start the MCP server:", error);
     throw error;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliyun-rds/supabase-mcp-server",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "MCP (Model Context Protocol) server for self-hosted Supabase instances. Allows AI assistants to interact with your self-hosted Supabase database.",
   "main": "dist/index.js",
   "bin": {
@@ -47,4 +47,4 @@
   "engines": {
     "node": ">=18"
   }
-}
+}