mcp-tenderly: Instructions file for Claude Code

mcp-tenderly

MCP server exposing Tenderly transaction simulation and trace debugging over the stdio transport. See README.md for user-facing setup and the tool reference.

Commands

npm run verify     # everything CI runs, in CI's order
npm test           # unit tests (excludes the stdio smoke test)
npm run test:smoke # builds, then drives dist/index.js over a real stdio transport
npm run typecheck
npm run lint

Layout

src/
  index.ts            entry point: config, stdio transport, signals
  server.ts           builds the McpServer and registers tools
  config.ts           the only module that reads process.env
  logger.ts           structured NDJSON logging to stderr
  errors.ts           error taxonomy, retriable vs terminal, remediation text
  tenderly/
    client.ts         REST client: auth, timeout, bounded retry
    schemas.ts        zod shapes for every response
    format.ts         payload to LLM-readable digest  <- the point of the server
    networks.ts       chain name to chain id
  tools/
    common.ts         shared input schemas, runTool boundary
    *.ts              one file per tool

Constraints worth knowing before you change anything

Stdout belongs to the protocol. Under stdio, stdout carries newline-delimited JSON-RPC frames. A single console.log anywhere in src/ corrupts the framing and the host silently drops the server. All diagnostics go through logger.ts, which writes to stderr. tests/stdio-smoke.test.ts asserts that stdout contains nothing but valid frames — that test exists specifically to catch this.

Response schemas are intentionally lenient. Every response shape in schemas.ts is a z.looseObject with almost every field optional. This is not laziness. The Tenderly API is not version-locked, and its payloads genuinely differ between simulation_type values, between /simulate and /simulations/{id}, and between verified and unverified contracts. Strict parsing would turn a harmless new field or an absent optional block into a hard tool failure — much worse than a formatter rendering "unknown" for one line. The invariant that is kept: nothing reaches the formatter without passing a schema, so the formatter never indexes into any.