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
| Category | Features | Tool Count | Documentation |
|---|---|---|---|
| Payment | Charges, Tokens, Sources | 8 | Omise Charges API |
| Customer | Customer & Card Management | 7 | Omise Customers API |
| Transfer | Transfer & Recipient Management | 6 | Omise Transfers API |
| Refund | Refund Processing | 3 | Omise Refunds API |
| Dispute | Chargeback Processing | 7 | Omise Disputes API |
| Schedule | Recurring Payments | 5 | Omise Schedules API |
| Event | Event Management | 2 | Omise Events API |
| Webhook | Notification Management | 5 | Omise Webhooks API |
| Link | Payment Links | 3 | Omise Links API |
| Chain | Multi-tenant | 4 | Omise Chains API |
| Capability | Feature Verification | 1 | Omise Capabilities API |
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
| Variable | Description | Required | Default |
|---|---|---|---|
OMISE_PUBLIC_KEY | Omise public key | ✓ | - |
OMISE_SECRET_KEY | Omise secret key | ✓ | - |
OMISE_ENVIRONMENT | Environment (test/production) | ✓ | - |
PORT | Server port | - | 3000 |
HOST | Server host | - | localhost |
LOG_LEVEL | Log level | - | info |
LOG_FORMAT | Log format | - | simple |
RATE_LIMIT_ENABLED | Enable rate limiting | - | true |
RATE_LIMIT_MAX_REQUESTS | Maximum requests | - | 100 |
RATE_LIMIT_WINDOW_MS | Time window (ms) | - | 60000 |
Obtaining Omise API Keys
- Access Omise Dashboard
- Create an account or log in
- Get keys from the API Keys section
- Test Environment: Use keys starting with
pkey_test_andskey_test_ - Production Environment: Use keys starting with
pkey_live_andskey_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 unitcurrency(required): Currency code (THB, USD, JPY, etc.)description(optional): Charge descriptioncustomer(optional): Customer IDcard(optional): Card IDsource(optional): Source IDcapture(optional): Capture immediately (default: true)return_uri(optional): Redirect URImetadata(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 filtercustomer(optional): Customer ID filter
Customer Tools
create_customer
Create a new customer.
Parameters:
email(optional): Customer email addressdescription(optional): Customer descriptioncard(optional): Card IDmetadata(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 informationname(required): Cardholder namenumber(required): Card numberexpiration_month(required): Expiration month (1-12)expiration_year(required): Expiration year (4 digits)city(optional): Billing address citypostal_code(optional): Billing address postal codesecurity_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:
- Fork this repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - 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! 🚀