# sentry01/supabase-mcp-for-copilot architecture

> Architecture diagram of the GitHub repository sentry01/supabase-mcp-for-copilot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sentry01/supabase-mcp-for-copilot
- Repository: https://github.com/sentry01/supabase-mcp-for-copilot

## Overview

##### Project type and purpose
- This is a middleware “Model Context Protocol (MCP) Supabase Server” written in Node.js.
- Purpose: act as a bridge between AI assistants (e.g., GitHub Copilot) and a Supabase database, exposing schema & safe query‐execution over an MCP-compatible server.

##### File structure
- Top‐level files:
- src/ – application code
– index.js: server bootstrap
– supabase-client.js: client factory
– schema-provider.js: fetch DB metadata
– query-handler.js: validate & run queries
– config.js: env-based configuration
– middleware/security.js: request-level checks
- sql/ – Supabase stored procedures (get_schema_information, etc.)
- .env.example, package.json, README.md, docs/guides/…
- Patterns & architecture:
- Single Node.js service following a modular design (client, provider, handler)
- Uses @modelcontextprotocol/server for MCP handshake
- RPC calls to Supabase functions for schema & query execution

##### README for additional insights
- Describes 3 main handlers: getSchema, getTableInfo, executeQuery.
- Highlights security via allowedQueryTypes, environment‐driven config, and RPC stored procedures.

##### Essential architectural elements
- Middleware/security module as a cross‐cutting concern on inbound requests.
- Configuration (dotenv) as a side input to supabase-client initialization.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Layer"
        direction TB
        VSCode["VS Code + Copilot (MCP Client)"]:::client
        Protocol["MCP Protocol Layer"]:::client
    end

    subgraph "Supabase MCP Server"
        direction TB
        MCPServer["MCPServer (Node.js)"]:::server
        Security["Security Middleware"]:::server
        SchemaProv["SchemaProvider"]:::server
        QueryH["QueryHandler"]:::server
        SupaClient["SupabaseClient"]:::server
        Config["Configuration (.env)"]:::server
    end

    subgraph "Supabase Database"
        direction TB
        DB["Supabase DB"]:::db
        Procs["SQL: Stored Procedures"]:::db
        Policies["SQL: Security Policies"]:::db
    end

    VSCode -->|"JSON-RPC requests"| Protocol
    Protocol -->|"JSON-RPC over IPC/HTTP"| MCPServer
    MCPServer -->|"apply security checks"| Security
    Security -->|"getSchema"| SchemaProv
    Security -->|"getTableInfo / executeQuery"| QueryH
    Config -->|"allowedQueryTypes / settings"| QueryH
    Config -->|"connection config"| SupaClient
    SchemaProv -->|"RPC call"| SupaClient
    QueryH -->|"RPC call"| SupaClient
    SupaClient -->|"execute RPC"| DB
    DB --> Procs
    DB --> Policies
    DB -->|"results"| SupaClient
    SupaClient -->|"schema result"| SchemaProv
    SupaClient -->|"query result"| QueryH
    SchemaProv -->|"schema result"| MCPServer
    QueryH -->|"query result"| MCPServer
    MCPServer -->|"JSON-RPC response"| Protocol
    Protocol -->|"response"| VSCode

    click MCPServer "https://github.com/sentry01/supabase-mcp-for-copilot/blob/main/src/index.js"
    click SupaClient "https://github.com/sentry01/supabase-mcp-for-copilot/blob/main/src/supabase-client.js"
    click SchemaProv "https://github.com/sentry01/supabase-mcp-for-copilot/blob/main/src/schema-provider.js"
    click QueryH "https://github.com/sentry01/supabase-mcp-for-copilot/blob/main/src/query-handler.js"
    click Security "https://github.com/sentry01/supabase-mcp-for-copilot/blob/main/src/middleware/security.js"
    click Config "https://github.com/sentry01/supabase-mcp-for-copilot/blob/main/src/config.js"
    click Procs "https://github.com/sentry01/supabase-mcp-for-copilot/blob/main/sql/database_functions.sql"
    click Policies "https://github.com/sentry01/supabase-mcp-for-copilot/blob/main/sql/security_policies.sql"
    click docs "https://github.com/sentry01/supabase-mcp-for-copilot/tree/main/docs/guides"
    click package.json "https://github.com/sentry01/supabase-mcp-for-copilot/blob/main/package.json"
    click env "https://github.com/sentry01/supabase-mcp-for-copilot/blob/main/.env.example"
    click README "https://github.com/sentry01/supabase-mcp-for-copilot/blob/main/README.md"

    classDef client fill:#E0F7FA,stroke:#036064,color:#000
    classDef server fill:#E8F5E9,stroke:#1B5E20,color:#000
    classDef db fill:#FFF3E0,stroke:#E65100,color:#000
```
