shield_lock
JinDaGe
← Back to MCP directory
publicPublicdnsLocal runtime

omise-mcp-alpha

Omise MCP Server是一个基于Model Context Protocol的完整支付处理服务器，支持Omise API的所有功能，包括支付处理、客户管理、转账、退款、定期支付等51个工具，提供TypeScript实现和Docker部署。

article

README

🚀 Omise MCP Server

Omise MCP Server 是一个全面的服务器，用于通过 模型上下文协议 (MCP) 集成 Omise 支付 API。它采用 TypeScript 实现，完全支持 Omise API v2017-11-02。

Version License TypeScript Node.js Docker

🚀 快速开始

前提条件

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

| 类别 | 特性 | 工具数量 | 文档 | |---------|----------|------------|---------------| | 支付 | 费用、令牌、支付源 | 8 | Omise 费用 API | | 客户 | 客户与银行卡管理 | 7 | Omise 客户 API | | 转账 | 转账与收款人管理 | 6 | Omise 转账 API | | 退款 | 退款处理 | 3 | Omise 退款 API | | 纠纷 | 退款争议处理 | 7 | Omise 纠纷 API | | 日程 | 定期支付 | 5 | Omise 日程 API | | 事件 | 事件管理 | 2 | Omise 事件 API | | Webhook | 通知管理 | 5 | Omise Webhook API | | 链接 | 支付链接 | 3 | Omise 链接 API | | 链 | 多租户 | 4 | Omise 链 API | | 功能 | 功能验证 | 1 | Omise 功能 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_PUBLIC_KEY | Omise 公钥 | ✓ | - | | OMISE_SECRET_KEY | Omise 私钥 | ✓ | - | | OMISE_ENVIRONMENT | 环境（测试/生产） | ✓ | - | | PORT | 服务器端口 | - | 3000 | | HOST | 服务器主机 | - | localhost | | LOG_LEVEL | 日志级别 | - | info | | LOG_FORMAT | 日志格式 | - | simple | | RATE_LIMIT_ENABLED | 是否启用速率限制 | - | true | | RATE_LIMIT_MAX_REQUESTS | 最大请求数 | - | 100 | | RATE_LIMIT_WINDOW_MS | 时间窗口（毫秒） | - | 60000 |

获取 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 官方文档

技术文档

支持

📄 许可证

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

help

Runtime guide

cloud

Hosted runtime

Hosted servers run from a provider-managed environment. You usually connect the MCP client to the hosted endpoint or follow the provider's authorization flow, without keeping a local process alive

  1. Open provider connection page
  2. Authorize or copy endpoint
  3. Connect from your MCP client
terminal

Local runtime / other methods

Local servers run on your own machine or infrastructure. You normally copy the server_config into your MCP client, install the required package, and provide env variables from env_schema when needed

  1. Copy server_config
  2. Install required package
  3. Fill env variables and restart client