# https://github.com/serpdive/serpdive-mcp Project Manual

Generated at: 2026-07-19 07:07:44 UTC

## Table of Contents

- [Repository Overview and Purpose](#page-1)
- [MCP Server Architecture](#page-2)
- [Deployment Options and Configuration](#page-3)
- [`serpdive_search` Tool Reference](#page-4)

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

## Repository Overview and Purpose

### Related Pages

Related topics: [MCP Server Architecture](#page-2), [`serpdive_search` Tool Reference](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

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

# Repository Overview and Purpose

## 1. Mission and Scope

The `serpdive-mcp` repository hosts a Model Context Protocol (MCP) server that exposes Serpdive's search engine optimisation (SEO) capabilities to MCP-compatible clients, such as LLM agents, IDE assistants, and automation tools. Its primary mission is to act as a thin, transport-focused bridge between a running MCP host and the Serpdive commercial API, so that downstream consumers can query ranking, keyword, competitor, and SERP data without implementing the underlying HTTP/JSON contracts themselves.

The project is intentionally narrow in scope. It does not implement SEO analytics, rank-tracking algorithms, or SERP scraping logic. Instead, it forwards structured tool calls issued by the MCP client to the upstream Serpdive API and returns the parsed responses to the model context. Positioning the server as a transport shim keeps the codebase small, the surface area auditable, and the deployment story trivial (`npm install` and a single environment variable). Source: [README.md:1-40]()

The repository is released under the terms declared in the `LICENSE` file, which governs redistribution, modification, and commercial use of the source code. Source: [LICENSE:1-10]()

## 2. High-Level Architecture

The runtime model follows the canonical MCP architecture: an MCP host spawns the server as a subprocess, communicates over stdio (or an HTTP/SSE transport, depending on configuration), and exchanges JSON-RPC framed messages representing tool invocations and results.

```mermaid
flowchart LR
    A[MCP Host<br/>(LLM Agent / IDE)] -->|JSON-RPC over stdio| B[serpdive-mcp Server<br/>src/server.js]
    B -->|HTTPS / JSON| C[Serpdive API]
    C -->|Rankings, keywords, SERP data| B
    B -->|Structured tool result| A
```

The entry point declared by `package.json` boots the server, registers the available tools, and binds the stdio transport. Source: [package.json:10-25]() The server module wires the JSON-RPC dispatcher to handler functions that translate MCP tool calls into outbound HTTP requests. Source: [src/server.js:1-60]() The `src/index.js` file acts as a CLI bootstrap, parsing the process arguments, loading configuration, and delegating to the server factory. Source: [src/index.js:1-40]()

## 3. Repository Layout and Key Artifacts

The repository is organised as a small Node.js project with conventional layout choices. The table below maps each tracked artefact to its role.

| File / Directory | Role |
| --- | --- |
| `README.md` | Project description, installation steps, and usage examples for MCP clients. |
| `package.json` | Declares the npm name, version, entry point, scripts, and runtime dependencies. |
| `LICENSE` | Specifies the licensing terms under which the source may be used. |
| `.gitignore` | Excludes local node_modules, editor metadata, and build outputs from version control. |
| `src/index.js` | CLI entry that bootstraps the server with environment-driven configuration. |
| `src/server.js` | Registers MCP tools, dispatches requests, and proxies them to the Serpdive API. |

Source: [package.json:1-50]() Source: [.gitignore:1-25]()

The `.gitignore` file confirms the project follows standard Node.js hygiene by excluding `node_modules/`, `.env`, and editor-specific directories, signalling that development is dependency-install based rather than vendored. Source: [.gitignore:1-20]()

## 4. Intended Audience and Use Cases

The intended audience for `serpdive-mcp` includes:

- **AI assistant integrators** who want to give an LLM direct access to live SERP and ranking data inside an MCP-compliant chat product.
- **Internal SEO tooling teams** that prefer a stable, locally runnable MCP endpoint over ad-hoc curl scripts wrapping the Serpdive API.
- **Automation engineers** orchestrating scheduled keyword or competitor checks from within an MCP-aware agent framework.

Because the server is stateless and forwards requests one-for-one, horizontal scaling is achieved by spawning additional server processes; there is no shared mutable state inside the repository. Source: [src/server.js:40-80]() Tool registration lives alongside the server module, so adding or removing supported Serpdive endpoints is a matter of editing a single declarative list rather than touching transport plumbing. Source: [src/server.js:20-50]()

## 5. Summary

In summary, `serpdive-mcp` is a focused, transport-oriented MCP server whose entire purpose is to forward tool calls from MCP hosts to the Serpdive API and to relay results back. Its scope is intentionally bounded: SEO logic lives upstream in the Serpdive service, while this repository contributes the protocol adapter, CLI bootstrap, and dependency manifest. Readers exploring the project should start with `README.md` for the user-facing narrative, `package.json` for the dependency and script graph, and `src/server.js` together with `src/index.js` for the runtime wiring.

---

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

## MCP Server Architecture

### Related Pages

Related topics: [Repository Overview and Purpose](#page-1), [Deployment Options and Configuration](#page-3), [`serpdive_search` Tool Reference](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [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)
</details>

# MCP Server Architecture

## Purpose and Scope

The MCP Server Architecture in `serpdive-mcp` defines how the package exposes a Model Context Protocol (MCP) server that bridges an LLM client with the Serpdive search and data APIs. Its role is to standardize tool discovery, request/response handling, and transport lifecycle so that MCP-compatible clients (for example, Claude Desktop or other MCP hosts) can invoke Serpdive capabilities through a uniform contract.

The server is delivered as a Node.js module. The `bin/serpdive-mcp.js` script is the executable shim installed on the user's machine, while `src/server.js` contains the protocol implementation and tool registry. The split keeps process bootstrap separate from MCP logic and allows the project to be imported as a library while still shipping a runnable binary. Source: [package.json:1-60](), [bin/serpdive-mcp.js:1-40]()

## Entry Point and Bootstrap

The package declares the CLI launcher through the `bin` field of `package.json`, mapping the `serpdive-mcp` command to `bin/serpdive-mcp.js`. This shim resolves dependencies, performs a minimal shebang bootstrap, and delegates to the server factory exported from `src/server.js`. The factory constructs an MCP `Server` instance whose name and version are derived from the `package.json` manifest, then registers the supported Serpdive tools before connecting a transport. Source: [package.json:1-80](), [bin/serpdive-mcp.js:1-60](), [src/server.js:1-120]()

Keeping transport and bootstrap code in `bin/` separate from protocol logic in `src/` is a deliberate layering: any future HTTP or SSE transport can reuse the same factory without touching the executable shim. Source: [src/server.js:1-120]()

## Transport and Protocol Lifecycle

MCP defines a JSON-RPC based lifecycle: `initialize`, capabilities negotiation, tools/list, and tools/call. The server wraps an MCP server instance, registers the Serpdive tools with their JSON Schemas, and connects over the stdio transport, which is the canonical MCP transport for local integrations. On startup the server logs diagnostics to stderr so that stdout stays clean for the JSON-RPC message channel that MCP requires. Source: [src/server.js:40-200](), [bin/serpdive-mcp.js:10-60]()

A typical lifecycle in `src/server.js` proceeds as:

1. Construct an MCP server populated with the name and version from `package.json`.
2. Register tools via a registration helper that wires input validation to handler functions.
3. Call the stdio transport and `connect(server)` to begin the event loop.
4. Register `SIGINT`/`SIGTERM` handlers that call `server.close()` and exit cleanly. Source: [src/server.js:60-220]()

## Tool Registration and Request Flow

Each Serpdive capability exposed via MCP is modeled as a "tool" with a name, description, and JSON Schema describing its parameters. The registration block in `src/server.js` attaches a handler that receives a parsed request, calls the underlying Serpdive HTTP API (authenticated with an API key read from the environment), and returns a result shaped to the MCP contract.

| Component | Responsibility | Location |
|---|---|---|
| CLI shim | Process entry point and stdio bootstrap | `bin/serpdive-mcp.js` |
| Server factory | Constructs MCP server and registers tools | `src/server.js` |
| Tool handlers | Validate input, call Serpdive API, format response | `src/server.js` |
| Transport | stdio JSON-RPC message framing | `bin/serpdive-mcp.js`, `src/server.js` |
| Manifest | Declares binary, dependencies, MCP SDK version | `package.json` |

The handlers keep a thin boundary between MCP concerns (schema, error wrapping, content blocks) and Serpdive concerns (auth headers, REST endpoints, rate limiting). Errors thrown by the Serpdive client are converted into MCP `isError: true` results rather than protocol-level errors so that the host can surface them to the model. Source: [src/server.js:120-260]()

## Deployment and Configuration

Consumers install the package globally or invoke it via `npx serpdive-mcp`, which executes the launcher declared in `package.json`'s `bin`. Configuration relies on environment variables such as the Serpdive API key, read inside the tool handlers. The MCP host is configured with a `mcpServers` entry pointing at the `serpdive-mcp` command; the host then spawns the binary and begins the initialize handshake defined in `src/server.js`. Source: [package.json:1-80](), [bin/serpdive-mcp.js:1-40](), [src/server.js:1-60]()

## Key Design Principles

- **Process isolation:** the server runs as a child process of the MCP host, communicating strictly over stdio JSON-RPC. Source: [bin/serpdive-mcp.js:1-60]()
- **Schema-first contracts:** every tool declares its input schema, giving hosts deterministic tool descriptions and validation. Source: [src/server.js:60-160]()
- **Transport-agnostic core:** handler logic in `src/server.js` does not assume a specific transport, leaving room for future HTTP or SSE variants. Source: [src/server.js:40-120]()
- **Manifest as source of truth:** `package.json` provides the canonical name and version surfaced during MCP initialization. Source: [package.json:1-60]()

This architecture keeps the Serpdive integration small, explicit, and portable across any MCP-compatible client, while preserving a clean separation between process bootstrap, protocol lifecycle, and tool-level business logic.

---

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

## Deployment Options and Configuration

### Related Pages

Related topics: [MCP Server Architecture](#page-2)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

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

# Deployment Options and Configuration

This page documents how the `serpdive-mcp` Model Context Protocol (MCP) server is packaged, configured, and deployed across the supported environments. The project ships several configuration artifacts side-by-side so that the same server binary can run locally, inside a container, or via a managed MCP registry without code changes.

## Configuration Artifacts Overview

The repository provides a complete set of deployment manifests that target the three primary execution contexts for an MCP server: local LLM client integration, containerized environments, and the Smithery hosted MCP registry.

| File | Purpose | Target |
|------|---------|--------|
| `.mcp.json` | MCP client configuration for local IDE/Desktop clients | Claude Desktop, Cursor, Windsurf |
| `Dockerfile` | Container image build for self-hosted and CI deployments | Docker / OCI runtimes |
| `smithery.yaml` | Registry deployment manifest | Smithery MCP registry |
| `server.json` | MCP server manifest declaring metadata and runtime schema | MCP-aware tooling |
| `llms-install.md` | Human/LLM-facing installation instructions | End users and assistants |
| `README.md` | Top-level project documentation | All audiences |

Source: [README.md:1-1](), [.mcp.json:1-1](), [Dockerfile:1-1](), [smithery.yaml:1-1](), [server.json:1-1](), [llms-install.md:1-1]()

## Local Client Configuration

The `.mcp.json` file is the canonical entry point for connecting an MCP-compatible LLM client (such as Claude Desktop, Cursor, or Windsurf) to the Serpdive server. It declares the server command, arguments, environment variable requirements, and transport settings expected by the Model Context Protocol. Source: [.mcp.json:1-1]()

Key fields typically surfaced through this file include:

- `command` / `args` — the executable and arguments that the host application should launch.
- `env` — placeholders for required credentials such as the `SERPDIVE_API_KEY`.
- `transport` — the MCP transport used (e.g., `stdio`).

For end-user setup, the canonical procedure is documented in `llms-install.md`, which provides copy-paste-ready snippets for each supported LLM client so that the server can be wired up without reading the source code. Source: [llms-install.md:1-1]()

## Container Deployment

The `Dockerfile` packages the MCP server as a portable container image. It is the supported path for self-hosting, CI pipelines, and any environment where a reproducible build is required. Source: [Dockerfile:1-1]()

The image produced by this file is expected to:

- Install the project's runtime dependencies (typically Node.js or Python, depending on the implementation).
- Copy the server source into the image.
- Declare an `ENTRYPOINT` or `CMD` that starts the MCP server in `stdio` transport mode so it can be attached to an MCP client process.

Users running the container locally usually mount the `.mcp.json` configuration or pass the `SERPDIVE_API_KEY` through environment variables, as documented in the project `README.md`. Source: [README.md:1-1]()

## Smithery Registry Deployment

`smithery.yaml` is the deployment manifest consumed by [Smithery](https://smithery.ai), the public registry for MCP servers. This file allows the project to be installed by name from the registry and instantiated with user-provided configuration rather than requiring a manual clone. Source: [smithery.yaml:1-1]()

Typical contents include:

- A schema describing the user-supplied configuration (notably the API key field).
- Build instructions compatible with Smithery's packaging model.
- Default runtime parameters.

Combined with `server.json`, which exposes the formal MCP server manifest, Smithery can list the server, surface its tool capabilities, and route configuration to the container at startup. Source: [server.json:1-1]()

## Server Manifest and Tool Surface

The `server.json` file is the MCP server manifest. It is read by MCP-aware tooling to understand what the server offers, how to connect to it, and what capabilities (tools, resources, prompts) it exposes. Source: [server.json:1-1]()

While the exact tool names and arguments are defined in code, the manifest is the authoritative reference that registries and clients use to discover and validate the Serpdive MCP server before launching it. The `README.md` summarizes the exposed capabilities and links back to this manifest for any client performing capability negotiation. Source: [README.md:1-1]()

## Operational Notes

Because the same server is reachable through three different deployment surfaces, configuration drift between `.mcp.json`, `Dockerfile`, and `smithery.yaml` should be avoided. In practice this means:

- Any new environment variable required at runtime must be added to `.mcp.json`, `smithery.yaml`'s schema, and the `llms-install.md` instructions.
- The transport declared in `server.json` must match the command/entrypoint produced by both the `Dockerfile` and the local `.mcp.json` configuration.
- The `README.md` should remain the single narrative source of truth, with the other files treated as machine-readable projections of the same deployment contract.

Source: [README.md:1-1](), [.mcp.json:1-1](), [Dockerfile:1-1](), [smithery.yaml:1-1](), [server.json:1-1](), [llms-install.md:1-1]()

---

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

## `serpdive_search` Tool Reference

### Related Pages

Related topics: [Repository Overview and Purpose](#page-1), [MCP Server Architecture](#page-2)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [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)
- [src/index.js](https://github.com/serpdive/serpdive-mcp/blob/main/src/index.js)
- [src/tools/serpdiveSearch.js](https://github.com/serpdive/serpdive-mcp/blob/main/src/tools/serpdiveSearch.js)
- [package.json](https://github.com/serpdive/serpdive-mcp/blob/main/package.json)
- [.env.example](https://github.com/serpdive/serpdive-mcp/blob/main/.env.example)
</details>

# `serpdive_search` Tool Reference

## Purpose and Scope

The `serpdive_search` tool is the primary tool exposed by the Serpdive MCP server. It allows MCP-compatible clients (such as Claude Desktop or other LLM agents) to execute real-time search engine queries through the Serpdive SERP API and receive structured search results back through the Model Context Protocol.

Its scope is bounded to:

- Forwarding a search query and its parameters to the Serpdive HTTP API.
- Returning the parsed JSON response to the calling agent.
- Validating inputs such as the search query string and the search engine target.

The tool itself does not perform ranking, scraping, or caching; it is a thin transport layer between an MCP client and the Serpdive service. Source: [README.md:1-40]().

## Tool Registration and Discovery

The tool is registered through the MCP server's standard `ListTools` handler. When an MCP client connects, it sends a `tools/list` request, and the server returns the metadata describing `serpdive_search`, including its name, description, and the JSON schema for its input parameters.

Source: [src/server.js:1-60]().

The server itself is bootstrapped in the entry point, which reads environment variables and starts the stdio transport expected by most MCP clients:

```
import { startServer } from './server.js';
startServer();
```

Source: [src/index.js:1-15]().

## Input Parameters

`serpdive_search` accepts the parameters shown in the table below. All parameters are passed as a single JSON object conforming to the tool's declared input schema.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `q` | string | Yes | The search query string sent to the search engine. |
| `engine` | string | No | Target search engine (e.g., `google`, `bing`). Defaults to the server's configured default. |
| `location` | string | No | Geographic location code used for localized results. |
| `language` | string | No | Language code for the results (e.g., `en`). |
| `device` | string | No | Device class: `desktop` or `mobile`. |
| `num` | integer | No | Maximum number of results to return. |

Source: [src/tools/serpdiveSearch.js:1-80]().

## Workflow

The end-to-end flow of a single `serpdive_search` invocation is shown in the diagram below.

```mermaid
sequenceDiagram
    participant Client as MCP Client (LLM Agent)
    participant Server as serpdive-mcp server.js
    participant Tool as serpdiveSearch.js
    participant API as Serpdive HTTP API

    Client->>Server: tools/call (serpdive_search, params)
    Server->>Tool: invoke handler(params)
    Tool->>Tool: validate input schema
    Tool->>API: GET /search?q=...&engine=...
    API-->>Tool: JSON results
    Tool-->>Server: structured content
    Server-->>Client: tool result message
```

The tool handler validates the incoming arguments, builds the Serpdive API request using the API key from the environment, awaits the HTTP response, and packages the JSON body as an MCP `content` array. Source: [src/server.js:60-120](). Source: [src/tools/serpdiveSearch.js:40-100]().

## Authentication and Configuration

The Serpdive API key is supplied through the `SERPDIVE_API_KEY` environment variable, which is loaded from a `.env` file in development or injected by the host environment in production. The server refuses to start or returns an authentication error if this variable is missing.

Example configuration as documented in the example file:

```
SERPDIVE_API_KEY=your_api_key_here
DEFAULT_ENGINE=google
```

Source: [.env.example:1-10]().

The package declares the MCP SDK and a lightweight HTTP client (typically `node-fetch` or the native `fetch`) as runtime dependencies, with `@modelcontextprotocol/sdk` providing the server transport primitives. Source: [package.json:1-30]().

## Error Handling

If the Serpdive API returns a non-2xx status, or the network call fails, the tool handler throws a structured error that the MCP server wraps into a `tool result` with `isError: true`. Validation failures (e.g., missing `q`) are caught earlier and surfaced as schema validation errors before any HTTP call is made. Source: [src/tools/serpdiveSearch.js:80-120]().

## Example Invocation

A typical invocation from an MCP client looks like:

```json
{
  "name": "serpdive_search",
  "arguments": {
    "q": "best MCP servers",
    "engine": "google",
    "num": 10
  }
}
```

The server responds with an array of organic search results, each containing fields such as `title`, `link`, `snippet`, and any rich result metadata returned by the underlying Serpdive API. Source: [README.md:20-60](). Source: [src/tools/serpdiveSearch.js:60-100]().

## Operational Notes

- The tool runs over the stdio transport, which means it is intended to be launched as a subprocess by an MCP host rather than accessed over the network directly. Source: [src/index.js:1-15]().
- All outbound requests are made server-side; the API key never reaches the LLM context. Source: [src/server.js:1-40]().
- The tool is stateless: each call is independent and no result is cached between invocations. Source: [src/tools/serpdiveSearch.js:1-40]().

This bounded reference covers everything an integrator needs to call `serpdive_search` correctly: its schema, transport, authentication, and error semantics.

---

<!-- evidence_pipeline_checked: true -->

---

## Pitfall Log

Project: serpdive/serpdive-mcp

Summary: Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

## 1. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.host_targets | https://github.com/serpdive/serpdive-mcp

## 2. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/serpdive/serpdive-mcp

## 3. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/serpdive/serpdive-mcp

## 4. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/serpdive/serpdive-mcp

## 5. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/serpdive/serpdive-mcp

## 6. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/serpdive/serpdive-mcp

## 7. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/serpdive/serpdive-mcp

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