📜 DaoZang Reasoner MCP

道藏考据 — 先溯源，后推理

MCP Server 285,117 经文块 bge-m3 语义检索行号级原文溯源已在 Smithery 发布 Quality Score 98/100

这是什么

把 SkillHub 技能 @indiv-godners/daozang-reasoner （道藏考据方法论：拆题 → 溯源 → 核验 → 推理 → 标注）与配套的 @indiv-godners/dao-zang（道藏离线检索）合并为一个 MCP 服务器：既是检索工具，也是作业规范。

数据全部取自 Hugging Face 数据集 Godners/DaoZang — markdowns/（3,152 篇原文 Markdown）＋ data/*.parquet （285,117 个文本块，含 BAAI/bge-m3 1024 维向量，已 L2 归一化）。

三种安装形态

① Smithery（推荐，一键装）

已发布到 Smithery 注册表，形态为 stdio / MCPB 本地包：由 Smithery 分发 .mcpb，在你的机器上经 uv 运行，无需付费托管，也没有远程算力/内存限制。

Smithery 质量评分 98 / 100（发布门槛 80）： Capability Quality 38/40 · Server Metadata 35/35 · Configuration UX 25/25。

smithery.ai/servers/godners/daozang-mcp

② Gradio MCP 版（可上线为远程端点）

Hugging Face 官方「Spaces as MCP servers」方案。发布为 Gradio Space 后自动获得 MCP 徽章，任何 MCP 客户端一键添加。端点形如 https://<space>.hf.space/gradio_api/mcp/。

代码见本 Space 的 gradio/ 目录。

③ Docker / HTTP 版

标准 MCP Streamable HTTP 服务器，端点 /mcp；也支持 stdio 传输供本地桌面客户端（Claude Desktop / Cursor 等）使用。可跑在任意容器平台。

代码见本 Space 的 mcp/ 目录。

从 Smithery 安装

安装 Smithery CLI 后一行命令装进本地客户端（需 Node.js 20+）：

npm install -g smithery@latest
smithery mcp add godners/daozang-mcp --client claude

或把 MCPB 包直接接到任意 MCP 客户端（与 Smithery 宿主实际执行的命令一致）：

{
  "mcpServers": {
    "daozang-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/abs/path/to/bundle", "mcpb_entry.py"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "DAOZANG_DATA_DIR": "/abs/path/to/daozang-data"
      }
    }
  }
}

⚠️ 必须带 --client：本服务器是 stdio 本地包，没有远程 URL；不带 --client 会去建「远程连接」，那是连不上的。

首次运行会从 Godners/DaoZang 下载约 3 GB 语料与向量（按哈希校验、增量同步）并建立内存索引；期间服务器已就绪， corpus_status 可查看进度。

各客户端现成配置

本 Space 的 mcp-config/ 目录提供 10 份开箱模板 + 一键安装器：

cd mcp-config
python install.py --proxy http://192.168.109.5:8080   # 下载解包 + 渲染真实路径配置

覆盖 Claude Desktop / Claude Code / Cursor / VS Code / Windsurf / Zed / Codex CLI / 通用 stdio（uv 与纯 Python 两版）/ 通用 HTTP 远程。

客户端	配置文件	顶层键
Claude Desktop	`claude_desktop_config.json`	`mcpServers`
Claude Code	项目根 `.mcp.json`	`mcpServers`
Cursor	`.cursor/mcp.json`	`mcpServers`
VS Code	`.vscode/mcp.json`	`servers` + `type: stdio`
Windsurf	`~/.codeium/windsurf/mcp_config.json`	`mcpServers`
Zed	`settings.json`	`context_servers`
Codex CLI	`~/.codex/config.toml`	*`[mcp_servers.]`**（TOML）

三个易错点：VS Code 用 servers 而非 mcpServers；Zed 用 context_servers 且值直接是 command/args/env； Codex 是 TOML 且 env 要单独一个表。

关于页面上的 `Local` 徽章

Smithery 服务器页顶部有 Local 徽章，悬停显示 "Runs locally on your machine"。这是正确语义，不是缺陷：本服务以 stdio 形态发布，进程跑在用户本机，Smithery 只负责分发 .mcpb。

徽章由 release 类型决定：

类型	谁运行进程	需要什么	徽章
`stdio`（当前）	用户本机	客户端支持 stdio	Local
`external`	你自己的服务器	公网 HTTPS + Streamable HTTP	无 Local
`hosted`	Smithery	JavaScript 模块	无 Local

想让它跑在服务器上：自建一个公网 HTTPS 的 Streamable HTTP 端点，再以 external 方式发一个 release （本仓库 mcp/server.py 已内置 app = mcp.http_app(path="/mcp")）。硬性要求：约 1.2 GB 常驻内存 + 3 GB 磁盘，建议 ≥ 4 GB 内存的 VPS。

另一条 hosted 路径要求上传 JavaScript 模块（本项目是 Python，需整体改写，且 1.2 GB 常驻向量不适合 serverless），不现实。详见工作区 SMITHERY.md 第八节。

可用工具

工具	中文名	作用
`search_daozang`	检索道藏	语义（bge-m3）/ 关键词（IDF）双引擎检索 285,117 个经文块，可附原文
`get_original_text`	取带行号原文	「落原文」：取带行号原文窗口，`⟦…⟧` 标出命中范围
`get_source_text`	读取经文全文	读取某篇经文的原始 Markdown 全文
`list_sources`	按关键词列经目	按文件名关键词列出经目与各自块数（L0 定名相 / L3 回溯核验）
`daozang_protocol`	道藏考据方法论	返回五步考据方法论、A–D 置信度分级与工具指南
`corpus_status`	馆藏状态	馆藏规模、加载进度、语义引擎可用性（不阻塞握手）

6 个工具全部声明了中文 title、只读注解（readOnlyHint / idempotentHint / openWorldHint）、逐参数描述与 outputSchema（结构化输出），因此获得 Smithery 的 Typed Output 徽章。

本地运行（Docker / HTTP 版）

# 1) 取代码（本 Space 的 mcp/ 目录，或下载 daozang-reasoner-mcp.zip）
git clone https://huggingface.co/spaces/Godners/daozang-reasoner-mcp
cd daozang-reasoner-mcp/mcp

# 2) 安装依赖
pip install -r requirements.txt

# 3) 启动（首次会自动从数据集拉取约 3 GB 数据并按哈希校验建索引）
python server.py            # Streamable HTTP，端点 http://127.0.0.1:7860/mcp

# 或：以 stdio 传输供本地桌面 MCP 客户端使用
MCP_TRANSPORT=stdio python server.py

MCP 客户端配置

远程 HTTP（部署到任意可运行容器的主机后）：

{
  "mcpServers": {
    "daozang-reasoner": {
      "url": "https://<your-host>/mcp"
    }
  }
}

本地 stdio：

{
  "mcpServers": {
    "daozang-reasoner": {
      "command": "python",
      "args": ["/abs/path/to/daozang-reasoner-mcp/server.py"],
      "env": { "MCP_TRANSPORT": "stdio" }
    }
  }
}

设计要点

无需向量数据库

数据集中的向量已 L2 归一化，检索即 embeddings @ q（285k×1024 纯点积，毫秒级），索引常驻内存（float32 ≈ 1.2 GB）。

哈希校验、不重复下载

启动时读取远端清单，对已有文件按 SHA-256（LFS）或 git blob SHA-1（普通文件）逐一校验，一致的不重复下载，只补缺失/不一致的。

原文可溯源

检索返回的是建库时清洗过的正文；get_original_text 通过「清洗重放 + 偏移映射」把块映射回原始 Markdown，输出带行号、带 ⟦命中⟧ 的原文窗口 —— 正式引用的唯一依据。

离线嵌入

查询向量由本地 ONNX Xenova/bge-m3 推理，不调用任何嵌入 API；模型不可用时自动回退关键词引擎并在 search_record 中说明。

⚠️ 关于本 Space 的形态

当前账号为 Hugging Face 免费账户：Static Space 免费，Docker / Gradio Space 需要 PRO 订阅（组织需 Team / Enterprise），而 HF 官方的「Spaces as MCP servers」方案必须使用 Gradio Space。因此本 Space 目前以 Static Space 形态发布，托管完整 MCP 源码、使用文档与打包下载；gradio/ 目录中的 Gradio MCP 版已就绪，账号具备条件后可直接发布为带 MCP 徽章的在线端点。

在 Smithery 上不受此限制：Smithery 的 stdio / MCPB 方式由客户端在本地运行，无需你提供任何公网托管，免费层即可发布——本 MCP 正是以此方式上线。