MCP Server for ArangoDB

ArangoDB 用 MCP サーバー

ArangoDB 用の Model Context Protocol サーバー

これは、ArangoDB を通じてデータベース操作機能を提供する、TypeScript ベースの MCP サーバーです。データベースの基本操作を実装し、MCP ツールを通じて ArangoDB とシームレスに連携できます。Claude アプリや、Cline のような MCP に対応した VSCode 拡張機能でも使用できます。

機能

ツール

ツール	カテゴリ	読み取り専用	データ／スキーマの変更	目的
arango_query	クエリ	いいえ	場合による	バインド変数、結果の上限、クエリガードレールを指定して、一般的な AQL を実行します。
arango_read_query	クエリ	はい	いいえ	読み取り専用の AQL を実行し、書き込み／DDL キーワードを拒否します。
arango_validate_query	クエリ	はい	いいえ	AQL を実行せずに解析し、検証します。
arango_explain_query	クエリ	はい	いいえ	AQL の実行計画、インデックスの使用状況、オプティマイザーの出力を調べます。
arango_describe_database	検出	はい	いいえ	コレクション、件数、インデックス、サンプルフィールドの概要を示します。
arango_list_collections	検出	はい	いいえ	設定済みデータベース内のコレクションを一覧表示します。
arango_get_collection	検出	はい	いいえ	コレクションのプロパティ、件数、インデックスを返します。
arango_create_collection	コレクション	いいえ	はい	ドキュメントコレクションまたはエッジコレクションを作成します。
arango_drop_collection	コレクション	いいえ	はい	confirm: true を必須として、コレクションを削除します。
arango_get_document	ドキュメント	はい	いいえ	コレクションと _key を指定して、1 件のドキュメントを取得します。
arango_list_documents	ドキュメント	はい	いいえ	limit と offset によるページネーションでドキュメントを一覧表示します。
arango_count_documents	ドキュメント	はい	いいえ	コレクション内のドキュメント数を数えます。
arango_sample_documents	ドキュメント	はい	いいえ	スキーマの検出に役立つ、少数のランダムなサンプルを返します。
arango_insert	ドキュメント	いいえ	はい	コレクションに 1 件のドキュメントを挿入します。
arango_bulk_insert	ドキュメント	いいえ	はい	1 回のリクエストで最大 1000 件のドキュメントを挿入します。
arango_update	ドキュメント	いいえ	はい	_key を指定して、1 件のドキュメントを部分更新します。
arango_bulk_update	ドキュメント	いいえ	はい	_key または _id を指定して、最大 1000 件のドキュメントをパッチ更新します。
arango_remove	ドキュメント	いいえ	はい	_key を指定して、1 件のドキュメントを削除します。
arango_list_indexes	インデックス	はい	いいえ	コレクションのインデックスを一覧表示します。
arango_create_index	インデックス	いいえ	はい	永続、地理空間、TTL、または転置インデックスを作成します。
arango_list_views	ArangoSearch	はい	いいえ	ArangoSearch と検索エイリアスのビューを一覧表示します。
arango_create_search_view	ArangoSearch	いいえ	はい	コレクションにリンクされた ArangoSearch ビューを作成します。
arango_search	ArangoSearch	はい	いいえ	アナライザーを考慮した BM25 ランキングを使用して、ArangoSearch ビューを検索します。
arango_list_analyzers	アナライザー	はい	いいえ	ArangoSearch アナライザーを一覧表示します。
arango_create_analyzer	アナライザー	いいえ	はい	ArangoSearch アナライザーを作成します。
arango_list_graphs	グラフ	はい	いいえ	名前付きグラフを一覧表示します。
arango_create_graph	グラフ	いいえ	はい	1 つのエッジ定義を持つ名前付きグラフを作成します。
arango_insert_edge	グラフ	いいえ	はい	_from と _to を含むエッジドキュメントを挿入します。
arango_traverse	グラフ	はい	いいえ	エッジコレクションまたは名前付きグラフを使用して、開始頂点からエッジをたどります。
arango_shortest_path	グラフ	はい	いいえ	エッジコレクションまたは名前付きグラフを使用して、2 つの頂点間の最短経路を見つけます。
arango_backup	バックアップ	いいえ	ファイルシステム	ARANGO_BACKUP_ROOT 配下の JSON ファイルにコレクションをバックアップします。

すべてのツールは、成功時に JSON テキストと structuredContent を返します。読み取り中心のツールでは、エージェントが扱いやすい応答を保つため、上限を設けた limit パラメーターを公開しています。該当する場合、クエリツールは memoryLimit、maxRuntime、failOnWarning などのガードレールにも対応しています。

インストール

NPM を使ったインストール

NPM を使って arango-server をグローバルにインストールするには、次のコマンドを実行します。

npm install -g arango-server

NPX を使った実行

インストールせずに arango-server を直接実行するには、次のコマンドを使用します。

npx -y arango-server

VSCode Agent の設定

arango-server を VSCode Copilot エージェントで使用するには、VSCode 1.99.0 以降がインストールされている必要があります。次の手順に従ってください。

1. MCP 設定ファイルを作成または編集します：

   • ワークスペース固有の設定：ワークスペース内に .vscode/mcp.json ファイルを作成または編集します。

   • ユーザー固有の設定：任意で、ユーザー設定の setting(mcp) にサーバーを指定すると、すべてのワークスペースで MCP サーバーを有効にできます。

     ヒント：設定ファイルのセットアップ方法の詳細については、VSCode の MCP 設定に関するドキュメントをこちらで参照してください。

2. 次の設定を追加します：

   {
     "servers": {
       "arango-mcp": {
         "type": "stdio",
         "command": "npx",
         "args": ["-y", "arango-server"],
         "env": {
           "ARANGO_URL": "http://localhost:8529",
           "ARANGO_DB": "your_database_name",
           "ARANGO_USERNAME": "your_username",
           "ARANGO_PASSWORD": "your_password"
         }
       }
     }
   }
   

3. MCP サーバーを起動します：

   • VSCode でコマンドパレットを開きます（Mac の場合は Ctrl+Shift+P または Cmd+Shift+P）。
   • MCP: Start Server コマンドを実行し、一覧から arango-mcp を選択します。

4. サーバーを確認します：

   • VSCode でチャットビューを開き、エージェントモードに切り替えます。
   • Tools ボタンを使用して、arango-server のツールが利用可能であることを確認します。

Claude Desktop で使用する場合

次の場所を開きます：Settings > Developer > Edit Config または

• MacOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%/Claude/claude_desktop_config.json

セットアップ方法については、MCP のドキュメントもご確認ください。

OpenCode で使用する場合

opencode.json や opencode.jsonc などの OpenCode 設定ファイルに、次の設定を追加します：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "arango": {
      "type": "local",
      "command": ["npx", "-y", "arango-server"],
      "enabled": true,
      "environment": {
        "ARANGO_URL": "your_database_url",
        "ARANGO_DB": "your_database_name",
        "ARANGO_USERNAME": "your_username",
        "ARANGO_PASSWORD": "your_password"
      }
    }
  }
}

OpenCode を再起動した後、ArangoDB のタスクで arango MCP ツールを使用するよう指示してください。

Cline VSCode Extension で使用する場合

次の場所を開きます：Cline Extension > MCP Servers > Edit Configuration または

• MacOS：~/Library/Application Support/Code/User/globalStorage/cline.cline/config.json
• Windows：%APPDATA%/Code/User/globalStorage/cline.cline/config.json

mcpServers セクションに次の設定を追加します：

{
  "mcpServers": {
    "arango": {
      "command": "npx",
      "args": ["-y", "arango-server"],
      "env": {
        "ARANGO_URL": "your_database_url",
        "ARANGO_DB": "your_database_name",
        "ARANGO_USERNAME": "your_username",
        "ARANGO_PASSWORD": "your_password"
      }
    }
  }
}

上記の設定を使用して、WARP でこのサーバーを動作させることもできます。

環境変数

サーバーには次の環境変数が必要です：

• ARANGO_URL - ArangoDB サーバーの URL（注：8529 はローカル開発での ArangoDB のデフォルトポートです）
• ARANGO_DB - データベース名
• ARANGO_USERNAME - データベースユーザー
• ARANGO_PASSWORD - データベースのパスワード
• ARANGO_BACKUP_ROOT - arango_backup の出力先となる任意のルートディレクトリ。デフォルトは ./backups です。

使用方法

意味のあるプロンプトであれば、ほぼどのような内容でも指定でき、Claude が適切な関数の実行を試みます。

プロンプトの例：

• 「データベース内のすべてのコレクションを一覧表示して」
• 「すべてのユーザーをクエリして」
• 「'users' コレクションに、名前が 'John Doe'、メールアドレスが "[email protected]' の新しいドキュメントを挿入して」
• 「キーが '123456' または名前が 'Jane Doe' のドキュメントを更新して、年齢を 48 に変更して」
• 「'products' という名前の新しいコレクションを作成して」

Claude App での使用

Cline VSCode 拡張機能での使用方法

すべてのユーザーをクエリします：

{
  "query": "FOR user IN users RETURN user",
  "limit": 100
}

新しいドキュメントを挿入します：

{
  "collection": "users",
  "document": {
    "name": "John Doe",
    "email": "[email protected]"
  }
}

ドキュメントを更新します：

{
  "collection": "users",
  "key": "123456",
  "update": {
    "name": "Jane Doe"
  }
}

ドキュメントを削除します：

{
  "collection": "users",
  "key": "123456"
}

すべてのコレクションを一覧表示します：

{
} // No parameters required

データベースのコレクションをバックアップします：

{
  "outputDir": "nightly_1", // Safe subdirectory name under ARANGO_BACKUP_ROOT. Absolute paths and slashes are rejected.
  "collection": "users", // Optional. If omitted, all collections are backed up.
  "docLimit": 1000 // Optional. Maximum documents per collection. Defaults to 1000 and is capped at 10000.
}

バックアップの保存先を選択するには、ARANGO_BACKUP_ROOT を設定します。このサーバーは、任意のファイル書き込みリスクを軽減するため、パストラバーサル、絶対パス、シンボリックリンクによるパスの逸脱、および既存の出力ファイルを拒否します。

新しいコレクションを作成します：

{
  "name": "products",
  "type": "document", // "document" or "edge" (optional, defaults to "document")
  "waitForSync": false // Optional, defaults to false
}

コレクションを削除します：

{
  "name": "products",
  "confirm": true
}

注：このサーバーはデータベース構造に依存せず、ArangoDB のドキュメントコレクションとエッジコレクションのモデルに従っていれば、どのようなコレクション名や構造でも使用できます。

免責事項

開発用途のみ

このツールはローカル開発環境専用に設計されています。技術的には本番データベースに接続できますが、重大なセキュリティリスクが生じるため、明示的に推奨されていません。責任の分離と本番データの保護のため、開発データベースでのみ使用しています。

開発

コントリビューションを歓迎します。プルリクエストを作成する前に、CONTRIBUTING.md をお読みください。

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

2. 依存関係をインストールします：

   npm run build
   

3. 自動再ビルドを有効にして開発する場合：

   npm run watch
   

デバッグ

MCP サーバーは標準入出力を介して通信するため、デバッグが難しい場合があります。開発には、MCP Inspector を使用したデバッグをおすすめします：

npm run inspector

Inspector は、ブラウザーでデバッグツールにアクセスするための URL を提供します。

テスト

npm test

テストスイートには、絶対パス、パストラバーサル、シンボリックリンクによるパスの逸脱を防ぐ arango_backup のパス処理に関する回帰テストが含まれています。

ローカルの Docker ArangoDB インスタンスで統合スモークテストを実行するには：

npm run test:integration

統合テストでは、一時的な Docker ArangoDB インスタンスを起動し、標準入出力経由で MCP サーバーを起動してツールを一覧表示し、outputSchema を検証します。次に、一時コレクションを作成してドキュメントを挿入し、limit を指定してクエリを実行します。また、バックアップの出力先が ARANGO_BACKUP_ROOT 配下に収まること、絶対バックアップパスが拒否されることを検証した後、コレクションをクリーンアップし、コンテナーを停止します。

テストコンテナーは、ローカルの ArangoDB（8529）との競合を避けるため、デフォルトでホストポート 18529 を使用します。必要に応じて ARANGO_PORT で上書きしてください。

ライセンス

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