TaxBrainAI MCP

taxbrainai-mcp

一个独立的 MCP 服务，提供 8 个工具，用于印度个人所得税事务（ITR-1/2/3/4 及申报后通知）。它基于 FastMCP 构建，是确定性 taxbrainai-compute 引擎的轻量封装，并附带一个随软件包提供的小型法规图谱。

它完全离线运行，无需 API 密钥——这里的每个工具都是确定性的，或可选地通过自带索引进行查询。本软件包不包含任何 LLM 调用。

这是更大型 TaxBrainAI 项目中独立提取、可自成一体的 MCP 功能。 在完整产品中，这些工具有三个由 LLM / 视觉模型和托管的判例语料库提供支持；此处则以确定性等效方案替代（或设为可选），因此本软件包无需私有后端、机密信息或重新分发的第三方数据，即可安装和启动。请参阅下文“关于各工具的说明”。

8 个工具

#	工具	类型	功能
1	compute_tax	确定性 — Decimal 计算	根据结构化输入（工资、资本利得、扣除额、年龄、居住身份、税制）计算所得税税额。计算流程中不使用 LLM。
2	regime_compare	确定性 — Decimal 计算	使用相同输入比较旧税制与新税制；推荐税额较低的方案，并提供节省金额差值和法定引文。
3	simulate_scenario	确定性 — Decimal 计算	假设分析：对基础输入应用更改，并比较更改前后的税额。
4	cite_section	确定性 — 法规图谱	根据条款编号查找其标题和格式化引文，包括另一部法律中的对应条款。
5	compare_acts	确定性 — 法规图谱	通过等效关系图谱映射 IT Act 1961 ↔ IT Act 2025 中的条款。
6	classify_notice	确定性 — 表格 + 模式匹配	通过匹配文本模式检测通知的条款，然后返回整理好的条款／类型／截止日期／指引信息（并非模型生成）。若未发现已知条款，则如实返回 found: false。
7	reconcile_documents	确定性 — 差异比对	标记 Form 16 / 26AS / AIS 预提取字段之间的跨文档差异（输出中会遮盖 PAN）。OCR／视觉提取不在范围内——请自备提取器。
8	find_case_law	可选 — BM25 词汇检索	在可选的判例元数据索引中进行词汇搜索。本软件包不附带任何语料库；设置环境变量即可启用（如下所述），否则会返回空结果集并附带说明。

关于各工具的说明

• **确定性 Decimal 计算（1–3）：**所有计算都通过经过属性测试的 taxbrainai-compute 库完成（经 Hypothesis 验证，并与所得税部门官方 ITR 工具交叉核对）。服务不会自行编造任何数字。
• **确定性法规图谱（4–5）：**答案来自随软件包提供的 1961↔2025 法规图谱快照（nodes.csv + edges.csv）。
• **确定性表格／差异比对（6–7）：**在完整的 TaxBrainAI 产品中，这些工具由 LLM／视觉模型提供支持（模型读取通知／提取文档字段）。此独立服务仅保留确定性部分——条款／关键词匹配器和字段级核对差异比对，因此无需模型或密钥。
• 可选检索（8）：find_case_law 需要判例索引，本软件包不附带该索引（此处不会重新分发第三方数据）。除非你指定自己的索引，否则它会平稳退化为空结果集。

安装

pip install "taxbrainai-mcp[mcp]"     # server + FastMCP SDK
pip install taxbrainai-mcp            # tool library only (no SDK; importable + testable)

taxbrainai-compute 是硬性依赖，会自动安装。

运行

# installed console script
taxbrainai-mcp

# or the module form
python -m taxbrainai_mcp.server

FastMCP 的 run() 默认通过 stdio 提供服务，也支持 Streamable HTTP（build_mcp_server().run(transport="streamable-http")）。无需 API 密钥。

可选：启用判例搜索

export TAXBRAIN_MCP_CASELAW_INDEX=/path/to/caselaw.jsonl   # JSONL of {"title","court",...}

如果你的索引来源于 Indian Kanoon（indiankanoon.org），请相应注明出处。

连接客户端（Claude Desktop）

在 claude_desktop_config.json（mcpServers 块）中添加：

{
  "mcpServers": {
    "taxbrain": {
      "command": "taxbrainai-mcp"
    }
  }
}

如果控制台脚本不在 PATH 中，请使用 "command": "python", "args": ["-m", "taxbrainai_mcp.server"]。

直接使用工具（不使用 MCP SDK）

工具逻辑是一个普通类，适用于测试或嵌入：

from taxbrainai_mcp import TaxBrainTools

t = TaxBrainTools()
print(t.compute_tax({"salary_income": 1275000, "regime": "new"})["total_tax"])  # 0 (rebated under Section 87A)
print(t.compare_acts("147")["equivalence"])

Registry 清单

server.json 是 MCP 注册表清单（架构 2025-12-11），目前为待提交草稿。其 _meta 块列出了发布前的完整检查清单（认领并发布 PyPI 名称、根据架构进行验证、验证 io.github.harshil-projects 命名空间）。此软件包通过 stdio 在本地运行——没有托管的远程端点。

范围与免责声明

适用于 AY 2026-27 / FY 2025-26 的居民个人 / HUF（ITR-1/2/3/4）。本软件仅用于估算，不构成税务、法律或财务建议；请先根据官方电子申报工具和合格专业人士的意见进行核实，再依赖任何估算结果。

许可证

MIT — 参见 LICENSE。捆绑的法规图数据源自《所得税法》的文本（官方法规文本）。taxbrainai-compute 采用 MIT 许可证。

---

mcp-name: io.github.harshil-projects/taxbrainai-mcp