WebMCP — Make Any Website Agent-Ready

webmcp-sdk

面向浏览器 Agent 的 TypeScript 工具，具备明确授权、受限执行、React 生命周期支持，以及非托管交易参考应用。

0.6.0 是一个存在破坏性变更的安全候选版本。 现有注册表版本不包含这些修复。请阅读迁移指南。此候选版本尚未发布；本项目既不托管资产，也不保证免受攻击。

试用交易工作室

从仓库检出版本开始，使用 Node 22.22.2+（22 LTS）或 24.15+（24 LTS）以及 npm：

npm ci --ignore-scripts
npm run build
npm run studio:dev

打开 Vite 提供的 localhost URL。练习模式使用虚构的余额、价格和收据；不会签名或广播交易。实时钱包模式使用 Base 链（8453）上的注入式 EIP-1193 钱包。此候选版本支持 ETH、原生 Base USDC 和 WETH 转账，以及通过配置的 Uniswap V3 路由器和 500 费率档进行的 USDC/WETH 精确输入兑换。Agent 可读取状态并提出操作；用户需分别审核每项确切的授权或交易，并在外部钱包中进行授权。

提案绑定账户、链、已保存的策略版本、确切金额、最低输出和 120 秒过期时间。滑点上限为 1%。单个提案的限额不会限制累计支出。未提供私钥/助记词输入、任意 Agent calldata、无限额授权或 Agent 签名工具。已保存的策略在模式切换后仍会保留；仅存在于内存中的活动记录会在重新加载或切换模式时清除。

已提交的哈希处于待处理状态。确认前必须核对匹配的交易字段、收据和代币事件。提交状态不明确以及 RPC 故障都会保持待处理状态。已挖出的交易纳入区块并不意味着不可逆的最终确认；重试前请检查钱包中的待处理活动。请参阅威胁模型和发布操作手册。

SDK 快速入门

发布后安装经过审查的包，或在本地构建此分支。公开子路径提供 CommonJS、ES 模块和 TypeScript 声明。

import { createKit, defineTool } from "webmcp-sdk";

const kit = createKit({ prefix: "demo" });
kit.register(
  defineTool(
    "hello",
    "Return a greeting for the supplied name.",
    {
      type: "object",
      properties: { name: { type: "string", maxLength: 100 } },
      required: ["name"],
      additionalProperties: false,
    },
    ({ name }) => ({ message: `Hello, ${name}!` }),
  ),
);
console.log(await kit.invoke("demo.hello", { name: "Bill" }));
// { message: 'Hello, Bill!' }
await kit.ready();
// Later: kit.unregisterAll();

无需原生浏览器 API 即可直接调用。默认适配器使用 document.modelContext、execute、异步注册和注册 AbortSignals。调用 ready() 并等待其完成，以获知注册错误。原生 WebMCP 仍处于实验阶段，并取决于浏览器和来源。使用浏览器规范示例区分本地执行与原生就绪状态。旧版 navigator 适配器需要明确设置 browserAdapter: 'legacy'，并单独进行兼容性测试。注解仅为建议性元数据，不构成授权。

执行与授权

输入必须是有限的自有数据 JSON 快照，并会在异步钩子运行前递归冻结。危险键、循环引用、任意原型、访问器和无效架构都会被拒绝。无需 unsafe-eval 即可进行验证；支持的架构限制是有意设置的兼容性边界。

默认值：10 个并发执行、100 个排队/准入等待、30 秒期限、65,536 字节输入、1,000 个节点和 10 层深度。处理程序会收到可选的第二个 { signal } 参数。请传播取消信号，并在操作边界检查当前授权状态。期限无法抢占同步 JavaScript，也无法强制停止不配合的 Promise；未解决的工作会一直占用其容量/租约，直到执行完成。

import { withConfirmation, withSecurity } from "webmcp-sdk/security";

// reviewedTool, showReviewDialog and writeAuditEvent are application-owned.
const secured = withSecurity(
  withConfirmation(
    reviewedTool,
    "Approve these reviewed terms?",
    showReviewDialog,
  ),
  {
    rateLimit: { maxInvocations: 10, windowMs: 60_000 },
    audit: true,
    onAudit: writeAuditEvent,
  },
);
kit.register(secured);

withConfirmation 要求其显式提供程序返回字面值 true。kit.requestUserInteraction 则独立要求 kit 配置中设置 confirmationProvider。金融审核必须绑定不可变的条款；通用布尔值对话框本身并不足够。audit: true 需要可靠的同步接收器。安全审计默认不包含输入，也绝不记录原始处理程序结果/错误；明确允许的字段会进行凭证键脱敏。常规 kit 回调/日志可能包含输入，不能视为经过脱敏的审计存储。blockedPatterns 是有长度限制的字面子字符串，并非全面的提示注入过滤器。

React 和声明式表单

使用 webmcp-sdk/react 中的 WebMCPProvider 来限定会话策略。工具钩子会发布已提交的处理函数/元数据，在回调权限发生变化时撤销旧注册，并且仅移除其自身拥有的注册。由配置拥有的 Provider 会拒绝变更后的配置；如需替换策略，请重新挂载。可以替换提供的工具包。稳定的回调可避免不必要的撤销，但必须保留所有账户/策略依赖项。

registerDeclarativeTools(kit, root, { handlers }) 通过显式的受信处理函数映射注册带注释的表单，并返回清理函数。HTML 无法定义可执行处理函数。有关支持的字段和授权职责，请参阅声明式工具。

x402 和发现

x402 支付： 因安全维护而暂停。请勿在生产环境中使用。

webmcp-sdk/middleware/express 提供发现元数据，而非执行传输或身份验证系统。目录默认拒绝访问：请提供返回字面值 true 的授权器，或有意选择 publicManifest: true。目录响应使用 private, no-store。实际操作需要单独的身份验证和授权。

Python 发现是单独的源代码发行包；npm 不会安装 Python 导入项。未提供 stdio 服务、webmcp-sdk serve、ProxyRelay 或 AuditLog 类。

验证

npm run verify:release

发布记录区分历史证据与重新构建的最新检查。完整门禁涵盖格式、类型、SDK/Studio 测试和构建、打包后的使用方、原生浏览器/CSP、确定性钱包流程、无障碍/移动端检查、Python 测试和依赖项审计。Python 安装另有单独的 wheel 导入检查。没有自动化检查会发布、部署或发送真实资金。报告问题请参阅 SECURITY.md。MIT 许可证。