Personal Knowledge-Base MCP Server

一个面向招聘者的 MCP 服务器，能够在真实且个人拥有的文档语料库上提供语义检索。

问题

当措辞不同时，关键词搜索会漏掉语义相关的信息。本项目使用嵌入向量为个人笔记建立索引，并通过模型上下文协议（Model Context Protocol）提供可复用的检索工具。

Related MCP server: Personal Knowledge-Base MCP Server

包含内容

• FastMCP server，提供 3 个可调用工具：

  • search_notes(user_id, query, top_k) — 排序后的文本块 + 来源引用

  • get_document(user_id, doc_id) — 完整索引的文档上下文

  • list_sources(user_id) — 已索引的来源

• 支持 PDF/Markdown/TXT 的导入与重叠感知分块

• sentence-transformers/all-MiniLM-L6-v2 嵌入模型

• Qdrant 向量存储，每个用户有独立的集合

• 相似度阈值，明确返回 no_confident_match

• FastAPI 多用户 Web 演示，包含注册/登录、上传和搜索

• 带人工标注的检索评估脚本

架构

参见 architecture.md。

快速开始

1. 安装

python -m venv .venv
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate
pip install -r requirements.txt

2. 配置 Qdrant Cloud

创建一个免费的 Qdrant Cloud 集群，复制其 URL/API 密钥，并根据 .env.example 创建 .env 文件。

QDRANT_URL=https://YOUR-CLUSTER.qdrant.io
QDRANT_API_KEY=YOUR_KEY

3. 加入你自己的语料库

把你的 2–5 份学期笔记放入 corpus/ 中，然后：

python ingest.py --user demo --path corpus

4. 运行 Web 演示

uvicorn api:app --reload

打开 http://127.0.0.1:8000。

5. 运行 MCP server

python server.py

对于 Claude Desktop，将服务器命令添加到 MCP 配置中，并使用 server.py 的绝对路径以及虚拟环境中相同的 Python 解释器。

示例结构如下：

{
  "mcpServers": {
    "personal-knowledge-base": {
      "command": "C:\\PATH\\TO\\.venv\\Scripts\\python.exe",
      "args": ["C:\\PATH\\TO\\personal-knowledge-base-mcp\\server.py"]
    }
  }
}

检索质量

在 evaluation_queries.json 中创建一个经过手工标注的小型评估集，每个查询映射到正确的 doc_id，然后运行：

python evaluate.py --user demo

在最终 README 中报告实际测得的 Precision@k 精确率。不要虚构该数字。

演示

5 分钟的现场演示流程见 demo_script.md。

技术栈

Python · FastMCP · Qdrant Cloud · Sentence Transformers · FastAPI · SQLite · PDF/Markdown/TXT

为什么这很有用

MCP 层处于协议层面：同样的检索能力可被 Claude Desktop 或其他兼容 MCP 的客户端调用，而不是被锁定在自定义的聊天机器人 UI 中。

局限性

这是一个 fellowship 演示实现。认证机制刻意保持简单；生产部署应增加安全会话、密码哈希、授权中间件、速率限制、加密存储以及更强的租户隔离。