deepseek-web-retrieval 0.5.1 → 0.7.0

package/src/installer/config-command.ts

@@ -0,0 +1,116 @@
+import { apiKeyFromEnv, MISSING_API_KEY_MESSAGE } from "../core/auth";
+import { createRetrievalClient, type RetrievalClient } from "../core/client";
+import { configFilePath, readFileOptionsReport } from "../core/config-file";
+import { configSummaryValues, formatConfigValue } from "../core/config-summary";
+import type { Env } from "../core/env";
+import { envOptionsReport, resolveEnvOptions } from "../core/env";
+import { formatSearchResults } from "../core/format";
+
+const EXIT_CONFIG_PROBLEMS = 1;
+const EXIT_USAGE = 2;
+
+const HOST_OVERRIDE_NOTE =
+  "Host-native layers (OpenCode options, Pi settings) may override file and env values per host.";
+
+/** Where the config command writes; the installer CLI resolves its CliIo into this. */
+export interface ConfigCommandIo {
+  readonly out: (line: string) => void;
+  readonly err: (line: string) => void;
+}
+
+/** Injectable seams: the environment to resolve, and the client for --search. */
+export interface ConfigCommandDeps {
+  readonly env?: Env;
+  readonly client?: RetrievalClient;
+}
+
+/**
+ * The `config` subcommand: the user-facing arm of configuration visibility.
+ * Prints the effective options exactly as the MCP server would resolve them
+ * (defaults < shared file < environment), each knob with its value and source,
+ * and replays the problems that would only whisper past on stderr at runtime —
+ * shared-file problems and set-but-unusable `DEEPSEEK_*` variables alike. With
+ * `query` set, runs one real billed search through that config — the
+ * end-to-end verifier for key, config, and network. Returns the exit code: 0
+ * normally, 1 for file or environment problems (plain form) or a failed
+ * search, 2 for a blank --search query. A missing file is not a problem.
+ */
+export async function runConfigCommand(
+  query: string | undefined,
+  io: ConfigCommandIo,
+  deps: ConfigCommandDeps = {},
+): Promise<number> {
+  if (query !== undefined && !query.trim()) {
+    io.err('error: --search requires a query (for example: config --search "deepseek mcp")');
+    return EXIT_USAGE;
+  }
+
+  const env = deps.env ?? process.env;
+  const file = configFilePath({ env });
+  const report = readFileOptionsReport(file);
+  for (const warning of report.warnings) io.err(`warning: ${warning}`);
+  const envReport = envOptionsReport(env);
+  for (const warning of envReport.warnings) io.err(`warning: ${warning}`);
+
+  // The same layers, in the same order, as the MCP server's startup resolution.
+  const resolved = resolveEnvOptions(env, report.options);
+
+  if (query === undefined) {
+    printConfigReport(file, report.exists, report.options, envReport.options, resolved, io);
+    return report.warnings.length > 0 || envReport.warnings.length > 0 ? EXIT_CONFIG_PROBLEMS : 0;
+  }
+
+  const apiKey = apiKeyFromEnv(env);
+  if (!apiKey) {
+    io.err(MISSING_API_KEY_MESSAGE);
+    return EXIT_CONFIG_PROBLEMS;
+  }
+  const client = deps.client ?? createRetrievalClient();
+  const startedAt = Date.now();
+  try {
+    const results = await client.searchWeb(query, resolved.search, {
+      signal: new AbortController().signal,
+      auth: { apiKey },
+      retry: resolved.retry,
+    });
+    const elapsedMs = Date.now() - startedAt;
+    io.out(
+      `search "${query.trim()}" — ${results.length} ${results.length === 1 ? "result" : "results"} in ${elapsedMs} ms`,
+    );
+    io.out("");
+    for (const line of formatSearchResults(results).split("\n")) io.out(line);
+    return 0;
+  } catch (error) {
+    io.err(error instanceof Error ? error.message : String(error));
+    return EXIT_CONFIG_PROBLEMS;
+  }
+}
+
+/** The knob table, in the vocabulary order the startup deviation summary uses. */
+function printConfigReport(
+  file: string,
+  exists: boolean,
+  fileOptions: Readonly<Record<string, unknown>>,
+  envOptions: Readonly<Record<string, unknown>>,
+  resolved: ReturnType<typeof resolveEnvOptions>,
+  io: ConfigCommandIo,
+): void {
+  io.out(`Config file: ${file} (${exists ? "exists" : "missing"})`);
+  io.out("");
+  const effective = configSummaryValues(resolved);
+  const fileKeys = new Set(Object.keys(fileOptions));
+  const envKeys = new Set(Object.keys(envOptions));
+  for (const name of Object.keys(effective)) {
+    // The environment wins over the file for the same key, exactly as resolution does.
+    let source = envKeys.has(name) ? "env" : fileKeys.has(name) ? "file" : "default";
+    // maxResults follows the effective count when unset (options.ts), so when
+    // the count knob was configured its derived value is not "default" — its
+    // source is the count setting that drove it.
+    if (name === "maxResults" && source === "default" && (envKeys.has("count") || fileKeys.has("count"))) {
+      source = "count";
+    }
+    io.out(`${name} = ${formatConfigValue(effective[name], "join")} (${source})`);
+  }
+  io.out("");
+  io.out(HOST_OVERRIDE_NOTE);
+}

package/src/installer/hosts/codex.ts

@@ -1,5 +1,6 @@
 import { spawnSync } from "node:child_process";
 import { API_KEY_ENV } from "../../core/constants";
+import { OPTION_ENV_VARS } from "../../core/env";
 import { FORCED_COST_NOTE, othersStayRegisteredNote, replacingExistingEntryNote, splitCompetitors } from "../detect";
 import { codecFor } from "../formats";
 import { buildRulesBlock } from "../formats/rules";
@@ -111,7 +112,7 @@ export function planCodex(input: InstallerInput, _previous: InstallRecord | unde
     command: "npx",
     args: ["-y", input.packageRef],
     ...(keptDisabled.length > 0 || offDisabled.length > 0 ? { disabled_tools: [...keptDisabled, ...offDisabled] } : {}),
-    env_vars: [API_KEY_ENV],
+    env_vars: [API_KEY_ENV, ...OPTION_ENV_VARS],
   };
 
   const ops: ConfigOp[] = [{ op: "set", path: ["mcp_servers", "deepseek"], value: entry, previous: existingEntry }];
@@ -133,8 +134,9 @@ export function planCodex(input: InstallerInput, _previous: InstallRecord | unde
   edits.push({ file: paths.config, format: "toml", shared: true, ops });
 
   notes.push(
-    `Codex stdio children do not inherit the parent environment, so the entry forwards ${API_KEY_ENV} 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 ${API_KEY_ENV} 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).",
   );
   if (input.scope === "project") {
     notes.push(

package/src/installer/hosts/opencode.ts

@@ -2,6 +2,7 @@ import { FORCED_COST_NOTE, looksLikeOwnPackage } from "../detect";
 import { codecFor } from "../formats";
 import { buildRulesBlock } from "../formats/rules";
 import { isPlainObject } from "../formats/value";
+import { lineageMatcher } from "../ownership";
 import { configHome, join } from "../paths";
 import { rulesLines } from "../rulesContent";
 import { appendedByPrevious } from "../state";
@@ -44,8 +45,10 @@ export function planOpenCode(input: InstallerInput, previous: InstallRecord | un
 
   const plugins = Array.isArray(loaded.value.plugins) ? loaded.value.plugins : [];
   // Precisely ours: plugin packages a tracked init appended, plus this init's ref.
-  // Without a record nothing is excused — an untracked same-name plugin (a fork
-  // registers the same tool ids and would collide) must be removed first.
+  // Refs compare by package name (samePackageName), so a pinned ref excuses the
+  // unpinned lineage a previous init wrote and vice versa. Without a record
+  // nothing is excused — an untracked same-name plugin (a fork registers the
+  // same tool ids and would collide) must be removed first.
   const trackedPackages = new Set(
     appendedByPrevious(previous, ["plugins"])
       .filter((entry): entry is { package: string } => isPlainObject(entry) && typeof entry.package === "string")
@@ -54,9 +57,10 @@ export function planOpenCode(input: InstallerInput, previous: InstallRecord | un
   const pluginPackages = plugins.filter(
     (entry): entry is { package: string } => isPlainObject(entry) && typeof entry.package === "string",
   );
-  const excused = previous === undefined ? new Set<string>() : new Set<string>([...trackedPackages, input.packageRef]);
+  const excusedRefs = previous === undefined ? [] : [...trackedPackages, input.packageRef];
+  const isExcusedRef = lineageMatcher(excusedRefs);
   const foreignOwn = pluginPackages.filter(
-    (entry) => looksLikeOwnPackage(entry.package) && !excused.has(entry.package),
+    (entry) => looksLikeOwnPackage(entry.package) && !isExcusedRef(entry.package),
   );
   if (foreignOwn.length > 0) {
     errors.push({
@@ -65,7 +69,7 @@ export function planOpenCode(input: InstallerInput, previous: InstallRecord | un
         "write. Remove it (or run uninstall if it came from a previous init), then retry.",
     });
   }
-  if (previous !== undefined && pluginPackages.some((entry) => excused.has(entry.package))) {
+  if (previous !== undefined && pluginPackages.some((entry) => isExcusedRef(entry.package))) {
     notes.push(
       "A previous init wrote the plugins entry; re-applying keeps it the only entry (a changed package ref or tier " +
         "options replace it, an unchanged one is a no-op) and the original snapshots carry over.",

package/src/installer/hosts/pi.ts

@@ -11,6 +11,7 @@ import {
 import { codecFor } from "../formats";
 import { buildRulesBlock } from "../formats/rules";
 import { isPlainObject } from "../formats/value";
+import { lineageMatcher } from "../ownership";
 import { join } from "../paths";
 import { MCP_TOOL_IDS, RAW_MCP_TOOL_IDS, rulesLines } from "../rulesContent";
 import { appendedByPrevious } from "../state";
@@ -60,14 +61,17 @@ function planPiExtension(input: InstallerInput, previous: InstallRecord | undefi
   const packages = Array.isArray(loaded.value.packages) ? loaded.value.packages : [];
   const source = piSourceRef(input.packageRef);
   // Precisely ours: what a tracked init appended, plus what this init would write.
-  // Only a tracked init can excuse a same-name source — without a record, even an
+  // Sources compare by package name (samePackageName), so a pinned source
+  // excuses the unpinned lineage a previous init wrote and vice versa. Only a
+  // tracked init can excuse a same-name source — without a record, even an
   // exact match is an untracked install this installer must not adopt silently.
   const trackedSources = appendedByPrevious(previous, ["packages"]).filter(
     (entry): entry is string => typeof entry === "string",
   );
-  const excused = previous === undefined ? new Set<string>() : new Set<string>([...trackedSources, source]);
   const sources = packages.filter((entry): entry is string => typeof entry === "string");
-  const foreignOwn = sources.filter((entry) => looksLikeOwnPackage(entry) && !excused.has(entry));
+  const excusedSources = previous === undefined ? [] : [...trackedSources, source];
+  const isExcusedSource = lineageMatcher(excusedSources);
+  const foreignOwn = sources.filter((entry) => looksLikeOwnPackage(entry) && !isExcusedSource(entry));
   if (foreignOwn.length > 0) {
     errors.push({
       message:
@@ -75,7 +79,7 @@ function planPiExtension(input: InstallerInput, previous: InstallRecord | undefi
         "write. Remove it (pi remove <source>, or uninstall if it came from a previous init), then retry.",
     });
   }
-  if (previous !== undefined && sources.some((entry) => excused.has(entry))) {
+  if (previous !== undefined && sources.some((entry) => isExcusedSource(entry))) {
     notes.push(
       "A previous init wrote the packages entry; re-applying reuses it (an unchanged source deduplicates, a changed " +
         "--package ref replaces the old source) and the original snapshots carry over.",
@@ -87,9 +91,9 @@ function planPiExtension(input: InstallerInput, previous: InstallRecord | undefi
     // Pi has no per-package kill switch in settings.json, so a web-capable
     // package or extension source cannot be excluded from the plan — refuse the
     // tier instead of promising routing that is not actually forced.
-    const ownSources = new Set<string>([...trackedSources, source]);
+    const isOwnSource = lineageMatcher([...trackedSources, source]);
     const unexcludable = [...collectSources(loaded.value.packages), ...collectSources(loaded.value.extensions)].filter(
-      (entry) => !ownSources.has(entry) && looksWebCapable(entry, undefined),
+      (entry) => !isOwnSource(entry) && looksWebCapable(entry, undefined),
     );
     if (unexcludable.length > 0) {
       errors.push({

package/src/installer/ownership.ts

@@ -2,11 +2,60 @@ import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSyn
 import { basename, dirname, join, resolve } from "node:path";
 import { isPlainObject } from "../core/object";
 import { pruneEmptyDir } from "./revert";
-import { statePathFor } from "./state";
+import { recordReadPath, statePathFor } from "./state";
 import type { InstallerInput, RecordedFile, Scope } from "./types";
 
 type ClaimedFile = Pick<RecordedFile, "file" | "format" | "shared">;
 
+/**
+ * True when a ref's final `@` segment is a version spec — it starts with a digit
+ * (`name@<version>`, `npm:name@<version>`) — and not an npm scope
+ * (`@scope/name`, whose only `@` leads the string) or a dist-tag (`name@canary`).
+ */
+function hasVersionSuffix(ref: string): boolean {
+  const at = ref.lastIndexOf("@");
+  return at > 0 && /^[0-9]/.test(ref.slice(at + 1));
+}
+
+function stripVersionSuffix(ref: string): string {
+  const at = ref.lastIndexOf("@");
+  return hasVersionSuffix(ref) ? ref.slice(0, at) : ref;
+}
+
+/**
+ * Package-ref identity, the one comparison for "is this entry our package":
+ * two refs are the same package when they are equal after stripping a trailing
+ * `@version` suffix, so a pinned ref (`deepseek-web-retrieval@<version>`,
+ * `npm:deepseek-web-retrieval@<version>`) still matches its lineage
+ * (`deepseek-web-retrieval`). Forks, dist-tags, and lookalike names compare
+ * unequal. Everywhere a recorded or configured ref is matched against this
+ * install's ref — orphan detection, upgrade detection — goes through this
+ * helper instead of exact string equality.
+ */
+export function samePackageName(a: string, b: string): boolean {
+  return stripVersionSuffix(a) === stripVersionSuffix(b);
+}
+
+/**
+ * A lineage-membership predicate over an excused/own ref set: the candidate
+ * matches when it is the same package as any listed ref (version suffixes
+ * stripped via samePackageName — a pinned or hand-edited ref still matches its
+ * lineage). Both host modules build their set (previous init's tracked entries
+ * plus this run's ref) and ask the same two questions with this one predicate.
+ */
+export function lineageMatcher(refs: readonly string[]): (candidate: string) => boolean {
+  return (candidate: string) => refs.some((ref) => samePackageName(ref, candidate));
+}
+
+/**
+ * The `--pin` rule: append the running CLI's version to the ref unless its
+ * final `@` segment already is a version (`name` → `name@<version>`; a ref
+ * already ending in a version keeps it).
+ */
+export function pinPackageRef(ref: string, version: string): string {
+  return hasVersionSuffix(ref) ? ref : `${ref}@${version}`;
+}
+
 interface FileOwner {
   readonly recordPath: string;
   readonly scope: Scope;
@@ -63,6 +112,10 @@ function readOwner(file: string): FileOwner | undefined {
 function assertOwner(input: InstallerInput, claim: string): void {
   const owner = readOwner(claim);
   if (owner === undefined || owner.recordPath === ownerOf(input).recordPath) return;
+  // A win32 sidecar written before the config home moved to %APPDATA% names the
+  // legacy record location; when that is where this input's record is read
+  // from (see recordReadPath), it still identifies this same install lineage.
+  if (owner.recordPath === canonicalPath(recordReadPath(input))) return;
   throw new Error(
     `A ${input.host} install is already recorded at the ${owner.scope} scope (${owner.recordPath}) and claims the same config file. ` +
       `Uninstall it first: deepseek-web-retrieval uninstall --host ${input.host} --scope ${owner.scope} --cwd ${JSON.stringify(owner.cwd)}. ` +

package/src/installer/paths.ts

@@ -7,7 +7,13 @@ export function join(...parts: readonly string[]): string {
   return nonEmpty.length === 0 ? "" : pathJoin(...nonEmpty);
 }
 
-/** Config home: an explicit root wins; otherwise ~/.config. The CLI resolves XDG at the edge. */
+/**
+ * Config home: an explicit root wins; otherwise `~/.config`. The CLI edge now
+ * supplies the platform-aware explicit root (see userConfigHome in
+ * core/config-file: an honored XDG on every platform, `%APPDATA%` or
+ * `<home>\AppData\Roaming` on win32), so the `.config` fallback applies only to
+ * callers that construct roots directly without going through the CLI.
+ */
 export function configHome(roots: FsRoots): string {
   return roots.configHome ?? join(roots.home, ".config");
 }

package/src/installer/state.ts

@@ -3,12 +3,38 @@ import { isAbsolute, join } from "node:path";
 import { z } from "zod/v4";
 import { stateDir } from "./paths";
 import { atomicWrite } from "./persistence";
-import type { FsRoots, InstallerInput, InstallRecord } from "./types";
+import type { FsRoots, InstallerInput, InstallRecord, Scope } from "./types";
 
 export function statePathFor(input: InstallerInput): string {
   return join(stateDir(input, input.scope), `install.${input.host}.json`);
 }
 
+/** The platform a read resolves for: injected at the CLI edge, process.platform otherwise. */
+function platformOf(roots: FsRoots): NodeJS.Platform {
+  return roots.platform ?? process.platform;
+}
+
+/**
+ * Windows-only read compatibility: global records written before the config
+ * home moved to %APPDATA% live under `~/.config`. Kept readable so `list` and
+ * `uninstall` keep tracking installs made by older releases.
+ */
+export function legacyGlobalStateDir(roots: FsRoots): string {
+  return join(roots.home, ".config", "deepseek-web-retrieval");
+}
+
+/**
+ * The file a record is read from: the canonical state path, except that a
+ * missing win32 global record falls back to the legacy `~/.config` location
+ * (see legacyGlobalStateDir). Writes always target the canonical path.
+ */
+export function recordReadPath(input: InstallerInput, platform: NodeJS.Platform = platformOf(input)): string {
+  const canonical = statePathFor(input);
+  if (platform !== "win32" || input.scope !== "global" || existsSync(canonical)) return canonical;
+  const legacy = join(legacyGlobalStateDir(input), `install.${input.host}.json`);
+  return existsSync(legacy) ? legacy : canonical;
+}
+
 const keyPath = z.array(z.string().min(1)).min(1);
 const tier = z.enum(["optional", "preferred", "forced", "off"]);
 const operation = z.discriminatedUnion("op", [
@@ -22,6 +48,7 @@ const operation = z.discriminatedUnion("op", [
 ]);
 const recordSchema = z.object({
   version: z.literal(1),
+  installerVersion: z.string().optional(),
   host: z.enum(["opencode", "pi", "codex"]),
   scope: z.enum(["global", "project"]),
   tiers: z.object({ search: tier, fetch: tier }),
@@ -85,7 +112,7 @@ function readRecordFile(file: string, host: string, scope: string): InstallRecor
 }
 
 export function readRecord(input: InstallerInput): InstallRecord | undefined {
-  return readRecordFile(statePathFor(input), input.host, input.scope);
+  return readRecordFile(recordReadPath(input), input.host, input.scope);
 }
 
 /**
@@ -122,27 +149,54 @@ export function appendedByPrevious(record: InstallRecord | undefined, path: read
 }
 
 export function deleteRecord(input: InstallerInput): void {
-  const file = statePathFor(input);
+  // Win32 legacy records are removed where they were found, so uninstalling a
+  // pre-APPDATA install clears its tracking instead of a canonical file that
+  // was never written.
+  const file = recordReadPath(input);
   if (existsSync(file)) rmSync(file);
 }
 
-/** Lists install records found in both scope locations for the given roots. */
-export function listRecords(roots: FsRoots): InstallRecord[] {
+/** Reads every valid record in one scope's directory; an absent directory is empty. */
+function readRecordsFromDir(dir: string, scope: Scope): InstallRecord[] {
   const records: InstallRecord[] = [];
-  for (const scope of ["global", "project"] as const) {
-    const dir = stateDir(roots, scope);
-    let names: string[];
-    try {
-      names = readdirSync(dir);
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code === "ENOENT") continue;
-      throw new InstallRecordError(dir, "unreadable", (error as NodeJS.ErrnoException).code ?? "list failed");
-    }
-    for (const name of names) {
-      if (!name.startsWith("install.") || !name.endsWith(".json")) continue;
-      const record = readRecordFile(join(dir, name), name.slice("install.".length, -".json".length), scope);
-      if (record !== undefined) records.push(record);
-    }
+  let names: string[];
+  try {
+    names = readdirSync(dir);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return records;
+    throw new InstallRecordError(dir, "unreadable", (error as NodeJS.ErrnoException).code ?? "list failed");
+  }
+  for (const name of names) {
+    if (!name.startsWith("install.") || !name.endsWith(".json")) continue;
+    const record = readRecordFile(join(dir, name), name.slice("install.".length, -".json".length), scope);
+    if (record !== undefined) records.push(record);
   }
   return records;
 }
+
+function hasRecordFiles(dir: string): boolean {
+  try {
+    return readdirSync(dir).some((name) => name.startsWith("install.") && name.endsWith(".json"));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * True when the global records must be read from the legacy win32 `~/.config`
+ * location: win32, nothing recorded under the canonical config home, and
+ * pre-%APPDATA% records still present there. `list` says so when this holds.
+ */
+export function readingLegacyGlobalRecords(roots: FsRoots): boolean {
+  if (platformOf(roots) !== "win32") return false;
+  if (hasRecordFiles(stateDir(roots, "global"))) return false;
+  return hasRecordFiles(legacyGlobalStateDir(roots));
+}
+
+/** Lists install records found in both scope locations for the given roots. */
+export function listRecords(roots: FsRoots): InstallRecord[] {
+  const global = readRecordsFromDir(stateDir(roots, "global"), "global");
+  const project = readRecordsFromDir(stateDir(roots, "project"), "project");
+  const legacy = readingLegacyGlobalRecords(roots) ? readRecordsFromDir(legacyGlobalStateDir(roots), "global") : [];
+  return [...global, ...legacy, ...project];
+}

package/src/installer/types.ts

@@ -13,6 +13,11 @@ export interface FsRoots {
   readonly cwd: string;
   /** Explicit config home; the CLI edge resolves XDG once and passes it down. */
   readonly configHome?: string;
+  /**
+   * Platform for the win32-aware reads (legacy record fallback); the CLI edge
+   * passes it down like configHome. Readers default to process.platform.
+   */
+  readonly platform?: NodeJS.Platform;
 }
 
 /** The files a host edit touches for a given scope. */
@@ -37,6 +42,11 @@ export interface InstallerInput {
   readonly home: string;
   readonly cwd: string;
   readonly configHome?: string;
+  /**
+   * Platform for the win32-aware reads (legacy record fallback); see FsRoots.
+   * Injected at the CLI edge, absent when callers construct inputs directly.
+   */
+  readonly platform?: NodeJS.Platform;
   /**
    * Integration mechanism for hosts with more than one (Pi: the native
    * extension, or the MCP server). Undefined means the host's default path.
@@ -136,6 +146,8 @@ export interface RecordedFile {
 /** Persisted install state; one record per host and scope. */
 export interface InstallRecord {
   readonly version: 1;
+  /** Version of the installer that wrote this record; absent on records from older releases. */
+  readonly installerVersion?: string;
   readonly host: HostName;
   readonly scope: Scope;
   readonly tiers: { readonly search: Tier; readonly fetch: Tier };

package/src/mcp/auth.ts

@@ -1,8 +1,7 @@
-import { apiKeyFromEnv } from "../core/auth";
-import { API_KEY_ENV } from "../core/constants";
+import { apiKeyFromEnv, MISSING_API_KEY_MESSAGE } from "../core/auth";
 import type { Env } from "../core/env";
 
-export const MISSING_API_KEY_MESSAGE = `DeepSeek API key not found. Set ${API_KEY_ENV} in the MCP server's env configuration.`;
+export { MISSING_API_KEY_MESSAGE };
 
 /** Resolves the API key from the environment or fails with shared guidance. */
 export function requireApiKey(env: Env): string {

package/src/mcp/cli.ts

@@ -1,57 +1,15 @@
 #!/usr/bin/env node
-import { serveStdio } from "@modelcontextprotocol/server/stdio";
-import { apiKeyFromEnv } from "../core/auth";
-import { resolveEnvOptions } from "../core/env";
-import { MISSING_API_KEY_MESSAGE } from "./auth";
-import { isJsonReplacingClient } from "./client";
-import { createDeepSeekServer, servePrecheck } from "./server";
-
-// Installer subcommands run before the server path; MCP clients spawn this bin
-// with no arguments, so the default stdio behavior is unchanged.
-const subcommand = process.argv[2];
-if (subcommand === "init" || subcommand === "uninstall" || subcommand === "list") {
+// Any argument means a human ran the CLI; MCP clients spawn this bin with no
+// arguments for the stdio server. Each side is imported dynamically, and only
+// the side being routed to, so init/uninstall never load — or depend on — the
+// server's dependency graph (and the server never loads the installer),
+// including when recovering from a bad server setup.
+if (process.argv.length > 2) {
   const { runInstallerCli } = await import("../installer/cli");
   process.exit(await runInstallerCli(process.argv.slice(2)));
 }
 
-// stdout is the JSON-RPC channel; all diagnostics must go to stderr.
-const env = process.env;
-if (!apiKeyFromEnv(env)) {
-  console.error(MISSING_API_KEY_MESSAGE);
-  process.exit(1);
-}
-
-const config = resolveEnvOptions(env);
-const precheck = servePrecheck(config);
-if (precheck) {
-  console.error(precheck);
-  process.exit(1);
-}
-const handle = serveStdio(() => {
-  const server = createDeepSeekServer(config, env);
-  // Fires after the handshake-era initialize exchange (the stateless era opens
-  // differently and simply never logs). One stderr line so a human run shows
-  // which client connected and whether text-only shaping kicked in; if a host
-  // renames its clientInfo, this line is where the regression becomes visible.
-  server.server.oninitialized = () => {
-    const info = server.server.getClientVersion();
-    if (info === undefined) return;
-    console.error(
-      `mcp client: ${info.name} ${info.version ?? "unknown"} — ` +
-        (isJsonReplacingClient(info.name)
-          ? "text-only results (this client replaces content with serialized structuredContent)"
-          : "text + structuredContent results"),
-    );
-  };
-  return server;
-});
-const tools = [
-  config.search.enabled ? `search (max ${config.search.maxResults} results)` : null,
-  config.fetch.enabled ? `fetch (max ${config.fetch.maxChars} chars)` : null,
-]
-  .filter(Boolean)
-  .join(", ");
-console.error(`deepseek-web-retrieval MCP server on stdio (${tools})`);
+const { serveMcp } = await import("./serve");
+serveMcp();
 
-process.on("SIGINT", () => void handle.close());
-process.on("SIGTERM", () => void handle.close());
+export {};

package/src/mcp/serve.ts

@@ -0,0 +1,60 @@
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { apiKeyFromEnv } from "../core/auth";
+import { sharedFileOptions } from "../core/config-file";
+import { configDeviations } from "../core/config-summary";
+import { resolveEnvOptions } from "../core/env";
+import { MISSING_API_KEY_MESSAGE } from "./auth";
+import { isJsonReplacingClient } from "./client";
+import { createDeepSeekServer, servePrecheck } from "./server";
+
+/** Boots the stdio MCP server; the CLI entry reaches this only with no arguments. */
+export function serveMcp(): void {
+  // stdout is the JSON-RPC channel; all diagnostics must go to stderr.
+  const env = process.env;
+  if (!apiKeyFromEnv(env)) {
+    console.error(MISSING_API_KEY_MESSAGE);
+    process.exit(1);
+  }
+
+  // Defaults < shared config file < environment: the server reads the file
+  // itself, so hosts that forward only DEEPSEEK_API_KEY still honor it.
+  const config = resolveEnvOptions(env, sharedFileOptions({ env }));
+  const precheck = servePrecheck(config);
+  if (precheck) {
+    console.error(precheck);
+    process.exit(1);
+  }
+  const handle = serveStdio(() => {
+    const server = createDeepSeekServer(config, env);
+    // Fires after the handshake-era initialize exchange (the stateless era opens
+    // differently and simply never logs). One stderr line so a human run shows
+    // which client connected and whether text-only shaping kicked in; if a host
+    // renames its clientInfo, this line is where the regression becomes visible.
+    server.server.oninitialized = () => {
+      const info = server.server.getClientVersion();
+      if (info === undefined) return;
+      console.error(
+        `mcp client: ${info.name} ${info.version ?? "unknown"} — ` +
+          (isJsonReplacingClient(info.name)
+            ? "text-only results (this client replaces content with serialized structuredContent)"
+            : "text + structuredContent results"),
+      );
+    };
+    return server;
+  });
+  const tools = [
+    config.search.enabled ? `search (max ${config.search.maxResults} results)` : null,
+    config.fetch.enabled ? `fetch (max ${config.fetch.maxChars} chars)` : null,
+  ]
+    .filter(Boolean)
+    .join(", ");
+  console.error(`deepseek-web-retrieval MCP server on stdio (${tools})`);
+  // Deviations only, so the line stays short while still showing every
+  // non-default knob the layered resolution produced; nothing deviating
+  // means no line at all.
+  const deviations = configDeviations(config);
+  if (deviations) console.error(`config: ${deviations}`);
+
+  process.on("SIGINT", () => void handle.close());
+  process.on("SIGTERM", () => void handle.close());
+}