Personal Knowledge-Base MCP Server

採用担当者にアピールできるMCPサーバーです。実際に個人が所有するドキュメントコーパスに対して、セマンティック検索を提供します。

問題

キーワード検索は、表現が異なる場合に意味的に関連する情報を見落としてしまいます。このプロジェクトは、個人のノートをエンベディングで索引化し、Model Context Protocol を通じて再利用可能な情報を検索するツールを提供します。

Related MCP server: Personal Knowledge-Base MCP Server

含まれるもの

• FastMCPサーバー（呼び出し可能な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サーバーを実行する

python server.py

Claude Desktopで使用する場合は、server.pyの絶対パスと、仮想環境と同じPythonインタプリタを使います。MCP設定にサーバーの起動コマンドを追加します。

設定例：

{
  "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 · FastAPI · Qdrant Cloud · Sentence Transformers · FastAPI · SQLite · PDF/Markdown/TXT

なぜこれが有用なのか

MCP層はプロトコルレベルのサーバーです。同じ検索機能を独自のチャットボットUIに閉じ込めず、Claude Desktopや他のMCP互換クライアントから直接呼び出すことができます。

制限事項

これはフェローシップ／デモ用の実装です。認証は意図的にシンプルにされています。本番運用では、セキュアなセッション、パスワードのハッシュ化、認可ミドルウェア、レート制限、暗号化ストレージ、そしてより強いテナント分離を追加してください。