PubFi MCP

PubFi MCP Stdio Bridge Smoke Fixture

这个公开示例是一个本地、无依赖、兼容 MCP 的标准输入输出桥接器和冒烟测试夹具，用于 PubFi 托管的 MCP 端点。请使用 Node.js 24.19.0 或更高版本的 Node.js 24 版本运行。

此桥接器会将现代 server/discover、列表和 tools/call 请求转发到 Rust MCP 端点，而不是合成第二次握手、运行已弃用的 TypeScript 路由工具实现，或为每个提供方创建一个公开工具。每个请求都包含完整的 MCP 2026-07-28 元数据，桥接器也会镜像标准 HTTP 路由标头。PubFi 不会创建协议会话。桥接器本身只接受现代输入；需要兼容 MCP 2025-11-25 初始化阶段的客户端，可直接连接到同一个托管端点。

如需通过身份验证使用托管服务，请将 MCP 客户端配置为使用 PubFi 的 Streamable HTTP 端点 https://mcp.pubfi.ai。托管的身份验证服务使用四个固定的 Registry v2 工具。目录列表和详情读取是公开的。在此根端点上执行精确调用需要 PubFi API 密钥或 OAuth 访问令牌。符合条件的无账户 x402 执行可通过 https://mcp.pubfi.ai/x402 进行，无需 Bearer 凭据。上游提供方凭据保留在服务端。

工具

• pubfi.capabilities.list
• pubfi.capabilities.get
• pubfi.route.execute
• pubfi.substrate.runtime_upgrade.verify

pubfi.capabilities.list 使用不透明且绑定代次的游标枚举精简摘要。pubfi.capabilities.get 返回一个精确能力 ID 的完整类型化契约。由客户端 Agent 选择能力；PubFi 不会对候选项排序或推断意图。可执行路径、方法、匹配器、架构、特定方法的 PubFi 定价和就绪状态，均只来自已安装的签名 Registry 代次。

在 Staging 中运行

从仓库根目录运行：

export STG_PUBFI_API_KEY='<Staging PubFi API key>'
export PUBFI_MCP_ENDPOINT='https://mcp-stg.pubfi.ai'
node examples/agents/pubfi-route-tools-mcp/server.ts

MCP 客户端配置示例：

{
  "mcpServers": {
    "pubfi-route-tools": {
      "command": "node",
      "args": ["examples/agents/pubfi-route-tools-mcp/server.ts"]
    }
  }
}

从提供这些变量的环境中启动客户端，或使用其密钥存储集成。不要将密钥放入受版本控制的配置文件中。

切换到 Production

创建单独的 Production 密钥，并使用精确的 Production 端点：

export PROD_PUBFI_API_KEY='<Production PubFi API key>'
export PUBFI_MCP_ENDPOINT='https://mcp.pubfi.ai'
node examples/agents/pubfi-route-tools-mcp/server.ts

上面的客户端配置使用相同的本地命令。不要将 Staging 密钥发送到 Production 端点。

冒烟测试

node examples/agents/pubfi-route-tools-mcp/smoke_pubfi_route_tools_mcp.ts
node --test examples/agents/pubfi-route-tools-mcp/bridge-response.test.ts \
  examples/agents/pubfi-route-tools-mcp/endpoint-policy.test.ts

进行经过身份验证的 Staging 冒烟测试：

export STG_PUBFI_API_KEY='<Staging PubFi API key>'
export PUBFI_MCP_ENDPOINT='https://mcp-stg.pubfi.ai'
node examples/agents/pubfi-route-tools-mcp/smoke_pubfi_route_tools_mcp.ts

如果没有端点所选的调用方密钥，冒烟测试会验证现代发现机制、固定工具列表、完整的目录分页、精确的能力详情，以及执行凭据门控。对于 Staging MCP 端点，使用 STG_PUBFI_API_KEY；对于 Production MCP 端点，使用 PROD_PUBFI_API_KEY。在这两种情况下，相同的目录读取操作仍然是公开的。若要有意发送实时请求，请根据当前目录设置 PUBFI_MCP_EXECUTE_LIVE=1、PUBFI_MCP_SMOKE_RAW_PATH 和 PUBFI_MCP_SMOKE_METHOD。可选的 PUBFI_MCP_SMOKE_QUERY 和 PUBFI_MCP_SMOKE_BODY 用于提供精确的路由输入。PUBFI_MCP_SMOKE_BODY 是精确的紧凑 ASCII 请求体（例如，{"limit":10}），而不是嵌套的 MCP JSON 值。冒烟测试不会自行编造提供方路由或能力 ID。

有关登录、密钥创建、HTTP 检查、Base Sepolia 测试边界以及向 Production 过渡的信息，请参阅 Staging 指南。

对于无账户支付，请使用官方 x402 MCP 客户端。对 https://mcp-stg.pubfi.ai/x402 或 https://mcp.pubfi.ai/x402 发起未签名且符合条件的 pubfi.route.execute 调用时，MCP 工具结果会返回 PaymentRequired。重试请求会在 params._meta["x402/payment"] 中携带 x402 V2 支付对象；结算结果会在 result._meta["x402/payment-response"] 中携带该对象。在此流程中，请勿传入 PubFi API 密钥、私钥或 PAYMENT-SIGNATURE HTTP 标头。

stdio 桥接仅接受精确的 Production 和 Staging 根 URL（https://mcp.pubfi.ai 和 https://mcp-stg.pubfi.ai）。在转发范围限定的调用方密钥之前，它会拒绝用户信息、端口、备用路径、查询字符串、片段、相似主机名和重定向。PUBFI_MCP_ORIGIN 不是受支持的别名。

与托管部署等效的冒烟测试包含在：

npm run smoke:mcp-e2e --workspace apps/web -- --json
npm run smoke:mcp-e2e --workspace apps/web -- --execute-live --json

执行边界

pubfi.route.execute 接受在读取列表/详情目录后选定的精确 raw_path 和 method。Rust 数据平面通过已安装的 Registry v2 匹配器解析这对值，并使用与 HTTP 网关相同的类型化执行器、凭据授权机制、Credit 记账、生成逻辑和失败关闭就绪状态。当前目录中被阻止或不存在的路由仍不可执行。此桥接不会增加提供方分支、能力排序、兼容路由 ID、供应商采购、自动支付或第二个目录授权源。