{
  "markdown": "# taxbrainai-mcp\n\nA **standalone [MCP](https://modelcontextprotocol.io) server** exposing **8 tools** for\nIndian personal income-tax work (ITR-1/2/3/4 + post-filing notices). It is built on\n**FastMCP** as a thin wrapper over the deterministic\n[`taxbrainai-compute`](https://github.com/harshil-projects/taxbrainai-compute) engine plus a\nsmall **statute graph that ships inside the package**.\n\nIt runs **fully offline with no API keys** — every tool here is deterministic or an\noptional bring-your-own-index lookup. There is **no LLM call anywhere in this package**.\n\n> This is the extracted, self-contained MCP surface of the larger [TaxBrainAI](https://taxbrainai.harshilprojects.com) project.\n> In the full product, three of these tools are backed by an LLM / vision model and a\n> hosted case-law corpus; here those halves are replaced by deterministic equivalents\n> (or made optional), so the package installs and starts with no private backend, no\n> secrets, and no redistributed third-party data. See \"Honesty about each tool\" below.\n\n## The 8 tools\n\n| # | Tool | Kind | What it does |\n|---|------|------|--------------|\n| 1 | `compute_tax` | **Deterministic — Decimal compute** | Income-tax liability for a structured input (salary, capital gains, deductions, age, residency, regime). No LLM in the math path. |\n| 2 | `regime_compare` | **Deterministic — Decimal compute** | Old vs new regime for the same inputs; recommends the cheaper, with savings delta + statutory citations. |\n| 3 | `simulate_scenario` | **Deterministic — Decimal compute** | What-if: apply changes to a base input and compare tax before/after. |\n| 4 | `cite_section` | **Deterministic — statute graph** | Resolves a section number to its title + a formatted citation, incl. the equivalent section in the other Act. |\n| 5 | `compare_acts` | **Deterministic — statute graph** | Maps a section across IT Act 1961 ↔ IT Act 2025 via the equivalence graph. |\n| 6 | `classify_notice` | **Deterministic — table + pattern-match** | Detects the notice *section* by pattern-matching the text, then returns curated section/type/deadline/guidance facts (not model-generated). Honest `found: false` when no known section is present. |\n| 7 | `reconcile_documents` | **Deterministic — diff** | Flags cross-document mismatches across Form 16 / 26AS / AIS **pre-extracted fields** (PAN redacted in output). OCR/vision extraction is out of scope — bring your own extractor. |\n| 8 | `find_case_law` | **Optional — lexical BM25 retrieval** | Lexical search over an optional case-law metadata index. **No corpus ships** with this package; set an env var to enable it (below), otherwise it returns an empty result set with a note. |\n\n### Honesty about each tool\n\n- **Deterministic Decimal compute (1–3):** all math flows through the\n  property-tested `taxbrainai-compute` library (Hypothesis-verified, cross-checked\n  against the official Income-Tax Dept ITR utilities). The server never authors a number.\n- **Deterministic statute graph (4–5):** answered from a vendored snapshot of the\n  1961↔2025 statute graph (`nodes.csv` + `edges.csv`, shipped inside the package).\n- **Deterministic table / diff (6–7):** in the full TaxBrainAI product these are\n  LLM/vision-backed (a model reads the notice / extracts document fields). This\n  standalone server keeps only the deterministic halves — a section/keyword matcher and\n  a field-level reconciliation diff — so no model or key is required.\n- **Optional retrieval (8):** `find_case_law` needs a case-law index, which is **not**\n  bundled (third-party data is not redistributed here). It degrades gracefully to an\n  empty result set unless you point it at your own index.\n\n## Install\n\n```bash\npip install \"taxbrainai-mcp[mcp]\"     # server + FastMCP SDK\npip install taxbrainai-mcp            # tool library only (no SDK; importable + testable)\n```\n\n`taxbrainai-compute` is a hard dependency and is installed automatically.\n\n## Run\n\n```bash\n# installed console script\ntaxbrainai-mcp\n\n# or the module form\npython -m taxbrainai_mcp.server\n```\n\nFastMCP's `run()` serves **stdio** by default and also supports **Streamable HTTP**\n(`build_mcp_server().run(transport=\"streamable-http\")`). No API keys are needed.\n\n### Optional: enable case-law search\n\n```bash\nexport TAXBRAIN_MCP_CASELAW_INDEX=/path/to/caselaw.jsonl   # JSONL of {\"title\",\"court\",...}\n```\n\nIf your index is derived from Indian Kanoon (indiankanoon.org), attribute it accordingly.\n\n## Connect a client (Claude Desktop)\n\nAdd to `claude_desktop_config.json` (`mcpServers` block):\n\n```json\n{\n  \"mcpServers\": {\n    \"taxbrain\": {\n      \"command\": \"taxbrainai-mcp\"\n    }\n  }\n}\n```\n\nIf the console script is not on `PATH`, use `\"command\": \"python\", \"args\": [\"-m\", \"taxbrainai_mcp.server\"]`.\n\n## Use the tools directly (no MCP SDK)\n\nThe tool logic is a plain class — handy for tests or embedding:\n\n```python\nfrom taxbrainai_mcp import TaxBrainTools\n\nt = TaxBrainTools()\nprint(t.compute_tax({\"salary_income\": 1275000, \"regime\": \"new\"})[\"total_tax\"])  # 0 (rebated under Section 87A)\nprint(t.compare_acts(\"147\")[\"equivalence\"])\n```\n\n## Registry manifest\n\n`server.json` is the MCP-registry manifest (schema `2025-12-11`), authored as a\n**draft for submission**. Its `_meta` block lists the exact pre-publish checklist\n(claim/publish the PyPI name, validate against the schema, authenticate the\n`io.github.harshil-projects` namespace). The package runs locally over stdio — there is\nno hosted remote endpoint.\n\n## Scope & disclaimer\n\nCovers AY 2026-27 / FY 2025-26 for resident individuals / HUF (ITR-1/2/3/4). This is\nsoftware for estimation, **not** tax, legal, or financial advice; verify against the\nofficial e-filing utility and a qualified professional before relying on any figure.\n\n## License\n\nMIT — see [LICENSE](./LICENSE). Bundled statute graph data is derived from the text of\nthe Income-tax Act (official statutory text). `taxbrainai-compute` is MIT-licensed.\n\n---\n\nmcp-name: io.github.harshil-projects/taxbrainai-mcp\n",
  "bytes": 5981,
  "sha": "bc5575c80bfc4fdae331ee0b44a1015b799fd8ea90dcca83f07fe68a2ee8ccc0",
  "repo_slug": "harshil-projects/taxbrainai-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_harshil_projects_taxbrainai_mc_f14a1c45/readme"
}