@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)

## Quick start with npx

```bash
npx @atlas-kitchen/atlas-mcp
```

### Using with Claude Desktop

Add this to your Claude Desktop MCP configuration:

```json
{
  "mcpServers": {
    "atlas-mcp": {
      "command": "npx",
      "args": ["-y", "@atlas-kitchen/atlas-mcp"],
      "env": {
        "ATLAS_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Environment variables

| Variable | Required | Description |
|---|---|---|
| `ATLAS_API_KEY` | Yes | API key for automatic authentication |
| `ATLAS_GRAPHQL_ENDPOINT` | No | GraphQL API base URL (default: `https://api.atlas.kitchen`) |
| `ATLAS_CLIENT_NAME` | No | Client identifier for API requests (default: `atlas-mcp-1.0.0`) |
| `ATLAS_MERCHANT_ID` | No | Default merchant ID on first run |
| `ATLAS_OUTLET_ID` | No | Default outlet ID on first run (defaults to `all`) |

## Authentication

The server authenticates automatically on startup using `ATLAS_API_KEY`. No manual login is needed.

- **Tokens are cached** to `~/.atlas-mcp/cache.json` and reused across restarts
- **Merchant/outlet context persists** across sessions until explicitly switched
- On auth failure, the server automatically refreshes tokens or re-authenticates

## Local development

```bash
npm install
cp .env.example .env  # Configure with your API key
npm run dev            # Run with tsx (development)
npm run build          # Compile TypeScript
npm start              # Run compiled JavaScript
```

### Local development config

```json
{
  "mcpServers": {
    "atlas-mcp": {
      "command": "npx",
      "args": ["tsx", "/path/to/atlas-mcp/src/index.ts"],
      "env": {
        "ATLAS_API_KEY": "your-api-key-here",
        "ATLAS_MERCHANT_ID": "1"
      }
    }
  }
}
```

### Pointing to a local backend

When iterating on Atlas APIs or developing new MCP tools, point the server to your local backend:

```json
{
  "mcpServers": {
    "atlas-mcp": {
      "command": "npx",
      "args": ["tsx", "/path/to/atlas-mcp/src/index.ts"],
      "env": {
        "ATLAS_API_KEY": "your-api-key-here",
        "ATLAS_GRAPHQL_ENDPOINT": "http://localhost:3000",
        "ATLAS_MERCHANT_ID": "1"
      }
    }
  }
}
```

The server appends `/graphql` automatically, so `http://localhost:3000` becomes `http://localhost:3000/graphql`.

**Tip:** After changing MCP config, restart Claude Desktop (or run `/exit` in Claude Code) to pick up the changes.

## Available tools

### Authentication
- `atlas_auth_status` - Show current authentication and merchant context
- `atlas_list_merchants` - List all merchants the user can access
- `atlas_list_outlets` - List outlets for the current merchant
- `atlas_switch_merchant` - Switch merchant context (fuzzy matches by name, identifier, or ID)

### Orders
- `atlas_get_orders` - List orders with filters (paginated, max 100 per page)
- `atlas_get_order` - Get detailed order information
- `atlas_get_cart` - Get cart details by ID
- `atlas_get_pos_carts` - List open POS carts (requires specific outlet)

### Menu
- `atlas_get_items` - Search and list item catalog (paginated, max 100 per page)

### Reports
- `atlas_get_sales_report` - Get sales analytics (max 90 day range)

## Publishing to npm

Releases are published automatically via GitHub Actions when you create a GitHub release.

### One-time setup

1. Go to [npmjs.com token settings](https://www.npmjs.com/settings/atlas-kitchen/tokens)
2. Create a **Granular Access Token** with **Read and write** permission on packages, scoped to `@atlas-kitchen`
3. In the GitHub repo, go to **Settings > Secrets and variables > Actions**
4. Add a secret named `NPM_TOKEN` with the token value

### Publishing a new version

```bash
npm run release         # patch: 1.1.0 → 1.1.1
npm run release:minor   # minor: 1.1.0 → 1.2.0
npm run release:major   # major: 1.1.0 → 2.0.0
```

This bumps the version, pushes the tag, and creates a GitHub release in one command. The GitHub Action then builds and publishes to npm automatically.

### CI

Pull requests and pushes to `main` run a build check across Node.js 18, 20, and 22.

### Usage example

```
# No login needed - authentication is automatic!

# Check current status
atlas_auth_status()

# Switch merchant by name (fuzzy matched)
atlas_switch_merchant({ merchant: "My Restaurant" })

# Switch merchant with specific outlet for POS
atlas_switch_merchant({ merchant: "My Restaurant", outletId: "5" })

# Query orders
atlas_get_orders({ startDate: "2026-01-01", endDate: "2026-01-31" })
```