用途
gst-einvoice-mcp 将印度 GST 税务发票转换为政府要求的 INV-01 JSON 载荷，并明确告知哪些内容无法读取。它生成的是可提交的载荷，而非已申报的发票——不包含 IRN（发票参考号），IRN 需由政府的发票注册门户在提交载荷后签发，本仓库不与 IRP 通信。
主要能力
- 以 MCP 服务器形式提供三个工具，使智能体可以解析文档、校验 GSTIN 或重新验证已持有的载荷。
- 结合 OCR、确定性提取和基于文档的 LLM 阶段。
- 核心规则：模型可以结构化文本，但绝不虚构数值。该规则通过提示词和逐值回查文档文本双重执行。无文档来源的值会被替换为 null 并报告；若该字段在 INV-01 中为必填，则不生成任何载荷。
- 所有关于自身工作的信息（每页如何读取、每个字段来源、不确定之处）放在 extraction_meta 中，不进入载荷，以保持载荷严格符合规范（政府 API 拒绝未知键）。
- parse_invoice 有三种正常结果：带警告的载荷（可用，但警告指出低 OCR 置信度字段、按位置而非标签分配的字段、以及推导而非打印的字段）；无载荷且 missing_fields 已填充（必填字段无法读取，未虚构填充）；无载荷且 refusals 已填充（出口、SEZ 和外汇发票按设计拒绝，并说明检测到什么及替代做法）。
- 警告块列出工具无法佐证的内容，帮助定位问题；四个算术校验器无输出即表示通过。
- 在模板省略列的发票上，会看到管道说明字段为推导而非读取，field_provenance 记录为 "source": "derived"。五条规则可触发推导：根据两个州代码将不适用的税种设为零；由应税价值和折扣填充行总额，或反之（互为精确逆运算，同一行不会同时出现）；单行发票仅页脚打印总额时，由 INV-01 项目恒等式填充行总额；模型遗漏的文档总额由行对应值填充（仅单行发票）。后两条仅在结果与打印的 ValDtls.TotInvVal 对账时触发，且推导值不会跨行/总额边界再次推导。多行发票缺失 TotItemVal 或文档总额仍报告缺失且不生成载荷。
- extraction_meta.field_provenance 为载荷中每个字段（示例发票为 45 个）记录产生阶段，扫描页还记录 OCR 置信度（干净 300 dpi 渲染下为 0.86 至 0.96，取字段各词最低置信度）。
使用方式
需要 Python 3.11 或更高版本，以及系统依赖 Tesseract OCR。Tesseract 无需在 PATH 中：OCR 模块先查找 PATH，再查找 Windows 标准安装位置，若均失败则抛出指明两者的可操作错误。
默认模型为 openai/gpt-oss-120b，无需配置即可工作。部署时仍应设置 GST_MCP_MODEL，因为硬编码模型标识符在提供商弃用后会静默失效，表现为类似密钥错误的 HTTP 404。请固定你有权访问的模型，并对照 Groq 的弃用通知检查。
MCP 客户端配置：pip install 会将 gst-einvoice-mcp 命令放入 PATH，客户端只需命名它。若从克隆运行而非安装，将 command 指向虚拟环境中的解释器并直接调用模块；Windows 上解释器路径以 .venv\Scripts\python.exe 结尾。
测试本地更改时注意：MCP 服务器运行 site-packages 中安装的版本，而非工作树。编辑仓库文件不会改变服务器行为，且无错误提示。需在每次更改后重新安装，或将 MCP 客户端的 command 指向仓库自己的虚拟环境。更改代码后需重启 MCP 服务器，因为运行中的服务器持有启动时导入的模块。
适用场景
适用于需要将印度 GST 税务发票转换为 INV-01 JSON 载荷的会计、财务或合规工作流，尤其适合通过 MCP 智能体自动化处理 PDF 或扫描发票的场景。
限制
- 不生成 IRN，不与 IRP 通信。
- 出口、SEZ 和外汇发票按设计拒绝。
- 多行发票缺失 TotItemVal 或文档总额时不生成载荷。
- 使用前应阅读 LIMITATIONS.md，其中具体说明工具无法佐证的内容及其代价。
- 依赖 PyMuPDF（AGPL-3.0），若作为闭源产品的一部分分发需先检查许可证。
- 测试套件包含十个模块共 1644 个测试，警告视为错误；LLM 阶段接受注入客户端，因此整个套件无需 API 密钥和网络即可运行。套件在 3.11 和 3.13 上通过，3.11 为最低版本。
