Solon-AI 的 MCP 协议支持

Solon-AI 的 MCP 协议支持

【免费下载链接】solon-ai Java AI & MCP 应用开发框架（LLM，Function Call，RAG，Embedding，Reranking，Flow，MCP Server，Mcp Client，Mcp Proxy）。同时兼容 java8 ~ java24。也可嵌入到 SpringBoot2、jFinal、Vert.x 等框架中使用。 项目地址: https://gitcode.com/opensolon/solon-ai

文章概要介绍了 Solon-AI 的 MCP（Model Context Protocol）协议，这是一种专为 AI 模型与服务器之间高效通信设计的协议。MCP 协议通过标准化的 JSON-RPC 格式实现消息交换，支持同步和异步操作，旨在为开发者提供灵活、可扩展的接口。文章详细介绍了 MCP 协议的简介、设计目标、关键组件以及交互流程示例。

MCP 协议简介与设计目标

Model Context Protocol (MCP) 是一种专为 AI 模型与服务器之间高效通信设计的协议。它通过标准化的 JSON-RPC 格式实现消息交换，支持同步和异步操作，旨在为开发者提供灵活、可扩展的接口，以便在 AI 应用中集成和管理模型功能。

协议简介

MCP 协议的核心目标是为 AI 模型与服务器之间的交互提供统一的通信框架。它定义了以下关键组件：

1. 传输层：支持多种传输方式（如 HTTP、SSE、Stdio），确保协议在不同环境下均可运行。
2. 会话管理：通过 McpSession 和 McpServerSession 管理客户端与服务器之间的会话状态。
3. 功能暴露：服务器可以通过 McpServer 暴露工具（Tools）、资源（Resources）和提示（Prompts），供 AI 模型调用。
4. 错误处理：内置标准错误码和异常处理机制，确保通信的可靠性。

以下是一个简化的 MCP 协议交互流程示例：

设计目标

MCP 协议的设计围绕以下目标展开：

1. 标准化：通过 JSON-RPC 格式统一消息交换，减少协议实现的复杂性。
2. 灵活性：支持同步和异步操作，适应不同场景的需求。
3. 可扩展性：通过模块化设计（如 McpServerFeatures 和 McpClientFeatures）支持功能扩展。
4. 高效性：优化传输层（如 SSE 心跳机制），确保低延迟和高吞吐量。

关键特性

特性	描述
多传输支持	支持 HTTP、SSE、Stdio 等多种传输方式。
会话管理	提供会话状态管理和心跳机制，确保连接稳定性。
功能暴露	服务器可动态注册工具、资源和提示，供客户端调用。
错误处理	内置标准错误码和异常处理机制，便于调试和维护。

以下是一个 MCP 服务器的功能模块示意图：

通过以上设计，MCP 协议为 AI 模型与服务器之间的交互提供了高效、可靠的解决方案。

MCP Server 端实现

MCP（Model Context Protocol）是 Solon-AI 的核心协议之一，用于支持 AI 模型的上下文管理。MCP Server 端实现负责处理客户端的请求，管理资源、提示和工具，并提供高效的通信机制。以下将详细介绍 MCP Server 端的关键实现细节。

核心类与功能

1. McpServerContext
   继承自 ContextEmpty，提供会话上下文管理功能，包括会话 ID、IP 地址、协议信息等。

   public class McpServerContext extends ContextEmpty {
       @Override public String sessionId() { /* ... */ }
       @Override public String realIp() { /* ... */ }
   }
   

2. McpServerProperties
   存储 MCP Server 的配置属性，如名称、版本、通道等。

   public class McpServerProperties {
       public String getName() { /* ... */ }
       public void setName(String name) { /* ... */ }
   }
   

3. McpServerEndpointProvider
   实现 LifecycleBean 接口，管理 MCP Server 的生命周期（启动、停止）。

   public class McpServerEndpointProvider implements LifecycleBean {
       @Override public void start() { /* ... */ }
       @Override public void stop() { /* ... */ }
   }
   

4. McpServerSession
   管理服务器端会话，包括会话 ID 和传输层。

   public class McpServerSession implements McpSession {
       public String getId() { /* ... */ }
       public void init(ClientCapabilities clientCapabilities, Implementation clientInfo) { /* ... */ }
   }
   

5. McpSyncServer 与 McpAsyncServer

   • McpSyncServer：同步处理客户端请求，支持工具、资源和提示的增删改查。

     public class McpSyncServer {
         public void addTool(SyncToolSpecification toolHandler) { /* ... */ }
         public void removeTool(String toolName) { /* ... */ }
     }
     

   • McpAsyncServer：异步处理客户端请求，支持非阻塞操作。

     public class McpAsyncServer {
         public void close() { /* ... */ }
     }
     

传输层实现

MCP Server 支持多种传输协议，包括 SSE（Server-Sent Events）和 Stdio（标准输入输出）。

1. SSE 传输 (WebRxSseServerTransportProvider)
   通过 HTTP 提供 SSE 支持，用于实时通信。

   public class WebRxSseServerTransportProvider implements McpServerTransportProvider {
       public void sendHeartbeat() { /* ... */ }
       public void handleSseConnection(Context ctx) { /* ... */ }
   }
   

2. Stdio 传输 (StdioServerTransportProvider)
   通过标准输入输出与客户端通信，适用于本地调试。

   public class StdioServerTransportProvider implements McpServerTransportProvider {
       @Override public void setSessionFactory(McpServerSession.Factory sessionFactory) { /* ... */ }
   }
   

资源与工具管理

MCP Server 提供了资源、提示和工具的管理机制，通过以下类实现：

1. ResourceMcpServerManager
   管理资源（如文件、API 端点）的增删改查。

   public class ResourceMcpServerManager implements McpServerManager<FunctionResource> {
       @Override public void add(McpSyncServer server, SyncSpecification spec, McpServerProperties props, FunctionResource resource) { /* ... */ }
   }
   

2. ToolMcpServerManager
   管理工具（如外部服务调用）的注册与调用。

   public class ToolMcpServerManager implements McpServerManager<FunctionTool> {
       @Override public void add(McpSyncServer server, SyncSpecification spec, McpServerProperties props, FunctionTool tool) { /* ... */ }
   }
   

3. PromptMcpServerManager
   管理提示（如 AI 模型的输入模板）的配置与调用。

   public class PromptMcpServerManager implements McpServerManager<FunctionPrompt> {
       @Override public void add(McpSyncServer server, SyncSpecification spec, McpServerProperties props, FunctionPrompt prompt) { /* ... */ }
   }
   

状态图示例

以下是一个简化的 MCP Server 状态图，展示了会话的生命周期：

总结

MCP Server 端实现通过核心类、传输层和管理机制，提供了高效的上下文管理能力。无论是同步还是异步操作，均能灵活应对客户端需求，确保 AI 模型的稳定运行。

MCP Client 端实现

Solon-AI 的 MCP（Model Context Protocol）协议支持为开发者提供了强大的客户端实现能力，支持同步和异步两种模式。MCP Client 端实现的核心目标是简化与 MCP 服务器的交互，提供高效、灵活的 API 调用方式。以下将从客户端配置、核心类、同步与异步模式等方面详细介绍 MCP Client 的实现细节。

客户端配置

MCP Client 的配置通过 McpClientProperties 类实现，支持以下关键配置项：

配置项	类型	描述
name	String	客户端名称，用于标识客户端实例。
version	String	客户端版本号。
channel	String	客户端所属的通道标识。
apiUrl	String	MCP 服务器的 API 地址。
apiKey	String	访问 MCP 服务器的认证密钥。
headers	Map<String, String>	自定义请求头。
httpTimeout	HttpTimeout	HTTP 请求超时设置。
httpProxy	Proxy	HTTP 代理配置。
requestTimeout	Duration	请求超时时间。
heartbeatInterval	Duration	心跳间隔时间，用于保持长连接。

示例配置代码：

McpClientProperties properties = new McpClientProperties();
properties.setName("MyClient");
properties.setVersion("1.0.0");
properties.setApiUrl("https://mcp.example.com/api");
properties.setApiKey("your-api-key");
properties.setRequestTimeout(Duration.ofSeconds(30));

核心类

1. McpClientProvider

McpClientProvider 是 MCP Client 的核心类，负责管理客户端与服务器的连接、资源调用和工具调用。其主要功能包括：

• 提供工具调用接口（callToolAsText、callToolAsImage）。
• 提供资源读取接口（readResourceAsText）。
• 支持动态配置日志级别（setLoggingLevel）。

示例代码：

McpClientProvider provider = McpClientProvider.builder()
    .name("MyClient")
    .version("1.0.0")
    .apiUrl("https://mcp.example.com/api")
    .build();

Text result = provider.callToolAsText("toolName", Map.of("param", "value"));

2. McpSyncClient 与 McpAsyncClient

MCP Client 支持同步和异步两种调用模式：

• 同步模式：通过 McpSyncClient 实现，适用于简单的请求-响应场景。
• 异步模式：通过 McpAsyncClient 实现，适用于高并发或需要非阻塞调用的场景。

同步模式示例：

McpSyncClient client = McpClient.sync()
    .requestTimeout(Duration.ofSeconds(10))
    .build();

ListPromptsResult prompts = client.listPrompts();

异步模式示例：

McpAsyncClient client = McpClient.async()
    .requestTimeout(Duration.ofSeconds(10))
    .build();

Mono<ListPromptsResult> promptsMono = Mono.from(client.listPrompts());

同步与异步模式对比

特性	同步模式 (McpSyncClient)	异步模式 (McpAsyncClient)
调用方式	阻塞式	非阻塞式
适用场景	简单请求	高并发或复杂请求
性能	较低	较高
代码复杂度	简单	较复杂

传输层实现

MCP Client 支持多种传输协议，包括：

1. Stdio 传输：通过标准输入输出与服务器通信，适用于本地调试或 CLI 工具。
2. WebRx SSE 传输：基于 Server-Sent Events (SSE) 的长连接协议，适用于实时通信场景。

示例配置 SSE 传输：

WebRxSseClientTransport transport = WebRxSseClientTransport.builder()
    .sseEndpoint("https://mcp.example.com/sse")
    .build();

McpClientProvider provider = McpClientProvider.builder()
    .transport(transport)
    .build();

状态图

以下为 MCP Client 的状态图，展示了客户端从初始化到关闭的生命周期：

通过以上实现，MCP Client 提供了灵活、高效的客户端支持，能够满足不同场景下的需求。

MCP Proxy 与工具链

Solon-AI 的 MCP 协议支持为开发者提供了强大的工具链和代理功能，帮助用户高效地管理和扩展 MCP 协议的应用场景。本节将深入探讨 MCP Proxy 的核心功能、工具链的组成以及如何通过这些工具实现高效的协议管理。

MCP Proxy 的核心功能

MCP Proxy 是 Solon-AI 中用于管理和转发 MCP 协议请求的核心组件。它提供了以下关键功能：

1. 请求转发：MCP Proxy 能够将客户端的请求转发到后端服务，支持负载均衡和故障转移。
2. 协议转换：支持将 MCP 协议转换为其他协议（如 HTTP、gRPC），便于与异构系统集成。
3. 安全认证：提供基于 Token 或 OAuth2 的认证机制，确保请求的安全性。
4. 日志与监控：记录请求日志，并提供监控接口，便于排查问题和优化性能。

以下是一个 MCP Proxy 的流程图示例：

工具链组成

Solon-AI 的工具链为 MCP Proxy 提供了丰富的支持，主要包括以下组件：

工具名称	功能描述
mcp-cli	命令行工具，用于快速测试和调试 MCP 协议请求。
mcp-dashboard	可视化面板，提供实时监控和日志查看功能。
mcp-converter	协议转换工具，支持将 MCP 协议转换为其他格式（如 JSON、YAML）。
mcp-auth	认证工具，用于生成和管理 Token，支持 OAuth2 集成。
mcp-logger	日志工具，记录请求和响应数据，支持导出为多种格式。

代码示例

以下是一个使用 mcp-cli 工具发送 MCP 请求的示例：

# 发送一个简单的 MCP 请求
mcp-cli --host localhost --port 8080 --request "{\"action\": \"ping\"}"

工具链的集成

Solon-AI 的工具链支持与现有系统无缝集成。例如，可以通过以下方式将 mcp-converter 集成到 CI/CD 流程中：

# 在 CI 流程中转换协议
mcp-converter --input mcp_request.mcp --output json --file request.json

性能优化建议

为了充分发挥 MCP Proxy 和工具链的性能，建议：

1. 启用缓存：对频繁请求的数据启用缓存，减少后端压力。
2. 负载均衡：使用多实例部署 MCP Proxy，并通过负载均衡器分发请求。
3. 日志分级：根据需求设置日志级别，避免过多日志影响性能。

通过以上工具和优化建议，开发者可以高效地利用 MCP Proxy 和工具链，实现协议的灵活管理和高性能转发。

总结

Solon-AI 的 MCP 协议支持为开发者提供了强大的工具链和代理功能，帮助用户高效地管理和扩展 MCP 协议的应用场景。通过 MCP Proxy 的核心功能（如请求转发、协议转换、安全认证和日志监控）以及丰富的工具链（如 mcp-cli、mcp-dashboard 等），开发者可以实现协议的灵活管理和高性能转发。文章还提供了性能优化建议，如启用缓存、负载均衡和日志分级，以充分发挥 MCP Proxy 和工具链的性能优势。

【免费下载链接】solon-ai Java AI & MCP 应用开发框架（LLM，Function Call，RAG，Embedding，Reranking，Flow，MCP Server，Mcp Client，Mcp Proxy）。同时兼容 java8 ~ java24。也可嵌入到 SpringBoot2、jFinal、Vert.x 等框架中使用。 项目地址: https://gitcode.com/opensolon/solon-ai