Omise MCP Server

Omise MCP Server is a comprehensive server for integrating with Omise payment APIs using Model Context Protocol (MCP). Implemented in TypeScript with full support for Omise API v2017-11-02.

🚀 Key Features

💳 Payment Processing

• Charge Management: Create, retrieve, update, capture, and reverse payments
• Tokenization: Secure card information tokenization
• Source Management: Support for various payment methods
• Refunds: Partial and full refund processing

👥 Customer Management

• Customer Information: Create, retrieve, update, and delete customers
• Card Management: Manage customer card information
• Metadata: Store custom information

🔄 Transfers & Recipients

• Transfer Processing: Send money to recipients
• Recipient Management: Create, verify, and manage recipients
• Bank Accounts: Manage bank account information

📅 Schedules & Recurring Payments

• Recurring Payments: Automatic payments based on schedules
• Occurrence Management: Manage schedule execution
• Flexible Configuration: Daily, weekly, and monthly schedules

🔍 Monitoring & Analytics

• Event Management: Track system events
• Dispute Management: Handle chargebacks
• Webhooks: Real-time notifications

🔗 Links & Chains

• Payment Links: Shareable payment links
• Chain Management: Multi-tenant support
• Capability Check: API functionality verification

📋 Supported APIs

Total: 51 tools covering all Omise API functionality

🛠️ Technology Stack

• Runtime: Node.js 20+
• Language: TypeScript 5.2+
• Framework: Model Context Protocol (MCP)
• HTTP Client: Axios
• Logging: Winston
• Testing: Jest + MSW
• Containerization: Docker + Docker Compose
• Monitoring: Prometheus + Grafana
• Caching: Redis
• Log Aggregation: Loki

🚀 Quick Start

Prerequisites

• Node.js 20+
• npm or yarn
• Omise Account and API keys

1. Installation

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

# Install dependencies
npm install

2. Environment Setup

# 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 Development Server

# Start in development mode
npm run dev

# Or start in production mode
npm run build
npm start

4. Verify Installation

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

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

📖 Usage

Basic Payment Processing

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

Recurring Payment Setup

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

Transfer Processing

// 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
});

🔧 Configuration

Environment Variables

Obtaining Omise API Keys

1. Access Omise Dashboard
2. Create an account or log in
3. Get keys from the API Keys section
4. Test Environment: Use keys starting with pkey_test_ and skey_test_
5. Production Environment: Use keys starting with pkey_live_ and skey_live_

Important: Always use live keys in production and test keys in test environment.

🏗️ Project Structure

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

🧪 Development

Development Environment Setup

# Install development dependencies
npm install

# Start development server
npm run dev

# Watch mode
npm run watch

Testing

# 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

Linting

# Run linting
npm run lint

# Auto-fix
npm run lint:fix

Build

# Compile TypeScript
npm run build

# Production build
npm run build:production

🐳 Docker Deployment

Development Environment

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

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

Production Environment

# 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

Automated Deployment

# Run deployment script
./deploy.sh latest production

📊 Monitoring & Logs

Prometheus Metrics

• URL: http://localhost:9090
• Metrics: CPU, memory, request count, response time
• Alerts: High load, error rate monitoring

Grafana Dashboard

• URL: http://localhost:3001
• Login: admin / admin (default)
• Dashboards: System monitoring, application monitoring

Log Management

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

# Nginx logs
docker-compose logs -f nginx

# All service logs
docker-compose logs -f

🔒 Security

Security Features

• Non-root user: Run containers as non-root user
• Security headers: Proper HTTP header configuration
• Rate limiting: API call restrictions
• Sensitive data masking: Hide sensitive information in logs
• Environment isolation: Complete separation of test and production environments

SSL/TLS Configuration

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

Security Scanning

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

🚨 Troubleshooting

Common Issues

1. Service Won't Start

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

# Check environment variables
docker-compose config

2. Health Check Fails

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

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

3. Memory Issues

# Check memory usage
docker stats

# Remove unnecessary containers
docker system prune -a

Log Analysis

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

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

📚 API Reference

Payment Tools

create_charge

Create a new charge.

Parameters:

• amount (required): Amount in smallest currency unit
• currency (required): Currency code (THB, USD, JPY, etc.)
• description (optional): Charge description
• customer (optional): Customer ID
• card (optional): Card ID
• source (optional): Source ID
• capture (optional): Capture immediately (default: true)
• return_uri (optional): Redirect URI
• metadata (optional): Metadata

retrieve_charge

Retrieve charge information.

Parameters:

• charge_id (required): Charge ID to retrieve

list_charges

List charges.

Parameters:

• limit (optional): Number of items to retrieve (default: 20)
• offset (optional): Offset (default: 0)
• order (optional): Sort order (chronological/reverse_chronological)
• status (optional): Status filter
• customer (optional): Customer ID filter

Customer Tools

create_customer

Create a new customer.

Parameters:

• email (optional): Customer email address
• description (optional): Customer description
• card (optional): Card ID
• metadata (optional): Metadata

retrieve_customer

Retrieve customer information.

Parameters:

• customer_id (required): Customer ID to retrieve

Token Tools

create_token

Create a secure card token for payment processing.

Parameters:

• card (required): Card information
  • name (required): Cardholder name
  • number (required): Card number
  • expiration_month (required): Expiration month (1-12)
  • expiration_year (required): Expiration year (4 digits)
  • city (optional): Billing address city
  • postal_code (optional): Billing address postal code
  • security_code (optional): Security code (CVV/CVC)

🔗 External Links

Omise Official Documentation

• 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

Technical Documentation

• Model Context Protocol (MCP)
• Docker Documentation
• Docker Compose Documentation
• Prometheus Documentation
• Grafana Documentation
• Redis Documentation
• Loki Documentation

Support

• GitHub Issues: Bug reports and feature requests
• Omise Support: Omise official support
• Community: Developer community

📄 License

This project is licensed under the MIT License.

🤝 Contributing

Contributions to the project are welcome! Please follow these steps:

1. Fork this repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Create a Pull Request

Development Guidelines

• Write code in TypeScript
• Maintain test coverage
• Follow ESLint rules
• Write clear commit messages

📈 Roadmap

v1.1.0 (Planned)

• Additional payment method support
• Advanced reporting features
• Performance optimizations

v1.2.0 (Planned)

• Enhanced multi-tenant support
• Advanced monitoring features
• Enhanced security features

📊 Statistics

• Total Tools: 51
• Supported APIs: 11 categories
• Test Coverage: 95%+
• TypeScript: 100%
• Docker Support: ✅
• Monitoring Support: ✅

Omise MCP Server - Achieve secure and efficient payment processing! 🚀