dsh-local-kb
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
dsh-local-kb
本地知识库:把一堆 Markdown 建成本地向量索引,聊到相关问题时自动检索、带来源注入。 两种形态,同一套内核:
形态 | 用途 | 触发方式 |
MCP 服务 | Claude Desktop / Cursor / 任何 MCP 客户端 | 模型调用 |
DSH 插件 | DeepSeek Harness |
|
嵌入在进程内用 ONNX 跑(bge-small-zh-v1.5 量化版,约 23 MB),不依赖任何外部服务:不要 Open WebUI,不要向量数据库,不要 GPU。
为什么这么做
DeepSeek API 没有 embedding 接口,向量必须自己解决。
查询嵌入是每轮对话都要做的事——起一个 Python 进程意味着每轮 0.5–2 秒启动开销,所以放进 Node 进程内跑。
2 万块 × 512 维只有 35 MB,暴力余弦 30 毫秒级;引 SQLite/faiss 只是增加编译和版本问题。
Related MCP server: SeekLink
支持哪些文档
格式 | 处理方式 |
| 直接读,按标题分块 |
| 转成 Markdown 表格(引号、逗号转义都处理),表格结构保住 |
| 剥掉脚本/样式/导航/页脚,再用 turndown 转 Markdown |
| 按页抽取(pdfjs-dist),每页加 |
| mammoth 转 Markdown,标题层级、列表、加粗都保留 |
解析失败的单个文件不会中断整批:会被跳过并在建索引结束时列出原因(缺依赖、加密 PDF、损坏文件)。
这套设计沿用源项目 kb-forge 的做法(Python 侧是 pypdf / python-docx / trafilatura),在 Node 里用 pdfjs-dist / mammoth / turndown 做等价的事。
快速开始
npm install
# 1. 下载模型(默认走 hf-mirror;海外可设 KB_MIRROR=https://huggingface.co)
npm run fetch-model
# 2. 建索引(指向你的资料目录,可多个 --source;md/pdf/docx/html/csv 混着放没问题)
npm run build-index -- --source /path/to/docs
# 3. 检索
npm run query -- "某个问题" --context已验证:在干净目录里
git clone→npm ci→fetch-model→build-index→query→mcp-smoke→npm test全部通过。
--context 会把真正会注入给模型的那段文本打印出来,方便判断阈值和预算。
作为 MCP 服务
// claude_desktop_config.json
{
"mcpServers": {
"local-kb": {
"command": "node",
"args": ["/absolute/path/to/dsh-local-kb/scripts/mcp-server.mjs"],
"env": {
"KB_INDEX_DIR": "/absolute/path/to/dsh-local-kb/index-data"
}
}
}
}暴露四个工具:
工具 | 作用 |
| 检索,返回片段 + 相似度 + 来源 |
| 后台建索引(只负责启动,进度用 |
| 块数、文档数、模型、最后构建时间、任务进度 |
| 列出已索引的文档与块数 |
协议:JSON-RPC 2.0 over stdio,protocolVersion 2024-11-05,一行一个消息。
验证协议本身:node scripts/mcp-smoke.mjs(真的 spawn 子进程对话)。
自己写 MCP 客户端配置时注意:
env里的KB_INDEX_DIR必须是绝对路径,否则按插件的包根目录解析。
作为 DSH 插件
dsh plugin --profile desktop add /absolute/path/to/dsh-local-kb或手动:profile 的 package.json 里加依赖 + 把 dsh-local-kb 写进 dsh.profile.bundles,然后重装。
装好后:
每条新的用户消息触发一次检索,命中就注入一条带来源的消息;同一会话同一问题只注入一次
注册
kb_search/kb_ingest/kb_status/kb_docs检索失败、超时、索引缺失都静默降级——知识库坏了不影响正常对话
配置
cordis.patch.yml 的 config,或同名环境变量:
配置 | 环境变量 | 默认 | 说明 |
|
|
| 索引目录 |
|
|
| 模型目录 |
|
| 5 | 注入/返回几条 |
|
| 0.45 | 余弦低于此值不注入 |
|
| 1600 | 注入内容字符上限 |
|
| true | 自动注入总开关 |
|
| user | 注入消息角色 |
|
| 0.25 | 词汇重排权重(0 = 纯向量) |
|
| 2 | 同一文档最多保留几块 |
|
| 800 | 检索超时,超时按没命中处理 |
|
| 空 |
|
实测(RTX 4060 Laptop / i7-13650HX / Node 20,CPU 推理)
语料:2,318 篇网页存档(8.09 M 字符,中文规格页为主)
指标 | 数值 |
分块 | 17,701 块 |
全量建索引 | 420 s(约 7 分钟) |
增量重建(无改动) | 2.5 s |
索引体积 | 34.6 MB |
查询嵌入(预热) | p50 4 ms |
端到端检索 | p50 40 ms / p95 225 ms |
检索质量(8 题人工标注) | top-1 6/8、top-3 8/8 |
混合格式验证(Markdown + PDF + Word + HTML + CSV 各一份):5 篇文档 → 7 块,建索引 1.3 s,五种格式的查询都能命中对应内容。
设计要点
分块:标题优先,段落兜底;超长段落按 80 字重叠硬切。
嵌入文本 ≠ 展示文本:建索引时把"产品名/文件名 + 标题 + 小节"拼进嵌入输入。中文厂商页面标题常是"规格参数|台式电脑",型号只在 URL 里,不这么做就永远搜不到。
三路召回:向量 top-50 + 元数据稀有词 + 正文英文/数字 token 倒排;命中型号时把整篇文档的块拉进候选(规格页常有"处理器在表格、内存在另一段")。
稀有词才加分:
nuc、支持这类泛词加分等于噪声,只有全库罕见的 token 才给加权。增量:按块内容哈希复用旧向量,改一个文件只重嵌它变动的块。
索引原子写:先写
.tmp-<pid>再rename,manifest 最后落盘;崩溃不会留下半新半旧的索引。按 mtime+size 跳过未改动文件:没改的文件连解析都不做(混入 PDF 后省的时间很明显)。
注入按轮去重:同一轮对话的多次 step 只注入一次;新的一轮会重新注入。注入消息带
【本地知识库检索结果】前缀,和用户发言区分。单文档限额:同一文档最多进 2 块(
maxPerDoc),避免 top-5 被一篇长文档占满。
已知限制
PDF 只抽文本层:扫描件/图片型 PDF 需要 OCR,本项目没做(会抽出空文本并跳过)
中文模型(bge-small-zh)跨语言弱:中文问句查英文页面只能进 top-2
注入会追加一条消息,可能让上游前缀缓存失效,增加 token 成本;已按用户回合去重
索引单进程独占写,别在
kb_ingest跑的时候同时写索引CPU 推理,全量建索引是分钟级
没有
.doc(Word 97)、.xlsx、.pptx支持;老格式建议先另存为.docx
脚本
命令 | 作用 |
| 从镜像下载 ONNX 模型 |
| 建索引( |
| 检索并预览注入文本 |
| 启动 MCP stdio 服务 |
| 30 个单元测试(分块 / 检索数学 / 索引读写 / MCP 协议 / 文档解析) |
| 用假 ctx 跑插件行为(不安装) |
| 预热后的延迟基准 |
| 8 题检索质量评估(样例针对中文规格页,换语料会提示跳过) |
| MCP 端到端(spawn 子进程) |
License
MIT
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Self-hosted AI workspace: semantic RAG document search, long-term memory, and AI chat via MCP.
Document-to-Markdown MCP server — convert PDF, Office and HTML into LLM-ready Markdown.
Convert PDFs, Office docs, websites and audio into AI-ready Markdown, then search and ask your docs.
Ingest, manage, and retrieve documents for RAG-powered AI applications
Related MCP Servers
- AlicenseAqualityDmaintenanceLocal offline semantic search over documents (txt, md, pdf, docx, pptx, csv). Indexes folders into a LanceDB vector database with multilingual embeddings and supports hybrid vector + keyword search via Reciprocal Rank Fusion. No API keys, no cloud, no Docker required.431AGPL 3.0
- AlicenseNot gradedqualityFmaintenanceLocal-first Markdown vault retrieval for agents. Read-only MCP stdio server exposing search, get, status, and doctor over Obsidian-compatible Markdown with hybrid BM25/vector/wikilink/title retrieval and first-class CJK support.14 PyPI11MIT
- AlicenseNot gradedqualityBmaintenanceA local-first semantic search server for documents, supporting PDFs, Office files, and text/markdown, enabling natural language search via the Model Context Protocol (MCP).85 PyPI1MIT
- FlicenseAqualityDmaintenanceEnables indexing local documents (PDF, Markdown, text, code) into a knowledge base and querying them via semantic search using local embeddings, all running privately on your machine.4-