RS.ge Waybill MCP Server

Instructions

Implementation Reference

• src/tools/lookup-tin.ts:49-74 (handler)

  The main handler function that executes the lookup_tin tool logic: validates the input TIN using Zod schema, calls the SOAP client's getNameFromTin method, formats the result or error message.

  export async function executeLookupTin(
    client: RsWaybillSoapClient,
    input: unknown
  ): Promise<string> {
    const logger = getLogger();
  
    try {
      // Validate input
      const validated = LookupTinInputSchema.parse(input);
  
      logger.info('Looking up TIN', { tin: validated.tin });
  
      // Call SOAP API
      const name = await client.getNameFromTin(validated.tin);
  
      if (!name || name.trim() === '') {
        return `No company or person found for TIN: ${validated.tin}`;
      }
  
      return `TIN ${validated.tin}: ${name}`;
  
    } catch (error) {
      logger.error('Error in lookup_tin tool', { error });
      return formatErrorForUser(error);
    }
  }

• src/tools/lookup-tin.ts:15-22 (schema)

  Zod schema for validating the input to the lookup_tin tool, requiring a TIN string between 9-11 characters.

  export const LookupTinInputSchema = z.object({
    tin: z.string()
      .min(9)
      .max(11)
      .describe('Tax identification number (TIN) to lookup'),
  });
  
  export type LookupTinInput = z.infer<typeof LookupTinInputSchema>;

• src/tools/lookup-tin.ts:27-44 (registration)

  MCP tool registration object defining the lookup_tin tool's name, description, and JSON input schema.

  export const lookupTinTool = {
    name: 'lookup_tin',
    description:
      'Look up a company or person name from their TIN (Tax Identification Number) ' +
      'in the RS.ge system.',
    inputSchema: {
      type: 'object' as const,
      properties: {
        tin: {
          type: 'string',
          description: 'Tax identification number (TIN) - 9 to 11 digits',
          minLength: 9,
          maxLength: 11,
        },
      },
      required: ['tin'],
    },
  };

• src/index.ts:120-122 (registration)

  Conditional registration of the lookup_tin tool into the list returned by ListToolsRequestHandler, based on feature flag.

  if (features.getNameFromTin) {
    tools.push(lookupTinTool);
  }

• src/index.ts:156-161 (handler)

  Dispatcher case in CallToolRequestHandler that invokes the executeLookupTin handler when lookup_tin is called, checking feature flag.

  case 'lookup_tin':
    if (!features.getNameFromTin) {
      throw new Error('lookup_tin tool is disabled');
    }
    result = await executeLookupTin(soapClient, args);
    break;