VAT Validation MCP Server

Instructions

Implementation Reference

• src/index.ts:118-132 (handler)

  MCP tool handler for 'check_vat_test_service': parses input with schema, calls ViesApiClient method, formats response as text

  case 'check_vat_test_service': {
    const params = checkVatTestSchema.parse(args);
    const result = await this.viesClient.checkVatTestService(params);
    
    const responseText = this.formatVatValidationResult(result, true);
    
    return {
      content: [
        {
          type: 'text',
          text: responseText,
        },
      ],
    };
  }

• src/index.ts:57-75 (registration)

  Registration of 'check_vat_test_service' tool in the ListTools response, including input schema definition

    name: 'check_vat_test_service',
    description: 'Test VIES service integration with test VAT numbers / Testovať integráciu so službou VIES',
    inputSchema: {
      type: 'object',
      properties: {
        countryCode: {
          type: 'string',
          enum: [...EU_MEMBER_STATES],
          description: 'EU member state code / Kód členského štátu EÚ',
        },
        vatNumber: {
          type: 'string',
          enum: ['100', '200'],
          description: 'Test VAT number: 100 (valid), 200 (invalid) / Testové IČ DPH: 100 (platné), 200 (neplatné)',
        },
      },
      required: ['countryCode', 'vatNumber'],
    },
  },

• src/schemas.ts:18-23 (schema)

  Zod input validation schema used for parsing tool arguments: checkVatTestSchema

  export const checkVatTestSchema = z.object({
    countryCode: z.enum(EU_MEMBER_STATES),
    vatNumber: z.enum(['100', '200'], {
      errorMap: () => ({ message: 'Test VAT number must be 100 (valid) or 200 (invalid)' })
    }),
  });

• src/client.ts:91-120 (helper)

  ViesApiClient method implementing the HTTP POST to VIES '/check-vat-test-service' endpoint, parses response and maps to VatNumberInfo

  async checkVatTestService(params: CheckVatTestParams): Promise<VatNumberInfo> {
    try {
      const response = await this.client.post('/check-vat-test-service', {
        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: false, // Test service doesn't preprocess
      };
    } catch (error) {
      if (error instanceof ViesApiError) {
        try {
          const errorData = errorResponseSchema.parse(error.response);
          throw new Error(`VIES test service failed: ${errorData.error}${errorData.message ? ` - ${errorData.message}` : ''}`);
        } catch {
          throw error;
        }
      }
      throw error;
    }
  }