NS Travel Information Server

Instructions

Implementation Reference

• src/services/NSApiService.ts:140-160 (handler)

  Core handler function that performs the HTTP request to the NS API to retrieve price information based on the input arguments.
  async getPrices(args: GetPricesArgs): Promise<PricesResponse> { this.ensureApiKeyConfigured(); const response = await this.axiosInstance.get<PricesResponse>( NSApiService.ENDPOINTS.PRICES, { params: { fromStation: args.fromStation, toStation: args.toStation, travelClass: args.travelClass, travelType: args.travelType, isJointJourney: args.isJointJourney, adults: args.adults, children: args.children, routeId: args.routeId, plannedDepartureTime: args.plannedDepartureTime, plannedArrivalTime: args.plannedArrivalTime }, } ); return response.data; }
• src/types.ts:588-665 (schema)

  Input schema (GetPricesArgs), output type (PricesResponse), and validation function for the get_prices tool.
  export interface PricesResponse { payload: { prices: Price[]; }; } export interface GetPricesArgs { fromStation?: string; toStation?: string; travelClass?: 'FIRST_CLASS' | 'SECOND_CLASS'; travelType?: 'single' | 'return'; isJointJourney?: boolean; adults?: number; children?: number; routeId?: string; plannedDepartureTime?: string; plannedArrivalTime?: string; } export function isValidPricesArgs(args: unknown): args is GetPricesArgs { if (!args || typeof args !== "object") { return false; } const typedArgs = args as Record<string, unknown>; // Check station fields: should be undefined or string if (typedArgs.fromStation !== undefined && typeof typedArgs.fromStation !== "string") { return false; } if (typedArgs.toStation !== undefined && typeof typedArgs.toStation !== "string") { return false; } // Check travelClass: should be undefined or one of the allowed values if (typedArgs.travelClass !== undefined && !["FIRST_CLASS", "SECOND_CLASS"].includes(typedArgs.travelClass as string)) { return false; } // Check travelType: should be undefined or one of the allowed values if (typedArgs.travelType !== undefined && !["single", "return"].includes(typedArgs.travelType as string)) { return false; } // Check isJointJourney: should be undefined or boolean if (typedArgs.isJointJourney !== undefined && typeof typedArgs.isJointJourney !== "boolean") { return false; } // Check adults: should be undefined or integer if (typedArgs.adults !== undefined && (typeof typedArgs.adults !== "number" || !Number.isInteger(typedArgs.adults))) { return false; } // Check children: should be undefined or integer if (typedArgs.children !== undefined && (typeof typedArgs.children !== "number" || !Number.isInteger(typedArgs.children))) { return false; } // Check routeId: should be undefined or string if (typedArgs.routeId !== undefined && typeof typedArgs.routeId !== "string") { return false; } // Check time fields: should be undefined or string if (typedArgs.plannedDepartureTime !== undefined && typeof typedArgs.plannedDepartureTime !== "string") { return false; } if (typedArgs.plannedArrivalTime !== undefined && typeof typedArgs.plannedArrivalTime !== "string") { return false; } return true; }
• src/index.ts:222-278 (registration)

  Tool registration in the stdio MCP server (index.ts), including name, description, and input schema.
  name: 'get_prices', description: 'Get price information for domestic train journeys, including different travel classes, ticket types, and discounts. Returns detailed pricing information with conditions and validity.', inputSchema: { type: 'object', properties: { fromStation: { type: 'string', description: 'UicCode or station code of the origin station', }, toStation: { type: 'string', description: 'UicCode or station code of the destination station', }, travelClass: { type: 'string', description: 'Travel class to return the price for', enum: ['FIRST_CLASS', 'SECOND_CLASS'] }, travelType: { type: 'string', description: 'Return the price for a single or return trip', enum: ['single', 'return'], default: 'single' }, isJointJourney: { type: 'boolean', description: 'Set to true to return the price including joint journey discount', default: false }, adults: { type: 'integer', description: 'Number of adults to return the price for', minimum: 1, default: 1 }, children: { type: 'integer', description: 'Number of children to return the price for', minimum: 0, default: 0 }, routeId: { type: 'string', description: 'Specific identifier for the route to take between the two stations. This routeId is returned in the /api/v3/trips call.' }, plannedDepartureTime: { type: 'string', description: 'Format - date-time (as date-time in RFC3339). Used to find the correct route if multiple routes are possible.' }, plannedArrivalTime: { type: 'string', description: 'Format - date-time (as date-time in RFC3339). Used to find the correct route if multiple routes are possible.' } }, required: ['fromStation', 'toStation'] } },
• src/http-server.ts:350-406 (registration)

  Tool registration in the HTTP MCP server (http-server.ts), including name, description, and input schema.
  name: 'get_prices', description: 'Get price information for domestic train journeys, including different travel classes, ticket types, and discounts. Returns detailed pricing information with conditions and validity.', inputSchema: { type: 'object', properties: { fromStation: { type: 'string', description: 'UicCode or station code of the origin station', }, toStation: { type: 'string', description: 'UicCode or station code of the destination station', }, travelClass: { type: 'string', description: 'Travel class to return the price for', enum: ['FIRST_CLASS', 'SECOND_CLASS'] }, travelType: { type: 'string', description: 'Return the price for a single or return trip', enum: ['single', 'return'], default: 'single' }, isJointJourney: { type: 'boolean', description: 'Set to true to return the price including joint journey discount', default: false }, adults: { type: 'integer', description: 'Number of adults to return the price for', minimum: 1, default: 1 }, children: { type: 'integer', description: 'Number of children to return the price for', minimum: 0, default: 0 }, routeId: { type: 'string', description: 'Specific identifier for the route to take between the two stations. This routeId is returned in the /api/v3/trips call.' }, plannedDepartureTime: { type: 'string', description: 'Format - date-time (as date-time in RFC3339). Used to find the correct route if multiple routes are possible.' }, plannedArrivalTime: { type: 'string', description: 'Format - date-time (as date-time in RFC3339). Used to find the correct route if multiple routes are possible.' } }, required: ['fromStation', 'toStation'] } },
• src/index.ts:361-370 (handler)

  Dispatch handler in stdio server that validates args and delegates to NSApiService.getPrices.
  case 'get_prices': { if (!isValidPricesArgs(rawArgs)) { throw ResponseFormatter.createMcpError( ErrorCode.InvalidParams, 'Invalid arguments for get_prices' ); } const data = await this.nsApiService.getPrices(rawArgs); return ResponseFormatter.formatSuccess(data); }