Maxio MCP Implementation

This repository contains a robust Docker-based solution for the Maxio Model Context Protocol (MCP). This approach leverages Smithy for API modeling and code generation.

Quick Start Guide (One Line Install)

The easiest way to install and run the Maxio MCP is to use our one-line install command:

curl -s https://raw.githubusercontent.com/banner-dev/maxio-mcp/main/install.sh | bash

This script will:

1. Pull the latest Maxio MCP image
2. Handle any existing containers
3. Set up everything for Claude to automatically start/stop the container

Alternative Installation (Fixed Version)

If you experience issues with the standard installation, you can use our fixed version with enhanced stability:

curl -s https://raw.githubusercontent.com/banner-dev/maxio-mcp/main/build-fixed.sh | bash

This will:

1. Build a custom Docker image with all dependencies properly installed
2. Start the container with the fixed configuration
3. Ensure netcat and other required tools are available

Authentication Setup

First, generate the necessary authentication token from Maxio:

1. Go to your Maxio admin portal
2. Navigate to Settings → API Keys
3. Create a new API token, name it
4. Copy the token immediately

Manual Installation

If you prefer to install manually, you can use these commands:

# Pull Pre-built Image
docker pull ghcr.io/banner-dev/maxio-mcp:latest

# Run with your Maxio credentials
docker run -d --name maxio-mcp -p 3000:3000 \
  -e MAXIO_BASE_URL="https://your-instance.saasoptics.com" \
  -e MAXIO_API_TOKEN="your-api-token-here" \
  --restart unless-stopped \
  ghcr.io/banner-dev/maxio-mcp:latest

Verify Installation

Verify that the MCP container is running properly:

# Check container status
docker ps | grep maxio-mcp

# View container logs
docker logs maxio-mcp

# Test the health endpoint
curl http://localhost:3000/health

The health endpoint should return a JSON response with status "healthy".

Connect to Claude

In Claude, set up the MCP connection:

1. URL: http://localhost:3000/mcp-endpoint
2. Authentication: Bearer Token
3. Token: Your Maxio API token (same as MAXIO_API_TOKEN)

Architecture Overview

The Maxio MCP implementation follows Atlassian's best practices:

1. Smithy-based API Modeling:

   • Defines API contracts using Smithy IDL
   • Generates type-safe clients and server scaffolding

2. Docker Multi-stage Build:

   • Optimized for small image size
   • Follows security best practices
   • No external dependencies required

Development Setup

For developers who want to modify the MCP:

1. Clone this repository:

   git clone https://github.com/banner-dev/maxio-mcp.git
   cd maxio-mcp
   

2. Install dependencies:

   npm install
   

3. Build and start locally:

   npm run build
   npm start
   

Configuration Options

Environment Variable	Description	Default
MAXIO_BASE_URL	Your Maxio/SaaSOatics instance URL	https://your-instance.saasoptics.com
MAXIO_API_TOKEN	Your Maxio API token	your-api-token-here
PORT	Port to expose the MCP service	3000
AUTO_SHUTDOWN	Enable automatic shutdown after idle period	true
IDLE_TIMEOUT	Minutes of inactivity before auto-shutdown	30
MCP_LOG_LEVEL	Logging level (debug, info, warn, error)	info

Features

This MCP provides access to the following Maxio resources:

• Customers: Create, retrieve, update and manage customer records
• Contracts: Manage contracts associated with customers
• Transactions: Create and manage subscription transactions
• Invoices: Generate and manage invoices and line items
• Payments: Record and track payments against invoices
• Items: Access product and service catalog items
• Revenue: Retrieve and analyze revenue entries

Troubleshooting

• Connection issues: Ensure your Docker container has network access
• Authentication errors: Verify your API token is valid
• Port conflict: If port 3000 is already in use, change the port mapping:

  docker run -d --name maxio-mcp -p 8080:3000 ...
  

  Then use http://localhost:8080/mcp-endpoint as the MCP URL.
• Container fails to start: Check Docker logs using docker logs maxio-mcp

Common Issues

• Netcat dependency errors: If you see errors like /lifecycle.sh: line 78: nc: command not found, use our fixed version by running the build-fixed.sh script above, which includes netcat and other dependencies.

Container Health Checks

The container includes automated health checks that will:

• Monitor the Node.js server process
• Auto-restart if the service fails
• Perform regular connectivity tests using curl or netcat
• Support Docker's built-in HEALTHCHECK

Recent Improvements

• 2025-04-25: Added fixed Dockerfile and build script to resolve netcat dependency issues.
• 2025-04-25: Removed netcat dependency from standard Dockerfile. The health check system now uses curl instead of netcat, eliminating the "nc: command not found" errors.
• 2025-04-23: Updated to latest Smithy version 1.29.0 for improved API modeling.

Auto-integration with Claude

The MCP container is designed to:

1. Automatically start when Claude is launched
2. Automatically shut down when Claude is closed
3. Maintain data integrity throughout your Claude session

License

This project is licensed under the MIT License - see the LICENSE file for details.