Omise MCP Alpha

🚀 Omise MCP Server

Omise MCP Server 是一個全面的服務器，用於通過 模型上下文協議 (MCP) 集成 Omise 支付 API。它採用 TypeScript 實現，完全支持 Omise API v2017-11-02。

🚀 快速開始

前提條件

• 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

✨ 主要特性

💳 支付處理

• 費用管理：創建、檢索、更新、捕獲和撤銷支付
• 令牌化：安全的銀行卡信息令牌化
• 支付源管理：支持多種支付方式
• 退款：部分和全額退款處理

👥 客戶管理

• 客戶信息：創建、檢索、更新和刪除客戶
• 銀行卡管理：管理客戶銀行卡信息
• 元數據：存儲自定義信息

🔄 轉賬與收款人

• 轉賬處理：向收款人轉賬
• 收款人管理：創建、驗證和管理收款人
• 銀行賬戶：管理銀行賬戶信息

📅 日程安排與定期支付

• 定期支付：根據日程安排自動支付
• 事件管理：管理日程執行
• 靈活配置：支持每日、每週和每月日程

🔍 監控與分析

• 事件管理：跟蹤系統事件
• 糾紛管理：處理退款爭議
• Webhook：即時通知

🔗 鏈接與鏈

• 支付鏈接：可共享的支付鏈接
• 鏈管理：多租戶支持
• 功能檢查：API 功能驗證

📦 支持的 API

總計：51 個工具，涵蓋所有 Omise API 功能

💻 使用示例

基礎用法

基本支付處理

// 創建一筆費用
const charge = await mcpClient.callTool('create_charge', {
  amount: 10000,        // 100.00 泰銖（最小貨幣單位）
  currency: 'THB',
  description: '測試支付',
  capture: true
});

// 創建一個客戶
const customer = await mcpClient.callTool('create_customer', {
  email: 'customer@example.com',
  description: '測試客戶'
});

// 創建一個銀行卡令牌
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: '月度訂閱'
  }
});

轉賬處理

// 創建一個收款人
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

安全

安全特性

• 非 root 用戶：以非 root 用戶身份運行容器
• 安全頭：正確配置 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 /"

🔧 技術細節

技術棧

• 運行時環境：Node.js 20+
• 編程語言：TypeScript 5.2+
• 框架：模型上下文協議 (MCP)
• HTTP 客戶端：Axios
• 日誌記錄：Winston
• 測試：Jest + MSW
• 容器化：Docker + Docker Compose
• 監控：Prometheus + Grafana
• 緩存：Redis
• 日誌聚合：Loki

📄 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（可選）：排序順序（按時間順序/按時間逆序）
• 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 文檔
• Omise 費用 API
• Omise 客戶 API
• Omise 轉賬 API
• Omise 退款 API
• Omise 糾紛 API
• Omise 日程 API
• Omise 事件 API
• Omise Webhook API
• Omise 鏈接 API
• Omise 鏈 API
• Omise 功能 API

技術文檔

• 模型上下文協議 (MCP)
• Docker 文檔
• Docker Compose 文檔
• Prometheus 文檔
• Grafana 文檔
• Redis 文檔
• Loki 文檔

支持

• GitHub 問題：Bug 報告和功能請求
• Omise 支持：Omise 官方支持
• 社區：開發者社區

📄 許可證

本項目採用 MIT 許可證。

🤝 貢獻

歡迎對本項目進行貢獻！請遵循以下步驟：

1. Fork 此倉庫
2. 創建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 創建 Pull Request

開發指南

• 使用 TypeScript 編寫代碼
• 保持測試覆蓋率
• 遵循 ESLint 規則
• 編寫清晰的提交信息

📈 路線圖

v1.1.0（計劃中）

• [ ] 支持更多支付方式
• [ ] 高級報告功能
• [ ] 性能優化

v1.2.0（計劃中）

• [ ] 增強多租戶支持
• [ ] 高級監控功能
• [ ] 增強安全功能

📊 統計信息

• 工具總數：51
• 支持的 API：11 個類別
• 測試覆蓋率：95%+
• TypeScript 佔比：100%
• Docker 支持：✅
• 監控支持：✅

Omise MCP Server - 實現安全高效的支付處理！🚀