ConnectWise API ゲートウェイ MCP サーバー

このモデルコンテキストプロトコル（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: 手動インストール

ウィンドウズ

リポジトリをクローンまたはダウンロードします。
git clone https://github.com/jasondsmith72/CWM-API-Gateway-MCP.git cd CWM-API-Gateway-MCP
パッケージをインストールします。
pip install -e .

macOS

NPM インストール方法では、次のコマンドを実行します。

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

手動インストールの場合:

まだインストールされていない場合は、Python 3.10+ をインストールします。
# Using Homebrew brew install python@3.10 # Or using pyenv brew install pyenv pyenv install 3.10.0 pyenv global 3.10.0
リポジトリをクローンします。
git clone https://github.com/jasondsmith72/CWM-API-Gateway-MCP.git cd CWM-API-Gateway-MCP
仮想環境をセットアップします (推奨):
python3 -m venv venv source venv/bin/activate
パッケージをインストールします。
pip install -e .

Linux（Ubuntu/Debian）

NPM インストール方法では、次のコマンドを実行します。

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

手動インストールの場合:

まだインストールされていない場合は、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
リポジトリをクローンします。
git clone https://github.com/jasondsmith72/CWM-API-Gateway-MCP.git cd CWM-API-Gateway-MCP
仮想環境をセットアップします (推奨):
python3.10 -m venv venv source venv/bin/activate
パッケージをインストールします。
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

この手順は 1 回だけ、または 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デスクトップの設定

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リクエストを送信します。

高速メモリツール

道具	説明
`save_to_fast_memory`	APIクエリをFast Memoryに手動で保存する
`list_fast_memory`	高速メモリに保存されたすべてのクエリを一覧表示します
`delete_from_fast_memory`	高速メモリから特定のクエリを削除する
`clear_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'")

高速メモリの内容を表示する

list_fast_memory()

便利なクエリを高速メモリに保存する

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

高速メモリの理解

高速メモリ機能を使用すると、頻繁に使用する API クエリを保存して取得できるため、ワークフローがいくつかの方法で最適化されます。

利点

**時間の節約:**正確なエンドポイントやパラメータを覚えていなくても、複雑な API 呼び出しを素早く実行できます。
**エラー削減:**成功した API 呼び出しを再利用して潜在的なエラーを最小限に抑えます
**適応学習:**システムはどのAPI呼び出しが最も価値があるかを学習します
**パラメータの永続性:**パラメータとリクエストボディは将来の使用のために保存されます

仕組み

自動学習: API呼び出しが成功すると、それを高速メモリに保存するように求められます。
**インテリジェントな検索:**次回同じAPIエンドポイントを使用するときに、システムは最初に高速メモリをチェックします。
**パラメータの再利用:**呼び出し時にパラメータを指定しない場合、システムは自動的に高速メモリに保存されているパラメータを使用します。
**使用状況の追跡:**システムは各クエリの使用頻度を追跡し、頻繁に使用されるクエリを優先します。

高速メモリ機能

自動パラメータ提案: パラメータが指定されていない場合、システムは高速メモリからパラメータを提案します。
**使用カウンタ:**高速メモリからのクエリが使用されるたびに、その使用カウンタが増加します。
**検索機能:**保存したクエリを説明またはエンドポイントパスで検索します
**優先順位:**クエリは使用頻度順に表示されます。最も頻繁に使用されるクエリが一番上に表示されます。

高速メモリの管理

保存されたクエリを表示: list_fast_memory()
特定のクエリを検索: list_fast_memory("search term")
クエリを削除する: delete_from_fast_memory(query_id)
すべてのクエリをクリア: clear_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を確認してください
APIキーにConnectWiseで必要な権限があることを確認する
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
- 高速メモリデータベース: api_gateway/fast_memory_api.db

データベースのテスト

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

python test_database.py

これにより、データベースに関する統計情報が表示され、適切にクエリできることが確認されます。

高度な使用法

APIクエリの最適化

ConnectWise API のパフォーマンスを向上させるには:

**特定の条件を使用する:**正確な条件でクエリを絞り込む
execute_api_call("/service/tickets", "GET", { "conditions": "status/name='Open' AND dateEntered > [2023-01-01T00:00:00Z]" })
**フィールド選択の制限:**必要なフィールドのみをリクエストします
execute_api_call("/service/tickets", "GET", { "conditions": "status/name='Open'", "fields": "id,summary,status,priority" })
大きな結果をページ分割する: page および pageSize パラメータを使用する
execute_api_call("/service/tickets", "GET", { "conditions": "status/name='Open'", "page": 1, "pageSize": 50 })

ライセンス

このソフトウェアは機密情報であり、独占的な権利を有します。無断で複製、配布、または使用することは禁止されています。

謝辞

モデルコンテキストプロトコル（MCP）フレームワークを使用して構築
ConnectWise Manage API を搭載

Integrations