ConnectWise API Gateway MCP Server

ConnectWise API Gateway MCP サーバー

この Model Context Protocol（MCP）サーバーは、ConnectWise Manage API を操作するための包括的なインターフェースを提供します。開発者と AI アシスタントの両方が、API の検出、実行、管理を簡単に行えるようにします。

主な機能

• API の検出： キーワードまたは自然言語を使って、ConnectWise API エンドポイントを検索、調査できます
• 簡素化された API の実行： 使いやすいパラメーター処理と自動エラー管理により、API 呼び出しを実行できます
• 高速メモリーシステム： 頻繁に使う API クエリを保存、取得して、ワークフローを効率化できます
• API への直接アクセス： エンドポイント、メソッド、パラメーターを完全に制御して、カスタム API リクエストを送信できます

主な特徴

• データベースを活用した API の検出： ConnectWise API 定義 JSON から作成された SQLite データベースを使用して、エンドポイントをすばやく効率的に検索できます
• 自然言語検索： 必要な内容を会話形式で説明して、関連する API エンドポイントを見つけられます
• カテゴリ別 API ナビゲーション： 機能カテゴリ別に整理された API エンドポイントを閲覧できます
• 詳細なドキュメントへのアクセス： パラメーター、スキーマ、レスポンス形式など、API エンドポイントに関する包括的な情報を確認できます
• 適応型学習： 使用状況の追跡を通じて、システムが最も有用な API 呼び出しを学習します

インストールとセットアップ

前提条件

• Python 3.10 以降
• ConnectWise Manage API の認証情報へのアクセス
• ConnectWise API 定義ファイル（manage.json）— リポジトリに含まれています

インストール手順

オプション 1：GitHub NPM パッケージを使用する（推奨）

パッケージは GitHub から直接インストールできます。

npm install -g jasondsmith72/CWM-API-Gateway-MCP

この方法では、すべての依存関係が自動的に処理され、Claude Desktop の設定も簡単になります。

オプション 2：手動インストール

Windows

1. リポジトリをクローンまたはダウンロードします：

   git clone https://github.com/jasondsmith72/CWM-API-Gateway-MCP.git
   cd CWM-API-Gateway-MCP
   

2. パッケージをインストールします：

   pip install -e .
   

macOS

NPM インストールを使用する場合は、次のコマンドを実行するだけです。

npm install -g jasondsmith72/CWM-API-Gateway-MCP

手動でインストールする場合：

1. Python 3.10 以降がまだインストールされていない場合は、インストールします：

   # Using Homebrew
   brew install [email protected]
   
   # Or using pyenv
   brew install pyenv
   pyenv install 3.10.0
   pyenv global 3.10.0
   

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

   git clone https://github.com/jasondsmith72/CWM-API-Gateway-MCP.git
   cd CWM-API-Gateway-MCP
   

3. 仮想環境を設定します（推奨）：

   python3 -m venv venv
   source venv/bin/activate
   

4. パッケージをインストールします：

   pip install -e .
   

Linux（Ubuntu/Debian）

NPM インストールを使用する場合は、次のコマンドを実行するだけです。

sudo npm install -g jasondsmith72/CWM-API-Gateway-MCP

手動でインストールする場合：

1. Python 3.10 以降がまだインストールされていない場合は、インストールします：

   # For Ubuntu 22.04+
   sudo apt update
   sudo apt install python3.10 python3.10-venv python3.10-dev python3-pip
   
   # For older versions of Ubuntu/Debian
   sudo add-apt-repository ppa:deadsnakes/ppa
   sudo apt update
   sudo apt install python3.10 python3.10-venv python3.10-dev python3-pip
   

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

   git clone https://github.com/jasondsmith72/CWM-API-Gateway-MCP.git
   cd CWM-API-Gateway-MCP
   

3. 仮想環境を設定します（推奨）：

   python3.10 -m venv venv
   source venv/bin/activate
   

4. パッケージをインストールします：

   pip install -e .
   

インストール後の手順

いずれのプラットフォーム（Windows、macOS、Linux）でも、インストール後に以下の手順を完了してください。

1.（任意）API データベースを構築する

このリポジトリには、構築済みのデータベースが含まれているため、この手順は任意です。より新しい ConnectWise API 定義ファイルを使用する必要がある場合にのみ実行してください。

# On Windows
python build_database.py path/to/manage.json

# On macOS/Linux
python3 build_database.py path/to/manage.json

この手順は一度だけ実行すればよく、ConnectWise API の定義が変更された場合に再度実行します。

2. API 認証情報を設定する

ConnectWise の認証情報を使って、以下の環境変数を設定します。

CONNECTWISE_API_URL=https://na.myconnectwise.net/v4_6_release/apis/3.0
CONNECTWISE_COMPANY_ID=your_company_id
CONNECTWISE_PUBLIC_KEY=your_public_key
CONNECTWISE_PRIVATE_KEY=your_private_key
CONNECTWISE_AUTH_PREFIX=yourprefix+  # Prefix required by ConnectWise for API authentication

これらの認証情報は、次のように認証処理で使用されます。

• CONNECTWISE_API_URL：ConnectWise インスタンスへのすべての API リクエストのベース URL

  url = f"{API_URL}{endpoint}"  # e.g., https://na.myconnectwise.net/v4_6_release/apis/3.0/service/tickets
  

• CONNECTWISE_COMPANY_ID：会社を識別するため、各リクエストの「clientId」ヘッダーに含めます

  headers = {'clientId': COMPANY_ID, ...}
  

• CONNECTWISE_PUBLIC_KEY と CONNECTWISE_PRIVATE_KEY：AUTH_PREFIX と組み合わせて、基本認証の認証情報を作成します

  username = f"{AUTH_PREFIX}{PUBLIC_KEY}"  # e.g., "yourprefix+your_public_key"
  password = PRIVATE_KEY
  credentials = f"{username}:{password}"  # Combined into "yourprefix+your_public_key:your_private_key"
  

• CONNECTWISE_AUTH_PREFIX：認証ユーザー名で公開鍵の前に付ける必須のプレフィックスです。ConnectWise API は、統合の種類を識別するためにこのプレフィックスを必要とします（例：「api+」、「integration+」など）。

すべてのリクエストで送信される最終的な HTTP ヘッダーは、次のようになります。

'Authorization': 'Basic [base64 encoded credentials]'
'clientId': 'your_company_id'
'Content-Type': 'application/json'

Claude Desktop の設定

Claude Desktop と連携する方法は 2 つあります。

方法 1：NPM パッケージを使用する（推奨）

NPM を使用してパッケージをインストールします：

npm install -g jasondsmith72/CWM-API-Gateway-MCP

次に、Claude Desktop（claude_desktop_config.json）を設定します：

{
  "mcpServers": {
    "CWM-API-Gateway-MCP": {
      "command": "npx",
      "args": [
        "-y",
        "@jasondsmith72/CWM-API-Gateway-MCP"
      ],
      "env": {
        "CONNECTWISE_API_URL": "https://na.myconnectwise.net/v4_6_release/apis/3.0",
        "CONNECTWISE_COMPANY_ID": "your_company_id",
        "CONNECTWISE_PUBLIC_KEY": "your_public_key",
        "CONNECTWISE_PRIVATE_KEY": "your_private_key",
        "CONNECTWISE_AUTH_PREFIX": "yourprefix+"
      }
    }
  }
}

方法 2：Node.js スクリプトを使用する（代替方法）

リポジトリをクローンし、依存関係をインストール済みの場合は、付属の Node.js スクリプトを使用できます：

{
  "mcpServers": {
    "CWM-API-Gateway-MCP": {
      "command": "node",
      "args": ["C:/path/to/CWM-API-Gateway-MCP/bin/server.js"],
      "env": {
        "CONNECTWISE_API_URL": "https://na.myconnectwise.net/v4_6_release/apis/3.0",
        "CONNECTWISE_COMPANY_ID": "your_company_id",
        "CONNECTWISE_PUBLIC_KEY": "your_public_key",
        "CONNECTWISE_PRIVATE_KEY": "your_private_key",
        "CONNECTWISE_AUTH_PREFIX": "yourprefix+"
      }
    }
  }
}

方法 3：Python スクリプトのパスを直接指定する

Python スクリプトを直接使用する場合：

{
  "mcpServers": {
    "CWM-API-Gateway-MCP": {
      "command": "python",
      "args": ["C:/path/to/CWM-API-Gateway-MCP/api_gateway_server.py"],
      "env": {
        "CONNECTWISE_API_URL": "https://na.myconnectwise.net/v4_6_release/apis/3.0",
        "CONNECTWISE_COMPANY_ID": "your_company_id",
        "CONNECTWISE_PUBLIC_KEY": "your_public_key",
        "CONNECTWISE_PRIVATE_KEY": "your_private_key",
        "CONNECTWISE_AUTH_PREFIX": "yourprefix+"
      }
    }
  }
}

macOS と Linux では、適切なパス形式を使用します：

{
  "mcpServers": {
    "CWM-API-Gateway-MCP": {
      "command": "python3",
      "args": ["/path/to/CWM-API-Gateway-MCP/api_gateway_server.py"],
      "env": {
        "CONNECTWISE_API_URL": "https://na.myconnectwise.net/v4_6_release/apis/3.0",
        "CONNECTWISE_COMPANY_ID": "your_company_id",
        "CONNECTWISE_PUBLIC_KEY": "your_public_key",
        "CONNECTWISE_PRIVATE_KEY": "your_private_key",
        "CONNECTWISE_AUTH_PREFIX": "yourprefix+"
      }
    }
  }
}

テストする場合は、コマンドラインからサーバーを直接実行できます：

# If installed via NPM
cwm-api-gateway-mcp

# If using the Node.js script (after cloning the repository)
node bin/server.js

# Or using the Python script directly
# On Windows
python api_gateway_server.py

# On macOS/Linux
python3 api_gateway_server.py

利用可能なツール

API Gateway MCP サーバーは、ConnectWise API を操作するための複数のツールを提供します：

API 検索ツール

ツール	説明
search_api_endpoints	クエリ文字列を使用して API エンドポイントを検索します
natural_language_api_search	自然言語による説明を使用してエンドポイントを検索します
list_api_categories	利用可能なすべての API カテゴリを一覧表示します
get_category_endpoints	特定のカテゴリに属するすべてのエンドポイントを一覧表示します
get_api_endpoint_details	特定のエンドポイントの詳細情報を取得します

API 実行ツール

ツール	説明
execute_api_call	パス、メソッド、パラメーター、データを指定して API 呼び出しを実行します
send_raw_api_request	「METHOD /path [JSON body]」形式で生の API リクエストを送信します

Fast Memory ツール

ツール	説明
save_to_fast_memory	API クエリを Fast Memory に手動で保存します
list_fast_memory	Fast Memory に保存されているすべてのクエリを一覧表示します
delete_from_fast_memory	Fast Memory から特定のクエリを削除します
clear_fast_memory	Fast Memory からすべてのクエリを消去します

使用例

チケット関連のエンドポイントを検索する

search_api_endpoints("tickets")

自然言語で検索する

natural_language_api_search("find all open service tickets that are high priority")

GET リクエストを実行する

execute_api_call(
    "/service/tickets", 
    "GET", 
    {"conditions": "status/name='Open' and priority/name='High'"}
)

新しいサービスチケットを作成する

execute_api_call(
    "/service/tickets", 
    "POST", 
    None,  # No query parameters 
    {
        "summary": "Server is down",
        "board": {"id": 1},
        "company": {"id": 2},
        "status": {"id": 1},
        "priority": {"id": 3}
    }
)

生の API リクエストを送信する

send_raw_api_request("GET /service/tickets?conditions=status/name='Open'")

Fast Memory の内容を表示する

list_fast_memory()

便利なクエリを Fast Memory に保存する

save_to_fast_memory(
    "/service/tickets", 
    "GET", 
    "Get all high priority open tickets", 
    {"conditions": "status/name='Open' and priority/name='High'"}
)

Fast Memory について

Fast Memory 機能を使用すると、よく使う API クエリを保存して取得でき、次のような方法でワークフローを最適化できます：

メリット

• 時間の節約： 正確なエンドポイントやパラメーターを覚えていなくても、複雑な API 呼び出しをすばやく実行できます
• エラーの削減： 成功した API 呼び出しを再利用して、エラーの可能性を最小限に抑えます
• 適応的な学習： システムが、どの API 呼び出しが最も役立つかを学習します
• パラメーターの保持： パラメーターとリクエストボディが今後の利用に備えて保存されます

仕組み

1. 自動学習： API 呼び出しが成功すると、Fast Memory への保存を促すメッセージが表示されます
2. インテリジェントな取得： 同じ API エンドポイントを次に使用するとき、システムはまず Fast Memory を確認します
3. パラメーターの再利用： 呼び出しにパラメーターを指定しない場合、システムは Fast Memory に保存されているパラメーターを自動的に使用します
4. 使用状況の追跡： システムは各クエリの使用頻度を追跡し、頻繁に使用されるクエリを優先します

Fast Memory の機能

• パラメーターの自動提案： パラメーターが指定されていない場合、システムは Fast Memory からパラメーターを提案します
• 使用回数カウンター： Fast Memory のクエリを使用するたびに、使用回数が増加します
• 検索機能： 説明またはエンドポイントのパスで、保存したクエリを検索できます
• 優先順位付け： クエリは使用頻度の高い順に表示され、最もよく使用されるクエリが先頭に表示されます

Fast Memory を管理する

• 保存済みクエリを表示： list_fast_memory()
• 特定のクエリを検索： list_fast_memory("search term")
• クエリを削除： delete_from_fast_memory(query_id)
• すべてのクエリを消去： clear_fast_memory()

Fast Memory の技術詳細

Fast Memory システムは、以下を保存する SQLite データベース（fast_memory_api.db）を基盤としています。

• クエリのパスとメソッド
• パラメーターとリクエストボディ（JSON 形式）
• 使用状況のメトリクスとタイムスタンプ
• ユーザーにわかりやすい説明

データベースの構造は次のとおりです。

• id：保存された各クエリの一意の識別子
• description：クエリの機能についてユーザーが入力した説明
• path：API エンドポイントのパス
• method：HTTP メソッド（GET、POST、PUT など）
• params：JSON 形式のクエリパラメーター
• data：JSON 形式のリクエストボディ
• timestamp：クエリが最後に使用された日時
• usage_count：クエリが使用された回数

トラブルシューティング

よくある問題

データベースが見つからないエラー

Error: Database file not found at [path]
Please run build_database.py script first to generate the database

解決方法： ConnectWise API 定義ファイルのパスを指定して、build_database.py スクリプトを実行します。

python build_database.py path/to/manage.json

API 認証の問題

HTTP error 401: Unauthorized

解決方法： 環境変数を確認し、ConnectWise の認証情報がすべて正しいことを確認します。

• CONNECTWISE_COMPANY_ID、CONNECTWISE_PUBLIC_KEY、CONNECTWISE_PRIVATE_KEY が正しいことを確認します。
• ConnectWise で API キーに必要な権限があることを確認します。
• お使いの環境で CONNECTWISE_AUTH_PREFIX が正しく設定されていることを確認します。

API 呼び出しのタイムアウト

Request timed out. ConnectWise API may be slow to respond.

解決方法：

• インターネット接続を確認します。
• ConnectWise API の負荷が高くなっている可能性があります。
• 大量のデータをリクエストする場合は、クエリにより具体的なフィルターを追加することを検討します。

ログと診断

ログの場所

• メインログファイル：api_gateway/api_gateway.log
• SQLite データベース：
  • API データベース：api_gateway/connectwise_api.db
  • Fast Memory データベース：api_gateway/fast_memory_api.db

データベースのテスト

データベースが正しく構築され、アクセス可能であることを確認します。

python test_database.py

これにより、データベースの統計情報が表示され、正しくクエリを実行できることを確認できます。

高度な使い方

API クエリの最適化

ConnectWise API のパフォーマンスを向上させるには、次の方法を使用します。

1. 条件を具体的に指定する： 正確な条件でクエリの範囲を絞り込みます。

   execute_api_call("/service/tickets", "GET", {
       "conditions": "status/name='Open' AND dateEntered > [2023-01-01T00:00:00Z]"
   })
   

2. 取得するフィールドを制限する： 必要なフィールドだけをリクエストします。

   execute_api_call("/service/tickets", "GET", {
       "conditions": "status/name='Open'",
       "fields": "id,summary,status,priority"
   })
   

3. 大量の結果をページネーションする： page および pageSize パラメーターを使用します。

   execute_api_call("/service/tickets", "GET", {
       "conditions": "status/name='Open'",
       "page": 1,
       "pageSize": 50
   })
   

ライセンス

このソフトウェアは専有かつ機密です。許可されていない複製、配布、使用は禁止されています。

謝辞

• Model Context Protocol (MCP) フレームワークを使用して構築されています。
• ConnectWise Manage API を利用しています。