@expander/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,102 @@
+# @expander/mcp-server
+
+Model Context Protocol (MCP) server for the [Exmachine External API](https://api.exmachine.io). Lets you query Exmachine data from **Claude Desktop** using your API key.
+
+## Prerequisites
+
+1. An Exmachine account with access to the data you need.
+2. An API key from **Settings → API Keys** in the Exmachine dashboard.
+3. [Node.js 20+](https://nodejs.org/) (for `npx`).
+
+## Claude Desktop setup
+
+1. Open **Claude Desktop → Settings → Developer → Edit Config**.
+2. Add the `expander` server under `mcpServers`:
+
+```json
+{
+  "mcpServers": {
+    "expander": {
+      "command": "npx",
+      "args": ["-y", "@expander/mcp-server"],
+      "env": {
+        "EXMACHINE_API_KEY": "exp_live_your_key_here",
+        "EXMACHINE_API_BASE": "https://api.exmachine.io/api/v1"
+      }
+    }
+  }
+}
+```
+
+**Config file paths**
+
+| OS | Path |
+|----|------|
+| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
+
+For **local development** against your gateway:
+
+```json
+"EXMACHINE_API_BASE": "http://localhost:8080/api/v1"
+```
+
+Quit and reopen Claude Desktop after saving.
+
+## Environment variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `EXMACHINE_API_KEY` | Yes | — | Your `exp_live_…` API key |
+| `EXMACHINE_API_BASE` | No | `https://api.exmachine.io/api/v1` | API root (includes `/api/v1`) |
+
+## Tools
+
+### Catalog (discover ids first)
+
+| Tool | Description |
+|------|-------------|
+| `list_marketplaces` | Active marketplaces → use `_id` as `marketplace_id` |
+| `list_brands` | Brands for a marketplace → use `id` as `brand_id` |
+| `list_business_partners` | Suppliers, forwarders, or warehouses (`type` param) |
+
+### Data
+
+| Tool | Calls |
+|------|--------|
+| `update_shipment_status` | `PATCH /external/shipments/{ex_number}/status` |
+| `get_shipment_by_ex_number` | `GET /external/shipments/{ex_number}` |
+| `list_shipments` | `GET /external/shipments` |
+| `list_products` | `GET /external/products` |
+| `list_parent_groups` | `GET /external/parent-groups` |
+| `list_sellerboard` | `GET /external/sellerboard` |
+| `list_fba_orders` | `GET /external/amazon-reports/fba-orders` |
+| … | Other Amazon report tools |
+
+Most data tools require `marketplace_id` and `brand_id`. Call catalog tools first.
+
+## Example prompts (in Claude)
+
+- “List marketplaces and brands for Amazon.ca, then show shipments in BOOKING status.”
+- “List forwarders and filter OCEAN shipments for brand Pelegon.”
+- “Pull Sellerboard data for last month for marketplace X and brand Y.”
+
+## Development
+
+```bash
+cd expander-mcp
+npm install
+npm run build
+EXMACHINE_API_KEY=exp_live_... EXMACHINE_API_BASE=http://localhost:8080/api/v1 npm start
+```
+
+## Security
+
+- Never commit API keys. Use env vars in the Claude config only.
+- The MCP server runs locally and forwards your key to the Exmachine API on each tool call.
+- Rate limit: 60 requests/minute per key (same as REST).
+- Dashboard permissions apply — denied endpoints return `403 forbidden`.
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,21 @@
+import type { ExmachineConfig } from './config.js';
+export declare class ExmachineApiClient {
+    private readonly config;
+    constructor(config: ExmachineConfig);
+    get(path: string, query?: Record<string, string | undefined>): Promise<unknown>;
+    patch(path: string, body?: Record<string, unknown>): Promise<unknown>;
+    private request;
+}
+export declare function jsonToolResult(data: unknown): {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+};
+export declare function errorToolResult(message: string): {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError: true;
+};

package/dist/client.js

@@ -0,0 +1,63 @@
+export class ExmachineApiClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async get(path, query) {
+        return this.request('GET', path, { query });
+    }
+    async patch(path, body) {
+        return this.request('PATCH', path, { body });
+    }
+    async request(method, path, options) {
+        const url = new URL(`${this.config.apiBase}${path.startsWith('/') ? path : `/${path}`}`);
+        if (options?.query) {
+            for (const [key, value] of Object.entries(options.query)) {
+                const trimmed = value?.trim();
+                if (trimmed) {
+                    url.searchParams.set(key, trimmed);
+                }
+            }
+        }
+        const response = await fetch(url, {
+            method,
+            headers: {
+                'x-api-key': this.config.apiKey,
+                Accept: 'application/json',
+                ...(options?.body ? { 'Content-Type': 'application/json' } : {}),
+            },
+            body: options?.body ? JSON.stringify(options.body) : undefined,
+        });
+        const bodyText = await response.text();
+        let body = bodyText;
+        if (bodyText) {
+            try {
+                body = JSON.parse(bodyText);
+            }
+            catch {
+                body = bodyText;
+            }
+        }
+        if (!response.ok) {
+            const message = typeof body === 'object' &&
+                body !== null &&
+                'message' in body &&
+                typeof body.message === 'string'
+                ? body.message
+                : `HTTP ${response.status} ${response.statusText}`;
+            throw new Error(message);
+        }
+        return body;
+    }
+}
+export function jsonToolResult(data) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+    };
+}
+export function errorToolResult(message) {
+    return {
+        content: [{ type: 'text', text: message }],
+        isError: true,
+    };
+}

package/dist/config.d.ts

@@ -0,0 +1,5 @@
+export interface ExmachineConfig {
+    apiKey: string;
+    apiBase: string;
+}
+export declare function loadConfig(): ExmachineConfig;

package/dist/config.js

@@ -0,0 +1,9 @@
+const DEFAULT_API_BASE = 'https://api.exmachine.io/api/v1';
+export function loadConfig() {
+    const apiKey = process.env.EXMACHINE_API_KEY?.trim();
+    if (!apiKey) {
+        throw new Error('EXMACHINE_API_KEY is required. Create a key in Exmachine Settings → API Keys.');
+    }
+    const apiBase = (process.env.EXMACHINE_API_BASE?.trim() || DEFAULT_API_BASE).replace(/\/$/, '');
+    return { apiKey, apiBase };
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { loadConfig } from './config.js';
+import { ExmachineApiClient } from './client.js';
+import { registerExmachineTools } from './tools.js';
+async function main() {
+    const config = loadConfig();
+    const client = new ExmachineApiClient(config);
+    const server = new McpServer({
+        name: 'expander-exmachine',
+        version: '0.1.0',
+    });
+    registerExmachineTools(server, client);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`Expander MCP server failed: ${message}`);
+    process.exit(1);
+});

package/dist/tools.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ExmachineApiClient } from './client.js';
+export declare function registerExmachineTools(server: McpServer, client: ExmachineApiClient): void;

package/dist/tools.js

@@ -0,0 +1,245 @@
+import { z } from 'zod';
+import { errorToolResult, jsonToolResult } from './client.js';
+const marketplaceId = z.string().min(1).describe('Marketplace _id from list_marketplaces');
+const brandId = z.string().min(1).describe('Brand id from list_brands');
+const limit = z
+    .number()
+    .int()
+    .min(1)
+    .max(1000)
+    .optional()
+    .describe('Page size (1–1000, default 100)');
+const cursor = z.string().optional().describe('Pagination cursor from prior response next_cursor');
+const marketplaceBrandSchema = z.object({
+    marketplace_id: marketplaceId,
+    brand_id: brandId,
+});
+const paginatedMarketplaceBrandSchema = marketplaceBrandSchema.extend({
+    limit,
+    cursor,
+});
+async function runTool(client, path, query) {
+    try {
+        const data = await client.get(path, query);
+        return jsonToolResult(data);
+    }
+    catch (err) {
+        return errorToolResult(err instanceof Error ? err.message : String(err));
+    }
+}
+async function runPatchTool(client, path, body) {
+    try {
+        const data = await client.patch(path, body);
+        return jsonToolResult(data);
+    }
+    catch (err) {
+        return errorToolResult(err instanceof Error ? err.message : String(err));
+    }
+}
+function optionalString(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+}
+const shipmentStatus = z
+    .enum([
+    'NEW',
+    'ORDER_CONFIRMATION',
+    'BOOKING',
+    'ON_BOARD',
+    'CUSTOMS',
+    'CUSTOMS_RELEASED',
+    'ARRIVAL',
+    'DELIVERED',
+    'CLOSED',
+])
+    .describe('Target pipeline status');
+export function registerExmachineTools(server, client) {
+    server.registerTool('list_marketplaces', {
+        description: 'List all active marketplaces. Use returned _id as marketplace_id on other tools.',
+        inputSchema: z.object({}),
+    }, async () => runTool(client, '/external/marketplaces'));
+    server.registerTool('list_brands', {
+        description: 'List active brands linked to a marketplace.',
+        inputSchema: z.object({ marketplace_id: marketplaceId }),
+    }, async ({ marketplace_id }) => runTool(client, '/external/brands', { marketplace_id }));
+    server.registerTool('list_business_partners', {
+        description: 'List active business partners by type: supplier, forwarder, or warehouse. Use forwarder _id as forwarder_id on list_shipments.',
+        inputSchema: z.object({
+            type: z
+                .enum(['supplier', 'forwarder', 'warehouse'])
+                .describe('Partner kind'),
+        }),
+    }, async ({ type }) => runTool(client, '/external/business-partners', { type }));
+    server.registerTool('get_shipment_by_ex_number', {
+        description: 'Look up one shipment by ExNumber (e.g. EX013994) and return full details including product lines, origin, destination, and parties.',
+        inputSchema: z.object({
+            ex_number: z
+                .string()
+                .min(1)
+                .describe('Shipment ExNumber — accepts EX013994, ex-013994, or EX 013994'),
+        }),
+    }, async ({ ex_number }) => {
+        const normalized = ex_number.trim().toUpperCase().replace(/[\s-]/g, '');
+        return runTool(client, `/external/shipments/${encodeURIComponent(normalized)}`);
+    });
+    server.registerTool('update_shipment_status', {
+        description: 'Update a shipment pipeline status by ExNumber. Uses the same backend rules as the Exmachine dashboard (inventory transactions, required documents for CLOSED, order planning). Requires Supply Chain Edit permission.',
+        inputSchema: z.object({
+            ex_number: z
+                .string()
+                .min(1)
+                .describe('Shipment ExNumber — accepts EX013994, ex-013994, or EX 013994'),
+            status: shipmentStatus,
+        }),
+    }, async ({ ex_number, status }) => {
+        const normalized = ex_number.trim().toUpperCase().replace(/[\s-]/g, '');
+        return runPatchTool(client, `/external/shipments/${encodeURIComponent(normalized)}/status`, {
+            status,
+        });
+    });
+    server.registerTool('list_shipments', {
+        description: 'List active shipments for a marketplace and brand. Optional filters: status, forwarder_id, type.',
+        inputSchema: paginatedMarketplaceBrandSchema.extend({
+            status: z
+                .string()
+                .optional()
+                .describe('Comma-separated statuses: NEW, ORDER_CONFIRMATION, BOOKING, ON_BOARD, CUSTOMS, CUSTOMS_RELEASED, ARRIVAL, DELIVERED, CLOSED'),
+            forwarder_id: z
+                .string()
+                .optional()
+                .describe('Forwarder BusinessPartner _id (comma-separated for multiple)'),
+            type: z
+                .string()
+                .optional()
+                .describe('Comma-separated transport types: OCEAN, AIR, AIR_EXPRESS, OCEAN_EXPRESS, INLAND'),
+        }),
+    }, async (args) => runTool(client, '/external/shipments', {
+        marketplace_id: args.marketplace_id,
+        brand_id: args.brand_id,
+        limit: args.limit != null ? String(args.limit) : undefined,
+        cursor: optionalString(args.cursor),
+        status: optionalString(args.status),
+        forwarder_id: optionalString(args.forwarder_id),
+        type: optionalString(args.type),
+    }));
+    server.registerTool('list_products', {
+        description: 'List product catalog rows for a marketplace and brand.',
+        inputSchema: paginatedMarketplaceBrandSchema.extend({
+            sku: z.string().optional().describe('Filter SKUs (case-insensitive contains)'),
+            asin: z.string().optional().describe('Filter ASINs (case-insensitive contains)'),
+            active: z
+                .enum(['true', 'false'])
+                .optional()
+                .describe('Filter by active flag'),
+        }),
+    }, async (args) => runTool(client, '/external/products', {
+        marketplace_id: args.marketplace_id,
+        brand_id: args.brand_id,
+        limit: args.limit != null ? String(args.limit) : undefined,
+        cursor: optionalString(args.cursor),
+        sku: optionalString(args.sku),
+        asin: optionalString(args.asin),
+        active: args.active,
+    }));
+    server.registerTool('list_parent_groups', {
+        description: 'List parent product groups with nested product rows.',
+        inputSchema: paginatedMarketplaceBrandSchema.extend({
+            parent_name: z.string().optional().describe('Filter group names (contains)'),
+            sku: z.string().optional(),
+            asin: z.string().optional(),
+        }),
+    }, async (args) => runTool(client, '/external/parent-groups', {
+        marketplace_id: args.marketplace_id,
+        brand_id: args.brand_id,
+        limit: args.limit != null ? String(args.limit) : undefined,
+        cursor: optionalString(args.cursor),
+        parent_name: optionalString(args.parent_name),
+        sku: optionalString(args.sku),
+        asin: optionalString(args.asin),
+    }));
+    server.registerTool('list_sellerboard', {
+        description: 'List Sellerboard daily rows for a marketplace, brand, and date range.',
+        inputSchema: marketplaceBrandSchema.extend({
+            from: z.string().describe('Start date YYYY-MM-DD (inclusive)'),
+            to: z.string().describe('End date YYYY-MM-DD (inclusive)'),
+            limit,
+            cursor,
+            sku: z.string().optional(),
+            asin: z.string().optional(),
+        }),
+    }, async (args) => runTool(client, '/external/sellerboard', {
+        marketplace_id: args.marketplace_id,
+        brand_id: args.brand_id,
+        from: args.from,
+        to: args.to,
+        limit: args.limit != null ? String(args.limit) : undefined,
+        cursor: optionalString(args.cursor),
+        sku: optionalString(args.sku),
+        asin: optionalString(args.asin),
+    }));
+    const amazonReportSchema = marketplaceBrandSchema.extend({
+        date: z.string().describe('Report date YYYY-MM-DD'),
+        sku: z.string().optional(),
+        asin: z.string().optional(),
+    });
+    server.registerTool('list_fba_orders', {
+        description: 'Amazon FBA order report rows for one marketplace, brand, and day.',
+        inputSchema: amazonReportSchema,
+    }, async (args) => runTool(client, '/external/amazon-reports/fba-orders', {
+        marketplace_id: args.marketplace_id,
+        brand_id: args.brand_id,
+        date: args.date,
+        sku: optionalString(args.sku),
+        asin: optionalString(args.asin),
+    }));
+    server.registerTool('list_fba_returns', {
+        description: 'Amazon FBA customer returns for one marketplace, brand, and day.',
+        inputSchema: amazonReportSchema,
+    }, async (args) => runTool(client, '/external/amazon-reports/fba-returns', {
+        marketplace_id: args.marketplace_id,
+        brand_id: args.brand_id,
+        date: args.date,
+        sku: optionalString(args.sku),
+        asin: optionalString(args.asin),
+    }));
+    server.registerTool('list_financial_transactions', {
+        description: 'Amazon financial transactions for one marketplace, brand, and day.',
+        inputSchema: amazonReportSchema,
+    }, async (args) => runTool(client, '/external/amazon-reports/financial-transactions', {
+        marketplace_id: args.marketplace_id,
+        brand_id: args.brand_id,
+        date: args.date,
+        sku: optionalString(args.sku),
+        asin: optionalString(args.asin),
+    }));
+    server.registerTool('list_fba_estimated_fees', {
+        description: 'Amazon FBA estimated fees snapshot for marketplace, brand, and date.',
+        inputSchema: amazonReportSchema,
+    }, async (args) => runTool(client, '/external/amazon-reports/fba-estimated-fees', {
+        marketplace_id: args.marketplace_id,
+        brand_id: args.brand_id,
+        date: args.date,
+        sku: optionalString(args.sku),
+        asin: optionalString(args.asin),
+    }));
+    server.registerTool('list_reserved_inventory', {
+        description: 'Amazon reserved inventory snapshot for marketplace, brand, and date.',
+        inputSchema: amazonReportSchema,
+    }, async (args) => runTool(client, '/external/amazon-reports/reserved-inventory', {
+        marketplace_id: args.marketplace_id,
+        brand_id: args.brand_id,
+        date: args.date,
+        sku: optionalString(args.sku),
+        asin: optionalString(args.asin),
+    }));
+    server.registerTool('list_fba_manage_inventory', {
+        description: 'Amazon FBA manage inventory snapshot for marketplace, brand, and date.',
+        inputSchema: amazonReportSchema,
+    }, async (args) => runTool(client, '/external/amazon-reports/fba-manage-inventory', {
+        marketplace_id: args.marketplace_id,
+        brand_id: args.brand_id,
+        date: args.date,
+        sku: optionalString(args.sku),
+        asin: optionalString(args.asin),
+    }));
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@expander/mcp-server",
+  "version": "0.1.0",
+  "description": "Model Context Protocol server for the Exmachine External API",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "expander-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p .",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "exmachine",
+    "expander",
+    "external-api"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "typescript": "^5.8.0"
+  }
+}