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; }