@payware/mcp-server 1.0.0

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@payware/mcp-server",
+  "version": "1.0.0",
+  "description": "Official MCP server for payware payment API integration",
+  "main": "src/index.js",
+  "type": "module",
+  "bin": {
+    "payware-mcp": "./src/index.js"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "dev": "node --watch src/index.js",
+    "proxy": "node src/proxy-server.js",
+    "proxy:dev": "node --watch src/proxy-server.js",
+    "bridge": "node src/mcp-proxy.js",
+    "inspector": "npx @modelcontextprotocol/inspector node src/mcp-proxy.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^0.5.0",
+    "axios": "^1.6.0",
+    "cors": "^2.8.5",
+    "dotenv": "^17.2.2",
+    "express": "^5.1.0",
+    "http-proxy-middleware": "^3.0.5",
+    "jsonwebtoken": "^9.0.0",
+    "node-forge": "^1.3.1"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "payware",
+    "payments",
+    "payment-gateway",
+    "payment-processing",
+    "api",
+    "fintech",
+    "pos",
+    "terminal",
+    "merchant",
+    "isv",
+    "oauth2"
+  ],
+  "author": "payware <support@payware.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/payware/mcp-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/payware/mcp-server/issues"
+  },
+  "homepage": "https://github.com/payware/mcp-server#readme",
+  "files": [
+    "src/",
+    "keys/README.md",
+    "README.md",
+    "check-keys.js",
+    "mcp-config.json",
+    "payware-mcp-config.json",
+    ".env.example",
+    "MCP-SETUP.md"
+  ]
+}

package/payware-mcp-config.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "payware": {
+      "command": "node",
+      "args": ["src/index.js"],
+      "cwd": "/mnt/d/git/payware/mcp",
+      "env": {
+        "NODE_ENV": "production"
+      }
+    }
+  }
+}

package/src/auth/rsa-keys.js

@@ -0,0 +1,82 @@
+import forge from 'node-forge';
+
+/**
+ * Generate RSA key pair for payware API authentication
+ * @param {number} keySize - RSA key size in bits (default: 2048)
+ * @returns {Object} Object containing publicKey and privateKey in PEM format
+ */
+export function generateRSAKeyPair(keySize = 2048) {
+  const keyPair = forge.pki.rsa.generateKeyPair({ bits: keySize });
+  
+  const privateKeyPem = forge.pki.privateKeyToPem(keyPair.privateKey);
+  const publicKeyPem = forge.pki.publicKeyToPem(keyPair.publicKey);
+  
+  return {
+    privateKey: privateKeyPem,
+    publicKey: publicKeyPem,
+    keySize,
+    generated: new Date().toISOString()
+  };
+}
+
+/**
+ * Generate RSA keys tool implementation
+ */
+export const generateRSAKeysTool = {
+  name: "payware_authentication_generate_rsa_keys",
+  description: "Generate RSA key pair for payware API authentication",
+  inputSchema: {
+    type: "object",
+    properties: {
+      keySize: {
+        type: "number",
+        description: "RSA key size in bits",
+        minimum: 2048,
+        maximum: 8192
+      }
+    },
+    additionalProperties: false
+  },
+  
+  async handler(args) {
+    const keySize = args.keySize || 2048;
+    
+    if (keySize < 2048) {
+      throw new Error("Key size must be at least 2048 bits for security");
+    }
+    
+    const keyPair = generateRSAKeyPair(keySize);
+    
+    return {
+      content: [{
+        type: "text",
+        text: `🔐 **RSA Key Pair Generated Successfully**
+
+**⚠️ SECURITY WARNING ⚠️**
+- Store private key securely and never share it
+- Use different keys for production environment
+- Sandbox keys should not be used in production
+
+**Private Key:**
+\`\`\`
+${keyPair.privateKey}
+\`\`\`
+
+**Public Key:**
+\`\`\`
+${keyPair.publicKey}
+\`\`\`
+
+**Key Details:**
+- Size: ${keyPair.keySize} bits
+- Generated: ${keyPair.generated}
+- Purpose: payware API authentication (sandbox only)
+
+**Next Steps:**
+1. Save private key to secure location
+2. Register public key with payware sandbox
+3. Use private key to create JWT tokens`
+      }]
+    };
+  }
+};

package/src/auth/sandbox-setup.js

@@ -0,0 +1,187 @@
+/**
+ * Setup sandbox authentication configuration
+ */
+
+import { getPartnerIdSafe, getPrivateKeySafe } from '../config/env.js';
+
+const SANDBOX_CONFIG = {
+  baseUrl: 'https://sandbox.payware.eu/api',
+  apiVersion: '1',
+  environment: 'sandbox',
+  supportedCurrencies: [
+    // Major currencies
+    'EUR', 'USD', 'GBP', 'JPY', 'CHF', 'CAD', 'AUD', 'CNY', 'SEK', 'NOK', 'DKK',
+    // All other supported currencies (100+ total)
+    'AED', 'AFN', 'ALL', 'AMD', 'ANG', 'AOA', 'ARS', 'AWG', 'AZN',
+    'BAM', 'BBD', 'BDT', 'BGN', 'BHD', 'BIF', 'BMD', 'BND', 'BOB', 'BRL', 'BSD', 'BTC', 'BTN', 'BWP', 'BYN', 'BZD',
+    'CDF', 'CLP', 'COP', 'CRC', 'CUP', 'CVE', 'CZK',
+    'DJF', 'DOP', 'DZD',
+    'EGP', 'ERN', 'ETB',
+    'FJD', 'FKP',
+    'GEL', 'GHS', 'GIP', 'GMD', 'GNF', 'GTQ', 'GYD',
+    'HKD', 'HNL', 'HRK', 'HTG', 'HUF',
+    'IDR', 'ILS', 'INR', 'IQD', 'IRR', 'ISK',
+    'JMD', 'JOD',
+    'KES', 'KGS', 'KHR', 'KMF', 'KPW', 'KRW', 'KWD', 'KYD', 'KZT',
+    'LAK', 'LBP', 'LKR', 'LRD', 'LSL', 'LYD',
+    'MAD', 'MDL', 'MGA', 'MKD', 'MMK', 'MNT', 'MOP', 'MRO', 'MUR', 'MVR', 'MWK', 'MXN', 'MYR', 'MZN',
+    'NAD', 'NGN', 'NIO', 'NPR', 'NZD',
+    'OMR',
+    'PAB', 'PEN', 'PGK', 'PHP', 'PKR', 'PLN', 'PYG',
+    'QAR',
+    'RON', 'RSD', 'RUB', 'RWF',
+    'SAR', 'SBD', 'SCR', 'SDG', 'SGD', 'SHP', 'SLL', 'SOS', 'SRD', 'STD', 'SVC', 'SYP', 'SZL',
+    'THB', 'TJS', 'TMT', 'TND', 'TOP', 'TRY', 'TTD', 'TWD', 'TZS',
+    'UAH', 'UGX', 'UYU', 'UZS',
+    'VND', 'VUV',
+    'WST',
+    'XAF', 'XCD', 'XOF', 'XPF',
+    'YER',
+    'ZAR', 'ZMW', 'ZWL'
+  ], // ISO 3-character codes
+  supportedTransactionTypes: ['PLAIN', 'QR', 'BARCODE'], // trOptions.type values
+  transactionTypes: ['DEFAULT', 'SHIPPABLE'], // transactionType values
+  maxAmount: 'Unlimited', // Limited by Java type implementation
+  minAmount: '0.00', // Zero allowed for flexible amounts
+  maxTTL: 600, // seconds
+  minTTL: 60, // seconds
+  defaultTTL: 120, // seconds
+  audience: 'https://payware.eu', // Required JWT audience
+  transactionIdPrefix: 'pw' // All transaction IDs start with 'pw'
+};
+
+/**
+ * Generate sandbox configuration
+ * @param {string} partnerId - Partner ID
+ * @param {string} privateKey - Private key (optional, for validation)
+ * @returns {Object} Sandbox configuration object
+ */
+export function generateSandboxConfig(partnerId, privateKey = null) {
+  const config = {
+    ...SANDBOX_CONFIG,
+    partnerId,
+    endpoints: {
+      createTransaction: `${SANDBOX_CONFIG.baseUrl}/transactions`,
+      getTransactionStatus: `${SANDBOX_CONFIG.baseUrl}/transactions/{id}`,
+      processTransaction: `${SANDBOX_CONFIG.baseUrl}/transactions/{id}`,
+      cancelTransaction: `${SANDBOX_CONFIG.baseUrl}/transactions/{id}`,
+      getTransactionHistory: `${SANDBOX_CONFIG.baseUrl}/transactions-history/{id}`,
+      callback: 'https://your-callback-url' // Provided by merchant
+    },
+    headers: {
+      'Content-Type': 'application/json',
+      'Api-Version': '1'
+    },
+    authentication: {
+      type: 'JWT',
+      algorithm: 'RS256',
+      audience: 'https://payware.eu',
+      requiresContentMd5: 'For POST/PUT/PATCH requests',
+      hasPrivateKey: !!privateKey
+    },
+    generatedAt: new Date().toISOString()
+  };
+
+  return config;
+}
+
+/**
+ * Setup sandbox auth tool implementation  
+ */
+export const setupSandboxAuthTool = {
+  name: "payware_authentication_setup_sandbox_auth",
+  description: "Setup sandbox authentication configuration for payware API",
+  inputSchema: {
+    type: "object",
+    properties: {
+      partnerId: {
+        type: "string",
+        description: "Partner ID from payware dashboard. Uses PAYWARE_PARTNER_ID env var as default."
+      },
+      privateKey: {
+        type: "string",
+        description: "RSA private key in PEM format (optional, for validation). Uses environment-specific private key as default."
+      }
+    },
+    additionalProperties: false
+  },
+  
+  async handler(args) {
+    const {
+      partnerId = getPartnerIdSafe(),
+      privateKey = getPrivateKeySafe()
+    } = args;
+
+    if (!partnerId) {
+      throw new Error("Partner ID is required. Provide via 'partnerId' parameter or set PAYWARE_PARTNER_ID environment variable.");
+    }
+    
+    const config = generateSandboxConfig(partnerId, privateKey);
+    
+    return {
+      content: [{
+        type: "text", 
+        text: `🔧 **Sandbox Authentication Setup Complete**
+
+**Configuration:**
+\`\`\`json
+${JSON.stringify(config, null, 2)}
+\`\`\`
+
+**Environment Details:**
+- Base URL: ${config.baseUrl}
+- API Version: ${config.apiVersion}  
+- Environment: ${config.environment}
+- Partner ID: ${config.partnerId}
+
+**Supported Features:**
+- Request Types (trOptions.type): ${config.supportedTransactionTypes.join(', ')}
+- Transaction Types: ${config.transactionTypes.join(', ')}
+- Currencies: ${config.supportedCurrencies.join(', ')} (ISO 3-char codes)
+- Amount Range: €${config.minAmount} - ${config.maxAmount} (currency values)
+- TTL Range: ${config.minTTL}-${config.maxTTL} seconds (default: ${config.defaultTTL})
+- Transaction ID Format: Starts with '${config.transactionIdPrefix}'
+- QR Options: Format (PNG/JPEG/SVG), Border, Error Correction (L/M/Q/H), Scale, Version
+- Barcode Options: Format (CODE128/CODE39/EAN13), Width, Height, Font Size, Text Location
+- Additional: passbackParams for custom callback data
+
+**API Endpoints:**
+- Create Transaction: \`POST ${config.endpoints.createTransaction}\`
+- Get Transaction Status: \`GET ${config.endpoints.getTransactionStatus}\`
+- Process Transaction: \`POST ${config.endpoints.processTransaction}\` (merchants only)
+- Cancel Transaction: \`PATCH ${config.endpoints.cancelTransaction}\` (creators only)
+- Transaction History: \`GET ${config.endpoints.getTransactionHistory}\` (completed/expired)
+- Callback Endpoint: \`POST [your-callback-url]\` (configured by you)
+
+**Required Headers (All Requests):**
+${Object.entries(config.headers).map(([key, value]) => `- ${key}: ${value}`).join('\n')}
+- Authorization: Bearer {JWT_TOKEN} (with contentMd5 for POST/PATCH)
+
+**JWT Requirements:**
+- Algorithm: RS256
+- Issuer (iss): Your Partner ID
+- Audience (aud): https://payware.eu
+- Content-MD5: Required in JWT header for POST/PATCH requests
+- Private Key: RSA 2048-bit minimum
+
+**Required Fields for Transaction Creation:**
+- trData.currency: ISO 3-character code (required)
+- trData.reasonL1: Description, max 100 chars (required)
+- trData.reasonL2: Continuation, max 100 chars (optional)
+- trData.amount: Currency value as string/number, 0.00+ (optional for flexible)
+- trOptions.type: PLAIN, QR, or BARCODE (default: PLAIN)
+- trOptions.timeToLive: 60-600 seconds (default: 120)
+
+**Next Steps:**
+1. Generate RSA key pair (2048-bit minimum)
+2. Register public key in payware portal
+3. Create JWT token with proper structure
+4. Test with create transaction endpoint
+5. Implement callback handler for status updates
+
+**⚠️ Sandbox Only:**
+This configuration is for sandbox testing only. Do not use in production.`
+      }]
+    };
+  }
+};

package/src/config/env.js

@@ -0,0 +1,229 @@
+/**
+ * Environment configuration for payware MCP server
+ * Supports different partner types: merchant, isv, payment_institution
+ */
+
+// Suppress dotenv informational messages that interfere with MCP JSON-RPC transport
+process.env.DOTENV_CONFIG_QUIET = 'true';
+
+import { config } from 'dotenv';
+import { readFileSync } from 'fs';
+import { resolve } from 'path';
+
+// Load environment variables from .env file (silent mode for MCP compatibility)
+config({ debug: false });
+
+// Valid partner types
+const VALID_PARTNER_TYPES = ['merchant', 'isv', 'payment_institution'];
+const DEFAULT_PARTNER_TYPE = 'merchant';
+
+/**
+ * Get partner ID from environment
+ * @returns {string} Partner ID
+ * @throws {Error} If partner ID is not configured
+ */
+export function getPartnerId() {
+  const partnerId = process.env.PAYWARE_PARTNER_ID;
+  if (!partnerId) {
+    throw new Error('PAYWARE_PARTNER_ID environment variable is required');
+  }
+  return partnerId;
+}
+
+/**
+ * Get private key from environment-specified path
+ * @param {boolean} useSandbox - Whether to use sandbox environment
+ * @returns {string} Private key content
+ * @throws {Error} If private key path is not configured or file cannot be read
+ */
+export function getPrivateKey(useSandbox = true) {
+  let privateKeyPath;
+
+  if (useSandbox) {
+    privateKeyPath = process.env.PAYWARE_SANDBOX_PRIVATE_KEY_PATH;
+  } else {
+    privateKeyPath = process.env.PAYWARE_PRODUCTION_PRIVATE_KEY_PATH;
+  }
+
+  if (!privateKeyPath) {
+    const envVar = useSandbox ? 'PAYWARE_SANDBOX_PRIVATE_KEY_PATH' : 'PAYWARE_PRODUCTION_PRIVATE_KEY_PATH';
+    throw new Error(`${envVar} environment variable is required`);
+  }
+
+  try {
+    // Resolve path relative to project root
+    const fullPath = resolve(privateKeyPath);
+    const privateKey = readFileSync(fullPath, 'utf8');
+    return privateKey;
+  } catch (error) {
+    throw new Error(`Cannot read private key from ${privateKeyPath}: ${error.message}`);
+  }
+}
+
+/**
+ * Get sandbox base URL from environment (with default)
+ * @returns {string} Sandbox base URL
+ */
+export function getSandboxUrl() {
+  return process.env.PAYWARE_SANDBOX_URL || 'https://sandbox.payware.eu/api';
+}
+
+/**
+ * Get production base URL from environment (with default)
+ * @returns {string} Production base URL
+ */
+export function getProductionUrl() {
+  return process.env.PAYWARE_PRODUCTION_URL || 'https://api.payware.eu/api';
+}
+
+/**
+ * Get environment configuration object
+ * @returns {Object} Configuration object with all environment settings
+ */
+export function getEnvironmentConfig() {
+  return {
+    partnerId: getPartnerId(),
+    sandboxPrivateKeyPath: process.env.PAYWARE_SANDBOX_PRIVATE_KEY_PATH,
+    productionPrivateKeyPath: process.env.PAYWARE_PRODUCTION_PRIVATE_KEY_PATH,
+    sandboxUrl: getSandboxUrl(),
+    productionUrl: getProductionUrl(),
+    hasSandboxPrivateKey: !!process.env.PAYWARE_SANDBOX_PRIVATE_KEY_PATH,
+    hasProductionPrivateKey: !!process.env.PAYWARE_PRODUCTION_PRIVATE_KEY_PATH,
+    configuredAt: new Date().toISOString()
+  };
+}
+
+/**
+ * Get partner ID safely (returns undefined if not configured)
+ * @returns {string|undefined} Partner ID or undefined
+ */
+export function getPartnerIdSafe() {
+  try {
+    return getPartnerId();
+  } catch (error) {
+    return undefined;
+  }
+}
+
+/**
+ * Get private key safely (returns undefined if not configured)
+ * @param {boolean} useSandbox - Whether to use sandbox environment
+ * @returns {string|undefined} Private key content or undefined
+ */
+export function getPrivateKeySafe(useSandbox = true) {
+  try {
+    return getPrivateKey(useSandbox);
+  } catch (error) {
+    return undefined;
+  }
+}
+
+/**
+ * Get partner type from environment
+ * @returns {string} Partner type (merchant, isv, or payment_institution)
+ */
+export function getPartnerType() {
+  const partnerType = process.env.PAYWARE_PARTNER_TYPE || DEFAULT_PARTNER_TYPE;
+
+  if (!VALID_PARTNER_TYPES.includes(partnerType)) {
+    throw new Error(`Invalid partner type: ${partnerType}. Valid types: ${VALID_PARTNER_TYPES.join(', ')}`);
+  }
+
+  return partnerType;
+}
+
+/**
+ * Get partner type safely (returns default if not configured)
+ * @returns {string} Partner type or default
+ */
+export function getPartnerTypeSafe() {
+  try {
+    return getPartnerType();
+  } catch (error) {
+    return DEFAULT_PARTNER_TYPE;
+  }
+}
+
+/**
+ * Check if current partner type is ISV
+ * @returns {boolean} True if partner type is ISV
+ */
+export function isISV() {
+  return getPartnerTypeSafe() === 'isv';
+}
+
+/**
+ * Check if current partner type is Payment Institution
+ * @returns {boolean} True if partner type is Payment Institution
+ */
+export function isPaymentInstitution() {
+  return getPartnerTypeSafe() === 'payment_institution';
+}
+
+/**
+ * Check if current partner type is Merchant
+ * @returns {boolean} True if partner type is Merchant
+ */
+export function isMerchant() {
+  return getPartnerTypeSafe() === 'merchant';
+}
+
+/**
+ * Get OAuth2 client ID for ISV partners
+ * @returns {string|undefined} OAuth2 client ID
+ */
+export function getOAuth2ClientId() {
+  if (!isISV()) return undefined;
+  return process.env.PAYWARE_OAUTH_CLIENT_ID;
+}
+
+/**
+ * Get OAuth2 client secret for ISV partners
+ * @returns {string|undefined} OAuth2 client secret
+ */
+export function getOAuth2ClientSecret() {
+  if (!isISV()) return undefined;
+  return process.env.PAYWARE_OAUTH_CLIENT_SECRET;
+}
+
+/**
+ * Get default merchant ID for ISV partners
+ * @returns {string|undefined} Default merchant ID
+ */
+export function getDefaultMerchantId() {
+  if (!isISV()) return undefined;
+  return process.env.PAYWARE_DEFAULT_MERCHANT_ID;
+}
+
+/**
+ * Validate that all required environment variables are set for the partner type
+ * @throws {Error} If any required environment variable is missing
+ */
+export function validateEnvironment() {
+  const partnerType = getPartnerType(); // Will throw if invalid
+  getPartnerId(); // Will throw if missing
+  getPrivateKey(true); // Will throw if missing or unreadable (check sandbox key)
+
+  // ISV-specific validation
+  if (isISV()) {
+    if (!getOAuth2ClientId()) {
+      throw new Error('PAYWARE_OAUTH_CLIENT_ID is required for ISV partners');
+    }
+    if (!getOAuth2ClientSecret()) {
+      throw new Error('PAYWARE_OAUTH_CLIENT_SECRET is required for ISV partners');
+    }
+  }
+
+  console.log('✅ Environment configuration validated');
+  console.log(`   Partner Type: ${partnerType}`);
+  console.log(`   Partner ID: ${getPartnerId()}`);
+  console.log(`   Sandbox Private Key: ${process.env.PAYWARE_SANDBOX_PRIVATE_KEY_PATH ? 'Set' : 'Not set'}`);
+  console.log(`   Production Private Key: ${process.env.PAYWARE_PRODUCTION_PRIVATE_KEY_PATH ? 'Set' : 'Not set'}`);
+  console.log(`   Sandbox URL: ${getSandboxUrl()}`);
+  console.log(`   Production URL: ${getProductionUrl()}`);
+
+  if (isISV()) {
+    console.log(`   OAuth2 Client ID: ${getOAuth2ClientId()}`);
+    console.log(`   Default Merchant ID: ${getDefaultMerchantId() || 'Not set'}`);
+  }
+}