项目定义与所属生态

serpdive-mcp 是一个基于 Model Context Protocol（MCP） 规范实现的服务端组件，用于在支持 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」的单向数据流，下图展示了从用户提问到结构化结果回传的主要阶段：

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

项目定位与总体架构

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

数据与协议流

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

资料来源：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

工具定义与角色定位

该工具通过 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 是唯一必填字段，其余字段缺省时由 SerpDive 后端采用默认地理与语言配置。资料来源：src/server.js:38-58

数据流与处理流程

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

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

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

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

资料来源：.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 上注册了一键安装能力。smithery.yaml 文件声明了该服务在 Smithery 平台上的元数据，包括运行时（Node.js）、启动命令 npx、包名 @serpdive/serpdive-mcp，以及必需的配置项 serpdiveApiKey，后者会以密钥形式在安装时由用户交互式填入。资料来源：smithery.yaml:1-12

用户只需在终端执行：

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 流程图展示从环境准备到客户端调用的整体链路：

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

Pitfall Log / 踩坑日志

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