gst-einvoice-mcp

# GST e-invoice extraction Turns an Indian GST tax invoice into the government's **INV-01 JSON payload**, and tells you exactly what it could not read. Ships as an [MCP](https://modelcontextprotocol.io/) server with three tools, so an agent can parse a document, check a GSTIN, or re-validate a payload it already holds. > **It produces a submission-ready payload, not a filed invoice.** There is no IRN here. An Invoice Reference Number is issued by the government's Invoice Registration Portal after you submit the payload to it. Nothing in this repository talks to the IRP. ------ ## The idea An extraction tool that quietly guesses is worse than one that says it cannot read a field. A hallucinated digit in a GSTIN that still passes its checksum, or a line item that was never on the page, is the failure that costs an accountant real money — and it is invisible precisely because it looks right. So the design has one rule: **the model may structure text, it may never invent values.** That is enforced twice. The prompt says it, and then every value the model returns is checked back against the document text before it is kept. A value with no source in the document is replaced with null and reported, however plausible it looks. If that field is mandatory in INV-01, no payload is produced at all. Everything the tool knows about its own work — how each page was read, where each field came from, what it was unsure about — travels beside the payload in `extraction_meta`, never inside it. The payload stays strictly spec-pure, because the government API rejects unknown keys. **Read [LIMITATIONS.md](LIMITATIONS.md) before trusting the output.** It is specific about what the tool cannot corroborate, and what that costs you. ------ ## Install Requires **Python 3.11 or newer** and **Tesseract OCR** as a system dependency. ```bash # Tesseract (Windows) winget install UB-Mannheim.TesseractOCR # Tesseract (Debian/Ubuntu) sudo apt-get install …