# https://github.com/0pen1/scrapingdog-mcp 项目说明书 生成时间：2026-07-31 07:58:45 UTC ## 目录 - [项目概述](#page-overview) - [系统架构与模块划分](#page-architecture) - [API 密钥解析与共享 HTTP 请求层](#page-api-key-http) - [九大工具一览](#page-tools-overview) - [搜索引擎与社交工具详解](#page-search-tools) - [抓取、截图与代理工具详解](#page-scrape-screenshot) - [工具 Schema 定义与注册流程](#page-tools-registry) - [MCP 客户端配置与部署](#page-deployment) ## 项目概述 ### 相关页面 相关主题：[系统架构与模块划分](#page-architecture), [九大工具一览](#page-tools-overview)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/0pen1/scrapingdog-mcp/blob/main/README.md) - [package.json](https://github.com/0pen1/scrapingdog-mcp/blob/main/package.json) - [LICENSE](https://github.com/0pen1/scrapingdog-mcp/blob/main/LICENSE) - [src/index.ts](https://github.com/0pen1/scrapingdog-mcp/blob/main/src/index.ts) - [src/server.ts](https://github.com/0pen1/scrapingdog-mcp/blob/main/src/server.ts) - [tsconfig.json](https://github.com/0pen1/scrapingdog-mcp/blob/main/tsconfig.json)
# 项目概述 ## 项目背景与定位 `scrapingdog-mcp` 是一个基于 **Model Context Protocol (MCP)** 协议实现的服务端程序，其核心定位是为支持 MCP 协议的 AI 助手（例如 Claude Desktop 等客户端）暴露 Scrapingdog 提供的网页抓取能力。通过该 MCP 服务，AI 助手可以在对话过程中以工具调用的方式，直接使用 Scrapingdog 的多种接口完成实时网络数据获取。资料来源：[README.md:1-20]() 项目以单一可执行包的形式发布，遵循 `npm` 包的标准结构，并提供 `bin` 入口以便通过 `npx` 直接启动。资料来源：[package.json:1-40]() ## 核心功能范围 项目围绕 Scrapingdog API 封装了若干高频使用的抓取工具，主要包括： - **Google 搜索抓取**：接受关键词与可选的地理、域名过滤等参数，返回结构化的 Google 搜索结果列表。资料来源：[src/server.ts:1-30]() - **通用网页抓取**：以 URL 为输入抓取目标页面的 HTML 或文本内容，并支持自定义请求头、超时与渲染等待。资料来源：[src/server.ts:31-60]() - **代理与高级渲染**：将 Scrapingdog 的代理区域、JS 渲染等高级参数透传至工具调用层，便于在客户端按需开启。资料来源：[README.md:21-50]() 所有工具统一通过 MCP 的 `tools/list` 与 `tools/call` 方法暴露，参数 schema 在服务端使用 JSON Schema 进行描述。资料来源：[src/server.ts:61-90]() ## 技术架构 项目使用 **TypeScript** 编写，遵循典型 MCP Server 实现模式，整体组件职责如下： | 组件 | 职责 | |------|------| | `src/index.ts` | 进程入口，初始化 MCP Server 并处理 stdio 传输 | | `src/server.ts` | 注册工具列表、参数校验、调用 Scrapingdog SDK | | `package.json` | 声明依赖、脚本与 `bin` 入口 | | `tsconfig.json` | 配置 TypeScript 编译选项与输出目录 `dist/` | 构建产物经 TypeScript 编译后输出至 `dist/`，并通过 `package.json` 中的 `bin` 字段将编译产物暴露为可执行命令，供 MCP 客户端以命令方式注册并拉起。资料来源：[package.json:41-70]() [tsconfig.json:1-20]() 运行时通过 stdio 与 MCP 客户端进行 JSON-RPC 通信，工具调用结果以 MCP 的 `TextContent` / `JSON` 形式回传，便于客户端按结构化内容进行渲染。资料来源：[src/index.ts:1-30]() ## 部署与集成方式 用户可在任意兼容 MCP 协议的客户端中通过如下典型配置集成该服务： ```json { "mcpServers": { "scrapingdog": { "command": "npx", "args": ["-y", "scrapingdog-mcp"], "env": { "SCRAPINGDOG_API_KEY": "" } } } } ``` 资料来源：[README.md:51-90]() 调用 Scrapingdog 接口所需的 API Key 通过环境变量 `SCRAPINGDOG_API_KEY` 注入，服务端在启动时读取并在每次请求中透传，避免在源码或配置文件中硬编码敏感凭证。资料来源：[src/index.ts:31-60]() ## 许可证与分发 项目以 **MIT 许可证** 开源分发，允许在保留版权声明的前提下自由使用、修改与再发布。资料来源：[LICENSE:1-10]() ## 总结 `scrapingdog-mcp` 是一个轻量、聚焦的 MCP 适配层：上接 MCP 客户端的工具调用协议，下接 Scrapingdog 的网页抓取 API。其价值在于以最小化的胶水代码，让 AI 助手在对话内即可完成搜索与网页内容获取，从而扩展模型在实时信息检索场景下的能力边界。资料来源：[README.md:91-120]() --- ## 系统架构与模块划分 ### 相关页面 相关主题：[API 密钥解析与共享 HTTP 请求层](#page-api-key-http)
相关源码文件 以下源码文件用于生成本页说明： - [src/index.ts](https://github.com/0pen1/scrapingdog-mcp/blob/main/src/index.ts) - [package.json](https://github.com/0pen1/scrapingdog-mcp/blob/main/package.json) - [tsconfig.json](https://github.com/0pen1/scrapingdog-mcp/blob/main/tsconfig.json) - [src/scrapingdog/client.ts](https://github.com/0pen1/scrapingdog-mcp/blob/main/src/scrapingdog/client.ts) - [src/scrapingdog/types.ts](https://github.com/0pen1/scrapingdog-mcp/blob/main/src/scrapingdog/types.ts) - [README.md](https://github.com/0pen1/scrapingdog-mcp/blob/main/README.md)
# 系统架构与模块划分 ## 1. 概述 scrapingdog-mcp 是一个基于 Model Context Protocol (MCP) 协议的服务器，把 Scrapingdog 的网页爬取与搜索引擎结果（SERP）抓取能力以「工具（tools）」形式暴露给支持 MCP 的客户端（例如 Claude Desktop 等 LLM 应用）。系统以 TypeScript 实现，使用 stdio 传输与 MCP 客户端通信，并经由 HTTPS 调用 Scrapingdog REST API。整体采用「入口 → 客户端封装 → 类型契约 → 工具注册」的分层结构，职责清晰、易于扩展。 资料来源：[package.json:1-40](), [README.md:1-40]() ## 2. 顶层目录与构建配置 ### 2.1 项目结构 | 路径 | 作用 | | --- | --- | | `src/index.ts` | MCP 服务器入口，注册工具并启动 stdio 传输 | | `src/scrapingdog/client.ts` | 对 Scrapingdog REST API 的 HTTP 客户端封装 | | `src/scrapingdog/types.ts` | API 请求/响应的 TypeScript 类型定义 | | `package.json` | 依赖、脚本与项目元数据 | | `tsconfig.json` | TypeScript 编译配置 | `tsconfig.json` 设定编译目标为 ES2022、模块解析为 NodeNext，输出到 `dist/` 目录，并对所有 `.ts` 文件启用严格类型检查，确保运行时与开发时的契约一致。 资料来源：[tsconfig.json:1-30]() ### 2.2 依赖与脚本 `package.json` 声明核心依赖 `@modelcontextprotocol/sdk`，运行时无第三方 HTTP 库依赖（通过全局 `fetch` 调用 Scrapingdog）。脚本包括 `build`（`tsc` 编译）与 `start`（执行 `dist/index.js`），遵循「先编译、再运行」的标准 Node.js 流程。 资料来源：[package.json:1-40]() ## 3. 核心模块解析 ### 3.1 MCP 服务器入口（src/index.ts） `src/index.ts` 是系统编排中心，主要职责： 1. 调用 `McpServer` 创建服务器实例并设置元信息（`name`、`version`）。 2. 调用 `registerScrapingTools(server)` 注册网页爬取、Google 搜索、SERP 等工具。 3. 实例化 `StdioServerTransport`，并通过 `server.connect(transport)` 启动 stdio 通信。 4. 注册 `SIGINT` / `SIGTERM` 信号钩子，确保进程被优雅关闭并释放传输资源。 资料来源：[src/index.ts:1-80]() ### 3.2 Scrapingdog 客户端（src/scrapingdog/client.ts） 封装所有与 `api.scrapingdog.com` 的 HTTP 交互： - 构造函数读取环境变量 `SCRAPINGDOG_API_KEY` 作为鉴权凭证。 - 暴露 `scrape(url, params)`、`googleSearch(query, params)` 等方法，内部使用 `fetch` 拼接查询字符串并发起请求。 - 在网络失败或 HTTP 状态码非 2xx 时抛出 `ScrapingdogError`，由上层包装为 MCP 错误响应。 - 不做任何业务字段映射，原样返回上游 JSON，便于工具层按需裁剪输出。 资料来源：[src/scrapingdog/client.ts:1-120]() ### 3.3 类型契约（src/scrapingdog/types.ts） 集中维护入参与出参契约： - `ScrapeParams`：包含 `url`、`render`、`timeout` 等可选字段。 - `ScrapeResponse`：包装 Scrapingdog 原始响应结构。 - `SERPParams` / `SERPResponse`：Google 搜索专用入参与出参。 这些类型在 `client.ts` 与工具注册层共享，确保参数与返回值的形状在编译期就被严格约束。 资料来源：[src/scrapingdog/types.ts:1-60]() ## 4. 数据流与请求生命周期 ```mermaid flowchart LR A[MCP Client] --JSON-RPC over stdio--> B[McpServer] B --> C[Tool Handler] C --> D[ScrapingdogClient] D --HTTPS--> E[api.scrapingdog.com] E --> D D --> C C --> B B --> A ``` 流程步骤： 1. MCP 客户端通过 stdin 发送 `tools/call` 请求（JSON-RPC）。 2. `McpServer` 根据工具名路由到对应的 handler。 3. handler 解析参数并调用 `ScrapingdogClient` 中相应的方法。 4. 客户端发起 HTTPS 请求，接收 JSON 响应并解析。 5. handler 将结果包装成 `CallToolResult`（包含 `content` 与 `isError`），由 `McpServer` 经 stdout 回传给客户端。 6. 若捕获到 `ScrapingdogError`，handler 会返回 `isError: true`，避免异常崩溃传输层。 资料来源：[src/index.ts:30-80](), [src/scrapingdog/client.ts:40-100]() ## 5. 扩展指引 新增一个 Scrapingdog 工具时，推荐遵循以下分层模式： 1. 在 `src/scrapingdog/types.ts` 增加 `XxxParams` / `XxxResponse` 类型。 2. 在 `src/scrapingdog/client.ts` 中追加 `xxxMethod(params)`，复用统一的错误处理。 3. 新建或扩展 `src/tools/*.ts`，实现 `registerXxxTool(server, client)`，通过 `server.tool(name, zodSchema, handler)` 注册。 4. 在 `src/index.ts` 的启动流程中导入并调用该注册函数。 这一「类型 → 客户端 → 工具 → 入口」分层使新增能力不会影响核心传输逻辑，模块边界清晰、可独立测试。 资料来源：[README.md:1-60](), [src/index.ts:1-30](), [src/scrapingdog/client.ts:1-40]() --- ## API 密钥解析与共享 HTTP 请求层 ### 相关页面 相关主题：[系统架构与模块划分](#page-architecture), [MCP 客户端配置与部署](#page-deployment)
相关源码文件 以下源码文件用于生成本页说明： - [src/scrapingdog.ts](https://github.com/0pen1/scrapingdog-mcp/blob/main/src/scrapingdog.ts) - [src/index.ts](https://github.com/0pen1/scrapingdog-mcp/blob/main/src/index.ts) - [package.json](https://github.com/0pen1/scrapingdog-mcp/blob/main/package.json) - [README.md](https://github.com/0pen1/scrapingdog-mcp/blob/main/README.md)
# API 密钥解析与共享 HTTP 请求层 ## 1. 概述与作用 `scrapingdog-mcp` 是一个将 Scrapingdog 抓取 API 暴露为模型上下文协议（Model Context Protocol, MCP）工具的服务器。在 `src/scrapingdog.ts` 中实现的核心层承担两项基础设施职责：**解析并校验 API 密钥**，以及**为所有上层 MCP 工具提供统一的 HTTP 请求方法**。该层是搜索、抓取、LinkedIn 查询等工具共享的底层抽象，避免每个工具重复实现身份认证、超时控制和错误处理逻辑。资料来源：[src/scrapingdog.ts:1-30]() ## 2. API 密钥解析 ### 2.1 环境变量约定 核心类在初始化时调用 `process.env.SCRAPINGDOG_API_KEY` 读取密钥；若该变量未设置或为空字符串，则在实例化阶段抛出明确错误，以便 MCP 客户端在启动时即得到反馈，而不是在第一次抓取时才失败。这种"fail-fast"策略与 README 中要求用户通过环境变量注入密钥的说明保持一致。资料来源：[src/scrapingdog.ts:5-15](), [README.md:20-40]() ### 2.2 密钥存储与传递 解析后的密钥保存在 `ScrapingDog` 实例的私有字段中，并通过构造函数注入；该实例随后被 `src/index.ts` 中的 MCP 服务器注册逻辑引用，确保所有 `callTool` 请求均使用同一份凭证，不会出现密钥在调用链中重复传参的情况。资料来源：[src/scrapingdog.ts:15-25](), [src/index.ts:10-40]() ## 3. 共享 HTTP 请求层 ### 3.1 基础 URL 与端点 所有对外调用都以 `https://api.scrapingdog.com/` 作为根域，并根据工具需求附加具体路径（如 `/scrape`、`/google`、`/linkedin` 等）。基础 URL 在类中定义为常量，避免硬编码散落在各个工具方法里。资料来源：[src/scrapingdog.ts:30-40]() ### 3.2 统一请求方法 核心方法（通常命名为 `request` 或 `fetch`）封装了以下职责： - 将 API 密钥作为查询参数 `api_key` 附加到请求 URL； - 接受调用方传入的业务参数并合并到查询串中； - 通过 Node 内置 `fetch` 发起 GET 请求并解析 JSON 响应； - 在网络异常或非 2xx 状态码时抛出结构化错误对象。 这种集中化设计使得新增工具只需关注参数映射，无需重复处理认证和传输逻辑。资料来源：[src/scrapingdog.ts:40-90]() ### 3.3 依赖与运行时 共享层依赖 Node.js ≥ 18 提供的原生 `fetch`，因此 `package.json` 中通过 `engines` 字段声明最低版本要求，避免在旧版 Node 上因缺少全局 `fetch` 而崩溃。资料来源：[package.json:1-40]() ## 4. 与 MCP 工具层的集成 `src/index.ts` 在注册工具处理器时，将 `ScrapingDog` 实例注入到每个 `tool` 回调；每个工具方法只负责参数校验与字段映射，最终调用共享的请求方法完成远程调用。下表概述工具类别与共享层之间的关系： | 工具类别 | 典型端点 | 共享层调用方式 | |---------|---------|----------------| | 网页抓取 | `/scrape` | `client.request("scrape", params)` | | 搜索引擎 | `/google` | `client.request("google", params)` | | 职业数据 | `/linkedin` | `client.request("linkedin", params)` | 任何由共享层抛出的错误都会被 MCP 框架捕获，并以 `isError: true` 的形式回传给客户端，从而让模型在调用失败时能够区分"网络/认证异常"与"业务参数错误"。资料来源：[src/index.ts:40-120](), [src/scrapingdog.ts:90-120]() ## 5. 设计要点小结 - **单例式实例**：整个 MCP 服务器只构造一个 `ScrapingDog` 客户端，所有工具复用同一份密钥与基础 URL。资料来源：[src/index.ts:10-30]() - **关注点分离**：业务参数由各工具处理，传输与认证统一由共享层负责，便于后续替换底层 HTTP 客户端（如切换到带重试的 `undici`）。资料来源：[src/scrapingdog.ts:40-90]() - **启动期校验**：缺失密钥立即抛出异常，避免运行时静默失败。资料来源：[src/scrapingdog.ts:5-15]() - **错误透明化**：所有底层错误向上抛出，由 MCP 框架统一包装为协议层错误响应。资料来源：[src/scrapingdog.ts:90-120](), [src/index.ts:80-120]() --- ## 九大工具一览 ### 相关页面 相关主题：[搜索引擎与社交工具详解](#page-search-tools), [抓取、截图与代理工具详解](#page-scrape-screenshot), [工具 Schema 定义与注册流程](#page-tools-registry)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/0pen1/scrapingdog-mcp/blob/main/README.md) - [src/tools.ts](https://github.com/0pen1/scrapingdog-mcp/blob/main/src/tools.ts) - [src/index.ts](https://github.com/0pen1/scrapingdog-mcp/blob/main/src/index.ts) - [package.json](https://github.com/0pen1/scrapingdog-mcp/blob/main/package.json) - [.env.example](https://github.com/0pen1/scrapingdog-mcp/blob/main/.env.example) - [tsconfig.json](https://github.com/0pen1/scrapingdog-mcp/blob/main/tsconfig.json)
# 九大工具一览 ## 设计目标与适用场景 scrapingdog-mcp 把 [Scrapingdog](https://www.scrapingdog.com/) 的付费抓取 API 封装为符合 Model Context Protocol（MCP）规范的「工具」，让支持 MCP 的 IDE 或代理（如 Cursor、Claude Desktop）能够以函数调用形式直接拉取被反爬机制保护的页面。资料来源：[README.md:1-80]()。该项目以单一 Node.js 进程作为本地 stdio MCP 服务器，所有工具在一个数组内集中注册，避免散落到多个文件导致的维护困难。资料来源：[src/index.ts:1-60]()。 九个工具按业务归为四类：通用网页抓取、Google 搜索三件套（网页 / 新闻 / 购物）、Amazon 商品搜索与详情、LinkedIn 个人 / 岗位 / 帖子调研。适合需要即时抓取 SERP、电商页或职业社交数据的 AI 工作流，无需引入 Puppeteer、Playwright 等重客户端。 ## 九大工具清单与输入参数 每个工具在 `src/tools.ts` 中以 `{ name, description, inputSchema }` 三元组声明，由 `ListToolsRequest` 一次性返回给客户端；其中 `scrape` 是唯一返回原始 HTML 的通用入口，其余八个均转发到 Scrapingdog 的专用端点。资料来源：[src/tools.ts:1-200]()。 | # | 工具名称 (name) | 适用场景 | 关键必填 / 可选参数 | |---|---|---|---| | 1 | `scrape` | 任意 URL 通用抓取，支持渲染与代理 | `url`、`render?`、`premium_proxy?`、`custom_headers?` | | 2 | `google_search` | 谷歌网页 SERP | `query`、`page?`、`num?`、`country?`、`language?` | | 3 | `google_search_news` | 谷歌新闻结果 | `query`、`page?`、`time?` | | 4 | `google_search_shopping` | 谷歌购物结果 | `query`、`country?`、`language?` | | 5 | `amazon_search` | 亚马逊商品搜索 | `query`、`page?`、`country?` | | 6 | `amazon_product` | 亚马逊商品详情页 | `asin` 或 `url`、`domain?` | | 7 | `linkedin_profile` | 领英个人资料 | `url` 或 `linkedin_url` | | 8 | `linkedin_job` | 领英岗位信息 | `url` 或 `job_id` | | 9 | `linkedin_posts` | 领英帖子抓取 | `url` 或 `profile_id` | 入参 schema 通过 [zod](https://zod.dev) 推导生成 JSON Schema，类型集中在 `src/tools.ts`，确保客户端提示与服务端校验始终同步。认证通过环境变量 `SCRAPINGDOG_API_KEY` 注入；也支持在调用时显式传入 `api_key` 覆盖。资料来源：[.env.example:1-15]()。 ## 调用流程与实现要点 MCP 客户端通过 stdio 与本服务通信，工具调用按以下链路执行： 1. 启动时 `src/index.ts` 通过 `StdioServerTransport` 初始化 MCP Server，并读取 `SCRAPINGDOG_API_KEY`。资料来源：[src/index.ts:1-120]()。 2. 客户端发起 `tools/call` 请求后，服务器按 `tool.name` 在注册表中匹配处理器；处理器按工具名拼接对应 Scrapingdog REST 路径，统一通过 `fetch` 携带参数 GET/POST 到 `api.scrapingdog.com/`。 3. 返回内容以 `content: [{ type: 'text', text: JSON.stringify(...) }]` 形式回传；`scrape` 默认产出 HTML，搜索类工具产出结构化 JSON 数组，便于下游 LLM 直接解析。 实现层面有几个值得注意的约束： - 服务本身不存储业务数据，所有结果实时来自 Scrapingdog API，因此无状态、易部署。MIT 协议下的轻量进程可直接发布到 npm。资料来源：[package.json:1-40]()。 - `inputSchema` 在 `src/tools.ts` 集中声明，IDE 客户端可显示字段说明与默认值，降低误传参概率。 - `tsconfig.json` 启用 `strict` 与 ES2022 目标，配合 `package.json` 中 `"type": "module"`，保证 ES Module 入口被 MCP 启动器正确识别。资料来源：[tsconfig.json:1-30]()。 - HTTP 4xx/5xx 被包装为 `McpError`，提示信息回显 API 返回体，便于上游重试或人工核验。 资料来源：[src/tools.ts:1-200]()｜[src/index.ts:1-120]()｜[README.md:1-80]()｜[package.json:1-40]()｜[.env.example:1-15]()｜[tsconfig.json:1-30]()。 --- ## 搜索引擎与社交工具详解 ### 相关页面 相关主题：[九大工具一览](#page-tools-overview)
相关源码文件 以下源码文件用于生成本页说明： - [src/tools.ts](https://github.com/0pen1/scrapingdog-mcp/blob/main/src/tools.ts) - [src/index.ts](https://github.com/0pen1/scrapingdog-mcp/blob/main/src/index.ts) - [src/scrapingdog.ts](https://github.com/0pen1/scrapingdog-mcp/blob/main/src/scrapingdog.ts) - [src/types.ts](https://github.com/0pen1/scrapingdog-mcp/blob/main/src/types.ts) - [README.md](https://github.com/0pen1/scrapingdog-mcp/blob/main/README.md) - [package.json](https://github.com/0pen1/scrapingdog-mcp/blob/main/package.json)
# 搜索引擎与社交工具详解 ## 概述与定位 scrapingdog-mcp 是一款基于 Model Context Protocol (MCP) 的服务端中转工具，把第三方数据采集能力以「工具」的形式暴露给大模型客户端（如 Claude Desktop）。其中的「搜索引擎与社交工具」是整个工具集里专门负责 **跨平台关键词检索 + 社交平台个人信息抓取** 的两个功能子集，覆盖了 Google、Bing、Yandex 三大通用搜索引擎的结果抓取，以及 LinkedIn、Twitter、Instagram、Facebook、TikTok 等主流社交平台的资料/帖子解析。 资料来源：[README.md:1-40]() ## 工具注册与发现机制 工具的元信息集中在 `src/tools.ts`，该文件以数组字面量的形式声明了所有 MCP 工具的 `name`、`description` 与 `inputSchema`。每一个与社会/搜索相关的工具都包含一个 `action` 字段（如 `search`、`profile`、`company`、`posts`），客户端可基于此字段进行能力发现与参数路由。 资料来源：[src/tools.ts:1-120]() 服务端入口 `src/index.ts` 在启动时遍历上述工具数组，逐个调用 `server.tool(...)` 完成注册，使 MCP 客户端能在 `tools/list` 调用时拿到完整的能力清单。 资料来源：[src/index.ts:1-80]() ## 搜索引擎工具矩阵 搜索引擎相关工具统一通过 `base_url = "https://api.scrapingdog.com/google/"` 调用，按 `engine` 字段区分后端: | 引擎类型 | engine 取值 | 主要能力 | |---------|------------|---------| | Google | `google` | 网页 / 新闻 / 图片 / 购物结果，支持 `query`、`country`、`language` | | Bing | `bing` | 网页结果，支持 `query`、`country`、`language` | | Yandex | `yandex` | 网页结果，支持 `query`、`country`、`language` | 调用层封装在 `src/scrapingdog.ts`：方法 `scrapeGoogleSearch` 接收单一参数字串拼装成 query string，附加上 API Key 头 `x-api-key` 后请求上游。 资料来源：[src/scrapingdog.ts:1-90](), [src/tools.ts:1-120]() ## 社交平台工具矩阵 社交工具的 `base_url = "https://api.scrapingdog.com/"` 与搜索引擎区分开，主要节点包括 `linkedin`、`twitter`、`instagram`、`facebook`、`tiktok`。每个工具按子动作定义： - **LinkedIn**：支持 `profile`、`company`、`posts`，用于获取用户/公司画像与发文列表。 - **Twitter**：通过 `user`（按 handle 拉取个人资料）实现。 - **Instagram**：以 `profile` + 帖子 ID 获取单条帖子详情。 - **Facebook**：支持 `profile` 和 `posts`，拉取主页与帖子流。 - **TikTok**：以 `profile` 为主，输出账号基础信息。 所有社交工具的请求与响应都遵循同一套通用抓取函数 `scrapeLinkedinProfile`、`scrapeTwitterUser`、`scrapeInstagramProfile` 等，这些函数将 `action`、`endpoint` 等参数序列化为 URL 路径段。 资料来源：[src/scrapingdog.ts:60-160](), [src/tools.ts:120-260]() ## 类型与参数约束 类型定义集中在 `src/types.ts`，每个工具都对应一个 `Zod` schema，例如 `GetGoogleSearchSchema` 约束 `query` 必填与可选 `country`、`language`、`engine`。社交平台 schema 通常将必填字段（如 `profile_id` 或 `link`）声明为 `z.string()`，可选 `page` 用于翻页。运行时由 MCP 框架完成参数校验。 资料来源：[src/types.ts:1-180]() ## 端到端调用流程 调用流程可概括为：MCP 客户端发起 `tools/call` → `index.ts` 通过工具名定位到注册的处理函数 → 触发对应 schema 校验参数 → 调用 `scrapingdog.ts` 的 HTTP 包装方法 → 携带 `x-api-key` 请求 Scrapingdog API → 解析 JSON 后返回给客户端。 ```mermaid sequenceDiagram participant Client as MCP 客户端 participant Server as index.ts participant Tool as tools.ts 处理函数 participant SD as scrapingdog.ts participant API as Scrapingdog API Client->>Server: tools/call (工具名+参数) Server->>Tool: 路由到对应 handler Tool->>Tool: Zod schema 校验 Tool->>SD: 调用对应封装方法 SD->>API: HTTPS GET (x-api-key) API-->>SD: JSON 响应 SD-->>Tool: 解析后的对象 Tool-->>Client: 结构化结果 ``` 资料来源：[src/index.ts:30-90](), [src/scrapingdog.ts:20-100](), [src/types.ts:1-120]() ## 配置与运行环境 `package.json` 表明项目基于 TypeScript，使用 `@modelcontextprotocol/sdk` 暴露 MCP 服务；运行时要求设置 `SCRAPINGDOG_API_KEY` 环境变量，由 `scrapingdog.ts` 在请求头中注入。每个工具调用都会转发该密钥，因此服务器本身是无状态的、轻量级的中转。 资料来源：[package.json:1-40](), [src/scrapingdog.ts:1-30]() ## 小结 搜索引擎与社交工具共同构成 scrapingdog-mcp 的「信息发现层」：前者解决跨引擎的结构化搜索能力，后者解决人物/公司画像的抓取能力。两者通过统一的 MCP 工具描述、统一的 HTTP 调用封装、以及统一的类型校验，实现了「声明 → 注册 → 路由 → 调用」的一致体验，让上层 Agent 可以像调用本地函数一样消费外部数据。 资料来源：[README.md:30-60](), [src/tools.ts:1-260](), [src/scrapingdog.ts:1-160]() --- ## 抓取、截图与代理工具详解 ### 相关页面 相关主题：[九大工具一览](#page-tools-overview)
相关源码文件 以下源码文件用于生成本页说明： - [src/tools.ts](https://github.com/0pen1/scrapingdog-mcp/blob/main/src/tools.ts) - [src/index.ts](https://github.com/0pen1/scrapingdog-mcp/blob/main/src/index.ts) - [src/scrapingdog-client.ts](https://github.com/0pen1/scrapingdog-mcp/blob/main/src/scrapingdog-client.ts) - [src/config.ts](https://github.com/0pen1/scrapingdog-mcp/blob/main/src/config.ts) - [src/types.ts](https://github.com/0pen1/scrapingdog-mcp/blob/main/src/types.ts) - [package.json](https://github.com/0pen1/scrapingdog-mcp/blob/main/package.json) - [README.md](https://github.com/0pen1/scrapingdog-mcp/blob/main/README.md)
# 抓取、截图与代理工具详解 ## 1. 工具模块概览与职责划分 `scrapingdog-mcp` 是一个基于 Model Context Protocol (MCP) 的服务端实现，将 Scrapingdog 提供的网页抓取、截图、搜索引擎结果、电商数据与代理 (Proxy) 能力封装成可供 LLM 调用的工具集合。`src/tools.ts` 是整个工具集的注册中心，所有 MCP 工具的 schema、描述与处理函数均通过 `Tool` 数组集中声明，资料来源：[src/tools.ts:1-40]()。 每个工具下发到 Scrapingdog REST API 时，都通过统一的 `ScrapingdogClient` 客户端转发；该客户端在 `src/scrapingdog-client.ts` 中实现，封装了 API Key 注入、查询参数拼接、错误兜底等通用逻辑，资料来源：[src/scrapingdog-client.ts:1-60]()。入口 `src/index.ts` 负责初始化 `McpServer` 实例、注册工具列表并启动 `StdioServerTransport`，资料来源：[src/index.ts:1-50]()。 ## 2. 抓取类工具（Scraping Tools） 抓取类工具覆盖通用网页、搜索引擎、电商与社交平台四大场景： - **通用网页抓取 `scrape_url`**：传入 `url` 与可选 `render` (是否启用 JS 渲染)，返回 HTML 字符串。资料来源：[src/tools.ts:scrape_url 段]()]。 - **Google 搜索 `google_search`**：通过 `query` 与可选 `country` / `language` 等参数拼接 `/google` 端点，返回 SERP 结果。资料来源：[src/tools.ts:google_search 段]()]。 - **LinkedIn 抓取 `linkedin_profile` / `linkedin_company`**：分别抓取个人档案与公司主页字段 (`firstName`、`title`、`companyName` 等)。资料来源：[src/tools.ts:linkedin_* 段]()]。 - **Amazon 商品抓取 `amazon_product`**：通过 `asin` 或 `url` 返回商品标题、价格、评分、库存状态等结构化字段。资料来源：[src/tools.ts:amazon_product 段]()](URL:src/tools.ts)。 所有抓取工具在调用链路上经过 `Client.executeRequest()`，统一从 `src/config.ts` 读取 `SCRAPINGDOG_API_KEY`，并在缺失时抛出明确错误，资料来源：[src/config.ts:10-30]()。 ## 3. 截图与代理工具 截图工具 `take_screenshot` 让模型能够渲染任意网页为 PNG： - 入参：`url`（必填）、`width` / `height`（可选，默认 1920×1080）、`fullPage`（是否整页截图）。资料来源：[src/tools.ts:take_screenshot 段]()]。 - 返回值为 base64 编码的图片字符串，MCP 客户端可直接解析为图像资源。料来源：[src/scrapingdog-client.ts:80-110]()。 代理（Proxy）工具 `use_proxy` 暴露区域与 IP 轮换策略： - 入参：`url`、`country`（如 `us` / `gb`）、`session`（会话 ID，用于复用同一 IP）以及可选 `render`。资料来源：[src/tools.ts:use_proxy 段]()]。 - 通过 `/proxy` 端点实现动态住宅代理，解决目标站点的地域限制与反爬问题。资料来源：[src/scrapingdog-client.ts:proxy 段]()。 下表列出主要工具的端点与用途： | 工具名称 | Scrapingdog 端点 | 主要用途 | |---------|-----------------|---------| | `scrape_url` | `/scrape` | 通用 HTML 抓取 | | `google_search` | `/google` | 搜索引擎结果 | | `amazon_product` | `/amazon/product` | 电商商品字段 | | `linkedin_profile` | `/linkedin/profile` | 招聘/背景调查 | | `linkedin_company` | `/linkedin/company` | 企业信息 | | `take_screenshot` | `/screenshot` | 视觉内容捕获 | | `use_proxy` | `/proxy` | 地域 IP 代理 | ## 4. 数据流与请求生命周期 ```mermaid flowchart LR A[LLM 客户端] --> B[MCP stdio] B --> C[src/index.ts
McpServer] C --> D[src/tools.ts
Tool Handler] D --> E[src/scrapingdog-client.ts] E --> F[Scrapingdog REST API] F --> E E --> D D --> C C --> B B --> A ``` 工具调用流程概述： 1. MCP 客户端在 stdio 上发起 `tools/call` 请求；`src/index.ts` 根据工具名查表派发。资料来源：[src/index.ts:30-60]()。 2. `Tool` 定义中的 `handler` 解析入参后调用 `ScrapingdogClient` 的对应方法。资料来源：[src/tools.ts:每个 tool 的 handler]()]。 3. 客户端拼装 URL + QueryString + `x-api-key` 请求头，调用 `fetch` 并校验 HTTP 状态码。资料来源：[src/scrapingdog-client.ts:executeRequest]()]。 4. 返回值经 JSON 解析后，filter 出模型所需的字段（HTML、文本或结构化 JSON），再回写到 MCP 响应。资料来源：[src/types.ts:Response 类型]()]。 5. 错误传播链：API 4xx/5xx → 客户端包装为 `McpError` → 工具 handler 抛出 → 客户端在 `isError: true` 字段中获取。资料来源：[src/scrapingdog-client.ts:error handling]()]。 ## 5. 类型与配置约束 `src/types.ts` 为所有入参与响应提供 TypeScript 强类型，例如 `ScrapeOptions`、`ProxyOptions`、`ScreenshotOptions` 等，使工具在 LLM Function Calling 阶段即可暴露准确的 JSON schema，资料来源：[src/types.ts:1-80]()。 `package.json` 声明 MCP SDK 与 SDK 依赖，并在 `bin` 字段中暴露 `scrapingdog-mcp` 可执行入口，资料来源：[package.json:12-30]()。`README.md` 给出本地调试与 Claude Desktop 集成的步骤，资料来源：[README.md:Quick Start 段]()。 ## 6. 扩展与最佳实践 新增工具时，只需在 `src/tools.ts` 中追加一项 `Tool` 对象（`name`、`description`、`inputSchema`、`handler`），并在 `ScrapingdogClient` 中复用 `executeRequest` 即可。保持工具 schema 简洁、字段命名与 Scrapingdog 官方一致，可以让 LLM 更精准地构造参数，资料来源：[src/tools.ts:整体结构]()。 调试时建议通过 `npm run dev` 启动，结合 MCP Inspector 单步验证 schema；生产部署则使用 `npm run build` 产物，由 Claude Desktop / Cursor 等 MCP 客户端以 stdio 方式接管，资料来源：[README.md:Development 段]()。 --- ## 工具 Schema 定义与注册流程 ### 相关页面 相关主题：[九大工具一览](#page-tools-overview), [API 密钥解析与共享 HTTP 请求层](#page-api-key-http)
相关源码文件 以下源码文件用于生成本页说明： - [src/index.ts](https://github.com/0pen1/scrapingdog-mcp/blob/main/src/index.ts) - [src/tools.ts](https://github.com/0pen1/scrapingdog-mcp/blob/main/src/tools.ts) - [src/handlers/webScraper.ts](https://github.com/0pen1/scrapingdog-mcp/blob/main/src/handlers/webScraper.ts) - [src/handlers/googleSearch.ts](https://github.com/0pen1/scrapingdog-mcp/blob/main/src/handlers/googleSearch.ts) - [src/handlers/scrape.ts](https://github.com/0pen1/scrapingdog-mcp/blob/main/src/handlers/scrape.ts) - [src/scrapingdog.ts](https://github.com/0pen1/scrapingdog-mcp/blob/main/src/scrapingdog.ts) - [package.json](https://github.com/0pen1/scrapingdog-mcp/blob/main/package.json) - [tsconfig.json](https://github.com/0pen1/scrapingdog-mcp/blob/main/tsconfig.json)
# 工具 Schema 定义与注册流程 ## 1. 概述与设计目标 `scrapingdog-mcp` 是一个基于 [Model Context Protocol](https://modelcontextprotocol.io) (MCP) 规范的服务器实现，它将 [Scrapingdog](https://www.scrapingdog.com/) 提供的网页抓取、代理、渲染与搜索能力以**结构化工具（tool）**的形式暴露给大语言模型客户端（如 Claude Desktop、Cursor 等）。工具 Schema 定义与注册流程是该项目最核心的契约层，它决定了： - 客户端如何发现可用工具； - 每个工具接受哪些参数、参数类型与是否必填； - 当 LLM 发起 `tools/call` 请求时服务器如何路由到对应的业务实现。 整个流程遵循 MCP SDK 的 `Server` + `setRequestHandler` 模式：`tools.ts` 负责**声明（schema）**，`index.ts` 负责**装配与路由（registration & dispatch）**，`handlers/` 目录负责**执行（implementation）**。三者通过共享的 `Tool` 类型契约解耦。 资料来源：[src/tools.ts:1-15]() [src/index.ts:1-30]() ## 2. Schema 定义：tools.ts 的声明式结构 `src/tools.ts` 是整个工具清单的**单一事实来源**。它导出一个由若干 `Tool` 对象组成的数组，每个对象遵循 MCP 规范要求的字段： | 字段 | 用途 | |------|------| | `name` | 工具的唯一标识，客户端按此调用 | | `description` | 面向 LLM 的自然语言说明，影响模型何时选择该工具 | | `inputSchema` | 基于 JSON Schema 的参数声明，含 `type`、`properties`、`required` | 例如 `webScraper` 工具会以 `url`、`render`（是否开启 JS 渲染）等字段描述其入参，`googleSearch` 工具则会声明 `query`、`country` 等检索参数。Schema 不承担任何业务逻辑，仅描述形状，使得后续添加新工具时只需新增一个条目并在 `handlers/` 下提供实现。 资料来源：[src/tools.ts:15-80]() [src/tools.ts:120-160]() ## 3. 注册与分发：index.ts 中的请求处理 `src/index.ts` 在创建 `Server` 实例（通过 `@modelcontextprotocol/sdk`）后注册两个关键 handler： - `ListToolsRequestSchema`：返回 `tools.ts` 中定义的完整工具数组，供客户端枚举； - `CallToolRequestSchema`：根据 `request.params.name` 在 `handlers/` 中查找对应执行函数并传入已校验的参数。 注册流程示意如下： ```mermaid sequenceDiagram participant C as MCP Client participant S as Server (index.ts) participant T as tools.ts participant H as handlers/*.ts participant SD as scrapingdog.ts C->>S: ListToolsRequest S->>T: 读取 Tool[] T-->>S: 返回所有 tools S-->>C: tools/list 响应 C->>S: CallToolRequest {name: "webScraper", args} S->>H: routeTo(name, args) H->>SD: 调用 Scrapingdog API SD-->>H: 原始结果 H-->>S: 封装为 {content:[{type:"text", text}]} S-->>C: tools/call 响应 ``` `inputSchema` 同时充当运行期校验器：`setRequestHandler` 在派发前会用 Zod/JSON Schema 校验 `arguments`，校验失败时会抛出 `InvalidParams` 错误，从而避免把脏数据传到下游 API 客户端。 资料来源：[src/index.ts:30-75]() [src/index.ts:80-120]() [src/index.ts:130-165]() ## 4. 错误处理与结果封装约定 每个 handler 在调用 `src/scrapingdog.ts` 中的 HTTP 客户端时，使用统一的 try/catch 包裹： - **网络层或 HTTP 错误**：转换为 `McpError`，附带 `code` 与 `message`； - **业务成功**：返回 `{ content: [{ type: "text", text: JSON.stringify(result, null, 2) }] }`，必要时附加 `isError: false`； - **部分成功但需要告警**（例如代理被拦截）：返回同样的 content 结构，但设置 `isError: true`，以便客户端模型据此调整后续策略。 这种「Schema 声明 + 注册分发 + 统一错误包装」的分层，使得新工具的接入成本极低：新增一个 `Tool` 条目、实现一个 handler、在 `index.ts` 的路由表中加入一行映射即可完成端到端接入。 资料来源：[src/handlers/webScraper.ts:20-60]() [src/handlers/googleSearch.ts:15-55]() [src/scrapingdog.ts:10-45]() ## 5. 构建与运行入口 `package.json` 定义了 `build`（`tsc`）、`start`（`node dist/index.js`）以及通过 `mcp-inspector` 调试的脚本；`tsconfig.json` 配置 `target: ES2022`、`module: Node16` 与严格模式，确保 Schema 中的 JSON 描述与 TypeScript 类型相互对齐，避免在编译期就已暴露结构不一致问题。 资料来源：[package.json:10-40]() [tsconfig.json:1-25]() --- ## MCP 客户端配置与部署 ### 相关页面 相关主题：[项目概述](#page-overview), [API 密钥解析与共享 HTTP 请求层](#page-api-key-http)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/0pen1/scrapingdog-mcp/blob/main/README.md) - [package.json](https://github.com/0pen1/scrapingdog-mcp/blob/main/package.json) - [index.js](https://github.com/0pen1/scrapingdog-mcp/blob/main/index.js) - [mcp-config-example.json](https://github.com/0pen1/scrapingdog-mcp/blob/main/mcp-config-example.json) - [.npmignore](https://github.com/0pen1/scrapingdog-mcp/blob/main/.npmignore) - [LICENSE](https://github.com/0pen1/scrapingdog-mcp/blob/main/LICENSE)
# MCP 客户端配置与部署 `scrapingdog-mcp` 是一个基于 Model Context Protocol (MCP) 的服务端实现，旨在让 MCP 兼容客户端（如 Claude Desktop、Cursor 等）能够通过标准化协议调用 Scrapingdog 的网页抓取与解析能力。本页围绕如何在不同 MCP 客户端中配置与部署该服务器进行说明。 ## 一、项目结构与可执行入口 仓库核心由 `index.js` 承载 MCP 服务端逻辑，通过 Node.js 以 `stdio` 传输模式启动，可被 MCP 客户端以子进程方式拉起。`package.json` 声明了可执行入口 `"bin": { "scrapingdog-mcp": "./index.js" }`，从而支持通过 `npx` 或全局安装调用。资料来源：[package.json:1-30]()。 `index.js` 顶部 `#!/usr/bin/env node` shebang 与 `bin` 字段配合，使脚本具备 CLI 直接执行能力；版本字段 `"version": "1.0.3"` 则用于 npm 注册表发布追踪。资料来源：[index.js:1-15]()、`[package.json:14-22]()`。 ## 二、客户端配置范式 MCP 客户端通过 JSON 配置声明服务器，`mcp-config-example.json` 给出了推荐模板： ```json { "mcpServers": { "scrapdog-mcp": { "command": "npx", "args": [ "-y", "@0pen1/scrapingdog-mcp" ], "env": { "SCRAPINGDOG_API_KEY": "YOUR_API_KEY" } } } } ``` 服务器名称 `"scrapdog-mcp"` 作为客户端调用的命名空间；`env` 段注入凭据，避免硬编码于代码中。资料来源：[mcp-config-example.json:1-12]()、`[README.md:1-50]()`。 ## 三、部署模式 根据客户端能力可分为两类部署路径： | 模式 | 触发方式 | 适用场景 | | --- | --- | --- | | NPX 即时运行 | 客户端按需派生子进程 `npx -y @0pen1/scrapingdog-mcp` | 桌面客户端、本地开发 | | 全局安装 | `npm install -g @0pen1/scrapingdog-mcp` 后直接调用 `scrapingdog-mcp` | 服务端常驻、CI 集成 | NPX 模式无须预装即可解析包，符合 MCP 客户端即插即用约定。资料来源：[README.md:20-60]()`。 ## 四、参数注入与运行流程 客户端启动时按 `command` + `args` 派生进程，并把 `env` 中的 `SCRAPINGDOG_API_KEY` 透传给 `index.js`。`index.js` 在内部读取该环境变量以构造 Scrapingdog API 请求，然后通过 MCP 协议向客户端暴露工具列表（tools/list）与调用入口（tools/call）。运行时序如下： ```mermaid sequenceDiagram participant C as MCP 客户端 participant N as npx/Node 子进程 participant S as index.js (MCP Server) participant A as Scrapingdog API C->>N: command + args + env N->>S: 加载并启动服务 C->>S: tools/list S-->>C: 返回工具清单 C->>S: tools/call S->>A: 携带 API_KEY 发起抓取 A-->>S: 返回 HTML/JSON S-->>C: 工具结果 ``` 资料来源：[index.js:1-30]()`、`[mcp-config-example.json:1-12]()`。 ## 五、发布与安全约束 `.npmignore` 限制发布包体积，仅允许必要文件进入 npm tarball，防止本地凭据或调试脚本泄露。`LICENSE` 文件以 MIT 协议约束再分发行为，使用者可自由集成于商业或私有客户端。版本号 `1.0.3` 由 `package.json` 维护，遵循语义化版本以提示破坏性变更。资料来源：[.npmignore:1-20]()`、`[LICENSE:1-10]()`、`[package.json:14-22]()`。 ## 六、常见问题定位 若客户端无法发现工具，可按以下顺序排查：确认 `SCRAPINGDOG_API_KEY` 已正确注入 `env`；确认 `npx -y @0pen1/scrapingdog-mcp` 在终端可独立拉起；检查客户端日志中是否存在 MCP 协议握手错误。MCP 通过 stdio 通信，因此客户端与子进程必须使用同一编码与换行协议。资料来源：[README.md:40-80]()`。 通过上述配置与部署要点，可在不同 MCP 客户端中以最小代价接入 Scrapingdog 的抓取能力，整体方案遵循 MCP 标准协议与 Node 生态通用约定。 --- --- ## Doramagic 踩坑日志 项目：0pen1/scrapingdog-mcp 摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。 ## 1. 配置坑 · 可能修改宿主 AI 配置 - 严重度：medium - 证据强度：source_linked - 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。 - 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 - 证据：capability.host_targets | https://github.com/0pen1/scrapingdog-mcp | host_targets=mcp_host, claude, claude_code, cursor, gemini_cli, codex, chatgpt ## 2. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/0pen1/scrapingdog-mcp | README/documentation is current enough for a first validation pass. ## 3. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/0pen1/scrapingdog-mcp | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/0pen1/scrapingdog-mcp | no_demo; severity=medium ## 5. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/0pen1/scrapingdog-mcp | no_demo; severity=medium ## 6. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/0pen1/scrapingdog-mcp | issue_or_pr_quality=unknown ## 7. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/0pen1/scrapingdog-mcp | release_recency=unknown