deepseek-web-retrieval 0.8.0 → 0.10.0

package/src/mcp/serve.ts

@@ -1,9 +1,8 @@
 import { serveStdio } from "@modelcontextprotocol/server/stdio";
-import { apiKeyFromEnv } from "../core/auth";
+import { apiKeyFromEnv, MISSING_API_KEY_MESSAGE } 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";
 

package/src/mcp/server.ts

@@ -2,20 +2,24 @@ import type { CallToolResult, ServerContext } from "@modelcontextprotocol/server
 import { McpServer } from "@modelcontextprotocol/server";
 import * as z from "zod/v4";
 import pkg from "../../package.json";
+import { requireApiKey } from "../core/auth";
 import type { RetrievalClient } from "../core/client";
-import { retrievalClient } from "../core/client";
-import { ENABLE_FETCH_ENV, ENABLE_SEARCH_ENV } from "../core/constants";
+import { requestContext, retrievalClient } from "../core/client";
+import { ENABLE_FETCH_ENV, ENABLE_SEARCH_ENV, MAX_FETCH_CHARS, MAX_SEARCH_COUNT } from "../core/constants";
 import {
+  FETCH_MAX_CHARS_PARAMETER,
   FETCH_TOOL_DESCRIPTION,
   FETCH_URL_PARAMETER,
+  SEARCH_COUNT_PARAMETER,
+  SEARCH_NEED_CONTENT_PARAMETER,
   SEARCH_ORI_QUESTION_PARAMETER,
   SEARCH_QUERY_PARAMETER,
   SEARCH_TOOL_DESCRIPTION,
 } from "../core/descriptions";
 import type { Env } from "../core/env";
 import { formatSearchResults, toStructuredResult } from "../core/format";
+import { bothDisabledPrecheck, withPerCallCount } from "../core/options";
 import type { ResolvedOptions } from "../core/types";
-import { requireApiKey } from "./auth";
 import { omitStructuredContent } from "./client";
 
 export const MCP_SERVER_NAME = "deepseek-web-retrieval";
@@ -23,10 +27,13 @@ export const MCP_SERVER_NAME = "deepseek-web-retrieval";
 const SEARCH_INPUT = z.object({
   query: z.string().min(1).describe(SEARCH_QUERY_PARAMETER),
   original_question: z.string().optional().describe(SEARCH_ORI_QUESTION_PARAMETER),
+  count: z.number().int().min(1).max(MAX_SEARCH_COUNT).optional().describe(SEARCH_COUNT_PARAMETER),
+  need_content: z.boolean().optional().describe(SEARCH_NEED_CONTENT_PARAMETER),
 });
 
 const FETCH_INPUT = z.object({
   url: z.string().min(1).describe(FETCH_URL_PARAMETER),
+  maxChars: z.number().int().min(0).max(MAX_FETCH_CHARS).optional().describe(FETCH_MAX_CHARS_PARAMETER),
 });
 
 /**
@@ -49,15 +56,16 @@ export function createDeepSeekServer(
         inputSchema: SEARCH_INPUT,
         annotations: { readOnlyHint: true },
       },
-      async ({ query, original_question }, ctx) => {
+      async ({ query, original_question, count, need_content }, ctx) => {
         try {
-          const request = requestContext(config, env, ctx.mcpReq.signal);
-          const results = await client.searchWeb(query, config.search, {
+          const request = requestContext(config, requireApiKey(env), ctx.mcpReq.signal);
+          const outcome = await client.searchWeb(query, withPerCallCount(config.search, count), {
             ...request,
             oriQuestion: original_question,
+            needContent: need_content === true,
           });
-          return callResult(server, ctx, formatSearchResults(results), {
-            results: results.map(toStructuredResult),
+          return callResult(server, ctx, formatSearchResults(outcome.results, outcome), {
+            results: outcome.results.map(toStructuredResult),
           });
         } catch (error) {
           return toErrorResult(error);
@@ -75,9 +83,9 @@ export function createDeepSeekServer(
         inputSchema: FETCH_INPUT,
         annotations: { readOnlyHint: true },
       },
-      async ({ url }, ctx) => {
+      async ({ url, maxChars }, ctx) => {
         try {
-          const request = requestContext(config, env, ctx.mcpReq.signal);
+          const request = requestContext(config, requireApiKey(env), ctx.mcpReq.signal, { maxChars });
           const page = await client.fetchDocument(url, config.fetch, request);
           return callResult(server, ctx, page.content, {
             url: page.url,
@@ -95,10 +103,6 @@ export function createDeepSeekServer(
   return server;
 }
 
-function requestContext(config: ResolvedOptions, env: Env, signal: AbortSignal) {
-  return { signal, auth: { apiKey: requireApiKey(env) }, retry: config.retry };
-}
-
 /**
  * Text content always reaches the model; the structured mirror is dropped for
  * clients that would replace the text with its serialized JSON (Codex does).
@@ -118,11 +122,7 @@ function callResult(
 
 /** 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;
-  return (
-    `Both tools are disabled (${ENABLE_SEARCH_ENV} and ${ENABLE_FETCH_ENV} are false); ` +
-    "at least one must stay enabled."
-  );
+  return bothDisabledPrecheck(config, `${ENABLE_SEARCH_ENV} and ${ENABLE_FETCH_ENV} are false`);
 }
 
 function toErrorResult(error: unknown): CallToolResult {

package/src/opencode/plugin.ts

@@ -2,10 +2,10 @@ 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 { inspectFetchTarget, requestContext, retrievalClient } from "../core/client";
 import { sharedFileOptions } from "../core/config-file";
 import { configDeviations } from "../core/config-summary";
-import { FETCH_MARKDOWN_ONLY, FETCH_OUTPUT_TRUNCATED } from "../core/descriptions";
+import { FETCH_MARKDOWN_ONLY, FETCH_MAX_CHARS_PARAMETER, FETCH_OUTPUT_TRUNCATED } from "../core/descriptions";
 import { pluginOptionsFromEnv } from "../core/env";
 import { formatQualityMarker } from "../core/format";
 import { resolveFetchTimeoutMs, resolvePluginOptions } from "../core/options";
@@ -16,6 +16,7 @@ type FetchInput = {
   readonly url: string;
   readonly format?: "markdown" | "text" | "html";
   readonly timeout?: number;
+  readonly maxChars?: number;
 };
 
 const FETCH_INPUT = {
@@ -38,6 +39,12 @@ const FETCH_INPUT = {
       description:
         "Optional timeout in seconds (maximum: 120). The effective limit is the shorter of this and fetchTimeoutMs.",
     },
+    maxChars: {
+      type: "integer",
+      minimum: 0,
+      maximum: 1_000_000,
+      description: FETCH_MAX_CHARS_PARAMETER,
+    },
   },
   required: ["url"],
   additionalProperties: false,
@@ -89,11 +96,6 @@ export function resolveRegistration(input?: PluginOptions): Registration {
   };
 }
 
-/** 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 }) };
-}
-
 async function runFetch(
   ctx: Context,
   config: ResolvedOptions,
@@ -135,7 +137,7 @@ async function runFetch(
   const page = await client.fetchDocument(
     target,
     config.fetch,
-    requestContext(config, apiKey, context.signal, timeoutMs),
+    requestContext(config, apiKey, context.signal, { timeoutMs, maxChars: input.maxChars }),
   );
   return {
     content: page.content,
@@ -173,12 +175,15 @@ export function createOpenCodePlugin(client: RetrievalClient = retrievalClient)
             name: "DeepSeek",
             execute: async (input, { signal }) => {
               const apiKey = await resolveApiKey(ctx, config.auth.source);
-              const results = await client.searchWeb(
+              const outcome = await client.searchWeb(
                 input.query,
                 config.search,
                 requestContext(config, apiKey, signal),
               );
-              return results.map(toOpenCodeResult);
+              // OpenCode's result shape is closed, so the effective-query header
+              // has nowhere to ride on this path (documented in the guide);
+              // degradation notes still surface through thrown error messages.
+              return outcome.results.map(toOpenCodeResult);
             },
           });
           if (registration.setDefault) editor.default.set("deepseek");

package/src/pi/extension.ts

@@ -3,14 +3,17 @@ import { Type } from "@earendil-works/pi-ai";
 import type { AgentToolResult, ExtensionAPI, ExtensionToolContext } from "@earendil-works/pi-coding-agent";
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { apiKeyFromEnv } from "../core/auth";
-import type { RequestOptions, RetrievalClient } from "../core/client";
-import { inspectFetchTarget, retrievalClient } from "../core/client";
+import type { RetrievalClient } from "../core/client";
+import { inspectFetchTarget, requestContext, retrievalClient } from "../core/client";
 import { sharedFileOptions } from "../core/config-file";
 import { configDeviations } from "../core/config-summary";
-import { API_KEY_ENV, ENABLE_FETCH_ENV, ENABLE_SEARCH_ENV } from "../core/constants";
+import { API_KEY_ENV, ENABLE_FETCH_ENV, ENABLE_SEARCH_ENV, MAX_FETCH_CHARS, MAX_SEARCH_COUNT } from "../core/constants";
 import {
+  FETCH_MAX_CHARS_PARAMETER,
   FETCH_TOOL_DESCRIPTION,
   FETCH_URL_PARAMETER,
+  SEARCH_COUNT_PARAMETER,
+  SEARCH_NEED_CONTENT_PARAMETER,
   SEARCH_ORI_QUESTION_PARAMETER,
   SEARCH_QUERY_PARAMETER,
   SEARCH_TOOL_DESCRIPTION,
@@ -18,7 +21,7 @@ import {
 import type { Env } from "../core/env";
 import { pluginOptionsFromEnv } from "../core/env";
 import { formatSearchResults, toStructuredResult } from "../core/format";
-import { resolvePluginOptions } from "../core/options";
+import { bothDisabledPrecheck, resolvePluginOptions, withPerCallCount } from "../core/options";
 import type { ResolvedOptions } from "../core/types";
 import type { ExtensionSettings } from "./settings";
 import { readExtensionSettings, SETTINGS_NAMESPACE } from "./settings";
@@ -30,6 +33,8 @@ const SEARCH_PARAMETERS = Type.Object({
       description: `${SEARCH_ORI_QUESTION_PARAMETER} When left blank, the most recent user message in the session is sent instead, truncated to fit.`,
     }),
   ),
+  count: Type.Optional(Type.Integer({ minimum: 1, maximum: MAX_SEARCH_COUNT, description: SEARCH_COUNT_PARAMETER })),
+  need_content: Type.Optional(Type.Boolean({ description: SEARCH_NEED_CONTENT_PARAMETER })),
 });
 
 const SEARCH_OUTPUT = Type.Object({
@@ -48,6 +53,9 @@ const SEARCH_OUTPUT = Type.Object({
 
 const FETCH_PARAMETERS = Type.Object({
   url: Type.String({ minLength: 1, description: FETCH_URL_PARAMETER }),
+  maxChars: Type.Optional(
+    Type.Integer({ minimum: 0, maximum: MAX_FETCH_CHARS, description: FETCH_MAX_CHARS_PARAMETER }),
+  ),
 });
 
 const FETCH_OUTPUT = Type.Object({
@@ -77,10 +85,10 @@ export function resolveExtensionOptions(env: Env = process.env, settings: Extens
 
 /** Returns the both-disabled message, or undefined when a tool stays enabled. */
 export function extensionPrecheck(config: ResolvedOptions): string | undefined {
-  if (config.search.enabled || config.fetch.enabled) return undefined;
-  return (
-    `Both tools are disabled (${ENABLE_SEARCH_ENV} and ${ENABLE_FETCH_ENV} are false, or the ` +
-    `${SETTINGS_NAMESPACE} settings namespace disabled them); at least one must stay enabled.`
+  return bothDisabledPrecheck(
+    config,
+    `${ENABLE_SEARCH_ENV} and ${ENABLE_FETCH_ENV} are false, or the ` +
+      `${SETTINGS_NAMESPACE} settings namespace disabled them`,
   );
 }
 
@@ -100,13 +108,14 @@ export function searchTool(config: ResolvedOptions, client: RetrievalClient = re
         // The explicit parameter wins; only when the model left it blank does
         // the session fallback get a say.
         const explicit = params.original_question?.trim() ? params.original_question : undefined;
-        const results = await client.searchWeb(params.query, config.search, {
-          ...requestContext(config, signal),
+        const outcome = await client.searchWeb(params.query, withPerCallCount(config.search, params.count), {
+          ...requestContext(config, requireApiKey(), signal ?? NEVER_ABORTS),
           oriQuestion: explicit ?? sessionOriQuestion(ctx),
+          needContent: params.need_content === true,
         });
         return {
-          content: [{ type: "text", text: formatSearchResults(results) }],
-          structuredContent: { results: results.map(toStructuredResult) },
+          content: [{ type: "text", text: formatSearchResults(outcome.results, outcome) }],
+          structuredContent: { results: outcome.results.map(toStructuredResult) },
           details: undefined,
         };
       } catch (error) {
@@ -130,7 +139,11 @@ export function fetchTool(config: ResolvedOptions, client: RetrievalClient = ret
     async execute(_toolCallId, params, signal): Promise<AgentToolResult> {
       try {
         const target = inspectFetchTarget(params.url, config.fetch);
-        const page = await client.fetchDocument(target, config.fetch, requestContext(config, signal));
+        const page = await client.fetchDocument(
+          target,
+          config.fetch,
+          requestContext(config, requireApiKey(), signal ?? NEVER_ABORTS, { maxChars: params.maxChars }),
+        );
         return {
           content: [{ type: "text", text: page.content }],
           structuredContent: {
@@ -168,10 +181,6 @@ export default function deepSeekWebRetrieval(pi: ExtensionAPI): void {
   if (config.fetch.enabled) pi.registerTool(fetchTool(config));
 }
 
-function requestContext(config: ResolvedOptions, signal: AbortSignal | undefined): RequestOptions {
-  return { signal: signal ?? NEVER_ABORTS, auth: { apiKey: requireApiKey() }, retry: config.retry };
-}
-
 /**
  * Best-effort `ori_question` fallback for when the model left the tool input
  * blank: the most recent user message text in the session projection, readable

package/src/mcp/auth.ts

@@ -1,11 +0,0 @@
-import { apiKeyFromEnv, MISSING_API_KEY_MESSAGE } from "../core/auth";
-import type { Env } from "../core/env";
-
-export { MISSING_API_KEY_MESSAGE };
-
-/** Resolves the API key from the environment or fails with shared guidance. */
-export function requireApiKey(env: Env): string {
-  const apiKey = apiKeyFromEnv(env);
-  if (!apiKey) throw new Error(MISSING_API_KEY_MESSAGE);
-  return apiKey;
-}