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