NS Travel Information Server

Instructions

Implementation Reference

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

  Core handler function that executes the get_departures tool logic by calling the NS API departures endpoint with provided arguments.

  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)

  Type definition and validation function for GetDeparturesArgs input schema.

  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)

  Tool registration in MCP stdio server including name, description, and input schema.

  {
    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 (registration)

  Dispatch handler in MCP stdio server that validates args and calls the core getDepartures function.

  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/http-server.ts:437-446 (registration)

  Dispatch handler in MCP HTTP server that validates args and calls the core getDepartures function.

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