RS.ge Waybill MCP Server

Instructions

Implementation Reference

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

  The main handler function that executes the get_waybills tool: validates input, calls SOAP API via client.getWaybillsV1, formats waybills into a human-readable list, handles empty results and errors.
  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:15-25 (schema)

  Zod input validation schema used in the handler to parse and validate tool arguments.
  export const GetWaybillsInputSchema = z.object({ start_date: z.string() .regex(/^\d{4}-\d{2}-\d{2}$/, 'Date must be in YYYY-MM-DD format') .describe('Start date in YYYY-MM-DD format (e.g., "2025-10-17")'), end_date: z.string() .regex(/^\d{4}-\d{2}-\d{2}$/, 'Date must be in YYYY-MM-DD format') .describe('End date in YYYY-MM-DD format (e.g., "2025-10-20")'), buyer_tin: z.string() .optional() .describe('Optional: Filter by buyer TIN (tax identification number)'), });
• src/tools/get-waybills.ts:32-57 (registration)

  MCP tool definition object including name, description, and JSON schema for input validation, exported for use in server registration.
  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:116-117 (registration)

  Registration of the getWaybillsTool in the MCP server's listTools handler, conditional on feature flag.
  if (features.getWaybills) { tools.push(getWaybillsTool);
• src/index.ts:149-153 (registration)

  Dispatch logic in the MCP callTool handler that checks feature flag and invokes the executeGetWaybills handler.
  case 'get_waybills': if (!features.getWaybills) { throw new Error('get_waybills tool is disabled'); } result = await executeGetWaybills(soapClient, args);