Related Pages

Related topics: MCP Server Architecture, serpdive_search Tool Reference

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.

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.

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.

Related Pages

Related topics: Repository Overview and Purpose, Deployment Options and Configuration, serpdive_search Tool Reference

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.

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.

Related Pages

Related topics: MCP Server Architecture

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.

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, 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

Related Pages

Related topics: Repository Overview and Purpose, MCP Server Architecture

`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.

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.

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:

{
  "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.

Doramagic Pitfall Log

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
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/serpdive/serpdive-mcp

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/serpdive/serpdive-mcp

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/serpdive/serpdive-mcp

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/serpdive/serpdive-mcp

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/serpdive/serpdive-mcp

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/serpdive/serpdive-mcp

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/serpdive/serpdive-mcp

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using serpdive-mcp with real data or production workflows.

• Configuration risk requires verification - GitHub / issue