Customaise MCP

@定制/mcp

MCP服务器，将AI编码代理连接到 自定义 Chrome扩展程序。管理UserScripts，构建AgentScript，在用户登录的浏览器会话中调用WebMCP工具，直观地选择DOM元素，并直接从IDE驱动选项卡。

18个工具，5个资源，WebSocket桥 在IDE和真正的Chrome会话之间。

AI Agent ←(stdio)→ MCP Server ←(WebSocket)→ Customaise Extension

快速开始

1.安装Customaise

安装 自定义Chrome扩展程序 并启用 MCP电桥 在设置中。

2.添加到IDE

光标 (.cursor/mcp.json):

{
  "mcpServers": {
    "customaise": {
      "command": "npx",
      "args": ["-y", "@customaise/mcp"]
    }
  }
}

克劳德桌面版 (claude_desktop_config.json):

{
  "mcpServers": {
    "customaise": {
      "command": "npx",
      "args": ["-y", "@customaise/mcp"]
    }
  }
}

帆板运动 (.windsurf/mcp.json):

{
  "mcpServers": {
    "customaise": {
      "command": "npx",
      "args": ["-y", "@customaise/mcp"]
    }
  }
}

基罗 (.kiro/mcp.json):

{
  "mcpServers": {
    "customaise": {
      "command": "npx",
      "args": ["-y", "@customaise/mcp"]
    }
  }
}

法典 (~/.codex/config.toml):

[mcp_servers.customaise]
command = "npx"
args = ["-y", "@customaise/mcp"]

反重力 (mcp_config.json):

{
  "mcpServers": {
    "customaise": {
      "command": "npx",
      "args": ["-y", "@customaise/mcp"]
    }
  }
}

3.完成

您的代理现在可以读取和编辑UserScripts，构建向其公开WebMCP工具的AgentScript，直观地选择DOM元素，检查控制台，并对实时选项卡进行截图。

工具（18）

脚本生命周期

浏览器上下文

选项卡控件

可视化DOM定位

WebMCP代理工具

UI控制和批处理

资源（5）

任何连接的代理都可以读取的五种资源 resources/read这两个约定手册确切地定义了Customaise期望如何编写UserScripts和AgentScript。代理人在接触剧本之前应阅读相关手册。

WebMCP工具调用和同意（HITL）

AgentScript通过以下方式在网页上注册工具 navigator.modelContext.registerTool(...)。每个工具都在AgentScript的 // @webmcp 具有以下三种权限之一的标头：

• allow：工具立即执行。每次通话的往返时间约为50至100毫秒（分机仍会进行权限检查）。
• prompt：每次调用都会显示浏览器内的同意模式并阻止，直到用户批准或拒绝为止。多达 5分钟.为此而设计。不要将快速门控电话紧紧地挂在一起，并处理长时间的呼叫 call_webmcp_tool 像往常一样。
• deny：工具被抑制，调用立即失败。

同意模式上的“始终允许”和“始终拒绝”按钮将每个脚本和每个工具的决定保持不变，直到用户在扩展设置中重置它。这些覆盖住 chrome.storage.local 在用户的设备上；MCP服务器对它们没有可见性。

远程审批（可选）

如果用户拥有高级用户，并在其Customaise帐户页面上启用了远程HITL审批，则提示门控调用也会在那里镜像。他们可以从任何登录的浏览器（包括手机）批准或拒绝。无论是扩展模态还是远程曲面都可以解析；第一个签署的决定获胜。从MCP客户的角度来看，这是透明的： call_webmcp_tool 当任何授权表面批准时，只返回结果，如果拒绝或超时，则返回错误。

MCP客户看到了什么

• 提示门控 call_webmcp_tool 响应可能需要5分钟。向最终用户显示待定状态，而不是主动超时。
• 如果用户否认， call_webmcp_tool 返回错误。MCP服务器不重试。
• 工具调用参数以明文形式将HTTPS传输到后端并着陆 KMS静态加密 在Firestore。元数据（toolName、scriptName、origin）保持明文。查看自定义项 隐私政策.

可视化DOM选择

用户可以在浏览器中直观地选择元素，扩展程序会实时将上下文文件推送到您的工作区：

.customaise/dom-context//
├── element-name.dom.md          # Selectors, element context, user comments
├── element-name.screenshot.png  # Cropped screenshot of the selected element
└── ...

\[！注意\] 文件保存在哪里？ MCP服务器写入 .customaise/ 到其当前工作目录（通常是Cursor或Windsurf中的项目根目录）。 如果您使用的是像Claude Desktop这样的全局IDE，它默认为您的主目录(~/.customaise/).要强制使用特定的项目文件夹，请设置 CUSTOMAISE_WORKSPACE 在MCP配置中： ``json "env": { "CUSTOMAISE_WORKSPACE": "/absolute/path/to/your/project" } ``

使用 get_selected_elements 以编程方式检索选择，或读取推送的内容 .dom.md 文件直接从工作区。

每个选项包括 防弹分层选择器 （稳定ID→ 数据属性→ ARIA → 语义类别→ 结构定位），因此定位在页面更新后仍然有效。

工作流

用户脚本

1. get_page_context       → understand the target page
2. User selects elements  → .dom.md files auto-pushed to workspace
3. Write .user.js file    → AI writes the script using IDE tools
4. export_script          → Customaise validates and installs
5. reload_tab             → re-inject the script
6. get_console_context    → check for errors
7. take_screenshot        → verify the visual result

代理脚本

1. Read customaise://agentscript-conventions   → get the structure right before writing
2. get_page_context                            → find stable selectors on the target page
3. Write .agent.js file                        → declare tools via // @webmcp, register with navigator.modelContext.registerTool()
4. export_script                               → Customaise validates and injects
5. reload_tab                                  → the AgentScript registers its tools in the page
6. list_webmcp_tools                           → confirm tools surfaced
7. call_webmcp_tool                            → invoke one; prompt-gated calls wait for user consent

文件同步

使用 sync_scripts 将每个脚本批量导出到本地目录：

sync_scripts({ directory: "~/customaise-scripts" })

这将创建：

• 一 .user.js 每个脚本的文件。 文件名来源于脚本名（小写、连字符，例如。 my-cool-script.user.js).
• .customaise-manifest.json：将文件名映射到脚本ID以进行双向编辑。

清单格式

{
  "dark-mode-fix.user.js": "vm_script_1774225715376_lus75sdzn",
  "my-cool-script.user.js": "vm_script_1774225800123_abc12defg"
}

往返

1. sync_scripts 将所有脚本导出到一个目录。
2. 编辑任意 .user.js IDE中的文件。
3. export_script 使用文件路径和 scriptId 从清单中更新该脚本。
4. 省略 scriptId 通话时 export_script 而是创建一个新脚本。

文件监视器（自动导出）

曾经 sync_scripts 如果已被调用，MCP服务器会监视目录 .user.js 变化。在IDE中保存文件会自动将其推送到Customaise，无需手动 export_script 需要。

配置

安全边界

MCP服务器监听 ws://localhost:4050 在您的环回接口上以明文形式显示。连接已通过身份验证 HTTP Origin标头允许列表:

• 允许: chrome-extension://anmpijcpaobaabcdncjjmnhdeibipmko （生产）和 chrome-extension://ijjaffggglamocdapoihpkcpealflopp （舞台）。Chrome会在来自扩展服务工作者的WebSocket握手中自动标记此标头；你什么都不配置。
• 拒绝：常规网页(https://...)、未知的扩展ID和没有Origin标头的握手。返回HTTP 403。

这会阻止什么：恶意网页打开 new WebSocket('ws://localhost:4050') 并在背后调用WebMCP工具。这是最有可能的滥用媒介。

这并没有停止什么：以用户身份运行的恶意本机进程。节点 ws 客户端（以及大多数HTTP库）允许调用者伪造任何Origin标头。如果你不能信任以操作系统用户身份运行的进程，那么威胁模型已经比这座桥更广泛了。

纵深防御：每 prompt-许可工具在运行前仍需要您在Customaise同意模式中明确批准。申报的工具 allow 无需询问即可运行，因此只安装来自您信任的源的AgentScript。

开发版本：如果使用自定义密钥加载未打包的扩展，请设置 CUSTOMAISE_MCP_EXTRA_EXTENSION_IDS= 在MCP服务器的环境中。

需求

• Node.js ≥ 18
• 铬 安装了Customaise扩展（对于v2网桥协议，≥1.2.3——旧的扩展仍然可以工作，但不会显示cap使用情况）
• MCP电桥 在Customaise设置中启用（免费，已登录）

计划层次

MCP网桥对任何登录的Customaise用户都是免费的。免费使用上限为 每个UTC日50个电话 和 每个7天滚动窗口150个电话. 高级用户 解锁无限MCP。上限涵盖了每一个成功的工具分派（内置工具和WebMCP调用都一样）；失败的呼叫和协议级流量不计算在内。

当cap触发时，服务器在定义的实现中返回JSON-RPC错误 -32029 带有人类可读信息的插槽+结构化 data 携带范围、使用/限制和重置时间戳。表面工具错误的IDE会逐字呈现消息。无论级别如何，都需要登录；如果没有新的Firebase ID令牌，服务器将返回 -32028 MCP_AUTH_REQUIRED.

故障排除

“自定义扩展未连接”

• 确保Chrome正在使用Customaise扩展程序运行。
• 检查MCP网桥是否在扩展设置中启用。
• 扩展程序会在几秒钟内自动连接。

4050港口冲突

• 设置其他端口： CUSTOMAISE_WS_PORT=4051 npx @customaise/mcp.

导出后脚本未运行

• 呼叫 reload_tab 以触发脚本重新注入。
• 检查 @match 模式覆盖当前URL。

call_webmcp_tool 挂了几分钟

• 工具是 prompt-门控。在自动拒绝之前，用户必须在浏览器中批准，或者在远程HITL批准的预算为0.5分钟的情况下进行远程批准。显示待处理状态，而不是超时。

call_webmcp_tool 返回“拒绝同意”等错误

• 当用户拒绝模式、5分钟预算到期或该工具上设置了之前的“始终拒绝”覆盖时，预计会发生这种情况。用户可以在扩展设置中重置每个工具的覆盖。

list_webmcp_tools 重新加载后返回空值

• 按照惯例手册的故障排除清单进行操作。最常见的情况是：Customaise设置中的全局AgentScript切换已关闭，或者 @match 模式不包括URL。请参阅 customaise://agentscript-conventions 查看完整列表。

许可证

麻省理工学院