README.md•6 kB
# 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)](https://modelcontextprotocol.io), 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:
```bash
git clone https://github.com/scanpower/scanmcp.git
cd scanmcp
```
2. Install dependencies:
```bash
npm install
```
3. Create a `.env` file (copy from `.env.example`):
```bash
cp .env.example .env
```
4. Configure your environment variables in `.env`:
```env
PORT=3000
NODE_ENV=development
HTTPS_ENABLED=true
SSL_KEY_PATH=./ssl/server.key
SSL_CERT_PATH=./ssl/server.cert
API_KEY=your_scanpower_api_key_here
```
5. Generate SSL certificates (for HTTPS):
```bash
npm run generate-cert
```
## Usage
### Development Mode
Start the development server with hot-reload:
```bash
npm run dev
```
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:
```bash
npm run build
npm start
```
## API Endpoints
### Health Check
```
GET /api/health
```
Returns server status and configuration information.
### MCP Protocol Endpoint
```
POST /api/mcp
```
Main endpoint for MCP protocol communication. Accepts JSON-RPC 2.0 formatted requests.
#### Example MCP Request:
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list"
}
```
#### 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
| Variable | Description | Default |
|----------|-------------|---------|
| `PORT` | Server port | `3000` |
| `NODE_ENV` | Environment mode | `development` |
| `HTTPS_ENABLED` | Enable HTTPS | `true` |
| `SSL_KEY_PATH` | Path to SSL key | `./ssl/server.key` |
| `SSL_CERT_PATH` | Path to SSL certificate | `./ssl/server.cert` |
| `API_BASE_URL` | ScanPower API base URL | `https://api.scanpower.com` |
| `API_KEY` | ScanPower API key | - |
| `LOG_LEVEL` | Logging level | `info` |
| `LOG_REQUESTS` | Enable request logging | `true` |
## SSL Certificates
For development, you can generate self-signed certificates:
```bash
npm run generate-cert
```
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
```
scanmcp/
├── app/ # Next.js app directory
│ ├── api/ # API routes
│ │ ├── health/ # Health check endpoint
│ │ └── mcp/ # MCP protocol endpoint
│ ├── globals.css # Global styles
│ ├── layout.tsx # Root layout
│ └── page.tsx # Home page
├── lib/ # Shared libraries
│ ├── logger.ts # Logging utilities
│ └── types.ts # TypeScript types
├── scripts/ # Utility scripts
│ └── generate-cert.sh # SSL certificate generation
├── middleware.ts # Request logging middleware
├── server.js # Custom HTTPS server
├── next.config.js # Next.js configuration
├── tailwind.config.ts # Tailwind CSS configuration
├── tsconfig.json # TypeScript configuration
└── package.json # Project dependencies
```
## Development
### Linting
```bash
npm run lint
```
### Building
```bash
npm run build
```
## 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](https://github.com/scanpower/scanmcp/issues)
- ScanPower API Documentation: [https://api.scanpower.com/docs/api/index.html](https://api.scanpower.com/docs/api/index.html)
- MCP Protocol Documentation: [https://modelcontextprotocol.io](https://modelcontextprotocol.io)