1. 当 AI 打开你的网页它到底看见了什么Chrome WebMCP 是 Chrome 团队推动的一项浏览器原生能力全称 Web Model Context Protocol核心目标是让网站把自身功能注册成结构化工具AI 智能体进入页面后可以直接像调用 API 一样调用它们。它适合两类人一类是做前端或全栈、想让自己的站点被 AI 顺畅操作的开发者另一类是在本地折腾 AI 编码工具、希望把浏览器里的工具能力接进 Cline、Claude Code 这类客户端的玩家。过去 AI 操作网页靠的是截图、视觉模型猜坐标、模拟点击一个多步任务动辄烧掉几万 token页面结构一变就全盘失效。WebMCP 把这条路换成了「网站主动自我介绍」页面用声明式 HTML 注解或命令式 JavaScript 注册工具AI 拿到的是带名字、描述、JSON Schema 的确定性接口而不是一堆像素。我试过在本地把这条链路跑通发现真正卡人的不是浏览器 API 本身而是工具侧的统一接入——你的 AI 客户端要能稳定拿到模型通道才能把「读取站点自我介绍」这件事变成可复现的闭环。这篇就按这个思路走先讲清楚 WebMCP 的两种注册方式再给出 settings.json 与 config.toml 骨架、CC Switch 与 Cline 的配置片段最后做一次端到端验证。2. 先把 TaoToken 的通道准备好TaoToken 在这里扮演的是统一 Key 与 API 通道的角色。你的 AI 编码工具、Agent 客户端、本地脚本都需要一个稳定的模型入口TaoToken 把这件事收敛成一套 Key 和兼容接口省得每个工具各配一份。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 注意这个地址不带 UTM 参数配置里直接写它。你需要先拿到 API Key入口在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。拿到之后先别急着写进配置文件建议用环境变量过渡避免 Key 散落在多个仓库里。如果你只是想先验证模型通道是否通可以直接用模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 发一条消息确认返回正常再往下走。注意Key 只放在本地环境变量或工具的私有配置里不要提交到 Git。团队协作时用各自的 Key不要共用。3. WebMCP 的两种注册方式与最小页面3.1 声明式一个 form 就是一个工具声明式 API 走 HTML 注解零 JavaScript页面加载时就能被解析。适合标准表单提交、搜索查询这类简单操作。!-- 一个 HTML 表单 一个 AI 工具 -- form toolnamegreet_user tooldescription向用户问好 input namename typetext description你的名字 / button typesubmit问好/button /formtoolname是工具标识tooldescription是给 AI 看的说明input 上的description会进入参数描述。这套写法对 SEO 和可访问性都友好维护成本低。3.2 命令式registerTool 精确控制复杂逻辑、中间状态、权限校验、动态工作流用命令式 API通过 JavaScript 注册。// 检测浏览器是否支持 WebMCP if (document.modelContext) { document.modelContext.registerTool({ name: get_weather, description: 查询指定城市的实时天气, inputSchema: { type: object, properties: { city: { type: string, description: 城市名 } }, required: [city] }, execute: async ({ city }) { const resp await fetch(/api/weather?city${encodeURIComponent(city)}); const data await resp.json(); return { content: [{ type: text, text: ${city}当前温度 ${data.temp}°C${data.condition} }] }; } }); console.log(WebMCP 工具注册成功); } else { console.warn(当前浏览器不支持 WebMCP); }注意 API 位置的变化早期是navigator.modelContext后来规范调整到document.modelContext。如果你参考的是旧文章记得改过来Chrome 150 之后旧位置逐步弃用。3.3 两种方式怎么选维度声明式命令式实现方式HTML 属性注解JavaScript registerTool复杂度低零 JS中到高适用场景简单表单、搜索复杂业务逻辑、多步流程出现时机页面加载时JS 执行后动态性静态可动态注册/注销4. 可复制的工具侧配置骨架4.1 settings.json 骨架很多 AI 编码工具用 JSON 存配置。下面这份骨架把模型通道指向 TaoTokenKey 从环境变量读。{ model: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: ${TAOTOKEN_API_KEY}, model: claude-sonnet-4-20250514 }, mcpServers: { webmcp-devtools: { command: npx, args: [-y, webmcp-devtools-server] } } }baseUrl用不带 UTM 的 API 地址apiKey用占位符实际值从 shell 环境变量注入。mcpServers这一段是把浏览器里的 WebMCP 工具桥接到本地客户端的常见做法后面验证环节会用到。4.2 config.toml 骨架如果你的工具用 TOML等价配置如下。[model] provider openai-compatible base_url https://taotoken.net/api api_key ${TAOTOKEN_API_KEY} model claude-sonnet-4-20250514 [mcp_servers.webmcp_devtools] command npx args [-y, webmcp-devtools-server]两份配置的字段名不同语义一致一个模型入口一个工具桥接入口。先把模型入口跑通再加工具桥接出问题时好定位。4.3 CC Switch 配置片段CC Switch 用来在多个模型通道之间切换。把 TaoToken 作为一个 profile 加进去{ profiles: [ { name: taotoken, baseUrl: https://taotoken.net/api, apiKeyEnv: TAOTOKEN_API_KEY, models: [claude-sonnet-4-20250514, gpt-4o] } ], active: taotoken }切换时只改active字段不用动其他工具的配置。长期做编码和 Agent 任务的话可以了解下 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 它更适合高频调用场景。4.4 Cline 配置片段Cline 在 VS Code 里配置自定义 provider 时填 API Provider 为 OpenAI CompatibleBase URL 填https://taotoken.net/apiAPI Key 填你的 KeyModel ID 填你要用的模型名。对应的 settings 片段{ cline.apiProvider: openai, cline.openAiBaseUrl: https://taotoken.net/api, cline.openAiApiKey: ${TAOTOKEN_API_KEY}, cline.openAiModelId: claude-sonnet-4-20250514 }配置完重启窗口让 Cline 重新读取设置。5. 端到端验证让 AI 读到站点自我介绍5.1 准备一个带 WebMCP 工具的本地页面新建webmcp-demo.html内容如下!DOCTYPE html html head meta charsetUTF-8 titleWebMCP Demo/title /head body h1我的站点/h1 form toolnamecontact_us tooldescription联系客服留下问题描述 input namemessage typetext description问题描述 required / button typesubmit提交/button /form script if (document.modelContext) { document.modelContext.registerTool({ name: get_store_info, description: 获取店铺基本信息营业时间、地址、电话, inputSchema: { type: object, properties: {} }, execute: async () ({ content: [{ type: text, text: JSON.stringify({ name: 示例商店, hours: 9:00-21:00, address: 示例地址, phone: 010-00000000 }) }] }) }); } /script /body /html用本地静态服务器打开比如python3 -m http.server 8080然后访问http://localhost:8080/webmcp-demo.html。5.2 在 DevTools 里确认工具已注册打开 F12进 Application 标签边栏找 WebMCP 面板应该能看到contact_us和get_store_info两个工具。也可以在 Console 里跑console.log(WebMCP 支持:, !!document.modelContext); if (document.modelContext?.getTools) { console.log(document.modelContext.getTools()); }返回里能看到工具名和 schema说明站点自我介绍已经生效。5.3 通过工具桥接让 AI 客户端读取启动webmcp-devtools-server后在支持 MCP 的客户端里应该能看到工具列表 webmcp_list_tools Found 2 WebMCP tool(s): - contact_us: 联系客服留下问题描述 [declarative] - get_store_info: 获取店铺基本信息 [read-only]再调用一次 webmcp_call_tool get_store_info {} {name:示例商店,hours:9:00-21:00,address:示例地址,phone:010-00000000}到这里AI 客户端已经成功读到了网页的自我介绍并执行了工具。整条链路是页面注册工具 → 浏览器暴露 → 桥接服务转发 → AI 客户端调用 → 返回结构化结果。6. 本篇常见错排查6.1 document.modelContext 是 undefined最常见的原因是浏览器版本不够或 flag 没开。先看chrome://version确认 Chrome 版本在 149 以上。开发阶段可以访问chrome://flags/enable-webmcp-testing设为 Enabled 后重启。生产环境走 Origin Trial需要在页面 head 里加 token。6.2 工具注册了但列表里看不到检查注册代码是否在document.modelContext存在之后执行。如果是 SPA组件挂载顺序可能导致注册时机太早或太晚。另外确认没有在组件卸载时误调unregisterTool。声明式工具如果放在动态渲染的 DOM 里也要等 DOM 真正插入后再验证。6.3 调用工具返回 schema 校验失败inputSchema必须是合法 JSON Schemarequired里的字段要在properties中定义。参数类型不匹配时AI 传进来的值可能被拒绝。建议给每个参数写清楚description这直接影响模型能否正确填参。6.4 模型通道返回 401 或超时先确认环境变量TAOTOKEN_API_KEY在当前 shell 里可见echo $TAOTOKEN_API_KEY能打印出值。再确认baseUrl写的是https://taotoken.net/api没有多余斜杠或路径。如果工具里配了多个 provider检查当前激活的是哪一个。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有完整的参数说明。6.5 桥接服务启动失败npx -y webmcp-devtools-server首次运行需要联网拉包网络不通会卡住。确认 Node 版本不要太旧必要时先手动npm install -g webmcp-devtools-server再启动。如果端口被占用换一个端口参数。7. 继续往下走把最小闭环跑通之后下一步可以做的事很具体给工具加更细的description让模型选工具更准把敏感操作加上用户确认用unregisterTool在登出时清理权限相关工具。如果你要长期跑编码和 Agent 任务建议把模型通道固定下来用 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 管理调用额度Key 统一在控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 里轮换。Claude Code 这类客户端的接入细节可以参考 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude_codeutm_campaignrewrite 里面有针对 Anthropic 协议的配置说明。真正让站点「会自我介绍」的不是某一行代码而是你把工具描述、schema、权限边界都想清楚之后AI 才可能稳定地用对它们。