Supabase远程MCP SDK——规范
动机
构建和部署模型上下文协议（MCP）服务器应该是快速、类型安全和生产就绪的，而无需深入了解边缘运行时或传输细节。如今，开发人员面临着三个方面的摩擦：
- 服务器脚手架：连接传输、模式验证和MCP功能（工具、资源、提示、中间件）。
- 部署：绑定并部署到具有合理默认值和可重复工作流的边缘运行时（例如，Deno上的Supabase edge Functions）。
- 用户体验：为MCP响应（用于ChatGPT应用程序和MCP-UI）添加丰富的UI功能强大，但跨多个协议和库。
此SDK旨在：
- 在mcp-lite之上提供一个流畅、类型安全的服务器构建器，可在Supabase Edge Functions上无缝工作。
- 提供附带电池的CLI，用于初始化、开发、部署、列出和查看特定功能的日志：
supabase-mcp-remote logs. - 使UI成为一流的可选插件，同时支持OpenAI应用程序（ChatGPT小部件）和MCP-UI消息模式。
- 将身份验证作为一个单独的包进行插入，这样不同的组织就可以带来自己的OAuth/JWT/Supabase Auth，而不会使核心膨胀。
非目标：
- 替换
mcp-lite。我们在此基础上进行构建，并按照人体工程学原理展示其功能。 - 将用户锁定到单个UI协议中。ChatGPT应用程序和MCP-UI都通过可选的UI包支持。
- 对任何单一身份验证机制进行硬编码。Auth是一个单独的包，是可选的。
设计原则：
- Edge-first和minimum：使用Deno/Subabase边缘函数和Hono，坚持Fetch API。
- 端到端类型安全：用于模式的Zod（或适配器）→ 键入处理程序。
- 渐进式、模块化采用：核心SDK（服务器+部署）、可选UI、可选身份验证。
- 清晰的人体工程学：小API表面和“刚刚好用”的CLI
项目结构
Monorepo由三个包和文档/示例组成。身份验证包已计划好，但尚未实现。
supabase-remote-mcp-sdk/
├── packages/
│ ├── sdk/ # @supabase-remote-mcp/sdk (core)
│ │ ├── src/
│ │ │ ├── core/
│ │ │ │ ├── server-builder.ts # Fluent builder over mcp-lite
│ │ │ │ ├── tool-registry.ts # Tools API
│ │ │ │ ├── resource-registry.ts # Static & templated resources
│ │ │ │ ├── prompt-registry.ts # Prompt templates
│ │ │ │ ├── middleware-manager.ts # Middleware chain
│ │ │ │ └── config.ts # SDK config types
│ │ │ ├── deployment/
│ │ │ │ ├── deployer.ts # Orchestrates edge deploys
│ │ │ │ ├── supabase-client.ts # Supabase CLI/API wrapper
│ │ │ │ ├── bundler.ts # Build/bundle for Edge Functions
│ │ │ │ └── templates.ts # Function/handler templates
│ │ │ ├── cli/
│ │ │ │ ├── commands/
│ │ │ │ │ ├── init.ts
│ │ │ │ │ ├── dev.ts
│ │ │ │ │ ├── deploy.ts
│ │ │ │ │ ├── list.ts
│ │ │ │ │ └── logs.ts # supabase-mcp-remote logs
│ │ │ │ └── index.ts # CLI entry
│ │ │ └── index.ts # Public exports
│ │ ├── tests/ # Unit, integration, e2e
│ │ └── package.json
│ │
│ ├── ui/ # @supabase-remote-mcp/ui (optional UI)
│ │ ├── src/
│ │ │ ├── chatgpt/ # OpenAI Apps widgets
│ │ │ │ ├── hooks/ # useWidgetProps, useWidgetState, etc.
│ │ │ │ ├── server/ # registerChatGPTWidget(), resource wiring
│ │ │ │ └── bundler/ # Bundle React → single HTML for widgets
│ │ │ ├── mcp-ui/ # MCP-UI protocol support
│ │ │ │ ├── messenger/ # Iframe messenger (postMessage/RPC)
│ │ │ │ ├── hooks/ # useUIMessenger(), etc.
│ │ │ │ └── server/ # registerMCPUIWidget() helpers
│ │ │ └── index.ts
│ │ ├── templates/ # Starter UI templates (ChatGPT/MCP-UI)
│ │ └── package.json
│ │
│ └── auth/ # @supabase-remote-mcp/auth (future)
│ ├── src/
│ │ ├── strategies/ # oauth, jwt, api-key, custom
│ │ ├── middleware/ # createAuthMiddleware(), rate limiter
│ │ ├── supabase/ # Supabase Auth helpers
│ │ └── index.ts
│ └── package.json
│
├── examples/
│ ├── basic-tools/ # Minimal tools-only example
│ ├── with-resources/ # Static + templated resources
│ ├── with-prompts/ # Prompt templates
│ ├── with-middleware/ # Logging/Auth/Rate limiting patterns
│ ├── chatgpt-widget/ # UI example (OpenAI Apps)
│ └── mcp-ui-widget/ # UI example (MCP-UI)
│
└── docs/
├── getting-started.md
├── ui/chatgpt-widgets.md
├── ui/mcp-ui.md
└── authentication.md # Placeholder for future auth package关键决策：
- 核心保持精简：mcp-lite服务器构建器+Supabase部署+CLI。
- UI是可选的：通过单独的包支持ChatGPT（OpenAI Apps）和MCP-UI；受分形mcp/sdk图案的启发。
- Auth是可选的和独立的：一个提供中间件和策略的未来包；芯部露出钩子来连接它。
- CLI名称稳定且明确：
supabase-mcp-remote，包括功能范围日志supabase-mcp-remote logs.
基本用法（非常少）
本例展示了开发人员如何使用SDK流畅的API通过一个工具定义一个小型MCP服务器。它侧重于核心开发人员体验；还没有UI或身份验证。
TypeScript（服务器文件）：
import { z } from "zod";
import { SupabaseMCPServer } from "@supabase-remote-mcp/sdk";
const server = new SupabaseMCPServer({
name: "hello-mcp",
version: "1.0.0",
// You can pass env or config as needed; SDK will handle edge bundling/deploy
});
server.tool("echo", {
description: "Echo a message",
schema: z.object({ message: z.string() }),
handler: async (args) => ({
content: [{ type: "text", text: args.message }],
}),
});
// Optionally add resources or prompts:
// server.resource("file://config.json", { /* … */ }, async (uri) => ({ contents: [/* … */] }));
// server.prompt("review", { /* … */ });
export default server;CLI（部署和查看日志）：
# Deploy to Supabase Edge Functions (bundles automatically)
supabase-mcp-remote deploy
# View logs for a specific function (tail optional)
supabase-mcp-remote logs hello-mcp这有什么作用：
- 使用一个工具定义MCP服务器
mcp-lite引擎盖下。 - 将Supabase Edge Functions的代码捆绑在一起，并将其部署在
//mcp终点。 - 允许您通过以下方式查看函数范围的日志
supabase-mcp-remote logs.
下一步（可选）：
- 通过添加UI
@supabase-remote-mcp/ui:
- ChatGPT小部件：注册一个小部件并返回 structuredContent +HTML资源。 - MCP-UI：为其他客户端中的交互式UI添加iframe信使和钩子。
- 通过添加身份验证
@supabase-remote-mcp/auth（未来）：
- 插入式OAuth/JWT/neneneba API关键中间件；访问 ctx.authInfo 在处理程序中。