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

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

# 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 API key
```

### 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)
- `ATLAS_API_KEY` environment variable (required for authentication)

## Architecture

### Core structure
```
src/
├── index.ts        # MCP server setup, auto-auth startup, tool registration
├── auth.ts         # Authentication state manager (JWT tokens, merchant context)
├── client.ts       # GraphQL client with auth retry and API key login
├── token-cache.ts  # Token + context persistence to ~/.atlas-mcp/cache.json
├── types/          # TypeScript type definitions
└── tools/          # MCP tool implementations by domain
```

### Key components

1. **Authentication Manager** (auth.ts)
   - Stateful JWT token management
   - Merchant/outlet context (outlet defaults to "all")

2. **Token Cache** (token-cache.ts)
   - Persists tokens + merchant/outlet context to `~/.atlas-mcp/cache.json`
   - Survives server restarts (like browser localStorage)

3. **GraphQL Client** (client.ts)
   - Wrapper around graphql-request
   - Automatic auth header injection
   - `onAuthFailure` callback for auto-retry on 401
   - `apiKeyLogin()` and `getMerchants()` methods

4. **Tool Organization**
   - `tools/auth.ts` - Merchant switching (fuzzy match), auth status
   - `tools/orders.ts` - Order and cart management
   - `tools/menu.ts` - Menu and item queries
   - `tools/reports.ts` - Sales analytics and insights

### Authentication flow
1. Server starts → loads cached tokens from `~/.atlas-mcp/cache.json`
2. If no cache → authenticates with `ATLAS_API_KEY` env var
3. Sets merchant context from cache or `ATLAS_MERCHANT_ID` / `ATLAS_OUTLET_ID` env vars
4. On 401 during any API call → refresh token → re-auth with API key → retry
5. No manual login needed - fully automatic

### Merchant context persistence
- Merchant and outlet IDs persist to `~/.atlas-mcp/cache.json`
- Switching merchant via `atlas_switch_merchant` updates the cache
- On restart, cached context is restored automatically
- `X-Outlet-ID` defaults to "all" unless explicitly set

### Outlet context requirements
Some endpoints require a specific outlet (not "all"):
- `atlas_get_pos_carts` - Requires specific outlet ID
- `atlas_get_product_insights` - Needs outlet context for data filtering

Use `atlas_switch_merchant` with an `outletId` parameter for these operations.

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

## 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 |
| `ATLAS_MERCHANT_ID` | No | Default merchant ID on first run |
| `ATLAS_OUTLET_ID` | No | Default outlet ID on first run |

## Publishing to npm

CI/CD is handled by GitHub Actions (`.github/workflows/`):

- **CI** (`ci.yml`): Builds on PRs and pushes to `main` across Node 18/20/22
- **Publish** (`publish.yml`): Publishes to npm when a GitHub release is created

### How to publish a new version

```bash
npm run release         # patch bump + push + GitHub release
npm run release:minor   # minor bump
npm run release:major   # major bump
```

### Required secret

`NPM_TOKEN` must be set in GitHub repo settings (Settings > Secrets > Actions). Create a Granular Access Token at https://www.npmjs.com/settings/atlas-kitchen/tokens with read/write package permissions scoped to `@atlas-kitchen`.

## 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
- Set `ATLAS_API_KEY` in MCP config env vars
- Optionally set `ATLAS_MERCHANT_ID` for auto-merchant selection
- For development, use tsx to run TypeScript directly