itr-agent: Instructions file for Claude Code

CLAUDE.md

This file stacks on top of the workspace root at C:\Code\GitHub\:

• Root CLAUDE.md -- voice, rules, routing map, references, skills, slash commands, conventions.
• Root MEMORY.md -- live facts across repos.
• Root STATUS.md -- live PR/CI/security dashboard.
• .claude/resources/ -- deep reference for collaboration, workflow, git, OSS, debugging, voice.

Read those first. The guidance below only adds repo-specific context -- it does not override anything in the root.

Project

Local-first MCP server for Indian income tax (FY 2025-26 / AY 2026-27): deterministic tax engine + document parsers exposed as MCP tools over stdio. Public OSS, npm package itr-agent. Positioning: privacy-first -- everything runs on-device, unlike cloud finance MCPs (Fi/INDmoney).

Stack

• Language: TypeScript 7 (strict, ESM, NodeNext)
• Framework: @modelcontextprotocol/sdk 1.30 (stdio transport only), zod 4
• Database: none -- rule packs are JSON files in data/
• Package manager: pnpm
• Deploy target: npm registry (npx -y itr-agent); .mcpb Desktop bundle planned

Run

pnpm install
pnpm build
node dist/index.js        # stdio MCP server
pnpm inspect              # MCP inspector UI

Test

pnpm test         # engine golden cases + in-memory MCP client round trips (121 tests)
pnpm lint         # biome
pnpm typecheck    # two configs: tsconfig.json (src) + tsconfig.test.json (src + tests)

pnpm typecheck runs twice on purpose: tsconfig.json carries the build's rootDir/outDir/declaration settings and excludes tests/, so without the second config the test suite is never typechecked and a stale call signature only shows up at runtime.

Entry points

• src/index.ts -- stdio bootstrap (banner adds the shebang via tsup)
• src/server.ts -- all tool registrations (the MCP surface)

Key files

• src/engine/compute.ts -- the tax engine: slabs (incl. senior/super-senior slab sets), 87A + marginal relief, CG rates with the s.111A/s.112A(2) basic-exemption set-off, surcharge with its own marginal relief, cess, s.288A/288B rounding. Pure functions; the LLM never does arithmetic
• data/fy2025-26.json -- rule pack: EVERY tax constant lives here, never inline in code. validatePack() in rulepack.ts throws at load time if a pack is missing a section the engine reads, which is why the config fields are required rather than optional-with-a-code-fallback
• src/parsers/form26as.ts -- caret-delimited TRACES text parser (tolerant, warnings[] over throws). Amounts are read POSITIONALLY from the cells after the section code, never by filtering for numeric-looking cells: a blank cell shifts that window and silently mis-assigns amount paid / TDS deducted / TDS deposited
• tests/engine.test.ts -- golden cases pinned to published worked examples plus statute-pinned surcharge, age-band, and rounding cases
• docs/v0.2-spec.md -- researched design + statutory citations, NOT a description of shipped behaviour. It predates the v0.2 code and roughly half of it was never built (Form 16 PDF parsing, the AIS CSV fallback, the SFT lookup, reconcile H2/M2/L1/L2, the whitelist engine). Every section carries a status marker; the table at the top is the index. Update those markers whenever one of those items lands