easypaydirect-mcp

easypaydirect-mcp

📖 ドキュメント： https://praveendias1180.github.io/easypaydirect-mcp/

Easy Pay Direct（EPD）／NMI 系の決済ゲートウェイ向けの、非公式かつ読み取り専用のModel Context Protocolサーバーです。

AI アシスタント（Claude Desktop、Claude Code、または任意の MCP クライアント）に、ゲートウェイの取引、サブスクリプション、定期プラン、Customer Vault の記録への安全な読み取り専用アクセスを提供します。これにより、「先週、この顧客の失敗した取引を見つけて」や「このサブスクリプションはまだ有効ですか？」といった質問を自然な言葉で尋ねられます。

Easy Pay Direct はNMI／Network Merchantsゲートウェイプラットフォーム上に構築されているため、このサーバーはあらゆる NMI ホワイトラベルゲートウェイで動作します。ゲートウェイのホストを指定するだけです。EPD は代表的な例であり、対応範囲の限界ではありません。

⚠️ Easy Pay Direct または NMI とは提携関係になく、承認や後援も受けていません。「Easy Pay Direct」、「EPD」、「NMI」は、それぞれの所有者の商標です。これは、公開されているQuery APIを利用する独立したオープンソースクライアントです。

---

読み取り専用である理由

このサーバーが通信するのは、ゲートウェイのQuery API（/api/query.php）、つまりレポート用エンドポイントのみです。取引エンドポイント（transact.php）へ到達するコードパスがないため、カードへの請求、返金、取引の取り消し、Vault の変更はできません。このサーバーに接続された LLM は情報を参照できますが、資金に手を触れることはできません。詳しくはdocs/security.mdをご覧ください。

書き込み操作は今後のメジャーバージョンで追加される可能性があります。常に明示的なオプトイン方式で、デフォルトでは無効にし、厳格な制限を設けます。

---

インストールと実行

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

# no install needed — run straight from npm
npx easypaydirect-mcp

このサーバーはstdioで MCP と通信し、2 つの環境変数を必要とします。

変数	必須	説明
NMI_SECURITY_KEY	✅	ゲートウェイ API のセキュリティキー（読み取り専用キーを推奨します）。加盟店ポータル → Settings → Security Keys。
NMI_API_URL	—	ゲートウェイ API のベース URL。デフォルトは https://secure.nmi.com です。EPD／ホワイトラベルの場合は、ゲートウェイのホストを設定してください。

キーとホストの確認方法については、docs/configuration.mdをご覧ください。

Docker で実行する

ローカルに Node.js をインストールする必要はありません。リポジトリのルートでイメージをビルドし、-i を指定して実行します。MCP は stdio で通信するため、コンテナの標準入力を開いたままにする必要があります。

docker build -t easypaydirect-mcp .

docker run --rm -i \
  -e NMI_SECURITY_KEY=your_read_only_security_key \
  -e NMI_API_URL=https://secure.nmi.com \
  easypaydirect-mcp

または、環境変数を env ファイル（--env-file .env）に保存します。.env はすでに git の追跡対象外です。実際のキーをコミットしないでください。

Claude に接続する

Claude Desktop — claude_desktop_config.json に追加します（examples/claude-desktop-config.jsonを参照）。

{
  "mcpServers": {
    "easypaydirect": {
      "command": "npx",
      "args": ["-y", "easypaydirect-mcp"],
      "env": {
        "NMI_SECURITY_KEY": "your_read_only_security_key",
        "NMI_API_URL": "https://secure.nmi.com"
      }
    }
  }
}

Claude Code：

claude mcp add easypaydirect \
  -e NMI_SECURITY_KEY=your_read_only_security_key \
  -e NMI_API_URL=https://secure.nmi.com \
  -- npx -y easypaydirect-mcp

代わりに Docker イメージを使うには、コマンドを入れ替えます。-e NAME のみを指定すると、その変数がコンテナに引き継がれます。

claude mcp add easypaydirect \
  -e NMI_SECURITY_KEY=your_read_only_security_key \
  -e NMI_API_URL=https://secure.nmi.com \
  -- docker run --rm -i -e NMI_SECURITY_KEY -e NMI_API_URL easypaydirect-mcp

手順の全容については、docs/getting-started.mdをご覧ください。

Claude Code プラグイン（サーバー + スキル）

このプラグインは、MCP サーバーと、ゲートウェイデータを正しく読み取る方法を Claude に教える Agent Skill をインストールします。たとえば、ACH の売上が成功しても、支払い済みではなく 送信済み にすぎないことや、EPD のタイムスタンプが UTC であることを学習します。

シェルでキーを設定します（プラグインは環境変数から読み取ります）。次にインストールします。

export NMI_SECURITY_KEY=your_read_only_security_key
export NMI_API_URL=https://secure.nmi.com   # optional; your EPD / white-label host

/plugin marketplace add praveendias1180/easypaydirect-mcp
/plugin install easypaydirect@easypaydirect-mcp

別のクライアントをお使いですか？スキルは通常の SKILL.md ファイルです。Agent Skills に対応しているツールなら、どれにでも追加できます。

ツール

すべてのツールは読み取り専用です。詳細なリファレンスは docs/tools.md をご覧ください。

ツール	機能
get_transaction	ゲートウェイのトランザクション ID を指定して、1 件のトランザクションを取得します。
search_transactions	日付範囲とフィルター（状態、アクションタイプ、支払いタイプ、ソース、メールアドレス、注文 ID）でトランザクションを検索します。
get_subscription	ID を指定して、1 件の定期購入を取得します。
list_subscriptions	定期購入の一覧を取得します。作成日または更新日の範囲で絞り込むこともできます。
list_recurring_plans	定期請求プランの一覧を取得します（または plan_id を指定して 1 件取得します）。
get_customer_vault_record	ID を指定して、保存済みの Customer Vault レコードを 1 件取得します。
list_customer_vault	保存済みの Customer Vault レコードの一覧を取得します。日付範囲で絞り込むこともできます。

開発

git clone https://github.com/praveendias1180/easypaydirect-mcp.git
cd easypaydirect-mcp
npm install
npm run build      # compile TypeScript to dist/
npm run typecheck  # type-check only

MCP Inspector を使ったローカル実行：

npx @modelcontextprotocol/inspector node dist/index.js

アーキテクチャと、各ツールが Query API にどう対応するかについては、docs/nmi-api-mapping.md をご覧ください。

ロードマップ

計画中または検討中の項目です。コントリビューションを歓迎します（未解決の Issue をご覧ください）。

• テスト — 記録済みの Query API フィクスチャを使ったユニットテストスイート（#1）
• 日付入力の改善 — 日付フィルターで ISO-8601 を受け付ける（#2）
• フィルターの拡充 — search_transactions に加盟店定義フィールドを追加する（#3）
• エラーの改善 — NMI の応答コードを、対処方法が分かるメッセージに変換する（#4）
• 配布 — リリース時の公開を自動化する（#8）
• ドキュメント — 応答フィールドのリファレンス（#9）

読み取り専用をデフォルトの方針とします。書き込み機能を追加する場合は、別途オプトイン方式の、ゲート付きのメジャーバージョンとして提供します。

リリース済みの変更については、変更履歴をご覧ください。

コントリビューション

コントリビューションを歓迎します。このプロジェクトは、小規模で信頼性の高い読み取り専用 MCP サーバーを目指しています。基本ルールと開発環境のセットアップについては、CONTRIBUTING.md をご覧ください。

初めての方へ： good first issue から始めてみてください。各 Issue には背景情報、タスクのチェックリスト、関連ファイルへのリンク、受け入れ基準が記載されています。質問がある場合は、ディスカッションを開いてください。

ライセンス

MIT © easypaydirect-mcp コントリビューター