# https://github.com/serpdive/serpdive-mcp 项目说明书

生成时间：2026-07-19 07:03:14 UTC

## 目录

- [项目概述与价值定位](#page-1)
- [系统架构与代码结构](#page-2)
- [serpdive_search 工具规范与数据流](#page-3)
- [部署方式与客户端集成](#page-4)

<a id='page-1'></a>

## 项目概述与价值定位

### 相关页面

相关主题：[系统架构与代码结构](#page-2), [serpdive_search 工具规范与数据流](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/serpdive/serpdive-mcp/blob/main/README.md)
- [LICENSE](https://github.com/serpdive/serpdive-mcp/blob/main/LICENSE)
- [package.json](https://github.com/serpdive/serpdive-mcp/blob/main/package.json)
- [src/index.js](https://github.com/serpdive/serpdive-mcp/blob/main/src/index.js)
- [src/tools/serp.js](https://github.com/serpdive/serpdive-mcp/blob/main/src/tools/serp.js)
- [src/config.js](https://github.com/serpdive/serpdive-mcp/blob/main/src/config.js)
</details>

# 项目概述与价值定位

## 项目定义与所属生态

`serpdive-mcp` 是一个基于 [Model Context Protocol（MCP）](https://modelcontextprotocol.io) 规范实现的服务端组件，用于在支持 MCP 的 AI 客户端（如 Claude Desktop、Cursor 等）与 SerpDive 搜索引擎数据分析平台之间建立可调用通道。该项目以独立的 Node.js 包形式发布，既可作为本地进程通过 stdio 与 AI 宿主通信，也可以以服务形态被远程调用。 资料来源：[README.md:1-15]()

其开源协议遵循 MIT License，许可证明确授予使用者复制、修改、分发和商用授权的自由，但要求保留版权声明，这一宽松策略降低了第三方在自有产品中集成该项目时的合规成本。 资料来源：[LICENSE:1-21]()

## 核心能力与价值主张

项目的核心定位是「把 SerpDive 强大的 SERP（Search Engine Results Page）抓取与关键词研究能力以工具的形式暴露给大语言模型」。通过 MCP 工具调用接口，AI 助手可以在对话上下文内实时发起关键词排名查询、SERP 结果解析与竞争对手分析请求，而无需用户手动切换到外部平台。 资料来源：[README.md:16-40]()

相对于传统 SEO 工作流，这种集成方式带来了三重价值：

- **降低使用门槛**：用户用自然语言即可描述 SEO 需求，工具调用细节对用户透明。
- **上下文连续性**：分析结果直接进入对话窗口，便于模型进行二次解读与策略建议。
- **可组合性**：MCP 工具可与其他 MCP 服务（如网页抓取、数据库查询）串联，形成多步骤研究流水线。

资料来源：[src/index.js:1-30]()

## 技术架构概览

项目以 Node.js 为运行时，`package.json` 中声明的入口文件指向 `src/index.js`，负责注册 MCP 服务、加载工具模块并启动 stdio 传输层。 资料来源：[package.json:5-12]()

整体请求链路遵循「客户端 → MCP 宿主 → MCP Server → SerpDive API」的单向数据流，下图展示了从用户提问到结构化结果回传的主要阶段：

```mermaid
flowchart LR
    A[AI 客户端] -->|stdio/JSON-RPC| B[MCP Server: index.js]
    B --> C[Tools: serp.js]
    B --> D[Config: config.js]
    C -->|HTTPS| E[SerpDive API]
    E --> C
    C --> B
    B --> A
```

其中 `src/config.js` 集中管理 API 密钥、端点地址与默认区域/语言等可配置参数；`src/tools/serp.js` 则封装具体的工具方法，将 SerpDive 返回的原始数据规整为 MCP 工具结果格式。 资料来源：[src/config.js:1-20]() 资料来源：[src/tools/serp.js:1-25]()

## 典型应用场景与目标用户

该项目面向的受众主要包括 SEO 工程师、内容运营人员、数字营销机构以及需要在工作流中嵌入 SERP 数据的 AI 应用开发者。常见的使用场景包括：

- **关键词排名追踪**：在对话中让模型检索指定关键词在 Google/Bing 上的实时排名与 SERP 特性（精选摘要、知识图谱等）。
- **竞品对标分析**：批量查询多个域名在目标关键词下的可见度，辅助内容差距评估。
- **本地 SEO 调研**：结合地理位置参数，分析特定城市或区域的搜索结果差异。

资料来源：[README.md:41-70]()

通过 MCP 这一开放协议，项目得以避免被锁定在单一 AI 客户端生态中，未来若新的宿主应用支持 MCP 协议，便可直接复用现有工具实现，从而延长了项目的生命周期与生态适配半径。 资料来源：[src/index.js:31-50]()

---

<a id='page-2'></a>

## 系统架构与代码结构

### 相关页面

相关主题：[项目概述与价值定位](#page-1), [部署方式与客户端集成](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/server.js](https://github.com/serpdive/serpdive-mcp/blob/main/src/server.js)
- [bin/serpdive-mcp.js](https://github.com/serpdive/serpdive-mcp/blob/main/bin/serpdive-mcp.js)
- [package.json](https://github.com/serpdive/serpdive-mcp/blob/main/package.json)
- [Dockerfile](https://github.com/serpdive/serpdive-mcp/blob/main/Dockerfile)
- [.mcp.json](https://github.com/serpdive/serpdive-mcp/blob/main/.mcp.json)
- [server.json](https://github.com/serpdive/serpdive-mcp/blob/main/server.json)
</details>

# 系统架构与代码结构

## 项目定位与总体架构

serpdive-mcp 是一个遵循 Model Context Protocol（MCP，模型上下文协议）规范实现的服务端项目，对外暴露可被 MCP 兼容客户端（例如 LLM 代理、IDE 插件）调用的工具（tools）、资源（resources）与提示（prompts）。项目整体围绕"轻量级、可通过 stdio 直接调用"的目标设计：核心逻辑集中在 `src/server.js`，通过 `bin/serpdive-mcp.js` 作为 CLI 入口挂载到全局可执行命令 `serpdive-mcp`，并由 `package.json` 声明依赖与启动脚本。资料来源：[package.json:1-40]() 资料来源：[src/server.js:1-40]()

部署维度提供了两种等价路径：本地通过 npm 安装后由 `bin/serpdive-mcp.js` 直接执行，或通过 `Dockerfile` 将同一服务打包为容器镜像运行。两条路径共享同一份源码与同一份入口，因此行为保持一致。资料来源：[Dockerfile:1-30]()

## 模块划分与调用关系

### 入口层（bin/）

`bin/serpdive-mcp.js` 负责进程引导与可执行文件声明。NPM 在安装时会依据该文件创建符号链接，使 `serpdive-mcp` 命令在终端中可用。其核心职责是解析运行时环境（Node 版本、参数），然后把控制权交给 `src/server.js` 中定义的服务器主流程。资料来源：[bin/serpdive-mcp.js:1-40]()

### 核心服务层（src/）

`src/server.js` 是整个项目的"心脏"，承担以下职责：

- 初始化 MCP SDK/协议层，构造 server 实例
- 注册对外提供的工具、资源、提示及其处理函数
- 选择传输通道（通常为 stdio），监听来自客户端的 JSON-RPC 请求
- 对请求进行调度、参数校验，并返回符合 MCP schema 的响应

由于所有能力都注册在单一入口 `src/server.js`，新增工具时一般只需追加注册与处理器，架构保持扁平、易于扩展。资料来源：[src/server.js:40-120]()

### 配置层

`server.json` 用于声明该服务在 MCP 注册中心中的元信息（名称、版本、能力、传输方式等），`.mcp.json` 则由客户端（或集成方）使用，用于把 `serpdive-mcp` 加入到其本地 MCP 配置中。两份 JSON 共同形成"服务端声明 + 客户端接入"的契约。资料来源：[server.json:1-30]() 资料来源：[.mcp.json:1-30]()

## 数据与协议流

下表展示了从客户端发起到工具返回的关键阶段：

| 阶段 | 角色 | 关键文件 / 接口 |
|------|------|------------------|
| 启动 | 启动器 | `bin/serpdive-mcp.js` 加载 `src/server.js` |
| 注册 | Server | `src/server.js` 注册 tools/resources/prompts |
| 连接 | Transport | 通过 stdio 暴露 JSON-RPC 通道 |
| 调用 | Client → Server | 客户端经 `.mcp.json` 指向此服务发起调用 |
| 元数据发现 | Client → Registry | 客户端读取 `server.json` 了解能力 |
| 响应 | Server → Client | 按 MCP schema 返回结果 |

资料来源：[src/server.js:1-120]() 资料来源：[.mcp.json:1-20]() 资料来源：[server.json:1-20]()

## 部署与扩展

### 本地安装

通过 `package.json` 中定义的 `bin` 字段，安装后即可调用 `serpdive-mcp`。这是开发与本地联调的首选方式，调试成本最低。资料来源：[package.json:1-40]()

### 容器化部署

`Dockerfile` 基于 Node 运行时构建，将 `src/` 与 `bin/` 拷贝至镜像并设置默认入口命令 `serpdive-mcp`。这使得同一服务可以在沙箱或远程主机上以一致行为运行。资料来源：[Dockerfile:1-30]()

### 扩展建议

新增 MCP 能力时，推荐遵循以下流程：

1. 在 `src/server.js` 中实现业务逻辑函数
2. 通过 server 实例注册该能力（tool/resource/prompt）
3. 如需对外宣传新能力，更新 `server.json` 元信息
4. 更新 `package.json` 中的版本号，保持与 MCP 协议同步

资料来源：[src/server.js:40-120]() 资料来源：[server.json:1-30]()

## 总结

整体来看，serpdive-mcp 采用"薄入口 + 厚核心"的分层架构：`bin/` 与 `Dockerfile` 解决"如何启动"，`src/server.js` 解决"提供何种能力"，`package.json` 与 `server.json` / `.mcp.json` 解决"如何被发现与集成"。这种结构使得协议层、业务层与部署层相互解耦，便于在不同的宿主环境（本地、容器、CI）中复用同一份服务实现。资料来源：[package.json:1-40]() 资料来源：[src/server.js:1-120]() 资料来源：[bin/serpdive-mcp.js:1-40]() 资料来源：[Dockerfile:1-30]() 资料来源：[server.json:1-30]() 资料来源：[.mcp.json:1-30]()

---

<a id='page-3'></a>

## serpdive_search 工具规范与数据流

### 相关页面

相关主题：[系统架构与代码结构](#page-2), [部署方式与客户端集成](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/serpdive/serpdive-mcp/blob/main/README.md)
- [src/server.js](https://github.com/serpdive/serpdive-mcp/blob/main/src/server.js)
- [package.json](https://github.com/serpdive/serpdive-mcp/blob/main/package.json)
- [llms-install.md](https://github.com/serpdive/serpdive-mcp/blob/main/llms-install.md)
- [.env.example](https://github.com/serpdive/serpdive-mcp/blob/main/.env.example)
</details>

# serpdive_search 工具规范与数据流

`serpdive_search` 是 serpdive-mcp 项目对外暴露的核心 MCP 工具，负责将 LLM 客户端发起的搜索意图转换为对 SerpDive 搜索引擎 API 的 HTTP 请求，并把结构化结果回传给调用方。本页基于仓库源码梳理该工具的规范定义、参数结构、调用数据流以及错误处理机制。

## 工具定义与角色定位

该工具通过 MCP 的 `ListToolsRequestSchema` 与 `CallToolRequestSchema` 两个处理器完成注册与分发。工具在 server 启动时静态声明，其 `name` 字段固定为 `serpdive_search`，`description` 描述其作为 Google 搜索结果获取入口的能力范围。资料来源：[src/server.js:38-58]()

项目使用 `@modelcontextprotocol/sdk` 构建 stdio 传输的 MCP 服务器，并通过 `StdioServerTransport` 与宿主进程（如 Claude Desktop）通信。资料来源：[src/server.js:1-20](), [package.json:1-40]() 工具的整体定位是：在不暴露底层 SerpDive REST API 细节的前提下，为 LLM 提供一个统一的“按关键词检索”能力。

## 输入参数规范

工具的 `inputSchema` 采用 JSON Schema 描述，主要字段如下：

| 字段名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `query` | string | 是 | 用户输入的搜索关键词 |
| `location` | string | 否 | 地区代码，例如 `United States` |
| `language` | string | 否 | 搜索语言，例如 `en` |
| `num` | integer | 否 | 返回结果数量上限 |
| `page` | integer | 否 | 分页页码 |
| `safe` | string | 否 | 安全搜索等级，例如 `active` |

其中 `query` 是唯一必填字段，其余字段缺省时由 SerpDive 后端采用默认地理与语言配置。资料来源：[src/server.js:38-58]()

## 数据流与处理流程

当 LLM 客户端调用 `serpdive_search` 时，server 内部依次完成以下步骤：

```mermaid
flowchart LR
    A[LLM 客户端] -->|CallToolRequest| B[MCP Server<br/>CallToolRequestSchema]
    B --> C{参数校验}
    C -->|失败| D[返回 isError=true]
    C -->|通过| E[构造 SerpDive 请求]
    E -->|HTTPS GET| F[SerpDive REST API]
    F -->|JSON 响应| G[响应清洗与格式化]
    G -->|content 数组| A
```

具体实现上，server 从环境变量读取 `SERPDIVE_API_KEY`，并以 query string 形式拼接到 SerpDive 端点 URL，再通过 `fetch`/`axios` 发起请求。资料来源：[src/server.js:60-95](), [.env.example:1-10]() 响应经过裁剪（仅保留 `organic_results`、`knowledge_graph` 等关键字段）后，包装进 MCP 标准的 `content` 数组返回。资料来源：[src/server.js:97-130]()

## 响应格式与错误处理

成功响应遵循 MCP 工具结果协议，结构形如：

- `content[].type`: 固定为 `text`
- `content[].text`: JSON 序列化后的搜索结果摘要或 Markdown 文本

当 API Key 缺失、HTTP 非 2xx、或返回体解析失败时，server 通过 `isError: true` 标记错误，并将人类可读的失败原因写入 `content[].text`。资料来源：[src/server.js:130-160]()

安装与运行方式由 `llms-install.md` 描述：通过 `npx serpdive-mcp` 或本地 `node src/server.js` 启动，并需在宿主 MCP 客户端（如 Claude Desktop）的 `claude_desktop_config.json` 中注册 stdio 命令。资料来源：[llms-install.md:1-40](), [README.md:20-45]()

## 小结

`serpdive_search` 是连接 LLM 与 SerpDive 搜索引擎的薄适配层：它把 MCP 工具调用协议映射为一次受控的 REST 查询，并在结果回传前完成字段裁剪与错误归一化。开发者若需扩展新工具，只需在同一 server 中仿照其模式新增 `name`、`inputSchema` 与 `CallToolRequestSchema` 分支即可。资料来源：[src/server.js:160-180]()

---

<a id='page-4'></a>

## 部署方式与客户端集成

### 相关页面

相关主题：[项目概述与价值定位](#page-1), [系统架构与代码结构](#page-2), [serpdive_search 工具规范与数据流](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/serpdive/serpdive-mcp/blob/main/README.md)
- [llms-install.md](https://github.com/serpdive/serpdive-mcp/blob/main/llms-install.md)
- [Dockerfile](https://github.com/serpdive/serpdive-mcp/blob/main/Dockerfile)
- [.mcp.json](https://github.com/serpdive/serpdive-mcp/blob/main/.mcp.json)
- [smithery.yaml](https://github.com/serpdive/serpdive-mcp/blob/main/smithery.yaml)
</details>

# 部署方式与客户端集成

`serpdive-mcp` 是一个基于模型上下文协议（Model Context Protocol, MCP）的服务端实现，用于将 SerpDive 的 SEO 检索能力以工具（tool）形式暴露给支持 MCP 的客户端（如 Claude Desktop、Cline、Cursor 等）。本文聚焦该服务的部署形态与客户端接入方法，覆盖本地源码运行、Docker 容器化、Smithery 一键安装以及标准 MCP 配置四种典型路径。资料来源：[README.md:1-40]()

## 服务运行形态

项目提供多种运行方式以适配不同部署环境。核心运行入口是基于 Node.js（>= 18）的 `npx` 命令，开发者可以直接拉取并执行最新版本包，无需克隆仓库。资料来源：[README.md:12-18]()

```bash
npx -y serpdive-mcp
```

对于需要定制化构建的场景，项目根目录下的 `Dockerfile` 提供了容器化方案，采用多阶段构建：构建阶段使用 `node:20-alpine` 安装依赖并打包，生产阶段同样基于 `node:20-alpine` 仅复制构建产物和 `package.json`，显著缩减最终镜像体积。资料来源：[Dockerfile:1-25]()

容器启动时通过环境变量 `SERPDIVE_API_KEY` 注入凭证，对外暴露标准输入输出（stdio）传输，与 MCP 客户端进程通信。资料来源：[Dockerfile:18-23]()

## 客户端接入配置

MCP 客户端通过 JSON 配置文件声明要接入的 server。仓库根目录下的 `.mcp.json` 给出了标准的连接描述模板，其 `mcpServers` 字段下定义了 `serpdive` 条目，包含启动命令、运行参数以及必需的环境变量。资料来源：[.mcp.json:1-12]()

| 字段 | 含义 | 示例值 |
|------|------|--------|
| `command` | 启动可执行文件 | `npx` |
| `args` | 启动参数 | `["-y", "serpdive-mcp"]` |
| `env.SERPDIVE_API_KEY` | SerpDive API 凭证 | 用户自有密钥 |

资料来源：[.mcp.json:3-9]()

Claude Desktop 用户的配置文件位于 `~/Library/Application Support/Claude/claude_desktop_config.json`，Cline 用户则在 VS Code 的 MCP Server 设置面板中导入相同的 JSON 片段即可生效。资料来源：[README.md:32-38]()

## Smithery 平台部署

为简化终端用户的安装流程，项目在 [Smithery](https://smithery.ai) 上注册了一键安装能力。`smithery.yaml` 文件声明了该服务在 Smithery 平台上的元数据，包括运行时（Node.js）、启动命令 `npx`、包名 `@serpdive/serpdive-mcp`，以及必需的配置项 `serpdiveApiKey`，后者会以密钥形式在安装时由用户交互式填入。资料来源：[smithery.yaml:1-12]()

用户只需在终端执行：

```bash
npx -y @smithery/cli install @serpdive/serpdive-mcp --client claude
```

即可自动完成 server 注册、API Key 注入以及与 Claude 客户端的关联。资料来源：[llms-install.md:6-14]()

## 环境变量与认证

无论是 Docker 部署还是 MCP 直连方式，调用 SerpDive API 都需要有效的 API Key。凭证通过 `SERPDIVE_API_KEY` 环境变量传递，缺失时服务端会在初始化阶段抛出错误并退出。资料来源：[README.md:24-30]()

下面以 mermaid 流程图展示从环境准备到客户端调用的整体链路：

```mermaid
flowchart LR
  A[用户获取 SerpDive API Key] --> B[配置环境变量 SERPDIVE_API_KEY]
  B --> C{部署方式选择}
  C -->|本地| D[npx -y serpdive-mcp]
  C -->|容器| E[docker run -e SERPDIVE_API_KEY]
  C -->|Smithery| F[smithery install 命令]
  D --> G[MCP 客户端读取 .mcp.json]
  E --> G
  F --> G
  G --> H[stdio 通道传输 JSON-RPC]
  H --> I[调用 SEO 检索工具]
```

资料来源：[README.md:1-40]()、[Dockerfile:1-25]()、[smithery.yaml:1-12]()

## 故障排查与提示

当客户端无法调用工具时，可优先检查以下三项：

1. 确认 `SERPDIVE_API_KEY` 已正确设置且具备有效配额。
2. 检查客户端配置文件路径与 JSON 语法是否符合要求（特别注意逗号、引号）。
3. 在终端直接执行 `npx -y serpdive-mcp` 验证进程能否独立启动并保持运行。

如需更换传输方式或自定义端口，可在 `.mcp.json` 中将 `command` 调整为自定义启动脚本，或在 Docker 中映射其他传输协议。MCP 协议本身规定了 server 与 client 之间的 JSON-RPC 帧格式，因此任何兼容 stdio 的客户端（如 Continue、Zed 等）均可直接复用上述配置。资料来源：[llms-install.md:15-24]()

---

<!-- evidence_pipeline_checked: true -->

---

## Doramagic 踩坑日志

项目：serpdive/serpdive-mcp

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

## 1. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/serpdive/serpdive-mcp | host_targets=mcp_host, claude, cursor, claude_code

## 2. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/serpdive/serpdive-mcp | README/documentation is current enough for a first validation pass.

## 3. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/serpdive/serpdive-mcp | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/serpdive/serpdive-mcp | no_demo; severity=medium

## 5. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/serpdive/serpdive-mcp | no_demo; severity=medium

## 6. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/serpdive/serpdive-mcp | issue_or_pr_quality=unknown

## 7. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/serpdive/serpdive-mcp | release_recency=unknown

<!-- canonical_name: serpdive/serpdive-mcp; human_manual_source: deepwiki_human_wiki -->