debug-log-analyzer-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.

Project Overview

An MCP server that analyses Salesforce Apex debug logs for performance bottlenecks, governor limit usage and optimization opportunities.

Development Commands

# Install dependencies
pnpm install

# Build the TypeScript project
pnpm run build

# Development with watch mode
pnpm run dev

# Run the server standalone
pnpm start

Architecture

Core Components

• src/index.ts: the bin entry point (dist/index.js). Parses flags, calls runStdioServer, nothing else. A bad flag exits 1 with one [apex-log-mcp] line, checked by pnpm run eval.
• src/server.ts: createApexLogServer, runStdioServer and parseServerConfig. Registers the eight tools over stdio, and takes no import side effects, so tests can import it without spawning a server.
• src/tools/responseShaping.ts: the shared response helpers - toonResult, omitEmpty, warningField, toLimitRows, toNamespaceLimitRows, limitUnitsClause, limitGatingCategory, LIMIT_GATING_CATEGORIES, roundMs, roundPercent, percentageOf, NS_TO_MS, NAME_LIMIT, and the page every analysis table stops at - fitPage, PAGE_CHAR_BUDGET, nextOffsetField - with the matches filter they share.
• src/tools/localFile.ts: absolutePathSchema, fileReadError, fsErrorWords and outsideRoots, shared by every tool that reads or writes a local file - a log or a file of Apex.
• src/tools/inputSchema.ts: toolInputSchema, which wraps every tool's parameters so a parameter the tool does not have is refused, and the parameters the org tools share, worded once: targetOrgSchema, outputDirSchema and levelsByCategorySchema.
• src/errors.ts: errorText, what a caught value says, and toolError, a tool's refusal or failure as a result.
• src/elide.ts: elide, elideAround and elideEnd, which cut over-long text without splitting a character.
• src/logLevels.ts: the debug log's categories and levels - DEBUG_CATEGORIES, TRACE_CATEGORIES, LOG_LEVELS, DEFAULT_TRACE_CONFIG - with the levels a call asks for, requestedLevels, and their wording, levelsClause; and declaredLevels and capturedAt, which read the levels a log's header declared. It needs no org, so the analysis tools import it; src/salesforce/debugLevels.ts writes DebugLevel records from it.
• src/tools/logStore.ts: openLogStore, writeDebugLog and saveStoredLog - where every org tool saves a log, and never over a different one - and unwritableLogDir, which refuses a directory before a step that cannot be undone, and creates nothing.
• src/tools/progress.ts: progressReporter, the progress notifications of a long org call, sent only to a caller that asked.
• src/tools/analysisTool.ts: defineAnalysisTool, which states an analysis tool once - its name, title, description, own parameters and a pure run(apexLog, args) - and adds logFilePath, the read-only annotations, the load and the TOON encoding. Test a tool through run on a parsed log; tests/analysisTool.test.ts tests the shell. src/tools/analysisTools.ts lists every analysis tool, for the server and the tests.
• src/salesforce/orgAccess.ts: OpenOrg, which a handler gets as open, is the one way an org tool reaches an org. It runs the roots, the local org, the identity deny, the connect, the type deny and, for a write, the production gate, for one call of one tool. bindOpenOrg makes it, and only src/server.ts calls bindOpenOrg.
• src/tools/*Definition.ts: an org tool's wire definition, { name, config }; one module can hold two tools. A write tool's definition is a function of the refusal and carries it, so registerOrgTool answers a refused call before the handler loads - copy a write tool, not a read tool, for a write. A definition loads at startup and loads no Salesforce SDK; the handler loads on its first call. A new org tool touches its definition, its handler, one registerOrgTool call in src/server.ts, its suite, which wires the handler through tests/support/wiredOrgTool.ts, the tool count and handler mocks in tests/server.test.ts, and a DEFINITION_BUDGET entry in scripts/eval.mjs. pnpm run eval names anything else it lacks, and pnpm run eval:update writes its README tables.
• src/apexLog/: the one module that imports the parser; an ESLint rule refuses it anywhere else. index.ts holds the parser's rules the tools share - textOf, countOf, ceilingOf, multipleLogsWarning, LOG_EVENT_ID, and the parser's DEFAULT_NAMESPACE, DEBUG_CATEGORY, DEBUG_CATEGORY_TOKEN, ENDED_BY, KIND, LEVEL, LIMIT_METRICS and eventType - and the readers of one event from log.columns: typeAt, frameTypeAt, namespaceAt, textAt, and totalAt for countOf(...).total; and isEventOf, which narrows an event so its details read as its type's. It also re-exports the parser types the tools read. A pass over every event reads log.columns, not event objects: the parser makes a new object on each read of an event. Each column reader takes its column, so a loop reads it from log.columns once; textAt alone takes the log. source.ts holds loadApexLog, the one way the analysis tools get a log. It caches the last parse against a stat fingerprint, shares one parse between concurrent callers, and drops it five minutes after its last use, because a parsed log holds one to two times the size of the file.
• @apexdevtools/apex-log-parser: the parser, as a dependency - nothing here parses a log. Every value, type and const comes from the package root. Read debugCategory for an event's category, never category: that one is a UI grouping slated for deprecation. Read isFrame for whether an event has a duration.