deepsearch
Execute broad web searches using the DeepSearch model to retrieve structured results with improved accuracy compared to standard AI search tools, though processing may take longer.
Instructions
使用 DeepSearch 模型执行广域检索并返回结构化结果,拥有比AI Agent内置搜索更好的搜索效果但更耗时，需要平衡需求
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| filters | No | ||
| locale | No | ||
| query | Yes | ||
| top_k | No |
Implementation Reference
- main.ts:78-99 (handler)The handler function for the MCP tool 'deepsearch'. It logs the call, invokes DeepSearchAgent.search with the provided arguments, parses the result using Zod schema, logs completion, and returns a structured MCP response with text and structured content.async (args) => { const toolLogger = logger.child({ tool: "deepsearch" }); toolLogger.info("收到工具调用", args); const result = await deepsearchAgent.search(args.query, { top_k: args.top_k, locale: args.locale, filters: args.filters, }); const structured = searchResultSchema.parse(result); toolLogger.info("完成工具调用", { itemCount: structured.items.length }); return { content: [ { type: "text" as const, text: JSON.stringify(structured, null, 2), }, ], structuredContent: structured, }; },
- main.ts:10-45 (schema)Schema definitions using Zod for input (deepSearchInputShape/Schema) and output (searchResultShape/Schema) of the deepsearch tool, including nested searchItemShape.const searchItemShape = { title: z.string(), snippet: z.string(), url: z.string(), score: z.number().nullable(), }; const searchResultShape = { items: z.array(z.object(searchItemShape)), metadata: z.record(z.any()), usage: z.object({ input_tokens: z.number(), output_tokens: z.number(), }), }; const deepSearchInputShape = { query: z.string().min(1, "query 不能为空"), top_k: z.number().int().min(1).max(10).optional(), locale: z.string().optional(), filters: z.record(z.any()).default({}), }; const deepSearchWebInputShape = { ...deepSearchInputShape, filters: z .record(z.any()) .refine((filters) => typeof filters.site === "string" || typeof filters.time_range === "string", { message: "filters 需要包含 site 或 time_range 字段", }), }; const deepSearchInputSchema = z.object(deepSearchInputShape); const deepSearchWebInputSchema = z.object(deepSearchWebInputShape); const searchResultSchema = z.object(searchResultShape);
- main.ts:70-100 (registration)Registration of the 'deepsearch' tool on the MCP server, including tool name, title, description, input/output schemas, and the handler function.server.registerTool( "deepsearch", { title: "DeepSearch 通用检索", description: "使用 DeepSearch 模型执行广域检索并返回结构化结果,拥有比AI Agent内置搜索更好的搜索效果但更耗时，需要平衡需求", inputSchema: deepSearchInputShape, outputSchema: searchResultShape, }, async (args) => { const toolLogger = logger.child({ tool: "deepsearch" }); toolLogger.info("收到工具调用", args); const result = await deepsearchAgent.search(args.query, { top_k: args.top_k, locale: args.locale, filters: args.filters, }); const structured = searchResultSchema.parse(result); toolLogger.info("完成工具调用", { itemCount: structured.items.length }); return { content: [ { type: "text" as const, text: JSON.stringify(structured, null, 2), }, ], structuredContent: structured, }; }, );
- DeepSearchAgent helper class instantiated in the server, providing search method that delegates to DeepSearchMCPClient to invoke the external transport/tool.export class DeepSearchAgent { private readonly client: DeepSearchMCPClient; private readonly transport?: DeepSearchTransport; private readonly logger: Logger; constructor(options: AgentOptions = {}) { const agentLogger = logger.child({ agent: "deepsearch" }); agentLogger.debug("初始化 DeepSearchAgent", { providedClient: Boolean(options.client) }); if (options.client) { this.client = options.client; this.transport = options.transport; } else { const transport = options.transport ?? DeepSearchTransport.fromEnv(); this.client = new DeepSearchMCPClient(transport, { toolName: "deepsearch" }); this.transport = transport; } this.logger = agentLogger; } search(query: string, options: SearchOptions = {}): Promise<SearchResult> { this.logger.info("执行检索", { query, options }); return this.client.search(query, options); } close(): void { this.logger.debug("关闭代理"); this.transport?.close(); } }
- source/api.ts:116-167 (helper)DeepSearchTransport.invokeTool helper method that performs the core logic: constructs prompt for Gemini model using googleSearch tool, calls external API (yunwu.ai), parses JSON response into structured search results. Called by MCPClient with toolName 'deepsearch'.async invokeTool(toolName: string, payload: InvokePayload): Promise<DeepSearchResponsePayload> { const body = this.buildRequest(toolName, payload); this.logger.info("调用 DeepSearch API", { toolName, endpoint: this.endpoint.toString(), timeoutMs: this.config.timeoutMs, }); const controller = new AbortController(); const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs); try { const response = await fetch(this.endpoint, { method: "POST", headers: { "Content-Type": "application/json", "Accept": "application/json", }, body: JSON.stringify(body), signal: controller.signal, }); if (!response.ok) { const message = `DeepSearch API 返回错误状态: ${response.status}`; this.logger.warn(message, { responseHeaders: Object.fromEntries(response.headers.entries()) }); throw new DeepSearchAPIError(message); } const data = (await response.json()) as Record<string, unknown>; this.logger.debug("收到 DeepSearch API 响应", data); return this.parseResponse(data); } catch (error) { if (error instanceof DeepSearchAPIError) { this.logger.error("DeepSearch API 调用失败", error); throw error; } if ((error as Error).name === "AbortError") { const timeoutError = new DeepSearchAPIError("DeepSearch API 请求超时", { cause: error as Error }); this.logger.error("DeepSearch API 请求超时", timeoutError); throw timeoutError; } const wrapped = new DeepSearchAPIError(`DeepSearch API 请求失败: ${(error as Error).message}`, { cause: error as Error, }); this.logger.error("DeepSearch API 调用过程中发生异常", wrapped); throw wrapped; } finally { clearTimeout(timeout); } }