anaplan-user-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

npm run build        # TypeScript → dist/
npm run dev          # Run with tsx (no build step)
npm run typecheck    # tsc --noEmit
npm start            # node dist/index.js (requires build first)

Auth is configured via environment variables: ANAPLAN_USERNAME/ANAPLAN_PASSWORD, ANAPLAN_CLIENT_ID, or ANAPLAN_CERTIFICATE_PATH/ANAPLAN_PRIVATE_KEY_PATH. The server runs on stdio (MCP transport).

Architecture

This is a read-only, session-cached MCP server for Anaplan business users. It exposes 5 tools (not 68 like its sibling anaplan-mcp). The auth layer, HTTP client, transport, and format utility are copied verbatim from anaplan-mcp — the API files have write methods stripped.

Flow: index.ts → server.ts:createServer() → wires AuthManager.fromEnv() → AnaplanClient → API classes + SessionCacheManager → registers 5 tools via registerReportingTools().

Iron Door

The core design constraint. SessionCacheManager.init() scans all models and only admits those with both an "AI Model Metadata" and an "AI Module Metadata" module (case-insensitive includes). Within admitted models, only line items tagged "AI LI Metadata" are cached. All data tools check cache.isInitialized() and resolve against the cache — if a model/module isn't cached, the tool refuses.

Session Cache (src/session/)

SessionCacheManager holds a SessionCache in memory: ModelEntry[] → ModuleEntry[] → LineItemEntry[]. Populated once by init_session, then all tools read from it. Lookup methods: findModel(nameOrId), findModule(modelId, nameOrId), findLineItem(moduleId, nameOrId) — all case-insensitive name or exact ID match.

Tools (src/tools/reporting.ts)

Five tools registered on McpServer with Zod schemas:

• identify_user — workspaces list, no iron door
• init_session — populates cache, reports which models passed
• list_accessible_models — table from cache
• read_module_summary — compound: resolves list dimensions to topLevelItem from list metadata, reads cells via readCellsWithPages with auto-computed pages
• read_module_detail — same but accepts explicit pages: Record<string, string> for drill-down