# anaplan-user-mcp

A business-user-focused [MCP server](https://modelcontextprotocol.io) for [Anaplan](https://www.anaplan.com) — read-only, session-cached, and gated by AI-layer metadata.

Unlike full-featured Anaplan MCP servers with dozens of tools, **anaplan-user-mcp** exposes just **5 tools** designed for guided data exploration by business users through an AI assistant.

## How It Works

### The Iron Door

Not every Anaplan model is accessible. A model must be explicitly prepared for AI consumption by including two sentinel modules:

- **AI Model Metadata** — marks the model as AI-accessible
- **AI Module Metadata** — defines which modules are exposed

Within admitted models, only line items tagged with **AI LI Metadata** appear. Everything else is invisible. No writes, no bulk actions, no admin operations — read-only by design.

### Session Flow

```
identify_user → init_session → list_accessible_models → read_module_summary / read_module_detail
```

1. **identify_user** — discover which workspaces the credentials can access
2. **init_session** — scan all models, admit those passing the iron door, cache metadata
3. **list_accessible_models** — browse the cached models
4. **read_module_summary** — one-call rollup: resolves list dimensions to top-level items, reads aggregated data
5. **read_module_detail** — drill into a specific dimension slice

## Setup

### Prerequisites

- Node.js 18+
- Anaplan credentials (any of: username/password, OAuth client, or certificate)

### Install

```bash
git clone https://github.com/larasrinath/anaplan-user-mcp.git
cd anaplan-user-mcp
npm install
npm run build
```

### Configure Credentials

Set one of these authentication methods via environment variables:

**Basic Auth:**
```bash
export ANAPLAN_USERNAME="your-email@example.com"
export ANAPLAN_PASSWORD="your-password"
```

**OAuth:**
```bash
export ANAPLAN_CLIENT_ID="your-client-id"
export ANAPLAN_CLIENT_SECRET="your-client-secret"  # optional for device grant
```

**Certificate:**
```bash
export ANAPLAN_CERTIFICATE_PATH="/path/to/cert.pem"
export ANAPLAN_PRIVATE_KEY_PATH="/path/to/key.pem"
```

### Add to Your MCP Client

**Claude Desktop / Claude Code** — add to your MCP config:

```json
{
  "mcpServers": {
    "anaplan-user": {
      "command": "node",
      "args": ["/path/to/anaplan-user-mcp/dist/index.js"],
      "env": {
        "ANAPLAN_USERNAME": "your-email@example.com",
        "ANAPLAN_PASSWORD": "your-password"
      }
    }
  }
}
```

**Or run directly:**
```bash
npm start
```

The server communicates over stdio using the MCP protocol.

## Development

```bash
npm run dev          # Run with tsx (no build step)
npm run build        # Compile TypeScript → dist/
npm run typecheck    # Type-check without emitting
```

## Architecture

```
src/
├── auth/            # Token lifecycle (basic, certificate, OAuth)
├── api/             # Read-only Anaplan API wrappers
├── session/         # Iron-door cache (types + SessionCacheManager)
├── tools/           # 5 MCP tools + table formatter
├── transport/       # stdio transport (content-length + line framing)
├── server.ts        # McpServer factory
└── index.ts         # Entry point
```

The auth layer, HTTP client, and transport are shared with [anaplan-mcp](https://github.com/larasrinath/anaplan-mcp). API modules have write methods removed.

## Preparing an Anaplan Model

For a model to be accessible through this server:

1. Create a module named **AI Model Metadata** in the model
2. Create a module named **AI Module Metadata** in the model
3. Tag line items you want to expose with **AI LI Metadata**

Only tagged line items in models with both sentinel modules will appear in the session cache.

## License

[MIT](LICENSE)