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 - 实现安全高效的支付处理！🚀