Skip to main content
Glama
deenesjakoruzh
AmnaSarwar522

Personal Knowledge-Base MCP Server

by AmnaSarwar522
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

个人知识库 MCP 服务器

一个个人知识库 MCP 服务器，使用 Model Context Protocol (MCP)、Gemini 嵌入和 Qdrant 对学生拥有的文档集合提供语义搜索。

项目概述

该项目将个人知识库公开为可调用的 MCP 工具。

该系统不依赖关键词匹配，而是将用户查询转换为向量嵌入，并从 Qdrant 中检索语义相关的文档块。

Related MCP server: genai-lab

架构

User / MCP Client
       |
       v
MCP Server (FastMCP)
       |
       +----------------------+
       |                      |
       v                      v
 search_notes()        get_document()
       |
       v
Gemini Embedding API
       |
       v
Qdrant Vector Database
       |
       v
Ranked Chunks
       |
       v
Source + Page + Score + Text
## Features

* PDF document ingestion
* Page-by-page text extraction
* Recursive text chunking
* Gemini `gemini-embedding-001` embeddings
* Qdrant vector storage
* Semantic similarity search
* Source and page citations
* Confidence threshold for low-relevance queries
* Full-document retrieval
* Indexed-source listing
* MCP Inspector support

## MCP Tools

### `search_notes`

Searches the knowledge base using semantic similarity.

Arguments:

* `query`: search question or topic
* `top_k`: maximum number of results

Returns:

* similarity score
* source filename
* page number
* relevant text chunk

### `get_document`

Returns the complete text of an indexed PDF document.

Argument:

* `doc_id`: document filename

Example:

```text
Complex_Variables_Project_Report.pdf

list_source_documents

列出所有已索引的源文档。

示例输出：

1. Complex_Variables_Project_Report.pdf

项目结构

Personal-Knowledge-MCP/
├── documents/
│   └── Complex_Variables_Project_Report.pdf
├── services/
│   ├── chunking.py
│   ├── embedding.py
│   ├── pdf_reader.py
│   └── qdrant_service.py
├── .env
├── .gitignore
├── evaluation.py
├── ingest.py
├── requirements.txt
└── server.py

设置

1. 创建并激活虚拟环境

python -m venv .venv
.venv\Scripts\Activate.ps1

2. 安装依赖

pip install -r requirements.txt

3. 配置 Gemini API 密钥

在项目根目录创建一个 .env 文件：

GEMINI_API_KEY=your_api_key_here

切勿将 .env 提交到 Git。

4. 启动 Qdrant

该项目在以下位置使用本地 Qdrant：

http://localhost:6333

示例 Docker 命令：

docker run -d --name qdrant -p 6333:6333 -p 6334:6334 qdrant/qdrant

文档摄取

将 PDF 放入：

documents/

运行：

python ingest.py

摄取管道执行以下操作：

PDF
 ↓
Page extraction
 ↓
Chunking
 ↓
Gemini embeddings
 ↓
Qdrant storage

每个存储的块包含：

text
page
source

运行 MCP 服务器

启动 MCP Inspector：

mcp dev server.py

MCP 服务器使用 STDIO 传输。

可用工具：

search_notes
get_document
list_source_documents

检索评估

使用了一个包含五个查询的小型评估集，来检查前三个检索结果中是否至少出现一个预期相关页面。

评估结果：

Tests: 5
Successful hits: 5
Hit@3: 100%

示例评估查询包括：

  • 什么是复变量？

  • 什么是柯西-黎曼方程？

  • 拉普拉斯变换如何帮助工程系统？

  • 拉普拉斯变换和傅里叶变换有什么区别？

  • FFT 如何用于音频降噪？

置信度过滤

搜索工具使用的初始相似度阈值为：

0.60

例如，相关查询产生的分数约为：

0.79
0.76
0.75

而不相关查询产生的分数约为：

0.52

因此，低分结果会被过滤，工具返回：

No confident match found.

技术

  • Python

  • FastMCP

  • Model Context Protocol (MCP)

  • Google Gemini Embeddings

  • Qdrant

  • PyMuPDF

  • LangChain Text Splitters

  • Docker

  • MCP Inspector

当前知识来源

当前的演示语料库是：

Complex_Variables_Project_Report.pdf

该文档包含 7 页，并为索引的 personal_knowledge 集合分成了 30 个块。

安全性

  • API 密钥存储在 .env 中

  • .env 通过 .gitignore 排除

  • 机密信息绝不应提交到源代码控制

未来改进

  • 支持 Markdown 和 TXT 文档

  • 添加文档级持久 ID

  • 改进重复块处理

  • 扩展评估数据集

  • 添加更多检索指标

  • 支持多个文档集合

  • 添加可选的 Qdrant Cloud 部署

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • hw_rag_mcp

    schuchev
    F
    license
    Not graded
    quality
    D
    maintenance
    MCP server that indexes a knowledge base into Chroma and provides search tools for retrieving document fragments via vector embeddings.
    -

  • ja-local-kb

    jefferyadventure519-byte
    A
    license
    Not graded
    quality
    A
    maintenance
    A local knowledge base MCP server that enables retrieval and evidence-based Q&A over Obsidian Markdown notes, with high-recall embedding search, chunked indexing, hybrid retrieval, and three STDIO MCP tools for agent-driven recollection and quality-gated recall.
    Academic Free v1.1