Meilisearch MCP Server

• 現在の接続設定を表示
• Meilisearch インスタンスを動的に切り替え
• API キーをその場で更新

• カスタム主キーを指定して新しいインデックスを作成
• 統計情報とともにすべてのインデックスを一覧表示
• インデックスとそのデータを削除
• 詳細なインデックスのメトリクスを取得

• ドキュメントを追加または更新
• ページネーションを使用してドキュメントを取得
• データを一括インポート

• フィルター、ソート、ファセットを使用して検索
• 複数のインデックスを検索
• ベクトルを使用したセマンティック検索
• ハイブリッド検索（キーワード＋セマンティック）

• ランキングルールを構成
• ファセットとフィルタリングを設定
• 検索可能な属性を管理
• あいまい検索の許容度をカスタマイズ

• API キーを作成および管理
• 詳細な権限を設定
• キーの使用状況を監視

⚠️ 注：利便性のため、チャットでホストや API キーを直接追加、更新できますが、この方法は主に開発用途（複数のインスタンスにその場で接続する場合など）を想定しています。MCP のベストセキュリティプラクティスに沿っていないため、適切な保護策なしで本番環境に使用しないでください。

• ヘルスチェック
• システム統計情報
• タスクの監視
• バージョン情報

利用可能なツール

接続管理

• get-connection-settings：現在の Meilisearch 接続 URL と API キーの状態を表示
• update-connection-settings：別のインスタンスに接続するため、URL や API キーを更新

インデックス管理

• create-index：オプションで主キーを指定して新しいインデックスを作成します
• list-indexes：利用可能なすべてのインデックスを一覧表示します
• delete-index：既存のインデックスとそのすべてのドキュメントを削除します
• get-index-metrics：特定のインデックスの詳細なメトリクスを取得します

ドキュメント操作

• get-documents：ページネーションを使用してインデックスからドキュメントを取得します
• add-documents：インデックスにドキュメントを追加または更新します

検索

• search：フィルタリングや並べ替えのオプションを使用して、単一または複数のインデックスを柔軟に検索します

設定管理

• get-settings：インデックスの現在の設定を表示します
• update-settings：インデックスの設定（ランキング、ファセットなど）を更新します

API キー管理

• get-keys：すべての API キーを一覧表示します
• create-key：特定の権限を持つ新しい API キーを作成します
• delete-key：既存の API キーを削除します

タスク管理

• get-task：特定のタスクに関する情報を取得します
• get-tasks：オプションのフィルターを指定してタスクを一覧表示します
• cancel-tasks：保留中またはキューに登録されたタスクをキャンセルします

システム監視

• health-check：基本的なヘルスチェックを行います
• get-health-status：包括的なヘルスステータスを取得します
• get-version：Meilisearch のバージョン情報を取得します
• get-stats：データベースの統計情報を取得します
• get-system-info：システムレベルの情報を取得します

開発環境のセットアップ

前提条件

1. Meilisearch サーバーを起動する：

   # Using Docker (recommended for development)
   docker run -d -p 7700:7700 getmeili/meilisearch:v1.28
   
   # Or using brew (macOS)
   brew install meilisearch
   meilisearch
   
   # Or download from https://github.com/meilisearch/meilisearch/releases
   

2. 開発ツールをインストールする：

   # Install uv for Python package management
   pip install uv
   
   # Install Node.js for MCP Inspector testing
   # Visit https://nodejs.org/ or use your package manager
   

テストの実行

このプロジェクトには、MCP ツールの機能を検証する包括的な統合テストが含まれています。

# Run all tests
python -m pytest tests/ -v

# Run specific test file
python -m pytest tests/test_mcp_client.py -v

# Run tests with coverage report
python -m pytest --cov=src tests/

# Run tests in watch mode (requires pytest-watch)
pytest-watch tests/

重要：テストを実行するには、http://localhost:7700 で Meilisearch インスタンスが実行されている必要があります。

コード品質

# Format code with Black
black src/ tests/

# Run type checking (if mypy is configured)
mypy src/

# Lint code (if flake8 is configured)
flake8 src/ tests/

コントリビューションガイドライン

1. リポジトリをフォークしてクローンします
2. 上記の「開発環境のセットアップ」セクションに従って、開発環境をセットアップします
3. main から機能ブランチを作成します
4. 新しい機能を追加する場合は、まずテストを作成します（テスト駆動開発）
5. コミットする前に、ローカルでテストを実行し、すべてのテストが成功することを確認します
6. Black でコードをフォーマットし、コード品質を確保します
7. 説明的なコミットメッセージを付けて変更をコミットします
8. フォークにプッシュし、プルリクエストを作成します

開発ワークフロー

# Create feature branch
git checkout -b feature/your-feature-name

# Make your changes, write tests first
# Edit files...

# Run tests to ensure everything works
python -m pytest tests/ -v

# Format code
black src/ tests/

# Commit and push
git add .
git commit -m "Add feature description"
git push origin feature/your-feature-name

テストガイドライン

• 新機能にはすべてテストを含めてください
• PR を提出する前にテストが成功することを確認してください
• 説明的なテスト名と明確なアサーションを使用してください
• 成功するケースとエラーケースの両方をテストしてください
• テストを実行する前に、Meilisearch が起動していることを確認してください

リリースプロセス

このプロジェクトでは、PyPI への自動バージョン管理と公開を使用しています。リリースプロセスは、シンプルで自動化されるように設計されています。

リリースの仕組み

1. 自動公開：main ブランチで pyproject.toml のバージョン番号が変更されると、GitHub Action が自動的に以下を実行します。

   • Python パッケージをビルドします
   • 信頼された公開を使用して PyPI に公開します
   • GitHub で新しいリリースを作成します

2. バージョンの検出：ワークフローは、pyproject.toml の現在のバージョンと直前のコミットを比較し、変更を検出します

3. PyPI への公開：信頼された公開を利用する PyPA 公式の公開アクションを使用します（手動で API キーを用意する必要はありません）

新しいリリースの作成

新しいリリースを作成するには、以下の手順に従います。

1. バージョン番号を決定する

セマンティックバージョニング（MAJOR.MINOR.PATCH）に従います。

• PATCH（例：0.4.0 → 0.4.1）：バグ修正、ドキュメントの更新、小規模な改善
• MINOR（例：0.4.0 → 0.5.0）：新機能、新しい MCP ツール、大幅な機能強化
• MAJOR（例：0.5.0 → 1.0.0）：互換性を損なう変更、主要な API の変更

2. バージョンを更新して PR を作成する

# 1. Create a branch from latest main
git checkout main
git pull origin main
git checkout -b release/v0.5.0

# 2. Update version in pyproject.toml
# Edit the version = "0.4.0" line to your new version

# 3. Commit and push
git add pyproject.toml
git commit -m "Bump version to 0.5.0"
git push origin release/v0.5.0

# 4. Create PR and get it reviewed/merged
gh pr create --title "Release v0.5.0" --body "Bump version for release"

3. Main にマージする

PR が承認され、main にマージされると、GitHub Action が自動的に以下を実行します。

1. バージョンの変更を検出します
2. パッケージをビルドします
3. https://pypi.org/p/meilisearch-mcp で PyPI に公開します
4. pip install meilisearch-mcp で新しいバージョンを利用できるようにします

4. リリースを確認する

マージ後、リリースを確認します。

# Check GitHub Action status
gh run list --workflow=publish.yml

# Verify on PyPI (may take a few minutes)
pip index versions meilisearch-mcp

# Test installation of new version
pip install --upgrade meilisearch-mcp

リリースワークフローファイル

自動リリースは .github/workflows/publish.yml で処理され、次の内容が実行されます。

• main ブランチへのプッシュ時にトリガーされます
• pyproject.toml のバージョンが変更されたかどうかを確認します
• Python 3.10 と公式のビルドツールを使用します
• トラステッドパブリッシングを使用して公開します（API キーは不要です）
• デバッグ用に詳細な出力を提供します

リリースのトラブルシューティング

リリースがトリガーされない場合：コミット間で pyproject.toml のバージョンが実際に変更されているか確認してください

ビルドに失敗した場合：GitHub Actions のログで Python パッケージのビルドエラーを確認してください

PyPI への公開に失敗した場合：パッケージ名と、トラステッドパブリッシングが正しく設定されているかを確認してください

バージョンが競合する場合：新しいバージョン番号が PyPI で以前に使用されていないことを確認してください

開発版と本番版

• 開発版：pip install -e . を使用してソースからインストールします
• 本番版：pip install meilisearch-mcp を使用して PyPI からインストールします
• 特定のバージョン：pip install meilisearch-mcp==0.5.0 を使用してインストールします