x402.mcp 变更日志全解：Python MCP 集成从首次发布到全量功能的演进路线

x402.mcp 变更日志全解Python MCP 集成从首次发布到全量功能的演进路线【免费下载链接】x402A payments protocol for the internet. Built on HTTP.项目地址: https://gitcode.com/GitHub_Trending/x4/x402本文以 x402 的 MCP 集成变更日志 为核心逐条梳理x402.mcp包从0.1.0初始 alpha 版本到当前Unreleased版本的全部功能变更并结合仓库源码还原每一项能力的真实实现包括 402 支付自动检测与重试流程、服务端支付包装器、工厂函数、Hook 系统与双格式PaymentRequired提取机制。读完本文你将能够依据源码理解该变更日志中每一条Added/Features记录对应的调用链、协议常量与测试覆盖并可据此在 Python 项目中搭建 MCP 付费工具调用链路。变更日志的文档规范CHANGELOG.md 开篇声明了两条规范这是理解整个文档结构的前提格式规范基于 Keep a Changelog即所有显著变更notable changes都会记录在文件中并按Added/Features等类别分组、按版本倒序排列版本规范遵循语义化版本Semantic Versioning 2.0.0版本号为MAJOR.MINOR.PATCH结构。文件当前包含两个版本条目版本日期状态说明[Unreleased]未定待发布MCP 传输集成的首次完整实现包含客户端、服务端、工具函数、类型、Hook 与测试[0.1.0]2025-02-05已发布初始 alpha 版本Initial alpha release这一结构说明x402.mcp包目前正处于 0.x 阶段Unreleased条目中列出的功能尚未形成独立版本号使用者应以源码树中的实际导出为准下文逐条对应。[Unreleased]Added 条目逐条溯源Unreleased的Added分组共列出 12 项内容。以下按依赖方向从底层到上层逐一对照源码。MCP 传输集成402 自动检测与重试变更日志第一条 Initial implementation of MCP transport integration for x402 payment protocol 对应的是 client.py 中的核心类x402MCPSession。它的call_tool()方法完整实现了协议文档 specs/transports-v2/mcp.md 中描述的五步支付流程首次不带支付调用工具session.call_tool(name, arguments)若返回结果isError为假直接构建MCPToolCallResult返回否则从错误结果中提取PaymentRequired优先structuredContent回退解析content[].text若提取失败或auto_payment为 False原样返回不视为支付流程提取成功则调用x402_client.create_payment_payload(payment_required)生成支付载荷将其model_dump(by_aliasTrue)序列化后以_meta{x402/payment: payload_dict}携带在第二次call_tool中重试。对应源码位置为 client.py 的 call_tool 方法。返回结构MCPToolCallResult是一个 dataclass包含content、is_error、payment_responseSettleResponse、payment_made和raw_result五个字段client.py这正是Features分组中 Payment verification and settlement integration 在客户端的落点payment_madeTrue时payment_response从响应_meta的x402/payment-response键反序列化为SettleResponse反序列化失败时降级为原始 dict。客户端封装与工厂函数日志中 x402MCPClient- Client wrapper with automatic payment handling 及三条工厂函数分别落在不同模块create_x402_mcp_client异步上下文管理器位于 client.py它通过mcp.client.sse.sse_client连接服务器若 URL 未以/sse结尾会自动补上创建ClientSession并包装为x402MCPSessioninitialize()在yield前自动执行。x402MCPClientSync位于 client.py同步版封装接收底层 MCP 客户端与x402ClientSync支付客户端支持auto_payment与on_payment_requested审批回调——回调返回 False 时不发起支付直接返回未支付的结果。三条工厂函数wrap_mcp_client_with_payment、wrap_mcp_client_with_payment_from_config、create_x402_mcp_client_from_config集中在 client_async.py前两者用于把已有 MCP 客户端包装成带支付能力的客户端后者直接从schemes配置字典创建完整的 x402 MCP 客户端。模块入口 mcp/init.py 通过__getattr__实现懒加载x402MCPClient从client_async导入、x402MCPClientSync与create_x402_mcp_client从client导入、服务端组件从server/server_sync/types导入。注释明确说明这是避免在导入期强制要求 mcp 依赖的设计——x402核心包可以不装 MCP SDK 而正常导入只有真正访问 MCP 组件时才触发import mcp安装方式为pip install x402[mcp]见init.py 模块 docstring。服务端支付包装器create_payment_wrapper- Server-side payment wrapper for tool handlers 对应 server.py。该工厂函数接收resource_server已注册 facilitator 客户端与 scheme 的x402ResourceServer实例、acceptsPaymentRequirements列表首个条目用于校验与结算、可选resourceResourceInfo缺省自动生成mcp://tool/{函数名}与可选hooks返回一个装饰器。被装饰的 FastMCP 工具处理器会自动获得完整的支付守卫逻辑server.py 包装流程从 FastMCP 注入的ctx中提取_meta[x402/payment]_extract_payment_from_context数据存放在ctx.request_context.meta.model_extra中无支付数据 → 返回isErrorTrue的 402 结果支付数据解析为PaymentPayload失败则返回 Invalid payment payload 402 结果调用resource_server.verify_payment(payload, accepts[0])向 facilitator 校验同步实现会走asyncio.to_thread避免阻塞事件循环触发on_before_executionhook返回 False 可中止执行执行原始 handler支持 async 与 sync 函数执行后触发on_after_executionhook调用resource_server.settle_payment结算失败返回 Settlement failed 402 结果结算成功后触发on_after_settlementhook并将SettleResponse序列化放入响应_meta[x402/payment-response]。一个值得注意的实现细节wrapper 会通过inspect.signature向包装函数的签名中合成一个ctx: Context关键字参数server.py。原因是 FastMCP 的Tool.from_function()依靠签名检查来发现 Context 注入点而用户的 handler 本身不需要声明ctx。若 mcp SDK 版本变化导致注入失效运行时会打印一次 warning 日志Payment metadata will be unavailable这是排查支付永远 402类问题的关键线索。工具函数、错误工具与类型守卫日志列出的实用函数全部实现在 utils.py函数作用源码位置extract_payment_from_meta(params)从请求参数_meta[x402/payment]提取并反序列化为PaymentPayloadutils.pyattach_payment_to_meta(params, payload)将PaymentPayload序列化后挂载到参数_metautils.pyextract_payment_required_from_result(result)从工具调用结果中提取PaymentRequired双格式utils.pycreate_tool_resource_url(tool_name, custom_urlNone)生成mcp://tool/{tool_name}形式的资源 URLutils.pyis_object(value)dict 类型守卫用于 JSON-RPC 错误解析utils.py错误三件套create_payment_required_error(payment_required, message)→ 抛出携带PaymentRequired的异常utils.pyis_payment_required_error(error)→ 判断异常是否为支付请求错误utils.pyextract_payment_required_from_error(json_rpc_error)→ 从 JSON-RPC 错误对象中抽取PaymentRequired。配套的PaymentRequiredError异常类定义在 types.py其code属性固定为MCP_PAYMENT_REQUIRED_CODE 402。高级类型与 Hook 系统DynamicPayTo、DynamicPrice、MCPToolPaymentConfig等 11 个高级类型 对应 types.py。其中与动态定价相关的类型直接以可调用对象定义DynamicPayTo Callable[[MCPToolContext], str]——根据工具调用上下文工具名、参数、_meta动态解析收款地址DynamicPrice Callable[[MCPToolContext], Price]——动态解析价格。MCPToolContext与MCPToolResult是这些可调用对象的输入载体types.py。Hook 系统是日志Added与Features两组都重点强调的能力。客户端侧有三个支付流 hookPaymentRequiredHook收到 402 时触发PaymentRequiredHookResult支持返回自定义payment或abortTrue中止、BeforePaymentHook、AfterPaymentHook服务端侧有BeforeExecutionHook可中止执行、AfterExecutionHook、AfterSettlementHook。服务端的PaymentWrapperHookstypes.py统一支持同步或异步回调bool | Awaitable[bool]在 server.py 的三个触发点被调用hook 抛出的异常会被静默吞掉不影响主支付流程——从源码结构看这是为了保证观测性 hook 的故障不会阻断收款。协议透传、测试与再导出全部 19 个 MCP 透传方法客户端 wrapper 除call_tool支付流程外对 MCP 协议其余方法list_tools、list_resources、read_resource、connect、close等做透明转发。测试夹具 tests/conftest.py 中的MockMCPClient/MockAsyncMCPClient同时 mock 了call_tool、connect、close、list_tools、list_resources、read_resource即为验证透传行为而设计。单元测试tests/目录包含 7 个测试文件——test_client.py569 行、test_client_async.py565 行、test_server.py929 行、test_server_async.py679 行、test_utils.py417 行加上共享夹具 conftest.py。夹具中的SAMPLE_PAYMENT_REQUIRED_JSONx402Version: 2、exactscheme、eip155:84532网络、USDC、maxTimeoutSeconds: 300与make_paid_success_result()_meta中携带x402/payment-response结算回执精确复现了协议中支付请求与结算响应的两种报文形态。核心包再导出PaymentPayload、PaymentRequired、PaymentRequirements、SettleResponse、Network、SchemeNetworkClient、SchemeNetworkServer等类型从x402核心包的 schemas 模块再导出用户from x402.mcp import ...即可获得完整类型。Features 分组双格式支付提取机制Features分组的 Dual format payment extraction (structuredContent and content[0].text) 是该包最关键的健壮性设计。x402MCPSession._extract_payment_requiredclient.py的提取顺序为首选structuredContent按 MCP x402 规范服务端必须以PaymentRequired对象形式直接提供客户端先检查该字段是否同时含x402Version与accepts命中则PaymentRequired.model_validate()回退解析content[].text逐条遍历带text属性的内容项走_try_extract_payment_jsonclient.py。该辅助函数先尝试整段json.loads若失败则用正则\{.*accepts\s*:\s*\[.*\].*\}DOTALL 模式从文本中抽取 JSON 子串——专门兼容 FastMCP 会把工具错误包装为Error executing tool get_weather: {...}形式的前缀文本两条路径都失败返回None客户端将其视为非支付错误并直接返回。协议规范 specs/transports-v2/mcp.md 要求服务端必须同时提供structuredContent直接对象与content[0].text同一对象的 JSON 字符串两种形式服务端包装器_create_payment_required_result正是这样构造 402 响应isErrorTrue、structuredContentpayment_required、content[TextContent(json.dumps(payment_required))]报文中x402Version固定为2。两个协议常量统一定义在 constants.pyMCP_PAYMENT_META_KEY x402/payment——请求_meta中携带PaymentPayload的键MCP_PAYMENT_RESPONSE_META_KEY x402/payment-response——响应_meta中携带结算回执的键。types.py 中另有MCP_PAYMENT_REQUIRED_CODE 402常量作为 JSON-RPC 错误场景下需要支付的规范错误码。版本演进0.1.0 与 Unreleased 的关系[0.1.0] - 2025-02-05条目仅包含一行 Initial alpha release说明首版发布时功能面非常有限。随后Unreleased条目一次性补齐了传输集成的全部组件客户端 wrapper、服务端包装器、工厂函数、工具函数、错误工具、11 个高级类型、6 个 hook、19 个透传方法与配套测试从变更日志的结构可以推断0.1.0之后到下一个正式版本之间x402.mcp经历了从骨架到完整的实现而这批内容正是等待版本化的主体。对下游使用者而言这意味着引用x402.mcp时应以当前源码树的实际导出__all__清单为准而非假定任何未发布版本的行为。使用方式小结结合变更日志与 mcp/README.md 中的示例落地步骤为pip install x402[mcp]服务端让 FastMCP 工具收费from x402.mcp import create_payment_wrapper wrapper create_payment_wrapper( resource_server, # 已注册 scheme 的 x402ResourceServer acceptsweather_accepts, # PaymentRequirements 列表 resourceResourceInfo(urlmcp://tool/get_weather), ) mcp.tool(nameget_weather, descriptionGet weather) wrapper async def get_weather(city: str) - str: return json.dumps({city: city, weather: sunny})客户端自动支付调用付费工具from x402.mcp import create_x402_mcp_client async with create_x402_mcp_client(x402_client, http://localhost:4022) as mcp: result await mcp.call_tool(get_weather, {city: SF}) print(result.content) # 工具返回内容 print(result.payment_response) # SettleResponse若已支付 print(result.payment_made) # True 表示本次调用发生过支付完整可运行示例可进一步参考 examples/python/clients/mcp 与 examples/python/servers/mcp 目录协议层面的完整定义报文格式、_meta键位、双格式要求见 MCP 传输规范。【免费下载链接】x402A payments protocol for the internet. Built on HTTP.项目地址: https://gitcode.com/GitHub_Trending/x4/x402创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考