Omise MCP Server

Omise MCP 服务器

Omise MCP 服务器 是一个用于与Omise支付API集成的综合服务器 模型上下文协议（MCP）使用TypeScript实现，全面支持Omise API v2017-11-02。

🚀 主要特点

💳 支付处理

• 充电管理创建、检索、更新、捕获和反转付款
• 分词（或标记化）安全的卡片信息令牌化
• 源管理支持多种支付方式
• 退款部分退款和全额退款处理

👥 客户管理

• 客户信息创建、检索、更新和删除客户信息
• 卡片管理管理客户卡信息
• 元数据存储自定义信息

🔄 转账与收款人

• 传输处理向收款人汇款
• 收件人管理创建、验证和管理收件人
• 银行账户管理银行账户信息

📅 时间表与定期付款

• 定期付款基于计划的自动付款
• 事件管理管理进度执行
• 灵活配置每日、每周和每月的时间表

🔍 监控与分析

• 活动管理跟踪系统事件
• 争议管理处理拒付（或：处理退款请求）
• Webhooks（网络钩子）实时通知

🔗 链接与链条

• 支付链接可分享的支付链接
• 链管理多租户支持
• 能力检查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 Webhooks API | | 链接 | 支付链接 | 3 | Omise Links API | | 链 | 多租户 | 4 | Omise Chains API | | 能力 | 特征验证 | 1 | Omise Capabilities API |

总计：51种工具 涵盖所有Omise API功能

🛠️ 技术栈

• 运行时Node.js 20+（版本）
• 语言TypeScript 5.2+
• 框架模型上下文协议（MCP）
• HTTP 客户端Axios（注：Axios是一个用于浏览器和Node.js的基于promise的HTTP客户端）
• 记录日志温斯顿
• 测试Jest + MSW（注：Jest 是一个 JavaScript 测试框架，MSW 可能是指 Mock Service Worker，一种用于拦截和模拟网络请求的工具）
• 集装箱化Docker + Docker Compose
• 监测Prometheus + Grafana
• 缓存Redis
• 日志聚合洛基

🚀 快速入门

先决条件

• Node.js 20多个版本
• npm 或 yarn
• Omise 账户 以及API密钥

1. 安装

# Clone the repository
git clone https://github.com/your-org/omise-mcp-server.git
cd omise-mcp-server

# Install dependencies
npm install

2. 环境设置

# Copy environment configuration file
cp config/development.env .env

# Set environment variables
export OMISE_PUBLIC_KEY=pkey_test_xxxxxxxxxxxxxxxx
export OMISE_SECRET_KEY=skey_test_xxxxxxxxxxxxxxxx
export OMISE_ENVIRONMENT=test

3. 启动开发服务器

# Start in development mode
npm run dev

# Or start in production mode
npm run build
npm start

4. 验证安装

# Health check
curl http://localhost:3000/health

# Check available tools
curl http://localhost:3000/tools

📖 使用方法

基本支付处理

// Create a charge
const charge = await mcpClient.callTool('create_charge', {
  amount: 10000,        // 100.00 THB (smallest currency unit)
  currency: 'THB',
  description: 'Test payment',
  capture: true
});

// Create a customer
const customer = await mcpClient.callTool('create_customer', {
  email: 'customer@example.com',
  description: 'Test customer'
});

// Create a card token
const token = await mcpClient.callTool('create_token', {
  card: {
    name: 'John Doe',
    number: '4242424242424242',
    expiration_month: 12,
    expiration_year: 2025,
    security_code: '123'
  }
});

设置定期付款

// Create a schedule
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'
  }
});

传输处理

// Create a recipient
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'
  }
});

// Execute transfer
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/                          # Source code
│   ├── index.ts                  # Main server file
│   ├── types/                    # Type definitions
│   │   ├── omise.ts             # Omise API type definitions
│   │   ├── mcp.ts               # MCP type definitions
│   │   └── index.ts             # Type definition exports
│   ├── tools/                    # Tool implementations
│   │   ├── payment-tools.ts     # Payment-related tools
│   │   ├── customer-tools.ts    # Customer-related tools
│   │   ├── token-tools.ts       # Token-related tools
│   │   ├── source-tools.ts      # Source-related tools
│   │   ├── transfer-tools.ts    # Transfer-related tools
│   │   ├── recipient-tools.ts  # Recipient-related tools
│   │   ├── refund-tools.ts      # Refund-related tools
│   │   ├── dispute-tools.ts     # Dispute-related tools
│   │   ├── schedule-tools.ts    # Schedule-related tools
│   │   ├── event-tools.ts       # Event-related tools
│   │   ├── webhook-tools.ts     # Webhook-related tools
│   │   ├── link-tools.ts        # Link-related tools
│   │   ├── chain-tools.ts       # Chain-related tools
│   │   ├── capability-tools.ts  # Capability verification tools
│   │   └── index.ts             # Tool exports
│   └── utils/                    # Utilities
│       ├── config.ts            # Configuration management
│       ├── logger.ts            # Logging functionality
│       ├── omise-client.ts      # Omise API client
│       ├── health-check.ts      # Health check
│       └── index.ts             # Utility exports
├── tests/                        # Tests
│   ├── unit/                     # Unit tests
│   ├── integration/              # Integration tests
│   ├── auth/                     # Authentication tests
│   ├── error/                    # Error handling tests
│   ├── rate-limit/               # Rate limiting tests
│   ├── mocks/                    # Mocks
│   └── factories/                # Test factories
├── config/                       # Configuration files
│   ├── development.env          # Development environment
│   ├── staging.env              # Staging environment
│   └── production.env            # Production environment
├── monitoring/                   # Monitoring configuration
│   ├── prometheus.yml            # Prometheus configuration
│   ├── loki-config.yml          # Loki configuration
│   └── grafana/                  # Grafana configuration
├── nginx/                        # Nginx configuration
├── docker-compose.yml            # Docker Compose configuration
├── Dockerfile                    # Docker configuration
├── package.json                  # Dependencies
├── tsconfig.json                 # TypeScript configuration
└── README.md                     # This file

🧪 开发

开发环境设置

# Install development dependencies
npm install

# Start development server
npm run dev

# Watch mode
npm run watch

测试

# Run all tests
npm test

# Watch mode
npm run test:watch

# Coverage report
npm run test:coverage

# Specific test categories
npm run test:unit
npm run test:integration
npm run test:auth
npm run test:error
npm run test:rate-limit

代码检查（或代码格式化、代码规范检查）

# Run linting
npm run lint

# Auto-fix
npm run lint:fix

构建

# Compile TypeScript
npm run build

# Production build
npm run build:production

🐳 Docker 部署

开发环境

# Start development environment
docker-compose --env-file config/development.env up -d

# Check logs
docker-compose logs -f omise-mcp-server

生产环境

# Start production environment
docker-compose --env-file config/production.env up -d

# Health check
curl http://localhost:3000/health
curl http://localhost:3000/ready
curl http://localhost:3000/live

自动化部署

# Run deployment script
./deploy.sh latest production

📊 监控与日志

Prometheus 指标

• URL（统一资源定位符）http://localhost:9090 翻译为中文是：“本地主机上的9090端口”。不过，通常我们不会直接翻译网址，而是根据上下文来解释或说明其含义。在这个例子中，网址表示的是访问本地计算机上运行在9090端口上的某个服务或应用
• 指标CPU、内存、请求次数、响应时间
• 警报高负载，错误率监控

Grafana 控制面板

• URL（统一资源定位符）http://localhost:3001 翻译为中文是：“本地主机：3001 端口”。不过，通常我们不会直接翻译网址的格式，而是说明其含义或用途。在这个上下文中，可以理解为“访问本地运行在3001端口的服务”
• 登录管理员 / 管理员（默认）
• 仪表盘系统监控，应用程序监控

日志管理

# Application logs
docker-compose logs -f omise-mcp-server

# Nginx logs
docker-compose logs -f nginx

# All service logs
docker-compose logs -f

🔒 安全

安全特性

• 非root用户以非root用户运行容器
• 安全头部（或安全响应头）正确的HTTP头部配置
• 速率限制API调用限制
• 敏感数据遮蔽在日志中隐藏敏感信息
• 环境隔离测试环境与生产环境完全分离

SSL/TLS 配置

# Place SSL certificates
mkdir -p nginx/ssl
cp your-cert.pem nginx/ssl/cert.pem
cp your-key.pem nginx/ssl/key.pem

安全扫描

# Container security scan
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
  aquasec/trivy image omise-mcp-server:latest

🚨 故障排除

常见问题

1. 服务无法启动

# Check logs
docker-compose logs omise-mcp-server

# Check environment variables
docker-compose config

2. 健康检查失败

# Check health check endpoint directly
curl -v http://localhost:3000/health

# Check service connectivity
docker-compose exec omise-mcp-server ping redis

3. 内存问题

# Check memory usage
docker stats

# Remove unnecessary containers
docker system prune -a

日志分析

# Check error logs
docker-compose logs omise-mcp-server | grep ERROR

# Analyze access logs
docker-compose logs nginx | grep "GET /"

📚 API 参考

支付工具

创建费用

创建一个新的费用。

参数：

• amount （必填）：以最小货币单位表示的金额
• currency （必填）：货币代码（泰铢、美元、日元等）
• description （可选）：充电描述
• customer （可选）：客户ID
• card （可选）：卡片ID
• source （可选）：源ID
• capture （可选）：立即捕获（默认：true）
• return_uri （可选）：重定向URI
• metadata （可选）：元数据

“retrieve_charge”可以翻译为“提取费用”或“收取费用（用于提取）”，具体取决于上下文。如果是指从某个地方提取某物时产生的费用，那么“提取费用”更为贴切；如果是指为了提取某物而预先收取的费用，则“收取费用（用于提取）”可能更合适。不过，在大多数情况下，“提取费用”是一个较为通用的翻译

检索收费信息。

参数：

• charge_id （必填）：用于检索的收费ID

费用清单

列出费用。

参数：

• limit （可选）：要检索的项目数量（默认：20）
• offset （可选）：偏移量（默认：0）
• order （可选）：排序顺序（按时间顺序/按逆时间顺序）
• status （可选）：状态过滤器
• customer （可选）：客户ID过滤器

客户工具

创建客户

创建一个新客户。

参数：

• email （可选）：客户电子邮箱地址
• description （可选）：客户描述
• card （可选）：卡片ID
• metadata （可选）：元数据

检索客户信息

检索客户信息。

参数：

• customer_id （必填）：要检索的客户ID

代币工具

创建令牌

为支付处理创建一个安全的卡片令牌。

参数：

• 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 Disputes API”的译文为“Omise争议处理API”
• Omise计划API
• Omise 事件 API
• Omise Webhooks API
• Omise Links API
• Omise Chains API
• Omise 功能 API

技术文档

• 模型上下文协议（MCP）
• Prometheus 文档
• Grafana 文档
• Redis 文档
• Loki 文档

支持

• GitHub Issues（在GitHub上的问题/议题）： 错误报告和功能请求
• Omise 支持团队： Omise官方支持
• 社区: 开发者社区

📄 许可证

这个项目采用以下许可证授权： 麻省理工学院许可证.

🤝 贡献

欢迎为该项目做出贡献！请按照以下步骤操作：

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（计划中）

• \[ \] 增强的多租户支持
• \[ \] 高级监控功能
• \[ \] 增强的安全功能

📊 统计数据

• 总工具五十一
• 支持的API11个类别
• 测试覆盖率95%以上
• TypeScript100%
• Docker 支持✅
• 监控支持✅

______________________________________________________________________

Omise MCP 服务器 - 实现安全高效的支付处理！ 🚀