Groundlane

English | 繁體中文

面向 AI 代理的可信 Web 访问层。

Groundlane 是一个开源、厂商中立、远程的 MCP 服务器，用于为 AI 代理提供对公共 Web 的受控访问。它提供统一的接口用于搜索、检索和确定性提取，将搜索路由到可替换的提供商，并在使用隔离的本地或 Browserless 浏览器之前，通过可选的 Jina Reader 升级困难的 Markdown 读取。

[!IMPORTANT] Groundlane 目前是早期预览版。其工具契约和部署模型仍在演进中；请勿将当前版本视为托管服务或通用的反机器人绕过方案。

为什么选择 Groundlane？

• 模型中立： 连接任何 Streamable HTTP MCP 客户端，而不是依赖模型供应商的内置 Web 工具。

• 提供商中立： 在统一的规范化结果契约下，跨多个具有每月免费额度的搜索 API 进行路由。

• HTTP 优先，必要时使用浏览器： 保持普通读取的快速性，并将 Chromium 保留用于 JavaScript、等待条件和支持的回退信号。

• 确定性提取： 使用 CSS 选择器选择字段，并接收结构化 JSON，无需隐式的 LLM 步骤。

• 安全优先： 对 MCP 端点进行身份验证，并应用 URL、重定向、网络、截止时间、字节、输出和并发限制。

• 自主控制的部署： 在您自己的环境中运行控制平面和浏览器工作负载，包括 Cloudflare Workers 和 Containers。

Related MCP server: agentfetch

MVP 工具

浏览器自动化是一个内部实现细节，称为 Groundlane Browser。Groundlane 在 MVP 中不暴露持久的浏览器会话。

快速开始

先决条件

• Node.js 22 或更高版本

• pnpm 10

• 用于浏览器回退的 Chromium

• 如果您想使用 web_search，至少需要一个受支持的每月免费搜索提供商密钥（Tavily、Exa、Parallel、Browserbase、Brave、Firecrawl 或 SerpApi）

本地运行

克隆此仓库，然后运行：

pnpm install
pnpm exec playwright install chromium
cp .env.example .env
set -a
source .env
set +a
pnpm dev

在 .env 中设置一个强 GROUNDLANE_AUTH_TOKEN。添加一个或多个受支持的提供商密钥以启用搜索。本地服务器监听配置的 PORT，并提供：

• POST /mcp — 经过身份验证的 Streamable HTTP MCP 端点

• GET /healthz — 进程存活检查

• GET /readyz — Container 可达性和服务配置就绪检查

连接 MCP 客户端

使用服务器 URL 和 bearer token 配置一个 Streamable HTTP MCP 客户端。客户端配置形式各不相同，但连接值如下：

URL: http://localhost:8080/mcp
Authorization: Bearer <GROUNDLANE_AUTH_TOKEN>

切勿将 token 放在查询字符串中，也不要将其提交到源代码控制。

服务器运行后，打开另一个 shell，加载相同的 .env，并验证 MCP 握手和公共 HTTP 路径：

set -a
source .env
set +a
pnpm smoke

设置 GROUNDLANE_SMOKE_BROWSER=1 以包含浏览器路径。

配置

Groundlane 从环境变量读取配置。请参阅 .env.example 获取完整的本地模板。

缺少搜索凭据不会阻止 web_fetch 或 web_extract 工作。它们只会使相应的搜索提供商不可用。

月度预算计算尝试的提供商请求（包括可重试的失败），并防止正在运行的 Groundlane 实例在达到其配置上限后选择提供商。这些预算刻意保守，但并非计费事实：Container 会重启，多个实例不共享计数器，并且某些提供商收取可变积分。请保持提供商侧的花费限制启用，并根据您的实际计划覆盖预算。

架构

MCP client
    |
    v
Cloudflare Worker / Node HTTP edge
    |  authentication, limits, request identity
    v
tool registry
    |-- web_search  -> monthly-free provider router (7 adapters)
    |-- web_fetch   -> safe HTTP -> optional Jina Reader -> browser fallback
    `-- web_extract -> fetch pipeline -> deterministic DOM extraction

核心策略和契约不依赖于提供商或浏览器运行时。适配器位于狭窄的接口之后。浏览器后端可以是 Container 本地的 Playwright 或 Browserless /content；engine 和 backend 输出字段会披露哪个路径产生了结果，而不会改变公共 MCP 工具。托管后端会收到请求的公共 URL，因此它们是选择加入的，而不是静默默认。

阅读 架构 了解组件边界、请求流程和设计决策。

安全

Web 检索是一种对 SSRF 敏感的能力。Groundlane 将用户 URL、重定向、浏览器子资源和搜索提供商 URL 视为不受信任的。部署应保持身份验证启用，使用出站网络策略，并保留默认的资源限制。

该项目不承诺通用的 CAPTCHA 解决、隐形自动化或访问您无权检索的内容。操作员负责目标站点的条款、robots 策略、隐私义务和适用法律。

请参阅 SECURITY.md 了解安全模型和私有漏洞报告流程。

部署

预期的生产拓扑使用 Cloudflare Worker 作为公共控制平面，并使用 Cloudflare Container 作为 Node/Playwright 浏览器工作负载。有关先决条件、密钥、部署步骤和验证，请参阅 在 Cloudflare 上部署。

路线图

• 定义厂商中立的 web_fetch、web_search 和确定性 web_extract 表面

• 添加可选的 Jina Reader 和 Browserless 检索后端，并带有来源信息

• 稳定 MCP 契约并发布兼容性测试夹具

• 强化 Cloudflare Worker + Container 部署和操作遥测

• 添加缓存适配器和提供商健康/成本感知路由

• 添加带有明确预算的可选批处理/爬取原语

• 将有状态浏览器会话评估为独立的、生命周期安全的单独能力

路线图是方向性的，不是发布承诺。请参阅 研究档案 了解当前范围背后的证据。

文档

• 架构

• MVP 产品需求

• Cloudflare 部署

• 安全策略

• 贡献指南

• 研究档案

贡献

欢迎提交 issue 和 pull request。在贡献之前，请阅读 CONTRIBUTING.md 和 行为准则。安全漏洞必须按照 SECURITY.md 中的描述私下报告。

许可证

Groundlane 根据 Apache License 2.0 许可。