ScanPower MCP Server

A Model Context Protocol (MCP) server implementation for the ScanPower API, built with Next.js, TypeScript, and Tailwind CSS. This server provides a secure, logged, and configurable interface to interact with ScanPower's inventory and shipment management system.

Features

• ✅ HTTPS Support - Secure server with configurable SSL/TLS certificates

• ✅ Request Logging - Comprehensive logging of all API requests and responses

• ✅ TypeScript - Full type safety with TypeScript implementation

• ✅ Tailwind CSS - Modern, responsive UI for monitoring and documentation

• ✅ MCP Protocol - Complete implementation of the Model Context Protocol

• ✅ Configurable - Environment-based configuration for flexibility

• ✅ Next.js App Router - Modern React framework with server components

Architecture

The server implements the Model Context Protocol (MCP), which provides:

• Tools: Execute operations like inventory retrieval and shipment creation

• Resources: Access to inventory and shipment data

• Prompts: Pre-configured prompts for common tasks

Prerequisites

• Node.js 18.x or higher

• npm or yarn

• OpenSSL (for generating SSL certificates)

Installation

1. Clone the repository:

2. Install dependencies:

3. Create a .env file (copy from .env.example):

4. Configure your environment variables in .env:

5. Generate SSL certificates (for HTTPS):

Usage

Development Mode

Start the development server with hot-reload:

The server will be available at:

• HTTP: http://localhost:3000

• HTTPS: https://localhost:3000 (if HTTPS_ENABLED=true and certificates are present)

Production Mode

Build and start the production server:

API Endpoints

Health Check

Returns server status and configuration information.

MCP Protocol Endpoint

Main endpoint for MCP protocol communication. Accepts JSON-RPC 2.0 formatted requests.

Example MCP Request:

Available MCP Methods:

• initialize - Initialize MCP session

• tools/list - List available tools

• tools/call - Execute a tool

• resources/list - List available resources

• prompts/list - List available prompts

Available Tools

get_inventory

Retrieve inventory items from ScanPower.

Parameters:

• sku (string, optional): Filter by SKU

• limit (number, optional): Maximum items to return (default: 100)

create_shipment

Create a new shipment plan.

Parameters:

• name (string, required): Shipment plan name

• items (array, required): Array of items with sku and quantity

get_shipments

Retrieve shipment plans.

Parameters:

• status (string, optional): Filter by status (pending, processing, shipped, completed)

Configuration

Environment Variables

SSL Certificates

For development, you can generate self-signed certificates:

This will create:

• ssl/server.key - Private key

• ssl/server.cert - Self-signed certificate

Note: Self-signed certificates will trigger browser security warnings. For production, use certificates from a trusted Certificate Authority.

Project Structure

Development

Linting

Building

Logging

All HTTP requests are automatically logged with the following information:

• Timestamp

• HTTP method

• Request path

• Status code

• Response time

• User agent

• IP address

Logs are output in JSON format to stdout and can be easily integrated with log aggregation services.

License

ISC

Support

For issues or questions:

• GitHub Issues: https://github.com/scanpower/scanmcp/issues

• ScanPower API Documentation: https://api.scanpower.com/docs/api/index.html

• MCP Protocol Documentation: https://modelcontextprotocol.io