check_vat_number
Validate EU VAT numbers using the official VIES service to confirm registration status and retrieve company information for business verification.
Instructions
Validate EU VAT number using VIES service / Overiť IČ DPH v EÚ pomocou služby VIES
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| countryCode | Yes | EU member state code (e.g., SK, CZ, DE) / Kód členského štátu EÚ | |
| vatNumber | Yes | VAT number without country prefix / IČ DPH bez predpony krajiny |
Implementation Reference
- src/index.ts:102-116 (handler)MCP tool handler for 'check_vat_number': parses input arguments using the schema, calls ViesApiClient to validate VAT number, formats the result, and returns it as text content.case 'check_vat_number': { const params = checkVatNumberSchema.parse(args); const result = await this.viesClient.checkVatNumber(params); const responseText = this.formatVatValidationResult(result); return { content: [ { type: 'text', text: responseText, }, ], }; }
- src/index.ts:35-55 (registration)Registers the 'check_vat_number' tool in the MCP server's tool list, including name, description, and input schema definition.{ name: 'check_vat_number', description: 'Validate EU VAT number using VIES service / Overiť IČ DPH v EÚ pomocou služby VIES', inputSchema: { type: 'object', properties: { countryCode: { type: 'string', enum: [...EU_MEMBER_STATES], description: 'EU member state code (e.g., SK, CZ, DE) / Kód členského štátu EÚ', }, vatNumber: { type: 'string', description: 'VAT number without country prefix / IČ DPH bez predpony krajiny', minLength: 1, maxLength: 20, }, }, required: ['countryCode', 'vatNumber'], }, },
- src/schemas.ts:11-16 (schema)Zod schema definition for validating input parameters of the check_vat_number tool (countryCode and vatNumber).export const checkVatNumberSchema = z.object({ countryCode: z.enum(EU_MEMBER_STATES, { errorMap: () => ({ message: 'Invalid EU member state code' }) }), vatNumber: z.string().min(1, 'VAT number is required').max(20, 'VAT number too long'), });
- src/client.ts:51-86 (helper)Core logic in ViesApiClient that performs the HTTP POST to VIES API to check VAT number validity, parses response, handles errors, and returns structured VatNumberInfo./** * Validate a VAT number using the VIES service */ async checkVatNumber(params: CheckVatNumberParams): Promise<VatNumberInfo> { try { const response = await this.client.post('/check-vat-number', { countryCode: params.countryCode, vatNumber: params.vatNumber, }); const validatedData = vatValidationResponseSchema.parse(response.data); return { countryCode: validatedData.countryCode || params.countryCode, vatNumber: validatedData.vatNumber || params.vatNumber, isValid: validatedData.valid, companyName: validatedData.name, companyAddress: validatedData.address, requestDate: validatedData.requestDate, wasPreprocessed: validatedData.originalVatNumber !== undefined, originalVatNumber: validatedData.originalVatNumber, originalCountryCode: validatedData.originalCountryCode, }; } catch (error) { if (error instanceof ViesApiError) { // Try to parse error response try { const errorData = errorResponseSchema.parse(error.response); throw new Error(`VIES validation failed: ${errorData.error}${errorData.message ? ` - ${errorData.message}` : ''}`); } catch { throw error; } } throw error; } }
- src/index.ts:211-239 (helper)Helper method to format the VAT validation result into a user-friendly bilingual (English/Slovak) text response.private formatVatValidationResult(result: any, isTest = false): string { const testPrefix = isTest ? '[TEST] ' : ''; const header = isTest ? `${testPrefix}VAT Test Service Result / Výsledok testovej služby IČ DPH:` : `${testPrefix}VAT Validation Result / Výsledok validácie IČ DPH:`; let response = `${header}\n\n`; response += `Country Code / Kód krajiny: ${result.countryCode}\n`; response += `VAT Number / IČ DPH: ${result.vatNumber}\n`; response += `Valid / Platné: ${result.isValid ? 'YES / ÁNO' : 'NO / NIE'}\n`; response += `Request Date / Dátum požiadavky: ${result.requestDate}\n`; if (result.companyName) { response += `Company Name / Názov spoločnosti: ${result.companyName}\n`; } if (result.companyAddress) { response += `Company Address / Adresa spoločnosti: ${result.companyAddress}\n`; } if (result.wasPreprocessed && result.originalVatNumber) { response += `\nNote / Poznámka: VAT number was preprocessed / IČ DPH bolo predspracované\n`; response += `Original VAT Number / Pôvodné IČ DPH: ${result.originalVatNumber}\n`; if (result.originalCountryCode) { response += `Original Country Code / Pôvodný kód krajiny: ${result.originalCountryCode}\n`; } } return response;