1. Spring Boot 里把文件操作收口到 MCP Server 的落地思路如果你正在写 Java 后端又想让 OpenCode 这类编码智能体通过标准协议调用你系统里的能力那 Spring Boot 接入 OpenCode 实现 MCP Server 就是一条很顺的路径。MCPModel Context Protocol本质上是给智能体定义一套「工具清单 调用约定」智能体不直接碰你的数据库或文件系统而是通过你暴露的接口来干活。这篇聚焦的场景很具体在 Spring Boot 项目里搭一个 MCP Server把文件名的模糊搜索能力包装成工具再让 OpenCode 以 remote 方式连上来联调验证。适合谁看有 Spring Boot 基础、想在 Java 后端暴露 MCP 能力的开发者正在用 OpenCode 做编码或文档助手、希望它调用自有工具的人以及想给智能体加一层「操作收口」、避免它直接对文件做 CRUD 的团队。核心检索词就三个spring boot、opencode、mcp server。下面从依赖、配置、工具类、OpenCode 侧配置到连通性验证一步步给可复制的片段。我试过把文件读写直接交给智能体结果它绕过业务校验乱改文件后来改成所有文件操作都走 MCP 工具行为才可控。所以这篇的重点不是「能连上」而是「连上之后调用链清晰、可验证」。2. TaoToken 前置统一 Key 与 API 通道在动手写 MCP Server 之前先把模型调用这条链路准备好。OpenCode 本身要连大模型如果你希望 Key 管理、模型切换、额度查看都在一个地方完成可以用 TaoToken 作为统一入口。它的官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 这个不加 UTM。你需要先拿到一个可用的 Key再去控制台确认通道状态。具体动作打开模型对话页 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 先确认目标模型能正常对话避免后面联调时把「模型不通」误判成「MCP 不通」。进控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 看额度与通道。到 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 生成 Key复制保存。注意Key 只放在本地环境变量或配置文件里不要提交到 Git 仓库。联调阶段建议单独建一个测试 Key方便随时吊销。如果你后面要长期跑编码任务或 Agent 流程可以了解 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 把额度规划好再上量。接入细节和参数说明在文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里遇到字段不确定时以文档为准。3. 可复制配置pom 依赖、application.yml 与工具类3.1 环境与依赖环境信息先对齐OpenCode Windows 版本 1.3.6从官网下载页获取Spring Boot 4.0.0JDK 17。MCP Server 的 starter 用 Spring AI 提供的 webmvc 版本dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-mcp-server-webmvc/artifactId version2.0.0-M4/version scopecompile/scope /dependency这个 starter 负责把 MCP 协议端点挂到 Spring MVC 上你只需要声明工具方法并加注解框架会完成协议编解码和工具注册。3.2 application.yml 配置骨架spring: ai: mcp: server: protocol: STREAMABLE name: mcp-server version: 1.0.0 # type: ASYNC instructions: This stateless server is optimized for cloud deployments streamable-http: mcp-endpoint: /mcp capabilities: tool: true completion: true tool-change-notification: true几个关键点protocol: STREAMABLE对应可流式传输的 HTTP 端点mcp-endpoint: /mcp决定了 OpenCode 侧要填的 URL 路径capabilities.tool: true打开工具能力completion和tool-change-notification按需开启。type: ASYNC这行被注释掉了先用默认同步模式跑通再考虑异步。3.3 工具类把文件搜索包成 MCP Tool工具方法用McpTool标注参数用McpToolParam描述描述文字会直接暴露给智能体所以写清楚用途和可选性很重要。Slf4j public class FileTools { Autowired private EverythingService everythingService; /** * 文件名模糊查询 * 通过 Everything 搜索文件名中包含关键词的文件 */ McpTool(description 根据关键词模糊搜索文件名返回匹配的文件列表包含路径、大小、修改日期等信息) public ListFileInfoResult searchFilesByName( McpToolParam(description 搜索关键词支持文件名模糊匹配) String keyword, McpToolParam(description 限定搜索的目录路径可选不填则搜索所有位置) String path, McpToolParam(description 返回结果数量限制可选默认50) Integer count) { log.info(文件名模糊查询keyword{}, path{}, count{}, keyword, path, count); ListEverythingSearchResult.FileResult results everythingService.searchByName(keyword, path, count); return results.stream() .map(FileInfoResult::fromFileResult) .collect(Collectors.toList()); } }这里的设计意图是智能体不直接读文件系统而是通过searchFilesByName这类工具拿结果。底层用 Everything 做文件名和内容的模糊搜索Everything 版本 V1.5.0.1408a (x64)开启 HTTP 访问后通过远程调用方式访问即可。这样搜索性能和索引质量都由 Everything 保证你的 Spring Boot 只做协议适配和结果转换。提示count参数建议在服务层兜底一个默认值比如 50避免智能体不传时返回全量结果把上下文撑爆。4. OpenCode 侧配置与联调验证4.1 配置 OpenCode 连接 MCP Server先加环境变量指向 OpenCode 的配置文件OPENCODE_CONFIGE:\Users\AppData\Local\OpenCode\opencode.json然后在opencode.json里声明 remote 类型的 MCP Server{ $schema: https://opencode.ai/config.json, mcp: { testMcp: { type: remote, url: http://127.0.0.1:8080/mcp, enabled: true } }, agent: { build: { prompt: 你是一个智能助手集成在文档系统中。\n\n重要规则\n1. 当用户询问关于文档、文件、知识库相关的问题时优先使用 files/get_knowledge_context 工具获取上下文。\n2. 只有在 knowledge_context 返回空或信息不足时才使用其他搜索工具。\n3. 文件读取、写入、删除等操作必须通过 files 系列工具执行。\n4. 高风险操作写入、删除会触发用户确认请等待确认后再执行。 } } }type: remote表示走 HTTP 远程连接url指向你 Spring Boot 启动后的 MCP 端点。agent.build.prompt里把「文件操作必须通过工具执行」写成硬规则配合前面的工具收口智能体就不会绕过 MCP 直接动文件。4.2 启动日志与连通性验证先启动 Spring Boot 应用观察日志里 MCP 端点是否注册成功。正常情况下你会看到类似「Registered MCP endpoint /mcp」以及工具注册的日志。如果没看到工具注册信息多半是McpTool所在类没被扫描到检查包路径和Component/Service注解。接着做接口连通性验证。用 curl 直接打端点确认服务在监听curl -i -X POST http://127.0.0.1:8080/mcp \ -H Content-Type: application/json \ -d {jsonrpc:2.0,id:1,method:tools/list,params:{}}如果返回里能看到searchFilesByName这个工具名和它的参数描述说明工具已经成功暴露。这一步很关键它把「Spring Boot 起没起」和「MCP 工具注册没注册」两件事分开了排障时不会混在一起。最后在 OpenCode 里发起一次真实调用让它搜索某个关键词的文件。观察 Spring Boot 控制台是否打印文件名模糊查询keyword...这行日志。日志出现且返回结果合理整条链路就通了OpenCode → MCP 端点 → FileTools → Everything → 结果回传。5. 本篇常见错排查端点 404 或连接被拒。先确认mcp-endpoint配的是/mcpOpenCode 的url拼的是http://127.0.0.1:8080/mcp端口和路径都要对上。Spring Boot 默认端口 8080如果你改过server.port两边要同步。工具列表为空。检查capabilities.tool是否为 true工具类是否被 Spring 扫描到McpTool方法是否为 public。starter 版本和 Spring Boot 版本不匹配也会导致注解不生效2.0.0-M4是里程碑版本注意和 Spring Boot 4.0.0 的兼容性。调用工具报参数错误。McpToolParam的 description 只是给智能体看的提示不参与校验。如果智能体传了 null 的count服务层要能兜底。建议在searchByName里对count做默认值处理。Everything 搜不到结果。确认 Everything 已开启 HTTP 访问且服务在运行everythingService的远程调用地址正确。Everything 没建索引时搜索结果会为空先在 Everything 客户端里手动搜一次确认索引正常。OpenCode 读不到配置。OPENCODE_CONFIG环境变量要指向实际存在的 json 文件路径里的反斜杠在 Windows 下注意转义。改完配置后重启 OpenCode 进程配置不会热加载。6. 继续把链路用起来链路跑通后下一步通常是补更多工具文件读取、写入、删除都按同样的McpTool模式包进来让智能体的所有文件操作都经过你的业务校验。模型侧如果要做多模型切换或统一额度管理回到模型对话 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 验证目标模型Key 在 API Keys https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 管理接入参数以文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 为准。如果你打算让 OpenCode 长期跑编码或 Agent 任务Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 能把额度规划清楚避免联调中途断流。