Skip to main content
Glama
deepseek_search

deepseek_search

by numakkiyu
README.md
<div align="center">

<img src="assets/banner.png" alt="Codex DeepSeek Search" width="100%">

</div>

# Codex DeepSeek Search

Adds web search and page fetch to Codex, using the DeepSeek Search / Fetch API as the search backend.

Once installed it shows up in Codex's plugin list next to the built-in web search. Codex uses it when
the built-in search is unavailable or gives poor results, or when you ask for DeepSeek search
explicitly.

**English** · [简体中文](README.zh-CN.md)

---

## What it looks like

In the Codex App plugin page you get the name, icon, three preset prompts, the MCP server, the skill,
and the version and website fields.

<div align="center">
<img src="assets/codex-app.png" alt="DeepSeek Search in the Codex App plugin page" width="460">
</div>

---

## Install

### Requirements

| | |
|:---|:---|
| Node.js | 20 or newer (`node -v`) |
| Codex | CLI, desktop app or IDE extension |
| DeepSeek API key | create one at [platform.deepseek.com](https://platform.deepseek.com/api_keys) |

### 1. Download and install

```bash
git clone https://github.com/numakkiyu/codex-deepseek-search.git
cd codex-deepseek-search
node install.mjs
```

The installer registers the plugin marketplace, installs the plugin, and enables it in
`~/.codex/config.toml`. **No key is needed for this step** — it also creates the key file for you.

### 2. Add your key

Open `~/.codex/deepseek-search.env` and put the key after the equals sign:

```dotenv
DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
```

Save it. **No restart needed** — the plugin re-reads this file on the next tool call.

> Don't want to hunt for the file: `node install.mjs --open-config` opens it in your editor.

### 3. Check it works

Start a new Codex session (`/new`), open `/plugins`, and confirm **DeepSeek Search** is enabled.

To check the whole chain from a terminal:

```bash
node doctor.mjs
```

It runs 14 checks: runtime, manifest files, which config file is active, the Codex install, the
marketplace registration, the plugin cache, the MCP handshake, and the account balance.

### Other installer options

```bash
node install.mjs --key sk-…          # write the key in the same run
node install.mjs --key-file key.txt  # read the key from a file
node install.mjs --configure         # only create the key file, print its path
node install.mjs --open-config       # create it and open it in your editor
node install.mjs --app-managed       # also register a user-level server (form-based key entry)
node install.mjs --print-config      # print all three routes as snippets
node install.mjs --verify-only       # verify only, change nothing
node install.mjs --no-verify         # skip the live check
node install.mjs --no-register       # do not touch the marketplace or plugin list
node install.mjs --uninstall         # remove plugin, marketplace and key file
```

The installer backs up `config.toml` before its first write, and writes nothing on a repeat run.

---

## Usage

### When it gets used

Codex reaches for this plugin when:

1. the built-in web search fails, returns nothing, or returns irrelevant results;
2. you ask for DeepSeek search explicitly;
3. you need the full text of a specific page;
4. it needs to work out *why* a search failed — it asks the status tool first.

Everything else still goes through the built-in search. When it switches, Codex says so in one
sentence, so you know which engine produced the answer.

### The three tools

The plugin registers one MCP server, `deepseek_search`, with three tools:

| Tool | What it does |
|:---|:---|
| `deepseek_web_search` | Searches the web. Returns title, URL, short snippet, long summary, site name and icon, publication date, authority score and relevance score |
| `deepseek_web_fetch` | Fetches one page as Markdown |
| `deepseek_search_status` | Reports where the key came from, which config files exist, the endpoints, the protocol version and the account balance |

### Search parameters

| Parameter | Type | Default | Notes |
|:---|:---|:---|:---|
| `query` | string, 1–128 chars | required | Supports the operators below |
| `count` | integer 1–50 | 10 | Number of results; the per-request price does not depend on it |
| `ori_question` | string ≤128 | — | Recommended. DeepSeek documents that it improves query understanding; measured effect on the result set is modest (mostly a re-rank) |
| `localization` | string | — | IP address for localized ranking; must be a valid IP |
| `need_content` | boolean | false | Also return page text, up to `count` pages per request |
| `summary_max_chars` | integer 200–8000 | 1200 | Per-result summary cap, to control context size |

### Search operators

Passed through to the DeepSeek engine as-is:

| Operator | Example | Meaning |
|:---|:---|:---|
| `site:` | `DeepSeek site:github.com` | Only this site; combine several with `OR` |
| `-site:` | `DeepSeek -site:example.com` | Exclude a site |
| `-word` | `DeepSeek -advertisement` | Exclude results containing a word |
| `"phrase"` | `DeepSeek "release notes"` | Exact phrase; prefix with `-` to exclude |
| `lang:` | `DeepSeek lang:en,zh` | Restrict language |
| `after:` / `before:` | `DeepSeek after:2025-01-01` | Restrict publication date |

### Examples

Just ask in Codex:

- Search with DeepSeek for the latest DeepSeek API changes
- Use DeepSeek to find the MCP spec, but only on modelcontextprotocol.io
- Read this page in full and summarize it: https://example.com/article

---

## How it works

### Pieces

The plugin is three parts, all under `plugins/deepseek-search/`:

```
plugins/deepseek-search/
├── .codex-plugin/plugin.json   what Codex reads: name, icons, skills, MCP declaration
├── .mcp.json                   how to start the server: command, args, timeouts, env allowlist
├── server/                     the MCP server itself — plain Node.js, no dependencies
│   ├── server.mjs              protocol handling + turns results into text and structured data
│   ├── deepseek-client.mjs     calls the DeepSeek API: retries, cache, rate limit, error mapping
│   ├── config.mjs              finds the key, merges config layers, watches the files
│   └── tools.mjs               parameter and response schemas for the three tools
└── skills/deepseek-search/
    └── SKILL.md                tells Codex when to use it and how to search well
```

After installation Codex copies the plugin to `~/.codex/plugins/cache/…/<version>/` and runs it from
there. Because the path contains the version, **you must reinstall after an upgrade** — otherwise
Codex keeps running the old copy.

### One search, end to end

```mermaid
flowchart TD
    A[User asks a question] --> B[Codex model]
    B -->|built-in search unavailable, or user asked| C[calls deepseek_web_search]
    C --> D[deepseek_search MCP server]
    D --> E{read the API key}
    E -->|environment variable| F[send request]
    E -->|config file| F
    E -->|neither| G[return a missing-key error with the file path]
    F --> H[DeepSeek Search API]
    H --> I[clean up results: decode site names, trim summaries]
    I --> J[return to Codex]
    J --> B
```

On a `tools/call` request the server calls `POST /v1/tools/search`, then returns two things together:

- `content` — text for the model to read (a Markdown list);
- `structuredContent` — fields for programs, matching the schema declared in `tools.mjs`.

### Where the key comes from

First source with a value wins:

1. `DEEPSEEK_API_KEY` (or `DS_API_KEY`) in the environment
2. A config file, in this order:
   - `$DEEPSEEK_SEARCH_ENV_FILE` (if set)
   - `$PLUGIN_DATA/deepseek-search.env` (the per-plugin data directory Codex injects)
   - `~/.codex/deepseek-search.env` (what the installer writes)
   - `~/.deepseek-search.env`
   - `<plugin dir>/.env`
3. The `refs:` block in `~/.dsh/.credentials.yaml`

The files are re-checked for changes before every tool call, so an edit takes effect immediately.
`deepseek_search_status` tells you which layer is active and the absolute paths of all candidates.

### MCP protocol

One server, two protocol eras:

| Client | How it opens | Response shape |
|:---|:---|:---|
| Legacy (2025-11-25 and earlier) | sends `initialize` first | legacy shape, no `resultType` |
| Modern (2026-07-28) | no handshake; version travels per request in `params._meta` | includes `resultType`, `cacheScope`, `ttlMs` |

Which era applies is decided by how the client opens the connection.

### How errors come back

Two kinds, on purpose:

**Tool execution errors** (`isError: true`) — problems the model can understand and correct, such as
a bad parameter, an invalid key, or an unreachable page. These carry an explanation, so the model can
adjust and retry.

**JSON-RPC protocol errors** (with a code) — the request itself is malformed: unknown tool, bad JSON,
unsupported protocol version. The model cannot fix these, so the host gets an error code.

| Status | `code` | Meaning | What the model is told |
|:---|:---|:---|:---|
| — | `missing_api_key` | No key configured | absolute paths of the three candidate files |
| 400 | `bad_request` | Invalid parameter | which field is wrong |
| 401 | `invalid_key` | Invalid key | which file the key came from, and which to edit |
| 402 | `balance_exhausted` | Balance exhausted | current balance and the top-up page |
| 403 | `forbidden` | Blocked by safety policy (fetch) | try a different URL |
| 404 | `page_not_found` | Page unreachable or no body | try a different search result |
| 408 | `timeout` | Upstream read timeout | already retried |
| 413 | `payload_too_large` | Body over 160 KiB | lower `count`, or turn off `need_content` |
| 429 | `rate_limited` | Rate limited | Search 100 QPS, Fetch 25 QPS per account |
| 5xx | `server_error` | Server error | already retried automatically |

Errors carry both forms at once: readable text for the model, and `structuredContent.error.code` for
programs (the values in the table above). That lets a front end recognise "out of credit" and offer a
top-up without parsing prose.

408, 429 and every 5xx are retried with exponential backoff and jitter. Other 4xx responses are not
retried.

### Empty results are relaxed automatically

DeepSeek does not bill a search that returns no results. The server uses that: when the first search
comes back empty it relaxes the query itself instead of handing the job back to the model — first
dropping `after:` / `before:`, then `site:` / `-site:`, then quoted phrases. It stops as soon as a
step returns something.

The response reports `relaxed`, `attempts` and `relaxations`, so you can tell "nothing matches the
strict query" from "nothing matches at all". Set `DEEPSEEK_SEARCH_AUTO_RELAX=0` to turn it off.

### How the DeepSeek API actually behaves

Measured, not taken from the docs. Where the two disagree, the plugin follows what the API does.

| Item | Documentation | Measured | Handling |
|:---|:---|:---|:---|
| `site_name` | site name | about half are hex strings (`e5a4aee5b9bfe7bd91` is 央广网) | validated decode, else left as-is |
| `summary` length | usually 600–800 chars | median 1739, max over 5600 | capped by `summary_max_chars`, default 1200 |
| `site_icon` | the site's favicon | always `cdn.deepseek.com/site-icons/<domain>` | passed through |
| `authority` | 0–4, ≥3 means highly authoritative, `-1` unknown | ~96% of results score 3 or higher | semantics kept; used for ordering and citation choice, not as a filter |
| `rerank_score` | 0–3, ≥1.5 means high quality | ~89% clear 1.5; normal range 1.3–2.7 | same: documented semantics kept, used as relative ordering within one response |
| error field | `code` identifies the error | `code` is constant; `type` is what varies | classified by `type` |
| request body limit | only "413 too large" | exactly 163840 bytes | stated in the 413 message |
| retry scope | 408, 429, 5xx | should cover all 5xx | checks `>= 500` |
| rate-limit headers | may include `Retry-After` | none are returned | plain exponential backoff |
| fetch body | Markdown | ~77 escaped characters per 1000 | unescaped before returning |
| same query | stable results | URL overlap ~4/10 across three calls; top hit stable | does not promise identical results |
| error pages | page errors surface | a site's "page not found" can arrive as HTTP 200 | flagged as `suspectedErrorPage` |
| deduplication | — | 1 duplicate in 300 results | not implemented |

Two more measurements shaped the defaults:

- `count` from 1 to 50 barely changes latency (634 ms → 543 ms), and pricing is per request — so a
  larger `count` does not cost more.
- One `need_content=true` request returns up to `count` full pages, which is cheaper than fetching
  them one by one and gives cleaner text.

### Limits and caching

- Fetch goes through a token bucket, 20 QPS by default (the account cap is 25), with at most 8
  requests in flight.
- Identical queries hit an in-process cache: 120 seconds, 64 entries. It only reduces latency; it is
  not a consistency guarantee.
- No per-domain serialization is needed — 20–24 concurrent fetches against one domain produced no 429s.

---

## How it differs from a plain DeepSeek MCP server

The existing DeepSeek search MCP servers all work, and do broadly the same thing. The differences are:

| Item | Plain MCP server | This project |
|:---|:---|:---|
| Knows when to be used | no, the model decides | yes, stated in `SKILL.md` |
| MCP protocol versions | usually one | both 2026-07-28 and legacy |
| Diagnostic tool | usually none | `doctor.mjs`, 14 checks |
| Where the key lives | usually `config.toml` | a separate file you can edit any time |
| Follows the API's real behaviour | mostly the docs | measured behaviour (see above) |

If you only need an MCP server and don't mind editing `config.toml` yourself, any of them will do.

---

## FAQ

**Installed, but nothing shows in `/plugins`**
Check that `node install.mjs` finished without errors, then start a new session. Plugins load when
Codex starts.

**It says no API key is configured**
Run `node doctor.mjs`. It prints the absolute paths of the three candidate files and marks which
exists and which is writable.

**Still 401 after adding a key**
You probably edited a file that isn't the active one. Call the `deepseek_search_status` tool and look
at `keySource`.

**It says the balance is exhausted**
Top up at [platform.deepseek.com](https://platform.deepseek.com). The status tool shows the balance.

**doctor reports `Marketplace path` failed**
The marketplace still points at another directory, usually because the checkout moved. Run
`node install.mjs` again — it rewrites that single line and nothing else.

**The plugin cache is locked**
A Codex instance is running. Close it and re-run the installer.

---

## License

[MIT](LICENSE).

Not affiliated with DeepSeek or OpenAI. "DeepSeek", the DeepSeek mark and "Codex" belong to their
respective owners.

---

<div align="center">
<sub>

[DeepSeek Search API docs](https://api-docs.deepseek.com/zh-cn/guides/search) ·
[MCP specification 2026-07-28](https://modelcontextprotocol.io/specification/2026-07-28) ·
[DeepSeek platform](https://platform.deepseek.com)

</sub>
</div>