Ambivo MCP Server

🚀 Ambivo Claude MCP Server

このClaude MCP（Model Context Protocol）サーバーは、Claude AIを使用してエンティティデータの自然言語クエリを行うためのAmbivo APIエンドポイントへのアクセスを提供します。

✨ 主な機能

• 自然言語クエリ：/entity/natural_queryエンドポイントを使用して、エンティティデータに対して自然言語クエリを実行します。
• JWT認証：Bearerトークン認証を使用して安全にアクセスします。
• レート制限：APIの乱用を防止するための組み込みのレート制限があります。
• トークンキャッシュ：キャッシュを使用した効率的なトークン検証を行います。
• エラーハンドリング：詳細なエラーメッセージを伴う包括的なエラーハンドリングを行います。
• リトライロジック：失敗したリクエストに対して指数バックオフで自動的にリトライします。

📚 詳細ドキュメント

1. set_auth_token

Ambivo APIとの認証に使用するJWT Bearerトークンを設定します。

パラメーター:

• token (文字列、必須): JWT Bearerトークン

使用例:

{
  "token": "your-jwt-token-here"
}

2. natural_query

Ambivoのエンティティデータに対して自然言語クエリを実行します。

パラメーター:

• query (文字列、必須): 取得したいデータを説明する自然言語クエリ
• response_format (文字列、オプション): レスポンス形式 - "table"、"natural"、または "both" (デフォルト: "both")

クエリの例:

• "今週作成されたリードを表示して"
• "gmailアドレスを持つコンタクトを検索して"
• "10,000ドル以上の商談を一覧表示して"
• "過去7日間のattribution_sourceがgoogle_adsのリードを表示して"

使用例:

{
  "query": "Show me leads created this week with attribution_source google_ads",
  "response_format": "both"
}

📦 インストール

オプション1: PyPIからインストール（推奨）

pip install ambivo-mcp-server

オプション2: ソースからインストール

git clone https://github.com/ambivo-corp/ambivo-mcp-server.git
cd ambivo-mcp-server
pip install -e .

💻 サーバーの起動

# pipを通じてインストールした場合
ambivo-mcp-server

# またはPythonモジュールを使用する場合
python -m ambivo_mcp_server.server

🔧 設定

サーバーは以下のデフォルト設定を使用します:

• ベースURL: https://goferapi.ambivo.com
• タイムアウト: 30秒
• コンテンツタイプ: application/json

必要に応じて、AmbivoAPIClientクラスでこれらの設定を変更できます。

🔑 認証

1. まず、set_auth_tokenツールを使用して認証トークンを設定します。
2. トークンは、すべての後続のAPIリクエストにBearerトークンとして含まれます。
3. トークンは、Ambivo API認証から取得した有効なJWTトークンである必要があります。

⚠️ エラーハンドリング

サーバーは包括的なエラーハンドリングを提供します:

• 認証エラー: トークンが欠落しているか無効な場合に明確なメッセージを表示します。
• HTTPエラー: 詳細なHTTPステータスコードとレスポンスメッセージを表示します。
• バリデーションエラー: パラメーターのバリデーションを行い、有益なエラーメッセージを表示します。
• ネットワークエラー: タイムアウトと接続エラーをハンドリングします。

📄 APIエンドポイント

このMCPサーバーは、以下のAmbivo APIエンドポイントとインターフェースを持ちます:

/entity/natural_query

• メソッド: POST
• 目的: エンティティデータの取得のための自然言語クエリを処理します。
• 認証: 必須 (JWT Bearerトークン)
• コンテンツタイプ: application/json

/entity/data

• メソッド: POST
• 目的: 構造化されたパラメーターを使用した直接的なエンティティデータへのアクセスを行います。
• 認証: 必須 (JWT Bearerトークン)
• コンテンツタイプ: application/json

💻 使用例

1. 認証の設定

{
  "tool": "set_auth_token",
  "arguments": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

2. 自然言語クエリ

{
  "tool": "natural_query", 
  "arguments": {
    "query": "Show me all leads created in the last 30 days with phone numbers",
    "response_format": "both"
  }
}

3. 直接的なエンティティクエリ

{
  "tool": "entity_data",
  "arguments": {
    "entity_type": "contact",
    "filters": {"email": {"$regex": "@gmail.com$"}},
    "limit": 100,
    "sort": {"created_date": -1}
  }
}

🛠️ 開発

このMCPサーバーを拡張するには:

1. 新しいツールの追加：handle_list_tools() と handle_call_tool() 関数に追加のツールを実装します。
2. APIクライアントの変更：AmbivoAPIClient クラスを拡張して、追加のエンドポイントをサポートします。
3. 設定の更新：設定セクションのデフォルト設定を変更します。

🐞 トラブルシューティング

一般的な問題

1. "Authentication required"エラー：最初に set_auth_token を呼び出したことを確認してください。
2. HTTP 401/403エラー：JWTトークンが有効で期限切れでないことを確認してください。
3. 接続タイムアウト：ネットワーク接続とAPIエンドポイントの可用性を確認してください。
4. 無効なパラメーター：ツールのスキーマを確認して、必須パラメーターとオプションパラメーターを確認してください。

ロギング

サーバーは重要なイベントとエラーをログに記録します。デバッグ情報はコンソール出力を確認してください。