vat-validator-mcp 1.0.0 → 1.4.3

package/README.md

@@ -1,47 +1,175 @@
-# VAT Validator MCP
+# VAT Validator MCP — Business Identity Verification & Invoice Fraud Detection
 
-Validate EU, UK, and Australian VAT numbers for AI agents. EU VIES, UK HMRC, and Australian ABN in one call. Required for EU ViDA mandatory e-invoicing compliance.
+Validate EU, UK, and Australian VAT numbers against live government registries. Plus AI-powered fraud risk analysis and invoice verification — so your agent doesn't just know a VAT number is valid, it knows whether to proceed with the transaction.
 
-## Free Tier
+**Free tier: 20 calls/month. No API key required. Just connect and go.**
 
-20 validations/month. No API key required. Just connect and start validating.
+## Quick Start
+
+```json
+{
+  "vat-validator": {
+    "url": "https://vat-validator-mcp-production.up.railway.app"
+  }
+}
+```
+
+Or via Smithery:
+
+```bash
+npx -y @smithery/cli@latest mcp add OjasKord/vat-validator-mcp
+```
+
+## Why Use This
+
+A VAT number is the most reliable identifier for a registered business in the EU, UK, and Australia. Validating it confirms the company is real and legally registered. But validation alone isn't enough — scammers use valid VAT numbers with mismatched company names, or invoice from newly registered shells. The AI tools in this server catch what raw validation misses.
+
+Required for EU ViDA mandatory e-invoicing compliance from 2026.
 
 ## Tools
 
-### validate_vat
-Validate any VAT number — auto-detects country from prefix and routes to the correct authority.
-- EU (all 27 member states) via VIES
-- UK (GB prefix) via HMRC
-- Australia (AU prefix or 11-digit ABN) via ABR
+### `validate_vat`
+Validate any EU, UK, or Australian VAT number against live government registries. Auto-detects country from prefix. Use before any B2B transaction, supplier onboarding, or invoice approval.
 
-### validate_uk_vat
-Validate UK VAT numbers against HMRC live records. Returns consultation number for audit trail.
+- EU (all 27 member states) via EU VIES (ec.europa.eu/taxation_customs/vies)
+- UK (GB prefix) via UK HMRC (api.service.hmrc.gov.uk)
+- Australia (AU prefix or 11-digit ABN) via Australian ABR (abr.business.gov.au)
 
-### get_vat_rates
-Get current VAT rates for any EU country, UK, or Australia. Returns standard and all reduced rates.
+```json
+{ "vat_number": "DE811128135" }
+```
 
-### batch_validate
-Validate up to 10 VAT numbers in one call across any mix of EU, UK, and Australian numbers. Paid tier only.
+### `validate_uk_vat`
+UK-specific validation against HMRC live records. Returns HMRC consultation number for audit trail. Use when you need to prove compliance during a tax audit.
 
-## Pricing
+```json
+{ "vat_number": "GB123456789" }
+```
 
-- **Free**: 20 validations/month, no API key
-- **Pro**: $99/month — 5,000 validations/month
-- **Enterprise**: $299/month — unlimited + batch validation
+### `get_vat_rates`
+Current VAT rates for all 27 EU member states, UK, and Australia. Use before generating any cross-border invoice or quote.
 
-Get your API key at [kordagencies.com](https://kordagencies.com)
+```json
+{ "country_code": "DE" }
+```
 
-## Legal
+### `batch_validate` *(Paid only)*
+Validate up to 10 VAT numbers in one call across any mix of EU, UK, and Australian numbers. Use for supplier onboarding batches and monthly vendor audits.
 
-Results are for informational purposes only and do not constitute legal or tax advice. Verify all results with a qualified tax advisor. Full terms: kordagencies.com/terms.html
+```json
+{ "vat_numbers": ["DE811128135", "GB123456789", "FR12345678901"] }
+```
 
-## MCP Config
+### `analyse_vat_risk` *(AI-powered — NOT a database lookup)*
+AI fraud risk assessment after validation. Returns CLEAR/REVIEW/BLOCK recommendation with specific fraud signals. Catches name mismatches between invoice and registry, newly registered companies with large invoice values, dormant status, shell company indicators, and address anomalies. Use before approving any payment or signing any contract with a first-time counterparty.
 
 ```json
 {
-  "vat-validator": {
-    "url": "https://vat-validator-mcp-production.up.railway.app",
-    "headers": { "x-api-key": "YOUR_API_KEY" }
-  }
+  "vat_number": "DE811128135",
+  "validation_result": { "valid": true, "company_name": null, "country": "DE" },
+  "invoice_amount": 50000,
+  "invoice_company_name": "Deutsche Test GmbH"
+}
+```
+
+### `compare_invoice_details` *(AI-powered — NOT a database lookup)*
+AI comparison of invoice details against official registry records. Flags discrepancies between the company name, address, and VAT number on an invoice versus registered government data. A name mismatch is one of the most common invoice fraud signals. Use before approving payment on any invoice from an unverified supplier.
+
+```json
+{
+  "invoice_company_name": "Deutsche Test GmbH",
+  "invoice_vat_number": "DE811128135",
+  "invoice_address": "Musterstrasse 1, Berlin",
+  "validation_result": { "valid": true, "company_name": null, "country": "DE" }
+}
+```
+
+## Example Responses
+
+**validate_vat:**
+```json
+{
+  "valid": true,
+  "vat_number": "DE811128135",
+  "country": "DE",
+  "company_name": null,
+  "source": "VIES",
+  "source_url": "ec.europa.eu/taxation_customs/vies",
+  "checked_at": "2026-04-09T06:17:00Z"
+}
+```
+
+**analyse_vat_risk:**
+```json
+{
+  "recommendation": "REVIEW",
+  "risk_level": "MEDIUM",
+  "risk_score": 65,
+  "fraud_signals": ["Company name not available in registry despite valid VAT number", "Unable to verify invoice company name against registry data"],
+  "positive_indicators": ["VAT number validates as authentic in German registry"],
+  "recommended_action": "Request additional company documentation before processing payment.",
+  "summary": "Valid VAT number but missing registry information prevents full verification."
 }
 ```
+
+## Recommended Workflows
+
+**Invoice processing (3 calls):**
+1. `validate_vat` — confirm VAT number is real and active
+2. `compare_invoice_details` — AI checks invoice name/address against registry
+3. `analyse_vat_risk` — AI fraud risk assessment with CLEAR/REVIEW/BLOCK
+Only proceed with payment if recommendation is CLEAR.
+
+**Supplier onboarding (2 calls):**
+1. `validate_vat` — confirm registration
+2. `analyse_vat_risk` — AI fraud signal check
+
+**Monthly vendor audit (1 call):**
+- `batch_validate` — re-validate all active suppliers. Registrations can lapse.
+
+## Data Sources
+
+| Tool | Data Source | Update Frequency |
+|---|---|---|
+| validate_vat (EU) | EU VIES (ec.europa.eu/taxation_customs/vies) | Real-time |
+| validate_vat (UK) | UK HMRC (api.service.hmrc.gov.uk) | Real-time |
+| validate_vat (AU) | Australian ABR (abr.business.gov.au) | Real-time |
+| analyse_vat_risk | Registry data + Claude AI analysis | Real-time |
+| compare_invoice_details | Registry data + Claude AI analysis | Real-time |
+
+Every response includes `source_url` and `checked_at` so agents can verify exactly where data came from and when.
+
+## Supported Jurisdictions
+
+**EU (27 member states):** AT BE BG CY CZ DE DK EE EL ES FI FR HR HU IE IT LT LU LV MT NL PL PT RO SE SI SK
+
+**UK:** GB prefix via HMRC
+
+**Australia:** AU prefix or 11-digit ABN via ABR
+
+## Pricing
+
+| Plan | Validations | Price |
+|---|---|---|
+| Free | 20/month | No API key required |
+| Pro | 5,000/month | $39/month |
+| Enterprise | Unlimited + batch | $199/month |
+
+Upgrade at **[kordagencies.com](https://kordagencies.com)**
+
+## Reliability
+
+- Uptime monitored every 5 minutes via UptimeRobot
+- Version history documented in [CHANGELOG.md](CHANGELOG.md)
+- Health endpoint: `GET /health`
+- Note: EU VIES experiences periodic downtime — errors include explanation and retry guidance
+
+## Legal
+
+Results sourced directly from official government VAT registries (EU VIES, UK HMRC, Australian ABR). We do not log or store your query content. Results are for informational purposes only and do not constitute legal or tax advice. Verify all results with a qualified tax advisor. Maximum liability limited to 3 months subscription fees. Full terms: [kordagencies.com/terms.html](https://kordagencies.com/terms.html)
+
+## Connect
+
+- Website: [kordagencies.com](https://kordagencies.com)
+- Smithery: [smithery.ai/server/OjasKord/vat-validator-mcp](https://smithery.ai/server/OjasKord/vat-validator-mcp)
+- Contact: ojas@kordagencies.com

package/package.json

@@ -1,18 +1,44 @@
 {
   "name": "vat-validator-mcp",
-  "version": "1.0.0",
+  "mcpName": "io.github.OjasKord/vat-validator-mcp",
+  "version": "1.4.3",
   "description": "VAT number validation for AI agents. EU VIES, UK HMRC, Australian ABN in one call.",
   "main": "src/server.js",
   "scripts": {
     "start": "node src/server.js"
   },
-  "mcpName": "io.github.OjasKord/vat-validator-mcp",
-  "keywords": ["mcp", "vat", "vat-validation", "eu-vat", "hmrc", "vies", "e-invoicing", "tax-compliance", "b2b", "invoice", "vida"],
-  "author": "Ojas Kord <ojas@kordagencies.com>",
+  "keywords": [
+    "mcp",
+    "vat",
+    "vat-validation",
+    "eu-vat",
+    "hmrc",
+    "vies",
+    "e-invoicing",
+    "tax-compliance",
+    "b2b",
+    "invoice",
+    "vida",
+    "uk-vat",
+    "australian-abn",
+    "invoice-fraud",
+    "vat-fraud",
+    "validator",
+    "tax-verification",
+    "supplier-verification",
+    "compliance"
+  ],
+  "author": "Kord Agencies Pte Ltd <ojas@kordagencies.com>",
   "license": "UNLICENSED",
   "homepage": "https://kordagencies.com",
   "repository": {
     "type": "git",
-    "url": "https://github.com/OjasKord/vat-validator-mcp"
+    "url": "git+https://github.com/OjasKord/vat-validator-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/OjasKord/vat-validator-mcp/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
   }
 }

package/patch_vat_v134.js

@@ -0,0 +1,84 @@
+const fs = require('fs');
+let c = fs.readFileSync('C:/vat-validator-mcp/src/server.js', 'utf8');
+
+console.log('File size:', c.length);
+console.log('Has vat_stats:', c.includes('vat_stats'));
+console.log('Version 1.3.2:', c.includes('1.3.2'));
+console.log('Has validate_vat:', c.includes('validate_vat'));
+
+if (!c.includes('vat_stats')) {
+  console.error('ERROR: Wrong file');
+  process.exit(1);
+}
+
+// 1. Add FREE_TIER_WARNING constant
+c = c.replace(
+  'const FREE_TIER_LIMIT = 20;',
+  'const FREE_TIER_LIMIT = 20;\nconst FREE_TIER_WARNING = 16; // warn at 80% usage'
+);
+
+// 2. Bump version to 1.4.0
+c = c.replace(/1\.3\.2/g, '1.4.0');
+
+// 3. Add partial response logic in tools/call handler
+// Find the existing tools/call result handling
+const oldResult = `          const result = await executeTool(name, toolArgs || {});
+          if (req._accessWarning) result._notice = req._accessWarning;
+          response = { jsonrpc: '2.0', id: request.id, result: { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] } };`;
+
+const newResult = `          const result = await executeTool(name, toolArgs || {});
+          if (req._accessWarning) result._notice = req._accessWarning;
+
+          // Partial response for free tier
+          if (req._tier === 'free' && !result.error) {
+            const ip = req.headers['x-forwarded-for'] || req.socket.remoteAddress || 'unknown';
+            const used = freeTierUsage.get(ip) || 0;
+            const remaining = FREE_TIER_LIMIT - used;
+            const isWarning = used >= FREE_TIER_WARNING;
+
+            if (name === 'validate_vat' || name === 'validate_uk_vat') {
+              // Gate address on free tier — company name + valid status visible
+              const gated = ['registered_address', 'address', 'consultation_number'];
+              gated.forEach(f => delete result[f]);
+              result._upgrade_note = 'Free tier: ' + remaining + ' of ' + FREE_TIER_LIMIT + ' calls remaining. Upgrade to Pro ($39/month) at kordagencies.com for full registered address and HMRC consultation number.';
+              result._gated_fields = gated;
+            }
+
+            if (name === 'analyse_vat_risk') {
+              // Gate full reasoning — verdict visible, details gated
+              const gated = ['fraud_signals', 'positive_indicators', 'recommended_action', 'summary'];
+              gated.forEach(f => delete result[f]);
+              result._upgrade_note = 'Free tier: ' + remaining + ' of ' + FREE_TIER_LIMIT + ' calls remaining. Upgrade to Pro ($39/month) at kordagencies.com for full fraud signal breakdown, positive indicators, and recommended action.';
+              result._gated_fields = gated;
+            }
+
+            if (name === 'compare_invoice_details') {
+              // Gate detail fields — match_status visible, discrepancies gated
+              const gated = ['discrepancies', 'name_match', 'address_match', 'recommended_action', 'summary'];
+              gated.forEach(f => delete result[f]);
+              result._upgrade_note = 'Free tier: ' + remaining + ' of ' + FREE_TIER_LIMIT + ' calls remaining. Upgrade to Pro ($39/month) at kordagencies.com for full discrepancy analysis and recommended action.';
+              result._gated_fields = gated;
+            }
+
+            if (isWarning) result._notice = 'Warning: only ' + remaining + ' free call' + (remaining === 1 ? '' : 's') + ' left this month. Upgrade to Pro at kordagencies.com to avoid interruption.';
+          }
+
+          response = { jsonrpc: '2.0', id: request.id, result: { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] } };`;
+
+if (!c.includes(oldResult)) {
+  console.error('ERROR: Could not find tool call handler');
+  const idx = c.indexOf('executeTool(name');
+  console.log('executeTool at:', idx);
+  console.log('Context:', c.substring(idx - 20, idx + 150));
+  process.exit(1);
+}
+
+c = c.replace(oldResult, newResult);
+
+console.log('FREE_TIER_WARNING:', c.includes('FREE_TIER_WARNING'));
+console.log('Version 1.4.0:', c.includes('1.4.0'));
+console.log('Partial response:', c.includes('_upgrade_note'));
+console.log('New size:', c.length);
+
+fs.writeFileSync('C:/vat-validator-mcp/src/server.js', c);
+console.log('Done');

package/server.json

@@ -3,15 +3,24 @@
   "name": "io.github.OjasKord/vat-validator-mcp",
   "title": "VAT Validator MCP",
   "description": "Validate EU, UK, AU VAT numbers for AI agents. EU ViDA e-invoicing compliance.",
-  "version": "1.0.0",
-  "repository": { "url": "https://github.com/OjasKord/vat-validator-mcp", "source": "github" },
-  "packages": [{
-    "registryType": "npm",
-    "registryBaseUrl": "https://registry.npmjs.org",
-    "identifier": "vat-validator-mcp",
-    "version": "1.0.0",
-    "transport": { "type": "stdio" },
-    "environmentVariables": []
-  }],
+  "version": "1.4.3",
+  "websiteUrl": "https://kordagencies.com",
+  "repository": {
+    "url": "https://github.com/OjasKord/vat-validator-mcp",
+    "source": "github"
+  },
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "vat-validator-mcp",
+      "version": "1.4.3",
+      "transport": { "type": "stdio" },
+      "environmentVariables": [
+        { "name": "ANTHROPIC_API_KEY", "description": "Anthropic API key for AI-powered fraud risk analysis", "isRequired": true, "isSecret": true },
+        { "name": "HMRC_CLIENT_ID", "description": "HMRC Developer Hub client ID for UK VAT validation", "isRequired": false, "isSecret": true },
+        { "name": "HMRC_CLIENT_SECRET", "description": "HMRC Developer Hub client secret for UK VAT validation", "isRequired": false, "isSecret": true }
+      ]
+    }
+  ],
   "remotes": [{ "type": "streamable-http", "url": "https://vat-validator-mcp-production.up.railway.app" }]
 }

package/smithery.yaml

@@ -12,55 +12,84 @@ startCommand:
     required: []
 
 systemPrompt: |
-  VAT Validator MCP validates VAT numbers for AI agents handling B2B invoicing, supplier onboarding, and e-invoicing compliance.
+  VAT Validator MCP is a business identity verification and invoice fraud detection layer for AI agents.
 
-  EU ViDA (VAT in the Digital Age) regulation now requires VAT validation as part of mandatory e-invoicing across EU member states. An invalid VAT number on a B2B invoice can result in tax authority fines, rejected invoices, and loss of VAT reclaim rights.
+  It combines official government VAT registry data (EU VIES, UK HMRC, Australian ABR) with AI-powered fraud analysis to give agents a complete picture before any B2B transaction.
+
+  TWO LAYERS OF INTELLIGENCE
+
+  Layer 1 - Government Registry Validation (validate_vat, validate_uk_vat, get_vat_rates, batch_validate)
+  Confirms a business is real and registered with official authorities.
+
+  Layer 2 - AI-Powered Fraud Analysis (analyse_vat_risk, compare_invoice_details)
+  Uses AI to synthesise registry data with transaction context to detect fraud signals that raw validation misses.
+  This is not a database lookup - it is intelligent analysis that catches subtle red flags.
 
   WHEN TO USE THIS SERVER
 
-  Call these tools whenever your agent:
-  - Is about to generate a B2B invoice for an EU, UK, or Australian business
-  - Is onboarding a new supplier or customer from the EU or UK
-  - Needs to apply the correct VAT rate to a cross-border transaction
-  - Is running a compliance audit on existing supplier VAT numbers
-  - Is processing a batch of invoices and needs to verify all VAT numbers
+  Use these tools whenever your agent is about to:
+  - Onboard a new supplier, vendor, customer, or contractor
+  - Process or approve an incoming invoice
+  - Sign or draft a B2B contract
+  - Make a payment to an unfamiliar company
+  - Apply B2B tax exemptions in e-commerce
+  - Audit or enrich CRM company records
+  - Run periodic compliance checks on active counterparties
+
+  RECOMMENDED WORKFLOW FOR INVOICE PROCESSING
+
+  When your agent receives an invoice from a new or unverified supplier:
+  1. validate_vat - confirm the VAT number is real and active
+  2. compare_invoice_details - AI checks if invoice details match registry (catches impersonation fraud)
+  3. analyse_vat_risk - AI risk assessment with CLEAR/REVIEW/BLOCK recommendation
+  Only proceed with payment if recommendation is CLEAR.
+
+  RECOMMENDED WORKFLOW FOR SUPPLIER ONBOARDING
+
+  When adding a new supplier to your approved vendor list:
+  1. validate_vat - confirm registration
+  2. analyse_vat_risk - AI fraud signal check
+  3. batch_validate - periodic re-validation of all active suppliers monthly
 
   TOOLS
 
   validate_vat
-  - Call for any VAT number from EU (all 27 countries), UK, or Australia
-  - Auto-detects country from prefix and routes to correct authority
-  - Returns valid/invalid, company name, address
-  - Use before generating any B2B invoice
-  - Free tier: no API key needed for first 20 calls/month
+  - Validates any EU, UK, or Australian VAT number against live government registries
+  - Auto-detects country from prefix
+  - Free tier: first 20 calls/month, no API key needed
 
   validate_uk_vat
-  - Call specifically for UK VAT numbers when you need the HMRC consultation number for your audit trail
-  - More detailed than validate_vat for UK numbers
-  - Returns company name, registered address, consultation number
-  - Free tier: no API key needed for first 20 calls/month
+  - UK-specific HMRC validation with consultation number for audit trail
+  - Free tier: first 20 calls/month, no API key needed
 
   get_vat_rates
-  - Call when you need to apply the correct VAT rate to an invoice or quote
-  - Covers all 27 EU member states, UK, and Australia
-  - Returns standard rate and all reduced rates
-  - Always verify with official tax authority before use
-  - Free tier: no API key needed for first 20 calls/month
+  - Current VAT rates for all 27 EU countries, UK, and Australia
+  - Free tier: first 20 calls/month, no API key needed
 
   batch_validate
-  - Call when you need to validate multiple VAT numbers at once
-  - Up to 10 numbers per call, any mix of EU/UK/AU
-  - Use for supplier audits or onboarding batches
-  - Requires paid API key
+  - Validate up to 10 VAT numbers in one call
+  - Use for supplier audits and onboarding batches
+  - Paid API key required
+
+  analyse_vat_risk (AI-POWERED)
+  - Call after validate_vat when you need a fraud risk assessment
+  - AI analyses registry data + transaction context for fraud signals
+  - Returns CLEAR/REVIEW/BLOCK recommendation with specific reasons
+  - Catches: name mismatches, newly registered companies, dormant status, shell company indicators
+  - Free tier: first 20 calls/month, no API key needed
+
+  compare_invoice_details (AI-POWERED)
+  - Call when processing an invoice to verify supplier details match registry records
+  - AI compares invoice name/address/VAT against official registered data
+  - Flags discrepancies that indicate fraud, impersonation, or error
+  - Returns APPROVE/REVIEW/REJECT recommendation
+  - Free tier: first 20 calls/month, no API key needed
 
   LEGAL NOTICE
-  All results are for informational purposes only and do not constitute legal or tax advice. Operator must independently verify results with a qualified tax advisor before making compliance decisions. Full terms: kordagencies.com/terms.html
+  All results are for informational purposes only and do not constitute legal or tax advice.
+  Operator must independently verify results before making compliance decisions.
+  Full terms: kordagencies.com/terms.html
 
   FREE TIER
-  20 validations/month with no API key.
-  Upgrade at kordagencies.com - Pro $99/month (5,000 validations), Enterprise $299/month (unlimited + batch).
-
-  COUNTRY CODES
-  EU: AT BE BG CY CZ DE DK EE EL ES FI FR HR HU IE IT LT LU LV MT NL PL PT RO SE SI SK
-  UK: GB prefix
-  Australia: AU prefix or 11-digit ABN
+  20 calls/month with no API key.
+  Upgrade at kordagencies.com - Pro $99/month (5,000 calls), Enterprise $299/month (unlimited + batch).