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>
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues