Crawlio Browser

克劳利奥特工

](https://www.npmjs.com/package/crawlio-browser) 

文档 | API 参考 | Chrome 扩展

MCP服务器，通过CDP让AI完全控制实时Chrome浏览器。100个工具（93个浏览器+3个提取+3个记录+1个编译器），具有框架感知智能、类型化证据基础设施和置信度跟踪发现，可以捕获静态爬虫无法看到的内容。

注： 此回购取代 crawlio-browser-mcp现在所有的发展都发生在这里。

链接：

• Chrome网络商店
• 文档
• 网站

何时使用Crawlio代理

当您的AI需要与…交互时，请使用Crawlio Agent 真实浏览器 --SPA、经过身份验证的页面、动态内容、JS渲染框架。与无头浏览器工具不同，Crawlio Agent连接到 您的实际Chrome 通过轻量级扩展，让人工智能访问您的登录会话、Cookie和完整浏览器状态。

Crawlio代理与无头浏览器工具： 无头工具会启动一个单独的浏览器进程。Crawlio Agent连接到您现有的Chrome浏览器——没有单独的浏览器，没有登录流，可以完全访问您的标签和会话。

快速开始

1. 安装 Chrome 扩展
2. 运行init向导：

   npx crawlio-browser init

就是这样。自动检测和配置14个MCP客户端：Claude Code、Cursor、VS Code、Codex、Gemini CLI、Claude Desktop、ChatGPT Desktop、Windsurf、Cline、Zed、Goose、OpenCode、MCPorter和Cline CLI。

初始化向导选项

npx crawlio-browser init              # Default: code mode, stdio transport
npx crawlio-browser init --full       # Full mode (100 individual tools)
npx crawlio-browser init --portal     # Portal mode (persistent HTTP server)
npx crawlio-browser init --cloudflare # Add Cloudflare MCP (89 tools, no wrangler)
npx crawlio-browser init --dry-run    # Show what would happen
npx crawlio-browser init --yes        # Skip prompts (CI / scripted installs)
npx crawlio-browser init -a claude    # Target specific MCP client

运输方式

建议对Claude Code使用门户模式——服务器在上下文压缩和会话重启过程中保持不变。在macOS上， --portal 安装一个launchd代理，用于登录时自动启动。

手动设置（任何客户端）

Per-client manual config

克劳德桌面 --添加到 claude_desktop_config.json:

{ "mcpServers": { "crawlio-browser": { "command": "npx", "args": ["-y", "crawlio-browser"] } } }

克劳德代码（门户模式） --开始 npx crawlio-browser --portal，然后添加到 .mcp.json:

{ "mcpServers": { "crawlio-browser": { "type": "http", "url": "http://127.0.0.1:3001/mcp" } } }

克劳德代码（stdio）：

claude mcp add crawlio-browser -- npx -y crawlio-browser

光标 --添加到 .cursor/mcp.json:

{ "mcpServers": { "crawlio-browser": { "command": "npx", "args": ["-y", "crawlio-browser"] } } }

帆板运动 --添加到Windsurf设置>MCP：

{ "mcpServers": { "crawlio-browser": { "command": "npx", "args": ["-y", "crawlio-browser"] } } }

Cline（VS代码） --添加到 settings.json:

{ "cline.mcpServers": { "crawlio-browser": { "command": "npx", "args": ["-y", "crawlio-browser"] } } }

ChatGPT桌面 --设置>集成>MCP： 网址： http://127.0.0.1:3001/mcp |类型：流式HTTP

运作原理

AI Client (stdio/http)  -->  MCP Server (Node.js)  -->  Chrome Extension (MV3)
                             crawlio-browser               WebSocket -> CDP

MCP服务器通过WebSocket与Chrome扩展程序通信。该扩展程序通过Chrome DevTools协议（CDP）控制浏览器。

能力

框架感知智能

每 execute 调用会探测浏览器中的框架签名，并注入变形 smart 带有框架原生访问器的对象。React状态、Vue反应性、Next.js路由、Shopify购物车数据——跨4层的17个框架名称空间，在运行时检测并在每次导航时重建。AI不会查询通用DOM；它查询框架自己的数据结构。

循证分析

方法模式在代码模式的基础上增加了高阶方法和类型化证据系统。 smart.extractPage() 在一次调用中运行7个并行操作——页面捕获、性能指标、安全状态、字体检测、元提取、可访问性审计和移动就绪检查。失败的操作产生类型化 CoverageGap 录制而不是静音 nulls.通过以下方式创建的调查结果 smart.finding() 当支持数据缺失时，自动调整他们的信心。结果：结构化、可审计的研究成果，具有差距跟踪和置信度传播功能。

会话录制和回放

将浏览器交互记录为结构化数据，然后将其编译为可重用的SKILL.md自动化。在录制过程中，会自动拦截12个交互工具——点击、打字、导航、滚动——每个工具都会捕获参数、结果、时间和页面URL compileRecording() 调用将会话转换为确定性自动化脚本。

自动设置和可操作性

每一个变异动作(click, type, navigate, select_option)在执行操作之前运行可操作性检查——轮询可见性、维度、启用状态和覆盖检测。行动后，渐进式回退解决延迟问题([0, 20, 100, 100, 500]ms)等待DOM突变停止。AI不需要手动 sleep() 行动之间的召唤。

体系结构：JIT上下文运行时

JIT上下文MCP运行时是一种分层执行架构，其中每一层都吸收了一类原本会落在模型上的复杂性。该模型包含三个工具和一个干净的SDK。表面之下的一切都是运行时吸收的现实。

                     ┌───────────────────────────────────┐
                     │        AI Model (LLM)             │
                     │  Writes code, reads errors, loops  │
                     └───────────────┬───────────────────┘
                                     │  3 tools: search, execute, connect_tab
                                     ▼
┌─────────────────────────────────────────────────────────────────┐
│                    JIT Context MCP Runtime                       │
│                                                                  │
│  ┌────────────────────────────────────────────────────────────┐  │
│  │  METHOD MODE                                               │  │
│  │  Behavioral protocol + higher-order methods                │  │
│  │  scrollCapture · waitForIdle · extractPage · comparePages  │  │
│  │  detectTables · extractTable · waitForNetworkIdle ·        │  │
│  │  extractData                                               │  │
│  │                                                            │  │
│  │  ↳ Absorbs: behavioral variance, ad-hoc composition,      │  │
│  │    inconsistent output shapes, data extraction patterns    │  │
│  ├────────────────────────────────────────────────────────────┤  │
│  │  POLYMORPHIC CONTEXT                                       │  │
│  │  17 framework namespaces, injected Just-In-Time            │  │
│  │  react · vue · angular · nextjs · shopify · ...            │  │
│  │                                                            │  │
│  │  ↳ Absorbs: framework opacity, minified code,             │  │
│  │    devtools hook complexity                                │  │
│  ├────────────────────────────────────────────────────────────┤  │
│  │  ACTIONABILITY ENGINE                                      │  │
│  │  7 core smart methods with built-in resilience             │  │
│  │  click · type · navigate · waitFor · evaluate ·            │  │
│  │  snapshot · screenshot                                     │  │
│  │                                                            │  │
│  │  ↳ Absorbs: DOM timing, hydration delays, CSS animations, │  │
│  │    disabled states, overlapping elements                   │  │
│  ├────────────────────────────────────────────────────────────┤  │
│  │  TETHERED IPC BRIDGE                                       │  │
│  │  WebSocket ↔ Chrome extension, message queue,              │  │
│  │  heartbeat, auto-reconnect, stale detection                │  │
│  │                                                            │  │
│  │  ↳ Absorbs: connection drops, tab refreshes,              │  │
│  │    port conflicts, extension lifecycle                     │  │
│  ├────────────────────────────────────────────────────────────┤  │
│  │  133 RAW COMMANDS  (bridge.send)                           │  │
│  │  CDP-level browser control via Chrome extension            │  │
│  └────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                                     │
                                     ▼
                     ┌───────────────────────────────────┐
                     │         Live Chrome Browser        │
                     │   Persistent session, real DOM,    │
                     │   framework runtime, user state    │
                     └───────────────────────────────────┘

每一层吸收什么

执行生命周期

1. 发现 --模型调用 search("page capture performance") 并获取相关命令的文档
2. 框架检测 --运行时探测实时DOM，检测活动框架，构造多态 smart 具有适当命名空间的对象
3. 示波器组装 --Model的代码被编译成一个带有注入参数的异步函数： bridge （133个命令）， crawlio （HTTP客户端）， sleep, TIMEOUTS, smart （7个核心+8个高阶+最多17个框架命名空间）， compileRecording
4. 执行 --方法模式方法组成了较低的层： extractPage() 火灾7平行 bridge.send() 电话； click() 运行可操作性引擎； react.getVersion() 评估特定于框架的表达式
5. 错误恢复（代理REPL） --失败时，浏览器将保持在产生错误的确切状态。模型读取结构化错误，进行调整并调用 execute 再一次。框架缓存持续存在——除非URL更改，否则不会重新检测

设计原则

1. 向下吸收复杂性 --每一类困难（连接管理、DOM计时、框架检测、多步组合）都由最适合它的层处理。模型只在顶部遇到干净的接口。
2. 根据目标塑造SDK --多态上下文系统检测页面是什么，并重塑可用的方法以进行匹配。该模型针对稳定的接口进行写入；运行时在下面进行调整。
3. 跨周期保持状态 --系留架构意味着模型可以在相同的实时环境中失败、学习和重试——将错误处理从“从头开始重新启动”转变为“调整并继续”

如何比较

阅读完整的架构指南→

两种模式

代码模式（3个工具）--默认

将100个工具拆分为3个高级工具，模式标记减少约95%：

// Navigate and screenshot
await bridge.send({ type: 'browser_navigate', url: 'https://example.com' }, 30000);
await sleep(2000);
const screenshot = await bridge.send({ type: 'take_screenshot' }, 10000);
return screenshot;

全模式（100个工具）

所有直接接触LLM的工具。启用 --full:

npx crawlio-browser init --full

智能对象

在代码模式下 smart 对象为框架感知助手提供了自动等待和可操作性检查。

核心方法

高阶方法

类型化证据

带置信度传播的结构化分析结果方法：

当发现 dimension 如果匹配有效覆盖范围差距，则信心会自动上限：

框架命名空间

当检测到框架时，智能对象会公开特定于框架的助手：

React — smart.react

Vue.js — smart.vue

Angular — smart.angular

Svelte — smart.svelte

Redux — smart.redux

Alpine.js — smart.alpine

Next.js — smart.nextjs

Nuxt — smart.nuxt

Remix — smart.remix

Shopify — smart.shopify

WordPress — smart.wordpress

More frameworks — Gatsby, WooCommerce, Laravel, Django, Drupal, jQuery

方法模式

方法模式是建立在代码模式之上的域层。它增加了高阶方法、类型化证据系统和行为协议 execute 沙盒——无需更改工具表面。该模型仍然有三个工具。相同 smart 对象。下面是相同的133命令目录。变化是什么 *里面* execute.

成熟阶梯

建筑

┌────────────────────────────────────────────────────────────┐
│                      execute sandbox                       │
│                                                            │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  Behavioral Protocol  (web-research skill)           │  │
│  │  Acquire → Normalize → Analyze                       │  │
│  ├──────────────────────────────────────────────────────┤  │
│  │  Evidence Infrastructure                             │  │
│  │  finding() · findings() · clearFindings()            │  │
│  │  Typed records · Coverage gaps · Confidence prop.    │  │
│  ├──────────────────────────────────────────────────────┤  │
│  │  Higher-Order Methods  [8]                           │  │
│  │  scrollCapture · waitForIdle · extractPage ·         │  │
│  │  comparePages · detectTables · extractTable ·        │  │
│  │  waitForNetworkIdle · extractData                    │  │
│  ├──────────────────────────────────────────────────────┤  │
│  │  Smart Core  [7 methods]                             │  │
│  │  evaluate · click · type · navigate · waitFor ·      │  │
│  │  snapshot · screenshot                               │  │
│  ├──────────────────────────────────────────────────────┤  │
│  │  Framework Namespaces  [up to 17, injected JIT]      │  │
│  │  react · vue · angular · nextjs · shopify · ...      │  │
│  ├──────────────────────────────────────────────────────┤  │
│  │  bridge.send()  — 133 raw commands                   │  │
│  └──────────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────────┘

每一层都编码了更多的领域知识。 bridge.send({ type: "capture_page" }) 捕获一页。 smart.extractPage() 捕获页面并并行运行性能指标、安全状态、字体检测、可访问性分析和移动就绪性检查——七个操作、一个调用、补充数据的优雅失败、为任何失败的内容键入间隙。

证据基础设施

覆盖缺口 --当补充操作在 extractPage() 失败，他们不会默默地回来 null键入的差距记录了维度、原因、影响以及是否降低了对相关调查结果的信心：

// Example gap from a failed performance metrics call
{ dimension: "performance", reason: "CDP domain disabled", impact: "method-failed", reducesConfidence: true }

工具强制调查结果 — smart.finding() 在工具级别验证每个字段。如果不符合模式，模型就无法生成结果——它要么返回有效的 Finding 或者出现明显的错误。调查结果逐渐累积 execute 会话中的呼叫通过 smart.findings().

会话聚合 --调查结果和覆盖范围差距持续存在 execute 电话。一个模型可以在多个调用中进行发现，然后使用 smart.findings().使用重置 smart.clearFindings().

端到端示例：竞争审计

// 1. Extract and compare both sites (scaffold + gaps included)
const comparison = await smart.comparePages(
  'https://acme.com',
  'https://rival.com'
);

// 2. Make findings — confidence auto-adjusts based on data availability
smart.finding({
  claim: 'Rival loads 2.3x faster on Largest Contentful Paint',
  evidence: [
    `Acme LCP: ${comparison.siteA.performance?.webVitals?.lcp}ms`,
    `Rival LCP: ${comparison.siteB.performance?.webVitals?.lcp}ms`,
  ],
  sourceUrl: 'https://acme.com',
  confidence: 'high',
  method: 'comparePages + extractPage performance metrics',
  dimension: 'performance',  // if perf data failed, confidence caps to "medium"
});

smart.finding({
  claim: 'Acme has 12 images without alt text; Rival has 0',
  evidence: [
    `Acme imagesWithoutAlt: ${comparison.siteA.accessibility?.imagesWithoutAlt}`,
    `Rival imagesWithoutAlt: ${comparison.siteB.accessibility?.imagesWithoutAlt}`,
  ],
  sourceUrl: 'https://acme.com',
  confidence: 'high',
  method: 'comparePages + extractPage accessibility summary',
  dimension: 'accessibility',
});

// 3. Capture visual evidence
await smart.navigate('https://acme.com');
await smart.waitForIdle();
const acmeVisuals = await smart.scrollCapture({ maxSections: 5 });

// 4. Return accumulated session findings + visual evidence
return {
  findings: smart.findings(),
  scaffold: comparison.scaffold,
  gaps: { acme: comparison.siteA.gaps, rival: comparison.siteB.gaps },
  visualEvidence: { acme: acmeVisuals.sectionCount + ' sections captured' },
};

例子

导航、提取和分析

// Connect to active tab, extract structured page evidence
const page = await smart.extractPage();
const finding = smart.finding({
  claim: `Site uses ${page.capture.framework?.name || 'no detected framework'}`,
  evidence: [`Framework: ${JSON.stringify(page.capture.framework)}`],
  sourceUrl: page.meta?.canonical || 'active tab',
  confidence: 'high',
  method: 'extractPage framework detection',
});
return { page: page.meta, finding };

移动仿真+截图

// Emulate iPhone and capture
await bridge.send({ type: 'emulate_device', device: 'iPhone 14' }, 10000);
await smart.navigate('https://example.com');
await smart.waitForIdle();
const screenshot = await smart.screenshot();
return screenshot;

记录和编译自动化

// Record a browser session, then compile to reusable skill
await bridge.send({ type: 'start_recording' }, 10000);
await smart.navigate('https://example.com');
await smart.click('button.submit');
await smart.type('#email', 'test@example.com');
const session = await bridge.send({ type: 'stop_recording' }, 10000);
return compileRecording(session.session, 'signup-flow');

拦截和模拟网络

// Block analytics, mock API response
await bridge.send({
  type: 'browser_intercept',
  pattern: '*analytics*',
  action: 'block'
}, 10000);
await bridge.send({
  type: 'browser_intercept',
  pattern: '*/api/user',
  action: 'mock',
  body: JSON.stringify({ name: 'Test User' }),
  statusCode: 200
}, 10000);
await smart.navigate('https://example.com');
return await smart.snapshot();

会话录制

将浏览器会话记录为结构化数据，然后将其编译为可重用的自动化技能。在录制过程中（点击、键入、导航、滚动等），会自动拦截12个交互工具，捕获参数、结果、计时和页面URL。

// In code mode: record, interact, compile
await bridge.send({ type: 'start_recording' }, 10000);
// ... interact with the page ...
const session = await bridge.send({ type: 'stop_recording' }, 10000);
const skill = compileRecording(session.session, 'my-automation');
return skill;

在全模式下，录制可作为4个单独的工具使用： start_recording, stop_recording, get_recording_status，以及 compile_recording.

自动设置

可变工具(browser_click, browser_type, browser_navigate, browser_select_option)使用可操作性检查：

1. 飞行前：在操作之前轮询元素可见性、稳定性和启用状态
2. 行动：分派CDP命令
3. 后结算：等待DOM突变随着逐步回退而停止 [0, 20, 100, 100, 500]ms

这意味着AI不需要手动添加 sleep() 或 waitFor() 操作之间的调用——这些工具会自动处理SPA渲染延迟。

框架检测

检测 64项技术 使用全局变量、DOM标记、元标记、HTTP标头和脚本URL跨4层：

多框架检测返回 主要的，重要的 框架（元框架优先）加上 subFrameworks 整个堆栈的数组。

工具参考

All 100 tools — Connection, Capture, Navigation, Network, Storage, Emulation, and more

连接和状态

页面捕获

导航与交互

网络

框架和标签

Cookie和存储

对话

仿真

安全

服务人员

DOM操作

CSS和JS覆盖率

性能和内存

PDF和辅助功能

目标和背景

可视化调试

会话录制

Crawlio应用程序集成

可选--必需 Crawlio.app 在本地运行。

需求

• Node.js >= 18
• 铬 （或铬）与 Crawlio代理扩展 安装
• Crawlio.app （可选）--用于网站爬行和丰富

资源

• 文档
• API 参考
• 产品页面
• Chrome 扩展
• 更新日志
• 上一个回购 --该项目取代 crawlio-browser-mcp

许可证

麻省理工学院