shoptet-mcp 1.0.0

package/README.md

@@ -0,0 +1,179 @@
+# Shoptet MCP Server
+
+[![npm version](https://img.shields.io/npm/v/shoptet-mcp.svg)](https://www.npmjs.com/package/shoptet-mcp)
+
+MCP (Model Context Protocol) server for the [Shoptet](https://www.shoptet.cz/) e-commerce platform API. Provides 42 tools for managing orders, products, customers, documents, webhooks, and more — directly from AI assistants like Claude.
+
+## Features
+
+- **Orders** — list, create, update status, get PDF, history, remarks, change tracking
+- **Products** — list, detail, stock levels, brands, categories, change tracking
+- **Customers** — list and detail with filtering
+- **Documents** — invoices, proforma invoices, credit notes, delivery notes, proof of payments
+- **Webhooks** — create, list, delete webhook subscriptions
+- **Eshop info** — basic shop metadata
+- **AI Prompts** — built-in prompts for order analysis, low stock check, daily summary, customer lookup
+- **Resources** — quick access to eshop info and order statuses
+
+## Prerequisites
+
+- Node.js 18+
+- Shoptet API token ([how to get one](https://www.shoptet.cz/api/))
+
+## Setup
+
+No installation needed — just configure your AI client with `npx`:
+
+### Claude Code (CLI)
+
+```bash
+claude mcp add shoptet -e SHOPTET_API_TOKEN=your-token -- npx shoptet-mcp
+```
+
+Or add to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "shoptet": {
+      "command": "npx",
+      "args": ["shoptet-mcp"],
+      "env": {
+        "SHOPTET_API_TOKEN": "your-token"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Open **Settings → Developer → Edit Config** and add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "shoptet": {
+      "command": "npx",
+      "args": ["shoptet-mcp"],
+      "env": {
+        "SHOPTET_API_TOKEN": "your-token"
+      }
+    }
+  }
+}
+```
+
+### VS Code (Copilot / Claude extension)
+
+Add to `.vscode/mcp.json` in your workspace:
+
+```json
+{
+  "servers": {
+    "shoptet": {
+      "command": "npx",
+      "args": ["shoptet-mcp"],
+      "env": {
+        "SHOPTET_API_TOKEN": "your-token"
+      }
+    }
+  }
+}
+```
+
+### JetBrains IDEs
+
+Go to **Settings → Tools → AI Assistant → MCP Servers → Add**, then configure:
+
+- **Name:** `shoptet`
+- **Command:** `npx`
+- **Args:** `shoptet-mcp`
+- **Environment:** `SHOPTET_API_TOKEN=your-token`
+
+### Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "shoptet": {
+      "command": "npx",
+      "args": ["shoptet-mcp"],
+      "env": {
+        "SHOPTET_API_TOKEN": "your-token"
+      }
+    }
+  }
+}
+```
+
+### Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "shoptet": {
+      "command": "npx",
+      "args": ["shoptet-mcp"],
+      "env": {
+        "SHOPTET_API_TOKEN": "your-token"
+      }
+    }
+  }
+}
+```
+
+### Cline (VS Code extension)
+
+Open MCP settings in Cline and add:
+
+```json
+{
+  "mcpServers": {
+    "shoptet": {
+      "command": "npx",
+      "args": ["shoptet-mcp"],
+      "env": {
+        "SHOPTET_API_TOKEN": "your-token"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+| Category | Tools |
+|----------|-------|
+| **Orders** | `list_orders`, `get_order`, `create_order`, `update_order_status`, `get_order_statuses`, `get_order_pdf`, `get_order_history`, `add_order_remark`, `get_order_changes` |
+| **Products** | `list_products`, `get_product`, `get_product_changes`, `get_stock`, `list_brands`, `create_brand`, `list_categories` |
+| **Customers** | `list_customers`, `get_customer` |
+| **Documents** | `list_invoices`, `get_invoice`, `create_invoice_from_order`, `get_invoice_pdf`, `list_proforma_invoices`, `get_proforma_invoice`, `list_credit_notes`, `get_credit_note`, `create_credit_note_from_invoice`, `list_delivery_notes`, `create_delivery_note`, `list_proof_payments`, `get_proof_payment` |
+| **Webhooks** | `list_webhooks`, `create_webhook`, `delete_webhook` |
+| **Eshop** | `get_eshop_info` |
+
+## Development
+
+```bash
+git clone https://github.com/tomaskalina/shoptet-mcp.git
+cd shoptet-mcp
+npm install
+npm run build
+```
+
+```bash
+npm run dev          # Watch mode (TypeScript compilation)
+npm run test         # Run tests
+npm run test:watch   # Watch mode tests
+npm run lint         # Lint
+npm run typecheck    # Type check
+npm run check        # All checks (typecheck + lint + test)
+```
+
+## License
+
+MIT

package/dist/__tests__/client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/client.test.js

@@ -0,0 +1,72 @@
+import { describe, it, expect } from "vitest";
+// Must set env before importing client
+process.env.SHOPTET_API_TOKEN = "test-token";
+import { safePath, buildQuery, text, errorResult, safeCall } from "../client.js";
+describe("safePath", () => {
+    it("encodes a simple string", () => {
+        expect(safePath("abc123")).toBe("abc123");
+    });
+    it("encodes special characters", () => {
+        expect(safePath("hello world")).toBe("hello%20world");
+    });
+    it("rejects path traversal", () => {
+        expect(() => safePath("../etc")).toThrow("Invalid path segment");
+    });
+    it("rejects slashes", () => {
+        expect(() => safePath("foo/bar")).toThrow("Invalid path segment");
+    });
+    it("rejects query strings", () => {
+        expect(() => safePath("foo?bar=1")).toThrow("Invalid path segment");
+    });
+    it("rejects fragments", () => {
+        expect(() => safePath("foo#bar")).toThrow("Invalid path segment");
+    });
+    it("handles numbers", () => {
+        expect(safePath(42)).toBe("42");
+    });
+});
+describe("buildQuery", () => {
+    it("returns empty string for no params", () => {
+        expect(buildQuery({})).toBe("");
+    });
+    it("builds query string from params", () => {
+        expect(buildQuery({ page: 1, itemsPerPage: 10 })).toBe("?page=1&itemsPerPage=10");
+    });
+    it("skips undefined values", () => {
+        expect(buildQuery({ page: 1, status: undefined })).toBe("?page=1");
+    });
+    it("handles string values", () => {
+        expect(buildQuery({ email: "test@example.com" })).toBe("?email=test%40example.com");
+    });
+});
+describe("text", () => {
+    it("wraps data as JSON text content", () => {
+        const result = text({ foo: "bar" });
+        expect(result.content).toHaveLength(1);
+        const item = result.content[0];
+        expect(item.type).toBe("text");
+        expect("text" in item && JSON.parse(item.text)).toEqual({ foo: "bar" });
+    });
+});
+describe("errorResult", () => {
+    it("returns error content with isError flag", () => {
+        const result = errorResult(new Error("test error"));
+        expect(result.isError).toBe(true);
+        const item = result.content[0];
+        expect("text" in item && item.text).toContain("test error");
+    });
+});
+describe("safeCall", () => {
+    it("returns result on success", async () => {
+        const result = await safeCall(async () => text({ ok: true }));
+        expect(result.isError).toBeUndefined();
+    });
+    it("catches errors and returns error result", async () => {
+        const result = await safeCall(async () => {
+            throw new Error("boom");
+        });
+        expect(result.isError).toBe(true);
+        const item = result.content[0];
+        expect("text" in item && item.text).toContain("boom");
+    });
+});

package/dist/__tests__/server.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/server.test.js

@@ -0,0 +1,60 @@
+import { describe, it, expect, vi, beforeAll } from "vitest";
+// Set env before any imports
+process.env.SHOPTET_API_TOKEN = "test-token";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerOrderTools } from "../tools/orders.js";
+import { registerProductTools } from "../tools/products.js";
+import { registerCustomerTools } from "../tools/customers.js";
+import { registerDocumentTools } from "../tools/documents.js";
+import { registerWebhookTools } from "../tools/webhooks.js";
+import { registerEshopTools } from "../tools/eshop.js";
+import { registerResources } from "../resources.js";
+import { registerPrompts } from "../prompts.js";
+describe("MCP Server registration", () => {
+    let server;
+    beforeAll(() => {
+        server = new McpServer({ name: "shoptet-test", version: "1.0.0" });
+    });
+    it("registers order tools without error", () => {
+        expect(() => registerOrderTools(server)).not.toThrow();
+    });
+    it("registers product tools without error", () => {
+        expect(() => registerProductTools(server)).not.toThrow();
+    });
+    it("registers customer tools without error", () => {
+        expect(() => registerCustomerTools(server)).not.toThrow();
+    });
+    it("registers document tools without error", () => {
+        expect(() => registerDocumentTools(server)).not.toThrow();
+    });
+    it("registers webhook tools without error", () => {
+        expect(() => registerWebhookTools(server)).not.toThrow();
+    });
+    it("registers eshop tools without error", () => {
+        expect(() => registerEshopTools(server)).not.toThrow();
+    });
+    it("registers resources without error", () => {
+        expect(() => registerResources(server)).not.toThrow();
+    });
+    it("registers prompts without error", () => {
+        expect(() => registerPrompts(server)).not.toThrow();
+    });
+});
+describe("API error handling", () => {
+    it("shoptet() throws on non-OK response", async () => {
+        const originalFetch = globalThis.fetch;
+        globalThis.fetch = vi.fn().mockResolvedValue({
+            ok: false,
+            status: 401,
+            text: async () => "Unauthorized",
+            headers: new Headers(),
+        });
+        try {
+            const { shoptet } = await import("../client.js");
+            await expect(shoptet("/api/eshop")).rejects.toThrow("401");
+        }
+        finally {
+            globalThis.fetch = originalFetch;
+        }
+    });
+});

package/dist/client.d.ts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+export declare function safePath(segment: string | number): string;
+export declare function shoptet(path: string, method?: string, body?: unknown): Promise<unknown>;
+export declare const pagingSchema: {
+    page: z.ZodOptional<z.ZodNumber>;
+    itemsPerPage: z.ZodOptional<z.ZodNumber>;
+};
+export declare function buildQuery(params: Record<string, string | number | undefined>): string;
+export declare function text(data: unknown): CallToolResult;
+export declare function errorResult(err: unknown): CallToolResult;
+export declare function safeCall(fn: () => Promise<CallToolResult>): Promise<CallToolResult>;

package/dist/client.js

@@ -0,0 +1,65 @@
+import { z } from "zod";
+const API_BASE = "https://api.myshoptet.com";
+function getToken() {
+    const t = process.env.SHOPTET_API_TOKEN;
+    if (!t)
+        throw new Error("SHOPTET_API_TOKEN environment variable is required");
+    return t;
+}
+export function safePath(segment) {
+    const s = String(segment);
+    if (s.includes("/") || s.includes("?") || s.includes("#") || s.includes("..")) {
+        throw new Error(`Invalid path segment: ${s}`);
+    }
+    return encodeURIComponent(s);
+}
+export async function shoptet(path, method = "GET", body) {
+    const res = await fetch(`${API_BASE}${path}`, {
+        method,
+        headers: {
+            "Shoptet-Access-Token": getToken(),
+            ...(body ? { "Content-Type": "application/json" } : {}),
+        },
+        ...(body ? { body: JSON.stringify(body) } : {}),
+    });
+    if (res.status === 429) {
+        const retryAfter = res.headers.get("Retry-After");
+        await new Promise((r) => setTimeout(r, (Number(retryAfter) || 2) * 1000));
+        return shoptet(path, method, body);
+    }
+    if (!res.ok) {
+        const errText = await res.text();
+        throw new Error(`Shoptet API ${res.status}: ${errText}`);
+    }
+    return res.json();
+}
+export const pagingSchema = {
+    page: z.number().optional().describe("Page number (starts at 1)"),
+    itemsPerPage: z.number().optional().describe("Items per page (max 100)"),
+};
+export function buildQuery(params) {
+    const query = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined)
+            query.set(key, String(value));
+    }
+    const qs = query.toString();
+    return qs ? `?${qs}` : "";
+}
+export function text(data) {
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+export function errorResult(err) {
+    return {
+        content: [{ type: "text", text: String(err) }],
+        isError: true,
+    };
+}
+export async function safeCall(fn) {
+    try {
+        return await fn();
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerOrderTools } from "./tools/orders.js";
+import { registerProductTools } from "./tools/products.js";
+import { registerCustomerTools } from "./tools/customers.js";
+import { registerDocumentTools } from "./tools/documents.js";
+import { registerWebhookTools } from "./tools/webhooks.js";
+import { registerEshopTools } from "./tools/eshop.js";
+import { registerResources } from "./resources.js";
+import { registerPrompts } from "./prompts.js";
+const server = new McpServer({
+    name: "shoptet",
+    version: "1.0.0",
+});
+// Tools
+registerOrderTools(server);
+registerProductTools(server);
+registerCustomerTools(server);
+registerDocumentTools(server);
+registerWebhookTools(server);
+registerEshopTools(server);
+// Resources & Prompts
+registerResources(server);
+registerPrompts(server);
+const transport = new StdioServerTransport();
+server.connect(transport).catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

package/dist/prompts.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerPrompts(server: McpServer): void;

package/dist/prompts.js

@@ -0,0 +1,54 @@
+import { z } from "zod";
+export function registerPrompts(server) {
+    server.prompt("analyze-orders", "Analyze recent orders — summarize totals, statuses, and trends", { days: z.string().optional().describe("Number of days to look back (default: 7)") }, async ({ days }) => {
+        const d = Number(days) || 7;
+        const from = new Date(Date.now() - d * 86400000).toISOString().slice(0, 16).replace("T", " ");
+        return {
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: `Use the list_orders tool with creationTimeFrom="${from}" to fetch recent orders. Then analyze them:\n\n1. Total number of orders and total revenue\n2. Breakdown by order status\n3. Top customers by order value\n4. Any notable trends or anomalies\n\nPresent the results in a clear summary with tables where appropriate.`,
+                    },
+                },
+            ],
+        };
+    });
+    server.prompt("low-stock-check", "Check for products with low inventory levels", {}, async () => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: "Use list_products to get all products, then check stock levels for each using get_stock. Identify products with low or zero inventory. Present a table of products sorted by stock level (lowest first) including product name, current stock, and any variants.",
+                },
+            },
+        ],
+    }));
+    server.prompt("daily-summary", "Generate a daily business summary for the eshop", {}, async () => {
+        const today = new Date().toISOString().slice(0, 10);
+        return {
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: `Generate a daily business summary for ${today}:\n\n1. Use get_eshop_info to get the shop name\n2. Use list_orders with creationTimeFrom="${today} 00:00" to get today's orders\n3. Use get_order_changes to see recent activity\n4. Summarize: new orders count, revenue, status distribution\n\nFormat as a concise daily report.`,
+                    },
+                },
+            ],
+        };
+    });
+    server.prompt("customer-lookup", "Look up a customer and their order history", { email: z.string().describe("Customer email address") }, async ({ email }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Look up the customer with email "${email}":\n\n1. Use list_customers with email filter to find them\n2. Use get_customer to get their full profile\n3. Use list_orders to find their orders\n4. Summarize: customer info, total orders, total spent, most recent order`,
+                },
+            },
+        ],
+    }));
+}

package/dist/resources.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerResources(server: McpServer): void;

package/dist/resources.js

@@ -0,0 +1,21 @@
+import { shoptet } from "./client.js";
+export function registerResources(server) {
+    server.resource("eshop-info", "shoptet://eshop/info", { description: "Basic eshop information: name, URL, contact, currency, settings" }, async () => ({
+        contents: [
+            {
+                uri: "shoptet://eshop/info",
+                mimeType: "application/json",
+                text: JSON.stringify(await shoptet("/api/eshop"), null, 2),
+            },
+        ],
+    }));
+    server.resource("order-statuses", "shoptet://orders/statuses", { description: "All available order statuses with IDs and names" }, async () => ({
+        contents: [
+            {
+                uri: "shoptet://orders/statuses",
+                mimeType: "application/json",
+                text: JSON.stringify(await shoptet("/api/orders/statuses"), null, 2),
+            },
+        ],
+    }));
+}

package/dist/tools/customers.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerCustomerTools(server: McpServer): void;

package/dist/tools/customers.js

@@ -0,0 +1,20 @@
+import { z } from "zod";
+import { shoptet, buildQuery, text, safePath, pagingSchema, safeCall } from "../client.js";
+export function registerCustomerTools(server) {
+    server.registerTool("list_customers", {
+        title: "List Customers",
+        description: "List registered customers with optional filtering by email or creation date.",
+        inputSchema: {
+            ...pagingSchema,
+            email: z.string().optional().describe("Filter by email address"),
+            creationTimeFrom: z.string().optional().describe("Created from date (YYYY-MM-DD)"),
+        },
+        annotations: { readOnlyHint: true },
+    }, (params) => safeCall(async () => text(await shoptet(`/api/customers${buildQuery(params)}`))));
+    server.registerTool("get_customer", {
+        title: "Get Customer Detail",
+        description: "Get full customer profile including contact info, addresses, and account details.",
+        inputSchema: { guid: z.string().describe("Customer GUID") },
+        annotations: { readOnlyHint: true },
+    }, ({ guid }) => safeCall(async () => text(await shoptet(`/api/customers/${safePath(guid)}`))));
+}

package/dist/tools/documents.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerDocumentTools(server: McpServer): void;

package/dist/tools/documents.js

@@ -0,0 +1,91 @@
+import { z } from "zod";
+import { shoptet, buildQuery, text, safePath, pagingSchema, safeCall } from "../client.js";
+export function registerDocumentTools(server) {
+    // ── Invoices ──────────────────────────────────────────
+    server.registerTool("list_invoices", {
+        title: "List Invoices",
+        description: "List invoices with optional date filtering. Returns invoice summaries with codes, amounts, and dates.",
+        inputSchema: {
+            ...pagingSchema,
+            creationTimeFrom: z.string().optional().describe("Created from date (YYYY-MM-DD)"),
+            creationTimeTo: z.string().optional().describe("Created to date (YYYY-MM-DD)"),
+        },
+        annotations: { readOnlyHint: true },
+    }, (params) => safeCall(async () => text(await shoptet(`/api/invoices${buildQuery(params)}`))));
+    server.registerTool("get_invoice", {
+        title: "Get Invoice Detail",
+        description: "Get full invoice detail including items, amounts, tax, and customer billing info.",
+        inputSchema: { code: z.string().describe("Invoice code") },
+        annotations: { readOnlyHint: true },
+    }, ({ code }) => safeCall(async () => text(await shoptet(`/api/invoices/${safePath(code)}`))));
+    server.registerTool("create_invoice_from_order", {
+        title: "Create Invoice from Order",
+        description: "Generate an invoice from an existing order.",
+        inputSchema: { orderCode: z.string().describe("Order code") },
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, ({ orderCode }) => safeCall(async () => text(await shoptet(`/api/orders/${safePath(orderCode)}/invoice`, "POST"))));
+    server.registerTool("get_invoice_pdf", {
+        title: "Get Invoice PDF",
+        description: "Get invoice document as PDF.",
+        inputSchema: { code: z.string().describe("Invoice code") },
+        annotations: { readOnlyHint: true },
+    }, ({ code }) => safeCall(async () => text(await shoptet(`/api/invoices/${safePath(code)}/pdf`))));
+    // ── Proforma Invoices ─────────────────────────────────
+    server.registerTool("list_proforma_invoices", {
+        title: "List Proforma Invoices",
+        description: "List proforma (advance) invoices.",
+        inputSchema: pagingSchema,
+        annotations: { readOnlyHint: true },
+    }, (params) => safeCall(async () => text(await shoptet(`/api/proforma-invoices${buildQuery(params)}`))));
+    server.registerTool("get_proforma_invoice", {
+        title: "Get Proforma Invoice Detail",
+        description: "Get full proforma invoice detail.",
+        inputSchema: { code: z.string().describe("Proforma invoice code") },
+        annotations: { readOnlyHint: true },
+    }, ({ code }) => safeCall(async () => text(await shoptet(`/api/proforma-invoices/${safePath(code)}`))));
+    // ── Credit Notes ──────────────────────────────────────
+    server.registerTool("list_credit_notes", {
+        title: "List Credit Notes",
+        description: "List credit notes (refund documents).",
+        inputSchema: pagingSchema,
+        annotations: { readOnlyHint: true },
+    }, (params) => safeCall(async () => text(await shoptet(`/api/credit-notes${buildQuery(params)}`))));
+    server.registerTool("get_credit_note", {
+        title: "Get Credit Note Detail",
+        description: "Get full credit note detail including refunded items and amounts.",
+        inputSchema: { code: z.string().describe("Credit note code") },
+        annotations: { readOnlyHint: true },
+    }, ({ code }) => safeCall(async () => text(await shoptet(`/api/credit-notes/${safePath(code)}`))));
+    server.registerTool("create_credit_note_from_invoice", {
+        title: "Create Credit Note from Invoice",
+        description: "Create a credit note (refund) from an existing invoice.",
+        inputSchema: { invoiceCode: z.string().describe("Invoice code") },
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, ({ invoiceCode }) => safeCall(async () => text(await shoptet(`/api/invoices/${safePath(invoiceCode)}/credit-note`, "POST"))));
+    // ── Delivery Notes ────────────────────────────────────
+    server.registerTool("list_delivery_notes", {
+        title: "List Delivery Notes",
+        description: "List delivery notes (shipping documents).",
+        inputSchema: pagingSchema,
+        annotations: { readOnlyHint: true },
+    }, (params) => safeCall(async () => text(await shoptet(`/api/delivery-notes${buildQuery(params)}`))));
+    server.registerTool("create_delivery_note", {
+        title: "Create Delivery Note from Order",
+        description: "Generate a delivery note from an existing order.",
+        inputSchema: { orderCode: z.string().describe("Order code") },
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, ({ orderCode }) => safeCall(async () => text(await shoptet(`/api/orders/${safePath(orderCode)}/delivery-notes`, "POST"))));
+    // ── Proof of Payments ─────────────────────────────────
+    server.registerTool("list_proof_payments", {
+        title: "List Proof of Payments",
+        description: "List proof of payment documents.",
+        inputSchema: pagingSchema,
+        annotations: { readOnlyHint: true },
+    }, (params) => safeCall(async () => text(await shoptet(`/api/proof-payments${buildQuery(params)}`))));
+    server.registerTool("get_proof_payment", {
+        title: "Get Proof of Payment Detail",
+        description: "Get full proof of payment detail.",
+        inputSchema: { code: z.string().describe("Proof of payment code") },
+        annotations: { readOnlyHint: true },
+    }, ({ code }) => safeCall(async () => text(await shoptet(`/api/proof-payments/${safePath(code)}`))));
+}

package/dist/tools/eshop.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerEshopTools(server: McpServer): void;

package/dist/tools/eshop.js

@@ -0,0 +1,8 @@
+import { shoptet, text, safeCall } from "../client.js";
+export function registerEshopTools(server) {
+    server.registerTool("get_eshop_info", {
+        title: "Get Eshop Info",
+        description: "Get basic information about the eshop: name, URL, contact info, currency, and settings.",
+        annotations: { readOnlyHint: true },
+    }, () => safeCall(async () => text(await shoptet("/api/eshop"))));
+}

package/dist/tools/orders.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerOrderTools(server: McpServer): void;

package/dist/tools/orders.js

@@ -0,0 +1,71 @@
+import { z } from "zod";
+import { shoptet, buildQuery, text, safePath, pagingSchema, safeCall } from "../client.js";
+export function registerOrderTools(server) {
+    server.registerTool("list_orders", {
+        title: "List Orders",
+        description: "List orders with optional filtering. Returns paginated results with order summaries including code, status, customer, and totals.",
+        inputSchema: {
+            ...pagingSchema,
+            statusId: z.number().optional().describe("Filter by status ID (use get_order_statuses to see available)"),
+            creationTimeFrom: z.string().optional().describe("Filter from date (YYYY-MM-DD HH:MM)"),
+            creationTimeTo: z.string().optional().describe("Filter to date (YYYY-MM-DD HH:MM)"),
+            code: z.string().optional().describe("Filter by order code"),
+        },
+        annotations: { readOnlyHint: true },
+    }, (params) => safeCall(async () => text(await shoptet(`/api/orders${buildQuery(params)}`))));
+    server.registerTool("get_order", {
+        title: "Get Order Detail",
+        description: "Get full order detail including items, shipping, payment, and customer info.",
+        inputSchema: { code: z.string().describe("Order code (e.g. '2024000123')") },
+        annotations: { readOnlyHint: true },
+    }, ({ code }) => safeCall(async () => text(await shoptet(`/api/orders/${safePath(code)}`))));
+    server.registerTool("create_order", {
+        title: "Create Order",
+        description: "Create a new order. Requires at minimum customer info and order items.",
+        inputSchema: { order: z.record(z.unknown()).describe("Order data object") },
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, ({ order }) => safeCall(async () => text(await shoptet("/api/orders", "POST", order))));
+    server.registerTool("update_order_status", {
+        title: "Update Order Status",
+        description: "Change the status of an order. Use get_order_statuses to see available status IDs.",
+        inputSchema: {
+            code: z.string().describe("Order code"),
+            statusId: z.number().describe("New status ID"),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+    }, ({ code, statusId }) => safeCall(async () => text(await shoptet(`/api/orders/${safePath(code)}/status`, "PATCH", { statusId }))));
+    server.registerTool("get_order_statuses", {
+        title: "List Order Statuses",
+        description: "List all available order statuses with their IDs and names. Useful for filtering orders or updating order status.",
+        annotations: { readOnlyHint: true },
+    }, () => safeCall(async () => text(await shoptet("/api/orders/statuses"))));
+    server.registerTool("get_order_pdf", {
+        title: "Get Order PDF",
+        description: "Get order document as PDF. Returns a download URL or base64-encoded content.",
+        inputSchema: { code: z.string().describe("Order code") },
+        annotations: { readOnlyHint: true },
+    }, ({ code }) => safeCall(async () => text(await shoptet(`/api/orders/${safePath(code)}/pdf`))));
+    server.registerTool("get_order_history", {
+        title: "Get Order History",
+        description: "Get order history log and user remarks. Shows status changes, edits, and internal notes.",
+        inputSchema: { code: z.string().describe("Order code") },
+        annotations: { readOnlyHint: true },
+    }, ({ code }) => safeCall(async () => text(await shoptet(`/api/orders/${safePath(code)}/history`))));
+    server.registerTool("add_order_remark", {
+        title: "Add Order Remark",
+        description: "Add an internal remark/note to an order. Visible only in admin, not to customers.",
+        inputSchema: {
+            code: z.string().describe("Order code"),
+            remark: z.string().describe("Remark text"),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, ({ code, remark }) => safeCall(async () => text(await shoptet(`/api/orders/${safePath(code)}/history`, "POST", { remark }))));
+    server.registerTool("get_order_changes", {
+        title: "Get Order Changes",
+        description: "Get list of recently changed orders. Useful for syncing or monitoring order updates.",
+        inputSchema: {
+            lastChangeFrom: z.string().optional().describe("Changes from date (YYYY-MM-DD HH:MM)"),
+        },
+        annotations: { readOnlyHint: true },
+    }, (params) => safeCall(async () => text(await shoptet(`/api/orders/changes${buildQuery(params)}`))));
+}

package/dist/tools/products.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerProductTools(server: McpServer): void;

package/dist/tools/products.js

@@ -0,0 +1,53 @@
+import { z } from "zod";
+import { shoptet, buildQuery, text, safePath, pagingSchema, safeCall } from "../client.js";
+export function registerProductTools(server) {
+    server.registerTool("list_products", {
+        title: "List Products",
+        description: "List products with optional filtering by category, brand, or visibility. Returns paginated product summaries.",
+        inputSchema: {
+            ...pagingSchema,
+            categoryGuid: z.string().optional().describe("Filter by category GUID"),
+            brandCode: z.string().optional().describe("Filter by brand code"),
+            visibility: z.string().optional().describe("Filter by visibility (visible, hidden, etc.)"),
+            creationTimeFrom: z.string().optional().describe("Created from date (YYYY-MM-DD)"),
+            creationTimeTo: z.string().optional().describe("Created to date (YYYY-MM-DD)"),
+        },
+        annotations: { readOnlyHint: true },
+    }, (params) => safeCall(async () => text(await shoptet(`/api/products${buildQuery(params)}`))));
+    server.registerTool("get_product", {
+        title: "Get Product Detail",
+        description: "Get full product detail including variants, pricing, images, and descriptions.",
+        inputSchema: { guid: z.string().describe("Product GUID") },
+        annotations: { readOnlyHint: true },
+    }, ({ guid }) => safeCall(async () => text(await shoptet(`/api/products/${safePath(guid)}`))));
+    server.registerTool("get_product_changes", {
+        title: "Get Product Changes",
+        description: "Get list of recently changed products. Useful for syncing product catalog.",
+        inputSchema: { lastChangeFrom: z.string().optional().describe("Changes from date (YYYY-MM-DD)") },
+        annotations: { readOnlyHint: true },
+    }, (params) => safeCall(async () => text(await shoptet(`/api/products/changes${buildQuery(params)}`))));
+    server.registerTool("get_stock", {
+        title: "Get Product Stock",
+        description: "Get inventory/stock levels for a product across all warehouses.",
+        inputSchema: { guid: z.string().describe("Product GUID") },
+        annotations: { readOnlyHint: true },
+    }, ({ guid }) => safeCall(async () => text(await shoptet(`/api/products/${safePath(guid)}/stock`))));
+    server.registerTool("list_brands", {
+        title: "List Brands",
+        description: "List all product brands in the eshop.",
+        inputSchema: pagingSchema,
+        annotations: { readOnlyHint: true },
+    }, (params) => safeCall(async () => text(await shoptet(`/api/brands${buildQuery(params)}`))));
+    server.registerTool("create_brand", {
+        title: "Create Brand",
+        description: "Create a new product brand.",
+        inputSchema: { brand: z.record(z.unknown()).describe("Brand data object") },
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, ({ brand }) => safeCall(async () => text(await shoptet("/api/brands", "POST", brand))));
+    server.registerTool("list_categories", {
+        title: "List Categories",
+        description: "List product categories with their hierarchy structure.",
+        inputSchema: pagingSchema,
+        annotations: { readOnlyHint: true },
+    }, (params) => safeCall(async () => text(await shoptet(`/api/categories${buildQuery(params)}`))));
+}

package/dist/tools/webhooks.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerWebhookTools(server: McpServer): void;

package/dist/tools/webhooks.js

@@ -0,0 +1,24 @@
+import { z } from "zod";
+import { shoptet, text, safePath, safeCall } from "../client.js";
+export function registerWebhookTools(server) {
+    server.registerTool("list_webhooks", {
+        title: "List Webhooks",
+        description: "List all registered webhooks and their event subscriptions.",
+        annotations: { readOnlyHint: true },
+    }, () => safeCall(async () => text(await shoptet("/api/webhooks"))));
+    server.registerTool("create_webhook", {
+        title: "Create Webhook",
+        description: "Register a new webhook to receive real-time notifications. Events: order:create, order:update, product:create, product:update, etc.",
+        inputSchema: {
+            event: z.string().describe("Event type (e.g. order:create, order:update, product:create)"),
+            url: z.string().describe("Callback URL that will receive POST notifications"),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, ({ event, url }) => safeCall(async () => text(await shoptet("/api/webhooks", "POST", { event, url }))));
+    server.registerTool("delete_webhook", {
+        title: "Delete Webhook",
+        description: "Remove a registered webhook by its ID.",
+        inputSchema: { id: z.number().describe("Webhook ID") },
+        annotations: { readOnlyHint: false, destructiveHint: true },
+    }, ({ id }) => safeCall(async () => text(await shoptet(`/api/webhooks/${safePath(id)}`, "DELETE"))));
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "shoptet-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for Shoptet e-commerce platform API — manage orders, products, customers, documents, and webhooks from AI assistants",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "shoptet-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "mcp",
+    "shoptet",
+    "ecommerce",
+    "model-context-protocol",
+    "ai",
+    "claude"
+  ],
+  "author": "Tonda Kalina",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tomaskalina/shoptet-mcp.git"
+  },
+  "homepage": "https://github.com/tomaskalina/shoptet-mcp#readme",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run typecheck && npm run lint && npm run test",
+    "prepublishOnly": "npm run check && npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.24.4"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^22.15.3",
+    "eslint": "^10.1.0",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.58.0",
+    "vitest": "^4.1.2"
+  },
+  "packageManager": "yarn@3.8.1+sha512.8cfec856814c797ccb480703ca5270824327fac5abce240835e2699e01732229fd22bbeb1bb87047a0069f7698be9b2e3d9a926e6046e851faa9908fdacdeacf"
+}