项目背景与定位

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 实现模式，整体组件职责如下：

构建产物经 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 协议的客户端中通过如下典型配置集成该服务：

{
  "mcpServers": {
    "scrapingdog": {
      "command": "npx",
      "args": ["-y", "scrapingdog-mcp"],
      "env": {
        "SCRAPINGDOG_API_KEY": "<your-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

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 项目结构

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. 数据流与请求生命周期

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

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 回调；每个工具方法只负责参数校验与字段映射，最终调用共享的请求方法完成远程调用。下表概述工具类别与共享层之间的关系：

任何由共享层抛出的错误都会被 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

设计目标与适用场景

scrapingdog-mcp 把 Scrapingdog 的付费抓取 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。

入参 schema 通过 zod 推导生成 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。

概述与定位

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 字段区分后端:

调用层封装在 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 后返回给客户端。

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

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 段。

下表列出主要工具的端点与用途：

4. 数据流与请求生命周期

flowchart LR
  A[LLM 客户端] --> B[MCP stdio]
  B --> C[src/index.ts<br/>McpServer]
  C --> D[src/tools.ts<br/>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 段。

1. 概述与设计目标

scrapingdog-mcp 是一个基于 Model Context Protocol (MCP) 规范的服务器实现，它将 Scrapingdog 提供的网页抓取、代理、渲染与搜索能力以结构化工具（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 规范要求的字段：

例如 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/ 中查找对应执行函数并传入已校验的参数。

注册流程示意如下：

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

一、项目结构与可执行入口

仓库核心由 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 给出了推荐模板：

{
  "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 模式无须预装即可解析包，符合 MCP 客户端即插即用约定。资料来源：README.md:20-60`。

四、参数注入与运行流程

客户端启动时按 command + args 派生进程，并把 env 中的 SCRAPINGDOG_API_KEY 透传给 index.js。index.js 在内部读取该环境变量以构造 Scrapingdog API 请求，然后通过 MCP 协议向客户端暴露工具列表（tools/list）与调用入口（tools/call）。运行时序如下：

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 生态通用约定。

Pitfall Log / 踩坑日志

项目：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