企业官网建设流程全解析

1. 为什么要在 Spring AI 智能体里接 MCP 读本地文件

如果你正在用 Spring AI 写智能体，大概率会遇到一个很具体的需求：让模型能读本地目录里的文件，比如项目文档、日志、配置、Markdown 笔记，然后基于这些内容回答问题。传统做法是自己写一堆@Tool方法，把FileReader、Files.walk包一层，再手动注册到ChatClient。能跑，但每换一个数据源就要重写一遍，工具描述、参数 schema、错误处理全得自己维护。

MCP（Model Context Protocol）解决的正是这件事。它把「模型怎么连数据源和工具」抽象成一套标准协议，本地文件系统、数据库、远程服务都可以各自实现一个 MCP Server，Spring AI 应用作为 MCP Client 去发现并调用这些工具。你不再关心文件怎么读，只关心「有哪些工具可用」，剩下的交给协议。

这篇要落地的链路是：Spring AI 智能体 → MCP Client → 本地 filesystem MCP Server → 读取本地文件数据 → 模型基于文件内容回答。同时把模型调用通道统一到 TaoToken 的 Key 上，这样你本地调试、换模型、跑 Agent 都不用改业务代码，只改配置。适合已经写过 Spring Boot、想快速把 MCP 跑通、又不想在模型接入上反复折腾的开发者。

我试过把模型 Key 散落在环境变量、application.yml、IDE 运行配置里，最后自己都记不清哪个生效。统一到一个 Key 通道之后，排障成本明显下降，这也是下面配置骨架的出发点。

2. TaoToken 前置：统一 Key 与 API 通道

在写 MCP 之前，先把模型通道固定下来。TaoToken 提供统一的 API 入口，Spring AI 侧只需要配置base-url和api-key两个值，就能对接模型对话能力。官网地址是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 入口是 https://taotoken.net/api 。

你需要先拿到一个 Key。进入控制台创建：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，然后在 API Keys 页面生成：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。生成后复制保存，后面配置里会用到。

这里有个概念要分清：MCP 负责「工具和数据源」，TaoToken 负责「模型调用通道」。两者是正交的。你完全可以用 MCP 读文件，用 TaoToken 调模型，互不干扰。很多新手会把这两件事混在一起，以为接了 MCP 就不用管模型 Key 了，其实 MCP Server 本身不调模型，它只暴露工具。

配置上我建议分两层：一层是模型通道（TaoToken），一层是 MCP Server 启动参数。下面分别给出settings.json和config.toml两种常见形态的骨架，你可以按自己项目实际用的配置文件选一种。

3. 可复制配置：settings.json 与 config.toml 骨架

先看settings.json。这种形态常见于把 MCP Server 配置和模型配置放在一起管理的场景，比如某些客户端或工具链会读这个文件来启动 MCP Server。核心是把 filesystem server 的启动命令、参数、以及模型通道的 base url 写清楚。

{ "mcpServers": { "filesystem": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/workspace/docs" ], "env": { "MCP_LOG_LEVEL": "info" } } }, "model": { "baseUrl": "https://taotoken.net/api", "apiKey": "sk-你的TaoTokenKey", "modelName": "claude-3-5-sonnet" } }

注意args最后那个路径就是 MCP Server 能访问的根目录，它决定了智能体能读哪些文件。不要一上来就写/或整个用户目录，权限太大，调试时也容易误读无关文件。先限定到一个具体目录，跑通再按需放宽。

再看config.toml。如果你的项目用 TOML 管理配置，等价骨架如下：

[mcp_servers.filesystem] command = "npx" args = ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/workspace/docs"] [model] base_url = "https://taotoken.net/api" api_key = "sk-你的TaoTokenKey" model_name = "claude-3-5-sonnet"

两种配置的语义完全一致，区别只是格式。关键点有三个：command必须是本地能执行的命令，args里的路径必须是绝对路径，api_key用你刚才在控制台生成的那个。如果你把 Key 直接写进文件，记得别提交到 Git，用.gitignore排除，或者改成读环境变量。

Spring AI 侧对应的application.yml大致是这样，把模型通道指向 TaoToken：

spring: ai: openai: base-url: https://taotoken.net/api api-key: ${TAOTOKEN_API_KEY} chat: options: model: claude-3-5-sonnet

这里用${TAOTOKEN_API_KEY}从环境变量读，比硬编码安全。启动前export TAOTOKEN_API_KEY=sk-你的Key即可。

4. 端到端验证：一次本地文件检索

配置写完，必须验证。分两步：先确认 MCP Server 能起来并列出工具，再确认 Spring AI 智能体能通过 MCP 读到文件内容。

第一步，单独启动 filesystem server，确认工具列表。在终端执行：

npx -y @modelcontextprotocol/server-filesystem /Users/yourname/workspace/docs

如果 Node 环境正常，它会以 stdio 方式启动并等待输入。这一步能跑起来，说明npx和包名没问题。如果卡住不动，通常是网络拉包慢，或者路径不存在。

第二步，在 Spring AI 里初始化McpSyncClient并列出工具。核心代码：

@Bean(destroyMethod = "close") public McpSyncClient mcpClient() { var stdioParams = ServerParameters.builder("npx") .args("-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/workspace/docs") .build(); var mcpClient = McpClient.sync( new StdioServerTransport(stdioParams), Duration.ofSeconds(10), new ObjectMapper()); var init = mcpClient.initialize(); System.out.println("MCP Initialized: " + init); return mcpClient; }

启动后控制台会打印初始化结果，里面包含 server 信息和协议版本。接着把工具适配成 Spring AI 的 function callback：

@Bean public List<McpFunctionCallback> functionCallbacks(McpSyncClient mcpClient) { return mcpClient.listTools(null) .tools() .stream() .map(tool -> new McpFunctionCallback(mcpClient, tool)) .toList(); }

然后注入到ChatClient：

var chatClient = chatClientBuilder .defaultFunctions(functionCallbacks) .build();

第三步，发一个真实问题，让模型去读文件。比如目录里放一个notes.md，内容是「本周待办：修复登录超时」。然后提问：

String answer = chatClient.prompt() .user("读取 notes.md，告诉我本周待办是什么") .call() .content(); System.out.println(answer);

成功的结果是：模型先触发 function call，McpClient通过 stdio 把请求转给 filesystem server，server 读取文件返回内容，模型再基于内容生成回答，控制台输出类似「本周待办是修复登录超时」。整个过程你不需要在业务代码里写任何文件读取逻辑。

如果你想单独验证模型通道是否通，可以先用模型对话页面发一条消息：https://taotoken.net/model-chat?utm_source=taotoken_aicg_blog_end&utm_content=model-chat&utm_campaign=rewrite 。通道正常再回来跑 MCP，能快速区分是模型问题还是 MCP 问题。

5. 本篇常见错排查

报错一：npx: command not found。说明本地没装 Node/npm。装完之后npm install -g npx，再重试。这是最常见的第一个坑，尤其在干净的容器或新机器上。

报错二：MCP 初始化超时。McpClient.sync的第二个参数是超时时间，默认给 10 秒。如果npx首次拉包慢，会超时。解决办法是先手动在终端跑一次npx -y @modelcontextprotocol/server-filesystem <path>，把包缓存下来，再启动应用。

报错三：文件访问权限问题。在 IDE 里运行时，进程工作目录可能不是你以为的那个目录，导致相对路径解析错误。统一用绝对路径，并且确认该路径对当前进程可读。如果路径写错，server 会启动但工具调用返回空或报错。

报错四：模型不触发 function call。检查defaultFunctions是否真的注入了 callback 列表。如果列表为空，说明listTools没拿到工具，回到第二步看初始化日志。另外，模型本身要支持 function calling，选一个支持的工具调用模型。

报错五：Key 无效或 401。确认base-url是https://taotoken.net/api，没有多余斜杠；确认 Key 是从控制台新生成的、没有空格。如果还是 401，去 API Keys 页面重新生成一个再试。

报错六：改了配置不生效。Spring Boot 配置有优先级，环境变量、application.yml、IDE 运行配置可能互相覆盖。排查时打印实际生效的base-url，别靠猜。

6. 继续往下走：Coding Plan 与接入文档

跑通上面这条链路之后，你手里就有了一个能读本地文件的 Spring AI 智能体。接下来通常会往两个方向走：一是把它变成长期运行的编码助手或 Agent，二是接入更多 MCP Server 扩展能力。

如果你要做长期编码或 Agent 场景，建议看一下 Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，它更适合持续调用、多轮工具编排的用法。接入细节和参数说明在文档里：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，遇到协议或字段问题先查文档再动手改代码。

最后一个实用建议：把 MCP Server 的根目录当成「最小权限边界」来管理。每接一个新数据源，先想清楚它该暴露哪个目录、哪些工具，再写进配置。这样后面接数据库、接远程服务时，权限模型是一致的，排障也有迹可循。