return-billing-mcp-server

CCAR-F 認定試験の学習対策として作成した、返品・請求問い合わせ振り分けサーバーの MCP (Model Context Protocol) サーバー実装です。ローカル JSON を「注文DB（+請求データ）」に 見立て、lookup_order / check_return_eligibility / process_return / get_billing_status / escalate_to_human の5つのツールを提供します。

会話フロー（ユーザーID確認 → 返品/請求/それ以外への振り分け → オペレーター対応の ターン数制御）そのものは MCP ツールの範囲外（呼び出し側 LLM エージェントの役割）のため、 ORCHESTRATION.md に呼び出し側へ設定するシステムプロンプト例を まとめています。

セットアップ

npm install
npm run build

起動（stdio）

npm start

デモ用のダミー注文データは 2026年8月/7月/6月の1日に登録されている想定のため、 判定結果を本タスク記載の想定どおりに再現するには MCP_TODAY で「今日」を固定してください。

MCP_TODAY=2026-08-11 npm start

MCP_TODAY を指定しない場合は実際のシステム時刻が使われます。

Claude Desktop などからの利用例

{
  "mcpServers": {
    "return-billing": {
      "command": "node",
      "args": ["/absolute/path/to/return-billing-mcp-server/dist/index.js"],
      "env": {
        "MCP_TODAY": "2026-08-11"
      }
    }
  }
}

テスト

@modelcontextprotocol/sdk の Client / StdioClientTransport を使い、実際に サーバープロセスを起動して5ツール全てを検証する統合テストを用意しています。

npm test

Related MCP server: Support Ticket Triage MCP

ディレクトリ構成

data/orders.json      注文DB（ユーザー・製品・注文+請求ステータスのダミーデータ）
src/db.ts              JSON読み込み・検索・返品期限計算などのデータアクセス層
src/errors.ts           構造化エラー（AppError / エラー分類）
src/returnEligibility.ts 返品可否判定ロジック（check_return_eligibility / process_return共通）
src/escalation.ts        エスカレーション・セッションのターン数管理
src/mail.ts               返品通知メール送信のシミュレーション（メモリ上にログ）
src/tools/*.ts            5つのMCPツールの実装
src/server.ts             McpServer 定義・起動
src/index.ts               エントリポイント
tests/integration.test.mjs 統合テスト
ORCHESTRATION.md            呼び出し側エージェント向けシステムプロンプト例

ダミーデータ

ユーザー

lookup_order / get_billing_status はユーザーIDを大文字小文字を無視して完全一致で照合します （似た別アドレスへの誤入力を検出できるよう、あえて紛らわしいアドレスを含めています）。

製品

• コカ・コーラ(500ml) 12本入りパック（¥1,800）

• 爨健美茶(350ml) 24本入りパック（¥2,400）

• 吉野家牛丯お得パック 18個入り（¥5,400）

注文

各ユーザーにつき、2026/8/1・2026/7/1・2026/6/1 の3件の注文を用意し（data/orders.json 生成元: scripts/gen-data.mjs）、製品と請求ステータス（未払い/支払い済み）を組み合わせて バリエーションを持たせています。MCP_TODAY=2026-08-11 で実行した場合:

• 2026/8/1 の注文 → 注文日から1ヶ月以内のため返品可能

• 2026/7/1・2026/6/1 の注文 → 1ヶ月を超過しているため返品不可

ツール仕様

1. lookup_order

ユーザーIDから注文一覧を取得する。問い合わせ対応の最初のステップ（本人確認）として使用。

• 入力: { user_id: string }

• 成功時出力: { user: {user_id, name}, order_count, orders: [{order_id, product_name, quantity, unit_price_jpy, order_date, billing_status, returned}] }

• エラー: USER_NOT_FOUND

2. check_return_eligibility

注文IDを指定し、返品可否（注文日から1ヶ月以内か）を判定する。

• 入力: { order_id: string }

• 出力: { order_id, order_date, deadline_date, days_elapsed, already_returned, eligible, reason: "OK"|"EXPIRED"|"ALREADY_RETURNED", message }

• エラー: ORDER_NOT_FOUND

期限切れ・返品済みは「エラー」ではなく eligible: false の正常応答として返す設計です （下記「エラー応答の分類」を参照）。

3. process_return

返品可能な注文について、返品理由を受け取り返品を確定する。処理後、ユーザーの登録 メールアドレス宛てに返品受付通知メールを送信する（本サンプルでは実送信せず、内容を そのままレスポンスに含めることでシミュレートしています）。

• 入力: { order_id: string, reason: string }

• 成功時出力: { return_id, order_id, reason, processed_at, notification: {to, subject, body, sent_at} }

• エラー: ORDER_NOT_FOUND, RETURN_NOT_ELIGIBLE（details.reason が EXPIRED または ALREADY_RETURNED）

check_return_eligibility を経由せず直接呼ばれた場合に備え、サーバー側でも 返品可否を再検証してから処理します。

4. get_billing_status

ユーザーの全注文について請求ステータス一覧を取得する。未払いの注文には振込先情報が 付与される。

• 入力: { user_id: string }

• 出力: { user: {user_id, name}, unpaid_count, billing: [{order_id, product_name, order_date, amount_jpy, billing_status, payment_instructions}] }

• エラー: USER_NOT_FOUND

payment_instructions（未払いの場合のみ）: テストサイトのため固定のダミー口座を返します。

XX株式会社 〇〇銀行 ××支店 普通 XXXXXXX

5. escalate_to_human

返品・請求のいずれにも該当しない問い合わせを有人オペレーターに引き継ぐ際の、 会話セッションのターン数管理を行う。オペレーターの回答文そのものは生成しない （MCP ツールは LLM を呼び出せないため、呼び出し側エージェントが一般的なオペレーターとして 応答内容を作成する前提）。

• 入力: { session_id: string, user_message: string }

• 出力: { session_id, turn_count, status: "active"|"confirm_close"|"force_closed", guidance, received_message }

• エラー: SESSION_CLOSED（force_closed 後に同じ session_id で再度呼び出した場合）

ターン数のルール:

エラー応答の分類と構造化

すべてのツールは、例外発生時に生の例外を投げるのではなく、isError: true とともに 以下の構造化された JSON を返します（src/errors.ts）。

{
  "error": {
    "code": "USER_NOT_FOUND",
    "category": "NOT_FOUND",
    "message": "ユーザーID「...」に該当する顧客情報が見つかりませんでした。...",
    "details": { "user_id": "..." }
  }
}

設計上の方針: 「返品期限切れ」「返品済み」のようにビジネス上ありうる結果は check_return_eligibility の正常応答（eligible: false + reason）として扱い、 「そもそも処理を実行できない異常系」（対象が存在しない、状態が矛盾している等）のみを 構造化エラーとして分離しています。これにより、呼び出し側エージェントは isError の有無だけで「例外的な失敗」と「業務上の正常な分岐」を区別できます。