Embedding MCP Server

Embedding MCP Server

txtai を活用した Model Context Protocol（MCP）サーバーの実装です。標準化されたインターフェースを通じて、セマンティック検索、ナレッジグラフ機能、AI によるテキスト処理を提供します。

txtai の力：オールインワンの埋め込みデータベース

このプロジェクトでは、セマンティック検索、ナレッジグラフの構築、言語モデルのワークフローを活用する RAG 向けのオールインワン埋め込みデータベースである txtai を利用しています。txtai には、次のような主な利点があります。

• 統合ベクトルデータベース：ベクトルインデックス、グラフネットワーク、リレーショナルデータベースを単一のプラットフォームに統合
• セマンティック検索：キーワードだけでなく、意味に基づいて情報を検索
• ナレッジグラフの統合：データからナレッジグラフを自動的に構築して検索
• ポータブルなナレッジベース：ナレッジベース全体を圧縮アーカイブ（.tar.gz）として保存し、簡単に共有して読み込み可能
• 拡張可能なパイプラインシステム：統合 API を通じて、テキスト、ドキュメント、音声、画像、動画を処理
• ローカルファーストのアーキテクチャ：外部サービスにデータを送信せず、すべてをローカルで実行

仕組み

このプロジェクトには、ナレッジベースビルダーツールと MCP サーバーが含まれています。ナレッジベースビルダーツールは、ナレッジベースを作成・管理するためのコマンドラインインターフェースです。MCP サーバーは、ナレッジベースにアクセスするための標準化されたインターフェースを提供します。

ナレッジベースを構築するために、ナレッジベースビルダーツールを使う必要はありません。Python スクリプトを記述したり、Jupyter Notebook を使ったりして、txtai のプログラミングインターフェースを使っていつでもナレッジベースを構築できます。txtai を使って構築されていれば、MCP サーバーで読み込めます。さらに、ナレッジベースはファイルシステム上のフォルダーでも、エクスポートされた .tar.gz ファイルでも構いません。MCP サーバーに渡すだけで読み込まれます。

1. kb_builder でナレッジベースを構築する

kb_builder モジュールは、ナレッジベースを作成・管理するためのコマンドラインインターフェースを提供します。

• さまざまなソース（ファイル、ディレクトリ、JSON）からドキュメントを処理
• テキストを抽出して埋め込みを作成
• ナレッジグラフを自動的に構築
• ポータブルなナレッジベースをエクスポート

機能に制限がある可能性があり、現在は利便性のためにのみ提供されている点にご注意ください。

2. MCP サーバーを起動する

MCP サーバーは、ナレッジベースにアクセスするための標準化されたインターフェースを提供します。

• セマンティック検索機能
• ナレッジグラフの検索と可視化
• テキスト処理パイプライン（要約、抽出など）
• Model Context Protocol に完全準拠

インストール

推奨：Python 3.10 以降で uv を使用する

最適な使用体験のため、Python 3.10 以降で uv を使用することをおすすめします。依存関係をより適切に管理でき、動作の一貫性も確保できます。

# Install uv if you don't have it already
pip install -U uv

# Create a virtual environment with Python 3.10 or newer
uv venv --python=3.10  # or 3.11, 3.12, etc.

# Activate the virtual environment (bash/zsh)
source .venv/bin/activate
# For fish shell
# source .venv/bin/activate.fish

# Install from PyPI
uv pip install kb-mcp-server

注：バージョン 4.50.0 以降で表示される transformers.agents.tools に関する非推奨警告を避けるため、transformers のバージョンを 4.49.0 に固定しています。より新しいバージョンの transformers を使用すると、この警告が表示されることがありますが、機能には影響しません。

conda を使用する

# Create a new conda environment (optional)
conda create -n embedding-mcp python=3.10
conda activate embedding-mcp

# Install from PyPI
pip install kb-mcp-server

ソースからインストールする

# Create a new conda environment
conda create -n embedding-mcp python=3.10
conda activate embedding-mcp

# Clone the repository
git clone https://github.com/Geeksfino/kb-mcp-server.git.git
cd kb-mcp-server

# Install dependencies
pip install -e .

uv を使用する（より高速な方法）

# Install uv if not already installed
pip install uv

# Create a new virtual environment
uv venv
source .venv/bin/activate

# Option 1: Install from PyPI
uv pip install kb-mcp-server

# Option 2: Install from source (for development)
uv pip install -e .

uvx を使用する（インストール不要）

uvx を使用すると、インストールせずに PyPI からパッケージを直接実行できます。

# Run the MCP server
uvx --from [email protected] kb-mcp-server --embeddings /path/to/knowledge_base

# Build a knowledge base
uvx --from [email protected] kb-build --input /path/to/documents --config config.yml

# Search a knowledge base
uvx --from [email protected] kb-search /path/to/knowledge_base "Your search query"

コマンドラインの使用方法

ナレッジベースを構築する

PyPI からインストールしたコマンド、Python モジュールを直接使用する方法、または便利なシェルスクリプトを利用できます。

PyPI からインストールしたコマンドを使用する

# Build a knowledge base from documents
kb-build --input /path/to/documents --config config.yml

# Update an existing knowledge base with new documents
kb-build --input /path/to/new_documents --update

# Export a knowledge base for portability
kb-build --input /path/to/documents --export my_knowledge_base.tar.gz

# Search a knowledge base
kb-search /path/to/knowledge_base "What is machine learning?"

# Search with graph enhancement
kb-search /path/to/knowledge_base "What is machine learning?" --graph --limit 10

uvx を使用する（インストール不要）

# Build a knowledge base from documents
uvx --from [email protected] kb-build --input /path/to/documents --config config.yml

# Update an existing knowledge base with new documents
uvx --from [email protected] kb-build --input /path/to/new_documents --update

# Export a knowledge base for portability
uvx --from [email protected] kb-build --input /path/to/documents --export my_knowledge_base.tar.gz

# Search a knowledge base
uvx --from [email protected] kb-search /path/to/knowledge_base "What is machine learning?"

# Search with graph enhancement
uvx --from [email protected] kb-search /path/to/knowledge_base "What is machine learning?" --graph --limit 10

Python モジュールを使用する

# Build a knowledge base from documents
python -m kb_builder build --input /path/to/documents --config config.yml

# Update an existing knowledge base with new documents
python -m kb_builder build --input /path/to/new_documents --update

# Export a knowledge base for portability
python -m kb_builder build --input /path/to/documents --export my_knowledge_base.tar.gz

便利なスクリプトの使用

このリポジトリには、ナレッジベースの構築と検索を簡単に行える便利なラッパースクリプトが含まれています。

# Build a knowledge base using a template configuration
./scripts/kb_build.sh /path/to/documents technical_docs

# Build using a custom configuration file
./scripts/kb_build.sh /path/to/documents /path/to/my_config.yml

# Update an existing knowledge base
./scripts/kb_build.sh /path/to/documents technical_docs --update

# Search a knowledge base
./scripts/kb_search.sh /path/to/knowledge_base "What is machine learning?"

# Search with graph enhancement
./scripts/kb_search.sh /path/to/knowledge_base "What is machine learning?" --graph

その他のオプションについては、./scripts/kb_build.sh --help または ./scripts/kb_search.sh --help を実行してください。

MCP サーバーの起動

PyPI からインストールしたコマンドを使用する

# Start with a specific knowledge base folder
kb-mcp-server --embeddings /path/to/knowledge_base_folder

# Start with a given knowledge base archive
kb-mcp-server --embeddings /path/to/knowledge_base.tar.gz

uvx を使用する（インストール不要）

# Start with a specific knowledge base folder
uvx [email protected] --embeddings /path/to/knowledge_base_folder

# Start with a given knowledge base archive
uvx [email protected] --embeddings /path/to/knowledge_base.tar.gz

Python モジュールを使用する

# Start with a specific knowledge base folder
python -m txtai_mcp_server --embeddings /path/to/knowledge_base_folder

# Start with a given knowledge base archive
python -m txtai_mcp_server --embeddings /path/to/knowledge_base.tar.gz

MCP サーバーの設定

MCP サーバーは、YAML ファイルではなく、環境変数またはコマンドライン引数を使用して設定します。YAML ファイルは、ナレッジベースの構築時に txtai コンポーネントを設定する場合にのみ使用します。

MCP サーバーの設定方法は次のとおりです。

# Start the server with command-line arguments
kb-mcp-server --embeddings /path/to/knowledge_base --host 0.0.0.0 --port 8000

# Or using uvx (no installation required)
uvx [email protected] --embeddings /path/to/knowledge_base --host 0.0.0.0 --port 8000

# Or using the Python module
python -m txtai_mcp_server --embeddings /path/to/knowledge_base --host 0.0.0.0 --port 8000

# Or use environment variables
export TXTAI_EMBEDDINGS=/path/to/knowledge_base
export MCP_SSE_HOST=0.0.0.0
export MCP_SSE_PORT=8000
python -m txtai_mcp_server

一般的な設定オプション：

• --embeddings：ナレッジベースへのパス（必須）
• --host：バインドするホストアドレス（デフォルト：localhost）
• --port：リッスンするポート（デフォルト：8000）
• --transport：使用するトランスポート。'sse' または 'stdio'（デフォルト：stdio）
• --enable-causal-boost：関連性スコアを向上させる因果ブースト機能を有効にします
• --causal-config：カスタム因果ブースト設定 YAML ファイルへのパス

MCP サーバーを使用するための LLM クライアントの設定

LLM クライアントが MCP サーバーを使用するように設定するには、MCP 設定ファイルを作成する必要があります。以下は mcp_config.json の例です。

サーバーを直接使用する

仮想 Python 環境を使用してサーバーをインストールする場合は、次の設定を使用できます。ただし、仮想環境を使用すると、Claude などの MCP ホストはサーバーに接続できません。「pip install」または「uv pip install」を実行した仮想環境の Python 実行ファイルへの絶対パスを指定する必要があります。たとえば、次のようになります。

{
  "mcpServers": {
    "kb-server": {
      "command": "/your/home/project/.venv/bin/kb-mcp-server",
      "args": [
        "--embeddings", 
        "/path/to/knowledge_base.tar.gz"
      ],
      "cwd": "/path/to/working/directory"
    }
  }
}

システムのデフォルト Python を使用する

システムのデフォルト Python を使用する場合は、次の設定を使用できます。

{
    "rag-server": {
      "command": "python3",
      "args": [
        "-m",
        "txtai_mcp_server",
        "--embeddings",
        "/path/to/knowledge_base.tar.gz",
        "--enable-causal-boost"
      ],
      "cwd": "/path/to/working/directory"
    }
}

または、システムに「brew install uvx」などで uvx をインストールしている場合や、uvx をインストールしてグローバルにアクセスできるようにしている場合は、次のようにします。

# Create a symlink to /usr/local/bin (which is typically in the system PATH)
sudo ln -s /Users/cliang/.local/bin/uvx /usr/local/bin/uvx

これにより、ユーザー固有のインストール先からシステム全体で使用できる場所へのシンボリックリンクが作成されます。Claude Desktop などの macOS アプリケーションでは、launchd 設定ファイルを作成または編集して、システム全体の PATH を変更できます。

# Create a plist file to set environment variables for all GUI applications
sudo nano /Library/LaunchAgents/environment.plist

次の内容を追加します。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>my.startup</string>
  <key>ProgramArguments</key>
  <array>
    <string>sh</string>
    <string>-c</string>
    <string>launchctl setenv PATH $PATH:/Users/cliang/.local/bin</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
</dict>
</plist>

次に、読み込みます。

sudo launchctl load -w /Library/LaunchAgents/environment.plist

反映するにはコンピューターを再起動する必要があります。

{
  "mcpServers": {
    "kb-server": {
      "command": "uvx",
      "args": [
        "[email protected]",
        "--embeddings", "/path/to/knowledge_base",
        "--host", "localhost",
        "--port", "8000"
      ],
      "cwd": "/path/to/working/directory"
    }
  }
}

この設定ファイルを LLM クライアントからアクセスできる場所に配置し、クライアントがそのファイルを使用するように設定してください。具体的な設定手順は、使用する LLM クライアントによって異なります。

高度なナレッジベース設定

txtai でナレッジベースを構築するには、埋め込み処理のさまざまな側面を制御する YAML 設定ファイルが必要です。この設定は kb_builder ツールで使用されるもので、MCP サーバー自体では使用されません。

セグメンテーション／チャンク化の方法、埋め込みモデル、スコアリング方式を調整したり、グラフの構築、因果ブースト、ハイブリッド検索の重みなどを設定したりする必要がある場合があります。

幸いなことに、txtai はコーディング不要の強力な YAML 設定システムを提供しています。以下は、ナレッジベース構築のための包括的な設定例です。

# Path to save/load embeddings index
path: ~/.txtai/embeddings
writable: true

# Content storage in SQLite
content:
  path: sqlite:///~/.txtai/content.db

# Embeddings configuration
embeddings:
  # Model settings
  path: sentence-transformers/nli-mpnet-base-v2
  backend: faiss
  gpu: true
  batch: 32
  normalize: true
  
  # Scoring settings
  scoring: hybrid
  hybridalpha: 0.75

# Pipeline configuration
pipeline:
  workers: 2
  queue: 100
  timeout: 300

# Question-answering pipeline
extractor:
  path: distilbert-base-cased-distilled-squad
  maxlength: 512
  minscore: 0.3

# Graph configuration
graph:
  backend: sqlite
  path: ~/.txtai/graph.db
  similarity: 0.75  # Threshold for creating graph connections
  limit: 10  # Maximum connections per node

設定例

src/kb_builder/configs ディレクトリには、さまざまなユースケースやストレージバックエンド向けの設定テンプレートが含まれています。

ストレージとバックエンドの設定

• memory.yml：メモリ内ベクトル（開発時に最速、永続化なし）
• sqlite-faiss.yml：コンテンツには SQLite、ベクトルには FAISS を使用（ローカルファイルベースの永続化）
• postgres-pgvector.yml：PostgreSQL + pgvector（完全な永続化に対応した本番環境向け）

ドメイン固有の設定

• base.yml：基本設定テンプレート
• code_repositories.yml：コードリポジトリ向けに最適化されています
• data_science.yml：データサイエンスの文書向けに設定されています
• general_knowledge.yml：汎用ナレッジベース
• research_papers.yml：学術論文向けに最適化されています
• technical_docs.yml：技術文書向けに設定されています

これらを独自の設定を作成する際の出発点として使用できます。

python -m kb_builder build --input /path/to/documents --config src/kb_builder/configs/technical_docs.yml

# Or use a storage-specific configuration
python -m kb_builder build --input /path/to/documents --config src/kb_builder/configs/postgres-pgvector.yml

高度な機能

ナレッジグラフ機能

MCP サーバーは、txtai に組み込まれたグラフ機能を活用し、強力なナレッジグラフ機能を提供します。

• グラフの自動構築：文書からナレッジグラフを自動的に構築します
• グラフのトラバーサル：関連する概念や文書をたどります
• 経路探索：異なる情報間のつながりを見つけます
• コミュニティ検出：関連情報のクラスターを特定します

因果関係ブーストの仕組み

MCP サーバーには、因果関係を特定して優先することで検索の関連性を高める、高度な因果関係ブーストの仕組みが備わっています。

• パターン認識：クエリと文書の両方で、因果関係を示す言語パターンを検出します
• 多言語サポート：検出されたクエリの言語に応じて、適切なパターンを自動的に適用します
• 設定可能なブースト倍率：異なる種類の因果関係の一致に、カスタマイズ可能なブースト係数を適用します
• 関連性の向上：因果関係を説明する結果を検索結果で優先します

この仕組みにより、概念間の関係を説明するコンテンツが表示されやすくなり、「なぜ」や「どのように」といった質問への応答が大幅に改善されます。因果関係ブーストの設定は YAML ファイルで細かくカスタマイズできるため、さまざまなドメインや言語に合わせて調整できます。

ライセンス

MIT License - 詳細は LICENSE ファイルをご覧ください