如何在 claude-code-templates 仪表盘上通过构建开关启用 WebMCP 只读目录工具？

如何在 claude-code-templates 仪表盘上通过构建开关启用 WebMCP 只读目录工具？

【免费下载链接】claude-code-templatesCLI tool for configuring and monitoring Claude Code项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-templates

claude-code-templates 的仪表盘（dashboard/目录下的 Astro 站点）内置了 WebMCP V1：把组件目录以一组只读工具的形式暴露给支持 WebMCP 的浏览器 AI agent，让它们可以直接查询目录、拿到安装命令，而不必去解析页面 UI。这套工具默认不生效——dashboard/src/lib/webmcp.ts 中的入口initWebMCP()在构建时开关PUBLIC_WEBMCP_ENABLED不是字符串"true"时会直接返回。本文说明如何在生产配置、CI 构建和本地构建三个位置打开这个开关，并在浏览器中确认 4 个只读工具已经注册。

开关控制的内容

PUBLIC_WEBMCP_ENABLED是构建期变量，文档（dashboard/docs/webmcp.md）说明它采用的是和PUBLIC_ADS_ENABLED相同的模式，判断逻辑只有一行（webmcp.ts 第 20 行）：

const WEBMCP_ENABLED = import.meta.env.PUBLIC_WEBMCP_ENABLED === 'true';

也就是说，只有字符串"true"会启用功能，其余任何取值（包括"false"）都让initWebMCP()在触碰document.modelContext之前直接返回。启用后，DashboardLayout.astro 中打包的<script>会调用initWebMCP()；站点所有页面共用这个布局，Astro 会去重脚本，因此工具在每一页都可用。

两个与“是否破坏页面”相关的行为来自文档和源码：

• 不支持 WebMCP 的浏览器不受影响：initWebMCP()先做document.modelContext.registerTool的 feature-detect，检测不到就直接退出。
• 注册失败（Permissions Policy 导致的NotAllowedError、重名导致的InvalidStateError）会被吞掉，不会中断页面。

注册成功的工具共 4 个，全部是只读（readOnlyHint: true），返回社区撰写的组件描述的工具还会带上untrustedContentHint: true，提示 agent 把该文本当数据而不是指令：

工具本身不新增后端和依赖，数据全部来自仪表盘已经提供的同源静态 JSON：search-index.json、components/{type}.json、counts.json、trending-data.json，通过 src/lib/data.ts 中 UI 共用的fetchSearchIndex()、fetchComponentsByType()、getInstallCommand()读取（共享 5 分钟内存缓存）。

在三个位置配置开关

生产环境：wrangler.toml 的[vars]

dashboard/wrangler.toml 的[vars]段保存生产值（PUBLIC_*必须写在这里而不是 secrets 中）：

# WebMCP catalog tools (src/lib/webmcp.ts); set to "false" to disable: PUBLIC_WEBMCP_ENABLED = "true"

需要关闭时把该行改成"false"即可，这是文档注释里给出的禁用方式。

CI 构建：Build 步骤的 env

.github/workflows/deploy.yml 在Build步骤里把开关作为环境变量传入构建（CI 使用 Node 22，依赖安装在dashboard目录下）：

- name: Build run: npm run build working-directory: dashboard env: PUBLIC_WEBMCP_ENABLED: "true"

构建产物由后续的npx wrangler pages deploy dist部署到 Cloudflare Pages。

本地构建

本地构建与 CI 的 Build 步骤等价：先在dashboard目录安装依赖，再带上同一个环境变量执行npm run build（dashboard/package.json 中build即astro build）：

cd dashboard npm install PUBLIC_WEBMCP_ENABLED=true npm run build

不设置该变量时，npm run build也能完成构建，只是产物中 WebMCP 功能处于关闭状态（initWebMCP()直接返回），不会报错。

验证工具是否注册

文档的 Testing 部分给出两种验证方式。

在支持 WebMCP 的浏览器中

在启用了 WebMCP 的浏览器里（文档列出的支持范围：Chrome 149+ / Edge 150+ 的 origin trial 版本，或 ChatGPT Desktop、Brave Leo 这类已支持 agent），getTools()/executeTool()可以同源调用，直接在 DevTools 中执行：

const tools = await document.modelContext.getTools(); await document.modelContext.executeTool( tools.find(t => t.name === 'search-components'), { query: 'react' } );

判断依据：getTools()返回的列表中能找到search-components等 4 个工具名，且executeTool能返回对应结果，说明开关生效且注册成功。文档没有给出这次调用的固定示例输出，结果内容以目录数据为准。

在普通浏览器中打桩

普通浏览器不支持document.modelContext，可以先打桩 API 再重载页面来验证注册逻辑是否执行（按文档说明，以下代码粘贴进 DevTools 后刷新页面）：

// paste in DevTools, then reload document.modelContext = { registerTool: t => (console.log('registered', t.name), Promise.resolve()) };

开关启用时，控制台会随每个工具注册打印registered及工具名；开关未启用时initWebMCP()直接返回，不会出现这些打印，可借此区分两种构建产物。

已知限制

• Chrome/Edge 的 origin trial 需要在对应试用计划中注册站点域名并添加<meta http-equiv="origin-trial">标签，文档把这一项列为 V1 之后的工作；ChatGPT Desktop 和 Brave Leo 不需要。
• V1 不包含声明式<form>工具、exposedTo跨源 iframe 暴露、service-worker 工具，也没有任何写操作/有后果的工具（购物车、PR 流程等需要先做用户确认设计）。
• 工具返回的组件描述属于社区撰写内容，agent 侧应按数据而非指令处理。

需要继续深入时，可以看 webmcp.md 中的架构与约定说明，以及 webmcp.ts（工具定义与注册）、DashboardLayout.astro（全站挂载点）三个文件的实现细节。

【免费下载链接】claude-code-templatesCLI tool for configuring and monitoring Claude Code项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-templates