SupaMCPBuilder

I'll analyze your requirement document and the reference materials to create a comprehensive implementation plan for the SupaMCP Server. Let me examine all the reference files first to understand the full scope. Read file: supabasejslibrary.txt Read file: mcpserverfull.txt Read file: mcptypescriptsdkreadme.md Read file: mcptypescriptsdkreadme.md Read file: supabasejslibrary.txt Read file: mcpserverfull.txt Based on my analysis of your requirement document and the reference materials, I'll create a comprehensive implementation plan for the SupaMCP Server. Let me break this down into key components: ## 🏗️ **Implementation Plan for SupaMCP Server** ### **Core Architecture Overview** The SupaMCP Server will be structured as follows: ``` SupaMCP Server ├── Configuration Layer (JSON-based) ├── Authentication Manager (Supabase Auth) ├── Tool Registry (Dynamic MCP Tools) ├── Action Executor (Supabase Operations) └── Transport Layer (MCP Protocol) ``` ### **1. 🔧 Configuration System** #### **Primary Config Structure** (`mcp.config.json`) ```json { "mcpServers": { "my-supabase-project": { "command": "npx", "args": [ "-y", "@yourorg/mcp-server-supabase-direct@latest", "--url", "https://your-project.supabase.co", "--anon-key", "eyJ...", "--email", "user@example.com", "--password", "userpassword", "--config-path", "./supabase-tools.json" // Optional external config ], "tools": [ { "name": "get-users", "description": "Fetch users from the database", "parameters": { "type": "object", "properties": { "limit": {"type": "number", "default": 10}, "email_filter": {"type": "string", "optional": true} } }, "action": { "type": "select", "table": "users", "columns": ["id", "email", "created_at"], "filters": { "email": "{{email_filter}}" }, "limit": "{{limit}}" } } ] } } } ``` #### **Extended Tool Configuration** (`supabase-tools.json`) ```json { "tools": [ { "name": "create-post", "description": "Create a new blog post", "parameters": { "type": "object", "properties": { "title": {"type": "string"}, "content": {"type": "string"}, "author_id": {"type": "string"} }, "required": ["title", "content", "author_id"] }, "action": { "type": "insert", "table": "posts", "values": { "title": "{{title}}", "content": "{{content}}", "author_id": "{{author_id}}", "created_at": "now()" } } }, { "name": "call-user-stats", "description": "Get user statistics via RPC", "parameters": { "type": "object", "properties": { "user_id": {"type": "string"} } }, "action": { "type": "rpc", "function": "get_user_stats", "args": { "user_id": "{{user_id}}" } } }, { "name": "process-image", "description": "Process image via edge function", "parameters": { "type": "object", "properties": { "image_url": {"type": "string"}, "operation": {"type": "string", "enum": ["resize", "crop", "filter"]} } }, "action": { "type": "edgeFunction", "function": "image-processor", "body": { "image_url": "{{image_url}}", "operation": "{{operation}}" } } } ], "resources": [ { "name": "user-profile", "description": "Get user profile information", "uri_template": "users://{user_id}/profile", "action": { "type": "select", "table": "users", "columns": ["id", "email", "profile"], "filters": { "id": "{{user_id}}" }, "single": true } } ] } ``` ### **2. 🔐 Authentication Architecture** #### **Multi-Mode Authentication Support** ```typescript enum AuthMode { ANONYMOUS = 'anonymous', // Uses anon key only USER_LOGIN = 'user_login', // Email/password login SERVICE_ROLE = 'service_role' // Service role key (admin) } interface AuthConfig { mode: AuthMode; anonKey: string; serviceRoleKey?: string; userCredentials?: { email: string; password: string; }; } ``` #### **Authentication Flow** 1. **Initialize with Anon Key**: Always start with anonymous client 2. **User Login** (if credentials provided): - Call `auth.signInWithPassword()` - Get `access_token` - Reinitialize client with token 3. **Service Role** (if service key provided): - Initialize separate admin client for privileged operations ### **3. 🛠️ Supported Tool Actions** #### **Database Operations** (via Supabase JS SDK) | Action Type | Supabase SDK Method | Parameters | Example | |-------------|-------------------|------------|---------| | `select` | `from().select()` | table, columns, filters, limit, offset | Query users table | | `insert` | `from().insert()` | table, values, onConflict | Create new records | | `update` | `from().update()` | table, values, filters | Update existing records | | `delete` | `from().delete()` | table, filters | Delete records | | `upsert` | `from().upsert()` | table, values, onConflict | Insert or update | | `rpc` | `rpc()` | function, args | Call database functions | | `edgeFunction` | Custom HTTP call | function, body, headers | Call edge functions | #### **Advanced Query Features** - **Foreign Key Joins**: Support for nested selects - **Filtering**: eq, neq, gt, lt, like, in, etc. - **Ordering**: order by multiple columns - **Pagination**: limit/offset with count - **JSON Operations**: Query JSON columns - **Full-text Search**: Using built-in search ### **4. 📡 MCP Server Implementation** #### **Core Server Structure** ```typescript import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { createClient, SupabaseClient } from '@supabase/supabase-js'; class SupaMCPServer { private mcpServer: McpServer; private supabaseClient: SupabaseClient; private config: SupabaseToolConfig[]; constructor(private authConfig: AuthConfig) { this.mcpServer = new McpServer({ name: "supabase-mcp-server", version: "1.0.0" }); } async initialize() { // 1. Initialize Supabase client await this.initializeSupabaseClient(); // 2. Load tool configurations await this.loadToolConfigurations(); // 3. Register MCP tools dynamically await this.registerMCPTools(); // 4. Register MCP resources await this.registerMCPResources(); } private async registerMCPTools() { for (const toolConfig of this.config) { await this.mcpServer.registerTool( toolConfig.name, { title: toolConfig.description, description: toolConfig.description, inputSchema: toolConfig.parameters }, async (params) => await this.executeToolAction(toolConfig, params) ); } } } ``` #### **Tool Executor System** ```typescript class ActionExecutor { constructor(private supabase: SupabaseClient) {} async executeAction(action: ToolAction, params: Record<string, any>) { const resolvedAction = this.resolveTemplates(action, params); switch (action.type) { case 'select': return await this.executeSelect(resolvedAction); case 'insert': return await this.executeInsert(resolvedAction); case 'update': return await this.executeUpdate(resolvedAction); case 'rpc': return await this.executeRPC(resolvedAction); case 'edgeFunction': return await this.executeEdgeFunction(resolvedAction); default: throw new Error(`Unsupported action type: ${action.type}`); } } private async executeSelect(action: SelectAction) { let query = this.supabase .from(action.table) .select(action.columns?.join(',') || '*'); // Apply filters if (action.filters) { for (const [column, value] of Object.entries(action.filters)) { if (value !== undefined) { query = query.eq(column, value); } } } // Apply pagination if (action.limit) query = query.limit(action.limit); if (action.offset) query = query.range(action.offset, action.offset + (action.limit || 10)); const { data, error } = action.single ? await query.single() : await query; if (error) throw error; return this.formatMCPResponse(data); } } ``` ### **5. 🚀 Feature Set Summary** #### **Core Features** - ✅ **JSON-based Configuration**: Runtime tool definition - ✅ **Multi-auth Support**: Anonymous, user login, service role - ✅ **Dynamic Tool Registration**: Auto-generate MCP tools from config - ✅ **Full CRUD Operations**: Select, insert, update, delete via Supabase SDK - ✅ **RPC Support**: Call Postgres functions - ✅ **Edge Function Integration**: HTTP calls to Supabase edge functions - ✅ **Resource Support**: Expose data as MCP resources - ✅ **Template System**: Parameter substitution with `{{param}}` syntax #### **Advanced Features** - ✅ **Foreign Key Queries**: Nested table selections - ✅ **Advanced Filtering**: Full Supabase filter support (eq, gt, like, in, etc.) - ✅ **JSON Column Queries**: Query JSON data structures - ✅ **Pagination Support**: Limit/offset with optional count - ✅ **Schema Switching**: Multi-schema support - ✅ **Row Level Security**: Automatic RLS enforcement with user auth - ✅ **Bulk Operations**: Insert/update multiple records - ✅ **Error Handling**: Proper MCP error responses - ✅ **Logging Integration**: Comprehensive operation logging #### **Planned Enhancements** - 🔄 **Real-time Subscriptions**: WebSocket support for live data - 🔄 **Storage Operations**: File upload/download via Supabase Storage - 🔄 **Migration Tools**: Schema introspection and tool auto-generation - 🔄 **Connection Pooling**: Optimize database connections - 🔄 **Caching Layer**: Redis integration for performance - 🔄 **Web UI**: Visual tool configuration interface ### **6. 💻 CLI Usage & Deployment** #### **NPM Package Structure** ```bash @yourorg/mcp-server-supabase-direct/ ├── dist/ # Compiled TypeScript ├── src/ │ ├── server.ts # Main MCP server │ ├── auth.ts # Authentication manager │ ├── executor.ts # Action executor │ └── types.ts # Type definitions ├── bin/ │ └── server.js # CLI entry point └── package.json # Package configuration ``` #### **CLI Command** ```bash npx @yourorg/mcp-server-supabase-direct \ --url https://your-project.supabase.co \ --anon-key eyJ... \ --email user@example.com \ --password password \ --config-path ./tools.json ``` This architecture provides a comprehensive, production-ready MCP server that leverages the full power of the Supabase ecosystem while maintaining the flexibility and standardization of the MCP protocol. The design supports both simple use cases (basic CRUD operations) and complex scenarios (multi-table joins, RPC calls, edge functions) through a declarative configuration approach. Would you like me to dive deeper into any specific aspect of this implementation plan or start working on the actual code structure?