@bsbofmusic/cdper-mcp

Lightweight MCP shell for agent-driven remote Chrome control through cdp-bridge, with integrated ChatGPT and Doubao runtime tools.

What's new in 1.4.6

• Doubao runtime now uses element-level interaction for 专家模式 switching, 新对话, 发送, and unavailable-page recovery — no coordinate clicking in the main Doubao flow.
• Doubao and ChatGPT smart wait now snapshot the pre-send reply baseline and only accept content that belongs to the current turn, avoiding stale reply reuse.
• Doubao page readiness and mode switching are now state-driven, reducing fixed waits and improving stability on slower pages.

Product role

cdper-mcp is the agent-facing shell. For productization, it should stay lightweight and delegate runtime logic to the shared core workspace.

See:

• ../ARCHITECTURE.md
• ../PACKAGES.md
• ../MIGRATION_PLAN.md

⚠️ FOR LEARNING PURPOSES ONLY | 仅供学习研究使用 使用本工具即表示您同意自行承担所有合规风险。

工作原理

你的 AI Agent（Claude Desktop / OpenClaw / Cursor...）
  ↓ MCP Protocol（stdio）
  ↓ cdper-mcp
  ↓ CDP WebSocket（cdp-bridge + Tailscale）
  ↓ 远程 Chrome（已登录任意网站）
  ↓ 抓取 / 截图 / 交互
  ↓ 返回结构化数据
你的 AI Agent

前置要求

| 要求 | 说明 | |------|------| | cdp-bridge | CDP 桥接服务 | | Tailscale | 两台机器在同一网络下 | | Node.js >= 18 | 运行环境 |

安装

npm install -g @bsbofmusic/cdper-mcp

安装后自动检测环境，缺失依赖时尝试自动修复。

配置

CDP 节点配置

# 编辑配置（支持单节点或多节点）
nano ~/.cdp-auth.json

// 单节点
{ "ws_url": "ws://100.121.130.36:39222/devtools/browser?token=xxx" }

// 多节点 + 权重（加权轮询）
{
  "nodes": [
    { "id": "node-1", "ws_url": "ws://100.121.130.36:39222/devtools/browser?token=xxx", "weight": 2 },
    { "id": "node-2", "ws_url": "ws://100.121.130.37:39222/devtools/browser?token=xxx", "weight": 1 }
  ]
}

工具清单

| 工具 | 说明 | |------|------| | chatgpt_query | 通过稳定 runtime 调用远端 ChatGPT | | doubao_query | 通过稳定 runtime 调用远端 Doubao | | cdp_fetch | 抓取页面内容，支持 CSS 选择器 / 模板提取 | | cdp_screenshot | 页面截图 | | cdp_interact | 页面交互（click / type / scroll / press） | | cdp_batch_fetch | 批量抓取（Crawlee 并发） | | cdper_doctor | 健康检测 + 问题诊断 | | cdper_ensure | 自动修复缺失依赖和环境问题 | | cdper_version | 版本信息 | | cdper_cache_clear | 清除离线缓存 | | cdper_templates_update | 强制更新提取模板 |

快速开始

# 诊断环境
cdper_doctor

# 自动修复
cdper_ensure

# 抓取页面
cdper-mcp
# 然后通过 MCP 客户端调用 cdp_fetch

MCP 工具调用示例

cdp_fetch

{
  "tool": "cdp_fetch",
  "params": {
    "url": "https://www.example.com",
    "extract_template": "reddit-post"
  }
}

chatgpt_query

{
  "tool": "chatgpt_query",
  "params": {
    "query": "请只回复：HELLO",
    "mode": "thinking"
  }
}

doubao_query

{
  "tool": "doubao_query",
  "params": {
    "query": "请只回复：HELLO",
    "mode": "expert"
  }
}

doubao_query now prefers state-driven expert-mode switching and turn-bound reply extraction, so short replies like 只回复：HELLO no longer get confused with old page content.

cdp_interact（🆕 press 键盘操作）

{
  "tool": "cdp_interact",
  "params": {
    "url": "https://chat.openai.com",
    "action": "press",
    "text": "Enter"
  }
}

支持键名：Enter / Tab / Escape / ArrowUp / ArrowDown / Backspace

cdp_batch_fetch

{
  "tool": "cdp_batch_fetch",
  "params": {
    "urls": ["https://reddit.com/r/..."],
    "max_concurrency": 3,
    "extract_template": "reddit-post"
  }
}

环境变量

| 变量 | 默认值 | 说明 | |------|--------|------| | CDP_WS | none | 直接提供单节点 WebSocket 地址，优先级最高 | | CDP_AUTH_PATH | ~/.cdp-auth.json | CDP 认证配置路径 | | CDPER_ARCHIVE_DIR | ~/.cdper-archive/ | 归档目录 | | CDPER_CACHE_TTL | 3600 | 缓存 TTL（秒） | | LOG_LEVEL | info | debug | info | warn | error | silent |

智能特性

安装 → 检测 → 提醒 → 使用

npm install @bsbofmusic/cdper-mcp
    ↓ 自动 postinstall
环境检测（doctor）
    ↓
发现问题 → 自动修复（ensure）→ 无法修复 → 提示修复步骤
    ↓
启动时检测 npm 最新版本，有更新则提醒
    ↓
正常执行

自我修复（ensure）

| 问题 | 修复动作 | |------|---------| | puppeteer-core 缺失 | 自动安装 | | 配置不存在 | 创建空配置模板 | | 模板过期 | 自动从 GitHub 更新 |

版本自检

启动时（非阻塞）检查 npm 最新版本，发现更新时输出：

⚠️  Update available: 1.3.0 → 1.4.0
   Run: npm install -g @bsbofmusic/cdper-mcp@latest

已知限制

• 需要稳定的 Tailscale 网络连接
• ⚠️ 远程 Chrome 必须已登录目标网站
• 批量抓取依赖 Crawlee（可选，未安装时自动降级）
• chatgpt_query / doubao_query 依赖 cdp-bridge 已正确暴露远端登录浏览器

链接

• cdp-bridge
• cdper-templates
• npm

免责声明

⚠️ 使用本工具即表示您同意自行承担所有合规风险及后果。

1. 平台使用限制：本工具通过 CDP 控制任意网页界面，可能违反相关平台服务条款。
2. 账号风险：使用本工具访问受保护内容可能导致相关账号被限制或封禁，风险完全由使用者承担。
3. 测试后处理：使用完毕后请关闭 cdp-bridge 的浏览器实例并清除登录状态，防止未授权访问。
4. 仅供学习：本工具仅用于技术研究和个人学习，不得用于商业目的或任何批量自动化行为。

作者不对任何使用后果负责，包括但不限于账号封禁、服务限制、数据泄露。

许可证

MIT License