@open-loyalty/mcp-server 1.0.0

package/dist/utils/errors.js

@@ -0,0 +1,69 @@
+import { AxiosError } from "axios";
+export class OpenLoyaltyError extends Error {
+    code;
+    hint;
+    relatedTool;
+    constructor(options) {
+        super(options.message);
+        this.name = "OpenLoyaltyError";
+        this.code = options.code;
+        this.hint = options.hint;
+        this.relatedTool = options.relatedTool;
+    }
+}
+export function formatApiError(error, relatedTool) {
+    if (error instanceof OpenLoyaltyError) {
+        return error;
+    }
+    if (error instanceof AxiosError) {
+        const status = error.response?.status;
+        const data = error.response?.data;
+        if (status === 404) {
+            return new OpenLoyaltyError({
+                code: "NOT_FOUND",
+                message: data?.message
+                    ? String(data.message)
+                    : "Resource not found",
+                hint: "Check that the ID or storeCode is correct",
+                relatedTool,
+            });
+        }
+        if (status === 400) {
+            const errors = data?.errors;
+            const errorDetails = errors?.map(e => `${e.path || ''}: ${e.message}`).join('; ') || '';
+            // If API returns "Validation failed" with no details, it's likely an MCP implementation bug
+            const hasNoDetails = !errorDetails && data?.message === "Validation failed";
+            const hint = hasNoDetails
+                ? "The API rejected the request without details. This is likely a bug in the MCP tool implementation (e.g., missing required fields like translations). Please report this issue."
+                : "Check the input parameters match the expected format";
+            return new OpenLoyaltyError({
+                code: "VALIDATION_ERROR",
+                message: data?.message
+                    ? `${String(data.message)}${errorDetails ? ` (${errorDetails})` : ''}`
+                    : "Invalid request data",
+                hint,
+                relatedTool,
+            });
+        }
+        return new OpenLoyaltyError({
+            code: `HTTP_${status || "UNKNOWN"}`,
+            message: error.message,
+            hint: "Check the API response for more details",
+            relatedTool,
+        });
+    }
+    if (error instanceof Error) {
+        return new OpenLoyaltyError({
+            code: "UNKNOWN_ERROR",
+            message: error.message,
+            hint: "An unexpected error occurred",
+            relatedTool,
+        });
+    }
+    return new OpenLoyaltyError({
+        code: "UNKNOWN_ERROR",
+        message: String(error),
+        hint: "An unexpected error occurred",
+        relatedTool,
+    });
+}

package/dist/utils/pagination.d.ts

@@ -0,0 +1,39 @@
+export interface PaginationParams {
+    page?: number;
+    perPage?: number;
+}
+export interface ScrollPaginationParams extends PaginationParams {
+    cursor?: string;
+}
+/**
+ * Build pagination query string using Open Loyalty API parameter names.
+ * API uses _page (1-indexed) and _itemsOnPage for pagination.
+ */
+export declare function buildPaginationQuery(params: PaginationParams): string;
+/**
+ * Build pagination params for URLSearchParams, supporting both traditional
+ * page-based pagination and cursor-based scroll pagination.
+ *
+ * When cursor is provided (including empty string for first scroll request),
+ * scroll pagination is used and page is ignored.
+ *
+ * API scroll behavior:
+ * - First request: ?_scroll (optionally with _itemsOnPage)
+ * - Subsequent requests: ?_scroll=<base64_cursor>
+ * - Response includes `scroll` field with next page cursor
+ */
+export declare function buildPaginationParams(params: ScrollPaginationParams, urlParams: URLSearchParams): void;
+/**
+ * Normalize a date string to full ISO datetime format.
+ * The Open Loyalty API requires full ISO datetime format (YYYY-MM-DDTHH:mm:ssZ).
+ *
+ * - If input is just a date (YYYY-MM-DD), converts based on position:
+ *   - "from" dates: adds T00:00:00Z (start of day)
+ *   - "to" dates: adds T23:59:59Z (end of day)
+ * - If input already has time component, returns as-is
+ *
+ * @param dateStr - Date string (YYYY-MM-DD or full ISO datetime)
+ * @param position - Whether this is a "from" (start) or "to" (end) date
+ * @returns Full ISO datetime string
+ */
+export declare function normalizeDateToISO(dateStr: string, position: "from" | "to"): string;

package/dist/utils/pagination.js

@@ -0,0 +1,77 @@
+/**
+ * Build pagination query string using Open Loyalty API parameter names.
+ * API uses _page (1-indexed) and _itemsOnPage for pagination.
+ */
+export function buildPaginationQuery(params) {
+    const queryParams = [];
+    if (params.page !== undefined && params.page > 0) {
+        queryParams.push(`_page=${params.page}`);
+    }
+    if (params.perPage !== undefined && params.perPage > 0) {
+        queryParams.push(`_itemsOnPage=${params.perPage}`);
+    }
+    return queryParams.length > 0 ? `?${queryParams.join("&")}` : "";
+}
+/**
+ * Build pagination params for URLSearchParams, supporting both traditional
+ * page-based pagination and cursor-based scroll pagination.
+ *
+ * When cursor is provided (including empty string for first scroll request),
+ * scroll pagination is used and page is ignored.
+ *
+ * API scroll behavior:
+ * - First request: ?_scroll (optionally with _itemsOnPage)
+ * - Subsequent requests: ?_scroll=<base64_cursor>
+ * - Response includes `scroll` field with next page cursor
+ */
+export function buildPaginationParams(params, urlParams) {
+    if (params.cursor !== undefined) {
+        // Scroll pagination - cursor takes precedence over page
+        // Empty string means first scroll request, non-empty is subsequent request
+        urlParams.set("_scroll", params.cursor);
+        if (params.perPage && params.perPage > 0) {
+            urlParams.set("_itemsOnPage", String(params.perPage));
+        }
+    }
+    else {
+        // Traditional page-based pagination
+        if (params.page && params.page > 0) {
+            urlParams.set("_page", String(params.page));
+        }
+        if (params.perPage && params.perPage > 0) {
+            urlParams.set("_itemsOnPage", String(params.perPage));
+        }
+    }
+}
+/**
+ * Normalize a date string to full ISO datetime format.
+ * The Open Loyalty API requires full ISO datetime format (YYYY-MM-DDTHH:mm:ssZ).
+ *
+ * - If input is just a date (YYYY-MM-DD), converts based on position:
+ *   - "from" dates: adds T00:00:00Z (start of day)
+ *   - "to" dates: adds T23:59:59Z (end of day)
+ * - If input already has time component, returns as-is
+ *
+ * @param dateStr - Date string (YYYY-MM-DD or full ISO datetime)
+ * @param position - Whether this is a "from" (start) or "to" (end) date
+ * @returns Full ISO datetime string
+ */
+export function normalizeDateToISO(dateStr, position) {
+    // Check if it's already a full datetime (has 'T' in it)
+    if (dateStr.includes("T")) {
+        return dateStr;
+    }
+    // Validate basic date format YYYY-MM-DD
+    const datePattern = /^\d{4}-\d{2}-\d{2}$/;
+    if (!datePattern.test(dateStr)) {
+        // Return as-is and let the API validate
+        return dateStr;
+    }
+    // Convert to full ISO datetime based on position
+    if (position === "from") {
+        return `${dateStr}T00:00:00Z`;
+    }
+    else {
+        return `${dateStr}T23:59:59Z`;
+    }
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@open-loyalty/mcp-server",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "MCP server for Open Loyalty API - enables AI agents to manage loyalty programs, members, points, rewards, and transactions",
+  "author": "Marcin Dyguda <md@openloyalty.io>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openloyalty/mcp-server.git"
+  },
+  "homepage": "https://github.com/openloyalty/mcp-server#readme",
+  "bugs": {
+    "url": "https://github.com/openloyalty/mcp-server/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "open-loyalty",
+    "loyalty",
+    "loyalty-program",
+    "claude",
+    "ai",
+    "anthropic"
+  ],
+  "main": "dist/index.js",
+  "bin": {
+    "openloyalty-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest --watch"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "axios": "^1.6.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "@vitest/coverage-v8": "^4.0.17",
+    "axios-mock-adapter": "^2.1.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.0",
+    "vitest": "^4.0.17"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}