deepseek-web-retrieval 0.4.0 → 0.5.0

package/src/mcp/server.ts

@@ -1,97 +1,64 @@
-import { McpServer } from "@modelcontextprotocol/server"
-import type { CallToolResult } from "@modelcontextprotocol/server"
-import * as z from "zod/v4"
-import { fetchDocument, searchWeb } from "../core/client"
-import { ENABLE_FETCH_ENV, ENABLE_SEARCH_ENV } from "../core/constants"
+import type { CallToolResult, ServerContext } from "@modelcontextprotocol/server";
+import { McpServer } from "@modelcontextprotocol/server";
+import * as z from "zod/v4";
+import pkg from "../../package.json";
+import type { RetrievalClient } from "../core/client";
+import { retrievalClient } from "../core/client";
+import { ENABLE_FETCH_ENV, ENABLE_SEARCH_ENV } from "../core/constants";
 import {
-  FETCH_OUTPUT_TRUNCATED,
-  FETCH_SERVICE_LIMITS,
-  SEARCH_EMPTY_IS_NORMAL,
-  SEARCH_QUERY_OPERATORS,
-  SEARCH_RANKED_FILTERED,
-} from "../core/descriptions"
-import { formatSearchResults } from "../core/format"
-import type { ResolvedOptions, SearchResult } from "../core/types"
-import pkg from "../../package.json"
-import { requireApiKey } from "./auth"
-import type { Env } from "./config"
+  FETCH_TOOL_DESCRIPTION,
+  FETCH_URL_PARAMETER,
+  SEARCH_QUERY_PARAMETER,
+  SEARCH_TOOL_DESCRIPTION,
+} from "../core/descriptions";
+import type { Env } from "../core/env";
+import { formatSearchResults, toStructuredResult } from "../core/format";
+import type { ResolvedOptions } from "../core/types";
+import { requireApiKey } from "./auth";
+import { omitStructuredContent } from "./client";
 
-export const MCP_SERVER_NAME = "deepseek-web-retrieval"
+export const MCP_SERVER_NAME = "deepseek-web-retrieval";
 
 const SEARCH_INPUT = z.object({
-  query: z
-    .string()
-    .min(1)
-    .describe(
-      "Search query, 128 characters or fewer including operators (site:, -site:, quoted phrases, lang:).",
-    ),
-})
-
-const SEARCH_OUTPUT = z.object({
-  results: z.array(
-    z.object({
-      url: z.string(),
-      title: z.string().optional(),
-      content: z.string().optional(),
-      published: z.number().optional(),
-    }),
-  ),
-})
+  query: z.string().min(1).describe(SEARCH_QUERY_PARAMETER),
+});
 
 const FETCH_INPUT = z.object({
-  url: z.string().min(1).describe("Absolute http:// or https:// URL to fetch. Credentials are rejected."),
-})
-
-const FETCH_OUTPUT = z.object({
-  url: z.string(),
-  title: z.string(),
-  content: z.string(),
-  truncated: z.boolean(),
-})
-
-const SEARCH_DESCRIPTION =
-  "Search the web with DeepSeek's in-house search engine and return a short, filtered result " +
-    "list (title, URL, summary). " +
-    `${SEARCH_RANKED_FILTERED} ` +
-    `${SEARCH_EMPTY_IS_NORMAL} ` +
-    `${SEARCH_QUERY_OPERATORS} ` +
-    "To read a full page, pass a result URL to the deepseek_fetch tool."
-
-const FETCH_DESCRIPTION =
-  "Fetch one web page as clean Markdown through DeepSeek's Fetch API. " +
-    `${FETCH_SERVICE_LIMITS} ` +
-    `${FETCH_OUTPUT_TRUNCATED}`
+  url: z.string().min(1).describe(FETCH_URL_PARAMETER),
+});
 
 /**
  * Builds the host-agnostic MCP server exposing the two DeepSeek retrieval tools.
  * `serveStdio` and `createMcpHandler` serve both protocol eras from this factory.
  */
-export function createDeepSeekServer(config: ResolvedOptions, env: Env = process.env): McpServer {
-  const server = new McpServer({ name: MCP_SERVER_NAME, version: pkg.version })
+export function createDeepSeekServer(
+  config: ResolvedOptions,
+  env: Env = process.env,
+  client: RetrievalClient = retrievalClient,
+): McpServer {
+  const server = new McpServer({ name: MCP_SERVER_NAME, version: pkg.version });
 
   if (config.search.enabled) {
     server.registerTool(
       "deepseek_web_search",
       {
         title: "DeepSeek Web Search",
-        description: SEARCH_DESCRIPTION,
+        description: SEARCH_TOOL_DESCRIPTION,
         inputSchema: SEARCH_INPUT,
-        outputSchema: SEARCH_OUTPUT,
         annotations: { readOnlyHint: true },
       },
       async ({ query }, ctx) => {
         try {
-          const request = requestContext(config, env, ctx.mcpReq.signal)
-          const results = await searchWeb(query, config.search, request)
-          return {
-            content: [{ type: "text", text: formatSearchResults(results) }],
-            structuredContent: { results: results.map(toStructuredResult) },
-          }
+          const request = requestContext(config, env, ctx.mcpReq.signal);
+          const results = await client.searchWeb(query, config.search, request);
+          return callResult(server, ctx, formatSearchResults(results), {
+            results: results.map(toStructuredResult),
+          });
         } catch (error) {
-          return toErrorResult(error)
+          return toErrorResult(error);
         }
       },
-    )
+    );
   }
 
   if (config.fetch.enabled) {
@@ -99,57 +66,61 @@ export function createDeepSeekServer(config: ResolvedOptions, env: Env = process
       "deepseek_fetch",
       {
         title: "DeepSeek Fetch",
-        description: FETCH_DESCRIPTION,
+        description: FETCH_TOOL_DESCRIPTION,
         inputSchema: FETCH_INPUT,
-        outputSchema: FETCH_OUTPUT,
         annotations: { readOnlyHint: true },
       },
       async ({ url }, ctx) => {
         try {
-          const request = requestContext(config, env, ctx.mcpReq.signal)
-          const page = await fetchDocument(url, config.fetch, request)
-          return {
-            content: [{ type: "text", text: page.content }],
-            structuredContent: {
-              url: page.url,
-              title: page.title,
-              content: page.content,
-              truncated: page.truncated,
-            },
-          }
+          const request = requestContext(config, env, ctx.mcpReq.signal);
+          const page = await client.fetchDocument(url, config.fetch, request);
+          return callResult(server, ctx, page.content, {
+            url: page.url,
+            title: page.title,
+            content: page.content,
+            truncated: page.truncated,
+          });
         } catch (error) {
-          return toErrorResult(error)
+          return toErrorResult(error);
         }
       },
-    )
+    );
   }
 
-  return server
+  return server;
 }
 
 function requestContext(config: ResolvedOptions, env: Env, signal: AbortSignal) {
-  return { signal, auth: { apiKey: requireApiKey(env) }, retry: config.retry }
+  return { signal, auth: { apiKey: requireApiKey(env) }, retry: config.retry };
 }
 
-function toStructuredResult(result: SearchResult) {
-  return {
-    url: result.url,
-    ...(result.title ? { title: result.title } : {}),
-    ...(result.content ? { content: result.content } : {}),
-    ...(result.published !== undefined ? { published: result.published } : {}),
-  }
+/**
+ * Text content always reaches the model; the structured mirror is dropped for
+ * clients that would replace the text with its serialized JSON (Codex does).
+ * The tools declare no `outputSchema` on purpose: the SDK rejects text-only
+ * results for a tool with a declared schema ("no structured content was
+ * provided"), and no host in the matrix validates the schema anyway.
+ */
+function callResult(
+  server: McpServer,
+  ctx: ServerContext,
+  text: string,
+  structured: Record<string, unknown>,
+): CallToolResult {
+  if (omitStructuredContent(server, ctx)) return { content: [{ type: "text", text }] };
+  return { content: [{ type: "text", text }], structuredContent: structured };
 }
 
 /** Returns the both-disabled message, or undefined when a tool stays enabled. */
 export function servePrecheck(config: ResolvedOptions): string | undefined {
-  if (config.search.enabled || config.fetch.enabled) return undefined
+  if (config.search.enabled || config.fetch.enabled) return undefined;
   return (
     `Both tools are disabled (${ENABLE_SEARCH_ENV} and ${ENABLE_FETCH_ENV} are false); ` +
     "at least one must stay enabled."
-  )
+  );
 }
 
 function toErrorResult(error: unknown): CallToolResult {
-  const message = error instanceof Error ? error.message : String(error)
-  return { content: [{ type: "text", text: message }], isError: true }
+  const message = error instanceof Error ? error.message : String(error);
+  return { content: [{ type: "text", text: message }], isError: true };
 }

package/src/opencode/auth.ts

@@ -1,23 +1,23 @@
-import type { Context } from "@opencode/plugin/promise/plugin"
-import { API_KEY_ENV } from "../core/constants"
-import { apiKeyFromEnv } from "../core/auth"
-import type { ApiKeySource } from "../core/types"
+import type { Context } from "@opencode/plugin/promise/plugin";
+import { apiKeyFromEnv } from "../core/auth";
+import { API_KEY_ENV } from "../core/constants";
+import type { ApiKeySource } from "../core/types";
 
-const DEEPSEEK_INTEGRATION_ID = "deepseek"
+const DEEPSEEK_INTEGRATION_ID = "deepseek";
 
 /** OpenCode-specific guidance for a missing key; the core stays agent-agnostic. */
 function missingApiKeyError(source: ApiKeySource): Error {
   if (source === "env") {
-    return new Error(`${API_KEY_ENV} is not set. Export it before starting OpenCode.`)
+    return new Error(`${API_KEY_ENV} is not set. Export it before starting OpenCode.`);
   }
   if (source === "opencode") {
     return new Error(
       'No DeepSeek credential is stored in OpenCode. Run "opencode auth login" and connect DeepSeek, or set apiKeySource to "env".',
-    )
+    );
   }
   return new Error(
     `DeepSeek API key is not configured. Connect DeepSeek in OpenCode ("opencode auth login") or set ${API_KEY_ENV}.`,
-  )
+  );
 }
 
 /**
@@ -26,45 +26,43 @@ function missingApiKeyError(source: ApiKeySource): Error {
  * `DEEPSEEK_API_KEY` remains available for headless setups.
  */
 export async function resolveApiKey(ctx: Context, source: ApiKeySource): Promise<string> {
-  const envKey = apiKeyFromEnv(process.env)
+  const envKey = apiKeyFromEnv(process.env);
 
   if (source === "env") {
-    if (envKey) return envKey
-    throw missingApiKeyError("env")
+    if (envKey) return envKey;
+    throw missingApiKeyError("env");
   }
 
-  let stored: string | undefined
-  let storedError: unknown
+  let stored: string | undefined;
+  let storedError: unknown;
   try {
-    const connection = await ctx.integration.connection.active(DEEPSEEK_INTEGRATION_ID)
-    const credential = connection
-      ? await ctx.integration.connection.resolve(connection)
-      : undefined
+    const connection = await ctx.integration.connection.active(DEEPSEEK_INTEGRATION_ID);
+    const credential = connection ? await ctx.integration.connection.resolve(connection) : undefined;
     if (credential?.type === "key") {
-      const key = credential.key.trim()
-      if (key) stored = key
+      const key = credential.key.trim();
+      if (key) stored = key;
     }
   } catch (error) {
-    storedError = error
+    storedError = error;
   }
 
-  if (stored) return stored
+  if (stored) return stored;
   if (source === "opencode") {
     if (storedError) {
       throw new Error(
         'Could not read the DeepSeek credential from OpenCode. Run "opencode auth login" and connect DeepSeek.',
         { cause: storedError },
-      )
+      );
     }
-    throw missingApiKeyError("opencode")
+    throw missingApiKeyError("opencode");
   }
-  if (envKey) return envKey
+  if (envKey) return envKey;
   if (storedError) {
     throw new Error(
       `DeepSeek API key is not configured, and the OpenCode credential could not be read. ` +
         `Set ${API_KEY_ENV} or run "opencode auth login".`,
       { cause: storedError },
-    )
+    );
   }
-  throw missingApiKeyError("auto")
+  throw missingApiKeyError("auto");
 }

package/src/opencode/plugin.ts

@@ -1,17 +1,18 @@
-import { Plugin } from "@opencode/plugin"
-import type { Context } from "@opencode/plugin/promise/plugin"
-import type { ToolContext } from "@opencode/plugin/promise/tool"
-import { fetchDocument, inspectFetchTarget, searchWeb } from "../core/client"
-import { FETCH_MARKDOWN_ONLY, FETCH_OUTPUT_TRUNCATED } from "../core/descriptions"
-import { resolveFetchTimeoutMs, resolvePluginOptions } from "../core/options"
-import type { PluginOptions, ResolvedOptions, SearchResult } from "../core/types"
-import { resolveApiKey } from "./auth"
+import { Plugin } from "@opencode/plugin";
+import type { Context } from "@opencode/plugin/promise/plugin";
+import type { ToolContext } from "@opencode/plugin/promise/tool";
+import type { RetrievalClient } from "../core/client";
+import { inspectFetchTarget, retrievalClient } from "../core/client";
+import { FETCH_MARKDOWN_ONLY, FETCH_OUTPUT_TRUNCATED } from "../core/descriptions";
+import { resolveFetchTimeoutMs, resolvePluginOptions } from "../core/options";
+import type { PluginOptions, ResolvedOptions, SearchResult } from "../core/types";
+import { resolveApiKey } from "./auth";
 
 type FetchInput = {
-  readonly url: string
-  readonly format?: "markdown" | "text" | "html"
-  readonly timeout?: number
-}
+  readonly url: string;
+  readonly format?: "markdown" | "text" | "html";
+  readonly timeout?: number;
+};
 
 const FETCH_INPUT = {
   type: "object",
@@ -36,23 +37,23 @@ const FETCH_INPUT = {
   },
   required: ["url"],
   additionalProperties: false,
-} as const
+} as const;
 
 const DEEPSEEK_FETCH_DESCRIPTION =
   "Fetch one web page as clean Markdown through DeepSeek's Fetch API. This separate tool remains " +
-    `available when the built-in webfetch is replaced. ${FETCH_MARKDOWN_ONLY} ${FETCH_OUTPUT_TRUNCATED}`
+  `available when the built-in webfetch is replaced. ${FETCH_MARKDOWN_ONLY} ${FETCH_OUTPUT_TRUNCATED}`;
 
 const WEBFETCH_DESCRIPTION =
   "Fetch content from an HTTP or HTTPS URL and return it as Markdown through DeepSeek's Fetch API. " +
-    "This is the built-in webfetch replacement enabled by fetchOverrideWebfetch. DeepSeek does not " +
-    `render JavaScript and some sites return 403/404. ${FETCH_MARKDOWN_ONLY} ${FETCH_OUTPUT_TRUNCATED}`
+  "This is the built-in webfetch replacement enabled by fetchOverrideWebfetch. DeepSeek does not " +
+  `render JavaScript and some sites return 403/404. ${FETCH_MARKDOWN_ONLY} ${FETCH_OUTPUT_TRUNCATED}`;
 
 /** OpenCode's WebSearch.Result shape, which wraps the published date in `time`. */
 interface OpenCodeSearchResult {
-  readonly url: string
-  readonly title?: string
-  readonly content?: string
-  readonly time: { readonly published?: number }
+  readonly url: string;
+  readonly title?: string;
+  readonly content?: string;
+  readonly time: { readonly published?: number };
 }
 
 /** Maps the core's neutral SearchResult onto the shape OpenCode expects. */
@@ -61,17 +62,15 @@ function toOpenCodeResult(result: SearchResult): OpenCodeSearchResult {
     url: result.url,
     ...(result.title ? { title: result.title } : {}),
     ...(result.content ? { content: result.content } : {}),
-    ...(result.published !== undefined
-      ? { time: { published: result.published } }
-      : { time: {} }),
-  }
+    ...(result.published !== undefined ? { time: { published: result.published } } : { time: {} }),
+  };
 }
 
 /** How the plugin registers itself with OpenCode; resolved where it is consumed. */
 export interface Registration {
-  readonly setDefault: boolean
-  readonly overrideWebfetch: boolean
-  readonly registerTool: boolean
+  readonly setDefault: boolean;
+  readonly overrideWebfetch: boolean;
+  readonly registerTool: boolean;
 }
 
 export function resolveRegistration(input?: PluginOptions): Registration {
@@ -79,12 +78,12 @@ export function resolveRegistration(input?: PluginOptions): Registration {
     setDefault: input?.setDefaultWebsearch === true,
     overrideWebfetch: input?.fetchOverrideWebfetch === true,
     registerTool: input?.fetchRegisterTool !== false,
-  }
+  };
 }
 
 /** One place builds the per-request context the core expects. */
 function requestContext(config: ResolvedOptions, apiKey: string, signal: AbortSignal, timeoutMs?: number) {
-  return { signal, auth: { apiKey }, retry: config.retry, ...(timeoutMs === undefined ? {} : { timeoutMs }) }
+  return { signal, auth: { apiKey }, retry: config.retry, ...(timeoutMs === undefined ? {} : { timeoutMs }) };
 }
 
 async function runFetch(
@@ -94,25 +93,26 @@ async function runFetch(
   context: ToolContext,
   permission: string,
   saveAll: boolean,
+  client: RetrievalClient,
 ) {
-  const format = input.format ?? "markdown"
+  const format = input.format ?? "markdown";
   if (format !== "markdown") {
     throw new Error(
       `DeepSeek Fetch only returns Markdown; format "${format}" is not supported. Omit format or use "markdown".`,
-    )
+    );
   }
 
   if (typeof input.url !== "string") {
-    throw new Error('"url" must be a string')
+    throw new Error('"url" must be a string');
   }
   // Inspect before the permission prompt so an invalid or blocked target fails
   // without asking the user; fetchPage enforces the policy again.
-  const target = inspectFetchTarget(input.url, config.fetch)
-  const timeoutMs = resolveFetchTimeoutMs(config.fetch.timeoutMs, input.timeout)
+  const target = inspectFetchTarget(input.url, config.fetch);
+  const timeoutMs = resolveFetchTimeoutMs(config.fetch.timeoutMs, input.timeout);
 
   // Resolved before the permission prompt so a missing key fails fast instead
   // of asking the user to approve a request that cannot run.
-  const apiKey = await resolveApiKey(ctx, config.auth.source)
+  const apiKey = await resolveApiKey(ctx, config.auth.source);
 
   await ctx.permission.assert({
     sessionID: context.sessionID,
@@ -122,9 +122,13 @@ async function runFetch(
     save: saveAll ? ["*"] : [target.href],
     metadata: saveAll ? { ...input, url: target.href, format } : { url: target.href },
     source: { type: "tool", messageID: context.messageID, id: context.id },
-  })
+  });
 
-  const page = await fetchDocument(target, config.fetch, requestContext(config, apiKey, context.signal, timeoutMs))
+  const page = await client.fetchDocument(
+    target,
+    config.fetch,
+    requestContext(config, apiKey, context.signal, timeoutMs),
+  );
   return {
     content: page.content,
     metadata: {
@@ -132,56 +136,64 @@ async function runFetch(
       title: page.title,
       truncated: page.truncated,
     },
-  }
+  };
 }
 
-export default Plugin.define({
-  id: "deepseek-web-retrieval",
-  async setup(ctx) {
-    const config = resolvePluginOptions(ctx.options)
-    const registration = resolveRegistration(ctx.options)
-
-    if (config.search.enabled) {
-      await ctx.websearch.transform((editor) => {
-        editor.add({
-          id: "deepseek",
-          name: "DeepSeek",
-          execute: async (input, { signal }) => {
-            const apiKey = await resolveApiKey(ctx, config.auth.source)
-            const results = await searchWeb(input.query, config.search, requestContext(config, apiKey, signal))
-            return results.map(toOpenCodeResult)
-          },
-        })
-        if (registration.setDefault) editor.default.set("deepseek")
-      })
-    }
-
-    if (config.fetch.enabled) {
-      await ctx.tool.transform((editor) => {
-        if (registration.overrideWebfetch) editor.remove("webfetch")
-
-        if (registration.registerTool) {
-          editor.add({
-            name: "deepseek_fetch",
-            description: DEEPSEEK_FETCH_DESCRIPTION,
-            input: FETCH_INPUT,
-            options: { codemode: false, permission: "deepseek_fetch" },
-            execute: (input, context) =>
-              runFetch(ctx, config, input as FetchInput, context, "deepseek_fetch", false),
-          })
-        }
-
-        if (registration.overrideWebfetch) {
+export function createOpenCodePlugin(client: RetrievalClient = retrievalClient) {
+  return Plugin.define({
+    id: "deepseek-web-retrieval",
+    async setup(ctx) {
+      const config = resolvePluginOptions(ctx.options);
+      const registration = resolveRegistration(ctx.options);
+
+      if (config.search.enabled) {
+        await ctx.websearch.transform((editor) => {
           editor.add({
-            name: "webfetch",
-            description: WEBFETCH_DESCRIPTION,
-            input: FETCH_INPUT,
-            options: { codemode: false, permission: "webfetch" },
-            execute: (input, context) =>
-              runFetch(ctx, config, input as FetchInput, context, "webfetch", true),
-          })
-        }
-      })
-    }
-  },
-})
+            id: "deepseek",
+            name: "DeepSeek",
+            execute: async (input, { signal }) => {
+              const apiKey = await resolveApiKey(ctx, config.auth.source);
+              const results = await client.searchWeb(
+                input.query,
+                config.search,
+                requestContext(config, apiKey, signal),
+              );
+              return results.map(toOpenCodeResult);
+            },
+          });
+          if (registration.setDefault) editor.default.set("deepseek");
+        });
+      }
+
+      if (config.fetch.enabled) {
+        await ctx.tool.transform((editor) => {
+          if (registration.overrideWebfetch) editor.remove("webfetch");
+
+          if (registration.registerTool) {
+            editor.add({
+              name: "deepseek_fetch",
+              description: DEEPSEEK_FETCH_DESCRIPTION,
+              input: FETCH_INPUT,
+              options: { codemode: false, permission: "deepseek_fetch" },
+              execute: (input, context) =>
+                runFetch(ctx, config, input as FetchInput, context, "deepseek_fetch", false, client),
+            });
+          }
+
+          if (registration.overrideWebfetch) {
+            editor.add({
+              name: "webfetch",
+              description: WEBFETCH_DESCRIPTION,
+              input: FETCH_INPUT,
+              options: { codemode: false, permission: "webfetch" },
+              execute: (input, context) =>
+                runFetch(ctx, config, input as FetchInput, context, "webfetch", true, client),
+            });
+          }
+        });
+      }
+    },
+  });
+}
+
+export default createOpenCodePlugin();