Smart Knowledge MCP Server

基于 MCP 协议的轻量知识库服务，核心路径（存储 + 检索）零外部依赖。
支持 Cursor、Claude Desktop、Claude Code 等多种客户端。

快速开始

# 1. 一键安装（自动创建虚拟环境 + 安装依赖 + 配置 MCP）
# Windows:
install.bat

# Linux / Mac:
bash install.sh

# 2. 启动
python main.py

安装脚本会自动配置 MCP 客户端（Cursor / Claude Desktop / Claude Code）。
如需手动配置，参见下方 "MCP 客户端配置"。

无需配置任何 API Key 即可使用全部核心功能。
仅 admin:learn_knowledge / admin:analyze_code / admin:consolidate 等管理工具需要 LLM，
系统会自动复用 Claude Code 或 Cursor 已有的配置。

MCP 客户端配置

Claude Code：

claude mcp add knowledge-mcp -- python /path/to/main.py

Cursor / Claude Desktop：

{
  "mcpServers": {
    "knowledge-mcp": {
      "command": "/path/to/python",
      "args": ["/path/to/main.py"]
    }
  }
}

或运行 python scripts/configure_mcp.py 自动配置。

Claude Code 内使用提示

在 Claude Code 中，所有 MCP 工具由 AI 根据对话上下文自动调用。你只需正常对话：

"帮我查一下知识库里有 Python 的资料"
"记住这个配置参数"
"整理这些知识点"
"导入这篇文档"

AI 会自动选择合适的工具。如需明确指定某个管理工具：

"用 admin:health_check 看下知识库状态"
"用 admin:consolidate 整理 conversatons"

---

工具总览（共 29 个）

核心工具（8 个，不需要 API Key）

这些是日常最常用的工具，AI 会自动在对话中调用。

工具	说明	触发场景
search_knowledge	BM25 全文检索知识库	用户提问、查资料时自动触发
store_knowledge	直接存入文本知识条目	用户说"记住""保存"时
save_conversation	无感记录对话精华到知识库	AI 回答问题后自动调用
ingest_document	解析 PDF/DOCX/图片并入库	提供文件路径时
list_documents	列出文档清单	浏览知识库时
delete_knowledge	删除知识条目（移到回收站）	用户说"删除"时
update_knowledge	替换旧文档内容，版本号+1	信息更新（如天气、价格）
deprecate_knowledge	标记文档为废弃，仍可检索	方案 A→B 演进时

管理工具（18 个，使用 admin: 前缀）

管理工具需要主动指定工具名调用，AI 不会自动触发。

工具	说明	需要 LLM
admin:consolidate	整理零散知识点，自动合并相关文档	可选（默认使用）
admin:health_check	健康检查：过期/待审/冲突/碎片检测	❌
admin:get_knowledge_overview	知识库统计概览（文档数、平台分布等）	❌
admin:rebuild_index	重建 BM25 索引	❌
admin:browse_knowledge	按 platform/category 树状浏览	❌
admin:list_platforms	列出所有平台名称	❌
admin:list_recent_updates	列出近期更新的文档	❌
admin:get_document_detail	查看文档完整内容（含 YAML 头）	❌
admin:get_document_changelog	查看文档变更历史	❌
admin:export_log	导出运行日志	❌
admin:list_unreviewed	列出待审核文档	❌
admin:review_knowledge	审核文档（verify/deprecate/flag）	❌
admin:get_review_history	查看审核记录	❌
admin:learn_knowledge	自然语言录入，LLM 提取结构化信息	✅
admin:analyze_code	C/C++ 代码流程分析	✅
admin:reprocess_document	重新解析源文件，版本号递增	❌
admin:promote_to_shared	个人→共享目录提升	❌
admin:consolidate	知识碎片整理合并	❌

其它工具（3 个）

工具	说明	需要 LLM
batch_import	批量导入目录中的文件	❌
lock_knowledge	锁定文档防止误操作	❌
restore_knowledge	从回收站或历史版本恢复	❌

---

工具详细说明

search_knowledge

search_knowledge(query, platform?, doc_type?, scope?, topk=5)

BM25 全文检索，支持按平台/类型过滤。结果自动按 doc_id 去重，保留最高分。

• query — 搜索关键词（中文自动分词）
• platform — 可选，指定平台过滤
• doc_type — 可选，official 或 self_developed
• topk — 返回结果数，默认 5

store_knowledge

store_knowledge(title, content, platform?, doc_type?)

直接存入文本知识，生成 doc_id、YAML front matter、索引。不需要 API Key。

• content — 正文内容，不能为空
• platform — 分类平台名，默认 unknown
• doc_type — self_developed（默认）或 official

save_conversation

save_conversation(question, answer, key_points?, tags?)

AI 自动调用，无感保存对话到 conversations 平台。同类问题自动追加而非新建。

• 相似度 > 0.7 时自动合并到已有条目
• 存于 shared/extracted_md/conversations/self_developed/

ingest_document

ingest_document(file_path)

支持 PDF、DOCX、图片三种格式，全部走纯本地 OCR 识别：

解析流程：

PDF   → pypdfium2 → 图片 → PaddleOCR → 文本 → 入库（全本地，不联网）
DOCX  → python-docx (文本) + zipfile → 嵌入图片 → PaddleOCR → 合并 → 入库
图片  → 直接 → PaddleOCR → 文本 → 入库

• 不需要 API Key
• OCR = 纯本地 PaddleOCR 推理
• 默认不安装，首次使用时会提示安装命令：install_ocr.bat

admin:consolidate

admin:consolidate(platform?, threshold?, dry_run?, use_llm?)

整理零散知识点。默认使用 LLM 智能合并，无 LLM 时自动降级为关键词匹配。

典型用法：

# 预览合并建议
admin:consolidate()

# 确认执行
admin:consolidate(dry_run=false)

# 整理其他平台
admin:consolidate(platform="deepseek", dry_run=false)

# 强制纯关键词匹配
admin:consolidate(use_llm=false, dry_run=false)

参数说明：

• platform — 默认 conversations，只整理该平台下的文档
• threshold — Jaccard 相似度阈值，默认 0.3，建议 0.2-0.6
• dry_run — 默认 true，预览模式不实际修改
• use_llm — 默认 true，使用 LLM 审核+智能合并

LLM 增强流程：

Jaccard 聚类 → LLM 审核(过滤误召回) → LLM 合并(去重+结构化) → 写入
               ↓ 失败                   ↓ 失败
           直接通过                  简单追加(降级)

admin:health_check

返回 consolidation_candidates 字段，自动检测哪些文档可以合并整理。
定期运行可见知识库碎片状况：

admin:health_check
→ 返回 expired / pending_review / conflicts / faq_candidates / consolidation_candidates

update_knowledge vs deprecate_knowledge vs amend_knowledge

工具	行为	适合场景
update_knowledge	替换内容，版本+1，旧版存档	时效性内容（天气、价格）
amend_knowledge	追加内容，不替换，版本+1	补充信息（加账号、改备注）
deprecate_knowledge	标记废弃，仍可检索但降权	方案演进（A→B，A仍有参考价值）

lock_knowledge / restore_knowledge

lock_knowledge(doc_id, lock=true)    # 锁定，防止误改/误删
restore_knowledge(doc_id, version?)  # 从回收站或历史版本恢复

---

数据存储结构

shared/
├── source_docs/{platform}/{type}/   ← 源文件备份
├── extracted_md/{platform}/{type}/  ← Markdown 知识条目
│   └── .history/                    ← 历史版本存档
└── .trash/                          ← 回收站（软删除）

chroma_db/vectors.pkl                ← BM25 索引缓存

Markdown 条目格式

---
doc_id: "sha256哈希"
platform: "deepseek"
doc_type: "self_developed"
version: "1.0.0.1"
last_updated: "2026-05-04T10:00:00"
changelog: "直接录入"
review_status: "draft"      # draft | verified | deprecated | conflict
confidence: "high"          # high | medium | low
---
正文内容...

---

OCR 增强安装

ingest_document 默认使用 PaddleOCR 做 OCR 识别（纯本地，不联网）。 PaddleOCR 约 500MB，默认不安装。首次使用时会提示：

# 一键安装 OCR 增强
install_ocr.bat   # Windows
bash install_ocr.sh  # Linux/Mac

安装脚本会自动检查 Python 版本（需 3.10~3.13）并安装 PaddleOCR。

---

配置说明

参考 config.yaml，核心配置项：

配置	说明	默认值
retrieval.hybrid.rrf_k	RRF 融合参数	60
retrieval.hybrid.min_score_threshold	最低分数阈值	0.1
embedding.model	向量模型名	BAAI/bge-small-zh-v1.5

核心功能不需要配置任何 API Key。LLM 相关功能（learn/analyze/consolidate）
系统自动复用 Claude Code 或 Cursor 的已有配置，无需手动填写。

---

运行测试

# 需要在 venv312 环境（OCR 用）
./venv312/Scripts/python -m pytest tests/ -v

# 64 passed, 1 failed（learn_knowledge 缺 LLM Key，不影响核心功能）

设计文档

详见 DESIGN.md