MCPサーバーの埋め込み
txtai を搭載したモデル コンテキスト プロトコル (MCP) サーバー実装。標準化されたインターフェースを通じて、セマンティック検索、ナレッジ グラフ機能、AI 駆動型テキスト処理を提供します。
txtaiのパワー：オールインワン埋め込みデータベース
このプロジェクトでは、セマンティック検索、ナレッジグラフ構築、言語モデルワークフローを活用する RAG 用のオールインワン埋め込みデータベースであるtxtaiを活用します。txtai にはいくつかの重要な利点があります。
- 統合ベクトルデータベース:ベクトルインデックス、グラフネットワーク、リレーショナルデータベースを単一のプラットフォームに統合します。
- セマンティック検索: キーワードだけでなく意味に基づいて情報を検索します
- ナレッジグラフ統合: データからナレッジグラフを自動的に構築し、クエリを実行します。
- ポータブルナレッジベース: ナレッジベース全体を圧縮アーカイブ (.tar.gz) として保存し、簡単に共有したりロードしたりできます。
- 拡張可能なパイプラインシステム: 統合された API を通じてテキスト、ドキュメント、オーディオ、画像、ビデオを処理します。
- ローカルファーストアーキテクチャ: 外部サービスにデータを送信せずにすべてをローカルで実行します
仕組み
このプロジェクトには、ナレッジベース構築ツールとMCPサーバーが含まれています。ナレッジベース構築ツールは、ナレッジベースを作成および管理するためのコマンドラインインターフェースです。MCPサーバーは、ナレッジベースにアクセスするための標準化されたインターフェースを提供します。
ナレッジベース構築にナレッジベースビルダーツールを使用する必要はありません。txtaiのプログラミングインターフェースを使えば、Pythonスクリプトを書いたり、Jupyter Notebookを使ったりすることで、いつでもナレッジベースを構築できます。txtaiで構築されたナレッジベースであれば、MCPサーバーに読み込むことができます。さらに、ナレッジベースはファイルシステム上のフォルダやエクスポートされた.tar.gzファイルでも構いません。MCPサーバーに渡すだけで読み込まれます。
1. kb_builderでナレッジベースを構築する
kb_builderモジュールは、ナレッジベースを作成および管理するためのコマンドライン インターフェイスを提供します。
- さまざまなソース（ファイル、ディレクトリ、JSON）からのドキュメントを処理する
- テキストを抽出して埋め込みを作成する
- ナレッジグラフを自動的に構築
- ポータブルなナレッジベースをエクスポートする
ただし、機能が制限される可能性があり、現在は利便性のためにのみ提供されていることに注意してください。
2. MCPサーバーを起動する
MCP サーバーは、ナレッジ ベースにアクセスするための標準化されたインターフェイスを提供します。
- セマンティック検索機能
- ナレッジグラフのクエリと視覚化
- テキスト処理パイプライン（要約、抽出など）
- モデルコンテキストプロトコルに完全準拠
インストール
推奨: 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 kb-mcp-server@0.3.0 kb-mcp-server --embeddings /path/to/knowledge_base
# Build a knowledge base
uvx --from kb-mcp-server@0.3.0 kb-build --input /path/to/documents --config config.yml
# Search a knowledge base
uvx --from kb-mcp-server@0.3.0 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 kb-mcp-server@0.3.0 kb-build --input /path/to/documents --config config.yml
# Update an existing knowledge base with new documents
uvx --from kb-mcp-server@0.3.0 kb-build --input /path/to/new_documents --update
# Export a knowledge base for portability
uvx --from kb-mcp-server@0.3.0 kb-build --input /path/to/documents --export my_knowledge_base.tar.gz
# Search a knowledge base
uvx --from kb-mcp-server@0.3.0 kb-search /path/to/knowledge_base "What is machine learning?"
# Search with graph enhancement
uvx --from kb-mcp-server@0.3.0 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 kb-mcp-server@0.2.6 --embeddings /path/to/knowledge_base_folder
# Start with a given knowledge base archive
uvx kb-mcp-server@0.2.6 --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 kb-mcp-server@0.2.6 --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 : カスタム causal boost 構成 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"
}
}
あるいは、uvx を使用している場合は、"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": [
"kb-mcp-server@0.2.6",
"--embeddings", "/path/to/knowledge_base",
"--host", "localhost",
"--port", "8000"
],
"cwd": "/path/to/working/directory"
}
}
}
この設定ファイルをLLMクライアントがアクセスできる場所に配置し、クライアントがそれを使用するように設定します。具体的な設定手順は、LLMクライアントによって異なります。
高度なナレッジベースの構成
txtai でナレッジベースを構築するには、埋め込みプロセスのさまざまな側面を制御する YAML 設定ファイルが必要です。この設定は、MCP サーバー自体ではなく、 kb_builderツールによって使用されます。
セグメンテーション/チャンク化戦略、埋め込みモデル、スコアリング方法を調整したり、グラフ構築、因果ブースティング、ハイブリッド検索の重みなどを設定したりする必要があるかもしれません。
幸いなことに、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ファイルを参照