1. 为什么 HSF 服务需要一层 MCP 协议转换手里跑着一堆 HSF 接口是很多后端团队的日常。HSF 作为高性能服务框架把服务注册、寻址、序列化、超时重试这些事都封装好了服务之间调用非常省心。但问题出在当你想让大模型或 Agent 去调用这些能力时LLM 生态认的是 MCPModel Context Protocol它用一套标准化的工具描述和调用约定让模型知道「有哪些工具、每个工具要什么参数、返回什么」。HSF 的接口签名、泛化调用参数、返回结构模型是看不懂的。于是就有了「HSF 转 MCP」这个需求不改动已有 HSF 服务只在外面加一层协议转换把 HSF 的接口暴露成 MCP 工具。这样后端团队不用重写业务逻辑就能让 Agent 通过 MCP 调用到存量服务。本文聚焦的就是这条链路——用 FastAPI-MCP 做协议转换工具把 HSF 泛化调用包装成 MCP 工具并给出可复制的服务骨架、配置片段和验证动作。适合已有 HSF 微服务、希望低成本接入 MCP 生态的后端同学。核心检索词先摆清楚HSF 是高性能服务框架MCP 是模型上下文协议FastAPI-MCP 是把 FastAPI 应用转成 MCP Server 的协议转换工具。三者组合起来就是「存量 HSF 服务 → FastAPI 适配层 → MCP 工具」的转换路径。2. 前置准备TaoToken 与 MCP 调用环境在写转换层之前先把「谁来调 MCP」这件事解决掉。MCP Server 本身只是暴露工具真正发起调用的是支持 MCP 的客户端或 Agent。我这边习惯用 TaoToken 作为统一的模型与工具接入入口它提供兼容的 API 地址和模型对话能力方便在本地把 MCP 工具挂上去做联调。需要提前拿到的两样东西一是 API Key。到控制台的 API Keys 页面创建一个注意 Key 只在创建时完整显示一次复制后妥善保存。地址是 https://taotoken.net/api-keys 这个页面同时能管理多个 Key建议按环境区分命名比如hsf-mcp-dev。二是接入文档。MCP 工具注册、模型对话的请求格式、鉴权头怎么写文档里都有。地址是 https://taotoken.net/doc 遇到字段对不上时优先翻这里比猜要快。注意API 基础地址用 https://taotoken.net/api 不要在后面拼多余的路径具体端点以文档为准。Key 通过请求头传递不要写进代码仓库。环境上Python 侧建议 3.10 以上FastAPI、uvicorn、httpx 是基础依赖FastAPI-MCP 用 pip 装即可。Java 侧保留原有 HSF 服务不动只需要确认泛化调用所需的接口全限定名、方法名、参数类型列表。这两边准备好转换层就能开工。3. 可复制配置FastAPI-MCP 服务骨架与 HSF 泛化调用这一节是全文重点直接给能跑的骨架。整体思路分三层最底层是 HSF 泛化调用客户端中间是 FastAPI 路由最上层用 FastAPI-MCP 把路由注册成 MCP 工具。先装依赖pip install fastapi uvicorn fastapi-mcp httpx然后是 HSF 泛化调用的封装。HSF 泛化调用不需要引入服务方的接口 jar只要知道接口名、方法名、参数类型和参数值就能发起调用。下面用一个 HTTP 网关式的封装示意实际项目里替换成你们内部的泛化调用 SDK 即可# hsf_client.py import httpx from typing import Any HSF_GATEWAY http://hsf-gateway.internal:8080/generic/invoke async def generic_invoke( interface: str, method: str, param_types: list[str], param_values: list[Any], ) - Any: HSF 泛化调用封装接口名 方法名 参数类型 参数值 payload { interface: interface, method: method, paramTypes: param_types, paramValues: param_values, } async with httpx.AsyncClient(timeout5.0) as client: resp await client.post(HSF_GATEWAY, jsonpayload) resp.raise_for_status() data resp.json() if not data.get(success): raise RuntimeError(fHSF invoke failed: {data.get(message)}) return data.get(result)接着是 FastAPI 应用和 MCP 工具注册。FastAPI-MCP 的用法很直接先建FastAPI实例再用FastApiMCP挂载它会自动把带类型注解的路由转成 MCP 工具# main.py from fastapi import FastAPI, HTTPException from fastapi_mcp import FastApiMCP from pydantic import BaseModel from hsf_client import generic_invoke app FastAPI(titleHSF-MCP Bridge) class UserQuery(BaseModel): userId: str app.post(/tools/get_user_info, operation_idget_user_info) async def get_user_info(query: UserQuery): 根据 userId 查询用户信息底层走 HSF 泛化调用 try: result await generic_invoke( interfacecom.example.user.UserInfoService, methodgetUserInfo, param_types[java.lang.String], param_values[query.userId], ) return {status: success, data: result} except Exception as e: raise HTTPException(status_code500, detailstr(e)) mcp FastApiMCP(app, namehsf-mcp-bridge) mcp.mount() if __name__ __main__: import uvicorn uvicorn.run(app, host0.0.0.0, port8000)几个关键点值得说明。operation_id会直接成为 MCP 工具名命名要清晰、避免和别的工具撞名。函数 docstring 会被当作工具描述喂给模型所以写清楚「这个工具干什么、参数含义」很重要模型靠它决定要不要调。参数用 Pydantic 模型声明FastAPI-MCP 才能推导出 JSON Schema模型才知道参数类型。参数对照可以看这张表配置项作用示例值interfaceHSF 接口全限定名com.example.user.UserInfoServicemethod方法名getUserInfoparam_types参数类型列表[java.lang.String]param_values参数值列表[123]operation_idMCP 工具名get_user_info启动服务uvicorn main:app --host 0.0.0.0 --port 80004. 验证请求拉取工具列表与一次完整调用服务起来后先确认 MCP 工具列表能拉到。FastAPI-MCP 挂载后会在应用上暴露 MCP 端点用 curl 拉一次工具清单curl -s http://localhost:8000/mcp/tools | python -m json.tool预期能看到类似结构说明get_user_info已经被注册成工具{ tools: [ { name: get_user_info, description: 根据 userId 查询用户信息底层走 HSF 泛化调用, inputSchema: { type: object, properties: {userId: {type: string}}, required: [userId] } } ] }工具列表正常后走一次完整调用链路。先直接打 FastAPI 路由确认 HSF 泛化调用通curl -X POST http://localhost:8000/tools/get_user_info \ -H Content-Type: application/json \ -d {userId: 123}预期返回{status: success, data: {userId: 123, userName: John Doe}}这一步通了说明「FastAPI → HSF 泛化调用」这段没问题。接下来验证 MCP 侧调用用支持 MCP 的客户端连上http://localhost:8000/mcp或者用 TaoToken 的模型对话能力做联调把 MCP Server 挂上去发一句「帮我查一下 userId 为 123 的用户信息」观察模型是否选中get_user_info工具、参数是否填对、返回是否被正确解析。模型对话入口在 https://taotoken.net/chat 适合做这种端到端验证。如果模型能正确调用并拿到结果整条链路就闭环了模型 → MCP 协议 → FastAPI 转换层 → HSF 泛化调用 → 存量服务。5. 本篇常见错排查实际搭的时候报错基本集中在几个地方逐个说。工具列表拉不到或为空。最常见原因是路由没加类型注解或者operation_id缺失。FastAPI-MCP 靠类型注解和 operation_id 生成工具缺一个就注册不上。检查路由函数参数是不是 Pydantic 模型operation_id有没有写。HSF 泛化调用报参数类型不匹配。HSF 泛化调用对param_types很敏感Java 的String要写成java.lang.Stringint要写java.lang.Integer基本类型和包装类型不能混。参数个数、顺序必须和方法签名严格一致多一个少一个都会失败。调用超时。HSF 网关默认超时可能偏短泛化调用链路又比直连多一跳。把httpx.AsyncClient的 timeout 调大同时确认 HSF 网关本身对泛化调用有没有单独的限流或超时配置。MCP 端点 404。确认mcp.mount()在路由注册之后调用挂载路径和客户端连接路径要一致。有些版本默认路径不是/mcp以实际启动日志打印的为准。模型不调用工具。工具描述写得太含糊模型判断不出该不该用。把 docstring 写具体参数说明清楚必要时在描述里点明「当用户询问用户信息时使用」。提示排障时优先看 FastAPI 的访问日志和 HSF 网关的调用日志两边对照能快速定位是转换层的问题还是 HSF 侧的问题。6. 后续接入与工具链选择转换层跑通后接下来就是把它接到真实工作流里。如果只是偶尔验证模型能不能调通工具用模型对话做联调就够了地址在 https://taotoken.net/chat 。如果是长期跑编码任务或 Agent 场景需要稳定的工具调用和额度管理可以看 Coding Plan地址是 https://taotoken.net/coding-plan 适合把 MCP 工具挂到日常开发流程里。接入相关的 Key 管理和文档再放一次方便直接跳API Keys 在 https://taotoken.net/api-keys 接入文档在 https://taotoken.net/doc 。API 基础地址统一用 https://taotoken.net/api 。最后说个实操经验HSF 转 MCP 这层转换别一上来就把所有接口都暴露成工具。工具太多模型选择成本高还容易误调。先挑三五个高频、参数简单的接口做试点把工具描述打磨好验证调用准确率再逐步扩。转换层本身要当成一个独立服务来维护加监控、加日志、加超时熔断别让它成为新的单点。