check_vat_number
Validate EU VAT numbers through the official VIES service to verify tax compliance and retrieve company information for all 27 EU member states.
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 execution handler for 'check_vat_number': parses arguments using checkVatNumberSchema, delegates to ViesApiClient.checkVatNumber(), formats the result into a text response.
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:36-55 (registration)Registration of the 'check_vat_number' tool in the ListTools response, defining name, description, and input schema matching the Zod schema.
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 input schema for 'check_vat_number' tool: validates countryCode against EU_MEMBER_STATES enum and vatNumber as non-empty string up to 20 chars.
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:54-86 (helper)Core implementation in ViesApiClient: POST request to VIES /check-vat-number endpoint, Zod validation of response, mapping to VatNumberInfo with preprocessing handling and error management.
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; } }