deepseek-web-retrieval 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -1,6 +1,28 @@
 # Changelog
 
-All notable changes to this project are documented here, with one sentence per item.
+All notable changes to this project are documented here, one sentence per item.
+
+## 0.8.0
+
+- Add Claude Code as a supported host: an MCP-only integration registered in `.mcp.json` (project scope) or `~/.claude.json` (user scope), with a full installer host module (plan/apply/uninstall, both scopes), a `docs/agents/claude-code.md` guide, a version probe with drift note, and managed-policy detection that reports a `managed-settings.json` layer outranking the install.
+- Route Claude Code tiers through its own settings files: forced capabilities deny the built-in `WebSearch`/`WebFetch` via `permissions.deny` in `.claude/settings.json` or `~/.claude/settings.json` (merged with the user's entries), off capabilities deny the full `mcp__deepseek__*` tool ids, and preferred writes a rules block into `CLAUDE.md`; web-capable competitor servers are excluded under forced via server-level `mcp__<server>` deny rules instead of refusing the tier.
+- Add a billed `claude-code` Docker e2e scenario that runs headless `claude -p` prompts with DeepSeek as the LLM over its Anthropic-compatible endpoint (single key for both legs) and asserts the deny-based kill switch keeps the built-in tools out of the session, plus installer/reinit coverage of the new host in the keyless scenarios.
+- Guard Pi's global config files with the shared-file ownership sidecar, and release claims before deleting the install record on uninstall, so two installs under different config homes can no longer claim the same `~/.pi/agent` file.
+- Run the Codex and Claude Code version probes through a shell so Windows npm `.cmd` shims launch and the drift check no longer silently skips on Windows.
+- Correct the research attribution for Claude Code's MCP `2026-07-28` default negotiation (v2 runtime from 2.1.274+, changelog bullet at 2.1.299 — not 2.1.296).
+- Restructure the README around a quickstart and a defaults table, moving the full configuration reference (knob classes, the complete file-key ↔ `DEEPSEEK_*` mapping, special semantics) to a new docs/configuration.md guide.
+- Generate the configuration guide's knob table from the config vocabulary itself (`bun run docs:matrix` regenerates it, `--check` fails CI on drift), so the documented key ↔ variable ↔ default mapping can no longer hand-drift from the code.
+
+## 0.7.0
+
+- Layer a shared config file (`$XDG_CONFIG_HOME/deepseek-web-retrieval/config.json`, camelCase keys) under the environment on every host, with the precedence `built-in defaults < shared file < DEEPSEEK_* environment < host-native config`; unknown and host-integration keys are warned about and ignored, and the API key stays out of the file.
+- Add a `config` command that prints every knob with its effective value and source (default, file, or environment — a count-derived `maxResults` is labeled `count`), replays shared-file problems, and verifies the key, config, and network end to end with `config --search "<query>"`.
+- Forward every `DEEPSEEK_*` option variable — not just the API key — in the Codex installer's `env_vars` entry, so shell-set knobs reach the stdio server without hand-editing `config.toml`.
+- Surface DeepSeek's `rerank_score`, `authority`, and `site_name` on search results in both text and structured output, accept an optional `original_question` on the MCP and Pi search tools (sent as `ori_question`), and add the `searchLocalization` deployment knob.
+- Couple `maxResults` to `count` when left unset — configuring only `count` was a silent no-op — and retry transient failures (408/425/429/5xx) twice by default instead of failing the billed call on the first attempt.
+- Resolve the shared config directory the Windows way on win32 (`%APPDATA%`, with an explicitly set `XDG_CONFIG_HOME` still winning), for the shared config file and the installer's global records alike.
+- Add `init --pin` to register the exact running CLI version (`deepseek-web-retrieval@<version>`) instead of the unpinned name, with package-identity comparisons that still match a pinned ref to its lineage.
+- `config` now warns and exits 1 when a `DEEPSEEK_*` variable is set but unusable (unknown name, non-numeric value, no-op switch value) instead of silently showing the default.
 
 ## 0.6.0
 

package/README.md

@@ -1,33 +1,52 @@
 # DeepSeek Web Retrieval
 
-**DeepSeek Search and Fetch for OpenCode, Pi, and Codex.**
+**DeepSeek Search and Fetch for OpenCode, Pi, Codex, and Claude Code.**
 
 Search the web and fetch pages as Markdown through
 [DeepSeek's APIs](https://api-docs.deepseek.com/guides/search), using a **native OpenCode
-plugin**, a **native Pi extension**, or **MCP for Codex**. All three share the same retrieval
-core, with results formatted for each host.
+plugin**, a **native Pi extension**, or **MCP for Codex and Claude Code**. All four share
+the same retrieval core, with results formatted for each host.
 
 This is an unofficial community project, not affiliated with DeepSeek or the supported
 host projects.
 
+Jump to: [Features](#features) · [Quickstart](#quickstart) · [Usage](#usage) ·
+[General behavior](#general-behavior) · [Configuration](#configuration) ·
+[Development](#development)
+
 ## Features
 
-- **One package, three hosts** — a native OpenCode v2 plugin, a native Pi extension,
-  and a stdio MCP server for Codex, all sharing one retrieval core
+- **One package, four hosts** — a native OpenCode v2 plugin, a native Pi extension,
+  and a stdio MCP server for Codex and Claude Code, all sharing one retrieval core
 - **Routing control per tool** — search and fetch are set independently to optional,
   preferred, forced, or off; the tier table in Usage explains each
 - **Review before anything is written** — `init` prints the full plan and writes only
   with `--apply`; uninstall restores from snapshots while preserving edits you made
   afterwards
 - **Knows the host's web landscape** — detects conflicting web tools and rules,
-  configures Pi's MCP fallback for direct tool exposure, and reports Codex version
-  drift
+  configures Pi's MCP fallback for direct tool exposure, and reports Codex and
+  Claude Code version drift
 - **Your key never enters a config file** — installs reference the environment
   (`${DEEPSEEK_API_KEY}` indirection or `env_vars`), so a project-scope install
   commits clean
 - **Fails loudly, never switches silently** — no fallback to another provider, and
   localhost/private URLs are blocked before a request leaves the machine
 
+## Quickstart
+
+Requires Node.js 20+ and npm, plus a DeepSeek API key with Search and Fetch access
+(retrieval is billed per successful request; the account needs balance).
+
+```bash
+export DEEPSEEK_API_KEY=sk-...
+# Preview the plan for your host — nothing is written yet:
+npx deepseek-web-retrieval init --host opencode --scope project --search forced --fetch preferred
+# Re-run with --apply to write it:
+npx deepseek-web-retrieval init --host opencode --scope project --search forced --fetch preferred --apply
+```
+
+For Pi, Codex, or Claude Code, other scopes, or finer routing control, see [Usage](#usage).
+
 ## Usage
 
 Choose your host:
@@ -37,23 +56,11 @@ Choose your host:
 | OpenCode v2 | Native plugin: search provider and Fetch tools | [OpenCode guide](docs/agents/opencode-v2.md) |
 | Pi | Native extension: Search and Fetch tools; MCP also available | [Pi guide](docs/agents/pi.md) |
 | Codex | MCP server over stdio, with readable text results | [Codex guide](docs/agents/codex.md) |
+| Claude Code | MCP server over stdio in `.mcp.json` or `~/.claude.json` | [Claude Code guide](docs/agents/claude-code.md) |
 
-The installer CLI requires Node.js 20+ and npm. Retrieval requires a DeepSeek API key
-with access to Search and Fetch and sufficient account balance. Set `DEEPSEEK_API_KEY`
-in the environment that launches your host; OpenCode can also use its stored DeepSeek key.
-
-Run the command for your host to preview a configuration:
-
-```bash
-# OpenCode: select DeepSeek as the search provider and prefer its Fetch tool.
-npx deepseek-web-retrieval init --host opencode --scope project --search forced --fetch preferred
-
-# Pi: use the native extension and prefer both tools.
-npx deepseek-web-retrieval init --host pi --scope project --search preferred --fetch preferred
-
-# Codex: register the MCP server and prefer both tools.
-npx deepseek-web-retrieval init --host codex --scope global --search preferred --fetch preferred
-```
+Set `DEEPSEEK_API_KEY` in the environment that launches your host; OpenCode can also
+use its stored DeepSeek key. Run `init` for your host to preview a configuration — the
+command shape is the quickstart's; each host guide shows its recommended tiers.
 
 `--search` and `--fetch` each pick a tier — how strongly the host steers toward the
 DeepSeek tool, chosen independently per capability:
@@ -75,12 +82,12 @@ Tiers: search=preferred, fetch=preferred
 
 Files:
   ~/.codex/config.toml
-    set mcp_servers.deepseek = {"command":"npx","args":["-y","deepseek-web-retrieval"],"env_vars":["DEEPSEEK_API_KEY"]} (was (absent))
+    set mcp_servers.deepseek = {"command":"npx","args":["-y","deepseek-web-retrieval"],"env_vars":["DEEPSEEK_API_KEY","DEEPSEEK_... (was (absent))
   ~/.codex/AGENTS.md
     upsert marked rules block
 
 Notes:
-  - Codex stdio children do not inherit the parent environment, so the entry forwards DEEPSEEK_API_KEY explicitly via env_vars; the key must be set in the shell that launches Codex.
+  - Codex stdio children do not inherit the parent environment, so the entry forwards DEEPSEEK_API_KEY and every DEEPSEEK_* option variable explicitly via env_vars; shell-set knobs reach the server without hand-editing config.toml (the shared config file works without any forwarding).
   - Rules block upserted in ~/.codex/AGENTS.md; Codex reads ~/.codex/AGENTS.md plus every AGENTS.md from the project root to the cwd.
   - Shared config ownership is recorded in ~/.codex/.config.toml.deepseek-web-retrieval.codex.owner.json; uninstall releases it. Keep this local metadata with the config.
 
@@ -91,14 +98,17 @@ Repeat your chosen command with `--apply` to write the plan. The host guides exp
 activation steps and per-host tier limits. Pi defaults to the extension path; add
 `--path mcp` to use its MCP fallback.
 
+Add `--pin` to register the exact version of the CLI you are running
+(`deepseek-web-retrieval@<version>`) instead of the unpinned name, so hosts keep
+resolving that release rather than every latest publish. The trade-off is no
+auto-updates: re-run `init --pin` from a newer CLI to move the pin.
+
 Other stdio MCP hosts may use the server, but the supported setup guides and installer
-currently cover the three hosts above. See the [integration model](docs/integration.md)
-for tested versions and the [control tiers](docs/research/control-matrix.md) for routing
-limits. For an existing installation, follow the
+currently cover the four hosts above. See the [integration model](docs/integration.md)
+for tested versions and the [control tiers](docs/research/control-matrix.md) for
+routing limits. For an existing installation, follow the
 [upgrade instructions](docs/integration.md#upgrading-existing-installs).
 
-For shared search, fetch, retry, and privacy behavior, see below.
-
 ## General behavior
 
 What this adapter layer adds on top of the
@@ -106,44 +116,55 @@ What this adapter layer adds on top of the
 own capabilities (Markdown-only output, no JavaScript rendering, no private networks or
 binary files, per-request billing) are documented there.
 
+| Default | Value | Knob |
+| --- | --- | --- |
+| Results per search | 10 | `count` |
+| Fetch output cap | 16,000 characters | `fetchMaxChars` |
+| Search summary cap | 1,200 characters | `maxSummaryChars` |
+| Request timeout, body read included | 30 s | `searchTimeoutMs` / `fetchTimeoutMs` |
+| Transient retries | 2 (range 0–5) | `maxRetries` |
+
 ### Search
 
-- Requests summaries only (`need_content: false`, `summary` falling back to `snippet`);
-  full page content never enters the results.
-- Returns at most ten results by default (matching the API's `count` default and the
-  industry norm for AI-native search APIs), deduplicating URLs.
-- Optional `rerank_score` and `authority` thresholds are off by default — the default
-  returns exactly what DeepSeek ranked, including results without a score;
-  when a positive threshold is set, results below it (or without a score to
-  compare) are dropped.
-- Builds `blockedDomains`, `includeDomains`, and `language` into query operators and
+- Requests summaries only (`need_content: false`, falling back from `summary` to
+  `snippet`); full page content never enters the results.
+- Deduplicates URLs; an empty result set is normal, not an error.
+- Builds `blockedDomains`, `includeDomains`, and `language` into query operators, and
   rejects the final query locally when it exceeds the API's 128-character limit.
-- An empty result set is normal and is not an error.
+- Optional `rerank_score` and `authority` thresholds are off by default — the default
+  returns exactly what DeepSeek ranked. A positive threshold drops results below it.
+  A missing `rerank_score` is dropped too; an unknown `authority` stays unless
+  `allowUnknownAuthority` is set to false.
+- On the paths where this package defines the search tool's inputs (the MCP server and
+  the Pi extension), the tool accepts an optional `original_question`: the user's
+  question in their own words. It is forwarded as DeepSeek's `ori_question`, trimmed
+  and truncated to 128 characters; on the Pi extension, a blank input falls back to the
+  most recent user message in the session.
 
 ### Fetch
 
-- Output is capped at 16,000 characters by default, including the title; a
-  `[content truncated]` marker is added when the limit leaves room for it.
+- Output is capped per the table above, title included; a `[content truncated]` marker
+  is added when the limit leaves room for it.
 - A page that already opens with its title as a top-level heading does not get a
   duplicate title.
-- Responses larger than 5 MiB are rejected before parsing; URLs must be absolute
-  `http://` or `https://`, credential-free, and at most 8,192 characters.
+- URLs must be absolute `http://` or `https://`, credential-free, and at most 8,192
+  characters; responses larger than 5 MiB are rejected before parsing.
 - `format: "text"` and `format: "html"` are rejected rather than misrepresented.
 - Allowed/blocked domain lists and private-host blocking are enforced on the client,
   before a request leaves the machine.
 
 ### Timeouts and retries
 
-Request timeouts include reading the response body. Retries are disabled by default;
-when enabled, retryable responses are 408, 425, 429, and 5xx, and `Retry-After` is honored
-up to 10 seconds. Other failures, including 401, timeouts, and network errors, fail
+Request timeouts include reading the response body. Transient failures are retried per
+the table; retryable responses are 408, 425, 429, and 5xx, and `Retry-After` is honored
+up to 10 seconds. Other failures — including 401, timeouts, and network errors — fail
 without retrying.
 
 ### No automatic fallback
 
-If no API key is available, Search and Fetch fail. If DeepSeek is unavailable, returns an
-error, or times out, the request fails. The tool does not silently switch to another search
-provider or fetch implementation.
+If no API key is available, Search and Fetch fail. If DeepSeek is unavailable, returns
+an error, or times out, the request fails. The tool does not silently switch to another
+search provider or fetch implementation.
 
 ### Privacy and cost
 
@@ -151,6 +172,46 @@ Queries and URLs are sent to `https://api.deepseek.com`; the API key is sent onl
 Bearer token to DeepSeek and to nothing else. Retrieval is billed per successful request —
 see the official docs for pricing and rate limits before enabling a team deployment.
 
+## Configuration
+
+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 shared file works on every host and takes camelCase keys:
+`$XDG_CONFIG_HOME/deepseek-web-retrieval/config.json` — by default
+`~/.config/deepseek-web-retrieval/config.json` on Linux and macOS and
+`%APPDATA%\deepseek-web-retrieval\config.json` on Windows.
+
+```json
+{
+  "count": 20,
+  "blockedDomains": ["pinterest.com"],
+  "language": "zh",
+  "searchLocalization": "203.0.113.7"
+}
+```
+
+Unknown keys and host-integration keys are warned about on stderr and ignored. The API
+key does not go in the file — it keeps its existing channels (`DEEPSEEK_API_KEY` in the
+environment, or OpenCode's stored credential).
+
+Which layer to set for a knob, the full file-key ↔ `DEEPSEEK_*` mapping, per-knob
+defaults, and special semantics live in the [configuration guide](docs/configuration.md).
+Per-host mechanics — how the environment reaches a stdio server, each host's output caps
+and deadlines — live in the host guides: [Codex](docs/agents/codex.md),
+[Claude Code](docs/agents/claude-code.md),
+[Pi](docs/agents/pi.md), [OpenCode](docs/agents/opencode-v2.md).
+
+To see what actually resolves, run `npx deepseek-web-retrieval config`: every knob
+printed with its value and its source (`default`, `file`, or `env`). Problems in the
+file or in `DEEPSEEK_*` variables are replayed as visible warnings, and it exits 1 when
+there are any — so it doubles as a dotfile CI check. `npx deepseek-web-retrieval config
+--search "<query>"` runs one billed search through the effective configuration to verify
+the key, config, and network end to end.
+
 ## Development
 
 ```bash
@@ -162,10 +223,9 @@ Use `bun run lint:fix` to apply Biome's safe lint fixes and formatting. See
 [CONTRIBUTING.md](CONTRIBUTING.md) for development checks, e2e scenarios, and
 [automated tag releases](CONTRIBUTING.md#automated-releases).
 
-The test suite mocks the DeepSeek HTTP API and the OpenCode and Pi host APIs, and drives the
-MCP server with SDK clients pinned to each supported protocol revision. Real API calls
+The test suite mocks the DeepSeek API and the OpenCode and Pi host APIs; real API calls
 require a funded DeepSeek account. Shared retrieval logic lives in `src/core/`; adapters
-live in `src/<agent>/` (the cross-host MCP server lives in `src/mcp/`). Adapter docs live
+live in `src/<agent>/` (the cross-host MCP server lives in `src/mcp/`), with adapter docs
 in `docs/agents/<agent>.md`.
 
 ## Prior art