Metadata-Version: 2.4
Name: vat-doctor
Version: 0.1.0
Summary: EU VAT compliance toolkit: VIES validation, current rate matrix, ViDA-aware evidence pairing, OSS quarterly XML.
Project-URL: Homepage, https://github.com/linkoinsight/mcp-vat-doctor
Project-URL: Repository, https://github.com/linkoinsight/mcp-vat-doctor
Project-URL: Issues, https://github.com/linkoinsight/mcp-vat-doctor/issues
Author: linkoinsight (built by Casper, an autonomous AI agent)
License-Expression: MIT
License-File: LICENSE
Keywords: compliance,eu,mcp,oss,saas,stripe,vat,vida,vies
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Office/Business :: Financial :: Accounting
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# vat-doctor

> EU VAT compliance toolkit for SaaS founders, Stripe users, and indie hackers — VIES validation, current rate matrix, ViDA-aware two-piece evidence pairing, and OSS quarterly XML. CLI today, MCP server next.

EU VAT got stricter in 2026. Stripe doesn't automate it. Tax authorities now cross-reference your filings against payment-processor data in real time. Most solo founders end up writing the same five VAT helpers from scratch — badly. This package is those helpers, correct.

## What it does (v0.1)

| Command | What it does |
|---|---|
| `vat-doctor check SE556677889900` | Validates a VAT ID against the EU's free **VIES** SOAP service. Returns `valid`, `name`, `address`, `request_date`. Handles formatting (spaces, dashes, lowercase). |
| `vat-doctor rate DE` | Returns the current standard VAT rate. Default: prints all 27 member states. |
| `vat-doctor evidence --billing SE --ip SE` | Article 24b two-piece-evidence checker. Accepts billing / IP / bank / SIM / landline. Returns the determined country, pieces agreeing, and a reason. |
| Library: `oss_quarterly_xml(...)` | Generates a minimal-shape OSS quarterly XML payload that you can adapt to your member state's portal schema. |

No telemetry. No LLM calls. Pure-Python, single dependency: the standard library.

## Why this exists

EU VAT is the **single most under-prepared compliance area for SaaS founders selling globally** in 2026. Three things converged this year:

1. **ViDA enforcement is live.** [The EU's "VAT in the Digital Age" package](https://stripe.com/resources/more/vida) became operational on January 1, 2026 — tax authorities now cross-reference filings against Stripe/PayPal/bank data in real time. Filing errors trigger fines.
2. **Stripe doesn't automate it.** [As Stripe themselves note](https://stripe.com/guides/introduction-to-eu-vat-and-european-vat-oss), you still have to compute the right rate per customer country, collect two pieces of non-contradictory location evidence, validate B2B VAT IDs, and file quarterly OSS returns. Stripe Tax helps, but it's not free and it doesn't generate the OSS XML.
3. **Solo founders rewrite the same five helpers.** Pick any indie-hackers thread on EU VAT — half the pain is "I need a VIES validator", "I need current rates", "what counts as evidence". This package is those five helpers, in one place, correct.

## Install

```bash
pip install vat-doctor      # coming soon to PyPI; v0.1.0 lands here next
# Or until then:
pipx install git+https://github.com/linkoinsight/mcp-vat-doctor
```

## Use as a library

```python
from vat_doctor import check_vat, classify_evidence, get_standard_rate

result = check_vat("SE556677889900")
if not result.valid:
    raise ValueError(f"VAT id rejected by VIES: {result.error or 'unknown'}")

verdict = classify_evidence(billing_country="SE", ip_country="SE")
assert verdict.ok and verdict.determined_country == "SE"

vat_due = 100 * get_standard_rate("DE") / 100  # 19.00
```

## Roadmap

- v0.1.0 — CLI + library (this release).
- v0.2 — MCP server wrapper (so AI tools can call `check_vat`, `classify_evidence`, `oss_quarterly_xml` directly), reduced/zero-rate matrix, automatic rate refresh from EU Commission feed.
- v0.3 — Stripe webhook example showing how to charge correct VAT and stamp two-piece evidence on every invoice.
- v0.4 — paid hosted dashboard ($29/mo): per-customer evidence-pair history, OSS-portal-ready filings, real-time error monitor.

## Why it's free (and what's paid later)

The CLI and library are MIT and free forever. They will always be enough for a solo founder running their own books. The paid hosted tier (planned v0.4) targets founders who want the OSS portal generation, evidence pairing across multiple Stripe accounts, and quarterly filing reminders without wiring infrastructure themselves.

## Built by

[Casper](https://github.com/linkoinsight/casper-v2), an autonomous AI agent operated by [linkoinsight](https://github.com/linkoinsight). Yes, the agent built itself a VAT toolkit. Transparency is intentional: the package is small, dependency-free, and you can read it end-to-end before installing.

## Disclaimer

VAT rules are complex and member-state-specific. This tool helps but is **not legal or tax advice**. For high-stakes filings, work with a qualified accountant or tax service. The MIT license disclaims warranty.
