MCP Arangodb Async

🚀 Python用ArangoDB MCPサーバー

このサーバーは、Claude DesktopやAugment CodeなどのAIアシスタントに高度なArangoDB操作を提供する、本番環境で使用可能なModel Context Protocol (MCP) サーバーです。非同期優先のPythonアーキテクチャ、包括的なグラフ管理、柔軟なコンテンツ変換 (JSON、Markdown、YAML、テーブル)、バックアップ/リストア機能、および分析機能を備えています。

🚀 クイックスタート

クイックリンク

• 📚 ドキュメント: https://github.com/PCfVW/mcp-arango-async/tree/master/docs
• 🚀 クイックスタート: https://github.com/PCfVW/mcp-arango-async/blob/master/docs/getting-started/quickstart.md
• 🔧 ArangoDBのセットアップ: https://github.com/PCfVW/mcp-arango-async/blob/master/docs/getting-started/install-arangodb.md
• 🗄️ マルチテナンシーガイド: https://github.com/PCfVW/mcp-arango-async/blob/master/docs/user-guide/multi-tenancy-guide.md
• ⚙️ CLIリファレンス: https://github.com/PCfVW/mcp-arango-async/blob/master/docs/user-guide/cli-reference.md
• 📖 ツールリファレンス: https://github.com/PCfVW/mcp-arango-async/blob/master/docs/user-guide/tools-reference.md
• 🎯 MCPデザインパターン: https://github.com/PCfVW/mcp-arango-async/blob/master/docs/user-guide/mcp-design-patterns.md
• 📝 変更履歴: https://github.com/PCfVW/mcp-arango-async/blob/master/docs/developer-guide/changelog.md
• 🐛 問題報告: https://github.com/PCfVW/mcp-arango-async/issues

✨ 主な機能

• ✅ 46のMCPツール - 完全なArangoDB操作 (クエリ、コレクション、インデックス、グラフ)
• ✅ マルチテナンシー - 複数のデータベースでの作業、環境切り替え、クロスデータベース操作
• ✅ MCPデザインパターン - 段階的な探索、コンテキスト切り替え、ツールのアンロード (トークン節約率98.7%)
• ✅ グラフ管理 - 名前付きグラフの作成、トラバース、バックアップ/リストア
• ✅ コンテンツ変換 - JSON、Markdown、YAML、およびテーブル形式
• ✅ バックアップ/リストア - コレクションおよびグラフレベルのバックアップと検証
• ✅ 分析 - クエリプロファイリング、実行計画の説明、グラフ統計
• ✅ デュアルトランスポート - stdio (デスクトップクライアント) とHTTP (Web/コンテナ化)
• ✅ Dockerサポート - 分離と再現性のためにDockerで実行
• ✅ 本番環境対応 - リトライロジック、緩やかな劣化、包括的なエラー処理
• ✅ 型安全 - すべてのツール引数に対するPydantic検証

アーキテクチャ

┌────────────────────┐      ┌─────────────────────┐       ┌──────────────────┐
│   MCP Client       │      │  ArangoDB MCP       │       │   ArangoDB       │
│ (Claude, Augment)  │─────▶│  Server (Python)    │─────▶│  (Docker)        │
│                    │      │  • 46 Tools         │       │  • Multi-Model   │
│                    │      │  • Multi-Tenancy    │       │  • Graph Engine  │
│                    │      │  • Graph Mgmt       │       │  • AQL Engine    │
│                    │      │  • MCP Patterns     │       │                  │
└────────────────────┘      └─────────────────────┘       └──────────────────┘

📦 インストール

前提条件

• DockerとDocker Compose がインストールされていること
• Python 3.11以上 (mcp-arangodb-async用)

ステップ1: ArangoDBのインストール

docker-compose.yml ファイルを作成します。

services:
  arangodb:
    image: arangodb:3.11
    environment:
      ARANGO_ROOT_PASSWORD: ${ARANGO_ROOT_PASSWORD:-changeme}
    ports:
      - "8529:8529"
    volumes:
      - arangodb_data:/var/lib/arangodb3
      - arangodb_apps:/var/lib/arangodb3-apps
    healthcheck:
      test: arangosh --server.username root --server.password "$ARANGO_ROOT_PASSWORD" --javascript.execute-string "require('@arangodb').db._version()" > /dev/null 2>&1 || exit 1
      interval: 5s
      timeout: 2s
      retries: 30
    restart: unless-stopped

volumes:
  arangodb_data:
    driver: local
  arangodb_apps:
    driver: local

.env ファイルを作成します。

# ArangoDB root password
ARANGO_ROOT_PASSWORD=changeme

# MCP Server connection settings
ARANGO_URL=http://localhost:8529
ARANGO_DB=mcp_arangodb_test
ARANGO_USERNAME=mcp_arangodb_user
ARANGO_PASSWORD=mcp_arangodb_password

ArangoDBを起動します。

docker compose --env-file .env up -d

ステップ2: mcp-arangodb-asyncのインストール

MCPサーバーパッケージをインストールします。

pip install mcp-arangodb-async

# 環境を作成してインストール
conda create -n mcp-arango python=3.11
conda activate mcp-arango
pip install mcp-arangodb-async

# またはmamba/micromambaを使用する場合:
# mamba create -n mcp-arango python=3.11
# mamba activate mcp-arango
# pip install mcp-arangodb-async

# 環境を作成してインストール
uv venv .venv --python 3.11
uv pip install mcp-arangodb-async

ステップ3: データベースとユーザーの作成

MCPサーバー用のデータベースとユーザーを作成します。

maa db add mcp_arangodb_test \
  --url http://localhost:8529 \
  --with-user mcp_arangodb_user \
  --env-file .env

期待される出力:

The following actions will be performed:
  [ADD] Database 'mcp_arangodb_test'
  [ADD] User 'mcp_arangodb_user' (active: true)
  [GRANT] Permission rw: mcp_arangodb_user → mcp_arangodb_test

Are you sure you want to proceed? [y/N]: y
db add:
[ADDED] Database 'mcp_arangodb_test'
[ADDED] User 'mcp_arangodb_user' (active: true)
[GRANTED] Permission rw: mcp_arangodb_user → mcp_arangodb_test

データベース接続を確認します。

# 環境変数を設定
export ARANGO_URL=http://localhost:8529
export ARANGO_DB=mcp_arangodb_test
export ARANGO_USERNAME=mcp_arangodb_user
export ARANGO_PASSWORD=mcp_arangodb_password

# ヘルスチェックを実行
maa health

期待される出力:

{"status": "healthy", "database_connected": true, "database_info": {"version": "3.11.x", "name": "mcp_arangodb_test"}}

ステップ4: MCPホストの設定

MCPホストを設定してサーバーを使用するようにします。設定にはデータベース接続用の環境変数が含まれます。設定ファイルの場所はMCPホストによって異なります。Claude Desktopの場合、ファイルは以下の場所にあります。

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

設定内容:

{
  "mcpServers": {
    "arangodb": {
      "command": "python",
      "args": ["-m", "mcp_arangodb_async"],
      "env": {
        "ARANGO_URL": "http://localhost:8529",
        "ARANGO_DB": "mcp_arangodb_test",
        "ARANGO_USERNAME": "mcp_arangodb_user",
        "ARANGO_PASSWORD": "mcp_arangodb_password"
      }
    }
  }
}

{
  "mcpServers": {
    "arangodb": {
      "command": "conda",
      "args": ["run", "-n", "mcp-arango", "maa", "server"],
      "env": {
        "ARANGO_URL": "http://localhost:8529",
        "ARANGO_DB": "mcp_arangodb_test",
        "ARANGO_USERNAME": "mcp_arangodb_user",
        "ARANGO_PASSWORD": "mcp_arangodb_password"
      }
    }
  }
}

{
  "mcpServers": {
    "arangodb": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/project", "maa", "server"],
      "env": {
        "ARANGO_URL": "http://localhost:8529",
        "ARANGO_DB": "mcp_arangodb_test",
        "ARANGO_USERNAME": "mcp_arangodb_user",
        "ARANGO_PASSWORD": "mcp_arangodb_password"
      }
    }
  }
}

設定を更新した後、MCPクライアントを再起動します。

接続をテストします: MCPクライアントに "List all collections in the ArangoDB database" と問い合わせます。 アシスタントが正常に接続し、コレクションをリストするはずです。

💻 使用例

コードベースのグラフ分析のユースケース例

コードベースをグラフとしてモデル化し、依存関係を分析し、循環参照を見つけ、アーキテクチャを理解することができます。以下は、より長い コードベース分析の例 からの抜粋です。

# 1. グラフ構造を作成
Ask Claude: "Create a graph called 'codebase' with vertex collections 'modules' and 'functions', and edge collection 'calls' connecting functions"

# 2. コードベースのデータをインポート
Ask Claude: "Insert these modules into the 'modules' collection: [...]"

# 3. 依存関係を分析
Ask Claude: "Find all functions that depend on the 'auth' module using graph traversal"

# 4. 循環依存関係を検出
Ask Claude: "Check for circular dependencies in the codebase graph"

# 5. アーキテクチャ図を生成
Ask Claude: "Export the codebase graph structure as Markdown for visualization"

📖 詳細な例

📚 詳細ドキュメント

入門編

• ArangoDBのインストール
• クイックスタートガイド
• ソースからのインストール
• 最初のインタラクション

設定編

• トランスポート設定
• 環境変数

ユーザーガイド

• ツールリファレンス
• トラブルシューティング

開発者ガイド

• アーキテクチャの概要
• 低レベルMCPの理論
• HTTPトランスポート
• 変更履歴

サンプル

• コードベースの依存関係分析

📖 完全なドキュメント: https://github.com/PCfVW/mcp-arango-async/tree/master/docs

トラブルシューティング

一般的な問題

データベース接続が失敗する場合:

# ArangoDBが実行中か確認
docker ps | grep arangodb

# 接続をテスト
curl http://localhost:8529/_api/version

# 資格情報を確認
maa health

Claude Desktopでサーバーが起動しない場合:

# Pythonのインストールを確認
python --version  # 3.11以上である必要があります

# モジュールを直接テスト
maa health

# Claude Desktopのログを確認
# Windows: %APPDATA%\Claude\logs\
# macOS: ~/Library/Logs/Claude/

ツールの実行エラーが発生する場合:

• ArangoDBが正常か確認: docker compose ps
• 環境変数が正しく設定されていることを確認
• 詳細なエラーメッセージを確認するには、サーバーのログを確認

📖 完全なトラブルシューティングガイド

なぜArangoDBにDockerを使用するのか？

✅ 安定性 - 分離された環境で、ホストとの競合がない
✅ ゼロインストール - docker compose で簡単に起動/停止
✅ 再現性 - すべての環境で同じイメージを使用
✅ ヘルスチェック - 組み込みの準備完了検証
✅ 高速リセット - 簡単にクリーンなインスタンスを再作成
✅ ポータビリティ - Windows/macOS/Linuxで一貫した動作

📄 ライセンス

• このプロジェクト: Apache License 2.0
• ArangoDB 3.11: Apache License 2.0
• ArangoDB 3.12以上: Business Source License 1.1 (BUSL-1.1)

⚠️ 重要: このリポジトリはArangoDBのバイナリに対する権利を付与しません。デプロイバージョンに応じてArangoDBのライセンスに準拠する必要があります。

📖 ライセンスの詳細

コントリビューション

コントリビューションは歓迎されます！ガイドラインについてはドキュメントを参照してください。

📖 アーキテクチャの決定事項

サポート

• 問題報告
• ディスカッション
• ドキュメント

謝辞

このプロジェクトは以下の技術を使用して構築されています。

• Model Context Protocol by Anthropic
• python-arango - 公式ArangoDB Pythonドライバー
• Pydantic - データ検証
• Starlette - HTTPトランスポート
• ArangoDB - マルチモデルデータベース