PageFly 返金 MCP サーバー

Crisp の Hugo AI エージェントが PageFly の返金リクエストをエンドツーエンドで処理するための MCP (Model Context Protocol) サーバーです。

3つのレイヤーにグループ化された9つのツールを提供します：

照会 (モックフィクスチャ)

• check_subscription → ストアまたはメールアドレスの現在のプランを取得

• get_billing_history → ストアのすべての請求 / 今後の請求を一覧表示

純粋なロジック

• classify_refund_case → コンテキストを7つのプレイブックケース (TH1–TH7) のいずれかにマッピング

• calculate_refund → 30日間の日割り計算または複数サイクルにわたる返金計算と控除

• collect_refund_info → 次に尋ねるべき質問を決定し、ブロック要因を特定

• generate_refund_message → PageFly テンプレートから顧客への返信をドラフト作成

状態 (Turso / libSQL)

• get_case_state → ストア URL でケースを再開

• save_case_state → 重要なステップごとに進捗を保存

• list_pending_cases → マネージャー、顧客、または支払い待ちのケースを確認

@modelcontextprotocol Typescript SDK を使用して構築されています。

環境設定

.env.example を .env にコピーし、Turso の認証情報を入力してください：

TURSO_DATABASE_URL=libsql://<your-db>.turso.io
TURSO_AUTH_TOKEN=<token>
PORT=3000

マイグレーションはサーバー起動時に自動的に実行されるため、再実行しても安全です。

Related MCP server: Spaceship MCP

I. インストールと実行

この MCP サーバーを使い始めるには、ローカルで実行するか、ホスト版を使用します。

ホスト版の使用

この MCP サーバーはすでにホストされており、すぐにテストしたい場合は Crisp ワークスペースに接続できます。 アクセス先: https://crisp-mcp-demo.fly.dev/mcp

ローカルでの実行

前提条件:

• Node.js 24.x がインストールされていること

• キーボード (オプションですが推奨)

ステップ 1 — リポジトリのクローン

任意のフォルダーでターミナルを開き、以下を実行します：

git clone https://github.com/NTHieu002/refund-crisp-mcp.git
cd refund-crisp-mcp

ステップ 2 — サーバーの実行

サーバーをビルドして起動するか、開発モードで直接実行できます。

サーバーをビルドして実行するには：

npm ci
npm run build
npm run start

または、tsx (ウォッチモード) を使用して開発モードで実行するには：

npm ci
npm run dev

ステップ 3 — サーバーの公開 (ローカル実行時)

ローカルでサーバーを実行する場合、Crisp がアクセスできるようにトンネル経由で公開する必要があります。 このパッケージは Cloudflared を使用するように事前設定されていますが、好みのトンネルソリューションを使用することも可能です。

Cloudflared がマシンにインストールされていない場合は、こちらのリンク から OS に合わせたインストール手順を確認してください：

インストール後、新しいターミナルを開いて以下を実行します：

npm run tunnel

トンネルの URL にアクセスして動作を確認できます。挨拶メッセージが表示されるはずです。

利用可能なスクリプト

• npm run dev → 開発サーバー (ウォッチ)

• npm run build → TypeScript のコンパイル

• npm run start → コンパイル済みサーバーの実行

• npm run tunnel → Cloudflare Tunnel 経由で localhost を公開

• npm run inspect → @modelcontextprotocol Inspector を実行

II. Crisp への接続

このセクションは、この MCP サーバーを Crisp ワークスペースに接続するためのクイックスタートガイドです。 より詳細な手順については、公式ドキュメント も併せてご確認ください。

前提条件:

• Crisp アカウント

• Essentials または Plus プランの Crisp ワークスペース

ステップ 1 — app.crisp.chat に移動

ステップ 2 — AI Agent メニューの AI Agent → Automate → Integrations & MCP → External MCP servers に移動し、Add MCP server ゾーンをクリックします。

ステップ 3 — MCP サーバーの URL (ホスト/トンネル URL または ホスト版) を入力し、Add MCP Server をクリックします。

ステップ 4 — MCP サーバーの設定:

1. 名前を付ける

2. ツールが自動的に取得されない場合は Refresh tools from server をクリック

3. MCP サーバーを有効にする

4. Save changes ボタンをクリック

ステップ 5 — MCP サーバーが登録され、使用可能になります！

III. MCP サーバーのテスト

引き続き Automations メニューの Playground で、MCP サーバーとさまざまな AI モデルをテストできます。質問を投げかけてみてください！

Playground の例

単発の質問:

注文 OID_002 の返金が処理されたか確認できますか？

こんにちは、アカウント baptiste@acme.com で通知は有効になっていますか？

AI は複数のツール呼び出しを連鎖させることができます (例: アカウントの検索、最近の注文のリストアップ、製品詳細の取得):

注文 OID_001 のアイテムはまだ保証期間内ですか？

最新の注文はいつ届きますか？アカウントは chris@acme.com です

部分的な質問も試してみてください。AI が追加情報を要求してきます：

前回の注文金額はいくらでしたか？

追跡番号が見つからないのですが、手伝ってもらえますか？

利用可能なアカウントと注文

• chris@acme.com

  • OID_003

  • OID_006

• baptiste@acme.com

  • OID_001

  • OID_004

• dinis@acme.com

  • OID_002

  • OID_005

  • OID_007

MCP のベストプラクティス

MCP 設計

• サーバーの説明: MCP サーバーの一般的な目的を記述する

• ツールの命名: 明確で明示的な名前を使用する (例: orderLookup ではなく get_order)

• ツールの説明: ツールが何をするか、いつ呼び出すべきかを簡潔に説明し、必要に応じて使用例を提供する

• スキーマ: ツール入力の正確なスキーマを提供し、正しい使用を保証する

ユーザー認証

MCP サーバーの設定で、AI が MCP ツールを呼び出す前にユーザーに認証を要求するように設定できます。これにより、機密性の高い操作に対するセキュリティが強化されます。

ユーザーがまだ認証されていない場合、Crisp は AI が MCP ツールを呼び出す前に、メールまたは SMS で OTP コードを送信します。

これを行うには、MCP サーバーに移動して Manage をクリックします。 各ツールで Require user identification verification オプションを切り替えることができます。

サーバー認証

本番環境では、MCP サーバーへのアクセスを制限し、不正な使用を防ぐことをお勧めします。 2つの認証方法が利用可能です：

• Bearer Token: 各リクエストの Authorization ヘッダーで送信される静的トークン

• Basic Auth: 各リクエストの Authorization ヘッダーで送信されるユーザー名とパスワード