cn-websearch-mcp

Language: English | 简体中文

One MCP tool, several built-in web-search channels. A Model Context Protocol server that fronts a set of upstream web-search APIs behind a single web_search tool. Channels ship in different wire formats — some are chat-completions-style APIs with a server-side tool-call or fiber loop, others are standalone search REST endpoints — and this server normalizes all of them into one schema and gives you two strategies:

• fallback (default) — try channels in your priority order, return the first success. Few calls, low latency.

• aggregate — query several channels in parallel, merge results, dedupe by URL, and tag each item with its source. Wider coverage.

fallback:   kimi ──✓ 1.2s → return          aggregate:  kimi  ─┐
            stepfun (only if kimi failed)               stepfun ─┼─→ merge + dedupe → return
            zhipu   (only if the above failed)          zhipu   ─┘

The channel identifiers shown above (kimi, stepfun, zhipu, mimo) are the literal config keys — see Configuration for the full set.

Install

Requires Node >= 18. From a checkout:

npm install
npm run build     # tsc → dist/

Provide at least one channel API key — via environment variables, a .env file, or a JSON config file (see Configuration). Channels without a key are skipped automatically.

Related MCP server: mcp-toolkit

Use it as an MCP server

Point your MCP client at the built entry point. Keys go in the client's env block — the server reads .env relative to its working directory, which is not necessarily your project.

{
  "mcpServers": {
    "cn-websearch": {
      "command": "node",
      "args": ["/absolute/path/to/cn-websearch-mcp/dist/index.js"],
      "env": {
        "STEPFUN_API_KEY": "sk-...",
        "WEBSEARCH_STRATEGY": "aggregate"
      }
    }
  }
}

Claude Code:

claude mcp add cn-websearch -e STEPFUN_API_KEY=sk-... -- node /absolute/path/to/cn-websearch-mcp/dist/index.js

Running the binary with no arguments starts the stdio MCP server, so existing MCP client configurations keep working.

Use it in a terminal

The same binary is a CLI, so you can search and test without wiring up a client.

cn-websearch-mcp                       # start the MCP stdio server (default)
cn-websearch-mcp search "query text"   # one-shot search
cn-websearch-mcp search --strategy aggregate --count 12 "query text"
cn-websearch-mcp status                # effective settings + channel status
cn-websearch-mcp test                  # probe every ready channel once
cn-websearch-mcp repl                  # interactive session
cn-websearch-mcp help                  # full usage

Options: -n/--count <1-50>, --strategy fallback|aggregate, --providers a,b (restrict this call), --no-dedupe, -q/--query (query for test), --json (raw output for scripting), -h, -v.

Exit codes: 0 success, 1 runtime failure (search failed / nothing configured), 2 usage error — so scripts and CI can branch on them.

In the interactive session, bare text is a search and / commands control the session:

cn-websearch> a recent news query
cn-websearch> /strategy aggregate      # switch this session to multi-source
cn-websearch> /aggregate rust async    # one-off multi-source search
cn-websearch> /count 12
cn-websearch> /providers stepfun,zhipu # restrict this session
cn-websearch> /test stepfun            # probe one channel
cn-websearch> /status  /config  /json on  /help  /quit

Configuration

Configuration is merged in this order — later layers win:

built-in defaults → JSON config file → environment variables

Environment variables win because MCP clients can generally only pass env.

Config file

Put cn-websearch.config.json in the working directory; it is picked up automatically. Or point at it explicitly with WEBSEARCH_CONFIG=/path/to/file.json.

See cn-websearch.config.example.json for every supported key. A minimal example:

{
  "strategy": "aggregate",
  "providers": {
    "stepfun": { "apiKey": "sk-...", "priority": 10 },
    "zhipu":   { "priority": 5, "options": { "searchEngine": "search_pro" } },
    "kimi":    { "enabled": false }
  }
}

If you put API keys in this file, do not commit it — cn-websearch.config.json is git-ignored by default for that reason (use git add -f if you keep a keyless, shareable config there).

Choosing channel priority

Three equivalent ways, evaluated in this order:

1. order (config file) or WEBSEARCH_ORDER (env) — an explicit list, highest priority first: ["stepfun", "zhipu"].

2. priority per channel — a number, higher goes earlier. Ties are broken alphabetically so the result is deterministic.

3. Neither set → alphabetical default (kimi, mimo, stepfun, zhipu).

Set in the config file:

{ "providers": { "stepfun": { "priority": 10 }, "zhipu": { "priority": 5 } } }

or by environment:

WEBSEARCH_ORDER=stepfun,zhipu,kimi
STEPFUN_PRIORITY=10

On the command line, --providers narrows a single call without changing the configured priority.

Settings

Booleans accept true/false, 1/0, yes/no, on/off. Invalid values are ignored with a warning rather than failing.

A blank value at any layer (KIMI_API_KEY=, "baseUrl": "") counts as "not set", so the empty placeholders in a template file never mask a value configured in the layer below — the config file, or the built-in default. A timeoutMs beyond 600000 ms is rejected with a warning and falls back, because such a delay no longer fits a 32-bit timer and would silently become 1 ms.

Per-channel settings

Every channel supports the same generic knobs, in the config file or as <NAME>_<SUFFIX> environment variables:

apiKey (_API_KEY), baseUrl (_BASE_URL), model (_MODEL), enabled (_ENABLED), priority (_PRIORITY), timeoutMs (_TIMEOUT_MS, overrides the global budget for that channel), and options for channel-specific parameters.

The four built-in channel slots and the options keys each one recognises:

The kimi slot's multi-round loop caps at maxRounds tool-call rounds; only when the last round still returns tool calls does it force one final chat call (without tools) for the answer. maxTokens is the token budget per chat call. The mimo slot sends a server-side web_search tool with maxKeyword and forceSearch knobs and an approximate user_location assembled from the configured location keys (country is always sent and defaults to China; region and city only when explicitly configured). The stepfun and zhipu slots are direct REST calls — their options map one-to-one onto the request fields those APIs accept.

Keys are never logged or echoed: error text is scrubbed of credential-looking strings, and status output only reports whether a key is set. A slot that has a key and a baseUrl which is not an https URL is reported with a warning at startup, because that key would otherwise travel in cleartext.

Tools

web_search

Input: { "query": string, "count"?: integer, "strategy"?: "fallback"|"aggregate", "providers"?: string[] }.

count defaults to your configured count, strategy to your configured strategy, and providers (when given) must name slots that are enabled and have a key — otherwise the call returns a structured error naming the problem rather than silently ignoring it. count is clamped to 1-50 and query is capped at 400 characters, on this surface and on every CLI command alike.

Output: normalized results plus an audit trail. In aggregate mode each item carries source, and _meta.providers lists everyone who answered:

{
  "results": [
    {
      "title": "…",
      "url": "https://…",
      "snippet": "…",
      "content": "optional full text when the channel returns it",
      "published_date": "2026-09-06",
      "source": "stepfun"
    }
  ],
  "_meta": {
    "provider": "stepfun",
    "providers": ["stepfun", "zhipu"],
    "total_latency_ms": 2586,
    "attempts": [
      { "provider": "stepfun", "status": "ok", "latency_ms": 2025 },
      { "provider": "zhipu",   "status": "transient_error", "latency_ms": 611, "error": "HttpError: HTTP 429: …" }
    ]
  }
}

provider_status

Read-only: effective strategy and settings, and per slot whether it is enabled, has a key, and is in the active chain.

Fallback & failure semantics

• Only channels that are enabled and have a key participate. fallback walks them in priority order; aggregate queries them in parallel.

• Per attempt: one wall-clock budget (timeoutMs); hung requests are aborted and recorded as timeout.

• Transient failures (network errors, HTTP 5xx, 429) are retried once after a short backoff (250 ms, 1 s for a 429), then the next channel is tried. A budget timeout is not retried — its wall-clock budget is already spent, so the chain moves on to the next channel instead.

• Permanent failures (HTTP 4xx other than 429) skip the retry and move on immediately.

• If the MCP client cancels the request, the search stops immediately: the in-flight attempt is aborted, its audit record is cancelled, and the call ends there instead of walking the rest of the chain.

• In aggregate, partial failure is not failure: successful channels' results are returned and the failures stay in _meta.attempts.

• Every attempt is recorded in _meta.attempts — success, retry, timeout, cancellation or error.

• If everyone fails, web_search returns a structured error containing the full attempt list.

• Worst case for a full fallback walk is roughly 2 × timeoutMs + backoff per channel, so a four-channel chain with the default budget can take up to ~4 minutes. Set WEBSEARCH_TIMEOUT_MS or WEBSEARCH_MAX_PROVIDERS to suit your client's deadline.

Channel matrix

Two slots (kimi, mimo) return an LLM-synthesized answer plus citations rather than a plain result list. This server surfaces the citations as result items and puts the synthesized answer in _meta.answer (labelled per channel when aggregating several).

Development

npm install
npm run build          # tsc → dist/
npm run typecheck      # tsc over src/, test/ and scripts/ (no emit)
npm test               # vitest, all HTTP mocked (no keys needed)
npm run test:coverage  # coverage gate: 95% minimum on src/ (lines/functions/branches/statements)
npm run smoke          # real requests against every ready channel, prints a latency table
npm run cli -- repl    # run the CLI from source via tsx

Conventions

• Comments and file headers are written in English.

• Runtime-visible strings stay in English — tool descriptions, CLI output, log lines and error messages — so clients and scripts get stable, greppable output.

• SERVER_NAME / SERVER_VERSION in src/server-info.ts are the single source of truth for the server identity; test/server-info.test.ts asserts they match package.json on every test run.

• Layering is one-directional: types / errors / config-file / normalize at the bottom, then config / http / provider-selection, then orchestrator / probe, then providers, then runtime / tools / cli.

Repository layout

Working rules for coding agents live in AGENTS.md.

License

MIT