[AI] MCP Milestones

[Similarityoung]

MCP OverPixiu Milestones

Step 1: 基础能力建设

1. MCP 基础协议支持：支持 MCP (Model Context Protocol) 的核心功能。 Feat(MCP): Add MCP Server Filter for Model Context Protocol support #702

2. 动态配置更新：集成 Nacos，实现配置的动态更新，提高系统的灵活性和可维护性。Feat(MCP): add MCP server with nacos #757

3. 权限认证：增加 MCP Auth 权限认证机制，保障模型的安全访问和合规使用。 feat(MCP): add MCP authorization #740

4. 核心对象支持：完整支持 MCP 中的 resource 和 prompt 对象。

Step 2: 兼容与扩展

1. 多后端支持：扩展 MCP Server 的后端能力，除了 OpenAPI，还将支持 gRPC 和 Dubbo，提供更广泛的后端服务接入能力。

2. 多集群模式：引入 MCP Session，支持多集群模式，提升系统的可伸缩性和容灾能力。

Step 3: 完善与增强

1. 多模态数据兼容：探索在 MCP 体系下对语音、图像等多模态数据的兼容方案。

2. 协议新特性对齐：对齐 MCP 协议的最新特性，包括日志（logging）、自动完成（completion）和分页（pagination）。

3. 可观测性：构建完善的可观测性体系，方便对系统进行监控和问题排查。

测试

• 测试工具：采用官方推荐的 inspector 工具进行全面的协议兼容性和功能测试。

[Similarityoung]

有关 OpenAPI 规范转化为 MCP 工具的文章，原文

[Similarityoung]

Authorization Flow  授权流程

1. 背景(Background)

随着模型上下文协议 (Model Context Protocol, MCP) 的应用场景从本地环境扩展到开放的互联网，对服务进行访问控制和身份验证变得至关重要。这直接关系到 MCP Server 的核心安全性。当前，Pixiu 网关已经具备将后端 API 包装为 MCP Server 的能力，下一步的核心任务是利用网关的现有能力，集成一套标准的鉴权机制，以完整实现 MCP 规范中的授权 (Authorization) 要求。

MCP 规范明确指出：

Implementations using an HTTP-based transport **SHOULD** conform to this specification.
（基于 HTTP 的传输应该实现此规范。）

本方案旨在设计一个健壮、可扩展且符合行业最佳实践的授权流程。

2. 核心原则与角色定位 (Core Principles & Role)

2.1 Pixiu 的角色抉择：资源服务器

A protected MCP server acts as an OAuth 2.1 resource server, capable of accepting and responding to protected resource requests using access tokens.

The authorization server is responsible for interacting with the user (if necessary) and issuing access tokens for use at the MCP server. The implementation details of the authorization server are beyond the scope of this specification. It may be hosted with the resource server or a separate entity. The Authorization Server Discovery section specifies how an MCP server indicates the location of its corresponding authorization server to a client.

受保护的 MCP 服务器充当 OAuth 2.1 资源服务器，能够使用访问令牌接受和响应受保护的资源请求。

授权服务器负责与用户交互（如有必要）并颁发供 MCP 服务器使用的访问令牌。授权服务器的实现细节超出了本规范的范围。它可以与资源服务器一起托管，也可以作为单独的实体托管。指定 MCP 服务器如何向客户端指示其相应授权服务器的位置。

对于 Pixiu 网关而言，其核心职责是保护后端的 API 服务，因此我觉得包装成 Resource Server 是更好且正确的选择。

方案	优点	缺点
网关只作资源服务器 (推荐)	架构清晰，职责单一。 安全性高，依赖专业方案。 灵活，可扩展性强。 符合行业最佳实践	需要额外部署/购买一个授权服务器
网关 = 资源服务器 + 授权服务器	表面上看起来组件少，部署简单	架构混乱，高耦合。 极高的安全风险。 难以维护和扩展。 缺乏互操作性

2.2. 授权流程概览

sequenceDiagram
    participant C as Client
    participant M as MCP Server (Resource Server)
    participant A as Authorization Server

    C->>M: MCP request without token
    M-->>C: HTTP 401 Unauthorized with WWW-Authenticate header
    Note over C: Extract resource_metadata<br />from WWW-Authenticate

    C->>M: GET /.well-known/oauth-protected-resource
    M-->>C: Resource metadata with authorization server URL
    Note over C: Validate RS metadata,<br />build AS metadata URL

    C->>A: GET /.well-known/oauth-authorization-server
    A-->>C: Authorization server metadata

    Note over C,A: OAuth 2.1 authorization flow happens here

    C->>A: Token request
    A-->>C: Access token

    C->>M: MCP request with access token
    M-->>C: MCP response
    Note over C,M: MCP communication continues with valid token

Loading

3. 约束与目标(Constraints & Goals)

3.1 功能约束

MCP servers MUST implement OAuth 2.0 Protected Resource Metadata (RFC9728). MCP clients MUST use OAuth 2.0 Protected Resource Metadata for authorization server discovery.

Pixiu 作为 MCP Server 需要保护资源元数据。

Implementors should note that Protected Resource Metadata documents can define multiple authorization servers. The responsibility for selecting which authorization server to use lies with the MCP client, following the guidelines specified in RFC9728 Section 7.6 “Authorization Servers”.

Pixiu 应该支持多个授权服务器的选择，选择权在于 MCP Client。

MCP servers MUST use the HTTP header WWW-Authenticate when returning a 401 Unauthorized to indicate the location of the resource server metadata URL as described in RFC9728 Section 5.1 “WWW-Authenticate Response”.

Pixiu 在返回 401 的时候，需要通过 WWW-Authenticate 指示资源服务器的元数据 URL。

MCP servers, acting in their role as an OAuth 2.1 resource server, MUST validate access tokens as described in OAuth 2.1 Section 5.2. MCP servers MUST validate that access tokens were issued specifically for them as the intended audience, according to RFC 8707 Section 2. If validation fails, servers MUST respond according to OAuth 2.1 Section 5.3 error handling requirements. Invalid or expired tokens MUST receive a HTTP 401 response.

Pixiu 需要验证访问令牌是否专门为其目标用户颁发。无效或过期的令牌必须收到 HTTP 401 响应。

• HTTP 401 Unauthorized: 用于认证失败，即客户端没有提供令牌、令牌无效、过期或签名错误。WWW-Authenticate 头应该如你所述被包含。

• HTTP 403 Forbidden: 用于授权失败，即客户端提供了有效的令牌，但该令牌所拥有的权限（如 scope）不足以执行当前请求的操作。在这种情况下，服务器已经知道了用户的身份，但拒绝其访问。

Token Audience Binding and Validation: MCP servers MUST validate that tokens presented to them were specifically issued for their use

Pixiu 必须验证提供给它们的令牌是否是专门为其使用的。

3.2 安全约束

杜绝硬编码密钥: 严禁在代码或配置中硬编码任何对称密钥或私钥。公钥应通过标准的 jwks_uri 动态获取。

核心声明验证: 必须强制验证令牌的 iss (Issuer), aud (Audience), exp (Expiration Time) 声明。

缓存安全: 元数据和公钥的缓存必须有明确的过期策略 (TTL)，以响应密钥轮换等安全事件。

3.3 技术选型

在对多个 JWT 库进行深入评估后，我们决定采用 github.com/lestrrat-go/jwx 作为我们项目的核心 JOSE (Javascript Object Signing and Encryption) 库。这是一个战略性的技术升级，主要原因如下：

1. 功能全面且统一: jwx 是一个完整的 JOSE 协议栈实现，原生支持 JWS (签名)、JWE (加密)、JWK (密钥) 和 JWA (算法)。这为我们提供了一个一站式的解决方案，避免了为了实现不同功能而组合多个库的复杂性，确保了 API 和设计理念的一致性。

2. 简化依赖管理: jwx 内置了对 JWKS (JSON Web Key Set) 的完整支持，包括从 jwks_uri 动态获取公钥、自动刷新和缓存管理。这意味着我们可以移除现有的 github.com/MicahParks/keyfunc 依赖，从而简化项目的依赖树，减少潜在的版本冲突和维护成本。

3. 架构前瞻性与可扩展性: 我们的目标是构建一个健壮、可扩展的系统。jwx 不仅能完美满足当前作为 OAuth 2.0 资源服务器的需求，其内置的 JWE (加密) 等高级功能，也为未来可能出现的更复杂的安全场景（如 OpenID Connect, FAPI, 加密令牌等）做好了充分准备，避免了未来的技术栈重构。

4. 严格遵循标准: 该库的设计严格遵循相关的 RFC 规范，确保了其行为的正确性和互操作性。这对于实现一个标准的、可与任何 OAuth 2.0 授权服务器对接的资源服务器至关重要。

综上所述，尽管切换库会带来一定的初期工作量，但选择 lestrrat-go/jwx 能显著提升项目的架构水平、简化依赖关系并增强未来的扩展能力。

4. 设计方案 (Design & Implementation)

本方案旨在通过引入 github.com/lestrrat-go/jwx 库，新增一个完全符合 MCP 规范的 OAuth 2.0 资源服务器过滤器 (mcp_auth)。为遵循务实、迭代的原则，本次实施将集中于交付新的 mcp_auth 过滤器，对现有 jwt 过滤器的重构将暂缓，作为后续的技术优化任务。

4.1 架构与文件结构

为避免过度设计，我们将核心的 JWT 验证逻辑内聚在 mcp 过滤器内部，采用 internal 包来明确其私有性。最终文件结构如下：

pkg/filter/auth/
├── jwt/                   # [保留, 本次不改动]
│   └── ...
│
├── mcp/                   # [新增] 新的 MCP 认证过滤器
│   ├── filter.go          # 实现 MCP 协议流程
│   ├── config.go          # MCP 过滤器相关配置
│   └── internal/          # [新增] 存放 MCP 过滤器内部使用的逻辑
│       └── validator/
│           ├── validator.go
│           └── config.go

4.2 核心验证器 (mcp/internal/validator/)

此包负责提供专供 mcp 过滤器使用的、基于 jwx 的令牌验证能力。

配置 (config.go):

• 定义 Provider 结构，包含 issuer, audiences 和 jwks_source 等字段。

验证器 (validator.go):

• NewValidator(providers) (伪代码):

  // 接收Provider配置列表
  // for each provider:
  //   根据 jwks_source (remote/local)
  //   创建 jwk.NewAutoRefresh() 或 jwk.Parse() 实例 (jwk.Set)
  //   将 jwk.Set 和 provider 元数据存入 map
  // return validator_instance

• Validate(providerName, tokenString) (伪代码):

  // providerRules = find_rules_for(providerName)
  // jwt.Parse(token,
  //   jwt.WithKeySet(providerRules.keySet),
  //   jwt.WithIssuer(providerRules.issuer),
  //   jwt.WithAnyAudience(providerRules.audiences...)
  // )
  // return token, err

4.3 mcp 认证过滤器 (mcp/)

配置 (config.go):

• 定义顶层 Config 结构，包含 ResourceMetadata 和 Rules。
• ResourceMetadata: 定义 /.well-known 端点的内容，包括 server_host 和 authorization_servers 列表。
• Rules: 定义 path_prefix 到 required_scopes 和 provider_name 的映射。

过滤器逻辑 (filter.go) (伪代码):

// 在 Factory.Apply() 中:
// validator = internal.NewValidator(config.Providers)

// 在 Filter.Decode() 中:
// if path == "/.well-known/oauth-protected-resource":
//   return metadata_json

// rule = find_matching_rule(path)
// if rule == nil:
//   return Continue

// token = extract_bearer_token(request)
// if token == nil:
//   return 401_with_www_authenticate_header()

// validatedToken, err = validator.Validate(rule.ProviderName, token)
// if err != nil:
//   return 401_with_standard_error_body("invalid_token", err)

// // 注意: `scope` 声明是空格分隔的字符串, 实现时需分割处理
// if !check_scopes(validatedToken.Scopes, rule.RequiredScopes):
//   return 403_with_standard_error_body("insufficient_scope", "Token has insufficient scope")

// return Continue

4.4 错误处理 (Error Handling)

所有认证/授权相关的 4xx 错误响应，其响应体都应为 JSON 格式，并遵循 OAuth 2.0 规范，至少包含 error 和 error_description 字段，以提供清晰的客户端错误信息。

// 示例: 403 Forbidden 响应
{
  "error": "insufficient_scope",
  "error_description": "The request requires higher privileges than provided by the access token."
}

4.5 实施清单 (Implementation Checklist)

1. 在 go.mod 中，添加 github.com/lestrrat-go/jwx/v2。
2. 创建 pkg/filter/auth/mcp/internal/validator/config.go 并定义核心配置结构。
3. 创建 pkg/filter/auth/mcp/internal/validator/validator.go 并实现 NewValidator 和 Validate 函数。
4. 创建 pkg/filter/auth/mcp/config.go 并定义 MCP 过滤器配置结构。
5. 创建 pkg/filter/auth/mcp/filter.go 并实现 MCP 认证流程调度逻辑。
6. 在 filter.go 中实现标准的 OAuth 2.0 错误响应格式。
7. 在 Pixiu 的插件注册表中，注册新的 mcp_auth 过滤器。
8. 编写单元测试和集成测试，覆盖所有新功能，特别是声明验证、scope 检查和 /.well-known 端点。
   [延后] 重构 pkg/filter/auth/jwt/ 过滤器。

[Similarityoung]

MCP Server 与 Nacos 集成设计方案

概述

本评论描述了 Dubbo-go-pixiu 中 MCP Server 与 Nacos 集成的设计方案，实现动态配置管理和服务发现能力。该方案通过扩展 pkg/remote 模块提供统一的远程通信抽象，并在 pkg/adapter 层创建 mcpserver 适配器来实现配置的动态转换和生命周期管理。

架构背景

现有架构问题

当前dubbo-go-pixiu存在以下架构不一致性：

1. 分散的Nacos客户端实现

• pkg/remote/nacos/client.go: 服务发现客户端（naming_client.INamingClient）

• configcenter/nacos_load.go: 配置管理客户端（config_client.IConfigClient）

• 两套独立实现导致代码重复和维护困难

2. 静态MCP Server配置

• 当前pkg/filter/mcp/mcpserver只支持静态配置的工具

• 无法动态响应Nacos配置变化

• 缺乏与远程配置中心的集成能力

3. 缺乏统一抽象

• pkg/remote 缺乏配置管理能力

• configcenter 与 pkg/remote 职责重叠

• 没有统一的远程存储通信抽象

目标架构

建立清晰的三层架构：

1. pkg/remote: 统一远程存储通信抽象层

2. pkg/adapter: 配置转换和生命周期管理层

3. pkg/filter: 协议处理层

动态配置发现流程

本节流程图聚焦于配置发现的逻辑，阐述了网关如何从 Nacos 中一步步发现并聚合一个完整 MCP 服务所需的全部信息。

sequenceDiagram
    participant Pixiu as Pixiu 网关
    participant Nacos

    loop 定期服务发现
        Pixiu->>Nacos: 1. 搜索所有 MCP 服务<br>(查询 group='mcp-server-versions' 的配置)
        Nacos-->>Pixiu: 返回服务ID列表
    end

    Note over Pixiu: 为每个新发现的服务启动一个独立的监听流程

    Pixiu->>Nacos: 2. 监听服务版本<br>(Listen to `{serviceId}-mcp-versions.json`)
    Nacos-->>Pixiu: 推送版本更新 (例如: `latest: v1.0.0`)

    Note over Pixiu: 收到新版本后，开始监听该版本的具体规格文件

    Pixiu->>Nacos: 3. 监听服务与工具规格<br>(Listen to `...-v1.0.0-mcp-server.json`)<br>(Listen to `...-v1.0.0-mcp-tools.json`)
    
    Nacos-->>Pixiu: 推送服务规格 (Service Spec)
    Note over Pixiu: 从服务规格中解析出后端服务名 (`serviceRef`)

    Pixiu->>Nacos: 4. 订阅后端服务实例<br>(Subscribe to `serviceRef`)
    Nacos-->>Pixiu: 推送实例列表 (e.g., [10.0.0.1, 10.0.0.2])

    Nacos-->>Pixiu: 推送工具规格 (Tool Spec)

    Note over Pixiu: 当版本、服务规格、工具规格、实例列表<br>这四份信息都就绪后...

    Pixiu->>Pixiu: 5. 聚合生成完整的配置快照

    Note over Pixiu: 快照已生成，准备在网关内部应用

Loading

设计方案

1. 统一远程客户端抽象 (pkg/remote)

本层负责屏蔽底层具体远程存储（如 Nacos、etcd）的实现差异，为上层提供一个稳定、统一的交互接口。

1.1 核心接口定义

我们将定义一个核心的 RemoteClient 接口，它通过组合另外两个接口来获得所需的能力。

• RemoteClient 接口:

• 组合能力: 它将内嵌 ServiceDiscovery 和 ConfigManagement 两个接口。

• 生命周期管理:

• Start() error: 启动客户端，建立与远程服务的连接。

• Stop() error: 关闭客户端，释放所有资源。

• ServiceDiscovery 接口: 负责服务发现相关的所有操作。

• 方法:

• SelectInstances(serviceName string) ([]Instance, error): 根据服务名查询所有健康的服务实例列表。Instance 是一个我们自己定义的、与具体实现无关的结构体，包含 IP、端口、元数据等信息。

• Subscribe(serviceName string, callback func([]Instance)) error: 订阅一个服务的实例变化。当实例列表发生变更时，将异步调用传入的 callback 函数。

• Unsubscribe(serviceName string) error: 取消对某个服务的订阅。

• ConfigManagement 接口: 负责配置管理相关的所有操作。

• 方法:

• GetConfig(dataId, group string) (string, error): 根据 dataId 和 group 获取一份配置，返回其原始内容（字符串）。

• ListenConfig(dataId, group string, callback func(string)) error: 监听一份配置的变更。当内容发生变化时，将异步调用传入的 callback 函数。

• StopListen(dataId, group string) error: 取消对某份配置的监听。

1.2 Nacos 客户端实现 (UnifiedNacosClient)

这是 RemoteClient 接口在 Nacos 场景下的具体实现。

• 结构: UnifiedNacosClient 是一个结构体 (struct)。

• 核心字段:

• namingClient: 持有一个 Nacos 官方的 naming_client.INamingClient 实例。

• configClient: 持有一个 Nacos 官方的 config_client.IConfigClient 实例。

• config: 保存用于初始化这两个客户端的配置信息。

• 职责:

• 实现 RemoteClient 接口的所有方法。

• 其方法的内部逻辑非常简单：将调用代理 (delegate) 给内部持有的 namingClient 或 configClient 去完成实际工作，并对返回结果进行必要的格式转换，使其符合我们自己定义的 Instance 等中立结构。

2. MCP Server 适配器 (pkg/adapter/mcpserver)

本层是连接远程数据源和网关核心业务逻辑的桥梁，负责将从 pkg/remote 获取的原始配置数据，转化为网关内部可以消费的业务对象。

2.1 适配器核心 (MCPServerAdapter)

• 结构: MCPServerAdapter 是一个结构体。

核心字段:

• remoteClient: 持有一个 remote.RemoteClient 接口实例，它不知道底层是 Nacos 还是其他实现。

• dynamicRegistry: 持有一个指向 DynamicToolRegistry 的指针，用于将最终的工具配置更新到 MCP 过滤器中。

• listeners: 一个 map，用于管理所有 ConfigListener 实例，方便启停。

职责:

• 初始化: 通过 Apply(config) 方法接收配置，并创建出 remoteClient 实例。

• 启动: Start() 方法会启动一个发现循环，扫描 Nacos 中所有需要处理的 MCP 服务，并为每个服务创建一个 ConfigListener。

• 停止: Stop() 方法会优雅地停止所有的 ConfigListener，并关闭 remoteClient。

• 处理变更: 提供一个内部方法（如 onConfigUpdate），供 ConfigListener 回调。当收到更新时，它会调用 ConfigConverter 进行转换，并将转换后的结果应用到 DynamicToolRegistry、RouterManager 和 ClusterManager。

2.2 配置监听器 (ConfigListener)

• 结构: ConfigListener 是一个结构体，每个实例负责一个 MCP 服务的完整监听。

核心字段:

• serviceId: 标识自己正在监听哪个 MCP 服务。

• adapter: 一个指回 MCPServerAdapter 的指针，用于回调。

• stopChan: 一个 channel，用于接收停止信号。

职责:

• 封装级联监听的复杂业务流程。在其 watch() 方法中，它会：

1. 首先使用 remoteClient.ListenConfig 监听“版本文件”。

2. 在版本的回调中，取消旧监听，并创建对新的“服务规格”和“工具规格”文件的监听。

3. 在服务规格的回调中，使用 remoteClient.Subscribe 订阅后端服务的实例列表。

• 当所有相关配置（版本、规格、实例）都获取到或发生变化时，将这些零散的信息聚合成一个完整的配置快照，然后调用 adapter.onConfigUpdate 方法，将快照传递出去。

2.3 配置转换器 (ConfigConverter)

• 结构: ConfigConverter 是一个无状态的工具类结构体，只包含方法。

职责:

负责数据模型的转换。

核心方法:

• ConvertToInternalModels(snapshot AggregatedConfig) (*InternalModels, error):

• 接收 ConfigListener 聚合好的配置快照 AggregatedConfig。

• 将快照中的各类 JSON/YAML 字符串，解析并转换为网关内部的强类型业务对象，如 []mcpserver.Tool、model.Router、model.Cluster。

• 将这些转换好的对象打包成 InternalModels 结构体返回。

3. 集成点设计

3.1 与 MCP Filter 集成 (DynamicToolRegistry)

目标: 让 MCP 过滤器能动态地感知工具的变化。

实现:

• 我们将改造现有的 ToolRegistry，使其成为 DynamicToolRegistry。

• 它将提供一个线程安全的方法：UpdateTools(adapterId string, tools []mcpserver.Tool)。

• MCPServerAdapter 在转换出新的工具列表后，会调用此方法。DynamicToolRegistry 内部会使用读写锁 (sync.RWMutex) 来安全地替换内存中的工具列表。

3.2 路由与集群管理集成

目标: 动态地创建、更新或删除与 MCP 工具相关的路由和后端集群。

实现:

• MCPServerAdapter 在调用 ConfigConverter 得到 model.Router 和 model.Cluster 对象后，将直接调用网关全局的管理器：

• server.GetRouterManager().AddRouter(router)

• server.GetClusterManager().SetCluster(cluster)

• 这些管理器已经具备了处理动态更新的能力，我们只需将正确的配置喂给它们即可。