vatnode-mcp 0.1.0

package/README.md

@@ -0,0 +1,124 @@
+# vatnode-mcp
+
+[![npm version](https://img.shields.io/npm/v/vatnode-mcp)](https://www.npmjs.com/package/vatnode-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Official [Model Context Protocol](https://modelcontextprotocol.io) server for **[vatnode](https://vatnode.dev)** — VAT validation and EU tax data for AI agents.
+
+Lets AI assistants (Claude Desktop, Cursor, ChatGPT, Continue, Cline, …) look up VAT rates, check VAT number formats, and validate VAT IDs against the EU VIES service without leaving the chat.
+
+- **Free, offline** — VAT rates and format checks for 45 European countries, no account needed
+- **Live validation** — verify EU VAT numbers against VIES, get the registered company + audit-grade consultation number (requires a free [vatnode](https://vatnode.dev) API key)
+- **Five focused tools** — well-described for accurate agent tool selection
+- Pure stdio, zero hosted dependencies, runs locally via `npx`
+
+---
+
+## Tools
+
+| Tool | Free | Description |
+|---|---|---|
+| `get_country_vat_rates` | ✅ | Standard / reduced / super-reduced / parking rates + VAT number format for a country |
+| `list_eu_vat_rates` | ✅ | All 27 EU member states (plus XI for Northern Ireland) at once |
+| `check_vat_format` | ✅ | Offline syntactic check of a VAT number against the country regex |
+| `list_supported_countries` | ✅ | All 45 supported countries and which ones support full VIES validation |
+| `validate_vat_number` | 🔑 | Live VIES validation — returns validity, company name, address, registration date, and optional consultation number for audit proof |
+
+Free tools work fully offline — data is bundled via [`eu-vat-rates-data`](https://www.npmjs.com/package/eu-vat-rates-data) and updated daily from the European Commission TEDB.
+
+`validate_vat_number` requires a vatnode API key. The free tier includes a monthly request quota — [get one in 30 seconds](https://vatnode.dev).
+
+---
+
+## Install
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "vatnode": {
+      "command": "npx",
+      "args": ["-y", "vatnode-mcp"],
+      "env": {
+        "VATNODE_API_KEY": "vat_live_..."
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The `vatnode` tools will appear in the tool picker.
+
+You can omit `VATNODE_API_KEY` if you only need the free tools (rates, format checks).
+
+### Cursor
+
+Settings → MCP → Add new server:
+
+```json
+{
+  "mcpServers": {
+    "vatnode": {
+      "command": "npx",
+      "args": ["-y", "vatnode-mcp"],
+      "env": { "VATNODE_API_KEY": "vat_live_..." }
+    }
+  }
+}
+```
+
+### ChatGPT (custom connectors / Apps SDK)
+
+Configure as an stdio MCP server with the same `npx -y vatnode-mcp` command. See the [Apps SDK docs](https://platform.openai.com/docs).
+
+### Continue / Cline / other clients
+
+Any MCP-compatible client can connect — point it at `npx -y vatnode-mcp` and (optionally) pass `VATNODE_API_KEY` via environment.
+
+---
+
+## Get an API key
+
+`validate_vat_number` requires a [vatnode](https://vatnode.dev) account. The platform also offers things the MCP doesn't expose:
+
+- Webhooks for VAT status changes (monitor a customer's VAT continuously)
+- Bulk validation
+- National-database fallback when VIES is down
+- VIES consultation numbers (audit-grade proof of validation)
+- Per-key rate limiting + dashboard analytics
+
+[**Sign up free →**](https://vatnode.dev)
+
+---
+
+## Example session
+
+> **You:** What's the VAT rate in Finland and Germany?
+>
+> *(Agent calls `get_country_vat_rates` for FI and DE — free, no key.)*
+>
+> **Agent:** Finland's standard VAT is 25.5%, Germany's is 19%. Finland has reduced rates of 14% and 10%; Germany has 7%.
+
+> **You:** Is IE6388047V a valid VAT?
+>
+> *(Agent calls `validate_vat_number` — requires API key.)*
+>
+> **Agent:** Yes, it's valid. Registered to **GOOGLE IRELAND LIMITED** at Gordon House, Barrow Street, Dublin 4.
+
+---
+
+## Configuration
+
+| Env var | Required | Default | Purpose |
+|---|---|---|---|
+| `VATNODE_API_KEY` | for `validate_vat_number` | — | API key from https://vatnode.dev |
+| `VATNODE_API_URL` | no | `https://api.vatnode.dev` | Override the API base (self-hosting / staging) |
+
+---
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,990 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z as z2 } from "zod";
+
+// ../../packages/eu-vat-rates/dist/index.js
+var eu_vat_rates_default = {
+  version: "2026-05-19",
+  source: "European Commission TEDB",
+  rates: {
+    AD: {
+      country: "Andorra",
+      currency: "EUR",
+      eu_member: false,
+      vat_name: "Impost General Indirecte",
+      vat_abbr: "IGI",
+      standard: 4.5,
+      reduced: [
+        1,
+        2.5
+      ],
+      super_reduced: null,
+      parking: null,
+      format: "1 letter + 6 digits + 1 letter",
+      pattern: "^[A-Z]\\d{6}[A-Z]$"
+    },
+    AL: {
+      country: "Albania",
+      currency: "ALL",
+      eu_member: false,
+      vat_name: "Tatimi mbi vler\xEBn e shtuar",
+      vat_abbr: "TVSH",
+      standard: 20,
+      reduced: [
+        6,
+        10
+      ],
+      super_reduced: null,
+      parking: null,
+      format: "1 letter + 8 digits + 1 letter",
+      pattern: "^[A-Z]\\d{8}[A-Z]$"
+    },
+    AT: {
+      country: "Austria",
+      currency: "EUR",
+      eu_member: true,
+      vat_name: "Umsatzsteuer",
+      vat_abbr: "USt",
+      standard: 20,
+      reduced: [
+        10,
+        13,
+        19
+      ],
+      super_reduced: null,
+      parking: null,
+      format: "ATU + 8 digits",
+      pattern: "^ATU\\d{8}$"
+    },
+    BA: {
+      country: "Bosnia and Herzegovina",
+      currency: "BAM",
+      eu_member: false,
+      vat_name: "Porez na dodanu vrijednost",
+      vat_abbr: "PDV",
+      standard: 17,
+      reduced: [],
+      super_reduced: null,
+      parking: null,
+      format: "12 digits",
+      pattern: "^\\d{12}$"
+    },
+    BE: {
+      country: "Belgium",
+      currency: "EUR",
+      eu_member: true,
+      vat_name: "Belasting over de toegevoegde waarde",
+      vat_abbr: "BTW",
+      standard: 21,
+      reduced: [
+        6,
+        12
+      ],
+      super_reduced: null,
+      parking: 12,
+      format: "BE + 0/1 + 9 digits",
+      pattern: "^BE[01]\\d{9}$"
+    },
+    BG: {
+      country: "Bulgaria",
+      currency: "EUR",
+      eu_member: true,
+      vat_name: "\u0414\u0430\u043D\u044A\u043A \u0432\u044A\u0440\u0445\u0443 \u0434\u043E\u0431\u0430\u0432\u0435\u043D\u0430\u0442\u0430 \u0441\u0442\u043E\u0439\u043D\u043E\u0441\u0442",
+      vat_abbr: "\u0414\u0414\u0421",
+      standard: 20,
+      reduced: [
+        9
+      ],
+      super_reduced: null,
+      parking: null,
+      format: "BG + 9\u201310 digits",
+      pattern: "^BG\\d{9,10}$"
+    },
+    CH: {
+      country: "Switzerland",
+      currency: "CHF",
+      eu_member: false,
+      vat_name: "Mehrwertsteuer",
+      vat_abbr: "MWST",
+      standard: 8.1,
+      reduced: [
+        2.6,
+        3.8
+      ],
+      super_reduced: null,
+      parking: null,
+      format: "CHE-NNN.NNN.NNN (+ MWST/TVA/IVA)",
+      pattern: "^CHE-?\\d{3}\\.?\\d{3}\\.?\\d{3}[ ]?(MWST|TVA|IVA)?$"
+    },
+    CY: {
+      country: "Cyprus",
+      currency: "EUR",
+      eu_member: true,
+      vat_name: "\u03A6\u03CC\u03C1\u03BF\u03C2 \u03A0\u03C1\u03BF\u03C3\u03C4\u03B9\u03B8\u03AD\u03BC\u03B5\u03BD\u03B7\u03C2 \u0391\u03BE\u03AF\u03B1\u03C2",
+      vat_abbr: "\u03A6\u03A0\u0391",
+      standard: 19,
+      reduced: [
+        5,
+        9
+      ],
+      super_reduced: 3,
+      parking: null,
+      format: "CY + 8 digits + 1 letter",
+      pattern: "^CY\\d{8}[A-Z]$"
+    },
+    CZ: {
+      country: "Czech Republic",
+      currency: "CZK",
+      eu_member: true,
+      vat_name: "Da\u0148 z p\u0159idan\xE9 hodnoty",
+      vat_abbr: "DPH",
+      standard: 21,
+      reduced: [
+        12
+      ],
+      super_reduced: null,
+      parking: null,
+      format: "CZ + 8\u201310 digits",
+      pattern: "^CZ\\d{8,10}$"
+    },
+    DE: {
+      country: "Germany",
+      currency: "EUR",
+      eu_member: true,
+      vat_name: "Mehrwertsteuer",
+      vat_abbr: "MwSt",
+      standard: 19,
+      reduced: [
+        7
+      ],
+      super_reduced: null,
+      parking: null,
+      format: "DE + 9 digits",
+      pattern: "^DE\\d{9}$"
+    },
+    DK: {
+      country: "Denmark",
+      currency: "DKK",
+      eu_member: true,
+      vat_name: "Moms",
+      vat_abbr: "moms",
+      standard: 25,
+      reduced: [],
+      super_reduced: null,
+      parking: null,
+      format: "DK + 8 digits",
+      pattern: "^DK\\d{8}$"
+    },
+    EE: {
+      country: "Estonia",
+      currency: "EUR",
+      eu_member: true,
+      vat_name: "K\xE4ibemaks",
+      vat_abbr: "km",
+      standard: 24,
+      reduced: [
+        9,
+        13
+      ],
+      super_reduced: null,
+      parking: null,
+      format: "EE + 9 digits",
+      pattern: "^EE\\d{9}$"
+    },
+    ES: {
+      country: "Spain",
+      currency: "EUR",
+      eu_member: true,
+      vat_name: "Impuesto sobre el Valor A\xF1adido",
+      vat_abbr: "IVA",
+      standard: 21,
+      reduced: [
+        10
+      ],
+      super_reduced: 4,
+      parking: null,
+      format: "ES + letter/digit + 7 digits + letter/digit",
+      pattern: "^ES[A-Z0-9]\\d{7}[A-Z0-9]$"
+    },
+    FI: {
+      country: "Finland",
+      currency: "EUR",
+      eu_member: true,
+      vat_name: "Arvonlis\xE4vero",
+      vat_abbr: "ALV",
+      standard: 25.5,
+      reduced: [
+        10,
+        13.5
+      ],
+      super_reduced: null,
+      parking: null,
+      format: "FI + 8 digits",
+      pattern: "^FI\\d{8}$"
+    },
+    FR: {
+      country: "France",
+      currency: "EUR",
+      eu_member: true,
+      vat_name: "Taxe sur la valeur ajout\xE9e",
+      vat_abbr: "TVA",
+      standard: 20,
+      reduced: [
+        0.9,
+        1.05,
+        5.5,
+        8.5,
+        10,
+        13
+      ],
+      super_reduced: 2.1,
+      parking: null,
+      format: "FR + 2 alphanumeric + 9 digits",
+      pattern: "^FR[A-HJ-NP-Z0-9]{2}\\d{9}$"
+    },
+    GB: {
+      country: "United Kingdom",
+      currency: "GBP",
+      eu_member: false,
+      vat_name: "Value Added Tax",
+      vat_abbr: "VAT",
+      standard: 20,
+      reduced: [
+        5
+      ],
+      super_reduced: null,
+      parking: null,
+      format: "GB + 9 digits, 12 digits, or GD/HA + 3 digits",
+      pattern: "^GB(\\d{9}|\\d{12}|GD\\d{3}|HA\\d{3})$"
+    },
+    GE: {
+      country: "Georgia",
+      currency: "GEL",
+      eu_member: false,
+      vat_name: "\u10D3\u10D0\u10DB\u10D0\u10E2\u10D4\u10D1\u10E3\u10DA\u10D8 \u10E6\u10D8\u10E0\u10D4\u10D1\u10E3\u10DA\u10D4\u10D1\u10D8\u10E1 \u10D2\u10D0\u10D3\u10D0\u10E1\u10D0\u10EE\u10D0\u10D3\u10D8",
+      vat_abbr: "\u10D3\u10E6\u10D2",
+      standard: 18,
+      reduced: [],
+      super_reduced: null,
+      parking: null,
+      format: "9 digits",
+      pattern: "^\\d{9}$"
+    },
+    GR: {
+      country: "Greece",
+      currency: "EUR",
+      eu_member: true,
+      vat_name: "\u03A6\u03CC\u03C1\u03BF\u03C2 \u03A0\u03C1\u03BF\u03C3\u03C4\u03B9\u03B8\u03AD\u03BC\u03B5\u03BD\u03B7\u03C2 \u0391\u03BE\u03AF\u03B1\u03C2",
+      vat_abbr: "\u03A6\u03A0\u0391",
+      standard: 24,
+      reduced: [
+        6,
+        13,
+        17
+      ],
+      super_reduced: 4,
+      parking: 13,
+      format: "EL + 9 digits",
+      pattern: "^EL\\d{9}$"
+    },
+    HR: {
+      country: "Croatia",
+      currency: "EUR",
+      eu_member: true,
+      vat_name: "Porez na dodanu vrijednost",
+      vat_abbr: "PDV",
+      standard: 25,
+      reduced: [
+        5,
+        13
+      ],
+      super_reduced: null,
+      parking: null,
+      format: "HR + 11 digits",
+      pattern: "^HR\\d{11}$"
+    },
+    HU: {
+      country: "Hungary",
+      currency: "HUF",
+      eu_member: true,
+      vat_name: "\xC1ltal\xE1nos forgalmi ad\xF3",
+      vat_abbr: "\xC1FA",
+      standard: 27,
+      reduced: [
+        5,
+        18
+      ],
+      super_reduced: null,
+      parking: null,
+      format: "HU + 8 digits",
+      pattern: "^HU\\d{8}$"
+    },
+    IE: {
+      country: "Ireland",
+      currency: "EUR",
+      eu_member: true,
+      vat_name: "Value Added Tax",
+      vat_abbr: "VAT",
+      standard: 23,
+      reduced: [
+        9,
+        13.5
+      ],
+      super_reduced: null,
+      parking: null,
+      format: "IE + 7 digits + 1\u20132 letters",
+      pattern: "^IE\\d{7}[A-W][A-IW]?$|^IE\\d[A-Z+*]\\d{5}[A-W]$"
+    },
+    IS: {
+      country: "Iceland",
+      currency: "ISK",
+      eu_member: false,
+      vat_name: "Vir\xF0isaukaskattur",
+      vat_abbr: "VSK",
+      standard: 24,
+      reduced: [
+        11
+      ],
+      super_reduced: null,
+      parking: null,
+      format: "5\u20136 digits",
+      pattern: "^\\d{5,6}$"
+    },
+    IT: {
+      country: "Italy",
+      currency: "EUR",
+      eu_member: true,
+      vat_name: "Imposta sul valore aggiunto",
+      vat_abbr: "IVA",
+      standard: 22,
+      reduced: [
+        5,
+        10
+      ],
+      super_reduced: 4,
+      parking: null,
+      format: "IT + 11 digits",
+      pattern: "^IT\\d{11}$"
+    },
+    LI: {
+      country: "Liechtenstein",
+      currency: "CHF",
+      eu_member: false,
+      vat_name: "Mehrwertsteuer",
+      vat_abbr: "MWST",
+      standard: 8.1,
+      reduced: [
+        2.6,
+        3.8
+      ],
+      super_reduced: null,
+      parking: null,
+      format: "5 digits",
+      pattern: "^\\d{5}$"
+    },
+    LT: {
+      country: "Lithuania",
+      currency: "EUR",
+      eu_member: true,
+      vat_name: "Prid\u0117tin\u0117s vert\u0117s mokestis",
+      vat_abbr: "PVM",
+      standard: 21,
+      reduced: [
+        5,
+        12
+      ],
+      super_reduced: null,
+      parking: null,
+      format: "LT + 9 or 12 digits",
+      pattern: "^LT(\\d{9}|\\d{12})$"
+    },
+    LU: {
+      country: "Luxembourg",
+      currency: "EUR",
+      eu_member: true,
+      vat_name: "Taxe sur la valeur ajout\xE9e",
+      vat_abbr: "TVA",
+      standard: 17,
+      reduced: [
+        8,
+        14
+      ],
+      super_reduced: 3,
+      parking: 14,
+      format: "LU + 8 digits",
+      pattern: "^LU\\d{8}$"
+    },
+    LV: {
+      country: "Latvia",
+      currency: "EUR",
+      eu_member: true,
+      vat_name: "Pievienot\u0101s v\u0113rt\u012Bbas nodoklis",
+      vat_abbr: "PVN",
+      standard: 21,
+      reduced: [
+        5,
+        12
+      ],
+      super_reduced: null,
+      parking: null,
+      format: "LV + 11 digits",
+      pattern: "^LV\\d{11}$"
+    },
+    MC: {
+      country: "Monaco",
+      currency: "EUR",
+      eu_member: false,
+      vat_name: "Taxe sur la valeur ajout\xE9e",
+      vat_abbr: "TVA",
+      standard: 20,
+      reduced: [
+        5.5,
+        10
+      ],
+      super_reduced: 2.1,
+      parking: null,
+      format: "FR + 2 alphanumeric + 9 digits",
+      pattern: "^FR[A-HJ-NP-Z0-9]{2}\\d{9}$"
+    },
+    MD: {
+      country: "Moldova",
+      currency: "MDL",
+      eu_member: false,
+      vat_name: "Taxa pe valoarea ad\u0103ugat\u0103",
+      vat_abbr: "TVA",
+      standard: 20,
+      reduced: [
+        8
+      ],
+      super_reduced: null,
+      parking: null,
+      format: "7 digits",
+      pattern: "^\\d{7}$"
+    },
+    ME: {
+      country: "Montenegro",
+      currency: "EUR",
+      eu_member: false,
+      vat_name: "Porez na dodatu vrijednost",
+      vat_abbr: "PDV",
+      standard: 21,
+      reduced: [
+        7,
+        15
+      ],
+      super_reduced: null,
+      parking: null,
+      format: "8 digits",
+      pattern: "^\\d{8}$"
+    },
+    MK: {
+      country: "North Macedonia",
+      currency: "MKD",
+      eu_member: false,
+      vat_name: "\u0414\u0430\u043D\u043E\u043A \u043D\u0430 \u0434\u043E\u0434\u0430\u0434\u0435\u043D\u0430 \u0432\u0440\u0435\u0434\u043D\u043E\u0441\u0442",
+      vat_abbr: "\u0414\u0414\u0412",
+      standard: 18,
+      reduced: [
+        5,
+        10
+      ],
+      super_reduced: null,
+      parking: null,
+      format: "MK + 13 digits",
+      pattern: "^MK\\d{13}$"
+    },
+    MT: {
+      country: "Malta",
+      currency: "EUR",
+      eu_member: true,
+      vat_name: "Taxxa tal-Valur Mi\u017Cjud",
+      vat_abbr: "VAT",
+      standard: 18,
+      reduced: [
+        5,
+        7
+      ],
+      super_reduced: null,
+      parking: 12,
+      format: "MT + 8 digits",
+      pattern: "^MT\\d{8}$"
+    },
+    NL: {
+      country: "Netherlands",
+      currency: "EUR",
+      eu_member: true,
+      vat_name: "Belasting over de toegevoegde waarde",
+      vat_abbr: "btw",
+      standard: 21,
+      reduced: [
+        9
+      ],
+      super_reduced: null,
+      parking: null,
+      format: "NL + 9 digits + B + 2 digits",
+      pattern: "^NL\\d{9}B\\d{2}$"
+    },
+    NO: {
+      country: "Norway",
+      currency: "NOK",
+      eu_member: false,
+      vat_name: "Merverdiavgift",
+      vat_abbr: "MVA",
+      standard: 25,
+      reduced: [
+        12,
+        15
+      ],
+      super_reduced: null,
+      parking: null,
+      format: "9 digits + MVA",
+      pattern: "^\\d{9}MVA$"
+    },
+    PL: {
+      country: "Poland",
+      currency: "PLN",
+      eu_member: true,
+      vat_name: "Podatek od towar\xF3w i us\u0142ug",
+      vat_abbr: "VAT",
+      standard: 23,
+      reduced: [
+        5,
+        8
+      ],
+      super_reduced: 8,
+      parking: null,
+      format: "PL + 10 digits",
+      pattern: "^PL\\d{10}$"
+    },
+    PT: {
+      country: "Portugal",
+      currency: "EUR",
+      eu_member: true,
+      vat_name: "Imposto sobre o Valor Acrescentado",
+      vat_abbr: "IVA",
+      standard: 23,
+      reduced: [
+        6,
+        13,
+        16,
+        22
+      ],
+      super_reduced: 6,
+      parking: 13,
+      format: "PT + 9 digits",
+      pattern: "^PT\\d{9}$"
+    },
+    RO: {
+      country: "Romania",
+      currency: "RON",
+      eu_member: true,
+      vat_name: "Taxa pe valoarea ad\u0103ugat\u0103",
+      vat_abbr: "TVA",
+      standard: 21,
+      reduced: [
+        11
+      ],
+      super_reduced: null,
+      parking: null,
+      format: "RO + 2\u201310 digits",
+      pattern: "^RO\\d{2,10}$"
+    },
+    RS: {
+      country: "Serbia",
+      currency: "RSD",
+      eu_member: false,
+      vat_name: "Porez na dodatu vrednost",
+      vat_abbr: "PDV",
+      standard: 20,
+      reduced: [
+        10
+      ],
+      super_reduced: null,
+      parking: null,
+      format: "9 digits",
+      pattern: "^\\d{9}$"
+    },
+    SE: {
+      country: "Sweden",
+      currency: "SEK",
+      eu_member: true,
+      vat_name: "Merv\xE4rdesskatt",
+      vat_abbr: "moms",
+      standard: 25,
+      reduced: [
+        6,
+        12
+      ],
+      super_reduced: null,
+      parking: null,
+      format: "SE + 10 digits + 01",
+      pattern: "^SE\\d{10}01$"
+    },
+    SI: {
+      country: "Slovenia",
+      currency: "EUR",
+      eu_member: true,
+      vat_name: "Davek na dodano vrednost",
+      vat_abbr: "DDV",
+      standard: 22,
+      reduced: [
+        5,
+        9.5
+      ],
+      super_reduced: null,
+      parking: null,
+      format: "SI + 8 digits",
+      pattern: "^SI\\d{8}$"
+    },
+    SK: {
+      country: "Slovakia",
+      currency: "EUR",
+      eu_member: true,
+      vat_name: "Da\u0148 z pridanej hodnoty",
+      vat_abbr: "DPH",
+      standard: 23,
+      reduced: [
+        5,
+        19
+      ],
+      super_reduced: null,
+      parking: null,
+      format: "SK + 10 digits",
+      pattern: "^SK\\d{10}$"
+    },
+    TR: {
+      country: "Turkey",
+      currency: "TRY",
+      eu_member: false,
+      vat_name: "Katma De\u011Fer Vergisi",
+      vat_abbr: "KDV",
+      standard: 20,
+      reduced: [
+        1,
+        10
+      ],
+      super_reduced: null,
+      parking: null,
+      format: "10 digits",
+      pattern: "^\\d{10}$"
+    },
+    UA: {
+      country: "Ukraine",
+      currency: "UAH",
+      eu_member: false,
+      vat_name: "\u041F\u043E\u0434\u0430\u0442\u043E\u043A \u043D\u0430 \u0434\u043E\u0434\u0430\u043D\u0443 \u0432\u0430\u0440\u0442\u0456\u0441\u0442\u044C",
+      vat_abbr: "\u041F\u0414\u0412",
+      standard: 20,
+      reduced: [
+        7,
+        14
+      ],
+      super_reduced: null,
+      parking: null,
+      format: "9 digits",
+      pattern: "^\\d{9}$"
+    },
+    XI: {
+      country: "Northern Ireland",
+      currency: "GBP",
+      eu_member: false,
+      vat_name: "Value Added Tax",
+      vat_abbr: "VAT",
+      standard: 20,
+      reduced: [
+        5
+      ],
+      super_reduced: null,
+      parking: null,
+      format: "XI + 9 digits, 12 digits, or GD/HA + 3 digits",
+      pattern: "^XI(\\d{9}|\\d{12}|(GD|HA)\\d{3})$"
+    },
+    XK: {
+      country: "Kosovo",
+      currency: "EUR",
+      eu_member: false,
+      vat_name: "Tatimi mbi Vler\xEBn e Shtuar",
+      vat_abbr: "TVSH",
+      standard: 18,
+      reduced: [
+        8
+      ],
+      super_reduced: null,
+      parking: null,
+      format: "9 digits",
+      pattern: "^\\d{9}$"
+    }
+  }
+};
+var dataset = eu_vat_rates_default;
+function getRate(code) {
+  return dataset.rates[code];
+}
+function getAllRates() {
+  return dataset.rates;
+}
+var dataVersion = dataset.version;
+
+// ../../packages/shared/src/validators/index.ts
+import { z } from "zod";
+var EU_COUNTRY_CODES = [
+  "AT",
+  "BE",
+  "BG",
+  "HR",
+  "CY",
+  "CZ",
+  "DK",
+  "EE",
+  "FI",
+  "FR",
+  "DE",
+  "GR",
+  "HU",
+  "IE",
+  "IT",
+  "LV",
+  "LT",
+  "LU",
+  "MT",
+  "NL",
+  "PL",
+  "PT",
+  "RO",
+  "SK",
+  "SI",
+  "ES",
+  "SE",
+  "XI"
+];
+var _rates = getAllRates();
+var VAT_PATTERNS = {};
+for (const code of EU_COUNTRY_CODES) {
+  const entry = _rates[code];
+  if (entry?.pattern) {
+    VAT_PATTERNS[code] = new RegExp(entry.pattern);
+  }
+}
+function normalizeVatId(vatId) {
+  const upper = vatId.trim().toUpperCase().replace(/[\s\-.]/g, "");
+  return upper.startsWith("GR") ? "EL" + upper.slice(2) : upper;
+}
+function extractCountryCode(vatId) {
+  const normalized = normalizeVatId(vatId);
+  if (normalized.startsWith("EL")) return "GR";
+  const code = normalized.slice(0, 2);
+  return EU_COUNTRY_CODES.includes(code) ? code : null;
+}
+function validateVatIdFormat(vatId) {
+  const normalized = normalizeVatId(vatId);
+  if (normalized.length < 4) {
+    return { valid: false, error: "VAT ID too short" };
+  }
+  const countryCode = extractCountryCode(normalized);
+  if (!countryCode) {
+    return { valid: false, error: "Invalid country code" };
+  }
+  const pattern = VAT_PATTERNS[countryCode];
+  if (pattern && !pattern.test(normalized)) {
+    return { valid: false, error: `Invalid VAT ID format for ${countryCode}` };
+  }
+  return { valid: true };
+}
+var vatIdSchema = z.string().min(4).max(20).transform(normalizeVatId);
+var countryCodeSchema = z.enum(EU_COUNTRY_CODES);
+var createSubscriptionSchema = z.object({
+  vatId: vatIdSchema,
+  webhookId: z.string().uuid().optional(),
+  emailEnabled: z.boolean().default(false)
+});
+var updateSubscriptionSchema = z.object({
+  status: z.enum(["active", "paused"]).optional(),
+  webhookId: z.string().uuid().nullable().optional(),
+  emailEnabled: z.boolean().optional()
+});
+var createWebhookSchema = z.object({
+  url: z.string().url()
+});
+var paginationSchema = z.object({
+  page: z.coerce.number().int().positive().default(1),
+  limit: z.coerce.number().int().min(1).max(100).default(20)
+});
+
+// src/index.ts
+var VERSION = "0.1.0";
+var API_BASE = process.env.VATNODE_API_URL ?? "https://api.vatnode.dev";
+var API_KEY = process.env.VATNODE_API_KEY;
+var USER_AGENT = `vatnode-mcp/${VERSION} (+https://vatnode.dev)`;
+var server = new McpServer({ name: "vatnode", version: VERSION });
+var ok = (data) => ({
+  content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+  structuredContent: data
+});
+var err = (message, hint) => ({
+  isError: true,
+  content: [
+    {
+      type: "text",
+      text: hint ? `${message}
+
+Hint: ${hint}` : message
+    }
+  ]
+});
+function buildRate(countryCode) {
+  const r = getRate(countryCode);
+  if (!r) return null;
+  return {
+    countryCode,
+    countryName: r.country,
+    vatName: r.vat_name,
+    vatAbbr: r.vat_abbr,
+    currency: r.currency,
+    standardRate: r.standard,
+    reducedRates: [...r.reduced].sort((a, b) => b - a),
+    superReducedRate: r.super_reduced,
+    parkingRate: r.parking,
+    vatNumberFormat: r.format ?? null,
+    vatNumberPattern: r.pattern ?? null,
+    updatedAt: dataVersion
+  };
+}
+server.registerTool(
+  "list_eu_vat_rates",
+  {
+    title: "List EU VAT rates",
+    description: 'Returns current VAT rates for all 27 EU member states (plus XI for Northern Ireland). Use when the user asks for an overview, a comparison across countries, or "all EU VAT rates". For a single country prefer get_country_vat_rates. Data is sourced from the EU Commission TEDB and updated daily. Free, no API key required.',
+    inputSchema: {}
+  },
+  async () => {
+    const rates = EU_COUNTRY_CODES.map((c) => buildRate(c)).filter(Boolean);
+    return ok({ rates, count: rates.length, updatedAt: dataVersion });
+  }
+);
+server.registerTool(
+  "get_country_vat_rates",
+  {
+    title: "Get VAT rates for a country",
+    description: 'Returns the standard, reduced, super-reduced and parking VAT rates for a single European country, plus the VAT number format and regex. Accepts ISO 3166-1 alpha-2 codes (DE, FR, IT, \u2026); also covers non-EU European jurisdictions where available (NO, CH, GB, UA, TR, \u2026). Use when the user asks "what is the VAT rate in X" or needs the VAT number format for a country. Free, no API key required.',
+    inputSchema: {
+      countryCode: z2.string().length(2).describe('ISO 3166-1 alpha-2 country code, e.g. "DE", "FR", "IT".')
+    }
+  },
+  async ({ countryCode }) => {
+    const rate = buildRate(countryCode.toUpperCase());
+    if (!rate) return err(`No VAT data for country code "${countryCode}".`);
+    return ok(rate);
+  }
+);
+server.registerTool(
+  "check_vat_format",
+  {
+    title: "Check VAT number format",
+    description: "Performs an offline syntactic check of a VAT number against the country-specific regex pattern. Does NOT verify the VAT with VIES \u2014 use validate_vat_number for that. Use when the user wants a quick sanity check on the shape of a VAT ID without burning a quota call. Free, no API key required.",
+    inputSchema: {
+      vatId: z2.string().min(3).describe(
+        'A VAT number, with or without spaces/dashes, with or without country prefix (e.g. "DE123456789", "IE 6388047 V").'
+      )
+    }
+  },
+  async ({ vatId }) => {
+    const normalized = normalizeVatId(vatId);
+    const country = extractCountryCode(normalized);
+    const result = validateVatIdFormat(normalized);
+    return ok({
+      input: vatId,
+      normalized,
+      countryCode: country,
+      validFormat: result.valid,
+      error: result.error ?? null
+    });
+  }
+);
+server.registerTool(
+  "list_supported_countries",
+  {
+    title: "List supported countries",
+    description: "Returns the list of countries the vatnode MCP server has VAT data for. Distinguishes EU member states (eligible for full VIES validation) from other European jurisdictions (rate lookup only).",
+    inputSchema: {}
+  },
+  async () => {
+    const all = getAllRates();
+    const euSet = new Set(EU_COUNTRY_CODES);
+    const countries = Object.entries(all).map(([code, r]) => ({
+      countryCode: code,
+      countryName: r.country,
+      isEUMember: euSet.has(code),
+      viesValidationSupported: euSet.has(code)
+    })).sort((a, b) => a.countryCode.localeCompare(b.countryCode));
+    return ok({
+      countries,
+      count: countries.length,
+      euCount: countries.filter((c) => c.isEUMember).length,
+      updatedAt: dataVersion
+    });
+  }
+);
+async function callVatnodeApi(path, init) {
+  if (!API_KEY) {
+    return {
+      ok: false,
+      error: err(
+        "This tool requires a vatnode API key.",
+        "Set the VATNODE_API_KEY environment variable in your MCP client config. Get a free key at https://vatnode.dev (free tier includes a monthly request quota)."
+      )
+    };
+  }
+  const res = await fetch(`${API_BASE}${path}`, {
+    ...init,
+    headers: {
+      Authorization: `Bearer ${API_KEY}`,
+      "User-Agent": USER_AGENT,
+      Accept: "application/json",
+      ...init?.headers ?? {}
+    }
+  });
+  const body = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    const code = body.error?.code ?? `HTTP_${res.status}`;
+    const message = body.error?.message ?? `vatnode API returned ${res.status}`;
+    return { ok: false, error: err(`${code}: ${message}`) };
+  }
+  return { ok: true, data: body };
+}
+server.registerTool(
+  "validate_vat_number",
+  {
+    title: "Validate EU VAT number",
+    description: "Verifies an EU VAT number against the official VIES service and returns validity, company name, address, registration date and other metadata. When the requester (your own VAT) is configured on the vatnode account, also returns a VIES consultation number \u2014 audit-grade proof of validation. Use whenever the user wants to confirm a VAT is real, look up the company behind a VAT, or needs evidence for accounting/compliance. Requires a vatnode API key (free tier available). Only EU-27 + XI (Northern Ireland) are supported by VIES.",
+    inputSchema: {
+      vatId: z2.string().min(3).describe(
+        'EU VAT number, with country prefix. Spaces and dashes are stripped. Examples: "DE123456789", "IE6388047V", "FR12345678901".'
+      ),
+      requesterCountryCode: z2.string().length(2).optional().describe(
+        "Optional: 2-letter country code of the party doing the check. Together with requesterVatNumber, asks VIES to issue an audit consultation number."
+      ),
+      requesterVatNumber: z2.string().min(1).optional().describe(
+        "Optional: VAT number of the party doing the check. Pair with requesterCountryCode to get a consultation number."
+      )
+    }
+  },
+  async ({ vatId, requesterCountryCode, requesterVatNumber }) => {
+    const normalized = normalizeVatId(vatId);
+    const params = new URLSearchParams();
+    if (requesterCountryCode && requesterVatNumber) {
+      params.set("requesterCountryCode", requesterCountryCode.toUpperCase());
+      params.set("requesterVatNumber", requesterVatNumber);
+    }
+    const qs = params.toString();
+    const result = await callVatnodeApi(
+      `/v1/vat/${encodeURIComponent(normalized)}${qs ? `?${qs}` : ""}`
+    );
+    if (!result.ok) return result.error;
+    return ok(result.data);
+  }
+);
+var transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "vatnode-mcp",
+  "version": "0.1.0",
+  "description": "Official Model Context Protocol (MCP) server for vatnode — EU VAT validation, rates, and format checks for AI agents (Claude, Cursor, ChatGPT).",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "vat",
+    "vies",
+    "eu-vat",
+    "tax",
+    "claude",
+    "anthropic",
+    "vatnode"
+  ],
+  "license": "MIT",
+  "author": "vatnode",
+  "homepage": "https://vatnode.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vatnode/vatnode.git",
+    "directory": "apps/mcp"
+  },
+  "type": "module",
+  "bin": {
+    "vatnode-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "zod": "^3.24.0",
+    "@vatnode/shared": "0.1.0",
+    "eu-vat-rates-data": "2026.3.27"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsup": "^8.3.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  },
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsup",
+    "start": "node dist/index.js",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit",
+    "test": "pnpm build && node test/smoke.mjs"
+  }
+}