MCP Registry & Tester

MCP Lab

MCP Lab 是一个 Next.js 15 仪表板，用于注册基于 HTTP 的模型上下文协议（MCP）服务、手动测试工具，或通过引导式聊天体验让大模型调用这些工具。每位用户通过电子邮件登录，管理自己的注册表，并可存储为 AI 聊天工作流提供支持的服务提供商 API 密钥。

访问线上版本：MCP Lab

亮点

• 检查功能：查看可用工具、阅读详细说明，并分析每个工具的 JSON 输入架构。
• OAuth 集成：内置支持连接需要 OAuth 身份验证的 MCP 服务（服务端需支持动态客户端注册，即 RFC 7591）。
• 自定义标头：为 MCP 服务请求定义并注入自定义标头（例如，API 密钥、身份验证令牌）。
• 双重交互模式：通过生成的表单手动与 MCP 工具交互，或让大模型编排交互流程。
• 上下文感知：查看大致的上下文开销，并监控每个已连接 MCP 服务的令牌用量。

部署架构

此应用使用 SST 部署在 AWS 上，并借助 OpenNext 将 Next.js 适配到无服务器环境。OpenNext 会将 Next.js 构建输出转换为兼容 AWS Lambda 和其他无服务器平台的格式。

如需深入了解 OpenNext 如何构建部署架构，请参阅其架构文档。

• 计算：运行于 AWS Lambda，可无限扩展，且无闲置成本。
• CDN：AWS CloudFront 提供静态资源，并在边缘缓存内容以降低延迟。
• 存储：用户数据和配置存储在托管的 PostgreSQL 数据库中。
• 安全性：通过 SST 的密钥管理安全地管理环境变量和密钥。

传输支持

目前，运行时仅注册 http 传输（StreamableHTTPClientTransport）。数据库枚举中仍包含 stdio 和 sse，但在提供更多传输方式之前，UI 会有意将“传输类型”选择器限制为 HTTP。尝试保存其他类型会被后端拒绝，因为 McpConnectionManager 缺少相应的实现。

开始使用

前提条件

• Node.js 18 或更高版本
• 已在本地配置 AWS 凭证（或使用配置文件）
• PostgreSQL 数据库 URL（本地或远程）

设置步骤

1. 克隆并安装

   git clone <repo-url>
   cd mcp-tester
   npm install
   

2. 配置密钥 使用 SST 初始化所需密钥：

   npx sst secret set DATABASE_URL "postgresql://user:pass@host:5432/mcp_registry"
   npx sst secret set NEXTAUTH_SECRET "your-random-secret"
   npx sst secret set EMAIL_API_KEY "your-email-provider-api-key"
   npx sst secret set EMAIL_FROM "[email protected]"
   npx sst secret set ENCRYPTION_KEY "your-32-char-encryption-key"
   

3. 应用迁移

   npm run db:migrate
   

4. 启动开发服务器

   npx sst dev
   

   这将启动本地开发环境，并将其连接到你的 AWS 沙盒。
5. 访问仪表板 打开 http://localhost:3000，请求一个魔法链接，并在确认电子邮件后重定向到 /dashboard/mcp。

实用脚本

• npm run build – Next.js 生产构建
• npm run db:studio – 启动 Drizzle Studio 并连接到已配置的数据库
• npm run lint – Next.js lint 流程

核心工作流

1. 登录并设置 API 密钥

1. 前往 /auth/login 并请求一个魔法链接（Nodemailer 通过 EMAIL_SERVER 发送）。
2. 登录后，打开 /dashboard/credentials 存储服务提供商密钥。目前 providers 中仅枚举了 OpenAI（openai）和 Anthropic（anthropic）。
3. 密钥通过 PostgreSQL 访问控制进行静态加密；只有所有者可以通过 src/services/key-service.ts 中的服务端操作读取、更新或删除这些密钥。

2. 注册或编辑 MCP 服务

• /dashboard/mcp 仅列出当前用户的服务，并显示注册／编辑／删除操作按钮。
• /dashboard/register 接受名称、描述、URL、HTTP 标头，并且（目前）强制将传输类型设为 HTTP。
• /dashboard/edit/[id] 使用同一表单，并通过 /api/mcp-servers/[id] 加载记录。
• API 层会按用户 ID 限定记录，因此即使构造请求，也无法操作其他用户的服务。

3. 手动测试工具

1. 点击服务上的 交互，加载 /dashboard/mcp/[id]。
2. 点击 连接到 MCP 服务；页面会调用 /api/mcp-connect，该接口会通过 McpConnectionManager.connect 列出工具。
3. 选择工具以查看其说明、输入架构和自动生成的表单。如果未提供架构，也可以切换到原始 JSON 文本区域。
4. 每次运行都会调用 /api/mcp-call-tool，并在 最近调用列表中记录结果或错误，同时提供一键复制按钮。
5. 展开 更多信息后，可以编辑标头覆盖项，以便临时更换令牌，而不永久保存这些令牌。

4. AI 聊天运行器

1. 连接后，将交互模式切换为 聊天；MCP Lab 会在聊天侧边栏中显示所选服务的工具。
2. 选择你拥有 API 密钥的 LLM 提供商／模型组合（模型定义在 src/lib/llm.ts 中）。
3. 消息通过 /api/chat 流式传输；每个请求的工具链调用最多限制为五步（stepCountIs(5)）。工具定义会使用已保存的服务器标头，回调 McpConnectionManager.callTool。
4. 聊天 UI 会显示所有助手／用户消息，并在等待响应时禁用发送功能，以避免重复执行工具。

5. OAuth 连接流程

1. 如果 MCP 服务需要身份验证（响应 401）且支持动态客户端注册（RFC 7591），系统会启动带 PKCE 的 OAuth 2.0 授权码流程。
2. 你会被重定向到提供商的登录页面，以授权该应用。
3. 成功后，你会被重定向回控制面板（/api/auth/mcp/callback），访问令牌会在此处加密并安全存储。
4. 控制面板会自动重新连接（auto_connect=true），之后的所有请求都会使用已存储的令牌。

API 路由

• GET/POST /api/mcp-servers – 列出或为已验证身份的用户创建 MCP 服务。
• GET/PUT/DELETE /api/mcp-servers/[id] – 获取、更新或删除单个服务（按用户强制执行授权）。
• POST /api/mcp-connect – 连接到服务，并通过 MCP SDK 返回工具元数据。
• POST /api/mcp-call-tool – 使用 JSON 参数执行指定工具，并返回原始 MCP 结果。
• GET /api/api-keys – 向聊天配置 UI 提供已存储的提供商密钥。
• POST /api/chat – 从所选 LLM 流式传输响应，同时允许模型调用 MCP 工具。
• api/auth/[...nextauth] – 由 NextAuth 处理会话管理和电子邮件验证链接。

技术栈

• 前端：Next.js 15 + React 19、App Router、Server Components、Tailwind 4（通过 PostCSS）+ shadcn/ui。
• 身份验证：NextAuth 搭配魔法链接、Drizzle 适配器，以及用于部署的 SST 密钥。
• 数据库：PostgreSQL 15、Drizzle ORM、Drizzle Kit 迁移。
• MCP：@modelcontextprotocol/sdk Streamable HTTP 客户端、手动调用和聊天工具。
• LLM SDK：ai（Vercel AI SDK），搭配来自 @ai-sdk/openai 和 @ai-sdk/anthropic 的提供商。
• 开发工具：ESLint 9、TypeScript 5、由 Turbopack 驱动的 next dev。

故障排除

• 邮箱登录 – 确保 EMAIL_SERVER 是有效的 Nodemailer 连接字符串，并且 localhost 已获准作为身份验证主机（AUTH_TRUST_HOST / NEXTAUTH_URL）。
• 数据库错误 – 确认可通过 DATABASE_URL 访问 Postgres，且已运行迁移；Drizzle 错误通常会指出缺少的表。
• MCP 连接失败 – 确认远程端点支持 Streamable HTTP（@modelcontextprotocol/sdk 服务传输），并且已提供任何必需的身份验证标头；CORS 必须允许 OPTIONS、POST 和 GET。
• 聊天显示“未找到 API 密钥” – 在 /dashboard/credentials 添加匹配的提供商密钥；聊天端点没有密钥时会拒绝调用模型。
• 工具调用验证 – 使用 @rjsf/validator-ajv8 验证架构；格式错误的 JSON 或不符合架构的内容会连同详细错误显示在“最近调用”列表中。

路线图

• 在交互界面中将 MCP 资源与工具一同展示。
• 支持更多大模型提供商，并支持按工具选择密钥。
• 支持为 OAuth 流程预注册 client_id 和密钥。