Skip to main content
Glama
deenesjakoruzh
AmnaSarwar522

Personal Knowledge-Base MCP Server

by AmnaSarwar522
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Personal Knowledge-Base MCP Server

Model Context Protocol (MCP), Gemini embeddings 및 Qdrant를 사용하여 학생이 소유한 문서 컬렉션에서 의미론적 검색을 제공하는 Personal Knowledge-Base MCP Server입니다.

프로젝트 개요

이 프로젝트는 개인 지식 기반을 호출 가능한 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

검색 평가

다섯 개 쿼리로 구성된 소규모 평가 세트를 사용하여 검색된 상위 3개 결과 안에 기대한 관련 페이지가 하나 이상 포함되는지 확인했습니다.

평가 결과:

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