Omise MCP Alpha

🚀 Omise MCP Server

Omise MCP Server は、モデルコンテキストプロトコル (MCP) を使用してOmise支払いAPIと統合するための包括的なサーバーです。TypeScriptで実装され、Omise API v2017 - 11 - 02を完全にサポートしています。

✨ 主な機能

💳 支払い処理

• 請求管理：支払いの作成、取得、更新、キャプチャ、および返金
• トークン化：カード情報の安全なトークン化
• ソース管理：さまざまな支払い方法のサポート
• 返金：部分返金と全額返金の処理

👥 顧客管理

• 顧客情報：顧客の作成、取得、更新、および削除
• カード管理：顧客のカード情報の管理
• メタデータ：カスタム情報の保存

🔄 振込と受取人

• 振込処理：受取人に送金
• 受取人管理：受取人の作成、検証、および管理
• 銀行口座：銀行口座情報の管理

📅 スケジュールと定期支払い

• 定期支払い：スケジュールに基づく自動支払い
• 発生管理：スケジュールの実行を管理
• 柔軟な設定：日次、週次、および月次のスケジュール

🔍 監視と分析

• イベント管理：システムイベントの追跡
• 紛争管理：請求取消の処理
• Webhook：リアルタイム通知

🔗 リンクとチェーン

• 支払いリンク：共有可能な支払いリンク
• チェーン管理：マルチテナントサポート
• 機能チェック：API機能の検証

📋 サポートされるAPI

合計: 51個のツール で、Omise APIのすべての機能を網羅しています。

🛠️ 技術スタック

🚀 クイックスタート

前提条件

• Node.js 20+
• npmまたはyarn
• Omiseアカウント とAPIキー

1. インストール

# リポジトリをクローン
git clone https://github.com/your-org/omise-mcp-server.git
cd omise-mcp-server

# 依存関係をインストール
npm install

2. 環境設定

# 環境構成ファイルをコピー
cp config/development.env .env

# 環境変数を設定
export OMISE_PUBLIC_KEY=pkey_test_xxxxxxxxxxxxxxxx
export OMISE_SECRET_KEY=skey_test_xxxxxxxxxxxxxxxx
export OMISE_ENVIRONMENT=test

3. 開発サーバーを起動

# 開発モードで起動
npm run dev

# または本番モードで起動
npm run build
npm start

4. インストールを確認

# ヘルスチェック
curl http://localhost:3000/health

# 利用可能なツールを確認
curl http://localhost:3000/tools

💻 使用例

基本的な支払い処理

// 請求を作成
const charge = await mcpClient.callTool('create_charge', {
  amount: 10000,        // 100.00 THB (最小通貨単位)
  currency: 'THB',
  description: 'Test payment',
  capture: true
});

// 顧客を作成
const customer = await mcpClient.callTool('create_customer', {
  email: 'customer@example.com',
  description: 'Test customer'
});

// カードトークンを作成
const token = await mcpClient.callTool('create_token', {
  card: {
    name: 'John Doe',
    number: '4242424242424242',
    expiration_month: 12,
    expiration_year: 2025,
    security_code: '123'
  }
});

定期支払いの設定

// スケジュールを作成
const schedule = await mcpClient.callTool('create_schedule', {
  every: 1,
  period: 'month',
  start_date: '2024-01-01',
  charge: {
    customer: 'cust_123',
    amount: 5000,
    currency: 'THB',
    description: 'Monthly subscription'
  }
});

振込処理

// 受取人を作成
const recipient = await mcpClient.callTool('create_recipient', {
  name: 'John Doe',
  email: 'john@example.com',
  type: 'individual',
  bank_account: {
    brand: 'bbl',
    number: '1234567890',
    name: 'John Doe'
  }
});

// 振込を実行
const transfer = await mcpClient.callTool('create_transfer', {
  amount: 10000,
  recipient: recipient.id
});

🔧 設定

環境変数

Omise APIキーの取得

1. Omiseダッシュボード にアクセス
2. アカウントを作成するか、ログインする
3. APIキー セクションからキーを取得
4. テスト環境：pkey_test_ と skey_test_ で始まるキーを使用
5. 本番環境：pkey_live_ と skey_live_ で始まるキーを使用

⚠️ 重要提示

常に本番環境では本番用のキーを、テスト環境ではテスト用のキーを使用してください。

🏗️ プロジェクト構造

omise-mcp-server/
├── src/                          # ソースコード
│   ├── index.ts                  # メインサーバーファイル
│   ├── types/                    # 型定義
│   │   ├── omise.ts             # Omise APIの型定義
│   │   ├── mcp.ts               # MCPの型定義
│   │   └── index.ts             # 型定義のエクスポート
│   ├── tools/                    # ツールの実装
│   │   ├── payment-tools.ts     # 支払い関連のツール
│   │   ├── customer-tools.ts    # 顧客関連のツール
│   │   ├── token-tools.ts       # トークン関連のツール
│   │   ├── source-tools.ts      # ソース関連のツール
│   │   ├── transfer-tools.ts    # 振込関連のツール
│   │   ├── recipient-tools.ts  # 受取人関連のツール
│   │   ├── refund-tools.ts      # 返金関連のツール
│   │   ├── dispute-tools.ts     # 紛争関連のツール
│   │   ├── schedule-tools.ts    # スケジュール関連のツール
│   │   ├── event-tools.ts       # イベント関連のツール
│   │   ├── webhook-tools.ts     # Webhook関連のツール
│   │   ├── link-tools.ts        # リンク関連のツール
│   │   ├── chain-tools.ts       # チェーン関連のツール
│   │   ├── capability-tools.ts  # 機能検証ツール
│   │   └── index.ts             # ツールのエクスポート
│   └── utils/                    # ユーティリティ
│       ├── config.ts            # 構成管理
│       ├── logger.ts            # ロギング機能
│       ├── omise-client.ts      # Omise APIクライアント
│       ├── health-check.ts      # ヘルスチェック
│       └── index.ts             # ユーティリティのエクスポート
├── tests/                        # テスト
│   ├── unit/                     # 単体テスト
│   ├── integration/              # 統合テスト
│   ├── auth/                     # 認証テスト
│   ├── error/                    # エラー処理テスト
│   ├── rate-limit/               # レート制限テスト
│   ├── mocks/                    # モック
│   └── factories/                # テストファクトリ
├── config/                       # 構成ファイル
│   ├── development.env          # 開発環境
│   ├── staging.env              # ステージング環境
│   └── production.env            # 本番環境
├── monitoring/                   # 監視構成
│   ├── prometheus.yml            # Prometheus構成
│   ├── loki-config.yml          # Loki構成
│   └── grafana/                  # Grafana構成
├── nginx/                        # Nginx構成
├── docker-compose.yml            # Docker Compose構成
├── Dockerfile                    # Docker構成
├── package.json                  # 依存関係
├── tsconfig.json                 # TypeScript構成
└── README.md                     # このファイル

🧪 開発

開発環境のセットアップ

# 開発用の依存関係をインストール
npm install

# 開発サーバーを起動
npm run dev

# ウォッチモード
npm run watch

テスト

# すべてのテストを実行
npm test

# ウォッチモード
npm run test:watch

# カバレッジレポート
npm run test:coverage

# 特定のテストカテゴリ
npm run test:unit
npm run test:integration
npm run test:auth
npm run test:error
npm run test:rate-limit

リント

# リントを実行
npm run lint

# 自動修正
npm run lint:fix

ビルド

# TypeScriptをコンパイル
npm run build

# 本番用ビルド
npm run build:production

🐳 Dockerデプロイメント

開発環境

# 開発環境を起動
docker-compose --env-file config/development.env up -d

# ログを確認
docker-compose logs -f omise-mcp-server

本番環境

# 本番環境を起動
docker-compose --env-file config/production.env up -d

# ヘルスチェック
curl http://localhost:3000/health
curl http://localhost:3000/ready
curl http://localhost:3000/live

自動デプロイメント

# デプロイメントスクリプトを実行
./deploy.sh latest production

📊 監視とログ

Prometheusメトリクス

• URL：http://localhost:9090
• メトリクス：CPU、メモリ、リクエスト数、レスポンス時間
• アラート：高負荷、エラー率の監視

Grafanaダッシュボード

• URL：http://localhost:3001
• ログイン：admin / admin (デフォルト)
• ダッシュボード：システム監視、アプリケーション監視

ログ管理

# アプリケーションログ
docker-compose logs -f omise-mcp-server

# Nginxログ
docker-compose logs -f nginx

# すべてのサービスのログ
docker-compose logs -f

🔒 セキュリティ

セキュリティ機能

• 非ルートユーザー：コンテナを非ルートユーザーとして実行
• セキュリティヘッダー：適切なHTTPヘッダー構成
• レート制限：API呼び出しの制限
• 機密データマスキング：ログ内の機密情報を隠す
• 環境分離：テスト環境と本番環境を完全に分離

SSL/TLS構成

# SSL証明書を配置
mkdir -p nginx/ssl
cp your-cert.pem nginx/ssl/cert.pem
cp your-key.pem nginx/ssl/key.pem

セキュリティスキャン

# コンテナのセキュリティスキャン
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
  aquasec/trivy image omise-mcp-server:latest

🚨 トラブルシューティング

一般的な問題

1. サービスが起動しない

# ログを確認
docker-compose logs omise-mcp-server

# 環境変数を確認
docker-compose config

2. ヘルスチェックが失敗する

# ヘルスチェックエンドポイントを直接確認
curl -v http://localhost:3000/health

# サービスの接続性を確認
docker-compose exec omise-mcp-server ping redis

3. メモリの問題

# メモリ使用量を確認
docker stats

# 不要なコンテナを削除
docker system prune -a

ログ分析

# エラーログを確認
docker-compose logs omise-mcp-server | grep ERROR

# アクセスログを分析
docker-compose logs nginx | grep "GET /"

📚 APIリファレンス

支払いツール

create_charge

新しい請求を作成します。

パラメーター:

• amount (必須): 最小通貨単位での金額
• currency (必須): 通貨コード (THB、USD、JPYなど)
• description (オプション): 請求の説明
• customer (オプション): 顧客ID
• card (オプション): カードID
• source (オプション): ソースID
• capture (オプション): すぐにキャプチャする (デフォルト: true)
• return_uri (オプション): リダイレクトURI
• metadata (オプション): メタデータ

retrieve_charge

請求情報を取得します。

パラメーター:

• charge_id (必須): 取得する請求ID

list_charges

請求を一覧表示します。

パラメーター:

• limit (オプション): 取得する項目数 (デフォルト: 20)
• offset (オプション): オフセット (デフォルト: 0)
• order (オプション): 並び順 (chronological/reverse_chronological)
• status (オプション): ステータスフィルター
• customer (オプション): 顧客IDフィルター

顧客ツール

create_customer

新しい顧客を作成します。

パラメーター:

• email (オプション): 顧客のメールアドレス
• description (オプション): 顧客の説明
• card (オプション): カードID
• metadata (オプション): メタデータ

retrieve_customer

顧客情報を取得します。

パラメーター:

• customer_id (必須): 取得する顧客ID

トークンツール

create_token

支払い処理用の安全なカードトークンを作成します。

パラメーター:

• card (必須): カード情報
  • name (必須): カード名義人の名前
  • number (必須): カード番号
  • expiration_month (必須): 有効期限の月 (1 - 12)
  • expiration_year (必須): 有効期限の年 (4桁)
  • city (オプション): 請求先住所の都市
  • postal_code (オプション): 請求先住所の郵便番号
  • security_code (オプション): セキュリティコード (CVV/CVC)

🔗 外部リンク

Omise公式ドキュメント

• Omise API Documentation
• Omise Charges API
• Omise Customers API
• Omise Transfers API
• Omise Refunds API
• Omise Disputes API
• Omise Schedules API
• Omise Events API
• Omise Webhooks API
• Omise Links API
• Omise Chains API
• Omise Capabilities API

技術ドキュメント

• モデルコンテキストプロトコル (MCP)
• Docker Documentation
• Docker Compose Documentation
• Prometheus Documentation
• Grafana Documentation
• Redis Documentation
• Loki Documentation

サポート

• GitHub Issues: バグレポートと機能リクエスト
• Omiseサポート: Omise公式サポート
• コミュニティ: 開発者コミュニティ

📄 ライセンス

このプロジェクトは MITライセンス の下でライセンスされています。

🤝 コントリビューション

このプロジェクトへのコントリビューションは歓迎されています！以下の手順に従ってください。

1. このリポジトリをフォークする
2. 機能ブランチを作成する (git checkout -b feature/amazing-feature)
3. 変更をコミットする (git commit -m 'Add some amazing feature')
4. ブランチにプッシュする (git push origin feature/amazing-feature)
5. プルリクエストを作成する

開発ガイドライン

• TypeScriptでコードを書く
• テストカバレッジを維持する
• ESLintルールに従う
• 明確なコミットメッセージを書く

📈 ロードマップ

v1.1.0 (予定)

• [ ] 追加の支払い方法のサポート
• [ ] 高度なレポート機能
• [ ] パフォーマンス最適化

v1.2.0 (予定)

• [ ] 強化されたマルチテナントサポート
• [ ] 高度な監視機能
• [ ] 強化されたセキュリティ機能

📊 統計

• 総ツール数：51
• サポートされるAPI：11カテゴリ
• テストカバレッジ：95%以上
• TypeScript：100%
• Dockerサポート：✅
• 監視サポート：✅

Omise MCP Server - 安全で効率的な支払い処理を実現しましょう！ 🚀