@payware/mcp-server 1.0.0

package/src/core/utils/json-serializer.js

@@ -0,0 +1,100 @@
+/**
+ * JSON Consistency Utilities for payware API
+ *
+ * CORE REQUIREMENT: The exact same compact JSON string must be used for
+ * both JWT contentMd5 calculation and HTTP request body to prevent MD5 mismatches.
+ *
+ * SOLUTION: We use deterministic serialization (sorted keys) to guarantee
+ * consistent JSON output regardless of object property insertion order.
+ *
+ * This prevents subtle bugs where the same object could produce different
+ * JSON strings across different JavaScript environments or property orderings.
+ */
+
+/**
+ * Create consistent compact JSON string for payware API requests
+ *
+ * CORE REQUIREMENT: payware API requires that the exact same compact JSON string
+ * is used for both JWT contentMd5 calculation and the HTTP request body.
+ *
+ * SOLUTION: This function uses deterministic serialization with sorted keys
+ * to guarantee the same output every time, preventing MD5 mismatch errors.
+ *
+ * @param {Object} obj - Object to serialize
+ * @returns {string} Compact JSON string with sorted keys (no whitespace)
+ */
+export function createDeterministicJSON(obj) {
+  if (obj === null || obj === undefined) {
+    return JSON.stringify(obj);
+  }
+  
+  if (typeof obj !== 'object' || Array.isArray(obj)) {
+    return JSON.stringify(obj);
+  }
+  
+  // Sort object keys recursively to ensure deterministic output
+  const sortedObj = sortObjectKeys(obj);
+  
+  // Use JSON.stringify with no formatting (minimized)
+  return JSON.stringify(sortedObj);
+}
+
+/**
+ * Recursively sort object keys to ensure deterministic ordering
+ * @param {any} obj - Object to sort
+ * @returns {any} Object with sorted keys
+ */
+function sortObjectKeys(obj) {
+  if (obj === null || obj === undefined) {
+    return obj;
+  }
+  
+  if (Array.isArray(obj)) {
+    return obj.map(item => sortObjectKeys(item));
+  }
+  
+  if (typeof obj !== 'object') {
+    return obj;
+  }
+  
+  const sorted = {};
+  const keys = Object.keys(obj).sort();
+  
+  for (const key of keys) {
+    sorted[key] = sortObjectKeys(obj[key]);
+  }
+  
+  return sorted;
+}
+
+/**
+ * Create compact JSON for payware API requests (alias for consistency)
+ *
+ * payware REQUIRES:
+ * 1. JSON must be compact (no extra whitespace)
+ * 2. The EXACT same string must be used for JWT contentMd5 and HTTP body
+ *
+ * This function ensures both requirements by using deterministic serialization.
+ *
+ * @param {Object} requestBody - Request body object
+ * @returns {string} Compact JSON string with sorted keys
+ */
+export function createMinimizedJSON(requestBody) {
+  return createDeterministicJSON(requestBody);
+}
+
+/**
+ * Validate that two objects produce the same JSON string
+ *
+ * This is crucial for payware API because the JWT contentMd5 and HTTP body
+ * must use the exact same string. This function helps test that requirement.
+ *
+ * @param {Object} obj1 - First object
+ * @param {Object} obj2 - Second object
+ * @returns {boolean} True if both objects produce identical JSON strings
+ */
+export function validateJSONConsistency(obj1, obj2) {
+  const json1 = createDeterministicJSON(obj1);
+  const json2 = createDeterministicJSON(obj2);
+  return json1 === json2;
+}

package/src/core/utils/key-utils.js

@@ -0,0 +1,133 @@
+/**
+ * RSA Key Utility Functions
+ * Handles flexible key formats for payware MCP server
+ */
+
+/**
+ * Normalize RSA private key to proper PEM format
+ * Accepts keys with or without headers/footers
+ * Preserves the original key format (PKCS#8 vs RSA) when headers are present
+ * @param {string} privateKey - RSA private key in various formats
+ * @returns {string} Properly formatted PEM private key
+ */
+export function normalizePrivateKey(privateKey) {
+  if (!privateKey) {
+    throw new Error('Private key is required');
+  }
+
+  // Remove any extra whitespace and line breaks
+  const cleanKey = privateKey.trim().replace(/\r/g, '');
+
+  // Check if key already has proper PEM format - preserve the original format
+  if (cleanKey.includes('-----BEGIN RSA PRIVATE KEY-----') || cleanKey.includes('-----BEGIN PRIVATE KEY-----')) {
+    // Key already has headers, return as-is (with proper line breaks)
+    return cleanKey.replace(/\r?\n/g, '\n');
+  }
+
+  // Remove any existing partial headers/footers
+  let keyContent = cleanKey
+    .replace(/-----BEGIN[^-]*-----/g, '')
+    .replace(/-----END[^-]*-----/g, '')
+    .replace(/\s+/g, '') // Remove all whitespace
+    .trim();
+
+  if (!keyContent) {
+    throw new Error('Private key content is empty after normalization');
+  }
+
+  // Add line breaks every 64 characters for proper PEM format
+  const formattedContent = keyContent.match(/.{1,64}/g)?.join('\n') || keyContent;
+
+  // Default to PKCS#8 format (more modern and widely supported)
+  // Use PRIVATE KEY instead of RSA PRIVATE KEY for better compatibility
+  return `-----BEGIN PRIVATE KEY-----
+${formattedContent}
+-----END PRIVATE KEY-----`;
+}
+
+/**
+ * Normalize RSA public key to proper PEM format
+ * Accepts keys with or without headers/footers
+ * @param {string} publicKey - RSA public key in various formats
+ * @returns {string} Properly formatted PEM public key
+ */
+export function normalizePublicKey(publicKey) {
+  if (!publicKey) {
+    throw new Error('Public key is required');
+  }
+
+  // Remove any extra whitespace and line breaks
+  const cleanKey = publicKey.trim().replace(/\r/g, '');
+  
+  // Check if key already has proper PEM format
+  if (cleanKey.includes('-----BEGIN PUBLIC KEY-----') || cleanKey.includes('-----BEGIN RSA PUBLIC KEY-----')) {
+    return cleanKey;
+  }
+  
+  // Remove any existing partial headers/footers
+  let keyContent = cleanKey
+    .replace(/-----BEGIN[^-]*-----/g, '')
+    .replace(/-----END[^-]*-----/g, '')
+    .replace(/\s+/g, '') // Remove all whitespace
+    .trim();
+  
+  if (!keyContent) {
+    throw new Error('Public key content is empty after normalization');
+  }
+  
+  // Add line breaks every 64 characters for proper PEM format
+  const formattedContent = keyContent.match(/.{1,64}/g)?.join('\n') || keyContent;
+  
+  // Return with proper PUBLIC KEY headers
+  return `-----BEGIN PUBLIC KEY-----
+${formattedContent}
+-----END PUBLIC KEY-----`;
+}
+
+/**
+ * Validate if a string looks like base64 encoded key content
+ * @param {string} content - Content to validate
+ * @returns {boolean} True if looks like valid base64 key content
+ */
+export function isValidKeyContent(content) {
+  if (!content || content.length < 100) return false; // RSA keys should be much longer
+  
+  // Check if it contains only valid base64 characters
+  const base64Regex = /^[A-Za-z0-9+/=\s]*$/;
+  return base64Regex.test(content);
+}
+
+/**
+ * Get key format information
+ * @param {string} key - Key to analyze
+ * @returns {Object} Information about the key format
+ */
+export function getKeyInfo(key) {
+  const cleanKey = key.trim();
+  
+  const info = {
+    hasHeaders: false,
+    isPrivate: false,
+    isPublic: false,
+    format: 'unknown',
+    length: key.length
+  };
+  
+  // Check for headers
+  if (cleanKey.includes('-----BEGIN') && cleanKey.includes('-----END')) {
+    info.hasHeaders = true;
+  }
+  
+  // Check key type
+  if (cleanKey.includes('PRIVATE KEY')) {
+    info.isPrivate = true;
+    info.format = cleanKey.includes('RSA PRIVATE KEY') ? 'rsa-private' : 'pkcs8-private';
+  } else if (cleanKey.includes('PUBLIC KEY')) {
+    info.isPublic = true;
+    info.format = cleanKey.includes('RSA PUBLIC KEY') ? 'rsa-public' : 'pkcs8-public';
+  } else if (isValidKeyContent(cleanKey)) {
+    info.format = 'base64-content';
+  }
+  
+  return info;
+}

package/src/index.js

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+
+/**
+ * payware MCP Server with Partner Type Support
+ * Dynamically loads tools based on partner type (merchant, isv, payment_institution)
+ * Provides authentication and transaction tools for payware API integration
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ErrorCode,
+  McpError
+} from '@modelcontextprotocol/sdk/types.js';
+
+// Import partner type and configuration
+import { getPartnerTypeSafe, getPartnerType } from './config/env.js';
+import { getPartnerConfig, getPartnerDisplayInfo } from './config/partner-types.js';
+
+// Import tool registries
+import { getSharedTools } from './shared/index.js';
+import { getMerchantTools } from './merchant/index.js';
+import { getISVTools } from './isv/index.js';
+import { getPaymentInstitutionTools } from './payment-institution/index.js';
+
+class PaywareMCPServer {
+  constructor() {
+    this.partnerType = getPartnerTypeSafe();
+    this.partnerConfig = getPartnerConfig(this.partnerType);
+    this.partnerInfo = getPartnerDisplayInfo(this.partnerType);
+
+    this.server = new Server(
+      {
+        name: `payware-mcp-server-${this.partnerType}`,
+        version: '1.0.0',
+      },
+      {
+        capabilities: {
+          tools: {},
+        },
+      }
+    );
+
+    this.tools = this.loadPartnerTools();
+    this.setupToolHandlers();
+    this.setupErrorHandling();
+  }
+
+  /**
+   * Load tools based on partner type
+   * @returns {Array} Combined array of shared and partner-specific tools
+   */
+  loadPartnerTools() {
+    let allTools = [];
+
+    switch (this.partnerType) {
+      case 'merchant':
+        allTools = getMerchantTools();
+        break;
+      case 'isv':
+        allTools = getISVTools();
+        break;
+      case 'payment_institution':
+        allTools = getPaymentInstitutionTools();
+        break;
+      default:
+        // Send warning to stderr to avoid MCP protocol corruption
+        process.stderr.write(`Warning: Unknown partner type: ${this.partnerType}, defaulting to merchant tools\n`);
+        allTools = getMerchantTools();
+    }
+
+    // Only log in development mode to avoid interfering with MCP transport
+    // Debugging disabled to prevent MCP JSON-RPC protocol corruption
+    // These logs interfere with the MCP client communication
+    // console.log messages on stdout break the JSON-RPC protocol
+    return allTools;
+  }
+
+  setupToolHandlers() {
+    // MCP protocol requires clean JSON-RPC communication over stdio
+    // Any console.log to stdout will corrupt the protocol and cause
+    // "Unexpected end of JSON input" and "not valid JSON" errors
+    // All debugging output has been permanently disabled
+
+    // List tools handler
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+      return {
+        tools: this.tools.map(tool => ({
+          name: tool.name,
+          description: `[${this.partnerInfo.name}] ${tool.description}`,
+          inputSchema: tool.inputSchema
+        }))
+      };
+    });
+
+    // Call tool handler
+    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      const { name, arguments: args } = request.params;
+      const timestamp = new Date().toISOString();
+
+      // Find the tool by name
+      const tool = this.tools.find(t => t.name === name);
+      
+      if (!tool) {
+        throw new McpError(
+          ErrorCode.MethodNotFound,
+          `Unknown tool: ${name}`
+        );
+      }
+
+      try {
+        // Call the tool's handler with execution metadata
+        const startTime = Date.now();
+        const result = await tool.handler(args || {});
+        const duration = Date.now() - startTime;
+        
+        // Add execution metadata to response
+        if (result && result.content && Array.isArray(result.content)) {
+          result.content.forEach(content => {
+            if (content.type === 'text') {
+              content.text += `\n\n---\n**Execution Info:**\n- Partner Type: ${this.partnerInfo.name}\n- Tool: ${name}\n- Executed: ${timestamp}\n- Duration: ${duration}ms\n- Process ID: ${process.pid}\n- Status: ✅ Success`;
+            }
+          });
+        }
+        
+        return result;
+      } catch (error) {
+        throw new McpError(
+          ErrorCode.InternalError,
+          `Error executing tool ${name}: ${error.message}`
+        );
+      }
+    });
+  }
+
+  setupErrorHandling() {
+    this.server.onerror = (error) => {
+      // MCP server error - will be handled by client
+      // Don't output anything to stdout to avoid protocol corruption
+    };
+
+    process.on('SIGINT', async () => {
+      // Graceful shutdown without any console output
+      try {
+        await this.server.close();
+      } catch (error) {
+        // Ignore shutdown errors to prevent console output
+      }
+      process.exit(0);
+    });
+
+    process.on('SIGTERM', async () => {
+      // Handle SIGTERM gracefully without console output
+      try {
+        await this.server.close();
+      } catch (error) {
+        // Ignore shutdown errors to prevent console output
+      }
+      process.exit(0);
+    });
+
+    // Prevent any unhandled promise rejections from outputting to console
+    process.on('unhandledRejection', (reason, promise) => {
+      // Send to stderr to avoid MCP protocol corruption
+      process.stderr.write(`Unhandled promise rejection: ${reason}\n`);
+    });
+  }
+
+  async run() {
+    const transport = new StdioServerTransport();
+    await this.server.connect(transport);
+    // MCP server ready - no console output needed
+  }
+}
+
+// COMPREHENSIVE stdout protection for MCP protocol
+// Hijack ALL console methods that could output to stdout
+const originalConsole = {
+  log: console.log,
+  info: console.info,
+  warn: console.warn,
+  error: console.error,
+  debug: console.debug,
+  trace: console.trace
+};
+
+// Redirect all console output to stderr to prevent MCP protocol corruption
+console.log = (...args) => process.stderr.write(`[LOG] ${args.join(' ')}\n`);
+console.info = (...args) => process.stderr.write(`[INFO] ${args.join(' ')}\n`);
+console.warn = (...args) => process.stderr.write(`[WARN] ${args.join(' ')}\n`);
+console.error = (...args) => process.stderr.write(`[ERROR] ${args.join(' ')}\n`);
+console.debug = (...args) => process.stderr.write(`[DEBUG] ${args.join(' ')}\n`);
+console.trace = (...args) => process.stderr.write(`[TRACE] ${args.join(' ')}\n`);
+
+// Hijack process.stdout.write to catch any direct writes
+const originalStdoutWrite = process.stdout.write;
+process.stdout.write = function(chunk, encoding, callback) {
+  // Only allow JSON-RPC messages through (they should start with { or be buffers)
+  const str = chunk.toString();
+
+  // Allow JSON-RPC messages (start with { or [, or are empty/whitespace)
+  if (str.startsWith('{') || str.startsWith('[') || str.trim() === '') {
+    return originalStdoutWrite.call(this, chunk, encoding, callback);
+  }
+
+  // Block anything that looks like text messages (especially shutdown messages)
+  if (str.toLowerCase().includes('shutting') ||
+      str.toLowerCase().includes('closing') ||
+      str.toLowerCase().includes('stopping') ||
+      str.toLowerCase().includes('exit')) {
+    process.stderr.write(`[MCP STDOUT BLOCKED] ${str}`);
+    if (callback) callback();
+    return true;
+  }
+
+  // Block any other non-JSON content
+  process.stderr.write(`[STDOUT BLOCKED] ${str}`);
+  if (callback) callback();
+  return true;
+};
+
+// Also override process exit handlers to be completely silent
+const originalExit = process.exit;
+process.exit = function(code) {
+  // Exit silently without any output
+  originalExit.call(this, code);
+};
+
+// Start the server
+const server = new PaywareMCPServer();
+server.run().catch(error => {
+  // Send error to stderr (not stdout) to avoid MCP protocol corruption
+  process.stderr.write(`Failed to start payware MCP Server: ${error.message}\n`);
+  process.exit(1);
+});