@yyaylt/zhipu-web-search-mcp-server 1.0.1

package/dist/schemas/webSearch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webSearch.js","sourceRoot":"","sources":["../../src/schemas/webSearch.ts"],"names":[],"mappings":"AAAA,iCAAiC;AAEjC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,cAAc,EACd,eAAe,EACf,aAAa,EACd,MAAM,iBAAiB,CAAC;AAEzB,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC;KAClC,MAAM,CAAC;IACN,YAAY,EAAE,CAAC;SACZ,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,EAAE,WAAW,CAAC;SACnB,GAAG,CAAC,EAAE,EAAE,kBAAkB,CAAC;SAC3B,QAAQ,CAAC,sBAAsB,CAAC;IAEnC,aAAa,EAAE,CAAC;SACb,UAAU,CAAC,cAAc,CAAC;SAC1B,OAAO,CAAC,cAAc,CAAC,KAAK,CAAC;SAC7B,QAAQ,CACP,4FAA4F,CAC7F;IAEH,aAAa,EAAE,CAAC;SACb,OAAO,EAAE;SACT,OAAO,CAAC,KAAK,CAAC;SACd,QAAQ,CACP,8CAA8C,CAC/C;IAEH,KAAK,EAAE,CAAC;SACL,MAAM,EAAE;SACR,GAAG,EAAE;SACL,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,EAAE,CAAC;SACP,OAAO,CAAC,EAAE,CAAC;SACX,QAAQ,CACP,0HAA0H,CAC3H;IAEH,oBAAoB,EAAE,CAAC;SACpB,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACP,+EAA+E,CAChF;IAEH,qBAAqB,EAAE,CAAC;SACrB,UAAU,CAAC,eAAe,CAAC;SAC3B,OAAO,CAAC,eAAe,CAAC,QAAQ,CAAC;SACjC,QAAQ,CACP,sFAAsF,CACvF;IAEH,YAAY,EAAE,CAAC;SACZ,UAAU,CAAC,aAAa,CAAC;SACzB,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC;SAC7B,QAAQ,CACP,6DAA6D,CAC9D;IAEH,OAAO,EAAE,CAAC;SACP,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,GAAG,CAAC;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,sCAAsC,CAAC;CACpD,CAAC;KACD,MAAM,EAAE,CAAC"}

package/dist/services/webSearchApi.d.ts

@@ -0,0 +1,15 @@
+import type { WebSearchApiRequest, WebSearchResponse } from "../types.js";
+/**
+ * 调用智谱 Web Search API。
+ * @param apiKey 智谱 API Key
+ * @param params 搜索请求参数
+ * @returns 搜索响应
+ */
+export declare function callWebSearch(apiKey: string, params: WebSearchApiRequest): Promise<WebSearchResponse>;
+/**
+ * 将 API 异常转换为可读、可操作的中文错误提示。
+ * 兜底分支不向客户端返回原始错误内容，仅将详细错误写入 stderr 供本地排查，
+ * 避免向 MCP 客户端泄露内部路径、服务地址等敏感信息。
+ */
+export declare function handleApiError(error: unknown): string;
+//# sourceMappingURL=webSearchApi.d.ts.map

package/dist/services/webSearchApi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webSearchApi.d.ts","sourceRoot":"","sources":["../../src/services/webSearchApi.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAE1E;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,mBAAmB,GAC1B,OAAO,CAAC,iBAAiB,CAAC,CAkB5B;AASD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CA+BrD"}

package/dist/services/webSearchApi.js

@@ -0,0 +1,80 @@
+// Web Search API 客户端服务，负责与智谱开放平台通信
+import axios from "axios";
+import { API_BASE_URL, REQUEST_TIMEOUT_MS } from "../constants.js";
+/**
+ * 调用智谱 Web Search API。
+ * @param apiKey 智谱 API Key
+ * @param params 搜索请求参数
+ * @returns 搜索响应
+ */
+export async function callWebSearch(apiKey, params) {
+    try {
+        const response = await axios.post(API_BASE_URL, params, {
+            timeout: REQUEST_TIMEOUT_MS,
+            headers: {
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+                "Authorization": `Bearer ${apiKey}`
+            }
+        });
+        return response.data;
+    }
+    catch (error) {
+        throw error;
+    }
+}
+// 错误码到建议操作的映射（智谱官方错误码）
+const ERROR_SUGGESTIONS = {
+    "1701": "网络搜索并发已达上限，请稍后重试或减少并发请求。",
+    "1702": "系统未找到可用的搜索引擎服务，请检查配置或联系管理员。",
+    "1703": "搜索引擎未返回有效数据，请调整查询条件后重试。"
+};
+/**
+ * 将 API 异常转换为可读、可操作的中文错误提示。
+ * 兜底分支不向客户端返回原始错误内容，仅将详细错误写入 stderr 供本地排查，
+ * 避免向 MCP 客户端泄露内部路径、服务地址等敏感信息。
+ */
+export function handleApiError(error) {
+    if (axios.isAxiosError(error)) {
+        const axiosError = error;
+        if (axiosError.response) {
+            const status = axiosError.response.status;
+            const body = axiosError.response.data;
+            // 尝试解析智谱业务错误码
+            const bizCode = extractBizCode(body);
+            if (bizCode && ERROR_SUGGESTIONS[bizCode]) {
+                return `搜索失败（错误码 ${bizCode}）：${ERROR_SUGGESTIONS[bizCode]}`;
+            }
+            if (status === 401) {
+                return "认证失败：请检查 ZHIPU_API_KEY 环境变量是否正确设置。";
+            }
+            if (status === 429) {
+                return "请求过于频繁：网络搜索并发已达上限，请稍后重试。";
+            }
+            return `API 请求失败，HTTP 状态码 ${status}。`;
+        }
+        if (axiosError.code === "ECONNABORTED") {
+            return "请求超时：网络搜索服务响应过慢，请稍后重试。";
+        }
+        if (axiosError.code === "ECONNREFUSED") {
+            return "网络错误：无法连接到智谱开放平台，请检查网络。";
+        }
+    }
+    // 详细错误仅写入 stderr（stdio 服务器日志通道，供开发者本地排查），不返回给客户端
+    console.error("智谱 Web Search 调用发生未知错误:", error);
+    return `发生未知错误，请稍后重试或联系管理员。`;
+}
+// 从错误响应体中提取业务错误码
+function extractBizCode(body) {
+    if (body &&
+        typeof body === "object" &&
+        "error" in body &&
+        body.error &&
+        typeof body.error === "object" &&
+        "code" in body.error) {
+        const code = body.error.code;
+        return typeof code === "string" ? code : undefined;
+    }
+    return undefined;
+}
+//# sourceMappingURL=webSearchApi.js.map

package/dist/services/webSearchApi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webSearchApi.js","sourceRoot":"","sources":["../../src/services/webSearchApi.ts"],"names":[],"mappings":"AAAA,mCAAmC;AAEnC,OAAO,KAAqB,MAAM,OAAO,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAGnE;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,MAAc,EACd,MAA2B;IAE3B,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,IAAI,CAC/B,YAAY,EACZ,MAAM,EACN;YACE,OAAO,EAAE,kBAAkB;YAC3B,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,QAAQ,EAAE,kBAAkB;gBAC5B,eAAe,EAAE,UAAU,MAAM,EAAE;aACpC;SACF,CACF,CAAC;QACF,OAAO,QAAQ,CAAC,IAAI,CAAC;IACvB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,uBAAuB;AACvB,MAAM,iBAAiB,GAA2B;IAChD,MAAM,EAAE,0BAA0B;IAClC,MAAM,EAAE,6BAA6B;IACrC,MAAM,EAAE,yBAAyB;CAClC,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,IAAI,KAAK,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9B,MAAM,UAAU,GAAG,KAAsC,CAAC;QAC1D,IAAI,UAAU,CAAC,QAAQ,EAAE,CAAC;YACxB,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,MAAM,CAAC;YAC1C,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,IAAe,CAAC;YAEjD,cAAc;YACd,MAAM,OAAO,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;YACrC,IAAI,OAAO,IAAI,iBAAiB,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC1C,OAAO,YAAY,OAAO,KAAK,iBAAiB,CAAC,OAAO,CAAC,EAAE,CAAC;YAC9D,CAAC;YAED,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;gBACnB,OAAO,oCAAoC,CAAC;YAC9C,CAAC;YACD,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;gBACnB,OAAO,0BAA0B,CAAC;YACpC,CAAC;YACD,OAAO,qBAAqB,MAAM,GAAG,CAAC;QACxC,CAAC;QACD,IAAI,UAAU,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;YACvC,OAAO,wBAAwB,CAAC;QAClC,CAAC;QACD,IAAI,UAAU,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;YACvC,OAAO,yBAAyB,CAAC;QACnC,CAAC;IACH,CAAC;IACD,iDAAiD;IACjD,OAAO,CAAC,KAAK,CAAC,yBAAyB,EAAE,KAAK,CAAC,CAAC;IAChD,OAAO,qBAAqB,CAAC;AAC/B,CAAC;AAED,iBAAiB;AACjB,SAAS,cAAc,CAAC,IAAa;IACnC,IACE,IAAI;QACJ,OAAO,IAAI,KAAK,QAAQ;QACxB,OAAO,IAAI,IAAI;QACf,IAAI,CAAC,KAAK;QACV,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ;QAC9B,MAAM,IAAI,IAAI,CAAC,KAAK,EACpB,CAAC;QACD,MAAM,IAAI,GAAI,IAAI,CAAC,KAA2B,CAAC,IAAI,CAAC;QACpD,OAAO,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;IACrD,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,47 @@
+export interface WebSearchResultItem {
+    title: string;
+    content: string;
+    link: string;
+    media: string;
+    icon: string;
+    refer: string;
+    publish_date: string;
+}
+export interface WebSearchIntentItem {
+    query: string;
+    intent: "SEARCH_ALL" | "SEARCH_NONE" | "SEARCH_ALWAYS";
+    keywords: string;
+}
+export interface WebSearchResponse {
+    id: string;
+    created: number;
+    request_id: string;
+    search_intent: WebSearchIntentItem[];
+    search_result: WebSearchResultItem[];
+}
+export interface WebSearchError {
+    error: {
+        code: string;
+        message: string;
+    };
+}
+export interface WebSearchApiRequest {
+    search_query: string;
+    search_engine: string;
+    search_intent: boolean;
+    count?: number;
+    search_domain_filter?: string;
+    search_recency_filter?: string;
+    content_size?: "medium" | "high";
+    request_id?: string;
+    user_id?: string;
+}
+export type WebSearchToolOutput = {
+    id: string;
+    created: number;
+    request_id: string;
+    search_intent: WebSearchIntentItem[];
+    count: number;
+    results: WebSearchResultItem[];
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;CACtB;AAGD,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,YAAY,GAAG,aAAa,GAAG,eAAe,CAAC;IACvD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAGD,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,mBAAmB,EAAE,CAAC;IACrC,aAAa,EAAE,mBAAmB,EAAE,CAAC;CACtC;AAGD,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE;QACL,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH;AAGD,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,OAAO,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,YAAY,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAGD,MAAM,MAAM,mBAAmB,GAAG;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,mBAAmB,EAAE,CAAC;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,mBAAmB,EAAE,CAAC;CAChC,CAAC"}

package/dist/types.js

@@ -0,0 +1,3 @@
+// 智谱 Web Search API 请求/响应类型定义
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,8BAA8B"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@yyaylt/zhipu-web-search-mcp-server",
+  "version": "1.0.1",
+  "description": "MCP server for ZHIPU AI Web Search API integration",
+  "keywords": [
+    "zhipu",
+    "web-search",
+    "mcp-server"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://gitee.com/yyaylt/zhipu-web-search-mcp-server.git"
+  },
+  "license": "Apache-2.0",
+  "author": "lost_fish",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "./dist/index.d.ts",
+  "directories": {
+    "doc": "docs"
+  },
+  "scripts": {
+    "start": "node dist/index.js",
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc",
+    "clean": "rimraf dist",
+    "test": "node --test --import tsx \"tests/**/*.test.ts\""
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "axios": "^1.7.9",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "rimraf": "^6.0.1",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist/**/*",
+    "src/**/*",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ]
+}

package/src/constants.ts

@@ -0,0 +1,40 @@
+// 智谱 Web Search API 相关常量定义
+
+// API 基础地址（智谱开放平台）
+export const API_BASE_URL = "https://open.bigmodel.cn/api/paas/v4/web_search";
+
+// 响应内容的最大字符数，防止单次返回内容过大
+export const CHARACTER_LIMIT = 25000;
+
+// 支持的搜索引擎编码
+export const SEARCH_ENGINES = {
+  STORE: "search_std",
+  PRO: "search_pro",
+  PRO_SOGOU: "search_pro_sogou",
+  PRO_QUARK: "search_pro_quark"
+} as const;
+
+// 时间范围过滤可选值
+export const RECENCY_FILTERS = {
+  ONE_DAY: "oneDay",
+  ONE_WEEK: "oneWeek",
+  ONE_MONTH: "oneMonth",
+  ONE_YEAR: "oneYear",
+  NO_LIMIT: "noLimit"
+} as const;
+
+// 内容长度选项
+export const CONTENT_SIZES = {
+  MEDIUM: "medium",
+  HIGH: "high"
+} as const;
+
+// 各搜索引擎支持的 count 枚举约束
+export const COUNT_BY_ENGINE: Record<string, number[]> = {
+  [SEARCH_ENGINES.STORE]: [10, 20, 30, 40, 50],
+  [SEARCH_ENGINES.PRO]: [10, 20, 30, 40, 50],
+  [SEARCH_ENGINES.PRO_SOGOU]: [10, 20, 30, 40, 50]
+};
+
+// 请求超时时间（毫秒）
+export const REQUEST_TIMEOUT_MS = 30000;

package/src/index.ts

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+/**
+ * 智谱 Web Search MCP Server
+ *
+ * 基于智谱开放平台 Web Search API（/paas/v4/web_search）实现的 MCP 服务器。
+ * 通过标准输入输出（stdio）与客户端通信，提供网络搜索能力。
+ *
+ * 环境变量：
+ *   ZHIPU_API_KEY - 智谱 API Key（必填），从 https://bigmodel.cn/usercenter/proj-mgmt/apikeys 获取
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { callWebSearch, handleApiError } from "./services/webSearchApi.js";
+import { WebSearchInputSchema } from "./schemas/webSearch.js";
+import { CHARACTER_LIMIT } from "./constants.js";
+import type { WebSearchToolOutput } from "./types.js";
+
+// 创建 MCP 服务器实例
+const server = new McpServer({
+  name: "zhipu-web-search-mcp-server",
+  version: "1.0.0"
+});
+
+// 将搜索结果格式化为 Markdown 文本
+function formatResultsMarkdown(output: WebSearchToolOutput): string {
+  const lines: string[] = [];
+
+  if (output.search_intent && output.search_intent.length > 0) {
+    const intent = output.search_intent[0];
+    lines.push(`## 搜索意图识别`);
+    lines.push(`- 原始查询：${intent.query}`);
+    lines.push(`- 识别意图：${intent.intent}`);
+    if (intent.keywords) {
+      lines.push(`- 改写关键词：${intent.keywords}`);
+    }
+    lines.push("");
+  }
+
+  if (output.results.length === 0) {
+    lines.push("未找到相关搜索结果。");
+    return lines.join("\n");
+  }
+
+  lines.push(`# 搜索结果 (${output.count})`);
+  lines.push("");
+  output.results.forEach((item, index) => {
+    lines.push(`## ${index + 1}. ${item.title}`);
+    if (item.publish_date) {
+      lines.push(`**发布时间：** ${item.publish_date}`);
+    }
+    if (item.media) {
+      lines.push(`**来源：** ${item.media}`);
+    }
+    if (item.link) {
+      lines.push(`**链接：** ${item.link}`);
+    }
+    lines.push("");
+    lines.push(item.content || "（无摘要）");
+    lines.push("");
+  });
+  return lines.join("\n");
+}
+
+// 注册网络搜索工具
+server.registerTool(
+  "zhipu_web_search",
+  {
+    title: "智谱网络搜索",
+    description: `通过智谱开放平台 Web Search API 执行网络搜索，返回网页标题、摘要、链接、网站名称等信息。
+
+支持四种搜索引擎：search_std（智谱基础版）、search_pro（智谱高阶版）、search_pro_sogou（搜狗）、search_pro_quark（夸克搜索）。
+
+Args:
+  - search_query (string): 需要搜索的内容，建议不超过 70 个字符
+  - search_engine (string): 搜索引擎编码（默认 search_std）
+  - search_intent (boolean): 是否执行搜索意图识别（默认 false）
+  - count (number): 返回结果条数，1-50（默认 10）
+  - search_domain_filter (string): 白名单域名过滤，仅返回指定域名内容（可选）
+  - search_recency_filter (string): 时间范围过滤：oneDay/oneWeek/oneMonth/oneYear/noLimit（默认 noLimit）
+  - content_size (string): 返回内容长短：medium/high（默认 medium）
+  - user_id (string): 终端用户唯一 ID，长度 6-128 字符（可选）
+
+Returns:
+  Markdown 文本：搜索意图识别结果 + 搜索结果列表（标题、发布时间、来源、链接、摘要）
+  同时返回结构化 JSON 数据。
+
+Examples:
+  - "帮我搜索今天的天气" -> search_query="今天北京天气"
+  - "搜索 GPT-5 相关新闻" -> search_query="GPT-5 新闻", search_recency_filter="oneWeek"
+  - "在夸克上搜索 Python 教程" -> search_query="Python 教程", search_engine="search_pro_quark"
+
+Error Handling:
+  - 1701：网络搜索并发已达上限，稍后重试
+  - 1702：系统未找到可用的搜索引擎服务
+  - 1703：搜索引擎未返回有效数据，请调整查询条件`,
+    inputSchema: WebSearchInputSchema,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    }
+  },
+  async (params) => {
+    const apiKey = process.env.ZHIPU_API_KEY;
+    if (!apiKey) {
+      return {
+        isError: true,
+        content: [
+          {
+            type: "text" as const,
+            text: "缺少 ZHIPU_API_KEY 环境变量。请在运行前通过环境变量设置智谱 API Key，获取地址：https://bigmodel.cn/usercenter/proj-mgmt/apikeys"
+          }
+        ]
+      };
+    }
+
+    try {
+      const data = await callWebSearch(apiKey, {
+        search_query: params.search_query,
+        search_engine: params.search_engine,
+        search_intent: params.search_intent,
+        count: params.count,
+        ...(params.search_domain_filter
+          ? { search_domain_filter: params.search_domain_filter }
+          : {}),
+        search_recency_filter: params.search_recency_filter,
+        content_size: params.content_size,
+        ...(params.user_id ? { user_id: params.user_id } : {})
+      });
+
+      const results = data.search_result ?? [];
+      const output: WebSearchToolOutput = {
+        id: data.id,
+        created: data.created,
+        request_id: data.request_id,
+        search_intent: data.search_intent ?? [],
+        count: results.length,
+        results
+      };
+
+      let text = formatResultsMarkdown(output);
+
+      // 超长截断，防止响应过大
+      if (text.length > CHARACTER_LIMIT) {
+        const keepItems = Math.max(1, Math.floor(results.length / 2));
+        const truncated = {
+          ...output,
+          results: results.slice(0, keepItems)
+        };
+        text = `${formatResultsMarkdown(truncated)}\n\n> 响应因过长被截断（原 ${results.length} 条），可减少 count 或增加关键词精度以查看更多结果。`;
+      }
+
+      return {
+        content: [{ type: "text" as const, text }],
+        structuredContent: output
+      };
+    } catch (error) {
+      return {
+        isError: true,
+        content: [
+          {
+            type: "text" as const,
+            text: handleApiError(error)
+          }
+        ]
+      };
+    }
+  }
+);
+
+// 主函数：通过 stdio 启动服务器
+async function main() {
+  if (!process.env.ZHIPU_API_KEY) {
+    console.error("ERROR: ZHIPU_API_KEY 环境变量是必需的");
+    process.exit(1);
+  }
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("智谱 Web Search MCP server 正在运行 (stdio)");
+}
+
+main().catch((error) => {
+  console.error("服务器启动失败:", error);
+  process.exit(1);
+});

package/src/schemas/webSearch.ts

@@ -0,0 +1,72 @@
+// Web Search 工具的 Zod 输入校验 schema
+
+import { z } from "zod";
+import {
+  SEARCH_ENGINES,
+  RECENCY_FILTERS,
+  CONTENT_SIZES
+} from "../constants.js";
+
+export const WebSearchInputSchema = z
+  .object({
+    search_query: z
+      .string()
+      .min(1, "搜索关键词不能为空")
+      .max(70, "搜索关键词不能超过 70 个字符")
+      .describe("需要搜索的内容，建议不超过 70 个字符"),
+
+    search_engine: z
+      .nativeEnum(SEARCH_ENGINES)
+      .default(SEARCH_ENGINES.STORE)
+      .describe(
+        "要调用的搜索引擎编码：search_std（智谱基础版）、search_pro（智谱高阶版）、search_pro_sogou（搜狗）、search_pro_quark（夸克搜索）"
+      ),
+
+    search_intent: z
+      .boolean()
+      .default(false)
+      .describe(
+        "是否执行搜索意图识别。true：先识别是否有搜索意图再搜索；false：跳过识别直接搜索"
+      ),
+
+    count: z
+      .number()
+      .int()
+      .min(1)
+      .max(50)
+      .default(10)
+      .describe(
+        "返回结果的条数，范围 1-50。注意：search_pro_sogou 仅支持枚举值 10/20/30/40/50，且同时指定 search_domain_filter 和 search_recency_filter 时 count 不生效"
+      ),
+
+    search_domain_filter: z
+      .string()
+      .optional()
+      .describe(
+        "限定搜索结果范围的白名单域名（如 www.example.com）。仅 search_std、search_pro、search_pro_sogou 支持"
+      ),
+
+    search_recency_filter: z
+      .nativeEnum(RECENCY_FILTERS)
+      .default(RECENCY_FILTERS.NO_LIMIT)
+      .describe(
+        "搜索指定时间范围内的网页。可选值：oneDay（一天内）、oneWeek（一周内）、oneMonth（一个月内）、oneYear（一年内）、noLimit（不限，默认）"
+      ),
+
+    content_size: z
+      .nativeEnum(CONTENT_SIZES)
+      .default(CONTENT_SIZES.MEDIUM)
+      .describe(
+        "控制返回网页内容长短：medium（摘要信息，适合常规问答）、high（最大化上下文，信息量更大，适合需要细节的场景）"
+      ),
+
+    user_id: z
+      .string()
+      .min(6)
+      .max(128)
+      .optional()
+      .describe("终端用户的唯一 ID，用于平台对非法活动的干预，长度 6-128 个字符")
+  })
+  .strict();
+
+export type WebSearchInput = z.infer<typeof WebSearchInputSchema>;

package/src/services/webSearchApi.ts

@@ -0,0 +1,95 @@
+// Web Search API 客户端服务，负责与智谱开放平台通信
+
+import axios, { AxiosError } from "axios";
+import { API_BASE_URL, REQUEST_TIMEOUT_MS } from "../constants.js";
+import type { WebSearchApiRequest, WebSearchResponse } from "../types.js";
+
+/**
+ * 调用智谱 Web Search API。
+ * @param apiKey 智谱 API Key
+ * @param params 搜索请求参数
+ * @returns 搜索响应
+ */
+export async function callWebSearch(
+  apiKey: string,
+  params: WebSearchApiRequest
+): Promise<WebSearchResponse> {
+  try {
+    const response = await axios.post<WebSearchResponse>(
+      API_BASE_URL,
+      params,
+      {
+        timeout: REQUEST_TIMEOUT_MS,
+        headers: {
+          "Content-Type": "application/json",
+          "Accept": "application/json",
+          "Authorization": `Bearer ${apiKey}`
+        }
+      }
+    );
+    return response.data;
+  } catch (error) {
+    throw error;
+  }
+}
+
+// 错误码到建议操作的映射（智谱官方错误码）
+const ERROR_SUGGESTIONS: Record<string, string> = {
+  "1701": "网络搜索并发已达上限，请稍后重试或减少并发请求。",
+  "1702": "系统未找到可用的搜索引擎服务，请检查配置或联系管理员。",
+  "1703": "搜索引擎未返回有效数据，请调整查询条件后重试。"
+};
+
+/**
+ * 将 API 异常转换为可读、可操作的中文错误提示。
+ * 兜底分支不向客户端返回原始错误内容，仅将详细错误写入 stderr 供本地排查，
+ * 避免向 MCP 客户端泄露内部路径、服务地址等敏感信息。
+ */
+export function handleApiError(error: unknown): string {
+  if (axios.isAxiosError(error)) {
+    const axiosError = error as AxiosError<WebSearchResponse>;
+    if (axiosError.response) {
+      const status = axiosError.response.status;
+      const body = axiosError.response.data as unknown;
+
+      // 尝试解析智谱业务错误码
+      const bizCode = extractBizCode(body);
+      if (bizCode && ERROR_SUGGESTIONS[bizCode]) {
+        return `搜索失败（错误码 ${bizCode}）：${ERROR_SUGGESTIONS[bizCode]}`;
+      }
+
+      if (status === 401) {
+        return "认证失败：请检查 ZHIPU_API_KEY 环境变量是否正确设置。";
+      }
+      if (status === 429) {
+        return "请求过于频繁：网络搜索并发已达上限，请稍后重试。";
+      }
+      return `API 请求失败，HTTP 状态码 ${status}。`;
+    }
+    if (axiosError.code === "ECONNABORTED") {
+      return "请求超时：网络搜索服务响应过慢，请稍后重试。";
+    }
+    if (axiosError.code === "ECONNREFUSED") {
+      return "网络错误：无法连接到智谱开放平台，请检查网络。";
+    }
+  }
+  // 详细错误仅写入 stderr（stdio 服务器日志通道，供开发者本地排查），不返回给客户端
+  console.error("智谱 Web Search 调用发生未知错误:", error);
+  return `发生未知错误，请稍后重试或联系管理员。`;
+}
+
+// 从错误响应体中提取业务错误码
+function extractBizCode(body: unknown): string | undefined {
+  if (
+    body &&
+    typeof body === "object" &&
+    "error" in body &&
+    body.error &&
+    typeof body.error === "object" &&
+    "code" in body.error
+  ) {
+    const code = (body.error as { code: unknown }).code;
+    return typeof code === "string" ? code : undefined;
+  }
+  return undefined;
+}

package/src/types.ts

@@ -0,0 +1,59 @@
+// 智谱 Web Search API 请求/响应类型定义
+
+// 搜索结果条目
+export interface WebSearchResultItem {
+  title: string;
+  content: string;
+  link: string;
+  media: string;
+  icon: string;
+  refer: string;
+  publish_date: string;
+}
+
+// 搜索意图识别结果
+export interface WebSearchIntentItem {
+  query: string;
+  intent: "SEARCH_ALL" | "SEARCH_NONE" | "SEARCH_ALWAYS";
+  keywords: string;
+}
+
+// API 成功响应
+export interface WebSearchResponse {
+  id: string;
+  created: number;
+  request_id: string;
+  search_intent: WebSearchIntentItem[];
+  search_result: WebSearchResultItem[];
+}
+
+// API 错误响应
+export interface WebSearchError {
+  error: {
+    code: string;
+    message: string;
+  };
+}
+
+// 发送给 API 的请求参数
+export interface WebSearchApiRequest {
+  search_query: string;
+  search_engine: string;
+  search_intent: boolean;
+  count?: number;
+  search_domain_filter?: string;
+  search_recency_filter?: string;
+  content_size?: "medium" | "high";
+  request_id?: string;
+  user_id?: string;
+}
+
+// 工具返回值（结构化输出）
+export type WebSearchToolOutput = {
+  id: string;
+  created: number;
+  request_id: string;
+  search_intent: WebSearchIntentItem[];
+  count: number;
+  results: WebSearchResultItem[];
+};