Syncro

Syncro MCP サーバー

効率的なツールナビゲーションを実現する決定木アーキテクチャを実装した、Syncro MSP 向け Model Context Protocol（MCP）サーバーです。

ワンクリックデプロイ

運用担当者向けメモ — GitHub Packages の認証（ワンクリックデプロイに必須）。 このサーバーは、GitHub Packages でホストされているプライベートな @wyre-technology/node-syncro SDK に依存しています。GitHub Packages ではインストールのたびに認証トークンが必要です（公開パッケージであっても、匿名での読み取りはできません）。そのため、トークンを指定しないとクラウドビルダーは npm install 中に 401 Unauthorized で失敗します。read:packages スコープを付与した GitHub Personal Access Token を作成し、ビルダーに設定してください。

• Cloudflare Workers — NODE_AUTH_TOKEN という名前のビルド／環境変数に PAT を設定します。
• DigitalOcean App Platform — GITHUB_TOKEN という名前のビルド時シークレットに PAT を設定します。

ローカルで npm install を実行する場合は、最初に export NODE_AUTH_TOKEN=$(gh auth token) を実行してください。

機能

• 決定木アーキテクチャ：ツールはドメインごとに整理され、遅延読み込みされます
• ドメインナビゲーション：顧客、チケット、アセット、連絡先、請求書間を移動できます
• 遅延読み込み：ドメインハンドラーと Syncro クライアントは必要に応じて読み込まれます
• Syncro API を幅広くカバー：Syncro MSP の主要な機能にアクセスできます
• インタラクティブなチケットカード（MCP Apps）：syncro_tickets_get は、MCP Apps ホスト（Claude Desktop／ウェブ）でインタラクティブなカードとして表示されます。カード内の「コメントを追加」操作は syncro_tickets_add_comment を介して実行できます（デフォルトでは内部向けのみ）。他のホストでのプレーン JSON の動作に変更はありません。カードはデフォルトではニュートラルなデザインで、window.__BRAND__ の注入、または MCP_BRAND_* 環境変数（MCP_BRAND_NAME、MCP_BRAND_LOGO_URL、MCP_BRAND_PRIMARY_COLOR、MCP_BRAND_ACCENT_COLOR、MCP_BRAND_BG、MCP_BRAND_TEXT）でブランド設定できます。再ビルドは不要です。

インストール

WYRE MCP サーバーは OCI／GHCR イメージおよび（利用可能な場合は）MCPB バンドルで配布されています。npm パッケージ @wyre-ai/syncro-mcp も GitHub Packages（npm.pkg.github.com）で公開されています。インストールには read:packages スコープを付与した認証済み .npmrc が必要です（ローカルで export NODE_AUTH_TOKEN=$(gh auth token) を実行してください）。

オプション 1：WYRE MCP Gateway（推奨）

ホスト型ゲートウェイ mcp.wyre.ai を使用してください。ゲートウェイの UI に Syncro API キーを貼り付ければ完了です。

{
  "mcpServers": {
    "syncro": {
      "type": "http",
      "url": "https://mcp.wyre.ai/v1/syncro/mcp",
      "headers": {
        "X-Syncro-Api-Key": "${SYNCRO_API_KEY}"
      }
    }
  }
}

オプション 2：Claude Code CLI（GitHub から実行）

claude mcp add syncro \
  -e SYNCRO_API_KEY=your-api-key \
  -e SYNCRO_SUBDOMAIN=your-subdomain \
  -- npx -y github:WYRE-AI/syncro-mcp

オプション 3：Docker（GHCR）

イメージはコンテナ内の 0.0.0.0 でリッスンし、デフォルトで AUTH_MODE=gateway に設定されています。ポートをループバックで公開し、サービス間通信シークレットを渡してください。ゲートウェイモードでは、Syncro の認証情報はリクエストごとにヘッダーで渡され、環境変数からは読み込まれません。

docker run --rm \
  -e CONDUIT_S2S_SECRET=your-s2s-secret \
  -p 127.0.0.1:8080:8080 \
  ghcr.io/wyre-ai/syncro-mcp:latest

CONDUIT_S2S_SECRET が未設定の場合、Compose は起動を拒否します。また、静的な SYNCRO_* 認証情報を使用せずに AUTH_MODE=gateway で実行し、127.0.0.1:8080:8080 を公開します。

CONDUIT_S2S_SECRET=your-s2s-secret docker compose up

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

docker run --rm \
  -e CONDUIT_S2S_SECRET=your-s2s-secret \
  -e AUTH_MODE=env \
  -e SYNCRO_API_KEY=your-api-key \
  -e SYNCRO_SUBDOMAIN=your-subdomain \
  -p 127.0.0.1:8080:8080 \
  ghcr.io/wyre-ai/syncro-mcp:latest

オプション 4：ソースから実行

git clone https://github.com/WYRE-AI/syncro-mcp.git
cd syncro-mcp
npm ci
npm run build
node dist/index.js

設定

.env.example をコピーし、以下の変数を設定してください。

変数	必須	説明
SYNCRO_API_KEY	stdio および AUTH_MODE=env では必須	Syncro API キー
SYNCRO_SUBDOMAIN	いいえ	Syncro のサブドメイン（該当する場合）
MCP_TRANSPORT	いいえ	stdio（デフォルト）または http
AUTH_MODE	いいえ	gateway（Docker イメージおよび Compose のデフォルト）または env。gateway モードでは各 /mcp リクエストに X-Syncro-API-Key が必要で、SYNCRO_* へのフォールバックは行いません。env では、S2S 認証に成功した後にのみこれらの変数を使用します。
CONDUIT_S2S_SECRET	HTTP では必須	サービス間共有シークレット。HTTP サーバーは、これが空の場合、または既知のプレースホルダー（changeme、your-s2s-secret、replace-with-a-real-secret、secret、未解決の ${...} 値、およびその他のサンプル文字列）の場合、エラーをログに記録してゼロ以外の終了コードで終了します。Compose はこの値がないと起動しません。実際の値をコミットしないでください。openssl rand -hex 32 で生成してください。
MCP_ALLOW_INSECURE_DEV	いいえ	CONDUIT_S2S_SECRET がなくても HTTP を起動する場合に限り、ローカル開発用として値を 1 に設定します。プロセスは警告をログに記録し、X-Gateway-S2S を検証せず、127.0.0.1 のみをバインドします。より広い範囲の MCP_HTTP_HOST（0.0.0.0 を含む）は無視され、その上書きがログに記録されます。既知のプレースホルダーシークレットが設定されている場合は、引き続き起動を拒否します。
MCP_HTTP_HOST	いいえ	MCP_TRANSPORT=http で、CONDUIT_S2S_SECRET が設定されている場合のバインドアドレスです。未設定時のデフォルトは 127.0.0.1 です。コンテナイメージでは 0.0.0.0 が設定されます。
MCP_HTTP_PORT	いいえ	HTTP ポートです。デフォルトは 8080 です。

/health は認証不要のままで、認証情報を読み取りません。stdio トランスポートでは CONDUIT_S2S_SECRET を使用しません。

HTTP 認証

MCP_TRANSPORT=http で CONDUIT_S2S_SECRET が設定されている場合、すべての /mcp リクエストに X-Gateway-S2S を含める必要があります。値は t=<unix seconds>,v1=<hex> の形式です。hex は、CONDUIT_S2S_SECRET をキーとして、リテラル文字列 t=<unix seconds> の HMAC-SHA256 を計算したものです（小文字の 16 進数 64 文字）。タイムスタンプはサーバーの時計との誤差が 300 秒以内でなければなりません。ヘッダーがない場合や無効な場合、ベンダーの認証情報を読み取る前に 401 を返します。シークレットがログに記録されることはありません。

TS=$(date +%s)
SIG=$(printf 't=%s' "$TS" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" -hex | awk '{print $NF}')
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: t=${TS},v1=${SIG}" \
  -H "X-Syncro-API-Key: $SYNCRO_API_KEY" \
  -H "X-Syncro-Subdomain: $SYNCRO_SUBDOMAIN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

AUTH_MODE=gateway では、/mcp に X-Syncro-API-Key も必要です（X-Syncro-Subdomain は任意です）。そのリクエストの認証情報ソースはこれらのヘッダーのみです。API キーのないリクエストには 401 を返し、プロセス環境の SYNCRO_API_KEY にはフォールバックしません。

AUTH_MODE=env でも、/mcp には有効な X-Gateway-S2S ヘッダーが必要です。リクエストに X-Syncro-API-Key が含まれていない場合、ベンダーの認証情報には SYNCRO_API_KEY と SYNCRO_SUBDOMAIN を使用します。

シークレットなしでのローカル HTTP は、開発用途に限られます。127.0.0.1 をバインドし、警告をログに記録します。

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm start

API キーの取得方法

1. Syncro MSP アカウントにログインします
2. Settings > API Tokens に移動します
3. 適切な権限を付与した新しい API トークンを生成します

アーキテクチャ

決定木ナビゲーション

このサーバーは、階層的なアプローチでツールを探索します。

1. 初期状態：ナビゲーションツールとステータスツールのみが公開されます
2. ナビゲーション後：ドメイン固有のツールが利用可能になります
3. 戻るナビゲーション：メインメニューに戻り、ドメインを切り替えます

これにより、認知負荷が軽減され、LLM によるツール選択の精度が向上します。

利用可能なドメイン

ドメイン	説明	ツール
customers	顧客アカウントを管理	list、get、create、search
tickets	サポートチケットを管理	list、get、create、update、add_comment
assets	構成アイテムを管理	list、get、search
contacts	顧客の連絡先を管理	list、get、create
invoices	請求情報を表示・管理	list、get、create、email

ツールリファレンス

ナビゲーションツール

syncro_navigate

ドメインに移動して、そのドメインのツールにアクセスします。

{
  "domain": "customers" | "tickets" | "assets" | "contacts" | "invoices"
}

syncro_back

任意のドメインからメインメニューに戻ります。

syncro_status

現在のナビゲーション状態と認証情報の状態を表示します。

Customers ドメイン

syncro_customers_list

任意のフィルターを指定して顧客の一覧を取得します。

{
  "query": "search term",
  "business_name": "Company Inc",
  "email": "[email protected]",
  "include_disabled": false,
  "page": 1,
  "per_page": 25
}

syncro_customers_get

IDを指定して特定の顧客を取得します。

{
  "customer_id": 123
}

syncro_customers_create

新しい顧客を作成します。

{
  "business_name": "Acme Corp",
  "firstname": "John",
  "lastname": "Doe",
  "email": "[email protected]"
}

syncro_customers_search

クエリ文字列で顧客を検索します。

{
  "query": "acme",
  "limit": 25
}

チケットドメイン

syncro_tickets_list

任意のフィルターを指定してチケットの一覧を取得します。

{
  "customer_id": 123,
  "status": "Open",
  "user_id": 456,
  "resolved": false
}

syncro_tickets_get

IDを指定して特定のチケットを取得します。

{
  "ticket_id": 789
}

syncro_tickets_create

新しいチケットを作成します。

{
  "customer_id": 123,
  "subject": "Network Issue",
  "problem_type": "Network",
  "comment_body": "Initial description"
}

syncro_tickets_update

既存のチケットを更新します。

{
  "ticket_id": 789,
  "status": "Resolved",
  "user_id": 456
}

syncro_tickets_add_comment

チケットにコメントを追加します。

{
  "ticket_id": 789,
  "body": "Comment text",
  "hidden": false
}

資産ドメイン

syncro_assets_list

任意のフィルターを指定して資産の一覧を取得します。

{
  "customer_id": 123,
  "asset_type": "Desktop"
}

syncro_assets_get

IDを指定して特定の資産を取得します。

{
  "asset_id": 456
}

syncro_assets_search

クエリまたはシリアル番号で資産を検索します。

{
  "query": "workstation",
  "asset_serial": "SN12345"
}

連絡先ドメイン

syncro_contacts_list

任意のフィルターを指定して連絡先の一覧を取得します。

{
  "customer_id": 123,
  "query": "john"
}

syncro_contacts_get

IDを指定して特定の連絡先を取得します。

{
  "contact_id": 789
}

syncro_contacts_create

新しい連絡先を作成します。

{
  "customer_id": 123,
  "name": "Jane Smith",
  "email": "[email protected]"
}

請求書ドメイン

syncro_invoices_list

任意のフィルターを指定して請求書の一覧を取得します。

{
  "customer_id": 123,
  "status": "sent",
  "since_date": "2024-01-01"
}

syncro_invoices_get

IDを指定して特定の請求書を取得します。

{
  "invoice_id": 456
}

syncro_invoices_create

新しい請求書を作成します。

{
  "customer_id": 123,
  "due_date": "2024-02-01"
}

syncro_invoices_email

請求書を顧客にメールで送信します。

{
  "invoice_id": 456,
  "subject": "Your Invoice"
}

レート制限

Syncro APIのレート制限は1分あたり180リクエストです。基盤となる@wyre-technology/node-syncroライブラリがレート制限を自動的に処理します。

開発

# Install dependencies. The @wyre-technology/node-syncro SDK lives on GitHub
# Packages, so authenticate first:
export NODE_AUTH_TOKEN=$(gh auth token)
npm install

# Build
npm run build

# Run in development (stdio)
npm run dev

# HTTP refuses to start until CONDUIT_S2S_SECRET is a real secret
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" MCP_TRANSPORT=http npm start

# Local HTTP only, without a service-to-service secret (always binds 127.0.0.1)
MCP_ALLOW_INSECURE_DEV=1 MCP_TRANSPORT=http npm start

# Type check
npm run typecheck

# Lint
npm run lint

ライセンス

Apache-2.0