@open-loyalty/mcp-server 1.0.0 → 1.0.2

package/README.md

@@ -1,6 +1,6 @@
 # Open Loyalty MCP Server
 
-MCP (Model Context Protocol) server for interacting with Open Loyalty API. This server enables AI agents like Claude to manage loyalty programs, members, points, rewards, and transactions.
+MCP (Model Context Protocol) server for interacting with Open Loyalty API. This server enables AI agents like Claude and ChatGPT to manage loyalty programs, members, points, rewards, and transactions.
 
 ## Prerequisites
 
@@ -12,20 +12,20 @@ MCP (Model Context Protocol) server for interacting with Open Loyalty API. This
 ### Via npm (Recommended)
 
 ```bash
-npm install -g @openloyalty/mcp-server
+npm install -g @open-loyalty/mcp-server
 ```
 
 Or use directly with npx (no installation required):
 
 ```bash
-npx @openloyalty/mcp-server
+npx @open-loyalty/mcp-server
 ```
 
 ### From Source
 
 ```bash
-git clone https://github.com/openloyalty/mcp-server.git
-cd mcp-server
+git clone https://github.com/OpenLoyalty/openloyalty-mcp.git
+cd openloyalty-mcp/openloyalty-mcp
 npm install
 npm run build
 ```
@@ -46,20 +46,37 @@ For local development, create a `.env` file based on `.env.example`:
 cp .env.example .env
 ```
 
-## Claude Desktop Configuration
+## Transport Modes
+
+The server supports two transport modes for different use cases:
+
+| Mode | Binary | Use Case |
+|------|--------|----------|
+| **stdio** | `openloyalty-mcp` | Local usage with Claude Desktop, Claude Code, Cursor |
+| **HTTP** | `openloyalty-mcp-http` | Remote hosting, ChatGPT Actions, web integrations |
+
+Both modes provide identical functionality - only the transport layer differs.
+
+---
+
+## Stdio Mode (Local)
+
+Use stdio mode when running the server locally with MCP clients like Claude Desktop.
+
+### Claude Desktop Configuration
 
 Add this to your Claude Desktop configuration file:
 - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
 - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
 
-### Using npx (Recommended)
+#### Using npx (Recommended)
 
 ```json
 {
   "mcpServers": {
     "openloyalty": {
       "command": "npx",
-      "args": ["-y", "@openloyalty/mcp-server"],
+      "args": ["-y", "@open-loyalty/mcp-server"],
       "env": {
         "OPENLOYALTY_API_URL": "https://your-instance.openloyalty.io",
         "OPENLOYALTY_API_TOKEN": "your-api-token",
@@ -70,7 +87,7 @@ Add this to your Claude Desktop configuration file:
 }
 ```
 
-### Using Global Installation
+#### Using Global Installation
 
 ```json
 {
@@ -87,14 +104,14 @@ Add this to your Claude Desktop configuration file:
 }
 ```
 
-### Using Local Build
+#### Using Local Build
 
 ```json
 {
   "mcpServers": {
     "openloyalty": {
       "command": "node",
-      "args": ["/path/to/mcp-server/dist/index.js"],
+      "args": ["/path/to/openloyalty-mcp/dist/index.js"],
       "env": {
         "OPENLOYALTY_API_URL": "https://your-instance.openloyalty.io",
         "OPENLOYALTY_API_TOKEN": "your-api-token",
@@ -105,12 +122,105 @@ Add this to your Claude Desktop configuration file:
 }
 ```
 
+---
+
+## HTTP Mode (Remote Hosting)
+
+Use HTTP mode when hosting the server remotely for web-based MCP clients or ChatGPT Actions.
+
+### Running HTTP Server
+
+```bash
+# Using the binary
+openloyalty-mcp-http
+
+# Using npm scripts
+npm run start:http
+
+# Development mode
+npm run dev:http
+```
+
+### HTTP Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `OPENLOYALTY_API_URL` | Yes* | Open Loyalty API URL |
+| `OPENLOYALTY_API_TOKEN` | Yes* | API authentication token |
+| `OPENLOYALTY_DEFAULT_STORE_CODE` | Yes* | Default store code |
+| `PORT` or `MCP_HTTP_PORT` | No | Server port (default: 3000) |
+| `OAUTH_ENABLED` | No | Enable multi-tenant OAuth mode |
+| `BASE_URL` | OAuth | Public URL for OAuth callbacks |
+| `REDIS_URL` | OAuth | Redis URL for token storage |
+
+*Required when `OAUTH_ENABLED` is not set or `false`
+
+### HTTP Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/` | GET | Server info |
+| `/health` | GET | Health check |
+| `/mcp` | POST | MCP message endpoint |
+| `/mcp` | GET | SSE stream (with session) |
+| `/mcp` | DELETE | Close session |
+
+### Single-Tenant Mode
+
+For dedicated deployments with fixed credentials:
+
+```bash
+export OPENLOYALTY_API_URL="https://api.openloyalty.io"
+export OPENLOYALTY_API_TOKEN="your-token"
+export OPENLOYALTY_DEFAULT_STORE_CODE="default"
+openloyalty-mcp-http
+```
+
+### Multi-Tenant OAuth Mode
+
+For shared deployments where each user provides their own credentials:
+
+```bash
+export OAUTH_ENABLED=true
+export BASE_URL="https://your-server.com"
+export REDIS_URL="redis://localhost:6379"
+openloyalty-mcp-http
+```
+
+With OAuth enabled, additional endpoints are available:
+
+| Endpoint | Description |
+|----------|-------------|
+| `/authorize` | OAuth authorization form |
+| `/token` | Token exchange |
+| `/register` | Dynamic client registration |
+| `/.well-known/oauth-authorization-server` | OAuth metadata |
+
+### ChatGPT Actions Integration
+
+To use with ChatGPT:
+
+1. Host the HTTP server with OAuth enabled
+2. In GPT Editor → Configure → Actions:
+   - Authentication: OAuth
+   - Authorization URL: `https://your-server.com/authorize`
+   - Token URL: `https://your-server.com/token`
+   - Scope: `mcp`
+3. Add your MCP endpoint: `https://your-server.com/mcp`
+
+Users will be prompted to enter their Open Loyalty credentials during the OAuth flow.
+
+---
+
 ## Development
 
 ```bash
-# Run in development mode
+# Run stdio server in development mode
 npm run dev
 
+# Run HTTP server in development mode
+npm run dev:http
+
 # Build for production
 npm run build
 
@@ -121,6 +231,8 @@ npm test
 npm run typecheck
 ```
 
+---
+
 ## Available Tools (112 total)
 
 ### Wallet Types (2 tools)
@@ -273,6 +385,8 @@ npm run typecheck
 - `openloyalty_export_get` - Get export status and details
 - `openloyalty_export_download` - Download export CSV (when status='done')
 
+---
+
 ## Example Workflows
 
 ### 1. Create 3-Tier Loyalty Program
@@ -649,6 +763,14 @@ openloyalty_import_create({
 openloyalty_import_get({ importId: "..." })
 ```
 
+---
+
+## Links
+
+- **GitHub**: [OpenLoyalty/openloyalty-mcp](https://github.com/OpenLoyalty/openloyalty-mcp)
+- **Open Loyalty**: [openloyalty.io](https://openloyalty.io)
+- **MCP Protocol**: [modelcontextprotocol.io](https://modelcontextprotocol.io)
+
 ## License
 
 MIT

package/dist/auth/provider.d.ts

@@ -0,0 +1,33 @@
+import type { OAuthServerProvider } from "@modelcontextprotocol/sdk/server/auth/provider.js";
+/**
+ * Open Loyalty API credentials stored per-client
+ */
+export interface OpenLoyaltyConfig {
+    apiUrl: string;
+    apiToken: string;
+    storeCode: string;
+}
+/**
+ * Creates the OAuth server provider
+ */
+export declare function createOAuthProvider(issuerUrl: string): OAuthServerProvider;
+/**
+ * Completes authorization after form submission
+ */
+export declare function completeAuthorization(sessionId: string, config: OpenLoyaltyConfig): Promise<{
+    redirectUrl: string;
+} | {
+    error: string;
+}>;
+/**
+ * Gets the Open Loyalty config for a client
+ */
+export declare function getClientConfig(clientId: string): Promise<OpenLoyaltyConfig | undefined>;
+/**
+ * Validates Open Loyalty credentials
+ * Uses the member list endpoint to validate both API token and store code
+ */
+export declare function validateOpenLoyaltyCredentials(config: OpenLoyaltyConfig): Promise<{
+    valid: boolean;
+    error?: string;
+}>;

package/dist/auth/provider.js

@@ -0,0 +1,395 @@
+import crypto from "crypto";
+import { getStorage, KEYS } from "./storage.js";
+// Expiration times
+const AUTH_CODE_TTL_MS = 10 * 60 * 1000; // 10 minutes
+const ACCESS_TOKEN_TTL_MS = 60 * 60 * 1000; // 1 hour
+const CLIENT_TTL_MS = 365 * 24 * 60 * 60 * 1000; // 1 year
+const CONFIG_TTL_MS = 365 * 24 * 60 * 60 * 1000; // 1 year
+/**
+ * Storage-backed OAuth clients store
+ */
+class StorageClientsStore {
+    async getClient(clientId) {
+        const storage = getStorage();
+        const client = await storage.get(KEYS.client(clientId));
+        return client ?? undefined;
+    }
+    async registerClient(client) {
+        const storage = getStorage();
+        const clientId = crypto.randomBytes(16).toString("hex");
+        const clientIdIssuedAt = Math.floor(Date.now() / 1000);
+        const fullClient = {
+            ...client,
+            client_id: clientId,
+            client_id_issued_at: clientIdIssuedAt,
+        };
+        await storage.set(KEYS.client(clientId), fullClient, CLIENT_TTL_MS);
+        return fullClient;
+    }
+}
+/**
+ * Creates the OAuth server provider
+ */
+export function createOAuthProvider(issuerUrl) {
+    const clientsStore = new StorageClientsStore();
+    return {
+        get clientsStore() {
+            return clientsStore;
+        },
+        /**
+         * Handles authorization by showing a configuration form
+         */
+        async authorize(client, params, res) {
+            const storage = getStorage();
+            // Generate session ID to track this authorization flow
+            const sessionId = crypto.randomBytes(16).toString("hex");
+            // Store the pending authorization
+            const sessionData = {
+                clientId: client.client_id,
+                redirectUri: params.redirectUri,
+                codeChallenge: params.codeChallenge,
+                state: params.state,
+                scope: params.scopes?.join(" "),
+                expiresAt: Date.now() + AUTH_CODE_TTL_MS,
+            };
+            await storage.set(KEYS.session(sessionId), sessionData, AUTH_CODE_TTL_MS);
+            // Render the configuration form
+            const html = renderAuthorizationForm({
+                sessionId,
+                state: params.state,
+                clientName: client.client_name || "ChatGPT",
+                issuerUrl,
+            });
+            res.setHeader("Content-Type", "text/html");
+            res.send(html);
+        },
+        /**
+         * Returns the code challenge for a given authorization code
+         */
+        async challengeForAuthorizationCode(_client, authorizationCode) {
+            const storage = getStorage();
+            const codeData = await storage.get(KEYS.authCode(authorizationCode));
+            if (!codeData || codeData.expiresAt < Date.now()) {
+                await storage.delete(KEYS.authCode(authorizationCode));
+                throw new Error("Authorization code not found or expired");
+            }
+            return codeData.codeChallenge;
+        },
+        /**
+         * Exchanges authorization code for tokens
+         */
+        async exchangeAuthorizationCode(client, authorizationCode) {
+            const storage = getStorage();
+            const codeData = await storage.get(KEYS.authCode(authorizationCode));
+            if (!codeData || codeData.expiresAt < Date.now()) {
+                await storage.delete(KEYS.authCode(authorizationCode));
+                throw new Error("Authorization code not found or expired");
+            }
+            if (codeData.clientId !== client.client_id) {
+                throw new Error("Authorization code was not issued to this client");
+            }
+            // Delete the code (one-time use)
+            await storage.delete(KEYS.authCode(authorizationCode));
+            // Store the client config if provided
+            if (codeData.pendingConfig) {
+                await storage.set(KEYS.config(client.client_id), codeData.pendingConfig, CONFIG_TTL_MS);
+            }
+            // Generate access token
+            const accessToken = crypto.randomBytes(32).toString("hex");
+            const expiresAt = Date.now() + ACCESS_TOKEN_TTL_MS;
+            const tokenData = {
+                clientId: client.client_id,
+                scope: codeData.scope,
+                expiresAt,
+            };
+            await storage.set(KEYS.token(accessToken), tokenData, ACCESS_TOKEN_TTL_MS);
+            return {
+                access_token: accessToken,
+                token_type: "Bearer",
+                expires_in: Math.floor(ACCESS_TOKEN_TTL_MS / 1000),
+                scope: codeData.scope,
+            };
+        },
+        /**
+         * Exchanges refresh token (not supported)
+         */
+        async exchangeRefreshToken() {
+            throw new Error("Refresh tokens are not supported");
+        },
+        /**
+         * Verifies an access token
+         */
+        async verifyAccessToken(token) {
+            const storage = getStorage();
+            const tokenData = await storage.get(KEYS.token(token));
+            if (!tokenData) {
+                throw new Error("Invalid access token");
+            }
+            if (tokenData.expiresAt < Date.now()) {
+                await storage.delete(KEYS.token(token));
+                throw new Error("Access token has expired");
+            }
+            return {
+                token,
+                clientId: tokenData.clientId,
+                scopes: tokenData.scope ? tokenData.scope.split(" ") : [],
+                expiresAt: Math.floor(tokenData.expiresAt / 1000),
+            };
+        },
+    };
+}
+/**
+ * Completes authorization after form submission
+ */
+export async function completeAuthorization(sessionId, config) {
+    const storage = getStorage();
+    const sessionData = await storage.get(KEYS.session(sessionId));
+    if (!sessionData || sessionData.expiresAt < Date.now()) {
+        await storage.delete(KEYS.session(sessionId));
+        return { error: "Session expired. Please start the authorization process again." };
+    }
+    // Delete session
+    await storage.delete(KEYS.session(sessionId));
+    // Generate authorization code
+    const authorizationCode = crypto.randomBytes(32).toString("hex");
+    // Store with pending config
+    const codeData = {
+        ...sessionData,
+        pendingConfig: config,
+        expiresAt: Date.now() + AUTH_CODE_TTL_MS,
+    };
+    await storage.set(KEYS.authCode(authorizationCode), codeData, AUTH_CODE_TTL_MS);
+    // Build redirect URL
+    const redirectUrl = new URL(sessionData.redirectUri);
+    redirectUrl.searchParams.set("code", authorizationCode);
+    if (sessionData.state) {
+        redirectUrl.searchParams.set("state", sessionData.state);
+    }
+    return { redirectUrl: redirectUrl.toString() };
+}
+/**
+ * Gets the Open Loyalty config for a client
+ */
+export async function getClientConfig(clientId) {
+    const storage = getStorage();
+    const config = await storage.get(KEYS.config(clientId));
+    return config ?? undefined;
+}
+/**
+ * Validates Open Loyalty credentials
+ * Uses the member list endpoint to validate both API token and store code
+ */
+export async function validateOpenLoyaltyCredentials(config) {
+    try {
+        // Use member list endpoint with limit=1 to validate credentials
+        // This validates both the API token and the store code existence
+        const response = await fetch(`${config.apiUrl}/${config.storeCode}/member?_itemsOnPage=1`, {
+            method: "GET",
+            headers: {
+                "Content-Type": "application/json",
+                "X-AUTH-TOKEN": config.apiToken,
+            },
+        });
+        if (response.status === 401) {
+            return { valid: false, error: "Invalid API token" };
+        }
+        if (response.status === 403) {
+            return { valid: false, error: "API token does not have required permissions" };
+        }
+        if (response.status === 404) {
+            return { valid: false, error: "Store code not found or invalid API URL" };
+        }
+        if (!response.ok) {
+            return { valid: false, error: `API returned status ${response.status}` };
+        }
+        return { valid: true };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return { valid: false, error: `Failed to connect: ${message}` };
+    }
+}
+/**
+ * Renders the authorization form HTML
+ */
+function renderAuthorizationForm(params) {
+    const { sessionId, state, clientName, issuerUrl } = params;
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Connect to Open Loyalty</title>
+  <style>
+    * { box-sizing: border-box; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+      min-height: 100vh;
+      margin: 0;
+      padding: 20px;
+      display: flex;
+      justify-content: center;
+      align-items: center;
+    }
+    .container {
+      background: white;
+      border-radius: 16px;
+      box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25);
+      padding: 40px;
+      width: 100%;
+      max-width: 420px;
+    }
+    h1 {
+      color: #1a1a2e;
+      font-size: 24px;
+      text-align: center;
+      margin: 0 0 8px 0;
+    }
+    .subtitle {
+      color: #6b7280;
+      text-align: center;
+      font-size: 14px;
+      margin-bottom: 32px;
+    }
+    .client-name { color: #667eea; font-weight: 500; }
+    .form-group { margin-bottom: 20px; }
+    label {
+      display: block;
+      color: #374151;
+      font-size: 14px;
+      font-weight: 500;
+      margin-bottom: 6px;
+    }
+    input {
+      width: 100%;
+      padding: 12px 16px;
+      border: 2px solid #e5e7eb;
+      border-radius: 8px;
+      font-size: 14px;
+    }
+    input:focus {
+      outline: none;
+      border-color: #667eea;
+    }
+    .help-text {
+      color: #6b7280;
+      font-size: 12px;
+      margin-top: 4px;
+    }
+    button {
+      width: 100%;
+      padding: 14px 24px;
+      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+      color: white;
+      border: none;
+      border-radius: 8px;
+      font-size: 16px;
+      font-weight: 600;
+      cursor: pointer;
+    }
+    button:hover { opacity: 0.9; }
+    button:disabled { opacity: 0.7; cursor: not-allowed; }
+    .error {
+      background: #fef2f2;
+      border: 1px solid #fecaca;
+      color: #dc2626;
+      padding: 12px;
+      border-radius: 8px;
+      margin-bottom: 20px;
+      display: none;
+    }
+    .error.visible { display: block; }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <h1>Connect to Open Loyalty</h1>
+    <p class="subtitle">
+      <span class="client-name">${escapeHtml(clientName)}</span> wants to access your Open Loyalty account
+    </p>
+
+    <div id="error" class="error"></div>
+
+    <form id="authForm">
+      <input type="hidden" name="session_id" value="${escapeHtml(sessionId)}">
+      ${state ? `<input type="hidden" name="state" value="${escapeHtml(state)}">` : ""}
+
+      <div class="form-group">
+        <label for="apiUrl">API URL</label>
+        <input type="url" id="apiUrl" name="api_url" placeholder="https://api.openloyalty.io" required>
+        <p class="help-text">Your Open Loyalty API endpoint</p>
+      </div>
+
+      <div class="form-group">
+        <label for="apiToken">API Token</label>
+        <input type="password" id="apiToken" name="api_token" required>
+        <p class="help-text">From your Open Loyalty admin panel</p>
+      </div>
+
+      <div class="form-group">
+        <label for="storeCode">Store Code</label>
+        <input type="text" id="storeCode" name="store_code" value="default" required>
+        <p class="help-text">Usually "default"</p>
+      </div>
+
+      <button type="submit" id="submitBtn">Connect Account</button>
+    </form>
+  </div>
+
+  <script>
+    const form = document.getElementById('authForm');
+    const errorEl = document.getElementById('error');
+    const submitBtn = document.getElementById('submitBtn');
+
+    form.addEventListener('submit', async (e) => {
+      e.preventDefault();
+      errorEl.classList.remove('visible');
+      submitBtn.disabled = true;
+      submitBtn.textContent = 'Connecting...';
+
+      try {
+        const formData = new FormData(form);
+        const response = await fetch('${issuerUrl}/authorize/submit', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            session_id: formData.get('session_id'),
+            state: formData.get('state'),
+            api_url: formData.get('api_url'),
+            api_token: formData.get('api_token'),
+            store_code: formData.get('store_code'),
+          }),
+        });
+
+        const result = await response.json();
+
+        if (result.redirect_url) {
+          window.location.href = result.redirect_url;
+        } else if (result.error) {
+          errorEl.textContent = result.error;
+          errorEl.classList.add('visible');
+          submitBtn.disabled = false;
+          submitBtn.textContent = 'Connect Account';
+        }
+      } catch (err) {
+        errorEl.textContent = 'Connection failed. Please try again.';
+        errorEl.classList.add('visible');
+        submitBtn.disabled = false;
+        submitBtn.textContent = 'Connect Account';
+      }
+    });
+  </script>
+</body>
+</html>`;
+}
+function escapeHtml(text) {
+    const escapes = {
+        "&": "&amp;",
+        "<": "&lt;",
+        ">": "&gt;",
+        '"': "&quot;",
+        "'": "&#39;",
+    };
+    return text.replace(/[&<>"']/g, (c) => escapes[c]);
+}

package/dist/auth/storage.d.ts

@@ -0,0 +1,16 @@
+export interface StorageBackend {
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T, ttlMs?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+/**
+ * Get the storage backend (Redis if available, otherwise in-memory)
+ */
+export declare function getStorage(): StorageBackend;
+export declare const KEYS: {
+    client: (id: string) => string;
+    authCode: (code: string) => string;
+    session: (id: string) => string;
+    token: (token: string) => string;
+    config: (clientId: string) => string;
+};