Kaseya Quote Manager

Kaseya Quote Manager MCP サーバー

AI アシスタントに Kaseya Quote Manager （Datto Commerce）への読み取り専用アクセスを提供する Model Context Protocol（MCP） サーバーです。見積もり、販売注文、購買、製品カタログ、顧客にアクセスできます。

Wyre Technology がメンテナンスしています。

クイックスタート

Claude Desktop — ダウンロードして開くだけです。

1. 最新リリースから kaseya-quote-manager-mcp.mcpb をダウンロードします
2. ファイルを開きます（ダブルクリックするか、Claude Desktop にドラッグします）
3. プロンプトが表示されたら、Kaseya Quote Manager の API Key を入力します

Claude Code（CLI）：

claude mcp add kaseya-quote-manager-mcp \
  -e KASEYA_QUOTE_MANAGER_API_KEY=your-api-key \
  -- npx -y github:WYRE-AI/kaseya-quote-manager-mcp

認証

Quote Manager は、apiKey ヘッダーで送信される単一の API キーを使用して認証します。Quote Manager の Settings → API で生成してください。

stdio と AUTH_MODE=env は KASEYA_QUOTE_MANAGER_API_KEY を読み取ります。HTTP トランスポートは、CONDUIT_S2S_SECRET に実際の値が設定されていない限り起動しません。既知のプレースホルダー（changeme、 change-me、secret、example、placeholder、replace-me、your-secret、 your-s2s-secret、s2s-secret、replace-with-a-real-secret）は、MCP_ALLOW_INSECURE_DEV=1 が設定されている場合も拒否されます。プロセスがシークレットをログに記録することはありません。

HTTP 認証

MCP_TRANSPORT=http を設定し、シークレットを構成すると、すべての /mcp リクエストに X-Gateway-S2S が必要です。

X-Gateway-S2S: t=<unix seconds>,v1=<64 lowercase hex chars>

v1 は、正確な ASCII 文字列 t=<unix seconds>（ヘッダーに含まれる同じプレフィックス）の HMAC-SHA256 で、CONDUIT_S2S_SECRET をキーとして使用し、小文字の 16 進数 64 文字でエンコードされます。タイムスタンプはサーバーのクロックとの差が 300 秒以内である必要があります。ヘッダーがない場合、または無効な場合は、401 が返されます。

AUTH_MODE=gateway（コンテナーイメージと Compose のデフォルト）では、/mcp に X-Kaseya-Quote-Manager-Api-Key も必要です。このヘッダーがそのリクエストで唯一の認証情報です。このヘッダーがないリクエストは 401 を返し、KASEYA_QUOTE_MANAGER_API_KEY にフォールバックしません。

/health は認証不要のままで、X-Gateway-S2S も必要とせず、API キーも返しません。stdio トランスポートは CONDUIT_S2S_SECRET を使用しません。

設定

.env.example をコピーしてください。

変数	必須	説明
KASEYA_QUOTE_MANAGER_API_KEY	stdio および AUTH_MODE=env の場合	Quote Manager の API キーです。ゲートウェイモードでは読み取られません。
MCP_TRANSPORT	いいえ	stdio（デフォルト）または http
AUTH_MODE	いいえ	gateway（Docker イメージと Compose のデフォルト）または env。ゲートウェイモードでは、各 /mcp リクエストに X-Kaseya-Quote-Manager-Api-Key が必要で、環境変数にはフォールバックしません。
CONDUIT_S2S_SECRET	HTTP の場合は必須	サービス間シークレットです。空の場合、または既知のプレースホルダーの場合、HTTP サーバーはエラーをログに記録してゼロ以外の終了コードで終了します。Compose はこの値がないと起動しません。実際の値をコミットしないでください。
MCP_ALLOW_INSECURE_DEV	いいえ	CONDUIT_S2S_SECRET なしで HTTP を起動する場合に限り、ローカル開発用として正確に 1 を設定します。プロセスは警告をログに記録し、X-Gateway-S2S の検証を行わず、127.0.0.1 のみで待ち受けます。ループバック以外の MCP_HTTP_HOST は上書きされ、その旨がログに記録されます。プレースホルダーのシークレットでは起動できません。
MCP_HTTP_HOST	いいえ	シークレットが設定されている場合のバインドアドレスです。デフォルトは 127.0.0.1 です。コンテナーイメージでは 0.0.0.0 に設定されます。安全でない開発用バイパスが有効な場合は無視され、127.0.0.1 が使用されます。
MCP_HTTP_PORT	いいえ	HTTP ポートです。デフォルトは 8080 です。
LOG_LEVEL	いいえ	debug、info、warn、または error。デフォルトは info です。

特徴

• 設計上、読み取り専用です — Quote Manager API が公開するのは list／get のみで、データを変更できるツールはありません。
• 39 個のエンティティツールを 5 つのドメインにわたって提供し、検出ツールとして kqm_navigate／kqm_status も備えています。
• 意思決定ツリー形式のナビゲーション — kqm_navigate を呼び出して、ドメインのツールを確認できます。
• レート制限 — API の 60 リクエスト／分の上限を守り、429／5xx の場合は再試行します。
• 2 種類のトランスポート — stdio（ローカル）と HTTP Streamable（ゲートウェイ／Docker）。
• MCPB パッケージにより、Claude Desktop にワンクリックでインストールできます。

ドメインとツール

ツール名は kqm_<entity>_list および kqm_<entity>_get です。

ドメイン	エンティティ
sales	quote、quote_section、quote_line、sales_order、sales_order_line、sales_order_payment
procurement	purchase_order、purchase_order_line、purchase_order_cost、supplier、product_supplier
catalog	product、product_image（list のみ）、category、brand
crm	customer、customer_address、contact
org	employee、warehouse

list ツールは、対応している場合、page、pageSize（最大 100）、modifiedAfter のほか、エンティティ固有のフィルター（例：quoteNumber、customerID、purchaseOrderID）を受け付けます。

使用例

kqm_navigate { "domain": "sales" }
kqm_quote_list { "page": 1, "pageSize": 50 }
kqm_quote_get { "id": 12345 }
kqm_quote_section_list { "quoteID": 12345 }

Docker

イメージはコンテナ内で 0.0.0.0（MCP_HTTP_HOST）をリッスンし、デフォルトで AUTH_MODE=gateway を使用します。ポートをループバックインターフェースに公開し、S2S シークレットを渡してください。ゲートウェイモードでは、API キーはリクエストごとに X-Kaseya-Quote-Manager-Api-Key として送信されます。環境変数からは読み込まれません。

シークレットを一度生成してエクスポートし、サーバーとリクエストの署名の両方で再利用してください。-e CONDUIT_S2S_SECRET（名前のみ）を指定すると、エクスポート済みの値が docker コマンドラインに表示されることなく渡されます。

export CONDUIT_S2S_SECRET="$(openssl rand -hex 32)"
docker build -t kaseya-quote-manager-mcp .
docker run --rm \
  -e CONDUIT_S2S_SECRET \
  -p 127.0.0.1:8080:8080 \
  kaseya-quote-manager-mcp
# Health: curl localhost:8080/health

CONDUIT_S2S_SECRET が設定されていない場合、Compose は起動を拒否します。AUTH_MODE=gateway を設定し、KASEYA_QUOTE_MANAGER_API_KEY は渡さず、127.0.0.1:8080:8080 を公開します。プロジェクトの .env は値の補間にのみ使用され、ゲートウェイサービスには env_file がありません。

# Reuses the CONDUIT_S2S_SECRET exported above.
docker compose up

シングルテナント HTTP（AUTH_MODE=env）でも S2S シークレットが必要です。その後、KASEYA_QUOTE_MANAGER_API_KEY を使用します。

docker run --rm \
  -e CONDUIT_S2S_SECRET \
  -e AUTH_MODE=env \
  -e KASEYA_QUOTE_MANAGER_API_KEY=your-api-key \
  -e MCP_HTTP_HOST=0.0.0.0 \
  -p 127.0.0.1:8080:8080 \
  kaseya-quote-manager-mcp

シークレットを使用しないローカル HTTP は、開発専用です。常に 127.0.0.1 にバインドし、警告をログに記録します。ループバック以外の MCP_HTTP_HOST は上書きされます。

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm run start:http

ゲートウェイリクエストに署名するには、X-Gateway-S2S と API キーのヘッダーを使用します。まずヘッダーを作成します。v1 は、CONDUIT_S2S_SECRET をキーとして、正確な ASCII 文字列 t=<unix seconds>（末尾に改行なし）を HMAC-SHA256 で処理した 64 文字の小文字の 16 進数です。サーバーの起動時に使用したものと同じエクスポート済みの CONDUIT_S2S_SECRET を使用してください。

openssl dgst -hmac はキーをプロセス引数として受け取るため、実行中は他のローカルユーザーがプロセス一覧からキーを確認できます。この例は、信頼できる単一ユーザーのマシンでのみ実行してください。それ以外の環境では、環境変数からシークレットを読み込むコードでリクエストに署名してください。

: "${CONDUIT_S2S_SECRET:?Set CONDUIT_S2S_SECRET to the server secret}"
: "${KASEYA_QUOTE_MANAGER_API_KEY:?Set KASEYA_QUOTE_MANAGER_API_KEY to the Quote Manager API key}"
timestamp="$(date +%s)"
digest="$(
  printf 't=%s' "$timestamp" |
    openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" |
    awk '{print $NF}' |
    tr '[:upper:]' '[:lower:]'
)"
X_GATEWAY_S2S="t=${timestamp},v1=${digest}"

curl -sS http://127.0.0.1:8080/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -H "x-gateway-s2s: ${X_GATEWAY_S2S}" \
  -H "x-kaseya-quote-manager-api-key: ${KASEYA_QUOTE_MANAGER_API_KEY}" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"kqm_status","arguments":{}}}'

開発

npm install
npm run build
npm test
npm run lint

ライセンス

Apache-2.0 © WYRE Technology