NS Travel Information Server

Instructions

Implementation Reference

• src/services/NSApiService.ts:123-138 (handler)

  Core handler function in NSApiService that executes the logic to fetch real-time train arrivals from the NS API endpoint using axios, with input validation via ensureApiKeyConfigured.
  async getArrivals(args: GetArrivalsArgs): Promise<ArrivalsResponse> { this.ensureApiKeyConfigured(); const response = await this.axiosInstance.get<ArrivalsResponse>( NSApiService.ENDPOINTS.ARRIVALS, { params: { station: args.station, uicCode: args.uicCode, dateTime: args.dateTime, maxJourneys: args.maxJourneys, lang: args.lang }, } ); return response.data; }
• src/types.ts:513-565 (schema)

  TypeScript interface defining input args for get_arrivals tool and type guard function for input validation.
  export interface GetArrivalsArgs { station?: string; uicCode?: string; dateTime?: string; maxJourneys?: number; lang?: string; } export function isValidArrivalsArgs(args: unknown): args is GetArrivalsArgs { if (!args || typeof args !== "object") { return false; } const typedArgs = args as Record<string, unknown>; // Either station or uicCode must be provided if (!typedArgs.station && !typedArgs.uicCode) { return false; } // Check station: should be undefined or string if (typedArgs.station !== undefined && typeof typedArgs.station !== "string") { return false; } // Check uicCode: should be undefined or string if (typedArgs.uicCode !== undefined && typeof typedArgs.uicCode !== "string") { return false; } // Check dateTime: should be undefined or string if (typedArgs.dateTime !== undefined && typeof typedArgs.dateTime !== "string") { return false; } // Check maxJourneys: should be undefined or number between 1 and 100 if (typedArgs.maxJourneys !== undefined) { if (typeof typedArgs.maxJourneys !== "number" || typedArgs.maxJourneys < 1 || typedArgs.maxJourneys > 100) { return false; } } // Check lang: should be undefined or 'nl' or 'en' if (typedArgs.lang !== undefined) { if (typeof typedArgs.lang !== "string" || !["nl", "en"].includes(typedArgs.lang)) { return false; } } return true; }
• src/index.ts:184-219 (registration)

  Tool registration in the stdio MCP server (index.ts), including name, description, and JSON schema for input validation.
  name: 'get_arrivals', description: 'Get real-time arrival information for trains at a specific station, including platform numbers, delays, origin stations, and any relevant travel notes. Returns a list of upcoming arrivals with timing, origin, and status information.', inputSchema: { type: 'object', properties: { station: { type: 'string', description: 'NS Station code for the station (e.g., ASD for Amsterdam Centraal). Required if uicCode is not provided', }, uicCode: { type: 'string', description: 'UIC code for the station. Required if station code is not provided', }, dateTime: { type: 'string', description: 'Format - date-time (as date-time in RFC3339). Only supported for arrivals at foreign stations. Defaults to server time (Europe/Amsterdam)', }, maxJourneys: { type: 'number', description: 'Number of arrivals to return', minimum: 1, maximum: 100, default: 40 }, lang: { type: 'string', description: 'Language for localizing the arrivals list. Only a small subset of text is translated, mainly notes. Defaults to Dutch', enum: ['nl', 'en'], default: 'nl' } }, oneOf: [ { required: ['station'] }, { required: ['uicCode'] } ] }
• src/index.ts:350-359 (registration)

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