deepseek-web-retrieval 0.2.0 → 0.3.0

package/docs/research/control-matrix.md

@@ -0,0 +1,257 @@
+# Control levels across hosts
+
+This note answers one question: for each host in the [support matrix](../integration.md), how
+strongly can a user steer when the DeepSeek tools are called — optionally available,
+preferentially used, or forcibly routed — independently for search and fetch? It is also
+the per-host reference for setup facts: MCP registration, rules files, built-in web
+competitors, and their kill switches. [integration.md](../integration.md) keeps the mechanism
+taxonomy and host-support matrix; [mcp-compatibility.md](mcp-compatibility.md) keeps the
+protocol research and its evidence.
+
+**Research baseline:** 2026-10-20, using the same version locks as
+[hosts.jsonc](../hosts.jsonc), the single source of truth for host facts. Open-source rows are
+verified at exact git tags, npm tarballs, or binary analysis; proprietary rows from official
+docs and changelogs at the locked versions. Version mentions inside the per-host sections
+and the generated `key` strings are research-provenance anchors verified at the lock, not
+restatements of it; they are re-verified on a baseline bump (see the drift list at the end).
+The matrix below is generated — edit
+hosts.jsonc, then run `bun run docs:matrix`.
+
+## Tiers
+
+| Tier | Meaning | Determinism |
+| --- | --- | --- |
+| Optional | Tools are declared to the model with no preference guidance; the model picks freely among available tools. | None |
+| Preferred | Prompt-level rules (instruction files, system-prompt additions) steer the model toward the tools. | Probabilistic |
+| Forced | Routing is deterministic **relative to the built-in competitor**; other web-capable MCP servers or a higher configuration layer can still break it (reading notes below). Three flavors: **replacement** (the built-in tool's implementation is swapped), **exclusion** (the built-in competitor is denied or disabled so the DeepSeek path is the only one), **de-facto** (the host ships no built-in web tool). | Deterministic (conditional) |
+
+## Matrix
+
+<!-- generated: control-matrix — edit docs/hosts.jsonc, then run `bun run docs:matrix` -->
+
+| Host | Capability | Optional | Preferred | Forced | Mechanism |
+| --- | --- | --- | --- | --- | --- |
+| Cline | Search | Yes | Yes | Yes | De-facto — no built-in web-search tool at 0.0.13 (binary-verified) |
+| Cline | Fetch | Yes | Yes | Yes | Exclusion — `disabledTools` in `~/.cline/data/settings/global-settings.json` |
+| Codex | Search | Yes | Yes | Yes | Exclusion — `web_search = "disabled"` (top-level config.toml) |
+| Codex | Fetch | Yes | Yes | Yes | De-facto — no built-in fetch tool at 0.163.0 |
+| OpenCode | Search | n/a | n/a | Yes | Replacement — `websearch.provider: "deepseek"` or plugin `setDefaultWebsearch` |
+| OpenCode | Fetch | Yes | Yes | Yes | Replacement — `fetchOverrideWebfetch: true` |
+| Pi | Search | Yes | Yes | Yes | De-facto — no built-in web tool at 1.3.0 (source-verified) |
+| Pi | Fetch | Yes | Yes | Yes | De-facto — no built-in web tool at 1.3.0 (source-verified) |
+| Claude Code | Search | Yes | Yes | Yes | Exclusion — `permissions.deny: ["WebSearch"]` removes the tool from context |
+| Claude Code | Fetch | Yes | Yes | Yes | Exclusion — `permissions.deny: ["WebFetch"]`, or `CLAUDE_CODE_DISABLE_WEB_FETCH=1` |
+| Cursor | Search | Yes | Yes | No | — |
+| Cursor | Fetch | Yes | Yes | Yes | Exclusion — `permissions.deny: ["WebFetch(*)"]` |
+| Devin | Search | Yes | Yes | Yes | Exclusion — `disabled_tools` / `permissions.deny` in config.json |
+| Devin | Fetch | Yes | Yes | Yes | Exclusion — `disabled_tools` / `permissions.deny` in config.json |
+| GitHub Copilot | Search | Yes | Yes | Yes | Exclusion — `githubMcpTools` settings (competitor ships via the bundled GitHub MCP server) |
+| GitHub Copilot | Fetch | Yes | Yes | Yes | Exclusion — `--deny-tool web_fetch` / `--excluded-tools` (session flags) |
+
+<!-- /generated: control-matrix -->
+
+Reading notes:
+
+- `n/a` marks a structurally unreachable tier, not missing research: OpenCode's search
+  provider is host-level config, not a model-selectable tool, so the model never chooses
+  between engines — the only choice is replacement on or off.
+- A `De-facto` Forced flavor needs no config: the host ships no built-in competitor, so the
+  registered tools are the only web path.
+- Cursor's search row is the one Forced-tier gap in the matrix: no documented deny token
+  exists for its built-in web search.
+- An `Exclusion` flavor forces routing **relative to the built-in competitor only**. If
+  other web-capable MCP servers are already registered, they stay on the field and
+  routing is not forced until they are excluded too; higher configuration layers
+  (managed, enterprise, system) can also outrank the kill switch. Install-time handling
+  of both conditions is specified in the
+  [installer design](../design/installer-design.md).
+
+## Per-host reference
+
+One section per host, in hosts.jsonc order. Each carries what an install needs beyond the
+matrix: the built-in competitors, their kill switches, how the MCP server is registered,
+and which rules files steer preference. The `init` CLI implements these tiers for
+OpenCode, Pi, and Codex (see [installer design](../design/installer-design.md)). Config
+paths imply the available scopes; keys locked to a single scope are enumerated in the
+[installer design](../design/installer-design.md#scope).
+
+### Cline
+
+- **Positioning** — VSCode-extension agent with an experimental lightweight CLI (`clite`,
+  built on the Cline SDKs). Apache-2.0. MCP plus CLI/SDK custom tools; neither replaces the
+  built-in `fetch_web_content`. Current docs.cline.bot describes the newer 3.x `cline`
+  binary — the lock is 0.0.13 `clite`, and everything here is verified against that binary.
+- **Built-in web tools** — `fetch_web_content` (fetch a URL and analyze it with a prompt);
+  no built-in web search (the binary's `web_search` strings are Bedrock provider tool
+  versions). Kill switch: `"disabledTools": ["fetch_web_content"]` in
+  `~/.cline/data/settings/global-settings.json` (path overridable via
+  `CLINE_GLOBAL_SETTINGS_PATH`); a disabled tool is dropped from the available set.
+  `--yolo` mode also deactivates web fetch.
+- **MCP registration** — `~/.cline/settings/cline_mcp_settings.json`
+  (`CLINE_MCP_SETTINGS_PATH`), written by the `clite mcp` wizard in a nested form:
+  `mcpServers.<name>.transport` with `type` (`stdio` | `sse` | `streamableHttp`) plus
+  `command`/`args`/`env`, `disabled`, and `autoApprove`. Negotiates `2024-11-05` — the
+  protocol floor of the matrix; treat it as text-content-blocks-only.
+- **Rules** — `.clinerules` (file or directory) and `.cline/rules/` plus `AGENTS.md` at
+  project scope; `~/.cline/rules` and `~/Documents/Cline/Rules` at user scope — all
+  verified inside the 0.0.13 binary.
+
+### Codex
+
+- **Positioning** — OpenAI's official Rust CLI. Apache-2.0. MCP is the only integration
+  path.
+- **Built-in web tools** — a native Responses `web_search` tool. The default mode is
+  `cached` (an OpenAI-maintained index, no external web access — the competitor exists
+  silently by default); `live` requires opt-in (`--search`, `web_search = "live"`, or a
+  full-access sandbox). No built-in fetch tool. Kill switch: top-level
+  `web_search = "disabled"` in `~/.codex/config.toml`. Trap: the `[tools] web_search =
+  <bool>` form parses but discards the value at 0.163.0 — a silent no-op
+  ([config source at rust-v0.163.0](https://github.com/openai/codex/blob/rust-v0.163.0/codex-rs/config/src/config_toml.rs)).
+- **MCP registration** — `~/.codex/config.toml` `[mcp_servers.<name>]`: stdio
+  `command`/`args`/`env`/`env_vars`; `startup_timeout_sec` (10 s), `tool_timeout_sec`
+  (60 s); `enabled_tools`/`disabled_tools`, per-tool approval modes, and output limits.
+  stdio children do not inherit the parent environment (only `HOME`, `PATH`, and explicit
+  `env`), so `DEEPSEEK_API_KEY` must be passed explicitly. When a tool result has
+  `structuredContent`, Codex replaces the content blocks with the serialized JSON. No SSE.
+- **Rules** — `~/.codex/AGENTS.md` (with `AGENTS.override.md` preferred) at user scope;
+  every `AGENTS.md` from the project root down to the cwd, concatenated root→cwd.
+  Extensible via `project_doc_fallback_filenames` and `developer_instructions`
+  ([agents_md.rs at rust-v0.163.0](https://github.com/openai/codex/blob/rust-v0.163.0/codex-rs/core/src/agents_md.rs)).
+
+### OpenCode
+
+- **Positioning** — the only host with both a native websearch provider and a native fetch
+  override; the shipped adapter uses them, not MCP. See [OpenCode v2](../agents/opencode-v2.md).
+- **Built-in web tools** — `websearch` (bundled providers: exa, firecrawl, parallel,
+  tavily, tinyfish, or `"random"`) and `webfetch`. `"websearch": false` removes the search
+  tool from model requests entirely; `webfetch` has no disable config key at 2.0.32 — the
+  deterministic paths are a permissions deny (`action: "webfetch"`) or a plugin
+  tool-transform removal, the latter being what `fetchOverrideWebfetch` does.
+- **MCP registration** — out of scope for this host: the shipped path is the plugin
+  adapter, and OpenCode's MCP support is not part of it.
+- **Rules** — `AGENTS.md` only (no CLAUDE.md fallback in v2): global
+  `~/.config/opencode/AGENTS.md`, then project files from the workspace toward home,
+  nested files injected when the agent reads into that subtree. The `instructions` config
+  key adds files, globs, or URLs ([docs](https://opencode.ai/v2/docs/instructions)).
+
+### Pi
+
+- **Positioning** — minimal, fully customizable agent (earendil-works). MIT. MCP server
+  plus a TypeScript extension API. See [Pi](../agents/pi.md).
+- **Built-in web tools** — none at 1.3.0. The built-in set is exactly `bash, edit, find,
+  grep, ls, powershell, read, write` (default-active: `read, bash, edit, write`); web
+  search/fetch arrive via MCP or extensions
+  ([tools index at v1.3.0](https://github.com/earendil-works/pi/blob/v1.3.0/packages/coding-agent/src/core/tools/index.ts)).
+- **MCP registration** — `~/.pi/agent/mcp.json` or `.pi/mcp.json`: stdio
+  `command`/`args`/`env`/`cwd`, HTTP `url`/`headers`, plus `timeout`, `enabled`,
+  `exposure`. MCP tools are hidden from the model by default
+  (`exposure: "codemode"`); `"exposure": "direct"` declares them like built-ins — the
+  prerequisite for every tier. SSE is rejected. Text results over 20 KB are
+  middle-truncated with the full text saved to a file, and the per-request default
+  timeout is 60 s. Pi is content-first for the model, with a `structuredContent`
+  fallback used only when a result has no content blocks — the one open-source host that
+  touches `structuredContent` at all — and a re-declared (not validated) tool
+  `outputSchema`.
+- **Rules** — `AGENTS.md`/`CLAUDE.md` context files from the agent dir, the working
+  directory, and its parents; `SYSTEM.md` replaces the system prompt and `APPEND_SYSTEM.md`
+  adds to it; extensions can replace the whole prompt via `before_agent_start`
+  ([configuration.md at v1.3.0](https://github.com/earendil-works/pi/blob/v1.3.0/packages/coding-agent/docs/configuration.md)).
+
+### Claude Code
+
+- **Positioning** — Anthropic's official CLI. Proprietary. MCP adds tools; built-ins are
+  not replaceable.
+- **Built-in web tools** — `WebSearch` and `WebFetch`. Kill switch: bare deny rules —
+  `"permissions": {"deny": ["WebSearch", "WebFetch"]}` — remove the tools from the model's
+  context entirely; deny outranks allow at every settings level and cannot be carved out.
+  `--disallowedTools` is the flag form. `CLAUDE_CODE_DISABLE_WEB_FETCH=1` (2.1.285+) kills
+  WebFetch only; there is no env equivalent for WebSearch
+  ([tools](https://code.claude.com/docs/en/tools),
+  [permissions](https://code.claude.com/docs/en/permissions)).
+- **MCP registration** — `.mcp.json` (`mcpServers` with `command`/`args`/`env`, or
+  `type: "http"` + `url`); `${VAR}` expansion in `command`/`args`/`env`/`url`/`headers`.
+  Tool permission rules use `mcp__<server>__<tool>`. Tool descriptions are capped at 4,096
+  chars (2.1.296+) and tool output at 25k tokens by default (`MAX_MCP_OUTPUT_TOKENS`),
+  with oversized text saved to a file; 16 MiB message cap on HTTP transports.
+- **Rules** — `CLAUDE.md` hierarchy (managed → user `~/.claude/CLAUDE.md` → project →
+  `CLAUDE.local.md`) with `@import`; `AGENTS.md` is read instead only when no CLAUDE.md
+  exists anywhere above the cwd (since 2.1.277)
+  ([memory](https://code.claude.com/docs/en/memory)).
+
+### Cursor
+
+- **Positioning** — AI-first editor plus a same-family CLI. Proprietary. MCP is the CLI
+  path.
+- **Built-in web tools** — web search and `WebFetch`. Fetch kill switch:
+  `"permissions.deny": ["WebFetch(*)"]` in `~/.cursor/cli-config.json` (global) or
+  `.cursor/cli.json` (project — only `permissions` is project-configurable); deny wins
+  over allow. Web search has no documented deny token; the only control is
+  `autoAcceptWebSearch` (a per-call approval prompt, not a hard deny). This is the
+  matrix's one Forced-tier gap
+  ([CLI permissions](https://cursor.com/docs/cli/reference/permissions),
+  [changelog](https://cursor.com/docs/cli/changelog)).
+- **MCP registration** — the same `mcp.json` servers as the editor (`.cursor/mcp.json` or
+  `~/.cursor/mcp.json`): `command`/`args`/`env` for stdio, `url`/`headers` for remote;
+  `${env:NAME}` interpolation. MCP tools prompt for approval; `--approve-mcps` bypasses,
+  and global-scope servers have been auto-approved since April 2026.
+- **Rules** — `.cursor/rules/*.mdc` (with `description`/`globs`/`alwaysApply` frontmatter —
+  a plain `.md` file there is ignored), `AGENTS.md` at the root and in subdirectories, and
+  `CLAUDE.md`; "The CLI agent supports the same rules system as the editor"
+  ([CLI using](https://cursor.com/docs/cli/using)).
+
+### Devin
+
+- **Positioning** — Cognition's autonomous-agent CLI. Proprietary. Plugins bundle skills,
+  rules, hooks, and MCP servers — not arbitrary custom tools — so MCP is the tool path.
+- **Built-in web tools** — `web_search` (v2026.5.6-1) and `webfetch` (v2026.5.26-0). Kill
+  switch: `"disabled_tools": ["webfetch", "web_search"]` in user `config.json`, and
+  `web_search` is accepted as a tool name in `permissions.deny`/`ask`/`allow` (both
+  changelog-documented at v3000.10.21, not yet on the reference pages); PreToolUse hooks
+  block calls by exiting with code 2; an enterprise "Enable Web Search" team setting
+  exists ([changelog](https://docs.devin.ai/cli/changelog)).
+- **MCP registration** — `.devin/mcp_config.local.json` (default),
+  `.devin/mcp_config.json`, or `~/.config/devin/mcp_config.json`, all with the same
+  `mcpServers` shape; `devin mcp add <name> -- <cmd>` / `<URL>`. MCP tools prompt for
+  approval by default; `mcp__server__tool` allow/deny patterns in `permissions`.
+- **Rules** — `AGENTS.md` (root, nested, and global `~/.config/devin/AGENTS.md`),
+  `AGENTS.local.md`, `.devin/rules/*.md` with `trigger` frontmatter,
+  `.devin/global_rules.md`, and plugin-shipped rules; imports other tools' rules via
+  `read_config_from` ([rules](https://docs.devin.ai/cli/extensibility/rules)).
+
+### GitHub Copilot
+
+- **Positioning** — GitHub's official CLI. Proprietary. MCP servers, optionally bundled in
+  plugins.
+- **Built-in web tools** — `web_fetch` (since 0.0.374) and `web_search` via the bundled
+  GitHub MCP server (which exposes only that tool since 1.0.57). Kill switch, session
+  scoped: `--deny-tool web_fetch,web_search` or `--excluded-tools` — the docs' own example
+  for avoiding web search entirely; deny wins even under `--allow-all`. Persistent:
+  `web_search` via `githubMcpToolsets`/`githubMcpTools` settings, and
+  `network.allowOutbound: false` blocks fetch egress at the network layer; a persistent
+  key for the built-in `web_fetch` itself is unconfirmed at 1.0.98
+  ([allowing tools](https://docs.github.com/en/copilot/how-tos/copilot-cli/use-copilot-cli/allowing-tools),
+  [changelog](https://github.com/github/copilot-cli/blob/main/changelog.md)).
+- **MCP registration** — `~/.copilot/mcp-config.json` or project `.mcp.json`; stdio
+  entries use `"type": "local"` plus `command`/`args`/`env`; a per-server `tools` list
+  gates which tools are exposed — per-tool control at registration time.
+- **Rules** — `~/.copilot/copilot-instructions.md` (user),
+  `.github/copilot-instructions.md` (repo) and `.github/instructions/**/*.instructions.md`
+  (path-scoped via `applyTo` globs); `AGENTS.md`/`CLAUDE.md` discovery (changelog-dated
+  ≤1.0.86; `GEMINI.md` could not be dated to the lock);
+  `COPILOT_CUSTOM_INSTRUCTIONS_DIRS` adds directories
+  ([custom instructions](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-custom-instructions)).
+
+## Cross-cutting observations
+
+- **AGENTS.md is the de-facto rules standard.** Seven of the eight hosts read it
+  natively (Codex, Cline, Cursor, Devin, Copilot, Pi, OpenCode); Claude Code reads it as
+  a fallback. One rules file works nearly everywhere; the exception: OpenCode v2 has no
+  CLAUDE.md fallback.
+- **Replacement is exclusive to native extension points** — only OpenCode. Exclusion is
+  the general forced path on MCP hosts. The two structural limits: OpenCode search has no
+  middle tier, and Cursor search cannot be forced at all.
+- **Version drift to re-verify on the next baseline pass:** Cline's docs describe the 3.x
+  `cline` binary while the lock is 0.0.13 `clite`; Codex's config docs have moved and
+  describe a newer release; Copilot's `GEMINI.md` support could not be changelog-dated to
+  ≤1.0.98. Protocol-revision evidence for every host lives in
+  [mcp-compatibility.md](mcp-compatibility.md).

package/docs/{mcp-compatibility.md → research/mcp-compatibility.md}

@@ -1,18 +1,18 @@
 # MCP compatibility across hosts
 
-This note answers one question for the planned MCP server: do the hosts in the
-[support matrix](integration.md) speak the same MCP protocol standard? Short answer: they all
+This note answers one question for the shipped MCP server: do the hosts in the
+[support matrix](../integration.md) speak the same MCP protocol standard? Short answer: they all
 speak MCP, but not the same revision. MCP has split into two eras, hosts negotiate different
 revisions, and one dual-era server covers them all.
 
-The nine MCP-capable hosts in the matrix span **four different negotiated revisions**:
-`2024-11-05` (Cline), `2025-06-18` (Codex, Gemini), `2025-11-25` (Continue, Pi), and
+The seven MCP-capable hosts in the matrix span **four different negotiated revisions**:
+`2024-11-05` (Cline), `2025-06-18` (Codex), `2025-11-25` (Pi), and
 `2026-07-28` (Claude Code, Devin, GitHub Copilot) — plus Cursor, whose revision no primary
 source pins. OpenCode is out of scope here: its shipped integration is the
-[native plugin adapter](opencode-v2.md), not MCP.
+[native plugin adapter](../agents/opencode-v2.md), not MCP.
 
 **Research baseline:** 2026-10-19, using the same version locks as the host support matrix in
-[integration.md](integration.md). Claims are cited to primary sources: the MCP specification,
+[integration.md](../integration.md). Claims are cited to primary sources: the MCP specification,
 official host docs and changelogs, npm registry manifests, and host source code at the locked
 versions.
 
@@ -74,87 +74,28 @@ Two release lines of the official TypeScript SDK ([docs](https://github.com/mode
 
 ## What each host supports
 
-| Host | Version | Negotiated revision | Transports | Evidence |
-| --- | --- | --- | --- | --- |
-| Cline | 0.0.13 | `2024-11-05` | stdio, Streamable HTTP, SSE | Custom client (no official SDK); `protocolVersion "2024-11-05"` extracted from the 0.0.13 platform binary; source repo not public |
-| Codex | 0.163.0 | `2025-06-18`; `mcp_2026_07_28` feature flag opts into `2026-07-28` | stdio, Streamable HTTP (no SSE) | Git tag `rust-v0.163.0`: rmcp 3.5.1 pinned; initialize sends `V_2025_06_18` |
-| Continue | 1.5.47 | `2025-11-25` | stdio, Streamable HTTP, SSE | 1.5.47 npm tarball: bundled TS SDK ≥ 1.24.1 (contains `2025-11-25` constants); no git tag exists |
-| Gemini | 0.64.0 | `2025-06-18` | stdio, Streamable HTTP, SSE | Git tag `v0.64.0`: `@modelcontextprotocol/sdk` 1.23.0 pinned in package.json |
-| Pi | 1.3.0 | `2025-11-25` | stdio, Streamable HTTP (SSE rejected) | Git tag `v1.3.0`: own `@earendil-works/pi-mcp` client, `LATEST_PROTOCOL_VERSION "2025-11-25"` |
-| Claude Code | 2.1.303 | `2026-07-28` by default (`MCP_PROTOCOL_NEGOTIATION=legacy` opt-out) | stdio, Streamable HTTP, SSE, ws | Changelog 2.1.296+: "negotiate MCP protocol version 2026-07-28 by default"; docs: TS SDK 2.0 runtime |
-| Cursor | 2026.10.08 | Unpinnable from primary sources (docs show ≥ `2025-06-18` features) | stdio, Streamable HTTP, SSE | Docs feature set only; no revision stated in docs or changelog |
-| Devin | 3000.11.92 | `2026-07-28` | stdio, Streamable HTTP (SSE fallback), SSE | Changelog for 3000.11.92 itself: "Support for MCP protocol revision 2026-07-28" |
-| GitHub Copilot | 1.0.98 | `2026-07-28` | stdio (`type: "local"`), Streamable HTTP, SSE | Changelog 1.0.81: "Ship MCP 2026-07-28 support to CLI, SDK, IDE, and in-memory clients" |
-
-Open-source rows are verified at the exact locked versions (git tag, npm tarball, or binary
-analysis); proprietary rows are verified from official docs and changelogs at the locked
-versions. All nine support stdio and Streamable HTTP; legacy SSE is never required (and Codex
-and Pi reject it).
-
-### Open-source hosts
-
-- **Cline** — Custom MCP client, no official SDK. Config at 0.0.13:
-  `~/.cline/settings/cline_mcp_settings.json` (override with `CLINE_MCP_SETTINGS_PATH`),
-  written by the `clite mcp` wizard in a nested form: `mcpServers.<name>.transport` with
-  `type` (`stdio` | `sse` | `streamableHttp`), `command`/`args`/`env` or `url`/`headers`, plus
-  `disabled` and `autoApprove`. Current docs describe a newer, flatter layout than the locked
-  binary. The client declares no capabilities and requests `2024-11-05` — the protocol floor
-  of the whole matrix; treat it as text-content-blocks-only.
-- **Codex** — Rust client on the official rmcp crate. Config: `~/.codex/config.toml`
-  `[mcp_servers.<name>]` — stdio `command`/`args`/`env`/`env_vars`; HTTP `url`,
-  `bearer_token_env_var`, `http_headers`; `startup_timeout_sec` (10s), `tool_timeout_sec`
-  (60s), `enabled_tools`/`disabled_tools`, per-tool approval modes and output limits.
-  **stdio children do not inherit the parent environment** — only `HOME`, `PATH`, and a few
-  system vars plus explicitly configured `env`, so `DEEPSEEK_API_KEY` must be passed
-  explicitly. When a tool result has `structuredContent`, Codex replaces the content blocks
-  with the serialized JSON. No SSE support.
-- **Continue** — Config: `~/.continue/config.yaml` `mcpServers` list — `name`, `type`
-  (`stdio` | `sse` | `streamable-http`), `command`/`args`/`env`/`cwd` or `url`/`apiKey`/
-  `requestOptions`; `${{ secrets.NAME }}` interpolation; headless mode fails if any MCP
-  server fails to connect. **Tool names are exposed raw, without a server prefix**, and
-  matching is first-found across servers — avoid generic names like `search`.
-  `structuredContent` is never read; content blocks are JSON-stringified for the model.
-- **Gemini** — Config: `mcpServers` in `~/.gemini/settings.json` or `.gemini/settings.json` —
-  `command`/`args`/`env`/`cwd`, or `url` with `type: "http" | "sse"` (at 0.64.0 a bare `url`
-  defaults to Streamable HTTP), `headers`, `timeout`, `includeTools`/`excludeTools`; `env`
-  values expand `$VAR`/`${VAR}`. Tools get an `mcp_{server}_{tool}` name truncated at 63
-  chars, and underscores in the server name break its FQN parsing — keep the server name
-  short and underscore-free. Reads only `content` blocks; `structuredContent` is ignored.
-- **Pi** — Config: `~/.pi/agent/mcp.json` or `.pi/mcp.json` — stdio `command`/`args`/`env`/
-  `cwd`, HTTP `url`/`headers`, plus `timeout`, `enabled`, `exposure`. **MCP tools are hidden
-  from the model by default (`exposure: "codemode"`) — set `exposure: "direct"`** so the
-  search/fetch tools are declared. SSE is explicitly rejected. Text results over 20 KB are
-  middle-truncated with the full text saved to a file. Pi is the one open-source host that
-  uses `structuredContent` and tool `outputSchema`.
-
-### Proprietary hosts
-
-All four locked versions happen to be the latest stable releases at the research date, so
-current docs and changelogs apply to them directly. Notes relevant to a two-tool DeepSeek
-search/fetch server:
-
-- **Claude Code** — [MCP docs](https://code.claude.com/docs/en/mcp),
-  [changelog](https://raw.githubusercontent.com/anthropics/claude-code/main/CHANGELOG.md).
-  Config: `.mcp.json` (`mcpServers` with `command`/`args`/`env`, or `type: "http"` + `url`).
-  Env expansion `${VAR}` works in `command`/`args`/`env`/`url`/`headers`. Tool permission
-  rules `mcp__<server>__<tool>`; tool descriptions capped at 4,096 chars (2.1.296+); tool
-  output capped at 25k tokens by default (`MAX_MCP_OUTPUT_TOKENS`), oversized text saved to a
-  file; 16 MiB message cap on HTTP transports.
-- **Cursor** — [MCP docs](https://cursor.com/docs/mcp),
-  [CLI MCP](https://cursor.com/docs/cli/mcp). Config: `.cursor/mcp.json` or
-  `~/.cursor/mcp.json`; `command`/`args`/`env` for stdio (docs mark `type` as required),
-  `url`/`headers` for remote; `${env:NAME}` interpolation. MCP tools need approval; the CLI
-  has `--approve-mcps`, global-scope servers have been auto-approved since April 2026.
-- **Devin** — [MCP config](https://docs.devin.ai/cli/extensibility/mcp/configuration),
-  [changelog](https://docs.devin.ai/cli/changelog). Config: `.devin/mcp_config.local.json`
-  (default), `.devin/mcp_config.json`, or `~/.config/devin/mcp_config.json`; same
-  `mcpServers` shape; `devin mcp add <name> -- <cmd>` / `<URL>`. MCP tools prompt for
-  approval by default, with `mcp__server__tool` allow/deny patterns in `permissions`.
-- **GitHub Copilot** — [MCP docs](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers),
-  [repo](https://github.com/github/copilot-cli). Config: `~/.copilot/mcp-config.json` or
-  project `.mcp.json`; stdio entries use `"type": "local"` plus `command`/`args`/`env`; a
-  per-server `tools` list gates which tools are exposed; runtime flags
-  `--allow-tool`/`--deny-tool` accept `MCP_SERVER_NAME(tool)`.
+Host versions are locked in [`docs/hosts.jsonc`](../hosts.jsonc), the single source of truth for
+host facts; each row below was verified against that lock on the research baseline.
+
+| Host | Negotiated revision | Transports | Evidence |
+| --- | --- | --- | --- |
+| Cline | `2024-11-05` | stdio, Streamable HTTP, SSE | Custom client (no official SDK); `protocolVersion "2024-11-05"` extracted from the platform binary; source repo not public |
+| Codex | `2025-06-18`; `mcp_2026_07_28` feature flag opts into `2026-07-28` | stdio, Streamable HTTP (no SSE) | Git tag `rust-v0.163.0`: rmcp 3.5.1 pinned; initialize sends `V_2025_06_18` |
+| Pi | `2025-11-25` | stdio, Streamable HTTP (SSE rejected) | Git tag: own `@earendil-works/pi-mcp` client, `LATEST_PROTOCOL_VERSION "2025-11-25"` |
+| Claude Code | `2026-07-28` by default (`MCP_PROTOCOL_NEGOTIATION=legacy` opt-out) | stdio, Streamable HTTP, SSE, ws | Changelog 2.1.296+: "negotiate MCP protocol version 2026-07-28 by default"; docs: TS SDK 2.0 runtime |
+| Cursor | Unpinnable from primary sources (docs show ≥ `2025-06-18` features) | stdio, Streamable HTTP, SSE | Docs feature set only; no revision stated in docs or changelog |
+| Devin | `2026-07-28` | stdio, Streamable HTTP (SSE fallback), SSE | Changelog for the locked release itself: "Support for MCP protocol revision 2026-07-28" |
+| GitHub Copilot | `2026-07-28` | stdio (`type: "local"`), Streamable HTTP, SSE | Changelog 1.0.81: "Ship MCP 2026-07-28 support to CLI, SDK, IDE, and in-memory clients" |
+
+All seven support stdio and Streamable HTTP; legacy SSE is never required (and Codex
+and Pi reject it). Verification methodology and provenance follow the
+[per-host reference](control-matrix.md#per-host-reference); the Evidence column cites per-row
+sources and Sources lists the file-level links.
+
+Registration paths, config shapes, approval surfaces, and per-host quirks live in the
+[per-host reference](control-matrix.md#per-host-reference) of the control-matrix note; they
+are setup facts, not protocol facts. The table above carries the protocol evidence, and
+source-level links follow in Sources.
 
 ## One server for all hosts
 
@@ -164,12 +105,14 @@ differences:
 
 1. **Tools only, text-first results.** Expose the retrieval as two tools via the `tools`
    capability; do not rely on resources, prompts, sampling, elicitation, or roots — the
-   hosts' client capabilities are inconsistent (Codex has elicitation only; Gemini and Pi
-   serve roots; Continue exposes nothing beyond tools and prompts). Always return readable
+   hosts' client capabilities are inconsistent (Codex has elicitation only; Pi serves
+   roots). Always return readable
    text in `content` blocks, and mirror the same data in `structuredContent` for
    `2025-06-18`+ clients — the spec's own backwards-compat SHOULD. This split matters in
-   practice: Codex *replaces* content with `structuredContent` when present, Gemini and
-   Continue *ignore* `structuredContent`, Pi and Cline read content only.
+   practice: Codex *replaces* content with `structuredContent` when present; Cline reads
+   text content only; Pi is
+   content-first, falling back to `structuredContent` only when a result has no content
+   blocks (verified in `tools.ts` at v1.3.0).
 2. **stdio is the universal transport.** Every host in the matrix launches stdio servers
    with the same conceptual JSON (`mcpServers` → `command`/`args`/`env`), differing only in
    file location and cosmetic field names. stdio needs no OAuth and no URL config, and the
@@ -185,15 +128,11 @@ differences:
    different `type` strings: `http`, `streamable-http`, `streamableHttp`), and OAuth 2.1
    resource-server behavior (RFC 9728 metadata) then applies; prefer pre-registered clients
    over the now-deprecated Dynamic Client Registration.
-5. **Host quirks to design around.** Name tools distinctly (`deepseek_web_search`,
-   `deepseek_fetch`): Continue exposes raw names with cross-server collisions, and Gemini
-   truncates the `mcp_{server}_{tool}` name at 63 chars. Pass the API key explicitly in
-   config — Codex's stdio children do not inherit the parent environment, while other hosts
-   expand `${VAR}`-style references. Keep tool descriptions under Claude Code's 4,096-char
-   cap and fetch output bounded (Claude Code caps tool output at 25k tokens by default; Pi
-   truncates text over 20 KB). Document per-host approval: `mcp__deepseek__*` rules (Claude
-   Code, Devin), `tools` lists and `--allow-tool` (Copilot), `--approve-mcps` (Cursor),
-   `autoApprove` (Cline), `exposure: "direct"` (Pi).
+5. **Host quirks to design around.** Tool naming (`deepseek_web_search`,
+   `deepseek_fetch`) already reflects the quirk catalog in the
+   [per-host reference](control-matrix.md#per-host-reference) — name collisions and
+   truncation, environment passing, output caps, and per-host approval surfaces; consult
+   it per host rather than this summary.
 
 ## Sources
 
@@ -215,20 +154,12 @@ differences:
 
 ### Hosts
 
-- Gemini CLI: [v0.64.0 tag](https://github.com/google-gemini/gemini-cli/tree/v0.64.0) —
-  [package.json (SDK 1.23.0 pin)](https://github.com/google-gemini/gemini-cli/blob/v0.64.0/packages/core/package.json),
-  [mcp-client.ts](https://github.com/google-gemini/gemini-cli/blob/v0.64.0/packages/core/src/tools/mcp-client.ts),
-  [mcp-tool.ts (name handling, result rendering)](https://github.com/google-gemini/gemini-cli/blob/v0.64.0/packages/core/src/tools/mcp-tool.ts),
-  [npm 0.64.0](https://registry.npmjs.org/@google/gemini-cli)
 - Codex: [rust-v0.163.0 tag](https://github.com/openai/codex/tree/rust-v0.163.0) —
   [Cargo.toml (rmcp pin)](https://github.com/openai/codex/blob/rust-v0.163.0/codex-rs/Cargo.toml),
   [rmcp_client.rs (initialize params)](https://github.com/openai/codex/blob/rust-v0.163.0/codex-rs/codex-mcp/src/rmcp_client.rs),
   [mcp_types.rs (config keys)](https://github.com/openai/codex/blob/rust-v0.163.0/codex-rs/config/src/mcp_types.rs),
   [utils.rs (stdio env allowlist)](https://github.com/openai/codex/blob/rust-v0.163.0/codex-rs/rmcp-client/src/utils.rs),
   [rust-sdk protocol constants at the pinned rev](https://github.com/modelcontextprotocol/rust-sdk/blob/4048ac40e958fb1a7d614617a2ae8d26666ee2fa/crates/rmcp/src/model.rs)
-- Continue: [1.5.47 npm tarball](https://registry.npmjs.org/@continuedev/cli/-/cli-1.5.47.tgz)
-  (MCPService.ts, mcpTransports.ts, bundled SDK protocol constants; no git tag exists),
-  [current docs](https://docs.continue.dev/customize/deep-dives/mcp)
 - Pi: [v1.3.0 tag](https://github.com/earendil-works/pi/tree/v1.3.0) —
   [pi-mcp protocol types](https://github.com/earendil-works/pi/blob/v1.3.0/packages/mcp/src/protocol/types.ts),
   [MCP docs at the tag](https://github.com/earendil-works/pi/blob/v1.3.0/packages/coding-agent/docs/mcp.md),

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "deepseek-web-retrieval",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Token-efficient DeepSeek Search and Fetch for coding agents, starting with OpenCode v2.",
   "type": "module",
   "license": "MIT",
@@ -26,7 +26,7 @@
     "./mcp": "./src/mcp/server.ts"
   },
   "bin": {
-    "deepseek-web-retrieval": "./dist/cli.js"
+    "deepseek-web-retrieval": "dist/cli.js"
   },
   "files": [
     "index.ts",
@@ -46,7 +46,7 @@
     "test:e2e": "bun run test/e2e/run.ts",
     "docs:matrix": "bun run scripts/render-matrix.ts",
     "test:coverage": "bun test --coverage",
-    "check": "bun run typecheck && bun run build && bun test"
+    "check": "bun run typecheck && bun run docs:matrix --check && bun run build && bun test"
   },
   "peerDependencies": {
     "@opencode/plugin": "^2.0.32"
@@ -64,6 +64,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/server": "^2.3.1",
+    "jsonc-parser": "^3.3.1",
+    "smol-toml": "^1.9.1",
     "zod": "^4"
   }
 }

package/src/core/auth.ts

@@ -1,4 +1,4 @@
-export const API_KEY_ENV = "DEEPSEEK_API_KEY"
+import { API_KEY_ENV } from "./constants"
 
 export function apiKeyFromEnv(
   env: Readonly<Record<string, string | undefined>> = process.env,