NS Travel Information Server

Instructions

Implementation Reference

• src/services/NSApiService.ts:79-93 (handler)

  Core handler function that executes the tool logic by making an authenticated HTTP request to the NS API departures endpoint with the provided station, dateTime, maxJourneys, and lang parameters.
  async getDepartures(args: GetDeparturesArgs): Promise<DeparturesResponse> { this.ensureApiKeyConfigured(); const response = await this.axiosInstance.get<DeparturesResponse>( NSApiService.ENDPOINTS.DEPARTURES, { params: { station: args.station, dateTime: args.dateTime, maxJourneys: args.maxJourneys, lang: args.lang }, } ); return response.data; }
• src/types.ts:326-359 (schema)

  TypeScript interface defining input arguments for get_departures and type guard function for input validation.
  export interface GetDeparturesArgs { station: string; dateTime?: string; maxJourneys?: number; lang?: string; } export function isValidDeparturesArgs(args: unknown): args is GetDeparturesArgs { if (!args || typeof args !== "object") { return false; } const typedArgs = args as Record<string, unknown>; // Required station field if (typeof typedArgs.station !== "string") { return false; } // Optional fields if (typedArgs.dateTime !== undefined && typeof typedArgs.dateTime !== "string") { return false; } if (typedArgs.maxJourneys !== undefined && typeof typedArgs.maxJourneys !== "number") { return false; } if (typedArgs.lang !== undefined && typeof typedArgs.lang !== "string") { return false; } return true; }
• src/index.ts:97-133 (registration)

  MCP tool registration including name, description, and input schema definition in the stdio server's ListToolsRequest handler.
  { name: 'get_departures', description: 'Get real-time departure information for trains from a specific station, including platform numbers, delays, route details, and any relevant travel notes. Returns a list of upcoming departures with timing, destination, 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 departures at foreign stations. Defaults to server time (Europe/Amsterdam)', }, maxJourneys: { type: 'number', description: 'Number of departures to return', minimum: 1, maximum: 100, default: 40 }, lang: { type: 'string', description: 'Language for localizing the departures 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:309-318 (handler)

  Dispatch handler in stdio server's CallToolRequest that validates arguments and delegates to NSApiService.getDepartures.
  case 'get_departures': { if (!isValidDeparturesArgs(rawArgs)) { throw ResponseFormatter.createMcpError( ErrorCode.InvalidParams, 'Invalid arguments for get_departures' ); } const data = await this.nsApiService.getDepartures(rawArgs); return ResponseFormatter.formatSuccess(data); }
• src/types.ts:319-324 (schema)

  TypeScript interface defining the expected output structure from the NS API departures endpoint.
  export interface DeparturesResponse { payload: { source: string; departures: Departure[]; }; }