@hktv/mms-mcp

MCP (Model Context Protocol) server for the MMS (HKTVmall Merchant Management System) OpenAPI.

Lets merchants interact with MMS API docs directly from AI hosts — Claude Code, Claude Desktop, Codex, Cursor, and any other MCP-compatible host.

Requirements

• Java 21+ on your PATH (Download)
• Node.js 18+ (for npx)

Installation

No install needed — just configure your AI host:

// claude_desktop_config.json  or  .mcp.json in your project
{
  "mcpServers": {
    "mms": {
      "command": "npx",
      "args": ["-y", "@hktv/mms-mcp"]
    }
  }
}

With API call capability (to actually call MMS APIs)

{
  "mcpServers": {
    "mms": {
      "command": "npx",
      "args": ["-y", "@hktv/mms-mcp"],
      "env": {
        "MMS_STORE_CODE": "your-merchant-name",
        "MMS_API_KEY": "your-uuid-from-mms-system",
        "MMS_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
        "MMS_ENV": "production"
      }
    }
  }
}

JWT is generated automatically from your private key using RS256.
The token includes sub, name, iat, x-api-key claims and is sent as x-auth-token header.
It refreshes on every call (MMS validates by iat freshness within a 30-minute window).

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | MMS_STORE_CODE | Yes* | Merchant name used as JWT sub + name claim | | MMS_API_KEY | Yes* | UUID from MMS system (x-api-key JWT claim) | | MMS_PRIVATE_KEY | Yes* | RSA private key in PKCS#8 PEM format | | MMS_JWT_TOKEN | No | Pre-built JWT (bypasses key generation) | | MMS_ENV | No | production / staging / dev (default: production) | | MMS_API_BASE_URL | No | Override base URL entirely | | MMS_SPEC_URL | No | Custom OpenAPI spec URL |

* Required only when using call_api tool

Available Tools

| Tool | Description | |------|-------------| | list_api_categories | List all API categories with operation counts | | list_api_operations | List all operations in a category | | get_api_operation | Get full schema & docs for an operation | | search_apis | Full-text search across all operations | | validate_request | Validate a request payload against the spec | | validate_response | Validate a response payload against the spec | | call_api | Actually call a MMS API endpoint with JWT auth |

Example Usage (via Claude Code)

# Browse APIs
> list_api_categories
> list_api_operations category="Order"
> get_api_operation operationId="getOrderList"

# Call the API directly
> call_api operationId="getOrderList" queryParamsJson={"shopCode":"SHOP01","page":"1"}

# Validate before calling
> validate_request operationId="createProduct" payloadJson="{\"name\":\"My Product\"}"

Development

Prerequisites

• Java 21+
• Maven 3.8+
• Node.js 18+ (for the scraper script)

Build

# 1. (Optional) Fetch the latest MMS spec from developers.shoalter.com
npm install puppeteer
node scripts/fetch-spec.js

# 2. Build the fat JAR (also copies to npm/jars/)
mvn clean package -DskipTests

# 3. Test locally
java -jar target/mms-mcp.jar

Project Structure

mms-openapi-mcp/
├── pom.xml                             # Maven build
├── src/main/java/com/hktv/mms/mcp/
│   ├── MmsMcpApplication.java          # Spring Boot entry point
│   ├── config/McpServerConfig.java     # Register all MCP tools
│   ├── service/
│   │   ├── SpecLoaderService.java      # Load & parse OpenAPI spec
│   │   └── ValidatorService.java       # JSON Schema validation
│   ├── tools/                          # MCP tool implementations
│   │   ├── ListCategoriesTools.java
│   │   ├── ListOperationsTools.java
│   │   ├── GetOperationTools.java
│   │   ├── SearchApisTools.java
│   │   ├── ValidateRequestTools.java
│   │   └── ValidateResponseTools.java
│   └── model/                          # Data classes
├── src/main/resources/
│   ├── application.yml
│   └── specs/mms-openapi.json          # Bundled spec (update via fetch-spec.js)
├── npm/                                # npm wrapper package
│   ├── package.json
│   ├── index.js                        # Launcher: java -jar mms-mcp.jar
│   ├── jars/mms-mcp.jar               # Built JAR (copied by Maven)
│   └── scripts/check-java.js
└── scripts/
    └── fetch-spec.js                   # Puppeteer scraper for MMS docs

Publishing

# After mvn package (which copies JAR to npm/jars/)
cd npm
npm publish --access public