Spring AI 智能体通过 MCP 集成本地文件数据

白燕子 發表於 2025-2-5 14:08:00

Spring AI 智能体通过 MCP 集成本地文件数据

作者：刘军
<h2 id="modelcontext-protocolmcp简介">Model Context Protocol（MCP）简介</h2>
模型上下文协议（即 Model Context Protocol，MCP） [ 1] 是一个开放协议，它规范了应用程序如何向大型语言模型（LLM）提供上下文。MCP 提供了一种统一的方式将 AI 模型连接到不同的数据源和工具，它定义了统一的集成方式。在开发智能体（Agent）的过程中，我们经常需要将将智能体与数据和工具集成，MCP 以标准的方式规范了智能体与数据及工具的集成方式，可以帮助您在 LLM 之上构建智能体（Agent）和复杂的工作流。
目前已经有大量的服务接入并提供了 MCP server 实现 [ 2] ，当前这个生态正在以非常快的速度不断的丰富中。
<h2 id="springai-mcp-简介">Spring AI MCP 简介</h2>
Spring AI MCP 为模型上下文协议提供 Java 和 Spring 框架集成。它使 Spring AI 应用程序能够通过标准化的接口与不同的数据源和工具进行交互，支持同步和异步通信模式。
<img src="https://img2024.cnblogs.com/blog/1411156/202502/1411156-20250205140351253-1213789530.png">
Spring AI MCP 采用模块化架构，包括以下组件：
<ul>
<li>Spring AI 应用程序：使用 Spring AI 框架构建想要通过 MCP 访问数据的生成式 AI 应用程序</li>
<li>Spring MCP 客户端：MCP 协议的 Spring AI 实现，与服务器保持 1:1 连接</li>
<li>MCP 服务器：轻量级程序，每个程序都通过标准化的模型上下文协议公开特定的功能</li>
<li>本地数据源：MCP 服务器可以安全访问的计算机文件、数据库和服务</li>
<li>远程服务：MCP 服务器可以通过互联网（例如，通过 API）连接到的外部系统</li>
</ul>
<h2 id="通过一个示例快速体验-springai-mcp">通过一个示例快速体验 Spring AI MCP</h2>
这里我们提供一个示例智能体应用，这个智能体可以通过 MCP 查询或更新本地文件系统，并以文件系统中的数据作为上下文与模型交互。次示例演示如何使用模型上下文协议（MCP）将 Spring AI 与本地文件系统进行集成。
示例完整源码 [ 3] ：https://github.com/springaialibaba/spring-ai-alibaba-examples/spring-ai-alibaba-mcp-example
<h3 id="示例架构源码说明">示例架构（源码说明）</h3>
前文中我们讲解了 Spring AI 与 MCP 集成的基础架构，在接下来的示例中，我们将用到以下关键组件：
<ol>
<li>
MCP Client，与 MCP 集成的关键，提供了与本地文件系统进行交互的能力。
</li>
<li>
Function Callbacks，Spring AI MCP 的 function calling 声明方式。
</li>
<li>
Chat Client，Spring AI 关键组件，用于 LLM 模型交互、智能体代理。
</li>
</ol>
声明 ChatClient
<pre><code>// List<McpFunctionCallback> functionCallbacks;
var chatClient = chatClientBuilder.defaultFunctions(functionCallbacks).build();
</code></pre>
和开发之前的 Spring AI 应用一样，我们先定义一个 ChatClient Bean，用于与大模型交互的代理。需要注意的是，我们为 ChatClient 注入的 functions 是通过 MCP 组件（McpFunctionCallback）创建的。
接下来让我们具体看一下 McpFunctionCallback 是怎么使用的。
声明 MCP Function Callbacks
以下代码段通过 mcpClient与 MCP server 交互，将 MCP 工具通过 McpFunctionCallback 适配为标准的 Spring AI function。
<ol>
<li>发现 MCP server 中可用的工具 tool（Spring AI 中叫做 function）列表。</li>
<li>依次将每个 tool 转换成 Spring AI function callback。</li>
<li>最终我们会将这些 McpFunctionCallback 注册到 ChatClient 使用。</li>
</ol>
<pre><code>@Bean
public List<McpFunctionCallback> functionCallbacks(McpSyncClient mcpClient) {
return mcpClient.listTools(null)
 .tools()
 .stream()
 .map(tool -> new McpFunctionCallback(mcpClient, tool))
 .toList();
}
</code></pre>
可以看出，ChatClient 与模型交互的过程是没有变化的，模型在需要的时候告知 ChatClient 去做函数调用，只不过 Spring AI 通过 McpFunctionCallback 将实际的函数调用过程委托给了 MCP，通过标准的 MCP 协议与本地文件系统交互：
<ul>
<li>在与大模交互的过程中，ChatClient 处理相关的 function calls 请求</li>
<li>ChatClient 调用 MCP 工具（通过 McpClient）</li>
<li>McpClient 与 MCP server（即 filesystem）交互</li>
</ul>
初始化 McpClient
该智能体应用使用同步 MCP 客户端与本地运行的文件系统 MCP server 通信：
<pre><code>@Bean(destroyMethod = "close")
public McpSyncClient mcpClient() {
var stdioParams = ServerParameters.builder("npx")
 .args("-y", "@modelcontextprotocol/server-filesystem", "path))
 .build(); // 1

var mcpClient = McpClient.sync(new StdioServerTransport(stdioParams),
 Duration.ofSeconds(10), new ObjectMapper()); //2

var init = mcpClient.initialize(); // 3
System.out.println("MCP Initialized: " + init);

return mcpClient;
}
</code></pre>
在以上代码中：
<ol>
<li>
配置 MCP server 启动命令与参数。
</li>
<li>
初始化 McpClient：关联 MCP server、指定超时时间等。
</li>
<li>
Spring AI 会使用 npx -y @modelcontextprotocol/server-filesystem "/path/to/file"在本地机器创建一个独立的子进程（代表本地 Mcp server），Spring AI 与 McpClient 通信，McpClient 进而通过与 Mcp server 的连接操作本地文件。
</li>
</ol>
<h3 id="运行示例">运行示例</h3>
前提条件
<ol>
<li>安装 npx（Node Package eXecute）</li>
</ol>
首先确保本地机器安装了 npm [ 4] ，然后运行如下命令：
<pre><code>npm install -g npx
</code></pre>
<ol start="2">
<li>下载示例源码</li>
</ol>
<pre><code>git clone https://github.com/springaialibaba/spring-ai-alibaba-examples.git
cd spring-ai-alibaba-examples/spring-ai-alibaba-mcp-example/filesystem
</code></pre>
<ol start="3">
<li>设置环境变量</li>
</ol>
<pre><code># 通义大模型 Dashscope API-KEY
export AI_DASHSCOPE_API_KEY=${your-api-key-here}
</code></pre>
<ol start="4">
<li>构建示例</li>
</ol>
<pre><code>./mvnw clean install
</code></pre>
运行示例应用
运行示例，智能体将向模型发起提问（源码中包含预置问题，可通过源码查看），可通过控制台查看输出结果。
<pre><code>./mvnw spring-boot:run
</code></pre>
如果您是在 IDE 中运行示例，并且遇到 filesystem mcp server 返回的文件访问权限问题，请确保指定当前进程工作目录为 spring-ai-alibaba-mcp-example/filesystem 目录。
<h2 id="总结">总结</h2>
MCP 作为一款开放协议，直接规范了应用程序如何向LLM提供上下文。MCP 就像是面向 AI 应用程序的 USB-C 端口，正如 USB-C 提供了一种将设备连接到各种外围设备和配件的标准化方式一样，MCP 提供了一个将 AI 模型连接到不同数据源和工具的标准化方法。
对于 Spring AI Alibaba 来说，我们将会从两个方面快速推进与 MCP 生态的集成：
<ul>
<li>在客户端，让 Spring AI 开发的智能体可以快速接入 MCP 生态中的各种 server 服务。</li>
<li>在服务端，帮助大量的 Java 服务快速转为 MCP server，通过 Spring AI Alibaba 将传统的 Spring Boot、Spring Cloud、Dubbo 等开发的单体或微服务应用发布为 MCP server。</li>
</ul>
相关链接：
 模型上下文协议（即 Model Context Protocol，MCP）
https://modelcontextprotocol.io/
 MCP server 实现
https://github.com/modelcontextprotocol/servers
 示例完整源码
https://github.com/springaialibaba/spring-ai-alibaba-examples/spring-ai-alibaba-mcp-example
 npm
https://docs.npmjs.com/downloading-and-installing-node-js-and-npm 
来源：https://www.cnblogs.com/alisystemsoftware/p/18699304

頁: [1]

琼殿技术论坛's Archiver

Spring AI 智能体通过 MCP 集成本地文件数据