@atlas-kitchen/atlas-mcp 1.0.0

package/.env.example

@@ -0,0 +1,8 @@
+# Atlas GraphQL base URL (production by default)
+ATLAS_GRAPHQL_ENDPOINT=https://atlas-api.food.wearelion.com
+
+# Client identification headers
+ATLAS_CLIENT_NAME=atlas-mcp-1.0.0
+
+# Optional: Override default Atlas endpoint for development
+# ATLAS_GRAPHQL_ENDPOINT=http://localhost:3000

package/CLAUDE.md

@@ -0,0 +1,135 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Atlas MCP Server - A Model Context Protocol (MCP) server that provides integration with the Atlas restaurant management system's GraphQL API. This server enables Claude to interact with restaurant orders, menus, sales reports, and other restaurant management features.
+
+## Development Commands
+
+### Setup
+```bash
+npm install
+cp .env.example .env  # Configure with your Atlas credentials
+```
+
+### Build & Run
+```bash
+npm run build    # Compile TypeScript to dist/
+npm run dev      # Run source directly with tsx (development)
+npm start        # Run compiled JavaScript (production)
+```
+
+### Requirements
+- Node.js >= 18.0.0 (required for native fetch and Headers APIs)
+- Environment variables configured in .env file
+
+## Architecture
+
+### Core Structure
+```
+src/
+├── index.ts      # MCP server setup and tool registration
+├── auth.ts       # Authentication state manager (JWT tokens)
+├── client.ts     # GraphQL client wrapper with auth handling
+├── types/        # TypeScript type definitions
+└── tools/        # MCP tool implementations by domain
+```
+
+### Key Components
+
+1. **Authentication Manager** (auth.ts)
+   - Stateful JWT token management
+   - Automatic token refresh on 401 errors
+   - Multi-merchant context switching
+
+2. **GraphQL Client** (client.ts)
+   - Wrapper around graphql-request
+   - Automatic auth header injection
+   - Error handling with retry on auth failures
+
+3. **Tool Organization**
+   - `tools/auth.ts` - Login, logout, token refresh, merchant switching
+   - `tools/orders.ts` - Order and cart management
+   - `tools/menu.ts` - Menu and item queries
+   - `tools/reports.ts` - Sales analytics and insights
+
+### Authentication Flow
+1. Use `atlas_login` tool with email/password
+2. Tokens are stored in AuthManager singleton
+3. All subsequent API calls use stored tokens
+4. On 401, automatically attempts token refresh
+5. Use `atlas_switch_merchant` to change merchant context
+
+### IMPORTANT: Outlet Context Requirements
+Many API endpoints require an outlet context to be set. Always use `atlas_switch_merchant` with an `outletId` after login:
+
+```javascript
+// After login, switch to a merchant WITH an outlet ID
+atlas_switch_merchant({ 
+  merchantId: "1", 
+  outletId: "1"  // REQUIRED for many endpoints!
+})
+```
+
+**Endpoints that REQUIRE outlet context:**
+- `atlas_get_pos_carts` - Uses `context[:current_outlet].id` in backend
+- `atlas_get_product_insights` - Needs outlet context for data filtering
+- Most POS-related operations
+
+**Common error if outlet not set:**
+- 500 server error
+- GraphQL execution errors
+
+Always check if an endpoint is returning 500 errors - it likely needs outlet context!
+
+### GraphQL Endpoint
+Default: `https://api.atlas.kitchen`
+Configurable via `ATLAS_GRAPHQL_ENDPOINT` environment variable (base URL only, paths are appended automatically)
+
+## Type Safety
+
+All GraphQL operations use TypeScript types defined in `src/types/atlas.ts`. When adding new queries/mutations:
+1. Define input/output types in atlas.ts
+2. Use Zod schemas for runtime validation of tool inputs
+3. Ensure GraphQL fragments match expected response types
+
+## Common Development Tasks
+
+### Adding a New Tool
+1. Create tool definition in appropriate file under `src/tools/`
+2. Define Zod schema for input validation
+3. Implement GraphQL query/mutation
+4. Add corresponding TypeScript types in `src/types/atlas.ts`
+5. Register tool in `src/index.ts`
+
+### Debugging GraphQL Requests
+The GraphQL client logs errors to console. Check for:
+- Authentication failures (401)
+- GraphQL validation errors
+- Network connectivity issues
+
+### Testing Authentication
+```bash
+# Start in dev mode
+npm run dev
+
+# In Claude, test login
+# Use atlas_login tool with valid credentials
+# Then test other tools like atlas_get_orders
+```
+
+## Environment Variables
+
+Required in .env:
+- `ATLAS_GRAPHQL_ENDPOINT` - GraphQL API endpoint (optional, has default)
+- `ATLAS_CLIENT_NAME` - Client identifier for API requests
+- `ATLAS_PLATFORM` - Platform identifier (defaults to "mcp")
+
+## Integration with Claude Code
+
+The server is configured via MCP settings. See README.md for the exact configuration needed. Key points:
+- Must use Node.js 18+ for the command path
+- Environment variables can be set in MCP config
+- For development, use tsx to run TypeScript directly

package/README.md

@@ -0,0 +1,161 @@
+# Atlas MCP Server
+
+An MCP (Model Context Protocol) server for integrating with the Atlas restaurant management system.
+
+## Requirements
+
+- Node.js 18.0.0 or higher (required for native fetch and Headers APIs)
+
+## Quick Start with npx
+
+The easiest way to use this MCP server is with npx (no installation required):
+
+```bash
+npx @atlas-kitchen/atlas-mcp
+```
+
+### Using with Claude Desktop
+
+Add this to your Claude Desktop MCP configuration:
+
+```json
+{
+  "atlas-mcp": {
+    "command": "npx",
+    "args": ["-y", "@atlas-kitchen/atlas-mcp"],
+    "env": {
+      "ATLAS_GRAPHQL_ENDPOINT": "https://api.atlas.kitchen/v1/restaurants/graphql",
+      "ATLAS_CLIENT_NAME": "atlas-mcp",
+      "ATLAS_PLATFORM": "mcp"
+    }
+  }
+}
+```
+
+### Environment Variables
+
+The following environment variables can be configured:
+
+- `ATLAS_GRAPHQL_ENDPOINT` - GraphQL API base URL (default: `https://api.atlas.kitchen`)
+- `ATLAS_CLIENT_NAME` - Client identifier for API requests (default: `atlas-mcp`)
+- `ATLAS_PLATFORM` - Platform identifier (default: `mcp`)
+
+## Local Installation
+
+```bash
+npm install atlas-mcp
+# or globally
+npm install -g atlas-mcp
+
+# Then run
+atlas-mcp
+```
+
+## Configuration
+
+### Environment Variables
+
+The server accepts the following environment variables:
+
+- `ATLAS_GRAPHQL_ENDPOINT` - Atlas GraphQL API endpoint (default: `https://atlas-api.food.wearelion.com/v1/restaurants/graphql`)
+- `ATLAS_CLIENT_NAME` - Client identifier for API requests (default: `atlas-mcp`)
+- `ATLAS_PLATFORM` - Platform identifier (default: `mcp`)
+
+### Local Development
+
+For local development, copy `.env.example` to `.env` and configure as needed:
+
+```bash
+cp .env.example .env
+```
+
+## Adding to Claude Desktop
+
+To use this MCP server with Claude Desktop, update your configuration file:
+
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`  
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+### Option 1: Using npx (Recommended)
+
+```json
+{
+  "mcpServers": {
+    "atlas-mcp": {
+      "command": "npx",
+      "args": ["-y", "@atlas-kitchen/atlas-mcp"],
+      "env": {
+        "ATLAS_GRAPHQL_ENDPOINT": "https://atlas-api.food.wearelion.com/v1/restaurants/graphql",
+        "ATLAS_CLIENT_NAME": "atlas-mcp",
+        "ATLAS_PLATFORM": "mcp"
+      }
+    }
+  }
+}
+```
+
+### Option 2: Local Development
+
+For development with source code:
+
+```json
+{
+  "mcpServers": {
+    "atlas-mcp": {
+      "command": "npx",
+      "args": ["tsx", "/path/to/atlas-mcp/src/index.ts"],
+      "env": {
+        "ATLAS_GRAPHQL_ENDPOINT": "https://atlas-api.food.wearelion.com/v1/restaurants/graphql",
+        "ATLAS_CLIENT_NAME": "atlas-mcp",
+        "ATLAS_PLATFORM": "mcp"
+      }
+    }
+  }
+}
+```
+
+**Note:** Ensure you have Node.js 18+ installed. You can verify with `node --version`.
+
+## Development
+
+```bash
+npm run dev
+```
+
+## Building
+
+```bash
+npm run build
+```
+
+## Available Tools
+
+### Authentication
+- `atlas_login` - Login to Atlas with email/password
+- `atlas_logout` - Logout and clear authentication
+- `atlas_refresh_token` - Refresh access token
+- `atlas_switch_merchant` - Switch active merchant context (⚠️ **IMPORTANT**: Always provide `outletId` for POS operations)
+
+### Usage Example
+```javascript
+// 1. Login first
+atlas_login({ email: "user@example.com", password: "password" })
+
+// 2. CRITICAL: Switch merchant WITH outlet ID
+atlas_switch_merchant({ 
+  merchantId: "1", 
+  outletId: "1"  // Required for POS carts, product insights, etc.
+})
+
+// 3. Now you can use POS endpoints
+atlas_get_pos_carts()
+```
+- `atlas_get_orders` - List orders with filters
+- `atlas_get_order` - Get detailed order information
+- `atlas_get_cart` - Get cart information
+- `atlas_get_pos_carts` - List open POS carts
+- `atlas_get_menus` - List available menus
+- `atlas_get_optimized_menus` - Get optimized menu structure with sections and items
+- `atlas_get_items` - List menu items
+- `atlas_get_sales_report` - Get sales analytics
+- `atlas_get_product_insights` - Product performance data

package/dist/auth.d.ts

@@ -0,0 +1,24 @@
+import { AuthTokens } from './types/atlas.js';
+export declare class AuthManager {
+    private tokens;
+    private merchantId;
+    private outletId;
+    private brandId;
+    private clientUuid;
+    private pinToken;
+    constructor();
+    setTokens(tokens: AuthTokens): void;
+    getTokens(): AuthTokens | null;
+    getAccessToken(): string | null;
+    setPinToken(pinToken: string): void;
+    getPinToken(): string | null;
+    setMerchantContext(merchantId: string, outletId?: string, brandId?: string): void;
+    getMerchantId(): string | null;
+    getOutletId(): string | null;
+    getBrandId(): string | null;
+    getClientUuid(): string;
+    getHeaders(): Record<string, string>;
+    clear(): void;
+    isAuthenticated(): boolean;
+}
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAiB,MAAM,kBAAkB,CAAC;AAG7D,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,OAAO,CAAuB;IACtC,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,QAAQ,CAAuB;;IAOvC,SAAS,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAInC,SAAS,IAAI,UAAU,GAAG,IAAI;IAI9B,cAAc,IAAI,MAAM,GAAG,IAAI;IAI/B,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAInC,WAAW,IAAI,MAAM,GAAG,IAAI;IAI5B,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAMjF,aAAa,IAAI,MAAM,GAAG,IAAI;IAI9B,WAAW,IAAI,MAAM,GAAG,IAAI;IAI5B,UAAU,IAAI,MAAM,GAAG,IAAI;IAI3B,aAAa,IAAI,MAAM;IAIvB,UAAU,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IA0BpC,KAAK,IAAI,IAAI;IAUb,eAAe,IAAI,OAAO;CAG3B"}

package/dist/auth.js

@@ -0,0 +1,78 @@
+import { v4 as uuidv4 } from 'uuid';
+export class AuthManager {
+    tokens = null;
+    merchantId = null;
+    outletId = null;
+    brandId = null;
+    clientUuid;
+    pinToken = null;
+    constructor() {
+        // Generate a persistent client UUID for this session
+        this.clientUuid = uuidv4();
+    }
+    setTokens(tokens) {
+        this.tokens = tokens;
+    }
+    getTokens() {
+        return this.tokens;
+    }
+    getAccessToken() {
+        return this.tokens?.accessToken || null;
+    }
+    setPinToken(pinToken) {
+        this.pinToken = pinToken;
+    }
+    getPinToken() {
+        return this.pinToken;
+    }
+    setMerchantContext(merchantId, outletId, brandId) {
+        this.merchantId = merchantId;
+        this.outletId = outletId || null;
+        this.brandId = brandId || null;
+    }
+    getMerchantId() {
+        return this.merchantId;
+    }
+    getOutletId() {
+        return this.outletId;
+    }
+    getBrandId() {
+        return this.brandId;
+    }
+    getClientUuid() {
+        return this.clientUuid;
+    }
+    getHeaders() {
+        const headers = {
+            'Content-Type': 'application/json',
+        };
+        // Add authorization header
+        if (this.tokens?.accessToken) {
+            headers['Authorization'] = `Bearer ${this.tokens.accessToken}`;
+        }
+        // Add merchant context headers
+        if (this.merchantId) {
+            headers['X-Merchant-ID'] = this.merchantId;
+        }
+        if (this.outletId) {
+            headers['X-Outlet-ID'] = this.outletId;
+        }
+        // Add client identification headers (matching restaurant-web format)
+        headers['X-Client-UUID'] = this.clientUuid;
+        headers['X-Client-Name'] = process.env.ATLAS_CLIENT_NAME || 'atlas-mcp-1.0.0';
+        return headers;
+    }
+    clear() {
+        this.tokens = null;
+        this.merchantId = null;
+        this.outletId = null;
+        this.brandId = null;
+        this.pinToken = null;
+        // Generate new client UUID on clear
+        this.clientUuid = uuidv4();
+    }
+    isAuthenticated() {
+        return this.tokens !== null && this.tokens.accessToken !== null;
+    }
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,EAAE,IAAI,MAAM,EAAE,MAAM,MAAM,CAAC;AAEpC,MAAM,OAAO,WAAW;IACd,MAAM,GAAsB,IAAI,CAAC;IACjC,UAAU,GAAkB,IAAI,CAAC;IACjC,QAAQ,GAAkB,IAAI,CAAC;IAC/B,OAAO,GAAkB,IAAI,CAAC;IAC9B,UAAU,CAAS;IACnB,QAAQ,GAAkB,IAAI,CAAC;IAEvC;QACE,qDAAqD;QACrD,IAAI,CAAC,UAAU,GAAG,MAAM,EAAE,CAAC;IAC7B,CAAC;IAED,SAAS,CAAC,MAAkB;QAC1B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,cAAc;QACZ,OAAO,IAAI,CAAC,MAAM,EAAE,WAAW,IAAI,IAAI,CAAC;IAC1C,CAAC;IAED,WAAW,CAAC,QAAgB;QAC1B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED,WAAW;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED,kBAAkB,CAAC,UAAkB,EAAE,QAAiB,EAAE,OAAgB;QACxE,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,QAAQ,GAAG,QAAQ,IAAI,IAAI,CAAC;QACjC,IAAI,CAAC,OAAO,GAAG,OAAO,IAAI,IAAI,CAAC;IACjC,CAAC;IAED,aAAa;QACX,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED,WAAW;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED,UAAU;QACR,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,aAAa;QACX,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED,UAAU;QACR,MAAM,OAAO,GAA2B;YACtC,cAAc,EAAE,kBAAkB;SACnC,CAAC;QAEF,2BAA2B;QAC3B,IAAI,IAAI,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC;YAC7B,OAAO,CAAC,eAAe,CAAC,GAAG,UAAU,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;QACjE,CAAC;QAED,+BAA+B;QAC/B,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACpB,OAAO,CAAC,eAAe,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC;QAC7C,CAAC;QAED,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,OAAO,CAAC,aAAa,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC;QACzC,CAAC;QAED,qEAAqE;QACrE,OAAO,CAAC,eAAe,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC;QAC3C,OAAO,CAAC,eAAe,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,iBAAiB,CAAC;QAE9E,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,KAAK;QACH,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QACvB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACrB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACrB,oCAAoC;QACpC,IAAI,CAAC,UAAU,GAAG,MAAM,EAAE,CAAC;IAC7B,CAAC;IAED,eAAe;QACb,OAAO,IAAI,CAAC,MAAM,KAAK,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC,WAAW,KAAK,IAAI,CAAC;IAClE,CAAC;CACF"}

package/dist/client.d.ts

@@ -0,0 +1,22 @@
+import { AuthManager } from './auth.js';
+export declare class AtlasClient {
+    private restaurantClient;
+    private accountClient;
+    private authManager;
+    private baseUrl;
+    constructor(authManager: AuthManager);
+    request<T = any>(query: string, variables?: any, context?: 'restaurants' | 'accounts'): Promise<T>;
+    login(email: string, password: string): Promise<any>;
+    logout(): Promise<any>;
+    refreshToken(refreshToken: string): Promise<any>;
+    getOrders(filters?: any): Promise<any>;
+    getOrder(orderId: string): Promise<any>;
+    getCart(cartId: string): Promise<any>;
+    getOpenPosCarts(): Promise<any>;
+    getMenus(outletId?: number, servingDate?: string, timeslotType?: string): Promise<any>;
+    getOptimizedMenus(outletId: number, servingDate: string): Promise<any>;
+    getItems(filter?: any): Promise<any>;
+    getSalesReport(filters: any, dateRange: any): Promise<any>;
+    getProductInsights(params: any): Promise<any>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAExC,qBAAa,WAAW;IACtB,OAAO,CAAC,gBAAgB,CAAgB;IACxC,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,OAAO,CAAS;gBAEZ,WAAW,EAAE,WAAW;IAS9B,OAAO,CAAC,CAAC,GAAG,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,GAAG,EAAE,OAAO,GAAE,aAAa,GAAG,UAA0B,GAAG,OAAO,CAAC,CAAC,CAAC;IAiBjH,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAqBpD,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC;IAatB,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAgDhD,SAAS,CAAC,OAAO,GAAE,GAAQ,GAAG,OAAO,CAAC,GAAG,CAAC;IAoF1C,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IA4WvC,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAoQrC,eAAe,IAAI,OAAO,CAAC,GAAG,CAAC;IAkC/B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAoCtF,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAsJtE,QAAQ,CAAC,MAAM,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;IAuDpC,cAAc,CAAC,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;IA2B1D,kBAAkB,CAAC,MAAM,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;CAsCpD"}