mcp-installation

ProAbono MCP インストール

IDE からサイトに ProAbono をインストールするローカルの MCP サーバーです。

コーディングアシスタントに ProAbono のドキュメント、API Live コントラクト、お客様ご自身の ProAbono 設定を提供するため、In-Site インストールを最初から最後まで一緒に実行したり、実際のビジネス識別子、Segment、オファー、Features が入力済みの統合コードを生成したり、アカウントの情報を読み戻して結果を検証したり、推測ではなく実際のコントラクトに基づいて API に関する質問に回答したりできます。

stdio 経由でローカルに実行され、認証情報でアクセスできるアカウントを対象とします。独自の環境という概念はなく、唯一の境界となるのはお客様の認証情報です。

インストール

Claude Code

claude mcp add --transport stdio proabono --scope user -- npx -y @proabono/mcp-installation

VS Code

.vscode/mcp.json に記述します。

{
  "servers": {
    "proabono": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@proabono/mcp-installation"]
    }
  }
}

Cursor

.cursor/mcp.json（または、すべてのプロジェクトで使用する場合は ~/.cursor/mcp.json）に記述します。

{
  "mcpServers": {
    "proabono": {
      "command": "npx",
      "args": ["-y", "@proabono/mcp-installation"]
    }
  }
}

Node.js 20 以降が必要です。

設定

このサーバーが読み取る環境変数は 7 つだけです。いずれかが設定されていない場合、起動を拒否し、必要な変数名を表示します。

変数	内容
PROABONO_API_BASE	API エンドポイント。https://api-{business_id}.proabono.com
PROABONO_BUSINESS_ID	数値のビジネス識別子
PROABONO_SEGMENT_REF	お客様とオファーが属する Segment
PROABONO_AGENT_KEY	Basic 認証のユーザー名
PROABONO_API_KEY	Basic 認証のパスワード
PROABONO_PORTAL_SECRET	ポータルのセキュリティハッシュ用 HMAC キー
PROABONO_WEBHOOK_SECRET	通知署名用のシークレット

7 つすべてが ProAbono BackOffice の 1 つのページ（Integration → MCP）にあります。PROABONO_API_BASE は https:// で始まる必要があり、PROABONO_BUSINESS_ID には数字のみを指定してください。

MCP クライアントの設定項目にある env ブロックへ記述し、Git の無視対象ファイルに保存してください。 これにより、7 つの値の組み合わせをそれぞれ 1 つのプロジェクトと 1 つの ProAbono アカウントに紐づけられます。サンドボックスと本番環境はエンドポイント、識別子、キーが異なる別々のアカウントなので、2 組の値が必要になったときに便利です。たとえば proabono-sandbox と proabono-production のように、アカウントごとに独自の env を持つ設定項目を作成します。

• .vscode/mcp.json と .cursor/mcp.json はリポジトリ内にあるため、値を貼り付ける前に .gitignore に追加してください。Cursor は、すべてのリポジトリの外にある ~/.cursor/mcp.json も読み取ります。
• Claude Code：--scope user を指定すると、設定項目をリポジトリの外に置けます。プロジェクトの .mcp.json は通常コミットされるため、値の代わりに ${PROABONO_API_KEY} とほかの 6 つの変数を記述してください。Claude Code は環境変数から値を展開します。
• VS Code では、mcp.json の inputs セクションから値の入力を求めることもでき、値をファイルに保存せずに済みます。
• シェルでのエクスポートは避けてください。シェルごと、マシンごとに 1 組の値しか保持できず、本番環境のキーが、開くすべてのプロジェクトで使える状態になります。
• サーバーは .env ファイルを読み取りません。読み取るのはプロセス環境だけです。

指定した値がログに記録されたり、ツールから返されたり、エラーメッセージに含まれたり、生成コードに直接埋め込まれたりすることはありません。生成コードでは変数名を参照します。

最初のプロンプト

サーバーを追加し、7つの変数を設定したら、プロジェクトを開いて、次の内容をアシスタントに貼り付けます。

Help me install ProAbono in this project.

1. Call get_server_info to confirm the server is reachable, and tell me which version you are talking to.
2. Call installation_status to see whether an installation was already started here.
3. Run install_insite: tell me which stack you detected and why, check the prerequisites with me, then take me through the three In-Site steps and the notification endpoint in order, placing the generated code where my signed-in user is known.
4. List what I still have to do by hand in the ProAbono BackOffice.
5. When the code is in place, run verify_insite_installation and walk me through the go-live checklist.

Answer every question about the ProAbono API from search_documentation and get_api_reference, never from memory.

正常に動作すると、手順1ではサーバーのバージョンと、ステータスが complete の設定が返されます。設定には7つの変数名が表示されますが、値は表示されません。ProAbono ツールがまったく表示されない場合は、サーバーの起動が拒否されています。変数が不足しており、それを示すエラーは MCP クライアントのログにあります。サーバーは不完全な設定では起動しないため、get_server_info が不完全な設定を報告することはありません。

ジェネレーターはコードを返すだけで、ファイルは編集しません。コードはアシスタントが配置します。サーバーが書き込む唯一のファイルは、インストール状態を記録する .proabono/installation.json です。認証情報は含まれず、後のセッションでこの作業の続きから再開できるよう、コミットすることを想定しています。また、record_state: false を指定してツールを呼び出した場合は書き込まれません。

実行には、キーを Sandbox アカウントに設定してください。verify_insite_installation は、検証対象の顧客が存在することを確認します。顧客を指定しない場合は、mcp-verify- を参照名とする顧客を作成します。通常はその後に実行するツール、つまり create_update_customer、create_subscription、Usage の書き込み、bill_customer は、認証情報でアクセスするアカウントに実際のデータを作成します。

プロンプトの例

インストールを進める中で、開発者が次に尋ねるのは次のような内容です。どのツールを使うかはアシスタントが判断します。2列目には、通常使用するツールが記載されています。

質問	通常使用するツール
「自分の Segment にはどの Offer が公開されていて、それぞれにどの Feature が含まれていますか？」	list_offers、list_features
「このページ用に、実際の Offer を使った料金表を生成してください。ログイン済みの顧客がその場でサブスクリプションに登録できるよう、顧客を識別できる形にしてください。」	generate_pricing_table
「このプロジェクトで、別の人が ProAbono のインストールを開始しました。現在どの段階で、BackOffice には何が残っていますか？」	installation_status
「通知エンドポイントをこのアプリに組み込み、BackOffice で有効にする方法も教えてください。」	scaffold_notification_endpoint
「アップグレード、ダウングレード、督促を含めたポータルのライフサイクルを計画してください。」	plan_integration
「顧客を作成し、最初の Offer に登録して、Usages を表示してください。」	create_update_customer、create_subscription、get_usages
「この顧客のシート数を5から10に増やすといくらかかりますか？また、その変更は許可されていますか？」	quote_usage_change
「顧客の請求書一覧を取得するエンドポイントはどれで、何が返されますか？Go で呼び出しを書いてください。」	search_documentation、get_api_reference、generate_integration_code

現在対応している内容

インストールしたバージョンはCHANGELOG.mdに記載されており、get_server_infoで確認できます。

• In-Siteの3つのステップを最初から最後までサポートします。セキュリティハッシュを使ったCustomer Portalの埋め込み、Subscription Workflowの往復処理、キャッシュ、ゲート、再同期を含むUsageの同期です。
• 通知エンドポイントをサポートします。署名の検証、重複排除、および有効化のためのBackOffice手順が含まれます。
• 検証をサポートします。ステップ2と3をお客様のアカウントに対して実行し、独自のファイルを対象に本番稼働ルールを確認し、12項目のチェックリストを提示します。
• カタログとアカウントの調査に対応します。オファー、Features、顧客、サブスクリプション、Usages、請求書が対象です。
• ライフサイクル全体での書き込みに対応します。顧客とその設定、請求先住所、サブスクリプションと4つの各状態遷移、3種類すべてのFeatureに対するUsageの書き込み、残高明細、請求が対象です。
• ドキュメントとAPIリファレンスに対応します。ProAbonoのコーパスとAPI Liveコントラクトを自然言語で検索できます。

対応しておらず、今後の実装を予定しているもの：高度なIn-Siteオプション（ホストされたページのCSSカスタマイズなど）と、さらに個別のワークフローです。

ウィジェットやプラグインによるインストール（WordPressなど）は、意図的に対象外としています。このサーバーは、どのようなスタックにも対応できるコードによるIn-Siteをインストールします。

オファー、Features、ウェブフック、価格ページ、ワークフローのリダイレクトURLはProAbono BackOfficeで設定します。APIからこれらを作成することはできません。サーバーは設定内容を読み取り、不足しているものを示し、BackOfficeでの設定手順を案内します。

ツール

*「書き込み」*は、お使いの認証情報でアクセスできるアカウントのデータを変更するツールを示します。アシスタントが呼び出すと、確認なしで即座に実行されます。境界となるのは、お使いの認証情報のみです。

ドキュメント

ツール	機能	書き込み
search_documentation	ProAbonoのドキュメントとAPI Liveコントラクトを自然言語で検索します。
get_api_reference	指定したエンドポイントまたはオブジェクトのパラメーターとスキーマを表示します。

インストール

ツール	機能	書き込み
install_insite	In-Siteのインストール全体を最初から最後まで実行します。スタックの検出、前提条件のゲート、3つのステップの順次実行、および進捗の.proabono/installation.jsonへの記録が含まれます。
installation_status	インストールの状況を表示します。完了した作業、生成されたファイルとその保存先、BackOfficeで保留中の作業、スキップされた項目を確認できます。
install_customer_portal	お使いのスタック向けに、セキュリティハッシュ付きのステップ1のIn-Site埋め込みを行います。
link_subscription_workflow	ステップ2を実行します。Linksから暗号化されたクエリを読み取り、ワークフローを開く2つの方法と、5つすべての結果に対応する単一の戻り先ルートを設定します。
sync_usage_rights	ステップ3の権限モジュールを設定します。Usageの読み取り、キャッシュと有効期限、ゲート、アプリケーションが変更するFeatureの書き戻し、再同期が含まれます。
scaffold_notification_endpoint	ウェブフックエンドポイントを設定します。署名の検証、検証ハンドシェイク、重複排除、迅速な応答、および有効化のためのBackOffice手順が含まれます。
verify_insite_installation	お客様のアカウントに対してステップ2と3を実行します。指定した顧客（見つからない場合は作成）または新しい顧客を対象にし、ファイルを確認して本番稼働ルールを検証し、12項目のチェックリストを提示します。	はい

コード生成

ツール	機能	書き込み
generate_pricing_table	実際のオファーに基づいて価格表を生成します。
plan_integration	インストール、サブスクリプションのファネル、ポータルのライフサイクル、Usageの計測、通知を含む、一連の処理の順序立てた計画を作成します。
generate_integration_code	コントラクトとドキュメントに基づき、指定した言語でタスクのコードを生成します。

カタログ

ツール	機能	書き込み
list_offers	Segment が公開しているオファーを一覧表示します。
list_offers_for_customer	ある顧客が利用できるオファーと、実行中のサブスクリプションのアップグレードオプションを一覧表示します。
get_offer	参照情報を指定して、単一のオファーを取得します。
list_features	ビジネスの機能を一覧表示します。

顧客

ツール	機能	書き込み
get_customer	参照情報を指定して顧客を取得します。
create_update_customer	顧客を作成するか、参照情報がすでに登録されている顧客を更新します。エンドポイントはアップサートのため、ツールは1つです。	はい
get_billing_address	請求書の発行先住所を取得します。
update_billing_address	指定したフィールドのみを変更して、その住所を更新します。	はい
get_payment_settings	支払い方法、請求モード、グレーリストフラグ、請求書の備考、次回請求日をまとめて読み取ります。
set_next_billing_date	顧客の次回請求日を設定します。	はい
set_invoice_note	顧客の今後のすべての請求書の下部に印字される備考を設定します。	はい
set_payment_method	手動の支払い方法を記録します。Card と DirectDebit は決済ゲートウェイによって制御されます。	はい
anonymize_customer	取り消せません。 GDPR の消去手続きです。個人データを消去し、請求書とサブスクリプションの履歴は保持します。顧客に未払いの請求書がある場合、ProAbono はこの処理を拒否し、何も消去しません。	はい

サブスクリプション

ツール	機能	書き込み
get_subscription, list_subscriptions	顧客が登録しているサブスクリプションを取得します。
create_subscription	顧客をオファーに登録します。	はい
start_subscription	下書き状態のサブスクリプションを開始するか、一時停止中のサブスクリプションを再開します。	はい
upgrade_subscription	サブスクリプションを別のオファーに変更します。	はい
suspend_subscription	サブスクリプションを一時停止します。start_subscription で再開できます。	はい
terminate_subscription	サブスクリプションを終了します。デフォルトでは契約期間の終了時に終了します。	はい

使用量と権利

ツール	機能	書き込み
get_usages	ProAbono が認識している顧客の現在の使用量を取得します。
quote_usage_change	変更を適用する前に、予定されている変更の料金を算出し、許可されているか確認します。
push_usage_increment	Consumption 機能の消費量を報告します。	はい
push_usage_quantity	Limitation 機能のプロビジョニング済み数量を設定します。	はい
push_usage_enabling	OnOff 機能を切り替えます。	はい

請求書と残高

ツール	機能	書き込み
get_invoice	借方請求書を取得します。公開されている場合は PDF の URL も含まれます。発行直後に請求書を読み取ると、まだ PDF が公開されていないことがあります。
get_credit_note	クレジットノートを取得します。TypeCredit、理由、公開されている場合は PDF の URL も含まれます。
list_invoices	顧客の請求書類を、両方の種類まとめて一覧表示します。
create_balance_line	借方項目を作成します。金額が負の場合は貸方項目になります。	はい
bill_customer	残高にあるすべての項目を請求書にします。	はい

サーバー

ツール	機能	書き込み
get_server_info	バージョンと設定状況を取得します。設定値は含まれません。

このサーバーのツールで請求履歴が破棄されることはありません。どのアカウントでも、顧客、サブスクリプション、請求書の削除は対象外です。また、ProAbono の顧客一時停止、無効化、リンク取り消しの各エンドポイントは存在しますが、意図的に公開していません。anonymize_customer は効果を元に戻せない唯一のツールですが、破棄ではありません。個人データを消去し、請求書とサブスクリプションの履歴を保持します。これは、請求システムに GDPR に基づく消去を求める際に必要な処理です。

トラブルシューティング

症状	原因	解決方法
アシスタントに ProAbono ツールが表示されず、MCP クライアントのログに設定変数が不足していると表示される	変数が不足しているか空のため、サーバーの起動が拒否されました	メッセージに記載された各変数をエントリーの env ブロックに設定し、クライアントを再起動してください
ログに PROABONO_API_BASE must be an https:// endpoint と表示される	エンドポイントが https:// で始まっていません	ご自身の事業者 ID を使って、https://api-{business_id}.proabono.com を指定してください
ログに PROABONO_BUSINESS_ID must be the numeric business identifier と表示される	ID に数字以外が含まれています	数字だけにしてください。接頭辞、引用符、空白は含めないでください
ツールが ProAbono API error 401 と応答する	Agent キーまたは API キーが正しくありません	BackOffice から両方をコピーし直してください
ツールが ProAbono API error 401 と応答し、両方のキーは正しい	エンドポイントとキーの取得元が異なるアカウントです	7 つすべての変数を同じアカウントから取得してください

ソースからビルドする

公開済みパッケージは自己完結型です。ProAbono API の仕様とドキュメントはビルド時に dist/resources/ にコピーされるため、実行時に何かを取得することはありません。

クローンも、認証情報やこちらのリソースへのアクセスなしで、同じ方法でビルドできます。

npm ci && npm run build && npm test

ビルドに組み込まれる両方のソースは、このリポジトリの resources/ にあります。API Live の仕様は resources/open-api/ に、ドキュメントコーパスは resources/docs/ にあります。仕様は ProAbono が内部で管理しているもののコピーです。npm run build と npm test は、ソースにアクセスできる場合はそこから更新し、アクセスできない場合（CI やこのリポジトリのクローンなど）はコミット済みのコピーを使用します。また、実行のたびにどちらを使用したかを表示します。resources/open-api/index.md を参照してください。

サポート

問題や質問はこちらまで：[email protected]。

問題を報告する際は、get_server_info の出力を含めてください。サーバーのバージョンと設定済みの変数を報告しますが、それらの値は決して表示しません。

このサーバー以外の情報：

• ProAbono ドキュメント
• API リファレンス
• ProAbono アカウントを作成

ライセンス

MIT。LICENSE を参照してください。