skipify-mcp-server by nick-suess-skipify - MCP Server

🚀 Skipify MCP (Merchant Control Panel) Server

A comprehensive development server and testing environment for integrating Skipify Checkout embedded components. This MCP helps customers install, configure, and test Skipify's checkout solution in a staging environment.

🎯 Overview

This MCP server provides:

Step-by-step guidance for Skipify embedded components integration
Local development environment with CORS and SSL handling
Interactive test page for complete integration flow testing
Secure credential management with environment variables
Direct API communication with Skipify's staging environment

Integration Flow Supported

Configuration Setup - API keys and merchant ID
SDK Loading - Dynamic Skipify SDK initialization
Shopper Lookup - Customer authentication check
Authentication Component - Identity verification UI
Payment Carousel - Payment method selection
Payment Processing - Transaction submission to Skipify

⚡ Quick Start

1. Start the Server

cd /path/to/demo-project
node direct-server.js

2. Open Test Page

In your browser, navigate to:

http://localhost:3000/skipify-test.html

3. Test Integration

Follow the 6-step process in the test page to validate your Skipify integration.

📁 File Structure

demo-project/
├── README.md                  # This documentation
├── direct-server.js          # ✅ RECOMMENDED: Direct API server (working)
├── simple-proxy.js           # Alternative: Simple proxy server
├── skipify-proxy.js          # Alternative: Full-featured proxy with security
├── skipify-test.html         # Interactive test page for integration
├── package.json              # Node.js dependencies and scripts
├── package-lock.json         # Dependency lock file
├── .gitignore                # Git ignore rules for security
├── SECURITY.md               # Comprehensive security guide
├── setup-secure-env.js       # Interactive credential setup script
├── env-example.txt           # Environment variable template
├── .env.local                # ⚠️ YOUR SECURE CREDENTIALS (gitignored)
└── config/
    └── skipify.js            # Configuration with environment variable support

Key Files Explained

🎯 `direct-server.js` (RECOMMENDED)

Primary server file that works reliably
Makes direct HTTPS requests to Skipify API
Bypasses proxy middleware complexity
Includes comprehensive error handling and logging
Serves static files and test page

🧪 `skipify-test.html`

Interactive test interface for the complete integration flow
Guides users through all 6 steps of Skipify integration
Real-time status updates and error reporting
Persists configuration in localStorage

🔒 Security Files

.env.local: Your actual API credentials (never committed)
SECURITY.md: Comprehensive security best practices
.gitignore: Protects sensitive files from version control
setup-secure-env.js: Interactive secure credential setup

⚙️ Configuration

config/skipify.js: Environment-aware configuration
package.json: Dependencies and useful npm scripts

🛠️ Setup Methods

Method 1: Quick Setup (Recommended)

Install Dependencies
```
npm install
```

Update Credentials in direct-server.js Edit lines 9-13 with your actual credentials:

const config = {
  apiUrl: 'https://services.staging.skipify.com',
  merchantId: 'your-merchant-id-here',
  apiKey: 'your-api-key-here'
};

Start Server
```
node direct-server.js
```

Method 2: Secure Environment Setup

Install Dependencies
```
npm install
```
Run Secure Setup
```
npm run setup
```
This will interactively prompt for your credentials and create a secure .env.local file.

Start Secure Server

npm start  # Uses skipify-proxy.js with environment variables

🧪 Testing the Integration

Access the Test Page

Start the server using either method above
Open your browser to: http://localhost:3000/skipify-test.html
Follow the 6-step process:

Step 1: Save Configuration

Enter your API credentials
Select staging environment
Configuration persists in browser localStorage

Step 2: Load SDK

Dynamically loads Skipify's JavaScript SDK
Initializes with your merchant ID and environment

Step 3: Perform Lookup

Tests customer authentication/lookup
Validates API connectivity

Step 4: Initialize Authentication

Renders Skipify's authentication component
Handles identity verification flow

Step 5: Initialize Payment Carousel

Displays available payment methods
Allows payment method selection

Step 6: Process Payment

Submits transaction to Skipify API
Shows real-time processing results

Expected Results

✅ Steps 1-5: Should complete successfully with proper configuration
✅ Step 6: Should show API communication (may show validation errors with test data, which is normal)

🔒 Security

Credential Protection

Never commit API keys to version control
Use environment variables for production
Enable .gitignore to protect sensitive files
Rotate API keys regularly

Files to Protect

.env.local - Your actual credentials
.env.* - Any environment files
**/credentials/* - Credential directories

Security Best Practices

See SECURITY.md for comprehensive security guidelines including:

Environment variable setup
Production deployment security
Emergency response procedures
Credential rotation practices

🐛 Troubleshooting

Common Issues

"Socket hang up" errors

Solution: Use direct-server.js instead of proxy-based servers

node direct-server.js  # ✅ Recommended approach

404 errors accessing test page

Solution: Ensure you're accessing the correct URL

✅ http://localhost:3000/skipify-test.html
❌ http://localhost:8080/skipify-test.html

"Missing script: start" errors

Solution: Run commands from the correct directory

cd /path/to/demo-project  # Must be in demo-project directory
node direct-server.js

API authentication errors (401/403)

Solution: Verify your credentials in the configuration

Check API key format: SKIP_...
Verify merchant ID is correct
Ensure you're using staging environment credentials

SSL/Certificate errors

Solution: The direct-server.js handles this with rejectUnauthorized: false

Debug Logs

The server provides detailed logging:

✅ Request/Response logging for API calls
✅ Credential masking for security (shows SKIP_***We5%)
✅ Error details with stack traces
✅ Step-by-step flow tracking

🌍 Production Deployment

Environment Variables

For production deployment, set these environment variables:

SKIPIFY_ENVIRONMENT=production
SKIPIFY_MERCHANT_ID=your_production_merchant_id
SKIPIFY_API_KEY=your_production_api_key
SKIPIFY_API_URL=https://services.skipify.com
SKIPIFY_SDK_URL=https://cdn.skipify.com/sdk/components-sdk.js

Production Checklist

Use production API endpoints
Set production credentials
Enable SSL certificate verification (secure: true)
Set up proper error monitoring
Configure rate limiting
Set up health check monitoring
Enable access logging
Configure firewall rules

Docker Deployment

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
EXPOSE 3000
CMD ["node", "direct-server.js"]

📚 API Reference

Health Check

GET /health
Response: {
  "status": "OK",
  "environment": "staging",
  "apiUrl": "https://services.staging.skipify.com",
  "timestamp": "2025-09-03T21:14:46.935Z"
}

Payment Processing

POST /api/payments
Headers:
  Content-Type: application/json
Body: {
  "paymentId": "string",
  "sessionId": "string",
  "amount": number,
  "currencyCode": "string",
  "merchantReference": "string"
}

Static Files

GET /skipify-test.html    # Main test interface
GET /config/skipify.js    # Configuration file
GET /*                    # All static files served

📞 Support

Getting Help

Check troubleshooting section above for common issues
Review server logs for detailed error information
Test with curl to isolate API vs. UI issues:
```
curl -v http://localhost:3000/health
```
Verify credentials in Skipify merchant portal

Development Tools

Browser DevTools: Check console for JavaScript errors
Network Tab: Monitor API requests and responses
Server Logs: Real-time debugging information
Test Page: Built-in status indicators and error reporting

🎉 Success Indicators

Your integration is working when:

✅ Health check returns 200 OK
✅ SDK loads without errors
✅ Authentication component renders
✅ Payment carousel displays
✅ API requests return valid responses (even validation errors are good!)

📝 Notes

Staging Environment: Uses https://services.staging.skipify.com
SSL Handling: Configured for staging environment certificates
CORS: Enabled for localhost development
Idempotency: Automatic UUID generation for payment requests

Built with ❤️ for seamless Skipify integration testing