PostEx MCP Server

PostEx MCP サーバー

このプロジェクトは、PostEx Merchant API（v4.1.9）のさまざまなエンドポイントとやり取りするためのツールを提供する、Model Context Protocol（MCP）サーバーを実装します。

前提条件

• Node.js（LTS バージョンを推奨）
• npm または yarn
• 有効な PostEx Merchant API トークン

セットアップ

1. リポジトリをクローンする（該当する場合）、または index.js ファイルがあることを確認します。
2. 依存関係をインストールします。

   npm install @modelcontextprotocol/sdk zod node-fetch@2 # Use v2 for require syntax compatibility
   # or
   yarn add @modelcontextprotocol/sdk zod node-fetch@2
   

3. PostEx API トークンを PostEx の加盟店アカウントまたは担当者から取得します。

サーバーの実行

コマンドライン引数として PostEx API トークンを指定し、Node.js を使ってサーバーを実行します。

node index.js <YOUR_POSTEX_API_TOKEN>

<YOUR_POSTEX_API_TOKEN> を実際のトークンに置き換えます。

サーバーは標準入出力経由で接続し、状態メッセージを標準エラーに出力します。これで MCP リクエストを受け付ける準備が整いました。

利用可能なツール

サーバーは、PostEx API のエンドポイントに対応する次のツールを公開します。

• getOperationalCities：PostEx が営業している都市の一覧を取得します。
• getMerchantAddress：加盟店に登録されている集荷先住所を取得します。
• createMerchantAddress：加盟店の新しい集荷先住所を作成します。
• getOrderTypes：対応している注文の種類（例：「Normal」、「Reverse」）を取得します。
• createOrder：PostEx システムで新しい注文を作成します。
• getUnbookedOrders：指定した日付範囲内で作成された、まだ集荷予約されていない注文の一覧を取得します。
• trackOrder：追跡番号を使って単一の注文を追跡します。
• trackBulkOrder：追跡番号の一覧を使って複数の注文を追跡します。（注：API ドキュメントでは GET が指定されていますが、リクエストボディが必要です。実装では最新のコード変更に従って GET を使用していますが、ボディを付けると想定どおりに動作しない可能性があります）。
• saveShipperAdvice：発送済みの荷物について、再試行や返送などの指示を行います。
• getShipperAdvice：追跡番号に関する発送指示の履歴を取得します。
• cancelOrder：追跡番号を使って注文をキャンセルします。（注：JSON ボディを使う PUT として実装されています）。
• getPaymentStatus：注文の支払い精算状況を確認します。
• getOrderStatus：すべての注文ステータスの一覧を取得します。
• listOrders：日付範囲内の注文の一覧を取得します。オプションでステータス ID による絞り込みも可能です。

注： PDF ファイルを返す API エンドポイント（generate-load-sheet、get-invoice）に対応するツールは、このバージョンでは実装されていません。

開発メモ

• サーバーは PostEx API への HTTP リクエストに node-fetch を使用します。
• ツールのパラメーターの入力検証には zod を使用します。
• API トークンはコマンドライン引数として安全に渡され、API 呼び出しの Authorization ヘッダーで使用されます。
• エラー処理は基本的なものです。API 呼び出し中に問題が発生した場合は、コンソール出力を確認してください。
• SIGINT および SIGTERM シグナルに対するグレースフルシャットダウンを処理します。