[RFC] 119 - Steamable HTTP MCP Server Auth 方案

[arvinxx]

1. 概述

本 RFC 旨在为 LobeChat 内的 Streamable HTTP MCP (模型上下文协议) 插件提出一个全面的、分三阶段的授权实现演进计划。我们的目标是支持需要认证的受保护 MCP 服务。经过深入讨论，我们决定采用一个统一的前置授权（Up-front Authorization）模型。在该模型下，用户在使用任何需要认证的插件之前，必须先完成授权流程。

此方案将从简单的手动配置令牌开始，逐步演进到一个完全自动化的、符合 MCP 规范的 OAuth 2.1 授权流程，并为桌面端和 Web 端提供各自最佳的授权回调体验。

2. 背景与动机

LobeChat 当前的实现不支持 Streamable HTTP 类型 MCP 插件的认证功能。随着 MCP 生态系统的发展，许多有价值的服务（例如，访问 GitHub、Figma、Google Drive 上的私有数据）都受到保护，并要求通过 OAuth 2.1 进行授权。

为了完全释放 LobeChat 插件生态系统的潜力，我们必须提供一个安全、可扩展且用户友好的机制，让用户能够授权插件代表他们执行操作。此实现必须与官方的 MCP 授权规范（2025-06-18 修订版） 保持一致，以确保互操作性和遵循安全最佳实践。

3. 提议方案：统一的前置授权模型与三阶段演进

经过深入讨论，我们决定采用一个统一的、前置的授权模型，以简化实现逻辑并提供一致的用户体验。

核心设计：前置授权 (Up-front Authorization)

对于任何需要认证的 MCP Server，其授权流程都将在用户实际调用其功能之前完成。

1. 安装与识别：用户在 LobeChat 中添加一个新的 MCP Server。LobeChat 将其识别为需要认证的插件（可以通过插件市场的元数据或用户手动指定）。
2. 进入待授权状态：插件被添加到列表后，其初始状态为“需要授权”。此时，用户无法看到或使用插件内的任何工具。
3. 引导用户授权：UI 上会清晰地显示一个 [ 连接并授权 ] 按钮，引导用户启动授权流程。
4. 授权后激活：用户必须先完成授权流程。成功后，LobeChat 才会使用获取到的凭证去请求 manifest，加载工具列表，并最终将插件状态更新为“已连接/可用”。

演进路线图

// 定义于 src/libs/mcp/types.ts，存储在 LobeChat 的插件配置中
interface AuthConfig {
  // 认证类型
  type: 'none' | 'bearer' | 'oauth2';

  // --- Stage 1: 手动配置 ---
  token?: string; // 用户手动粘贴的 Bearer Token

  // --- Stage 2 & 3: OAuth 2.1 自动化流程 ---

  // A. 静态配置 或 动态注册获取的【客户端凭证】
  clientId?: string;
  clientSecret?: string; // 如果是机密客户端
  scope?: string;        // 想要申请的权限范围, e.g., "repo user:email"

  // B. 服务器发现机制获取的【授权服务器元数据】
  serverMetadata?: {
    authorization_endpoint?: string;
    token_endpoint?: string;
        registration_endpoint?: string;
        // ... and other RFC8414 fields
  };

  // C. 用户授权后获取的【用户令牌】
  accessToken?: string;
  refreshToken?: string;
  tokenExpiresAt?: number; // accessToken 的过期时间戳
}

第一阶段：手动认证模式 (Bearer Token / Header)

目标： 作为实现完整 OAuth 流程的第一步，快速支持需要手动配置认证凭证的 MCP 服务。

核心变更：

1. 可扩展的 auth 数据模型：在 src/libs/mcp/types.ts 中为 HttpMCPClientParams 增加一个 auth 对象，用于容纳所有认证信息。初期将包含 type: 'bearer' 和 token 字段。
2. UI 流程：
   • 用户添加插件后，插件显示为“需要授权”。
   • 点击 [ 连接并授权 ] 按钮，弹出一个配置模态框。
   • 用户选择认证方式为“Bearer Token / API 密钥”，并粘贴他们的令牌。
3. 客户端逻辑：用户保存令牌后，LobeChat 使用该令牌去请求服务器的 manifest。请求成功则插件激活；失败则提示用户检查令牌。

产出成果： LobeChat 可以连接到需要基本令牌认证的服务。为第二阶段的自动化流程奠定了数据结构和 UI 基础。

第二阶段：核心 OAuth 2.1 授权码流程

目标： 实现完整的、用户友好的 OAuth 2.1 授权码授权流程（Authorization Code Grant Flow with PKCE）。

核心变更：

1. UI 流程：
   • 用户添加插件后，插件显示为“需要授权”。
   • 点击 [ 连接并授权 ] 按钮，LobeChat 立即启动 OAuth 流程，将用户重定向到浏览器进行授权。
2. 数据模型扩展：完善 auth 对象，添加 clientId, scope, accessToken, refreshToken, tokenExpiresAt, 以及 serverMetadata 等字段。
3. 核心服务与回调：
   • 创建一个新的 OAuthService，负责处理 OAuth 流程的启动和回调。
   • 实现针对桌面端和 Web 端的不同回调处理逻辑（详见 4.1 节）。
4. SDK 集成：实现一个 OAuthClientProvider，负责向 StreamableHTTPClientTransport 提供和刷新 accessToken。
5. 服务器发现：在 OAuth 流程启动前，实现根据 WWW-Authenticate 头部发现和存储授权服务器元数据的能力。

产出成果： LobeChat 支持标准、安全且流程统一的 OAuth 2.1 授权。

第三阶段：完全自动化与健壮性

目标： 通过实现动态客户端注册和完善的令牌管理生命周期，实现接近零配置的用户体验。

核心变更：

1. 动态客户端注册 (RFC 7591)：在 OAuthService 中增加自动向授权服务器的 registration_endpoint 请求 client_id 的功能，消除用户手动配置的需要。
2. 健壮的令牌刷新逻辑：在 OAuthClientProvider 中完全实现无缝的后台令牌刷新机制。
3. 增强的 UI 与管理能力：提供一个集中的设置区域，供用户管理所有已连接的应用授权。

产出成果： LobeChat 为 MCP 插件提供了一套业界顶级的、高度自动化的、安全的授权系统。

4. 技术实现细节

4.1. 核心差异：回调处理机制 (Callback Handling)

由于客户端环境的限制，LobeChat 必须为桌面端和 Web 端实现不同的 OAuth 回调处理策略。

5. 实施策略

三阶段计划本身构成了我们的实施策略。它允许我们进行增量开发和部署，从而降低风险，并使社区能够更快地从新功能中受益。第一阶段可以作为独立的改进发布，同时继续进行第二和第三阶段的工作。

进展

• 第一阶段：✨ feat: support Streamable HTTP MCP Server Auth #8425

[yuchanns]

期待！

没注意到这个 RFC 仅仅发布了两天，以为已经实现了。刚刚折腾了半天发现始终无法通过认证，原来是我自己粗心大意了😢
订正: 第一阶段已经实现了