@atlas-kitchen/atlas-mcp/README.md

Model Context Protocol server for Atlas restaurant management system - enables Claude to interact with restaurant orders, menus, and reports

# 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)
- If you encounter "fetch is not defined" errors, ensure you're using Node.js 18+ and not an older version

## 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