Omise MCP Alpha

🚀 Omise MCP Server

Omise MCP Server is a comprehensive server designed for seamless integration with Omise payment APIs using the Model Context Protocol (MCP). Built with TypeScript, it fully supports Omise API v2017 - 11 - 02, enabling secure and efficient payment processing.

✨ Features

💳 Payment Processing

• Charge Management: Create, retrieve, update, capture, and reverse payments.
• Tokenization: Securely tokenize card information.
• Source Management: Support various payment methods.
• Refunds: Process partial and full refunds.

👥 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: Automate payments based on schedules.
• Occurrence Management: Manage schedule execution.
• Flexible Configuration: Set daily, weekly, or monthly schedules.

🔍 Monitoring & Analytics

• Event Management: Track system events.
• Dispute Management: Handle chargebacks.
• Webhooks: Receive real - time notifications.

🔗 Links & Chains

• Payment Links: Share payment links.
• Chain Management: Support multi - tenant scenarios.
• Capability Check: Verify API functionality.

📦 Installation

Prerequisites

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

1. Clone the Repository

git clone https://github.com/your-org/omise-mcp-server.git
cd omise-mcp-server

2. Install Dependencies

npm install

3. Environment Setup

cp config/development.env .env
export OMISE_PUBLIC_KEY=pkey_test_xxxxxxxxxxxxxxxx
export OMISE_SECRET_KEY=skey_test_xxxxxxxxxxxxxxxx
export OMISE_ENVIRONMENT=test

4. Start the Server

# Start in development mode
npm run dev

# Or start in production mode
npm run build
npm start

5. Verify Installation

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

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

💻 Usage Examples

Basic Usage

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

Advanced Usage

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

📚 Documentation

Supported APIs

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 Note

Always use live keys in production and test keys in the 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: Properly configure HTTP headers.
• Rate limiting: Restrict API calls.
• Sensitive data masking: Hide sensitive information in logs.
• Environment isolation: Completely separate 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 /"

🔧 Technical Details

API Reference

Payment Tools

create_charge

Create a new charge.

Parameters:

• amount (required): Amount in the 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! 🚀