MCP 服务器

Supabase MCP Server

一个连接像 GitHub Copilot 这样的 AI 助手和 Supabase 数据库的桥梁，使 AI 能够理解数据库模式，协助编写查询，并提供与您的数据模型相关的上下文感知建议。

README

Supabase MCP 服务器实现计划

本文档概述了创建连接到 Supabase 的模型上下文协议 (MCP) 服务器的计划，该服务器允许像 GitHub Copilot 这样的 AI 助手与您的 Supabase 数据库进行交互。

概述

Supabase MCP 服务器将充当 AI 助手（如 GitHub Copilot）和您的 Supabase 数据库之间的桥梁。这允许 AI：

了解您的数据库模式
了解表和关系
协助编写查询
提供与您的数据模型相关的上下文感知建议

先决条件

已安装 Node.js 18+
npm 或 yarn 包管理器
具有管理员 API 密钥的 Supabase 项目
支持 Copilot/MCP 的 VS Code
Git

实施步骤

1. 创建服务器包

mkdir mcp-server-supabase
cd mcp-server-supabase
npm init -y

2. 安装依赖项

npm install @supabase/supabase-js @modelcontextprotocol/server dotenv

3. 基本服务器结构

创建以下文件：

src/index.js - 主要入口点
src/supabase-client.js - Supabase 连接处理
src/schema-provider.js - 数据库模式提取
src/query-handler.js - 安全查询执行
.env.example - 环境变量模板
config.js - 配置管理

4. 服务器实现细节

src/index.js

此文件将初始化 MCP 服务器并连接组件：

const { MCPServer } = require('@modelcontextprotocol/server');
const { getSupabaseClient } = require('./supabase-client');
const { SchemaProvider } = require('./schema-provider');
const { QueryHandler } = require('./query-handler');
const config = require('./config');

async function main() {
  try {
    // 初始化 Supabase 客户端
    const supabaseClient = getSupabaseClient(config.supabase.url, config.supabase.key);
    
    // 创建 providers
    const schemaProvider = new SchemaProvider(supabaseClient);
    const queryHandler = new QueryHandler(supabaseClient, config.security.allowedQueries);
    
    // 初始化 MCP 服务器
    const server = new MCPServer({
      name: 'mcp-server-supabase',
      version: '1.0.0',
    });
    
    // 注册 handlers
    server.registerHandler('getSchema', async () => {
      return await schemaProvider.getFullSchema();
    });
    
    server.registerHandler('getTableInfo', async (params) => {
      return await schemaProvider.getTableInfo(params.tableName);
    });
    
    server.registerHandler('executeQuery', async (params) => {
      return await queryHandler.execute(params.query, params.params);
    });
    
    // 启动服务器
    await server.start();
    console.log('MCP Supabase server is running');
  } catch (error) {
    console.error('Failed to start MCP server:', error);
    process.exit(1);
  }
}

main();

src/supabase-client.js

const { createClient } = require('@supabase/supabase-js');

function getSupabaseClient(url, apiKey) {
  if (!url || !apiKey) {
    throw new Error('Supabase URL and API key must be provided');
  }
  
  return createClient(url, apiKey, {
    auth: { persistSession: false },
  });
}

module.exports = { getSupabaseClient };

src/schema-provider.js

class SchemaProvider {
  constructor(supabaseClient) {
    this.supabase = supabaseClient;
  }
  
  async getFullSchema() {
    // 查询 Supabase 获取完整数据库模式
    const { data, error } = await this.supabase
      .rpc('get_schema_information', {});
    
    if (error) throw new Error(`Failed to get schema: ${error.message}`);
    
    return data;
  }
  
  async getTableInfo(tableName) {
    // 获取有关特定表的详细信息
    const { data, error } = await this.supabase
      .rpc('get_table_information', { table_name: tableName });
    
    if (error) throw new Error(`Failed to get table info: ${error.message}`);
    
    return data;
  }
}

module.exports = { SchemaProvider };

src/query-handler.js

class QueryHandler {
  constructor(supabaseClient, allowedQueryTypes = ['SELECT']) {
    this.supabase = supabaseClient;
    this.allowedQueryTypes = allowedQueryTypes; 
  }
  
  validateQuery(queryString) {
    // 基本 SQL 注入预防和查询类型验证
    const normalizedQuery = queryString.trim().toUpperCase();
    
    // 检查查询是否以允许的查询类型开头
    const isAllowed = this.allowedQueryTypes.some(
      type => normalizedQuery.startsWith(type)
    );
    
    if (!isAllowed) {
      throw new Error(`Query type not allowed. Allowed types: ${this.allowedQueryTypes.join(', ')}`);
    }
    
    return true;
  }
  
  async execute(queryString, params = {}) {
    // 在执行之前验证查询
    this.validateQuery(queryString);
    
    // 通过 Supabase 执行查询
    const { data, error } = await this.supabase
      .rpc('execute_query', { query_string: queryString, query_params: params });
    
    if (error) throw new Error(`Query execution failed: ${error.message}`);
    
    return data;
  }
}

module.exports = { QueryHandler };

config.js

require('dotenv').config();

module.exports = {
  supabase: {
    url: process.env.SUPABASE_URL,
    key: process.env.SUPABASE_SERVICE_KEY,
  },
  server: {
    port: process.env.PORT || 3000,
  },
  security: {
    allowedQueries: process.env.ALLOWED_QUERY_TYPES 
      ? process.env.ALLOWED_QUERY_TYPES.split(',') 
      : ['SELECT'],
  }
};

.env.example

SUPABASE_URL=https://your-project-ref.supabase.co
SUPABASE_SERVICE_KEY=your-service-key
PORT=3000
ALLOWED_QUERY_TYPES=SELECT

5. Supabase 数据库函数

您需要在 Supabase 中创建以下存储过程：

get_schema_information() - 返回数据库模式
get_table_information(table_name TEXT) - 返回有关特定表的信息
execute_query(query_string TEXT, query_params JSONB) - 安全地执行查询

服务器架构

┌─────────────────────┐      ┌───────────────────┐
│                     │      │                   │
│  VS Code + Copilot  │◄────►│   MCP 协议    │
│                     │      │                   │
└─────────────────────┘      └─────────┬─────────┘
                                      │
                                      ▼
                            ┌─────────────────────┐
                            │                     │
                            │ Supabase MCP 服务器 │
                            │                     │
                            └─────────┬───────────┘
                                      │
                                      ▼
                            ┌─────────────────────┐
                            │                     │
                            │  Supabase 数据库  │
                            │                     │
                            └─────────────────────┘

配置

将 Supabase MCP 服务器添加到您的 VS Code settings.json：

"mcp": {
  "inputs": [],
  "servers": {
    // ...existing servers...
    "mcp-server-supabase": {
      "command": "node",
      "args": [
        "/path/to/mcp-server-supabase/src/index.js"
      ],
      "env": {
        "SUPABASE_URL": "https://your-project-ref.supabase.co",
        "SUPABASE_SERVICE_KEY": "your-service-key",
        "ALLOWED_QUERY_TYPES": "SELECT"
      }
    }
  }
}

安全注意事项

API 密钥管理:
- 使用具有最低所需权限的范围限定的 API 密钥
- 安全地存储 API 密钥，切勿提交到版本控制
- 考虑使用密钥轮换策略
查询限制:
- 默认为仅 SELECT 以确保安全
- 考虑实施查询允许列表方法
- 添加速率限制以防止滥用
数据保护:
- 避免暴露 PII 或敏感数据
- 在 Supabase 中实施行级安全性
- 考虑为敏感字段添加数据屏蔽

安装指南

本地开发

克隆存储库

git clone https://github.com/yourusername/mcp-server-supabase.git
cd mcp-server-supabase

安装依赖项
```
npm install
```
从示例创建 .env 文件
```
cp .env.example .env
```
使用您的 Supabase 凭据编辑 .env
启动服务器
```
node src/index.js
```

VS Code 集成

使用服务器配置更新您的 VS Code settings.json
重新启动 VS Code
验证服务器是否在 VS Code MCP 面板中运行

使用示例

集成后，您可以通过多种方式使用 Supabase MCP 服务器：

模式探索：

我的 Supabase 数据库中有哪些表？

表信息：
```
users 表中有哪些列？
```

查询协助：

帮我编写一个查询来获取过去 7 天内注册的所有用户

故障排除

服务器无法启动

检查您的 Node.js 版本（应为 18+）
验证您的 Supabase 凭据
检查终端中的错误日志

模式未加载

验证您的 Supabase 服务密钥是否具有必要的权限
检查数据库函数是否已正确创建

VS Code 无法连接

检查 settings.json 中的服务器路径是否正确
在配置更改后重新启动 VS Code
验证服务器进程是否正在运行