agentleFS
Sagargupta16Sagargupta16/itr-agent/CLAUDE.md

itr-agent

CLAUDE.md10 starsChanged 3 days agoMITView on GitHub

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. Local-first MCP server for Indian income tax (FY 2025-26 /…

  • Installs packages

The file

We split this CLAUDE.md into the rules it gives an agent

3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Never add a network transport or telemetry -- local-only is the product.

    line 98
  2. Very specific:

    Every new tool: annotations: { readOnlyHint: true, openWorldHint: false }, zod-described inputs, structuredContent output, disclaimers on …

    line 100
  3. Very specific:

    Never commit anything to fixtures/ -- it is gitignored because it is where real 26AS/AIS documents land during manual parser checks.

    line 103

≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

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/server 2.4 (MCP SDK v2, stdio transport only; @modelcontextprotocol/client 2.4 is a dev dependency for tests and scripts), zod 4
  • Database: none -- rule packs are JSON files in data/
  • Package manager: pnpm
  • Deploy target: npm registry (npx -y itr-agent); .mcpb Claude Desktop bundle attached to each GitHub release (pnpm bundle)

Run

pnpm install
pnpm build
node dist/index.js        # stdio MCP server
pnpm inspect              # MCP inspector UI
pnpm bundle               # build/itr-agent-<version>.mcpb (Claude Desktop bundle)
node scripts/demo.mjs     # the README demo session against dist/

Test

pnpm test         # engine golden cases + in-memory MCP client round trips (280 tests)
pnpm lint         # biome
pnpm typecheck    # two configs: tsconfig.json (src) + tsconfig.test.json (src + tests)
pnpm validate     # docs/validation.md cases against dist/ (run pnpm build first); --write regenerates

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: 16 tools + 1 prompt)

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
  • data/fy2026-27.json -- tax year 2026-27 under the Income-tax Act 2025. Same shape; statute carries the Act, the 1961-to-2025 section map and the renumbered form names, and its note is appended to the disclaimers of every result computed with it (withStatuteNote in server.ts), because engine notes still cite 1961 section numbers. Its last sources entry names what is carried from 2025-26 until the TY 2026-27 forms are notified
  • src/engine/house-property.ts, presumptive.ts, loss-setoff.ts -- the heads the model used to work out by hand (s.23/24, s.44AD/44ADA/44AE, s.70-80). Each returns forComputeTax; resolveTaxInput in server.ts folds houses and presumptiveBusiness into compute_tax, compare_regimes and tax_summary per regime
  • src/engine/summary.ts -- tax_summary: tax, credits, s.234A/B/C from dates, s.234F, s.288B net. breakeven.ts (compare_regimes breakeven) and deadlines.ts (list_tax_years status) are pure; the server passes today's date in Asia/Kolkata
  • src/engine/dates.ts -- dates to interest months (Rule 119A(b), the pack's interest.partMonthIsFullMonth, and the s234A/s234B fromDate tokens). Tools take dates and count here; a month count from the caller is still accepted
  • 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
  • scripts/validation-cases.json -- source of docs/validation.md. Budget Speech rows are independent figures; statute rows carry their arithmetic in working. Any change to computed output must keep pnpm validate green, and the doc is generated, never hand-edited
  • scripts/build-mcpb.mjs -- the Desktop bundle. Inlines every dependency (noExternal; SDK v2 has no CommonJS dependency left, so the createRequire banner ajv needed under 1.x is gone), stages outside the repo so a missed dependency fails the build, and generates the manifest from the live tools/list, so there is no hand-kept tool list to drift
  • docs/diagrams/*.yaml -- the README's architecture and filing-flow diagrams, as orrery specs (github.com/Sagargupta16/orrery). The -light.svg / -dark.svg beside each are rendered output: change the YAML, re-render both themes (orrery render <spec> -o docs/diagrams/<name> -f svg --theme both), never hand-edit the SVG. Both pass orrery review --width 880
  • 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

Gotchas

  • stdout is the MCP channel -- all logging must go to stderr (console.error). One stray console.log breaks the protocol.
  • Rules key off TRANSACTION DATES, not just FY: 23-Jul-2024 (CG rate flip), 1-Apr-2023 (debt MF s50AA), 1-Oct-2024 (buyback deemed dividend). Keep date boundaries in the rule pack when those land.
  • 87A rebate NEVER offsets 111A/112A tax under the new regime (Finance Act 2025 second proviso) -- the engine applies it to normal-income slab tax only, driven by allowAgainst111A / allowAgainst112A in the pack. A mutation test in tests/engine.test.ts flips allowAgainst111A on and asserts the answer changes, so the claim is enforced and not just documented.
  • The 87A THRESHOLD tests TOTAL income in both regimes (thresholdBasis: "totalIncome", pack 1.4.0). Pack 1.3.0 had the new regime on normalIncome, which over-rebated anyone whose gains pushed total income past 12L; the statute's first proviso says "total income" in both clause (a) and clause (b). The contrary reading is a real practitioner position, so it stays encodable and compute_tax names the reading in disclaimers whenever gains are present.
  • parse_form26as: TCS collectors carry TANs exactly like deductors, so a part-header reset alone does NOT keep TCS out of tdsEntries. Rows are split by section (206C* -> tcsEntries). Booking status is the second cell after the section; only F is creditable and creditableTdsDeposited says so. Current 26AS layout: Part I TDS, Part II 15G/15H TDS, Part VI TCS, Part VII refunds; SFT/challans moved to AIS.
  • McpServer version comes from packageVersion() (reads package.json next to data/). Never hardcode it again; it drifted to 0.3.0 while the package was 0.4.0.
  • readDocument has an extension allow-list (.txt for 26AS, .json/.txt for AIS) and refuses dotfiles. path is otherwise an arbitrary-file-read for a prompt-injected client.
  • The senior / super-senior basic exemption is a SLAB SET (oldRegime.slabsSenior / slabsSuperSenior), never an income deduction. Subtracting it from income under-taxes by a whole slab and mis-states total income; the age-band tests pin taxableNormalIncome for exactly this reason.
  • Surcharge marginal relief compares tax PLUS surcharge at the band threshold against the actual figure (via a notional recomputation on income rolled back to the threshold). Comparing surcharge alone leaves the full amount standing just past a band edge.
  • The 25%/37% surcharge bands exclude 111A/112/112A/dividend income (First Schedule Part I Para A), so a taxpayer past Rs 2 crore purely on gains stays in the 15% band.
  • A house-property loss needs its type. Self-occupied: the loss IS the s.24(b) interest, capped at deductionCaps.24b_selfOccupied in the old regime and nil under s.115BAC(2)(i) (incometax.gov.in new-regime FAQ), and the excess is housePropertyLossDisallowed, never carried forward. Let-out: no cap, set off to the s.71(3A) limit, rest carried forward. The tools refuse a loss without housePropertyType; direct engine callers default to let-out. Until 0.6.0 a self-occupied 3L interest bill reported 3L (new) or 1L (old) "carried forward".
  • The model must not do glue arithmetic. reconcile_documents reads form26asPath and aisFile itself; parse_ais returns totals (per section/element/code group, and section-192 salary by TAN, TDS block only because Annexure-II salary repeats it). Interest and dividend groups are NAMED by the caller, never auto-summed: a bank can report the same interest as a TDS-194A row and again as an SFT row, and only the titles tell them apart.
  • Vitest collects only tests/**/*.test.ts and biome force-ignores **/.claude, because Claude Code session worktrees under .claude/worktrees/ once made pnpm test run a stale copy of the suite (302 tests) and pnpm lint fail on a nested root config.
  • SDK v2 ships under NEW package names (@modelcontextprotocol/server + @modelcontextprotocol/core; the client is @modelcontextprotocol/client), so @modelcontextprotocol/sdk stays on 1.x and its latest dist-tag never shows a 2.x -- checking that package alone is how an earlier note concluded v2 had not shipped. Migrated in 0.7.0 (2.4.0): the runtime install is server + core + zod (5 packages, was 92), which retired the hono / @hono/node-server / qs / ip-address / fast-uri overrides. Every registerTool inputSchema is z.object(shape) (a raw shape still works in v2 but is deprecated), the multi-field shapes stay hoisted as module-level consts, and a prompt with no arguments omits argsSchema instead of passing {}. Stdio: server @modelcontextprotocol/server/stdio, client @modelcontextprotocol/client/stdio; InMemoryTransport comes from either package root.
  • houses in compute_tax / compare_regimes / tax_summary is worked out PER REGIME (self-occupied interest is nil under s.115BAC(2)(i)), and the head loss goes into compute_tax as letOut, because house-property.ts has already applied the s.24(b) caps: selfOccupied would cap it a second time. Passing houses together with housePropertyLoss is refused. compare_regimes passes the old- and new-regime inputs to regimeBreakeven separately for the same reason.
  • tax_summary takes TDS from the 26AS file (creditable status F rows; TCS rows with status F or none) and refuses a 26AS whose assessment year is not the pack's. Its filing date and list_tax_years' asOf default to today in Asia/Kolkata (indiaToday), never the machine's own zone.
  • bin must be dist/index.js, never ./dist/index.js: npm 11 printed "script name ... was invalid and removed" for the ./ form during the v0.5.1 publish run. CI's publish dry-run step fails on any npm auto-correction.
  • npm reports a missing trusted-publisher link, a mismatched field in it, AND a link whose allowed actions stop at npm stage publish as the same bare E404 on the PUT (v0.5.1 and v0.5.3 both got it; the repo holds no npm token, gh secret list is empty). publish.yml therefore does the OIDC exchange itself first ("Check the npmjs.com trusted publisher link"): it prints the id-token claims npm matches and the registry's own answer. gh workflow run publish.yml runs every check and that diagnostic without publishing anything. Its answer on 2026-10-22 was package not found: no trusted publisher is saved. On 2026-11-13 npm trust github itr-agent ... failed E401 because the owner's npm login (sagargupta1610) had expired (npm whoami 401); after npm login it succeeded (permissions: publish, stage publish), and the dry run got exchange HTTP 201 with a token. A successful exchange is 201 Created, not 200: the check accepts any 2xx that carries a token. v0.6.0 was the first publish from the workflow (2026-11-13, + itr-agent@0.6.0, SLSA provenance). The registry's version endpoint then answered E404 for over 75 seconds, so the provenance wait is now five minutes, the npm publish step skips a version already on npm (a re-run goes straight to the registry steps), and the registry steps run whenever the publish step succeeded. gh workflow run publish.yml -f list_version=X.Y.Z lists an already-published version on the MCP registry without a release.
  • publish.yml installs without the pnpm cache in both jobs: a release build must not take dependencies from a cache another workflow wrote.
  • Workflow steps feed server output to node -e on stdin (printf '%s' "$out" | node -e '...readFileSync(0)...'), never as an argument. Windows caps a command line at 32,767 characters, and the tools/list reply (~30 KB, more once quotes are escaped) broke every windows-latest leg with exit 126 when it was passed as "$out".
  • data/ ships in the npm package (files field); resolveDataDir() in rulepack.ts probes both dist- and src-relative paths.
  • server.json (MCP registry manifest) carries the version TWICE -- top level and packages[0].version -- and both must equal package.json version and the release tag. publish.yml fails the release if they drift, or if server.json name stops matching package.json mcpName.
  • FY 2026-27 pack (Income-tax Act 2025, 30 of 2025, + Income-tax Rules 2026, G.S.R. 198(E) of 20-3-2026, in force 1 Apr 2026; read from the official Rules PDF on incometaxindia.gov.in): HRA metros go 4 -> 8 under Rule 279(1)(c) Table ("Mumbai, Kolkata, Delhi, Chennai, Hyderabad, Pune, Ahmedabad and Bengaluru" at 50%, any other place 40%; the salary definition in Rule 279(2)(b) is the old Fourth Schedule one, so daRetirement stays). Form 16 -> Form No. 130 (Rule 215(1) Table Sl. No. 1, due 15 June; with several employers each issues Parts A and B and any one issues Part C, Rule 215(2)). Form 12BB -> Form No. 124 (Rule 205; landlord PAN still above Rs 1,00,000). Form 10BA -> Form No. 31 (Rule 65; s.134 is the 80GG successor). AIS is Form No. 168 (Rule 245, s.510). Rule 119A survives verbatim as Rule 269 (floor to Rs 100, part month = full month). ITR-1 admits two house properties and LTCG under s.198 up to Rs 1,25,000 (Rule 164). The Rules carry no slab, rebate, surcharge or cess figure; those stay in the Act and the Finance Act. No rule for a 26AS successor was found in them, so check the portal before assuming parse_form26as has a FY 2026-27 input. Buyback reverts to capital gains (Finance Act 2026). Rule 164(14) keeps returns for FY 2025-26 and earlier on the forms of that year, so nothing in the 2026 Rules changes data/fy2025-26.json. The pack shipped in 0.7.0 as data/fy2026-27.json, read from the Act 2025 as amended by the Finance Act 2026 (incometaxindia.gov.in PDF, via r.jina.ai): s.202(1) slabs, s.19, s.156 (rebate; s.156(3) caps the s.202 rebate at tax at s.202(1) rates), ss.196-198, ss.21-22 and 109(1)(b), ss.110-113 and s.121 (the s.80 successor, house property excepted), s.58(2) Table and its heavy-vehicle Explanation, s.263(1)(c), s.428(a)/(b), s.516. Default year stays 2025-26 until those returns are filed.
  • s.234-I (Finance Act 2026 s.16, from 1 March 2026): a revised return filed after nine months pays Rs 1,000 (total income up to Rs 5 lakh) or Rs 5,000, the s.234F bands; it lives in the pack as fee234I, the s.234F threshold as lateFee234F.incomeThreshold.
  • Deadlines: itr3_4_nonAudit 2026-08-31 and revised 2027-03-31 are BOTH Finance Act 2026 and both correct -- a line-by-line review flagged them as wrong before the fact-check confirmed them. deadlineCitations in the pack carries the basis for each; keep it in step with deadlines.

Repo-specific rules

  • Never add a network transport or telemetry -- local-only is the product.
  • Tax constants only ever change via data/*.json + a CHANGELOG entry citing the source (Finance Act / CBDT circular / incometax.gov.in page).
  • Every new tool: annotations: { readOnlyHint: true, openWorldHint: false }, zod-described inputs, structuredContent output, disclaimers on anything that computes tax.
  • Parsers must be tolerant: collect warnings[], never throw on layout surprises; errors must name the fix ("download the Text format from TRACES").
  • Text output masks PAN; structuredContent does NOT (downstream tools need the real value). So "local-only" describes this server, not the whole stack -- the connected client still sees parsed contents. Say that plainly in docs rather than claiming the PAN never leaves the process.
  • Never commit anything to fixtures/ -- it is gitignored because it is where real 26AS/AIS documents land during manual parser checks.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.