RS.ge Waybill MCP Server

Instructions

Implementation Reference

• src/tools/get-waybills.ts:62-125 (handler)

  Core handler function that executes the get_waybills tool: validates input with Zod, calls SOAP client.getWaybillsV1, formats waybills into readable text response.

  export async function executeGetWaybills(
    client: RsWaybillSoapClient,
    input: unknown
  ): Promise<string> {
    const logger = getLogger();
  
    try {
      // Validate input
      const validated = GetWaybillsInputSchema.parse(input);
  
      logger.info('Getting waybills', {
        startDate: validated.start_date,
        endDate: validated.end_date,
        buyerTin: validated.buyer_tin,
      });
  
      // Call SOAP API
      const waybills = await client.getWaybillsV1(
        validated.start_date,
        validated.end_date,
        validated.buyer_tin
      );
  
      logger.info(`Retrieved ${waybills.length} waybills`);
  
      // Format response for Claude
      if (waybills.length === 0) {
        return `No waybills found for date range ${validated.start_date} to ${validated.end_date}` +
          (validated.buyer_tin ? ` with buyer TIN ${validated.buyer_tin}` : '');
      }
  
      let response = `Found ${waybills.length} waybill(s) for ${validated.start_date} to ${validated.end_date}\n\n`;
  
      waybills.forEach((wb, index) => {
        response += `${index + 1}. Waybill #${wb.ID}\n`;
        response += `   Type: ${wb.TYPE}\n`;
        response += `   Buyer: ${wb.BUYER_TIN}${wb.BUYER_NAME ? ` (${wb.BUYER_NAME})` : ''}\n`;
  
        if (wb.SELLER_TIN) {
          response += `   Seller: ${wb.SELLER_TIN}\n`;
        }
  
        response += `   Status: ${wb.STATUS}\n`;
        response += `   Amount: ${wb.FULL_AMOUNT}\n`;
        response += `   Date: ${wb.CREATE_DATE || wb.BEGIN_DATE}\n`;
  
        if (wb.CAR_NUMBER) {
          response += `   Car: ${wb.CAR_NUMBER}\n`;
        }
  
        if (wb.END_ADDRESS) {
          response += `   Delivery: ${wb.END_ADDRESS}\n`;
        }
  
        response += '\n';
      });
  
      return response;
  
    } catch (error) {
      logger.error('Error in get_waybills tool', { error });
      return formatErrorForUser(error);
    }
  }

• src/tools/get-waybills.ts:32-57 (schema)

  MCP tool definition including name, description, and inputSchema for get_waybills (JSON Schema). Zod schema GetWaybillsInputSchema is above at lines 15-25.

  export const getWaybillsTool = {
    name: 'get_waybills',
    description:
      'Get waybills from RS.ge for a specific date range. Returns all waybills ' +
      'created within the specified dates. Can optionally filter by buyer TIN.',
    inputSchema: {
      type: 'object' as const,
      properties: {
        start_date: {
          type: 'string',
          description: 'Start date in YYYY-MM-DD format (e.g., "2025-10-17")',
          pattern: '^\\d{4}-\\d{2}-\\d{2}$',
        },
        end_date: {
          type: 'string',
          description: 'End date in YYYY-MM-DD format (e.g., "2025-10-20")',
          pattern: '^\\d{4}-\\d{2}-\\d{2}$',
        },
        buyer_tin: {
          type: 'string',
          description: 'Optional: Filter by buyer TIN (tax identification number)',
        },
      },
      required: ['start_date', 'end_date'],
    },
  };

• src/index.ts:113-118 (registration)

  Registration of getWaybillsTool in the MCP server's listTools handler, conditionally based on feature flag.

  const tools = [];
  
  // Add tools based on feature flags
  if (features.getWaybills) {
    tools.push(getWaybillsTool);
  }

• src/index.ts:149-154 (registration)

  Dispatch/execution routing for 'get_waybills' tool in the MCP server's callTool handler.

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

• src/services/soap-client.ts:185-223 (helper)

  Supporting SOAP client method getWaybillsV1 called by the tool handler to perform the actual 'get_waybills' API operation.

  async getWaybillsV1(
    startDate?: string,
    endDate?: string,
    buyerTin?: string
  ): Promise<Waybill[]> {
    // Validate date range
    if (!startDate || !endDate) {
      throw new SoapApiError(
        'Start date and end date are required. ' +
        'RS.ge API requires date ranges to be specified.'
      );
    }
  
    // Create and validate date range
    const dateRange = DateRange.create(startDate, endDate);
    const apiDates = dateRange.toApiFormat();
  
    // Extract seller_un_id from credentials (e.g., "4053098841:405309884" -> "405309884")
    const sellerUnId = this.credentials.user.includes(':')
      ? this.credentials.user.split(':')[1]
      : '';
  
    this.logger.info(`Querying waybills: ${dateRange.toString()}`);
  
    const response = await this.callSoap<GetWaybillsResponse>('get_waybills', {
      su: this.credentials.user,
      sp: this.credentials.password,
      seller_un_id: sellerUnId,
      create_date_s: apiDates.start,
      create_date_e: apiDates.end,
      buyer_tin: buyerTin || '',
    });
  
    const waybills = normalizeToArray(response.WAYBILL_LIST?.WAYBILL).map(normalizeWaybill);
  
    this.logger.info(`Received ${waybills.length} waybills from API`);
  
    return waybills;
  }