TxtAI Assistant MCP

TxtAI Assistant MCP

txtai を使用した、セマンティック検索とメモリ管理のための Model Context Protocol（MCP）サーバー実装です。このサーバーは、セマンティック検索機能を備えたテキストベースのメモリを保存、取得、管理するための堅牢な API を提供します。

txtai について

このプロジェクトは、NeuML が開発した優れたオープンソースの AI 搭載検索エンジンである txtai を基盤としています。txtai は以下を提供します。

• 🔍 オールインワンのセマンティック検索ソリューション
• 🧠 トランスフォーマーを活用したニューラル検索
• 💡 ゼロショットテキスト分類
• 🔄 テキスト抽出と埋め込み
• 🌐 多言語サポート
• 🚀 高いパフォーマンスとスケーラビリティ

txtai を Model Context Protocol（MCP）と統合してその機能を拡張することで、Claude や Cline などの AI アシスタントが、txtai の強力なセマンティック検索機能を活用できるようにしています。このような強力で柔軟なツールを開発した txtai チームに、特別な感謝を申し上げます。

機能

• 🔍 保存されたメモリを横断するセマンティック検索
• 💾 ファイルベースのバックエンドによる永続ストレージ
• 🏷️ タグに基づくメモリの整理と取得
• 📊 メモリの統計情報とヘルスモニタリング
• 🔄 データの自動永続化
• 📝 包括的なロギング
• 🔒 設定可能な CORS 設定
• 🤖 Claude および Cline AI との統合

前提条件

• Python 3.8 以上
• pip（Python パッケージインストーラー）
• virtualenv（推奨）

インストール

1. このリポジトリをクローンします。

git clone https://github.com/yourusername/txtai-assistant-mcp.git
cd txtai-assistant-mcp

2. 起動スクリプトを実行します。

./scripts/start.sh

スクリプトは以下を実行します。

• 仮想環境を作成します
• 必要な依存関係をインストールします
• 必要なディレクトリを設定します
• テンプレートから設定ファイルを作成します
• サーバーを起動します

設定

サーバーは、.env ファイル内の環境変数を使用して設定できます。テンプレートは .env.template にあります。

# Server Configuration
HOST=0.0.0.0
PORT=8000

# CORS Configuration
CORS_ORIGINS=*

# Logging Configuration
LOG_LEVEL=DEBUG

# Memory Configuration
MAX_MEMORIES=0

Claude および Cline AI との統合

この TxtAI Assistant は、Claude や Cline AI の機能をセマンティックメモリと検索機能で強化するために、MCP サーバーとして使用できます。

Claude の設定

このサーバーを Claude で使用するには、Claude の MCP 設定ファイルに追加します（macOS では通常 ~/Library/Application Support/Claude/claude_desktop_config.json にあります）。

{
  "mcpServers": {
    "txtai-assistant": {
      "command": "path/to/txtai-assistant-mcp/scripts/start.sh",
      "env": {}
    }
  }
}

Cline の設定

Cline で使用するには、サーバー設定を Cline の MCP 設定ファイルに追加します（通常 ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json にあります）。

{
  "mcpServers": {
    "txtai-assistant": {
      "command": "path/to/txtai-assistant-mcp/scripts/start.sh",
      "env": {}
    }
  }
}

利用可能な MCP ツール

設定すると、以下のツールを Claude と Cline から利用できるようになります。

1. store_memory：メタデータとタグを付けて新しいメモリを保存します

{
  "content": "Memory content to store",
  "metadata": {
    "source": "conversation",
    "timestamp": "2023-01-01T00:00:00Z"
  },
  "tags": ["important", "context"],
  "type": "conversation"
}

2. retrieve_memory：セマンティック検索に基づいてメモリを取得します

{
  "query": "search query",
  "n_results": 5
}

3. search_by_tag：タグでメモリを検索します

{
  "tags": ["important", "context"]
}

4. delete_memory：コンテンツハッシュを指定して特定のメモリを削除します

{
  "content_hash": "hash_value"
}

5. get_stats：データベースの統計情報を取得します

{}

6. check_health：データベースと埋め込みモデルの状態を確認します

{}

使用例

Claude または Cline では、MCP プロトコルを通じてこれらのツールを使用できます。

# Store a memory
<use_mcp_tool>
<server_name>txtai-assistant</server_name>
<tool_name>store_memory</tool_name>
<arguments>
{
  "content": "Important information to remember",
  "tags": ["important"]
}
</arguments>
</use_mcp_tool>

# Retrieve memories
<use_mcp_tool>
<server_name>txtai-assistant</server_name>
<tool_name>retrieve_memory</tool_name>
<arguments>
{
  "query": "what was the important information?",
  "n_results": 5
}
</arguments>
</use_mcp_tool>

AI は会話中に、コンテキストを維持し、関連情報を取得するためにこれらのツールを自動的に使用します。

API エンドポイント

メモリの保存

POST /store

オプションのメタデータとタグを付けて新しいメモリを保存します。

リクエストボディ：

{
    "content": "Memory content to store",
    "metadata": {
        "source": "example",
        "timestamp": "2023-01-01T00:00:00Z"
    },
    "tags": ["example", "memory"],
    "type": "general"
}

メモリの検索

POST /search

セマンティック検索を使用してメモリを検索します。

リクエストボディ：

{
    "query": "search query",
    "n_results": 5,
    "similarity_threshold": 0.7
}

タグで検索

POST /search_tags

タグでメモリを検索します。

リクエストボディ：

{
    "tags": ["example", "memory"]
}

メモリの削除

DELETE /memory/{content_hash}

コンテンツハッシュを指定して特定のメモリを削除します。

統計情報の取得

GET /stats

メモリ数やタグの分布など、システムの統計情報を取得します。

ヘルスチェック

GET /health

サーバーのヘルス状態を確認します。

ディレクトリ構成

txtai-assistant-mcp/
├── server/
│   ├── main.py           # Main server implementation
│   └── requirements.txt  # Python dependencies
├── scripts/
│   └── start.sh         # Server startup script
├── data/                # Data storage directory
├── logs/                # Log files directory
├── .env.template        # Environment configuration template
└── README.md           # This file

データストレージ

メモリとタグは、data ディレクトリ内の JSON ファイルに保存されます。

• memories.json：保存されたすべてのメモリが含まれます
• tags.json：タグインデックスが含まれます

ログ記録

ログは logs ディレクトリに保存されます。デフォルトのログファイルは server.log です。

開発

このプロジェクトに貢献するには、次の手順に従ってください。

1. リポジトリをフォークします
2. フィーチャーブランチを作成します
3. 変更を加えます
4. プルリクエストを送信します

エラー処理

サーバーでは、包括的なエラー処理を実装しています。

• 無効なリクエストには、適切な HTTP ステータスコードを返します
• エラーはスタックトレースとともにログに記録されます
• レスポンスには、ユーザーにわかりやすいエラーメッセージを返します

セキュリティに関する考慮事項

• CORS の設定は環境変数で構成できます
• ディレクトリトラバーサルを防ぐため、ファイルパスをサニタイズします
• すべてのエンドポイントで入力検証を行います

ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細については、LICENSE ファイルを参照してください。

貢献

貢献を歓迎します。お気軽にプルリクエストを送信してください。

サポート

問題が発生した場合や質問がある場合は、GitHub リポジトリで issue を作成してください。