get_arrivals

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