itr-agent
# itr-agent
An open-source MCP server for filing Indian Income Tax Returns. It runs locally
on your machine and plugs into any MCP-capable AI app (Claude Desktop, Cursor,
and others). No backend, and no document leaves your device.
## Status
Phase 0 (foundation): strict schemas, the trade validation gate, and the MCP
server skeleton.
Phase 1 (AIS and missing documents) is in place:
- **Ingest and store.** `ingest_ais`, `ingest_26as`, `ingest_form16`, and
`ingest_trades` take structured data that the AI has read from the user's
file. The server validates it and stores it under `ITR_AGENT_HOME` (default
`~/.itr-agent`), one folder per assessment year.
- **Show.** `show_ais` renders the AIS as markdown, with Indian digit grouping
and TDS totals.
- **Find what's missing.** `get_document_checklist` works out which supporting
documents the AIS implies (26AS, Form 16 per employer, broker P&L) and
attaches a download guide to each missing one. Guides live in
`src/itr_agent/guides_data/`. They are drafted and not yet checked against
the live portals.
Still `not_implemented`: reconciliation, tax and capital-gains engines, ITR
JSON, and currency conversion. These are Phases 2 to 3.
## Development
```bash
uv venv .venv
uv pip install -p .venv/bin/python -e ".[dev]"
.venv/bin/python -m pytest
```
Run the server over stdio:
```bash
.venv/bin/itr-agent
```
## License
MIT. See [LICENSE](LICENSE).
TDQS
Scored across 16 tools
Most tools have clearly distinct resource/action targets, especially the ingest_* and compute_* families. The main overlap is between get_document_checklist and get_download_guide, since the checklist already includes download guides, creating some ambiguity about when to call the standalone guide tool.
The set overwhelmingly follows snake_case verb_noun naming such as compute_tax, ingest_form16, and generate_itr_json. The only notable deviation is reconcile, which is verb-only rather than following the verb_object pattern.
Sixteen tools is slightly above the typical well-scoped range, but the complexity of ITR filing justifies most of them. The ingestion, computation, validation, reconciliation, and generation tools each serve a clear role.
The core filing lifecycle is well covered: document checklist, ingestion, reconciliation, computation, validation, and ITR JSON generation. Minor gaps remain around displaying or retrieving stored Form 26AS, Form 16, and trade data, since only show_ais exists.