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
- Distinctive: line 98
Never add a network transport or telemetry -- local-only is the product.
- Very specific: line 100
Every new tool: annotations: { readOnlyHint: true, openWorldHint: false }, zod-described inputs, structuredContent output, disclaimers on …
- Very specific: line 103
Never commit anything to fixtures/ -- it is gitignored because it is where real 26AS/AIS documents land during manual parser checks.
≈ “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.
Files
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);.mcpbClaude 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 regeneratespnpm 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 arithmeticdata/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-fallbackdata/fy2026-27.json-- tax year 2026-27 under the Income-tax Act 2025. Same shape;statutecarries the Act, the 1961-to-2025 section map and the renumbered form names, and itsnoteis appended to the disclaimers of every result computed with it (withStatuteNotein server.ts), because engine notes still cite 1961 section numbers. Its lastsourcesentry names what is carried from 2025-26 until the TY 2026-27 forms are notifiedsrc/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 returnsforComputeTax;resolveTaxInputin server.ts foldshousesandpresumptiveBusinessinto compute_tax, compare_regimes and tax_summary per regimesrc/engine/summary.ts-- tax_summary: tax, credits, s.234A/B/C from dates, s.234F, s.288B net.breakeven.ts(compare_regimesbreakeven) anddeadlines.ts(list_tax_yearsstatus) are pure; the server passes today's date in Asia/Kolkatasrc/engine/dates.ts-- dates to interest months (Rule 119A(b), the pack'sinterest.partMonthIsFullMonth, and thes234A/s234BfromDatetokens). Tools take dates and count here; a month count from the caller is still acceptedsrc/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 depositedtests/engine.test.ts-- golden cases pinned to published worked examples plus statute-pinned surcharge, age-band, and rounding casesscripts/validation-cases.json-- source ofdocs/validation.md. Budget Speech rows are independent figures; statute rows carry their arithmetic inworking. Any change to computed output must keeppnpm validategreen, and the doc is generated, never hand-editedscripts/build-mcpb.mjs-- the Desktop bundle. Inlines every dependency (noExternal; SDK v2 has no CommonJS dependency left, so thecreateRequirebanner ajv needed under 1.x is gone), stages outside the repo so a missed dependency fails the build, and generates the manifest from the livetools/list, so there is no hand-kept tool list to driftdocs/diagrams/*.yaml-- the README's architecture and filing-flow diagrams, as orrery specs (github.com/Sagargupta16/orrery). The-light.svg/-dark.svgbeside 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 passorrery review --width 880docs/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 strayconsole.logbreaks 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/allowAgainst112Ain the pack. A mutation test intests/engine.test.tsflipsallowAgainst111Aon 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 onnormalIncome, 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 andcompute_taxnames the reading indisclaimerswhenever gains are present. parse_form26as: TCS collectors carry TANs exactly like deductors, so a part-header reset alone does NOT keep TCS out oftdsEntries. Rows are split by section (206C* ->tcsEntries). Booking status is the second cell after the section; only F is creditable andcreditableTdsDepositedsays so. Current 26AS layout: Part I TDS, Part II 15G/15H TDS, Part VI TCS, Part VII refunds; SFT/challans moved to AIS.McpServerversion comes frompackageVersion()(reads package.json next to data/). Never hardcode it again; it drifted to 0.3.0 while the package was 0.4.0.readDocumenthas an extension allow-list (.txt for 26AS, .json/.txt for AIS) and refuses dotfiles.pathis 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 pintaxableNormalIncomefor 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_selfOccupiedin the old regime and nil under s.115BAC(2)(i) (incometax.gov.in new-regime FAQ), and the excess ishousePropertyLossDisallowed, never carried forward. Let-out: no cap, set off to the s.71(3A) limit, rest carried forward. The tools refuse a loss withouthousePropertyType; 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_documentsreadsform26asPathandaisFileitself;parse_aisreturnstotals(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.tsand biome force-ignores**/.claude, because Claude Code session worktrees under.claude/worktrees/once madepnpm testrun a stale copy of the suite (302 tests) andpnpm lintfail on a nested root config. - SDK v2 ships under NEW package names (
@modelcontextprotocol/server+@modelcontextprotocol/core; the client is@modelcontextprotocol/client), so@modelcontextprotocol/sdkstays on 1.x and itslatestdist-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. EveryregisterToolinputSchema isz.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 omitsargsSchemainstead of passing{}. Stdio: server@modelcontextprotocol/server/stdio, client@modelcontextprotocol/client/stdio;InMemoryTransportcomes from either package root. housesin 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 asletOut, because house-property.ts has already applied the s.24(b) caps:selfOccupiedwould cap it a second time. Passinghousestogether withhousePropertyLossis refused. compare_regimes passes the old- and new-regime inputs toregimeBreakevenseparately for the same reason.tax_summarytakes 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'asOfdefault to today in Asia/Kolkata (indiaToday), never the machine's own zone.binmust bedist/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 publishas 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 listis empty).publish.ymltherefore 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.ymlruns every check and that diagnostic without publishing anything. Its answer on 2026-10-22 waspackage not found: no trusted publisher is saved. On 2026-11-13npm trust github itr-agent ...failed E401 because the owner's npm login (sagargupta1610) had expired (npm whoami401); afternpm loginit succeeded (permissions: publish, stage publish), and the dry run gotexchange HTTP 201with 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.Zlists an already-published version on the MCP registry without a release. publish.ymlinstalls 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 -eon stdin (printf '%s' "$out" | node -e '...readFileSync(0)...'), never as an argument. Windows caps a command line at 32,767 characters, and thetools/listreply (~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 (filesfield);resolveDataDir()in rulepack.ts probes both dist- and src-relative paths.server.json(MCP registry manifest) carries the version TWICE -- top level andpackages[0].version-- and both must equalpackage.jsonversion and the release tag.publish.ymlfails the release if they drift, or ifserver.jsonnamestops matchingpackage.jsonmcpName.- 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
daRetirementstays). 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 assumingparse_form26ashas 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 changesdata/fy2025-26.json. The pack shipped in 0.7.0 asdata/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 aslateFee234F.incomeThreshold. - Deadlines:
itr3_4_nonAudit2026-08-31 andrevised2027-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.deadlineCitationsin the pack carries the basis for each; keep it in step withdeadlines.
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,structuredContentoutput, 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;
structuredContentdoes 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.
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
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.

