@kubova/mcp 0.1.0

package/README.md

@@ -0,0 +1,94 @@
+# @kubova/mcp
+
+Model Context Protocol server for the [Kubova](https://kubova-web-next.vercel.app) container loading calculator.
+
+Lets Claude, Cursor, Cline, ChatGPT, n8n, and any other MCP-aware AI agent pack shipping containers as a tool call.
+
+## Install
+
+```bash
+# Get an API key first at
+#   https://kubova-web-next.vercel.app/dashboard/api-keys
+# (Pro plan; 14-day trial available.)
+```
+
+## Configure
+
+### Claude Code / Claude Desktop
+
+Add to `~/.claude/settings.json` (or the Claude Desktop config file):
+
+```json
+{
+  "mcpServers": {
+    "kubova": {
+      "command": "npx",
+      "args": ["-y", "@kubova/mcp@latest"],
+      "env": {
+        "KUBOVA_API_KEY": "kbv_..."
+      }
+    }
+  }
+}
+```
+
+### Cursor / Cline / Codex
+
+Same JSON shape — point your MCP-aware client at the package via `npx`.
+
+## Tools exposed
+
+| Tool | Purpose |
+|---|---|
+| `pack_containers` | Pack a list of cargo SKUs into one or more shipping containers. Returns placements, utilization, weight, and any unplaced pieces. |
+| `verify_key` | Sanity-check the configured API key. Returns identity, scopes, and rate limit. |
+
+## Input schema (pack_containers)
+
+```ts
+{
+  cargos: [
+    {
+      id: string,
+      name: string,
+      shape?: "box" | "cylinder",
+      lengthCm: number,
+      widthCm: number,
+      heightCm: number,
+      quantity: number,
+      weightKg: number,
+      color?: string,
+      includeInLoading?: boolean,
+      allowStacking?: boolean,
+      allowRotation?: boolean
+    }
+  ],
+  container?: {
+    id: string,
+    name: string,
+    innerLengthCm: number,
+    innerWidthCm: number,
+    innerHeightCm: number,
+    doorWidthCm: number,
+    doorHeightCm: number,
+    maxPayloadKg: number
+  },
+  containers?: [ /* multiple types — packer picks best mix */ ],
+  options?: {
+    loadingDirection?: "floor-to-top" | "right-to-left",
+    maxContainers?: number,
+    vnsTimeLimitMs?: number
+  }
+}
+```
+
+## Env
+
+| Variable | Default | Notes |
+|---|---|---|
+| `KUBOVA_API_KEY` | — | **Required.** Generated from the dashboard. |
+| `KUBOVA_API_URL` | `https://kubova-web-next.vercel.app` | Override if self-hosting Kubova. |
+
+## License
+
+MIT.

package/dist/index.js

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+/**
+ * Kubova MCP server.
+ *
+ * Exposes the Kubova container loading calculator as an MCP server so
+ * Claude, Cursor, Cline, ChatGPT, n8n, and any other MCP-aware AI agent
+ * can pack containers as a tool call.
+ *
+ * Usage in Claude Code / Cursor settings:
+ *
+ *   {
+ *     "mcpServers": {
+ *       "kubova": {
+ *         "command": "npx",
+ *         "args": ["-y", "@kubova/mcp@latest"],
+ *         "env": { "KUBOVA_API_KEY": "kbv_..." }
+ *       }
+ *     }
+ *   }
+ *
+ * Env:
+ *   KUBOVA_API_KEY  (required) — get one at https://kubova-web-next.vercel.app/dashboard/api-keys
+ *   KUBOVA_API_URL  (optional) — defaults to https://kubova-web-next.vercel.app
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+const API_URL = process.env.KUBOVA_API_URL ?? 'https://kubova-web-next.vercel.app';
+const API_KEY = process.env.KUBOVA_API_KEY;
+if (!API_KEY) {
+    // eslint-disable-next-line no-console
+    console.error('[kubova-mcp] KUBOVA_API_KEY is required. Generate one at /dashboard/api-keys.');
+    process.exit(1);
+}
+const CargoSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    shape: z.enum(['box', 'cylinder']).default('box'),
+    lengthCm: z.number().positive(),
+    widthCm: z.number().positive(),
+    heightCm: z.number().positive(),
+    diameterCm: z.number().positive().optional(),
+    quantity: z.number().int().positive(),
+    weightKg: z.number().nonnegative(),
+    color: z.string().default('#3b82f6'),
+    includeInLoading: z.boolean().default(true),
+    allowStacking: z.boolean().default(true),
+    allowRotation: z.boolean().default(true),
+});
+const ContainerSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    innerLengthCm: z.number().positive(),
+    innerWidthCm: z.number().positive(),
+    innerHeightCm: z.number().positive(),
+    doorWidthCm: z.number().positive(),
+    doorHeightCm: z.number().positive(),
+    maxPayloadKg: z.number().positive(),
+});
+const PackInputSchema = z.object({
+    cargos: z.array(CargoSchema).min(1),
+    container: ContainerSchema.optional(),
+    containers: z.array(ContainerSchema).optional(),
+    options: z
+        .object({
+        loadingDirection: z.enum(['floor-to-top', 'right-to-left']).optional(),
+        maxContainers: z.number().int().positive().optional(),
+        vnsTimeLimitMs: z.number().int().nonnegative().optional(),
+    })
+        .optional(),
+});
+const PACK_INPUT_JSONSCHEMA = {
+    type: 'object',
+    required: ['cargos'],
+    properties: {
+        cargos: {
+            type: 'array',
+            minItems: 1,
+            items: {
+                type: 'object',
+                required: ['id', 'name', 'lengthCm', 'widthCm', 'heightCm', 'quantity', 'weightKg'],
+                properties: {
+                    id: { type: 'string' },
+                    name: { type: 'string' },
+                    shape: { type: 'string', enum: ['box', 'cylinder'], default: 'box' },
+                    lengthCm: { type: 'number' },
+                    widthCm: { type: 'number' },
+                    heightCm: { type: 'number' },
+                    diameterCm: { type: 'number' },
+                    quantity: { type: 'integer' },
+                    weightKg: { type: 'number' },
+                    color: { type: 'string' },
+                    includeInLoading: { type: 'boolean', default: true },
+                    allowStacking: { type: 'boolean', default: true },
+                    allowRotation: { type: 'boolean', default: true },
+                },
+            },
+        },
+        container: {
+            type: 'object',
+            description: 'Single container to pack into. Use this OR containers[].',
+        },
+        containers: {
+            type: 'array',
+            description: 'Multiple container types — packer picks the best mix.',
+        },
+        options: {
+            type: 'object',
+            properties: {
+                loadingDirection: { type: 'string', enum: ['floor-to-top', 'right-to-left'] },
+                maxContainers: { type: 'integer' },
+                vnsTimeLimitMs: { type: 'integer' },
+            },
+        },
+    },
+};
+const server = new Server({ name: 'kubova-mcp', version: '0.1.0' }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: 'pack_containers',
+            description: 'Pack a list of cargo SKUs into one or more shipping containers using ' +
+                'the Kubova algorithm (Bischoff–Ratcliff block-loading + Parreño 2010 VNS). ' +
+                'Returns per-container placements with x,y,z coordinates in cm, volume ' +
+                'utilization, weight, and any unplaced pieces.',
+            inputSchema: PACK_INPUT_JSONSCHEMA,
+        },
+        {
+            name: 'generate_report',
+            description: 'Generate a CAD-style PDF + 3D PNG report for a packing job. ' +
+                'Same input shape as pack_containers. Returns base64-encoded PDF + PNG per container ' +
+                'plus the full pack result (placements, utilization, unplaced).',
+            inputSchema: PACK_INPUT_JSONSCHEMA,
+        },
+        {
+            name: 'verify_key',
+            description: 'Verify the configured API key. Returns the key identity, scopes, and rate limit.',
+            inputSchema: { type: 'object', properties: {} },
+        },
+    ],
+}));
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const { name, arguments: args } = req.params;
+    if (name === 'verify_key') {
+        const res = await fetch(`${API_URL}/api/v1/me`, {
+            headers: { Authorization: `Bearer ${API_KEY}` },
+        });
+        const text = await res.text();
+        return {
+            content: [{ type: 'text', text }],
+            isError: !res.ok,
+        };
+    }
+    if (name === 'pack_containers' || name === 'generate_report') {
+        const parsed = PackInputSchema.safeParse(args);
+        if (!parsed.success) {
+            return {
+                content: [{ type: 'text', text: `Invalid input: ${parsed.error.message}` }],
+                isError: true,
+            };
+        }
+        const endpoint = name === 'pack_containers' ? '/api/v1/pack' : '/api/v1/report';
+        const res = await fetch(`${API_URL}${endpoint}`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${API_KEY}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(parsed.data),
+        });
+        const text = await res.text();
+        return {
+            content: [{ type: 'text', text }],
+            isError: !res.ok,
+        };
+    }
+    return {
+        content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+        isError: true,
+    };
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);
+// eslint-disable-next-line no-console
+console.error('[kubova-mcp] connected on stdio');

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@kubova/mcp",
+  "version": "0.1.0",
+  "description": "Model Context Protocol server for the Kubova container loading calculator",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "kubova-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "pnpm build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}