汉典网 MCP Server

汉典网 (zdic.net) 的 MCP Server v1.1.0，支持汉字（单字）、词语（多字词）、成语三种条目的全量结构化查询。

概述

本 MCP Server 以 zdic.net（汉典）为数据源，完整解析网页上所有栏目，将数据以结构化 JSON 返回，供 AI Agent 下游消费。相比 v1.0 的简化输出，v1.1.0 覆盖以下全部栏目：

| 条目类型 | 覆盖栏目 | |----------|----------| | 字（单汉字） | 部首/笔画/结构 · 基本解释 · 详细解释 · 國語辭典 · 康熙字典 · 说文解字 · 音韵方言 · 字源字形 · 常用词组 | | 词语（2–3字） | 基本解释 · 详细解释 · 近义词 · 反义词 · 英语翻译 · 相关词语 | | 成语（≥4字） | 基本解释 · 出处 · 典故 · 近义词 · 反义词 · 例句 · 英语翻译 · 结构分析 |

安装

npm install -g @dhcckb/zdic-mcp-server

或通过 npx 直接运行：

npx @dhcckb/zdic-mcp-server

工具

1. zdic_lookup — 通用查询

自动检测输入为字（单字符）、词语（2–3字）或成语（≥4字），从 zdic.net 抓取并解析对应页面的全量结构化数据。

参数：

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | query | string | 是 | 待查询的字、词语或成语 | | sections | string[] | 否 | 限定返回的栏目（见下方对照表） | | includeRaw | boolean | 否 | 是否附带原始 HTML（默认 false） |

栏目过滤对照表：

| 条目类型 | sections 可选值 | |----------|------------------| | 字 (char) | basic, detailed, guoyu, kangxi, shuowen, phonology, etymology, compounds | | 词语 (word) | basic, detailed, synonyms, antonyms, english, related | | 成语 (idiom) | basic, source, allusion, synonyms, antonyms, examples, english, structure |

返回字段映射：

字（单汉字）— CharResult

| 字段 | 类型 | 说明 | |------|------|------| | type | "char" | 条目类型标识 | | query | string | 原始查询 | | url | string | zdic.net 页面 URL | | pinyin | string | 拼音 | | radical | string | 部首 | | strokes | number | 总笔画数 | | structure | string | 字形结构 | | basic | object | 基本解释（含拼音、部首、笔画、结构、五笔/仓颉/郑码、Unicode、基本释义、详细释义） | | detailed | object | 详细解释（按词性分组的义项列表） | | guoyu | object | 國語辭典 | | kangxi | object | 康熙字典（原文、康熙笔画、康熙部首） | | shuowen | object | 说文解字（原文、说文部首） | | phonology | object | 音韵方言（上古音/中古音/现代音/方言分段） | | etymology | object | 字源字形（描述 + 图片URL列表） | | compounds | array | 常用词组列表 |

词语（2–3字）— WordResult

| 字段 | 类型 | 说明 | |------|------|------| | type | "word" | 条目类型标识 | | query | string | 原始查询 | | url | string | zdic.net 页面 URL | | pinyin | string | 拼音 | | basic | object | 基本解释 | | detailed | object | 详细解释（按词性分组的义项列表） | | synonyms | string[] | 近义词 | | antonyms | string[] | 反义词 | | english | string[] | 英语翻译 | | related | object[] | 相关词语（含 word 和 url） |

成语（≥4字）— IdiomResult

| 字段 | 类型 | 说明 | |------|------|------| | type | "idiom" | 条目类型标识 | | query | string | 原始查询 | | url | string | zdic.net 页面 URL | | pinyin | string | 拼音 | | basic | object | 基本解释 | | source | object | 出处（原文与原始出处） | | allusion | object | 典故 | | synonyms | string[] | 近义成语 | | antonyms | string[] | 反义成语 | | examples | string[] | 例句 | | english | string[] | 英语翻译 | | structure | object | 结构分析（感情色彩、语法结构、用法） |

2. zdic_search — 模糊搜索

关键词搜索 zdic.net，返回匹配条目列表。

参数：

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | keyword | string | 是 | 搜索关键词 | | entryType | string | 否 | char / word / idiom / auto，默认 auto | | limit | integer | 否 | 返回数量（1–50），默认 10 |

3. zdic_batch_lookup — 批量查询

批量并发查询多个条目。

参数：

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | queries | string[] | 是 | 条目列表（最多 20 个） | | sections | string[] | 否 | 同 zdic_lookup | | concurrency | integer | 否 | 并发数（1–10），默认 3 |

运行方式

本地开发

npm install
npm run build
npm start

通过 npx 运行

npx @dhcckb/zdic-mcp-server

MCP 客户端配置示例

{
  "mcpServers": {
    "zdic": {
      "command": "npx",
      "args": ["@dhcckb/zdic-mcp-server"]
    }
  }
}

环境变量

| 变量 | 默认值 | 说明 | |------|--------|------| | ZDIC_BASE_URL | https://zdic.net | 汉典网基础 URL | | ZDIC_TIMEOUT_MS | 10000 | HTTP 请求超时（毫秒） | | ZDIC_USER_AGENT | ZdicMCPServer/1.1 ... | 自定义 User-Agent |

目录结构

zdic-mcp-server/
├── package.json          # 包配置（含 mcp.tools / mcp.transport）
├── tsconfig.json         # TypeScript 编译选项
├── README.md             # 本文档
├── .gitignore
└── src/
    ├── index.ts          # MCP Server 入口（stdio transport + 3 工具处理）
    ├── zdic-client.ts    # HTTP 客户端 + cheerio HTML 全量解析器
    └── types.ts          # TypeScript 类型定义 + 条目类型检测

技术架构

• 运行环境: Node.js ≥ 18 LTS
• 模块系统: ESM（"type": "module"）
• MCP SDK: @modelcontextprotocol/sdk（stdio transport）
• HTML 解析: cheerio（服务端 DOM 解析，无需浏览器无头渲染）
• HTTP 请求: Node.js 原生 fetch（>= 18 内置）

错误处理

所有错误均返回结构化 JSON，包含 error.code 和 error.message，不抛出未捕获异常：

{
  "error": {
    "code": "NOT_FOUND",
    "message": "未找到词条\"xxx\"，请尝试使用 zdic_search 搜索。"
  }
}

错误码：NOT_FOUND / HTTP_ERROR / TIMEOUT / NETWORK_ERROR / API_ERROR / LOOKUP_ERROR / BATCH_ERROR / INVALID_PARAM / INTERNAL_ERROR

许可证

MIT