@payware/mcp-server 1.0.0

package/src/mcp-proxy.js

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+
+/**
+ * MCP-to-HTTP Bridge for payware MCP Server
+ * Provides proper MCP transport (stdio) that bridges to HTTP endpoints
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import './config/env.js'; // Load environment variables
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ErrorCode,
+  McpError
+} from '@modelcontextprotocol/sdk/types.js';
+import axios from 'axios';
+
+class PaywareMCPBridge {
+  constructor(httpServerUrl = 'http://localhost:3001') {
+    this.httpServerUrl = httpServerUrl;
+    this.server = new Server(
+      {
+        name: 'payware-mcp-bridge',
+        version: '1.0.0',
+      },
+      {
+        capabilities: {
+          tools: {},
+        },
+      }
+    );
+
+    this.setupToolHandlers();
+    this.setupErrorHandling();
+  }
+
+  setupToolHandlers() {
+    // List tools handler - proxy to HTTP server
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+      try {
+        const response = await axios.get(`${this.httpServerUrl}/tools`, {
+          timeout: 5000
+        });
+        
+        if (response.data && response.data.result && response.data.result.tools) {
+          return { tools: response.data.result.tools };
+        } else {
+          throw new Error('Invalid response format from HTTP server');
+        }
+      } catch (error) {
+        throw new McpError(
+          ErrorCode.InternalError,
+          `Failed to list tools from HTTP server: ${error.message}`
+        );
+      }
+    });
+
+    // Call tool handler - proxy to HTTP server
+    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      const { name, arguments: args } = request.params;
+      
+      try {
+        const response = await axios.post(`${this.httpServerUrl}/tools/${name}`, args || {}, {
+          headers: { 'Content-Type': 'application/json' },
+          timeout: 30000
+        });
+        
+        // Handle both direct result and JSON-RPC wrapped responses
+        if (response.data && response.data.result) {
+          return response.data.result;
+        } else if (response.data && !response.data.error) {
+          // Direct response without JSON-RPC wrapper
+          return response.data;
+        } else if (response.data && response.data.error) {
+          // JSON-RPC error response - preserve the original error message
+          const errorMessage = response.data.error.message || 'Tool execution failed';
+          console.error(`[Bridge] HTTP proxy returned error: ${errorMessage}`);
+          throw new Error(errorMessage);
+        } else {
+          throw new Error('Invalid response format from HTTP server');
+        }
+      } catch (error) {
+        if (error.response) {
+          // HTTP error response
+          const errorMsg = error.response.data?.message || error.response.statusText || 'HTTP request failed';
+          throw new McpError(
+            ErrorCode.InternalError,
+            `Tool execution failed: ${errorMsg}`
+          );
+        } else if (error.request) {
+          // Network error
+          throw new McpError(
+            ErrorCode.InternalError,
+            `Network error: Failed to connect to HTTP server at ${this.httpServerUrl}`
+          );
+        } else {
+          // Other error
+          throw new McpError(
+            ErrorCode.InternalError,
+            `Unexpected error: ${error.message}`
+          );
+        }
+      }
+    });
+  }
+
+  setupErrorHandling() {
+    this.server.onerror = (error) => {
+      console.error('MCP Bridge error:', error);
+    };
+
+    process.on('SIGINT', async () => {
+      console.log('\nShutting down MCP Bridge...');
+      await this.server.close();
+      process.exit(0);
+    });
+
+    process.on('SIGTERM', async () => {
+      console.log('\nShutting down MCP Bridge...');
+      await this.server.close();
+      process.exit(0);
+    });
+  }
+
+  async run() {
+    // Test connection to HTTP server first
+    try {
+      const response = await axios.get(`${this.httpServerUrl}/health`, { timeout: 5000 });
+      console.error(`✅ Connected to HTTP server: ${response.data.service} v${response.data.version}`);
+    } catch (error) {
+      console.error(`❌ Failed to connect to HTTP server at ${this.httpServerUrl}`);
+      console.error('Make sure the HTTP proxy server is running with: npm run proxy');
+      process.exit(1);
+    }
+
+    const transport = new StdioServerTransport();
+    await this.server.connect(transport);
+    console.error('🔗 MCP Bridge ready - connected to payware HTTP proxy');
+  }
+}
+
+// Start the bridge
+const httpServerUrl = process.env.HTTP_SERVER_URL || 'http://localhost:3001';
+const bridge = new PaywareMCPBridge(httpServerUrl);
+
+bridge.run().catch(error => {
+  console.error('❌ Failed to start MCP Bridge:', error.message);
+  process.exit(1);
+});

package/src/merchant/data/export-report.js

@@ -0,0 +1,108 @@
+import { exportReport, EXPORT_FORMATS } from '../../shared/data/data-api.js';
+import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+
+/**
+ * Export report tool for merchants
+ */
+export const exportReportTool = {
+  name: "payware_data_export_report",
+  description: "Export a READY report in a specific format (PDF, CSV, Excel, JSON). The report must be in READY status first.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      requestId: {
+        type: "string",
+        description: "The request ID from the report generation (UUID format)"
+      },
+      outputFormat: {
+        type: "string",
+        description: "Export format",
+        enum: Object.values(EXPORT_FORMATS),
+        default: EXPORT_FORMATS.PDF
+      },
+      partnerId: {
+        type: "string",
+        description: "Partner ID from payware dashboard. Uses PAYWARE_PARTNER_ID env var as default.",
+        default: getPartnerIdSafe()
+      },
+      privateKey: {
+        type: "string",
+        description: "RSA private key for authentication. Uses environment-specific private key as default.",
+        default: getPrivateKeySafe()
+      }
+    },
+    required: ["requestId"]
+  },
+
+  async handler(args) {
+    const {
+      requestId,
+      outputFormat = EXPORT_FORMATS.PDF,
+      partnerId = getPartnerIdSafe(),
+      privateKey = getPrivateKeySafe()
+    } = args;
+
+    if (!partnerId || !privateKey) {
+      throw new Error("Partner ID and private key are required. Set PAYWARE_PARTNER_ID and environment-specific private key variables or provide them as parameters.");
+    }
+
+    try {
+      const result = await exportReport({
+        requestId,
+        outputFormat,
+        partnerType: 'merchant',
+        partnerId,
+        privateKey
+      });
+
+      const data = result.data;
+
+      // The export API returns export details in an outputResource object
+      if (!data.outputResource || !data.outputResource.exportId) {
+        throw new Error(`Export ID not found in response. Response: ${JSON.stringify(data)}`);
+      }
+
+      const exportResource = data.outputResource;
+
+      return {
+        content: [{
+          type: "text",
+          text: `📊 **Report Export Started**
+
+**Export Details:**
+- Request ID: ${data.requestId || requestId}
+- Export ID: ${exportResource.exportId}
+- Format: ${outputFormat.toUpperCase()}
+- Status: ${exportResource.status || 'QUEUED'}
+- Export Started: ${exportResource.exportedAt || 'Just now'}
+
+**Report Information:**
+- Report Type: ${data.reportUnitId || 'N/A'}
+- Date Range: ${data.dateFrom || 'Default'} to ${data.dateTo || 'Default'}
+- Timezone: ${data.timeZone || 'N/A'}
+
+**Next Steps:**
+1. Save the Export ID: \`${exportResource.exportId}\`
+2. Use "Get Export Status" tool to monitor export progress
+3. When export status is "READY", use "Download Export" tool to get the file
+
+**Available Export Formats:**
+- **PDF**: ${EXPORT_FORMATS.PDF} - Formatted reports with charts and styling
+- **CSV**: ${EXPORT_FORMATS.CSV} - Comma-separated values for data analysis
+- **Excel**: ${EXPORT_FORMATS.EXCEL} - Microsoft Excel format
+- **JSON**: ${EXPORT_FORMATS.JSON} - Structured data format
+
+**Export Status Meanings:**
+- 🟡 **QUEUED**: Export is waiting to be processed
+- ✅ **READY**: Export completed and ready for download
+- ❌ **CANCELLED**: Export was cancelled
+- 💥 **FAILED**: Error occurred during export
+
+Monitor the export progress using Export ID: \`${exportResource.exportId}\``
+        }]
+      };
+    } catch (error) {
+      throw new Error(`Failed to export report: ${error.message}`);
+    }
+  }
+};

package/src/merchant/data/generate-report.js

@@ -0,0 +1,151 @@
+import { generateReport, REPORT_TYPES, LOCALES } from '../../shared/data/data-api.js';
+import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+
+/**
+ * Generate report tool for merchants
+ */
+export const generateReportTool = {
+  name: "payware_data_generate_report",
+  description: "Generate an asynchronous data report for merchant data analysis and reporting. Production only - not supported in sandbox.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      reportUnitId: {
+        type: "string",
+        description: "The ID of the report to generate",
+        enum: Object.values(REPORT_TYPES),
+        default: REPORT_TYPES.PROCESSED_TRANSACTIONS
+      },
+      dateFrom: {
+        type: "string",
+        description: "Start date for the reporting period (YYYY-MM-DD format). Required for premium reports.",
+        pattern: "^\\d{4}-\\d{2}-\\d{2}$"
+      },
+      dateTo: {
+        type: "string",
+        description: "End date for the reporting period (YYYY-MM-DD format). Required for premium reports.",
+        pattern: "^\\d{4}-\\d{2}-\\d{2}$"
+      },
+      ignorePagination: {
+        type: "boolean",
+        description: "If true, return report as single continuous document. If false, paginate results.",
+        default: false
+      },
+      locale: {
+        type: "string",
+        description: "Locale for the report",
+        enum: Object.values(LOCALES),
+        default: LOCALES.ENGLISH_US
+      },
+      timeZone: {
+        type: "string",
+        description: "Timezone for date calculations (e.g., 'Europe/Sofia', 'America/New_York')",
+        default: "GMT"
+      },
+      partnerId: {
+        type: "string",
+        description: "Partner ID from payware dashboard. Uses PAYWARE_PARTNER_ID env var as default.",
+        default: getPartnerIdSafe()
+      },
+      privateKey: {
+        type: "string",
+        description: "RSA private key for authentication. Uses environment-specific private key as default.",
+        default: getPrivateKeySafe()
+      }
+    },
+    required: ["reportUnitId"]
+  },
+
+  async handler(args) {
+    const {
+      reportUnitId,
+      dateFrom,
+      dateTo,
+      ignorePagination = false,
+      locale = LOCALES.ENGLISH_US,
+      timeZone = 'GMT',
+      partnerId = getPartnerIdSafe(),
+      privateKey = getPrivateKeySafe()
+    } = args;
+
+    if (!partnerId || !privateKey) {
+      throw new Error("Partner ID and private key are required. Set PAYWARE_PARTNER_ID and environment-specific private key variables or provide them as parameters.");
+    }
+
+    // Check for required date range on premium reports
+    const premiumReports = [
+      REPORT_TYPES.PROCESSED_TRANSACTIONS,
+      REPORT_TYPES.SCHEDULES_LIST,
+      REPORT_TYPES.TRANSACTIONS_PER_PRODUCT,
+      REPORT_TYPES.SALES_PER_PRODUCT,
+      REPORT_TYPES.TRANSACTIONS_PER_WEBPOS
+    ];
+
+    if (premiumReports.includes(reportUnitId) && (!dateFrom || !dateTo)) {
+      throw new Error(`Report "${reportUnitId}" requires dateFrom and dateTo parameters (YYYY-MM-DD format)`);
+    }
+
+    try {
+      const result = await generateReport({
+        reportUnitId,
+        dateFrom,
+        dateTo,
+        ignorePagination,
+        locale,
+        timeZone,
+        partnerType: 'merchant',
+        partnerId,
+        privateKey
+      });
+
+      const reportType = Object.keys(REPORT_TYPES).find(key => REPORT_TYPES[key] === reportUnitId) || reportUnitId;
+
+      return {
+        content: [{
+          type: "text",
+          text: `📊 **Data Report Generation Started**
+
+**Report Details:**
+- Type: ${reportType}
+- Report Unit ID: ${reportUnitId}
+- Request ID: ${result.data.requestId}
+- Status: ${result.data.status}
+- Generated: ${result.data.generatedAt}
+
+**Report Parameters:**
+- Date Range: ${dateFrom || 'Default'} to ${dateTo || 'Default'}
+- Timezone: ${timeZone}
+- Locale: ${locale}
+- Pagination: ${ignorePagination ? 'Disabled (single document)' : 'Enabled'}
+
+**Next Steps:**
+1. Save the Request ID: \`${result.data.requestId}\`
+2. Use "Get Report Status" tool to monitor progress
+3. When status is "READY", use "Export Report" tool to get the data
+
+**Available Report Types:**
+- **Standard Reports** (no date range required):
+  - Current Week Transactions: ${REPORT_TYPES.CURRENT_WEEK_TRANSACTIONS}
+  - Current Month Transactions: ${REPORT_TYPES.CURRENT_MONTH_TRANSACTIONS}
+  - Current Year Transactions: ${REPORT_TYPES.CURRENT_YEAR_TRANSACTIONS}
+  - Products List: ${REPORT_TYPES.PRODUCTS_LIST}
+  - Shops List: ${REPORT_TYPES.SHOPS_LIST}
+  - Payment Profiles: ${REPORT_TYPES.PAYMENT_PROFILES}
+  - Partner Profile: ${REPORT_TYPES.PARTNER_PROFILE}
+
+- **Premium Reports** (date range required):
+  - Processed Transactions: ${REPORT_TYPES.PROCESSED_TRANSACTIONS}
+  - Schedules List: ${REPORT_TYPES.SCHEDULES_LIST}
+  - Transactions per Product: ${REPORT_TYPES.TRANSACTIONS_PER_PRODUCT}
+  - Sales per Product: ${REPORT_TYPES.SALES_PER_PRODUCT}
+  - Transactions per WebPOS: ${REPORT_TYPES.TRANSACTIONS_PER_WEBPOS}
+
+**⚠️ Production Only:**
+This feature is only available in the production environment, not in sandbox.`
+        }]
+      };
+    } catch (error) {
+      throw new Error(`Failed to generate report: ${error.message}`);
+    }
+  }
+};

package/src/merchant/data/get-report-status.js

@@ -0,0 +1,120 @@
+import { getReportStatus } from '../../shared/data/data-api.js';
+import { getPartnerIdSafe, getPrivateKeySafe } from '../../config/env.js';
+
+/**
+ * Get report status tool for merchants
+ */
+export const getReportStatusTool = {
+  name: "payware_data_get_report_status",
+  description: "Get the status of an asynchronous report generation request. Use this to monitor report progress.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      requestId: {
+        type: "string",
+        description: "The request ID returned from the report generation request (UUID format)"
+      },
+      partnerId: {
+        type: "string",
+        description: "Partner ID from payware dashboard. Uses PAYWARE_PARTNER_ID env var as default.",
+        default: getPartnerIdSafe()
+      },
+      privateKey: {
+        type: "string",
+        description: "RSA private key for authentication. Uses environment-specific private key as default.",
+        default: getPrivateKeySafe()
+      }
+    },
+    required: ["requestId"]
+  },
+
+  async handler(args) {
+    const {
+      requestId,
+      partnerId = getPartnerIdSafe(),
+      privateKey = getPrivateKeySafe()
+    } = args;
+
+    if (!partnerId || !privateKey) {
+      throw new Error("Partner ID and private key are required. Set PAYWARE_PARTNER_ID and environment-specific private key variables or provide them as parameters.");
+    }
+
+    try {
+      const result = await getReportStatus({
+        requestId,
+        partnerType: 'merchant',
+        partnerId,
+        privateKey
+      });
+
+      const data = result.data;
+      const statusEmoji = {
+        'QUEUED': '⏳',
+        'READY': '✅',
+        'CANCELLED': '❌',
+        'FAILED': '💥'
+      };
+
+      let nextSteps = '';
+      if (data.status === 'READY') {
+        nextSteps = `
+**🎉 Report is Ready!**
+Use the "Export Report" tool with request ID: \`${requestId}\`
+Available formats: PDF, CSV, Excel, JSON`;
+      } else if (data.status === 'QUEUED') {
+        nextSteps = `
+**⏳ Report is Processing**
+Check status again in a few moments using the same request ID.`;
+      } else if (data.status === 'FAILED') {
+        nextSteps = `
+**💥 Report Failed**
+You may need to generate a new report with different parameters.`;
+      } else if (data.status === 'CANCELLED') {
+        nextSteps = `
+**❌ Report was Cancelled**
+Generate a new report if needed.`;
+      }
+
+      let outputResourcesInfo = '';
+      if (data.outputResources && data.outputResources.length > 0) {
+        outputResourcesInfo = `
+**Export Resources:**
+${data.outputResources.map(resource =>
+  `- Export ID: ${resource.exportId}
+  - Format: ${resource.contentType}
+  - Status: ${statusEmoji[resource.status] || '❓'} ${resource.status}
+  - Pages: ${resource.pages || 'N/A'}
+  - Completed: ${resource.outputFinal ? 'Yes' : 'No'}`
+).join('\n')}`;
+      }
+
+      return {
+        content: [{
+          type: "text",
+          text: `📊 **Report Status Check**
+
+**Report Information:**
+- Request ID: ${data.requestId}
+- Report Type: ${data.reportUnitId}
+- Status: ${statusEmoji[data.status] || '❓'} ${data.status}
+- Generated: ${data.generatedAt}
+
+**Report Parameters:**
+- Date Range: ${data.dateFrom || 'Default'} to ${data.dateTo || 'Default'}
+- Timezone: ${data.timeZone}
+- Pagination: ${data.ignorePagination ? 'Disabled' : 'Enabled'}
+${outputResourcesInfo}
+${nextSteps}
+
+**Status Meanings:**
+- 🟡 **QUEUED**: Report is waiting to be processed
+- ✅ **READY**: Report completed and available for export
+- ❌ **CANCELLED**: Report was cancelled by user
+- 💥 **FAILED**: Error occurred during report generation`
+        }]
+      };
+    } catch (error) {
+      throw new Error(`Failed to get report status: ${error.message}`);
+    }
+  }
+};