Partner-MCP-Server

bianca-sanchez-fattmerchant/Partner-MCP-Server

3.2

If you are the rightful owner of Partner-MCP-Server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

Stax Partner MCP Server is a production-grade Model Context Protocol server designed to support Stax payment processing partners with efficient access to merchant data and transaction management.

Tools
4
Resources
0
Prompts
0

Stax Partner MCP Server

A production-grade Model Context Protocol (MCP) server for Stax payment processing partner support. This server provides token-optimized, fast-response tools for common support tasks, helping partner support representatives efficiently access merchant data, transaction information, and manage portfolios.

🚀 Quick Start

Prerequisites

  • Node.js 18+
  • Stax API key with partner permissions
  • MCP-compatible client (Claude Desktop, etc.)

Installation

# 1. Clone and install
git clone https://github.com/your-org/stax-partner-mcp-server.git
cd stax-partner-mcp-server
npm install && npm run build

# 2. Configure API key
cp config.json.template config.json
# Edit config.json and add your Stax API key

# 3. Verify setup
npm run health-check

# 4. Setup Claude Desktop (auto-configures)
npm run setup-claude

That's it! Restart Claude Desktop and you're ready to go.

📖 Need detailed setup? See for platform-specific instructions.

✨ Features

  • 6 Essential Tools for partner support workflows
  • Token-Optimized Responses (typically <500 tokens)
  • Smart Caching with 70%+ hit rate for common queries
  • Production-Grade Error Handling with helpful messages
  • Request Batching and deduplication for performance
  • Secure Authentication with Stax API keys
  • TypeScript for type safety and better development experience
  • Flexible Configuration via config file or environment variables

🛠️ Available Tools

The server provides 6 essential tools for partner support:

1. Merchant Management

  • get_merchant - Basic info and health status
  • get_application_status - Underwriting progress and blockers
  • list_portfolio_merchants - Portfolio overview with filtering

2. Transaction Analysis

  • list_recent_transactions - Recent transaction history with filtering

3. Financial Tools

  • fee_statement_analysis - Comprehensive fee breakdown and volume analysis

4. Dispute Management

  • list_active_disputes - Active disputes with urgency tracking

Each tool returns token-optimized responses with essential data first and details on demand.

📋 Configuration

Simple Setup (Recommended)

{
  "stax_api_key": "your-stax-api-key-here"
}

Advanced Configuration

{
  "stax_api_key": "your-api-key",
  "api_settings": {
    "timeout": 8000,
    "max_retries": 2
  },
  "caching": {
    "enabled": true,
    "ttl_seconds": 180
  },
  "logging": {
    "level": "info"
  }
}

Environment Variables: You can also use STAX_API_KEY environment variable instead of config.json

🔗 Claude Desktop Integration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "stax-partner": {
      "command": "node",
      "args": ["/path/to/stax-partner-mcp-server/dist/index.js"]
    }
  }
}

Config file locations:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

🧪 Development

npm run dev         # Development with auto-reload
npm run build       # Build TypeScript
npm run test        # Run test suite
npm run lint        # Check code style
npm run health-check # Verify setup

📚 Documentation

  • 🛠️ - Platform-specific setup details
  • 📖 - Usage examples and configurations
  • 🏗️ API Documentation - Complete tool reference

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes with tests
  4. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

Token Optimization Strategy

Response Design

  • Concise summaries: 30-50 tokens
  • Essential data first: Core info in 100-200 tokens
  • Details on demand: Use include_details flags
  • Smart truncation: Limit lists, show "and X more"

Caching Strategy

  • Merchant info: 5-minute cache (infrequent changes)
  • Transactions: 1-minute cache (frequent changes)
  • Deposits: 3-minute cache (daily settlement)
  • Portfolio: 2-minute cache (overview queries)

Performance Features

  • Request batching: Identical requests share responses
  • Parallel fetching: Multiple API calls when needed
  • Compression: Large responses are compressed
  • Rate limiting: Prevents API quota exhaustion

Error Handling

The server provides helpful, actionable error messages:

  • Merchant not found: Shows ID format help and suggests portfolio listing
  • Authentication failed: Explains credential setup and permissions
  • Rate limited: Suggests wait time and optimization tips
  • Invalid parameters: Shows valid ranges and examples
  • API errors: Provides troubleshooting guidance

Development

Project Structure

src/
├── config.ts              # Configuration management
├── index.ts               # Entry point
├── server.ts              # Main MCP server
├── services/              # Core services
│   ├── authManager.ts     # Authentication handling
│   ├── apiClient.ts       # Optimized Stax API client  
│   ├── cache.ts           # Token-aware caching
│   └── toolRegistry.ts    # Tool registration & execution
├── tools/                 # Tool implementations
│   ├── merchantTools.ts   # Merchant information tools
│   ├── transactionTools.ts # Transaction tools
│   ├── financialTools.ts  # Financial tools
│   └── disputeTools.ts    # Dispute & portfolio tools
├── types/                 # TypeScript type definitions
│   ├── config.ts          # Configuration types
│   ├── merchant.ts        # Merchant-related types
│   ├── transactions.ts    # Transaction types
│   ├── financial.ts       # Financial types
│   ├── disputes.ts        # Dispute types
│   └── index.ts           # Type exports
└── utils/                 # Utility classes
    ├── errorHandler.ts    # Production error handling
    ├── formatter.ts       # Token-optimized formatting
    └── logger.ts          # Structured logging

Scripts

npm run build       # Build TypeScript
npm run start       # Start production server
npm run dev         # Development with auto-reload
npm run test        # Run test suite
npm run lint        # Check code style
npm run lint:fix    # Fix linting issues
npm run type-check  # TypeScript type checking

Testing

# Run all tests
npm test

# Run with coverage
npm run test -- --coverage

# Watch mode for development
npm run test -- --watch

Performance Metrics

Target performance indicators:

  • Token Efficiency: <500 tokens per typical response
  • Response Time: <2s cached, <5s API calls
  • Cache Hit Rate: >70% for merchant/portfolio queries
  • Error Rate: <1% for valid requests
  • API Rate Limit: 120 RPM (2 req/second) with burst allowance

Security

  • API Key Security: Credentials stored in environment variables
  • Request Validation: All inputs validated and sanitized
  • Error Sanitization: No sensitive data in error messages
  • Rate Limiting: Prevents abuse and quota exhaustion
  • Logging: Structured logs without sensitive information

Production Deployment

Docker Support

Create a Dockerfile:

FROM node:18-alpine

WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

COPY dist ./dist
EXPOSE 3000

USER node
CMD ["node", "dist/index.js"]

Environment Setup

# Production configuration
export NODE_ENV="production"
export LOG_LEVEL="info"
export ENABLE_METRICS="true"

# Stax API credentials (secure)
export STAX_API_KEY="$(cat /run/secrets/stax_api_key)"

# Performance tuning
export CACHE_MAX_ENTRIES="2000"
export PARTNER_RATE_LIMIT_RPM="200"

MCP Client Configuration

Add to your MCP client configuration:

{
  "mcpServers": {
    "stax-partner": {
      "command": "node",
      "args": ["/path/to/stax-partner-mcp-server/dist/index.js"],
      "env": {
        "STAX_API_KEY": "your-api-key"
      }
    }
  }
}

Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes with tests
  4. Ensure code passes linting and tests
  5. Commit changes (git commit -m 'Add amazing feature')
  6. Push to branch (git push origin feature/amazing-feature)
  7. Open a Pull Request

Support

  • Issues: Report bugs and feature requests via GitHub Issues
  • Documentation: Check the /docs folder for detailed guides
  • API Reference: See the Stax API documentation
  • MCP Protocol: Visit the Model Context Protocol specification

License

MIT License - see LICENSE file for details.

Changelog

v1.0.0

  • Initial release with 8 essential tools
  • Token-optimized response formatting
  • Production-grade error handling
  • Smart caching and request batching
  • Comprehensive test suite