mcp

<!-- mcp-name: ai.foura/mcp --> # @fouradata/mcp [](https://www.npmjs.com/package/@fouradata/mcp) [](https://www.npmjs.com/package/@fouradata/mcp) [](https://www.npmjs.com/package/@fouradata/mcp) [](./LICENSE) [FourA 网络爬虫 API](https://foura.ai/) 作为 four 个 [模型上下文协议](https://modelcontextprotocol.io) 工具，加上六个内置的工作流提示。将它插入 Claude Desktop、Claude Code、Cursor、Windsurf 或任何其他 MCP 客户端，获取任意公共网页，绕过反机器人挑战，并渲染 JavaScript-heavy 网站 - 无需编写一行集成代码。 四个工具，六个提示，一个 API 密钥。一个智能的 `foura_auto` 工具为您选择获取方法（直接、代理或完整浏览器）；当您需要显式控制时，可以使用基本工具。发布到 npm 时带有构建 [溯源](https://docs.npmjs.com/generating-provenance-statements) - tarball 可以加密追溯到此仓库和 CI 运行。 **一键安装：** [](cursor://anysphere.cursor-deeplink/mcp/install?name=foura&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBmb3VyYWRhdGEvbWNwIl0sImVudiI6eyJGT1VSQV9BUElfS0VZIjoiWU9VUl9GT1VSQV9BUElfS0VZIn19) [](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522foura%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522%2540fouradata%252Fmcp%2522%255D%252C%2522env%2522%253A%257B%2522FOURA_API_KEY%2522%253A%2522YOUR_FOURA_API_KEY%2522%257D%257D) 两个按钮都预填充了 `YOUR_FOURA_API_KEY` 占位符 - 用您的密钥替换它。或者手动：`claude mcp add foura -- npx -y @fouradata/mcp`（首先在 env 中设置 `FOURA_API_KEY`）。完整的客户端设置如下。 [FourA](https://foura.ai) - [MCP 页面](https://foura.ai/mcp) - [GitHub](https://github.com/fouradata/mcp) - [npm](https://www.npmjs.com/package/@fouradata/mcp) - [文档](https://foura.ai/docs/mcp/server) - [托管端点](https://mcp.foura.ai/mcp) ## 快速入门 - 本地 stdio（推荐用于 Claude Desktop） 在 [foura.ai/dashboard/#api-keys](https://foura.ai/dashboard/#api-keys) 获取密钥（一次点击，创建时显示，格式为 `pk_live_...`）。然后将以下内容放入您的 MCP 客户端的配置文件中： ```json { "mcpServers": { "foura": { "command": "npx", "args": ["-y", "@fouradata/mcp"], "env": { "FOURA_API_KEY": "pk_live_..." } } } } ``` > **Claude Desktop 注意：** 在编辑配置文件之前，请完全退出 Claude Desktop（macOS 上为 `Cmd+Q`）。如果应用程序仍在运行，它将在退出时用其内存配置文件覆盖您的编辑。 npx 命令在第一次启动时下载软件包（~10s）并将其作为您的 MCP 客户端的子进程运行。不需要全局安装。相同的 JSON 适用于每个主要客户端 - 只需将其指向正确的文件： | 客户端 | 配置文件位置 | |---|---| | Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` | | Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` | | Claude Code | `claude mcp add foura -- npx -y @fouradata/mcp`（首先在 env 中设置 `FOURA_API_KEY`） | | Cursor | `~/.cursor/mcp.json` | | Windsurf | `~/.codeium/windsurf/mcp_config.json` | | VS Code（MCP 扩展） | `.vscode/mcp.json` 在您的工作区中 | 重启客户端后，`foura_auto`、`foura_single`、`foura_proxy`、`foura_browser` 显示在您的工具列表中，以及 `/prompts` 下的六个提示。 ## 快速入门 - 托管（流式 HTTP） 对于支持流式 HTTP 传输的客户端（Cursor、Windsurf、VS Code、带有 `--transport http` 的 Claude Code），请指向托管端点而不是运行本地子进程： ```json { "mcpServers": { "foura": { "url": "https://mcp.foura.ai/mcp", "headers": { "Authorization": "Bearer pk_live_..." } } } } ``` 当前的 Claude Desktop 版本拒绝裸 `url` 形式 - 对 Claude Desktop 使用上面的 stdio 配置，或通过 `mcp-remote` 桥接： ```json { "mcpServers": { "foura": { "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.foura.ai/mcp", "--header", "Authorization: Bearer pk_live_..."] } } } ``` ## 工具 `foura_auto` 是 **默认** - 给它一个 URL，它会返回内容，为您选择获取方法。其他三个是它协调的较低级别的基元；当您需要显式控制时，可以使用它们。 所有四个工具都标记为 `readOnlyHint: true` 和 `openWorldHint: true`，根据 [MCP 规范](https://modelcontextprotocol.io/specification/2025-06-18/server/tools) - 自动批准受信任的只读工具的客户端（Claude Desktop、Cursor 在 2026 年）调用它们时不会显示每个请求的确认模态。 每个响应都带有人类可读的文本（`content`）和键控的 `structuredContent` JSON 对象，针对工具的 `outputSchema` 进行验证。客户端将 `structuredContent` 原生传递给您的 LLM，跳过字符串化 JSON 的重新标记税。 ### `foura_auto` - 智能获取（默认） 给出一个 URL，获取内容。使用此工具时，您只需要页面，不需要选择方法。内部，它会走一个成本感知的阶梯 - 一个快速的直接请求，然后是一个旋转的代理，然后是一个完整的浏览器会话 - 只需升级到目标强制执行的内容，解决途中的常见机器人挑战，并廉价地重放同一个主机上的热会话。 ```jsonc { "url": "https://example.com", // 可选：一个子字符串，实际页面必须包含，以便 auto 可以将实际页面与保护目标上的挑战页面区分开来 "validate": { "data": { "accept": ["Example Domain"] } } } ``` 客户端界面故意最小化：`url`（必需），以及可选的 `method`、`headers`、`data`、`validate`、`returnSession`（默认为 `true`）、`forceProxy`（默认为 `true`）、`timeout_ms`（5000-180000，默认为 120000）、`ignoreProxies`。 `structuredContent` 形状：`{status, headers, data, meta, session}`。`meta` 始终存在 - `{rung, solved, attempts, credits}` - 提供交付的 rung 的跟踪以及花费了多少。`session`（`{proxy, cookies, userAgent}`）默认返回，以便您可以通过 `foura_single` / `foura_proxy` 重用相同的会话。发送 `returnSession: false` 以省略它。没有 `total_time` 字段。 ### `foura_single` - 快速 HTTP 一个 HTTP 请求，响应返回。通常 200ms-2s。使用它来获取静态页面、JSON API、服务器渲染的 HTML - 爬虫的面包和黄油。设置 `unblocker: true` 如果目标对线路信号很挑剔。 ```jsonc { "method": "GET", "url": "https://example.com", "unblocker": true } ``` 支持自定义标头、主体、分阶段超时、重定向控制、JSON 自动解析、二进制缓冲区模式和内置响应验证（`validate.status.accept`、`validate.data.fail` 等）。如果 `foura_single` 返回被阻止 - 状态 403/429、验证码页面，或响应标头 `x-vercel-mitigated: challenge` / `cf-mitigated: challenge`，或正文标题匹配 `Vercel Security Checkpoint` / `Just a moment` / `Attention Required` - 升级到 `foura_proxy`，尝试 25-30 次适用于这些一级 WAF。如果页面还需要 JavaScript 渲染，请将 `foura_proxy` 返回的 `proxy` ID 链接到 `foura_browser.proxy`。 `structuredContent` 形状：`{status, headers, data, total_time, ...}`。 ### `foura_proxy` - 带有重试的旋转代理 与 `foura_single` 相同的目标形状，但通过代理池路由，自动失败重试。每个主机评分选择最有可能针对特定目标成功的代理，因此您不会在已知不好的路由上浪费尝试。 ```jsonc { "maxTries": 5, "request": { "method": "GET", "url": "https://example.com/pricing", "unblocker": true } } ``` 通常延迟 1-5s。`structuredContent` 添加 `proxy`（使用的代理的 base36 ID - 将其传递给 `ignoreProxies` 以防它以后变坏）和 `total`（包括选择 + 重试的外层计时）。对于一级 WAF 挑战（Vercel Security Checkpoint、Cloudflare 'Just a moment'、Akamai Bot Manager），使用 `maxTries: 25-30` - 默认的 5 大小适用于轻度阻止的站点。如果仍然被阻止，则门户可能位于国家/ASN 白名单（不能通过旋转解决）- 转变策略。如果目标需要 JavaScript 渲染，请将返回的 `proxy` ID 链接到 `foura_browser.proxy` - 浏览器然后通过已经为此目标清除挑战的 IP 出口。 ### `foura_browser` - 完整的浏览器会话 一个真正的浏览器会话。JavaScript 运行，DOM 完成渲染，cookies 与响应一起返回。使用它时，页面是单页应用，内容延迟加载到第一帧后，或者存在反机器人挑战，需要真正的浏览器来清除。 ```jsonc { "url": "https://example.com/spa", "timeout_ms": 15000, "checkText": "data-table" } ``` 最慢的底层工具（2-10s），但唯一处理 JavaScript 端到端的工具。`checkText` 是一个一次性渲染后验证器（对渲染的 HTML 进行子字符串搜索 - 不是等待器，不会轮询）：如果子字符串丢失，则调用失败并返回错误信封。有用的页面返回 200 但实际内容丢失。`unblocker` 默认为 `true` - 会话积极解决它遇到的反机器人 / 验证码挑战（Cloudflare Turnstile 等）; 设置 `unblocker: false` 以呈现和返回页面完全按照加载，包含挑战页面。 `structuredContent` 形状故意与 single/proxy 不同：`{status, headers (object, not array), body (not data), cookies (full browser cookie shape), userAgent}`。 ## 内置提示 六个工作流模板在您的 MCP 客户端的 `/prompts` 下显示。它们协调一个或多个工具，而无需您逐一说明步骤。 | 提示 | 参数 | 它做了什么 | |---|---|---| | `smart_fetch` | `url, must_contain?, extract?` | 自动获取（选择方法，处理机器人保护）→ 返回或提取内容 | | `scrape_product_page` | `url` | 浏览器获取 → 提取标题、价格、图像、库存、SKU 为 JSON | | `extract_article` | `url` | Single → 代理 → 剥离导航/广告 → 返回干净的文章 JSON | | `monitor_pricing` | `url, target_price?` | 代理获取 → 提取价格 → 与目标比较 | | `check_endpoint_health` | `url, expected_text?` | 具有严格验证的 Single → 可达性/状态/计时报告 | | `bulk_fetch_urls` | `urls`（逗号分隔）| 并行 single → 自动回落到每个 URL 的代理 → 仅元数据 | 每个提示作为模板用户消息，您的 LLM 执行它，使用正确的工具。它们在空闲时消耗零个代币 - 仅调用的提示进入上下文窗口。 完整的配方文本 + 手动回退提示：[foura.ai/docs/mcp/recipes](https://foura.ai/docs/mcp/recipes)。完整的错误代码列表，请参阅 [foura.ai/docs/mcp/errors](https://foura.ai/docs/mcp/errors)。 ## 身份验证 您的 `Bearer` 令牌（或 stdio 模式下的 `FOURA_API_KEY` env var）转发到 FourA API 作为 `X-API-Key`。一个密钥，所有四个工具都使用。 密钥在 [仪表盘](https://foura.ai/dashboard/#api-keys) 创建，在创建时显示一次，任何时候都可以旋转或停用。参见 [foura.ai/docs/getting-started/authentication](https://foura.ai/docs/getting-started/authentication) 以获取完整的密钥管理流程。 ## 错误信封 - 智能代理重试的键控合约 每个错误（`isError: true`）都带有 `structuredContent` 信封，至少包含以下三个字段： ```jsonc { "service": "single" | "proxy" | "browser", "code": "ssrf_blocked" | "auth_failed" | "rate_limited" | ..., "error": "人类可读的消息" } ``` 上游返回状态时，还会提供 `status`（HTTP 代码），在速率限制/容量错误时，FourA API 信封添加 `retryAfter`、`current.{concurrency, rpm}`、`limits.{maxConcurrency, maxRpm}`。 | `code` | 发生时 | 能否安全重试？ | |---|---|---| | `ssrf_blocked` | 目标 IP 在私有/保留范围（RFC 5735+6598+IPv6 保留块）内 | 否 - 更改 URL | | `upstream_non_json` | 上游返回格式错误的正文 | 可能 - 调查 | | `bad_request` (400) | 输入形状被 FourA 拒绝 | 否 - 修复参数 | | `auth_failed` (401) | 密钥丢失、无效或停用 | 否 - 修复密钥 | | `forbidden` (403) | 已验证但不允许 | 否 | | `not_found` (404) | 目标/端点不存在 | 否 | | `rate_limited` (429) | 达到 RPM 限制 | 是 - 等待 `retryAfter` | | `at_capacity` (503) | 达到并发限制 | 是 - 等待 `retryAfter` | | `service_disabled` (503) | 维护窗口 | 是 - 等待 `retryAfter` | | `service_unavailable` (503) | 通用 503 | 是 - 短暂退后 | | `upstream_error` (≥500) | 上游 5xx | 是 - 指数退后 | | `upstream_client_error` (4xx) | 其他 4xx | 通常否 | LLM 代理可以直接读取 `code` 进行重试逻辑，无需解析散文。规范参考：[foura.ai/docs/api/errors](https://foura.ai/docs/api/errors)。 ## 组合工具 - 固定出口 IP 较低级别的工具可以组合使用。`foura_proxy` 返回使用的出口 base36 ID。将该 ID 传回 `foura_single.proxy` 或 `foura_browser.proxy`，下一个调用将通过 **相同的 IP** 出口 - 相同的会话，相同的指纹，相同的地理位置。 ```jsonc // 1. 为目标找到一个可用的出口 - 对于一级 WAF，请使用 maxTries:25-30 const r = await foura_proxy({ maxTries: 30, request: { method: "GET", url: "https://probe.example.com", unblocker: true } }); // → { status: 200, proxy: "4DZ3VE", ... } // 2. 重用它进行后续 HTTP 操作（cookie，多步骤流程） await foura_single({ method: "GET", url: "https://target/api", proxy: r.proxy }); // 3. 或通过相同的出口渲染 JavaScript - 出口通过已经为目标清除挑战的 IP 出口，因此快照捕获实际的 // 挑战后内容，而不是挑战页面。 await foura_browser({ url: "https://target/spa", proxy: r.proxy }); ``` 此链是 **一级 WAF + JavaScript 渲染目标**（Vercel Security Checkpoint，Cloudflare 'Just a moment'，Akamai Bot Manager 保护 SPA）的规范模式。直接调用 `foura_browser` 通常会捕获挑战页面 - 快照在挑战的延迟重载完成之前触发。先通过 `foura_proxy` 解决，然后链接。 要轮换离开已知坏代理，请在下一个 `foura_proxy` 调用中将其作为 `ignoreProxies: ["4DZ3VE"]` 传递。`proxy` 字段还接受原始 URL（`http://host:port`，`socks5://...`），如果您有自己的列表。 ## 大响应 - `offload_large`（默认：内联） 默认情况下（自 v0.2.0 起），完整的响应正文无论大小如何都内联返回在 `structuredContent` 中。这适用于每个 MCP 客户端。 如果您的客户端支持 MCP `resources/read`（并且您想节省大页面的令牌），请在工具调用中传递 `offload_large: true`。≥ 50 KB 的响应然后写入磁盘，作为 `resource_link` 返回，您的客户端仅在实际需要时获取正文。缓存的负载在 1 小时后过期。 ```jsonc { "method": "GET", "url": "https://en.wikipedia.org/wiki/Web_scraping", "offload_large": true // 启用以节省令牌 } ``` | 客户端 | `offload_large: true` | |---|---| | Claude Desktop | 暂不支持 - 默认留为 `false` | | Claude Code, Cursor, Windsurf | 支持 | | VS Code MCP 扩展 | 支持 | 租户隔离：只有存储有效载荷的 API 密钥才能读取它。 ## 其他限制 - **私有目标被拒绝。** 对私有或保留 IP 范围（RFC 5735、6598、IPv6 保留块）的请求在 MCP 层被阻止。仅允许公共互联网主机转发。 - **速率限制** 由 FourA API 按服务强制执行。并发 + RPM。详细信息请参阅 [foura.ai/docs/api/rate-limits](https://foura.ai/docs/api/rate-limits)。 - **正文大小上限** 为 256 KB（传入 `/mcp` 请求的实际 MCP 有效载荷小于 4 KB）。 - **DNS 重绑保护：**托管服务器验证 `Origin` 和 `Host` 头。基于浏览器的调用者必须来自允许的来源。服务器到服务器的调用者（curl，stdio 桥接模式下的 MCP 客户端）不受影响。 ## 自托管 MCP 服务器在一个容器中无状态运行 - 每个请求都带有自己的密钥，因此没有会话状态，没有粘性负载均衡，也无需协调。水平扩展到任意负载均衡器后面。 可配置的环境： | 变量 | 默认值 | 用途 | |---|---|---| | `PORT` | `3076` | HTTP 监听端口 | | `FOURA_API_BASE` | `https://api.foura.ai/api` | FourA REST 基址 | | `FOURA_MCP_PAYLOADS_DIR` | `/data/payloads` | ≥50 KB 响应缓存在磁盘上的位置 | 完整的源码在这里公开，遵循 MIT 许可证 - 从包含的 [`Dockerfile`](./Dockerfile) 构建容器（`docker build -t foura-mcp .`），或使用 `npx -y @fouradata/mcp` 直接从 npm 运行。有关本地构建和测试工作流，请参见 [DEVELOPMENT.md](./DEVELOPMENT.md)。 ## 许可证 MIT。参见 [`LICENSE`](./LICENSE)。 ## 链接 - FourA（网页抓取 API）：<https://foura.ai> - MCP 服务器页面：<https://foura.ai/mcp> - 源码（GitHub）：<https://github.com/fouradata/mcp> - npm 软件包：<https://www.npmjs.com/package/@fouradata/mcp> - API 文档：<https://foura.ai/docs> - MCP 服务器参考：<https://foura.ai/docs/mcp/server> - MCP 错误代码：<https://foura.ai/docs/mcp/errors> - MCP 配方：<https://foura.ai/docs/mcp/recipes> - REST API 错误：<https://foura.ai/docs/api/errors> - MCP 规范：<https://modelcontextprotocol.io> - 获取密钥：<https://foura.ai/dashboard/#api-keys>