deepseek-web-retrieval 0.7.0 → 0.9.0

package/docs/agents/claude-code.md

@@ -0,0 +1,279 @@
+# Claude Code
+
+Claude Code adapter for [DeepSeek Web Retrieval](../../README.md).
+
+Integration mechanism: MCP server over stdio, registered in Claude Code's own MCP config
+files — `.mcp.json` at the project root (project scope) or the top-level `mcpServers` key
+of `~/.claude.json` (user scope, where `claude mcp add --scope user` writes). Claude Code
+negotiates MCP revision `2026-07-28`; the server accepts clients from `2024-11-05` through
+`2026-07-28`, so the same build works for other MCP hosts (see
+[the compatibility research](../research/mcp-compatibility.md)).
+
+When registered, it adds:
+
+- A `deepseek_web_search` tool backed by DeepSeek Search
+- A `deepseek_fetch` tool backed by DeepSeek Fetch
+
+The tools appear in Claude Code as `mcp__deepseek__deepseek_web_search` and
+`mcp__deepseek__deepseek_fetch`. Claude Code's built-in `WebSearch` and `WebFetch` tools
+are not replaced; see [Control tiers](#control-tiers) for routing them away.
+
+For shared search/fetch limits, retries, and privacy behavior, see
+[General behavior](../../README.md#general-behavior).
+For configuration layers, the full knob mapping, and defaults, see the
+[configuration guide](../configuration.md).
+
+## Requirements
+
+- Claude Code at the tested version in [`docs/hosts.jsonc`](../hosts.jsonc); init reports
+  version drift, and newer versions may require rechecking routing behavior
+- Node.js 20 or newer (`npx` runs the server)
+- A DeepSeek account with access to `/v1/tools/search` and `/v1/tools/fetch`
+- A funded DeepSeek account; Search and Fetch are billed per successful request
+- `DEEPSEEK_API_KEY` set in the shell that launches Claude Code
+
+## Install
+
+The quickest option is the installer CLI:
+
+```bash
+npx deepseek-web-retrieval init --host claude-code --scope project \
+  --search <tier> --fetch <tier>
+```
+
+It prints the full plan — every file, old value → new value, and notes about existing MCP
+servers — and writes nothing until you pass `--apply`. Add `--pin` to register the exact
+version of the CLI you are running instead of the always-latest package name. `uninstall`
+removes recorded additions and restores snapshotted values that have not since been edited.
+`--scope project` registers the server in `./.mcp.json` (shareable via VCS) and writes tier
+artifacts to `./.claude/settings.json` and `./CLAUDE.md`; `--scope global` uses
+`~/.claude.json`, `~/.claude/settings.json`, and `~/.claude/CLAUDE.md` instead — the two
+scopes use disjoint files, so both can coexist. An `off` capability is written as the
+tool's full id in the `permissions.deny` array — Claude Code's own mechanism, which removes
+the tool from the model's context while the server keeps running — merging with any entries
+you put there yourself. When `claude` is on PATH, `init` also probes `claude --version` and
+adds a plan note when the installed release differs from the tested lock (see
+[hosts.jsonc](../hosts.jsonc)) — version-anchored behavior such as the deny rules may have
+drifted between the two.
+
+For an existing installer-managed setup, follow the
+[upgrade instructions](../integration.md#upgrading-existing-installs) from the original
+project directory and scope.
+
+### Manual install
+
+Add the server to `.mcp.json` at the project root:
+
+```json
+{
+  "mcpServers": {
+    "deepseek": {
+      "command": "npx",
+      "args": ["-y", "deepseek-web-retrieval"],
+      "env": { "DEEPSEEK_API_KEY": "${DEEPSEEK_API_KEY}" }
+    }
+  }
+}
+```
+
+> [!NOTE]
+> `"${DEEPSEEK_API_KEY}"` is Claude Code's own `${VAR}` expansion: the key is read from
+> the environment that launches Claude Code and never sits in the file. A literal value
+> works too if you prefer it in the file. For a user-scope install, the same entry goes
+> under the top-level `mcpServers` key of `~/.claude.json`, or use
+> `claude mcp add --scope user --env 'DEEPSEEK_API_KEY=${DEEPSEEK_API_KEY}' deepseek -- npx -y deepseek-web-retrieval`.
+
+Claude Code asks once per project whether to use servers from `.mcp.json`; approve the
+`deepseek` server when prompted (or via the `/mcp` menu), or its tools will not load in
+that project.
+
+To disable one capability, add the tool's full id to `permissions.deny` in
+`.claude/settings.json` — Claude Code removes the tool from the model's context while the
+server keeps running:
+
+```json
+{
+  "permissions": {
+    "deny": ["mcp__deepseek__deepseek_web_search"]
+  }
+}
+```
+
+The ids match the tool names verbatim (`mcp__deepseek__deepseek_web_search`,
+`mcp__deepseek__deepseek_fetch`). The server also honors
+`DEEPSEEK_ENABLE_SEARCH`/`DEEPSEEK_ENABLE_FETCH` in the server's `env` block if you prefer
+switching the tools off at the source; the installer uses `permissions.deny`.
+
+### Local checkout
+
+```bash
+git clone https://github.com/gwokhou/deepseek-web-retrieval.git
+cd deepseek-web-retrieval && bun install && bun run build
+```
+
+```json
+{
+  "mcpServers": {
+    "deepseek": {
+      "command": "node",
+      "args": ["/absolute/path/to/deepseek-web-retrieval/dist/cli.js"],
+      "env": { "DEEPSEEK_API_KEY": "${DEEPSEEK_API_KEY}" }
+    }
+  }
+}
+```
+
+## Control tiers
+
+Claude Code ships built-in `WebSearch` and `WebFetch` tools; neither is replaceable, so
+both capabilities use exclusion for the forced tier:
+
+| Capability | Optional | Preferred | Forced |
+| --- | --- | --- | --- |
+| Search | Tools registered; the built-in `WebSearch` stays available | Plus a CLAUDE.md rules block steering the model to `mcp__deepseek__deepseek_web_search` | Exclusion: `permissions.deny: ["WebSearch"]` |
+| Fetch | Tools registered; the built-in `WebFetch` stays available | Plus the rules block | Exclusion: `permissions.deny: ["WebFetch"]` |
+
+The installer maps each tier to these artifacts. Deny entries land in
+`~/.claude/settings.json` (user) or `./.claude/settings.json` (project) and merge with
+your existing `permissions.deny` entries. The CLAUDE.md rules block lands in
+`~/.claude/CLAUDE.md` (user) or `./CLAUDE.md` (project); Claude Code loads the user file
+plus every CLAUDE.md from the cwd up the directory tree, concatenating the levels — so
+the block steers wherever it is installed. Under a forced tier, other web-capable MCP
+servers detected in the config are denied by server-level rules (`mcp__<server>` denies
+every tool of that server), so routing stays exclusive.
+
+> [!WARNING]
+> Deny rules outrank allow rules at every settings level and **cannot be carved out** —
+> denying `WebSearch` or `WebFetch` removes the tool for every workflow in the install's
+> scope (every project on the machine for `--scope global`). A managed policy layer
+> (`managed-settings.json`) outranks both files; the installer reports when one exists.
+
+## Authentication
+
+`DEEPSEEK_API_KEY` is the only source; MCP has no host credential store. It is forwarded
+through the server's `env` block as `${DEEPSEEK_API_KEY}` and read per request, sent only
+to `api.deepseek.com` as a Bearer token. Without it the server exits at startup with a
+message on stderr.
+
+## Usage
+
+Ask naturally:
+
+```text
+Search the web for the latest Claude Code MCP config changes and cite the sources.
+Fetch https://code.claude.com/docs/en/mcp and summarize the config keys.
+```
+
+The model calls `mcp__deepseek__deepseek_web_search` or `mcp__deepseek__deepseek_fetch`.
+
+The search tool accepts an optional `original_question` argument — the user's question in
+their own words — forwarded as DeepSeek's `ori_question` to sharpen search intent; omit it
+when the query already stands alone. It also takes an optional `count` (1–50) for the call,
+and the fetch tool takes an optional `maxChars` (0–1,000,000) per-call output budget; each
+overrides the configured default for that call, so the model can widen a truncated fetch or
+ask for more results without rephrasing the query. When configured domain or language
+operators change the query actually sent, the result text opens with
+`Searched for: <effective query>` (plus any degradation applied to fit the API's
+128-character limit), so the model can attribute results to the configuration in effect.
+
+Tool output is capped at 25k tokens by default (`MAX_MCP_OUTPUT_TOKENS`), and successful
+text results longer than 50,000 characters are saved to a file and referenced — not
+dropped silently.
+
+## Configuration
+
+Set these in the server's `env` block in `.mcp.json` (or `~/.claude.json`). Values map onto
+the shared option pipeline, so defaults and clamping match the other adapters.
+`DEEPSEEK_API_KEY` goes in the same block as the `${VAR}` expansion.
+
+> [!NOTE]
+> A shared config file — `~/.config/deepseek-web-retrieval/config.json`
+> (Windows: `%APPDATA%\deepseek-web-retrieval\config.json`), camelCase keys —
+> sits under the environment layer and works with no env forwarding at all: the server
+> reads the file itself, making it the way to set knobs without editing the MCP entry. The
+> file carries neither the API key nor the host-integration switches. Run
+> `npx deepseek-web-retrieval config` to see every knob's effective value and source
+> (it replays file warnings visibly and exits 1 on file problems); `config --search "<query>"`
+> verifies key, config, and network with one billed search.
+
+### Search
+
+The "Config file" column names each key's camelCase twin in the shared config file —
+one vocabulary pair, one pipeline. `—` marks host-integration entries the file rejects.
+
+| Env variable | Config file | Default | Description |
+| --- | --- | --- | --- |
+| `DEEPSEEK_ENABLE_SEARCH` | — | `true` | Register the search tool. Only an explicit `false`/`0`/`no`/`off` disables it; at least one tool must stay enabled. |
+| `DEEPSEEK_SEARCH_COUNT` | `count` | `10` | Results requested from DeepSeek, 1–50. Billing is per request, not per result. |
+| `DEEPSEEK_SEARCH_MAX_RESULTS` | `maxResults` | `10` | Results returned to the model after filtering, 0–50; defaults to `DEEPSEEK_SEARCH_COUNT` when unset. `0` returns no results. |
+| `DEEPSEEK_SEARCH_MIN_RERANK` | `minRerank` | `0` | Drop results below this relevance score (0–3); results without a finite score pass at zero and are dropped at a positive threshold. |
+| `DEEPSEEK_SEARCH_MIN_AUTHORITY` | `minAuthority` | `0` | Drop known authorities below this tier. Authority is 0–4. |
+| `DEEPSEEK_SEARCH_ALLOW_UNKNOWN_AUTHORITY` | `allowUnknownAuthority` | `true` | Keep results whose authority is missing or unknown. Set `false`/`0`/`no`/`off` to drop them. |
+| `DEEPSEEK_SEARCH_BLOCKED_DOMAINS` | `blockedDomains` | unset | Comma-separated; adds `-site:` operators to the query. |
+| `DEEPSEEK_SEARCH_INCLUDE_DOMAINS` | `includeDomains` | unset | Comma-separated; restricts results with `site:` operators. |
+| `DEEPSEEK_SEARCH_LANGUAGE` | `language` | unset | Adds a `lang:` operator, for example `zh,en`. |
+| `DEEPSEEK_SEARCH_LOCALIZATION` | `searchLocalization` | unset | Valid IPv4 or IPv6 address sent as DeepSeek's `localization` to prefer geo-localized results; invalid values are ignored. Deployment-level only, never a per-call parameter. |
+| `DEEPSEEK_SEARCH_MAX_SUMMARY_CHARS` | `maxSummaryChars` | `1200` | Per-result summary cap, 0–1,000,000. |
+| `DEEPSEEK_SEARCH_TIMEOUT_MS` | `searchTimeoutMs` | `30000` | Search timeout, 1,000–120,000 ms. |
+
+### Fetch
+
+| Env variable | Config file | Default | Description |
+| --- | --- | --- | --- |
+| `DEEPSEEK_ENABLE_FETCH` | — | `true` | Register the fetch tool. Same false-only semantics as `DEEPSEEK_ENABLE_SEARCH`. |
+| `DEEPSEEK_FETCH_MAX_CHARS` | `fetchMaxChars` | `16000` | Maximum characters returned, including the title, 0–1,000,000. |
+| `DEEPSEEK_FETCH_TIMEOUT_MS` | `fetchTimeoutMs` | `30000` | Fetch timeout, 1,000–120,000 ms. |
+| `DEEPSEEK_FETCH_ALLOWED_DOMAINS` | `fetchAllowedDomains` | unset | If set, only these hosts and subdomains may be fetched. |
+| `DEEPSEEK_FETCH_BLOCKED_DOMAINS` | `fetchBlockedDomains` | unset | Always block these hosts and subdomains. Blocked wins over allowed. |
+| `DEEPSEEK_FETCH_BLOCK_PRIVATE_HOSTS` | `fetchBlockPrivateHosts` | `true` | Reject localhost, private IPs, `.local`, `.internal`, and similar hosts. |
+
+### Credentials and retries
+
+| Env variable | Config file | Default | Description |
+| --- | --- | --- | --- |
+| `DEEPSEEK_API_KEY` | — | required | DeepSeek API key, expanded from the launching environment via `${DEEPSEEK_API_KEY}`. The server refuses to start without it. |
+| `DEEPSEEK_MAX_RETRIES` | `maxRetries` | `2` | Retries for 408, 425, 429, and 5xx responses, 0–5. |
+| `DEEPSEEK_RETRY_BASE_DELAY_MS` | `retryBaseDelayMs` | `250` | Base delay for exponential backoff. `Retry-After` is honored up to 10 seconds. |
+
+## Troubleshooting
+
+| Error or symptom | What to do |
+| --- | --- |
+| Server fails to start or `HTTP 401` from the tools | `DEEPSEEK_API_KEY` must be set in the environment that launches Claude Code; the `${DEEPSEEK_API_KEY}` expansion in the server's `env` block reads it at launch. |
+| Project tools missing after install | Claude Code asks once per project whether to use `.mcp.json` servers; approve the `deepseek` server when prompted or via the `/mcp` menu. |
+| Both tools missing after startup | At least one of `DEEPSEEK_ENABLE_SEARCH`/`DEEPSEEK_ENABLE_FETCH` must stay enabled; the server exits when both are false. |
+| Forced tier still shows the built-in tool | The kill switch is the bare deny rule in `permissions.deny` at the install's scope; a managed policy layer (`managed-settings.json`) outranks it — the plan reports when one exists. |
+| Routing not exclusive | Other MCP servers stay registered and are noted in the plan. Under a forced tier, web-capable servers detected in the config (and the other scope's file) are denied by server-level `mcp__<server>` rules; a server added after install is not covered — re-run init. |
+| Fetch results appear as a file reference instead of content | Tool output is capped at 25k tokens by default; raise `MAX_MCP_OUTPUT_TOKENS` or lower `DEEPSEEK_FETCH_MAX_CHARS`. |
+| `HTTP 402`, `HTTP 429` | Top up the DeepSeek account; wait, reduce concurrency, or set `DEEPSEEK_MAX_RETRIES`. |
+| Fetch fails on localhost or an internal URL | Use a local fetch tool; DeepSeek cannot reach private networks. |
+
+## Compatibility
+
+| Component | Version |
+| --- | --- |
+| Claude Code | locked in [`docs/hosts.jsonc`](../hosts.jsonc) |
+| MCP revision | `2026-07-28` negotiated; server accepts `2024-11-05`–`2026-07-28` |
+| MCP SDK | `@modelcontextprotocol/server` 2.3.1 |
+| Runtime | Node.js 20+ (stdio) |
+| DeepSeek API | `/v1/tools/search`, `/v1/tools/fetch` |
+
+Tested with Claude Code at the `docs/hosts.jsonc` lock on Linux over stdio: the keyless
+Docker e2e verifies the installer's registration, tiers, and uninstall with a real
+`claude mcp list` handshake, and the billed scenario (`bun run test:e2e claude-code`,
+requires `DEEPSEEK_API_KEY`) runs headless prompts end to end with the deny kill switch
+asserted for both capabilities.
+
+## Uninstall
+
+```bash
+npx deepseek-web-retrieval uninstall --host claude-code --scope project
+```
+
+This removes the recorded `mcpServers.deepseek` entry and the installer-appended
+`permissions.deny` entries only when their current values still match what the installer
+wrote, removes the managed rules block, and deletes installer-created config files only
+when left empty. Later user edits to configuration values are kept and reported. For a
+manual installation, remove the `deepseek` entry from `.mcp.json` (or `~/.claude.json`),
+any `deepseek-web-retrieval` rules block in your `CLAUDE.md`, and the deny entries the
+setup added to `settings.json` if they were only for this integration.

package/docs/agents/codex.md

@@ -24,6 +24,8 @@ both the text and `structuredContent`.
 
 For shared search/fetch limits, retries, and privacy behavior, see
 [General behavior](../../README.md#general-behavior).
+For configuration layers, the full knob mapping, and defaults, see the
+[configuration guide](../configuration.md).
 
 ## Requirements
 
@@ -146,7 +148,13 @@ The model calls `mcp__deepseek__deepseek_web_search` or `mcp__deepseek__deepseek
 
 The search tool accepts an optional `original_question` argument — the user's question in
 their own words — forwarded as DeepSeek's `ori_question` to sharpen search intent; omit it
-when the query already stands alone.
+when the query already stands alone. It also takes an optional `count` (1–50) for the call,
+and the fetch tool takes an optional `maxChars` (0–1,000,000) per-call output budget; each
+overrides the configured default for that call, so the model can widen a truncated fetch or
+ask for more results without rephrasing the query. When configured domain or language
+operators change the query actually sent, the result text opens with
+`Searched for: <effective query>` (plus any degradation applied to fit the API's
+128-character limit), so the model can attribute results to the configuration in effect.
 
 ## Configuration
 

package/docs/agents/opencode-v2.md

@@ -15,6 +15,8 @@ if you want all Markdown fetches to go through DeepSeek.
 
 For shared search/fetch limits, retries, and privacy behavior, see
 [General behavior](../../README.md#general-behavior).
+For configuration layers, the full knob mapping, and defaults, see the
+[configuration guide](../configuration.md).
 
 ## Requirements
 
@@ -174,9 +176,17 @@ Fetch https://opencode.ai/v2/docs/build/plugins and summarize the plugin lifecyc
 The model calls `websearch` (provider `deepseek`) or `deepseek_fetch`. When
 `fetchOverrideWebfetch` is enabled, Markdown fetches go through `webfetch` instead.
 
-DeepSeek's optional `ori_question` is not sent on this path: OpenCode's `websearch` tool
-input is fixed to `query` at 2.0.32, so the provider has no channel for it (see the
-[research note](../research/ori-question-sourcing.md)).
+DeepSeek's optional `ori_question` is not sent on this path, and the model cannot request a
+per-call result count: OpenCode's `websearch` tool input is fixed to `query` (verified unchanged
+at 2.1.4), so the provider has no channel for either. Upstream requests:
+[anomalyco/opencode#58635](https://github.com/anomalyco/opencode/issues/58635) (session linkage)
+and [#58636](https://github.com/anomalyco/opencode/issues/58636) (per-call `count`); see the
+[research note](../research/ori-question-sourcing.md). The fetch tools are not constrained:
+they accept an optional per-call `maxChars` (0–1,000,000) that overrides the configured
+`fetchMaxChars` for one call, so the model can widen the budget after seeing a
+`[content truncated]` marker. The effective-query header and query degradation notes have no
+channel on this path either — OpenCode's result shape is closed — but degradation still runs,
+and failures that cannot degrade surface as errors.
 
 ## Configuration
 

package/docs/agents/pi.md

@@ -22,6 +22,8 @@ When loaded, it adds:
 Pi 1.3.0 ships no built-in web tool, so the registered tools are the only web path. For
 shared search/fetch limits, retries, and privacy behavior, see
 [General behavior](../../README.md#general-behavior).
+For configuration layers, the full knob mapping, and defaults, see the
+[configuration guide](../configuration.md).
 
 ## Requirements
 
@@ -108,7 +110,12 @@ The search tool accepts an optional `original_question` input — the user's que
 own words — forwarded as DeepSeek's `ori_question` to sharpen search intent. When the model
 leaves it blank, the extension falls back to the most recent user message in the session
 (best-effort; truncated to the API's 128-character limit). The MCP fallback path has no
-session access, so there a blank input simply omits the parameter.
+session access, so there a blank input simply omits the parameter. The search tool also
+takes an optional `count` (1–50) for the call, and the fetch tool an optional `maxChars`
+(0–1,000,000) per-call output budget; each overrides the configured default for that call.
+When configured domain or language operators change the query actually sent, the result text
+opens with `Searched for: <effective query>` (plus any degradation applied to fit the API's
+128-character limit), so the model can attribute results to the configuration in effect.
 
 ## Configuration
 

package/docs/configuration.md

@@ -0,0 +1,116 @@
+# Configuration guide
+
+The one reference for how every knob resolves on every host: the layering
+chain, the shared config file, the full knob vocabulary, and which layer to set.
+Behavior (what search and fetch do) lives in the README's
+[General behavior](../README.md#general-behavior); per-host mechanics (output
+caps, deadlines, how the environment reaches a stdio server) live in the host
+guides: [Codex](agents/codex.md), [Claude Code](agents/claude-code.md),
+[Pi](agents/pi.md),
+[OpenCode](agents/opencode-v2.md).
+
+## The resolution chain
+
+Every knob resolves through one chain, low → high, identically on every host:
+
+```
+built-in defaults  <  shared config file  <  DEEPSEEK_* environment  <  host-native config
+```
+
+A higher layer always wins, so nothing already configured loses effect. The
+host-native layer means OpenCode's plugin options (`opencode.jsonc`), Pi's
+`deepseekWebRetrieval` settings namespace, and — for MCP hosts — the per-server
+`env` block in the host's registration (that block is how an environment
+variable arrives, not a fifth layer).
+
+## The shared config file
+
+`$XDG_CONFIG_HOME/deepseek-web-retrieval/config.json` when `XDG_CONFIG_HOME` is
+set (this wins on every platform, Windows included); otherwise
+`~/.config/deepseek-web-retrieval/config.json` on Linux and macOS and
+`%APPDATA%\deepseek-web-retrieval\config.json` on Windows. camelCase keys:
+
+```json
+{
+  "count": 20,
+  "blockedDomains": ["pinterest.com"],
+  "language": "zh",
+  "searchLocalization": "203.0.113.7"
+}
+```
+
+Unknown keys and host-integration keys (below) draw a one-line stderr warning
+and are otherwise ignored — a bad file never blocks startup. The API key never
+goes in the file; it keeps its existing channels (`DEEPSEEK_API_KEY` in the
+environment, or OpenCode's stored credential).
+
+## Knob classes
+
+| Knob class | Shared file | Examples |
+| --- | --- | --- |
+| API behavior — the user↔DeepSeek relationship | yes — that is the point of the file | `count`, `blockedDomains`, `language`, `maxRetries` |
+| Host-sensitive — interacts with host output caps and deadlines | carries the safe defaults; a host layer is the recommended override point | `searchTimeoutMs`, `fetchTimeoutMs`, `fetchMaxChars`, `maxSummaryChars` |
+| Host integration — the host's tool landscape | rejected — warned about and ignored | `searchEnabled`, `setDefaultWebsearch`, `apiKeySource` |
+
+Keep host-independent intent in the shared file; prefer a host layer when a
+host-sensitive knob would cross its host's cap or deadline.
+
+## The knob vocabulary
+
+One knob, two names: the camelCase key for the shared file and OpenCode's
+options, the `DEEPSEEK_*` variable for the environment. The table generates
+from the same config vocabulary the adapters resolve through, so it cannot
+drift from the code (`bun run docs:matrix` regenerates it; CI checks it).
+
+<!-- generated: knob-table — edit src/core/config-summary.ts or env.ts, then run `bun run docs:matrix` -->
+
+| File / OpenCode key | Environment | Default |
+| --- | --- | --- |
+| `count` | `DEEPSEEK_SEARCH_COUNT` | 10 |
+| `maxResults` | `DEEPSEEK_SEARCH_MAX_RESULTS` | follows `count` (10) |
+| `minRerank` | `DEEPSEEK_SEARCH_MIN_RERANK` | 0 |
+| `minAuthority` | `DEEPSEEK_SEARCH_MIN_AUTHORITY` | 0 |
+| `allowUnknownAuthority` | `DEEPSEEK_SEARCH_ALLOW_UNKNOWN_AUTHORITY` | true |
+| `blockedDomains` | `DEEPSEEK_SEARCH_BLOCKED_DOMAINS` | unset |
+| `includeDomains` | `DEEPSEEK_SEARCH_INCLUDE_DOMAINS` | unset |
+| `language` | `DEEPSEEK_SEARCH_LANGUAGE` | unset |
+| `searchLocalization` | `DEEPSEEK_SEARCH_LOCALIZATION` | unset |
+| `maxSummaryChars` | `DEEPSEEK_SEARCH_MAX_SUMMARY_CHARS` | 1200 |
+| `searchTimeoutMs` | `DEEPSEEK_SEARCH_TIMEOUT_MS` | 30000 |
+| `fetchMaxChars` | `DEEPSEEK_FETCH_MAX_CHARS` | 16000 |
+| `fetchAllowedDomains` | `DEEPSEEK_FETCH_ALLOWED_DOMAINS` | unset |
+| `fetchBlockedDomains` | `DEEPSEEK_FETCH_BLOCKED_DOMAINS` | unset |
+| `fetchTimeoutMs` | `DEEPSEEK_FETCH_TIMEOUT_MS` | 30000 |
+| `fetchBlockPrivateHosts` | `DEEPSEEK_FETCH_BLOCK_PRIVATE_HOSTS` | true |
+| `maxRetries` | `DEEPSEEK_MAX_RETRIES` | 2 |
+| `retryBaseDelayMs` | `DEEPSEEK_RETRY_BASE_DELAY_MS` | 250 |
+| `baseUrl` | `DEEPSEEK_BASE_URL` | https://api.deepseek.com |
+
+<!-- /generated: knob-table -->
+
+## Special semantics
+
+- **`maxResults` follows `count`** when left unset — configure only `count` and
+  the cap moves with it. An explicit `maxResults` still caps; `count` never
+  follows `maxResults`.
+- **Some switches are false-only.** `allowUnknownAuthority`,
+  `fetchBlockPrivateHosts`, `searchEnabled`, and `fetchEnabled` are on by
+  default; the environment can only turn them off (`false`, `0`, `no`, or
+  `off`). The last two have no file key — they are host-integration keys — so
+  they exist only as `DEEPSEEK_ENABLE_SEARCH` and `DEEPSEEK_ENABLE_FETCH`. A
+  value like `=true` changes nothing.
+- **Invalid environment values are dropped** at startup and the default
+  applies. `npx deepseek-web-retrieval config` reports every dropped or
+  unknown `DEEPSEEK_*` variable as a warning and exits 1, alongside file
+  problems.
+- **`searchLocalization` must be a valid IPv4 or IPv6 address**; anything else
+  is dropped at option resolution. It is deployment-level configuration, never
+  a per-call tool parameter.
+- **`baseUrl` routes the retrieval API** (`/v1/tools/search` and
+  `/v1/tools/fetch` are composed from it). It is infrastructure routing for
+  proxies, gateways, and mock upstreams — not a provider switch, so nothing
+  falls back to another search service. Only an http(s) URL survives
+  resolution (trailing slashes are stripped); anything else drops back to
+  `https://api.deepseek.com`.
+- **Domains** in the environment are comma-separated; entries that are not
+  domains are dropped (and reported by `config`).

package/docs/design/installer-design.md

@@ -1,13 +1,13 @@
 # Installer design
 
 Design note for the install-time flow, shipped as the `deepseek-web-retrieval init`,
-`uninstall`, and `list` subcommands for **OpenCode, Pi, and Codex**. It records how the
-[control tiers](../research/control-matrix.md) map to the artifacts the installer emits, so
-the design survives between conversations. Research backing lives in
+`uninstall`, and `list` subcommands for **OpenCode, Pi, Codex, and Claude Code**. It records how the
+[control tiers](../research/control-matrix.md) map to the artifacts the installer emits, so the design
+survives between conversations. Research backing lives in
 [control-matrix.md](../research/control-matrix.md); host facts in [hosts.jsonc](../hosts.jsonc).
 Remaining hosts get host modules here as their guides ship.
 Examples involving other hosts describe design requirements for future modules;
-the current CLI accepts only the three shipped hosts above.
+the current CLI accepts only the four shipped hosts above.
 
 ## Principles
 
@@ -44,9 +44,9 @@ already exists, and the installer uses three phases:
    Report the conflict surface: existing rules steering toward another web tool; other
    web-capable MCP servers already on the field; array-valued keys the plan must merge
    into rather than replace (`disabledTools`, `permissions.deny`, permissions
-   `exclude`, `disabled_tools`); and higher layers (Claude Code managed policy, Devin
-   enterprise team settings) that would outrank what the
-   installer writes.
+   `exclude`, `disabled_tools`); and higher layers (Claude Code managed policy — its
+   existence is checked by the claude-code module; Devin enterprise team settings) that
+   would outrank what the installer writes.
 2. **Merge or snapshot.** Array keys merge with existing entries, recording exactly
    which entries the installer appended; single-value keys (`websearch.provider`, Pi's
    `exposure`) snapshot the prior value before overwriting; files the installer creates
@@ -71,7 +71,9 @@ already exists, and the installer uses three phases:
   competitor, not third-party web MCP servers — those must be excluded too (the
   per-host keys cover them), or routing is not actually forced. Concretely: Pi's
   per-server `enabled` key lets the plan disable detected web-capable competitors
-  (each prior value snapshotted for uninstall); Codex has no per-server kill switch,
+  (each prior value snapshotted for uninstall); Claude Code excludes them the same way
+  via server-level `mcp__<server>` deny rules appended to `permissions.deny`; Codex has
+  no per-server kill switch,
   so a detected web-capable competitor makes the plan refuse the tier instead of
   promising non-exclusive routing; OpenCode's forced is replacement, which no
   third-party server overrides. Detection classifies a server web-capable from its
@@ -156,9 +158,9 @@ the artifacts below name the path where they differ.
 | Optional | Host config registering the integration: Pi's extension path appends an `npm:<package>` source to `packages` in settings.json; the MCP paths register the server (Pi's MCP entry needs `"exposure": "direct"`; the extension path needs nothing — extension tools are `direct` by Pi's own default) |
 | Preferred | The above plus a rules file for the host (file names per host in the [per-host reference](../research/control-matrix.md#per-host-reference)); the rules name the path's tool ids (`deepseek_web_search` for the extension, `mcp__deepseek__deepseek_web_search` for MCP) |
 | Forced (replacement) | OpenCode plugin options (`setDefaultWebsearch` / `fetchOverrideWebfetch`) |
-| Forced (exclusion) | The built-in competitor's kill switch (per-host keys in the per-host reference), plus the exclusion of any other web-capable MCP servers the detect phase found — Pi sets their `enabled` key to `false`; Codex, lacking a per-server kill switch, refuses the tier instead; Pi's extension path additionally refuses when a web-capable `packages`/`extensions` source is listed in settings.json (no per-package kill switch exists) |
+| Forced (exclusion) | The built-in competitor's kill switch (per-host keys in the per-host reference), plus the exclusion of any other web-capable MCP servers the detect phase found — Pi sets their `enabled` key to `false`; Claude Code appends server-level `mcp__<server>` deny rules to `permissions.deny` (merging with the user's own entries); Codex, lacking a per-server kill switch, refuses the tier instead; Pi's extension path additionally refuses when a web-capable `packages`/`extensions` source is listed in settings.json (no per-package kill switch exists) |
 | Forced (de-facto) | Nothing beyond the Optional artifacts — no competitor exists |
-| Off | Codex writes the capability's raw tool name into the server entry's `disabled_tools` (host-native: the tool leaves the model's context; the user's own entries in that array are kept); the other MCP entry writes the capability's false-only server-side switch instead (`DEEPSEEK_ENABLE_SEARCH` / `DEEPSEEK_ENABLE_FETCH`); Pi's extension path writes the same switches into the `deepseekWebRetrieval` settings namespace the extension reads at load; both capabilities off refuses to install |
+| Off | Codex writes the capability's raw tool name into the server entry's `disabled_tools` (host-native: the tool leaves the model's context; the user's own entries in that array are kept); Claude Code appends the capability's full tool id (`mcp__deepseek__*`) to `permissions.deny`, the same host-native removal; the other MCP entry writes the capability's false-only server-side switch instead (`DEEPSEEK_ENABLE_SEARCH` / `DEEPSEEK_ENABLE_FETCH`); Pi's extension path writes the same switches into the `deepseekWebRetrieval` settings namespace the extension reads at load; both capabilities off refuses to install |
 
 OpenCode additionally appends `permissions` allow entries for exactly the tools it
 registers (`websearch`, `deepseek_fetch`, and `webfetch` when fetch is forced), merged
@@ -184,18 +186,19 @@ into any existing `permissions` array rather than replacing it.
   comments and formatting in `opencode.jsonc` and Pi's `mcp.json` survive apply and
   uninstall; TOML edits go through `smol-toml` and drop comments, which the plan reports
   as a note. The hand-written JSONC stripper that predated this lived in `scripts/jsonc.ts`.
-- Install state lives per host and scope (global under
-  `~/.config/deepseek-web-retrieval/`, project under `.deepseek-web-retrieval/`); it
-  records snapshots, appended entries, created files, and created path prefixes — never
-  full file contents, so other servers' secrets stay out of the state file.
+- Install records live per host and scope (global under
+  `~/.config/deepseek-web-retrieval/`, project under `.deepseek-web-retrieval/`); they
+  record snapshots, appended entries, created files, and created path prefixes — never
+  full file contents, so other servers' secrets stay out of the install record.
 - Re-applying over a previous init inherits the original snapshots instead of recording
   the installer's own output as the "previous" value. Pi forced re-inits keep their
   competitor-disable ops even when those servers are already disabled, so orphan
   reverts cannot re-enable a still-excluded competitor.
 - Verify is file-level: after apply it re-reads each written file and asserts every op
   holds (set values in place, appended entries present, rules block present). Higher
-  layers would be a plan-time detect concern, and none of the three shipped hosts
-  documents a layer above user config, so there is nothing to check there yet.
+  layers are a plan-time detect concern; Claude Code documents one (managed policy), and
+  the claude-code module reports an existing managed-settings.json instead of failing
+  silently. The other shipped hosts document no layer above user config.
 - Only a bare `--apply` enables writes; assigning a value such as `--apply=false`
   is a usage error and writes nothing.
 - `--pin` is opt-in version pinning: the ref written into host config gets the
@@ -224,7 +227,7 @@ host-side tool filtering.
 
 ## Hosts without an installer story
 
-Claude Code, Cursor, Devin, GitHub Copilot, and Cline still have no
+Cursor, Devin, GitHub Copilot, and Cline still have no
 host module; their artifacts (from the tier-to-artifact mapping) remain hand-edited
 config until a module lands here. OpenCode's `opencode plugin add` remains available but
 cannot pass options or manage snapshots; `init` supersedes it for tiered installs.

package/docs/hosts.jsonc

@@ -102,11 +102,15 @@
       "nativeSearchProvider": false,
       "nativeFetchOverride": false,
       "paths": ["mcp"],
-      "status": "no-adapter-yet",
+      "status": "supported",
       "control": {
         "search": { "optional": "yes", "preferred": "yes", "forced": "exclusion", "key": "`permissions.deny: [\"WebSearch\"]` removes the tool from context" },
         "fetch": { "optional": "yes", "preferred": "yes", "forced": "exclusion", "key": "`permissions.deny: [\"WebFetch\"]`, or `CLAUDE_CODE_DISABLE_WEB_FETCH=1`" }
       },
+      "adapter": "src/mcp",
+      "installer": "src/installer/hosts/claude-code",
+      "guide": "docs/agents/claude-code.md",
+      "e2eScenario": "claude-code"
     },
     {
       "name": "cursor",

package/docs/integration.md

@@ -17,7 +17,7 @@ ship built-in web tools. MCP tools can add equivalent tools, but do not replace
 | Native tool / fetch override | No | Yes | Host tool API | OpenCode v2 adapter |
 | Custom tool plugin | Yes | Yes | Host plugin API | Cline CLI/SDK; no adapter yet |
 | Extension API | Yes | Yes | Host extension API | Pi adapter (`src/pi/`) |
-| MCP server | Yes | Yes | Host MCP client | Shipped (`src/mcp/`; Pi and Codex guides) |
+| MCP server | Yes | Yes | Host MCP client | Shipped (`src/mcp/`; Pi, Codex, and Claude Code guides) |
 | CLI/HTTP wrapper | Yes | Yes | Host can call external tools | Not shipped |
 
 MCP is a protocol, not an agent. It is one possible transport for hosts that support MCP
@@ -35,7 +35,7 @@ Rows are sorted with open-source hosts first, then by host name alphabetically.
 | Codex | 0.163.0 | Yes (Apache-2.0) | No | No | MCP server | Supported |
 | OpenCode | 2.0.32 | Yes (MIT) | Yes | Yes | native websearch provider or native tool/fetch override | Supported |
 | Pi | 1.3.0 | Yes (MIT) | No | No | extension API or MCP server | Supported |
-| Claude Code | 2.1.303 | No | No | No | MCP server | No adapter yet |
+| Claude Code | 2.1.303 | No | No | No | MCP server | Supported |
 | Cursor | 2026.10.08 | No | No | No | MCP server | No adapter yet |
 | Devin | 3000.11.92 | No | No | No | MCP server | No adapter yet |
 | GitHub Copilot | 1.0.98 | No | No | No | MCP server | No adapter yet |
@@ -48,7 +48,7 @@ Codex are Apache-2.0; OpenCode and Pi are MIT. Claude Code and
 Cursor are proprietary. GitHub Copilot CLI and Devin CLI publish installers and docs, not
 source code, under proprietary terms.
 
-OpenCode, Pi, and Codex have supported setup guides and installer host modules. The
+OpenCode, Pi, Codex, and Claude Code have supported setup guides and installer host modules. The
 MCP server in `src/mcp/` provides a possible stdio path for the remaining hosts, but
 protocol compatibility alone does not establish a tested host setup. For those rows,
 `No adapter yet` means no supported host-specific adapter or setup guide is shipped.
@@ -66,8 +66,10 @@ the details: built-in web tools and their kill switches, MCP registration, and r
 - **OpenCode v2** — Uses OpenCode's native plugin API and
   exposes both a websearch provider and a fetch tool/override. See
   [OpenCode v2](agents/opencode-v2.md).
-- **Claude Code** — Ships built-in `WebSearch` and `WebFetch` tools. See
-  [Claude Code](research/control-matrix.md#claude-code).
+- **Claude Code** — Ships built-in `WebSearch` and `WebFetch` tools. Supported through
+  the MCP server; see
+  [Claude Code](agents/claude-code.md) and
+  [Claude Code in the per-host reference](research/control-matrix.md#claude-code).
 - **Codex** — Ships a built-in `web_search` tool. Supported through the MCP server; see
   [Codex](agents/codex.md) and [Codex in the per-host reference](research/control-matrix.md#codex).
 - **Cursor** — Uses the same `mcp.json` servers as the editor; ships built-in web search
@@ -119,7 +121,8 @@ Code importing the core's removed `formatFetchContent` helper must migrate to
 ## Available paths and future hosts
 
 - **MCP server** — shipped in `src/mcp/` (the fallback path in the [Pi](agents/pi.md) guide
-  and the path in the [Codex](agents/codex.md) guide); the broadest route for hosts that
+  and the path in the [Codex](agents/codex.md) and
+  [Claude Code](agents/claude-code.md) guides); the broadest route for hosts that
   support MCP tools. Protocol compatibility across these hosts is researched in
   [mcp-compatibility.md](research/mcp-compatibility.md).
 - **Native extension adapters** — the Pi extension adapter ships in `src/pi/`; a host whose