MCP Time Server Node

Instructions

Implementation Reference

• src/tools/getCurrentTime.ts:71-106 (handler)

  The primary handler function that implements the core logic for the 'get_current_time' tool: validates input, resolves timezone, applies caching, formats current time, handles errors, and constructs the result object.

  export function getCurrentTime(params: GetCurrentTimeParams): GetCurrentTimeResult {
    debug.timezone('getCurrentTime called with params: %O', params);
  
    // Validate format string length first
    if (params.format) {
      validateStringLength(params.format, LIMITS.MAX_FORMAT_LENGTH, 'format');
    }
  
    // Resolve timezone with proper empty string handling
    const config = getConfig();
    const timezone = resolveTimezone(params.timezone, config.defaultTimezone);
    const formatStr = params.format ?? "yyyy-MM-dd'T'HH:mm:ss.SSSXXX";
    const includeOffset = params.include_offset !== false;
  
    // Use withCache wrapper instead of manual cache management
    return withCache(getCacheKey(timezone, formatStr, includeOffset), CacheTTL.CURRENT_TIME, () => {
      // Validate timezone
      if (!validateTimezone(timezone)) {
        throw new TimezoneError(`Invalid timezone: ${timezone}`, timezone);
      }
  
      const now = new Date();
  
      try {
        // Format time with appropriate options
        const formattedTime = formatTimeWithOptions(now, timezone, params, formatStr);
  
        // Build result
        const result = buildTimeResult(now, formattedTime, timezone);
  
        return result;
      } catch (error: unknown) {
        handleFormatError(error, params.format ?? formatStr);
      }
    });
  }

• src/types/index.ts:29-41 (schema)

  TypeScript interfaces defining the input parameters (GetCurrentTimeParams) and output structure (GetCurrentTimeResult) for the get_current_time tool.

  export interface GetCurrentTimeParams {
    timezone?: string;
    format?: string;
    include_offset?: boolean;
  }
  
  export interface GetCurrentTimeResult {
    time: string;
    timezone: string;
    offset: string;
    unix: number;
    iso: string;
  }

• src/index.ts:42-58 (registration)

  Tool registration in TOOL_DEFINITIONS: defines the MCP tool name 'get_current_time', description, and JSON schema for input validation.

    name: 'get_current_time',
    description: 'Get current time in specified timezone with formatting options',
    inputSchema: {
      type: 'object' as const,
      properties: {
        timezone: {
          type: 'string' as const,
          description: 'IANA timezone (default: system timezone)',
        },
        format: { type: 'string' as const, description: 'date-fns format string' },
        include_offset: {
          type: 'boolean' as const,
          description: 'Include UTC offset (default: true)',
        },
      },
    },
  },

• src/index.ts:258-259 (registration)

  Tool function mapping in TOOL_FUNCTIONS: associates the 'get_current_time' tool name with the getCurrentTime handler implementation.

  get_current_time: (params: unknown) =>
    getCurrentTime(params as Parameters<typeof getCurrentTime>[0]),

• src/tools/getCurrentTime.ts:44-59 (helper)

  Helper function buildTimeResult constructs the standardized output object for the tool result, including formatted time, offset, Unix timestamp, and ISO string.

  export function buildTimeResult(
    now: Date,
    formattedTime: string,
    timezone: string
  ): GetCurrentTimeResult {
    // Get offset separately for the result object
    const offset = timezone === 'UTC' ? 'Z' : formatInTimeZone(now, timezone, 'XXX');
  
    return {
      time: formattedTime,
      timezone: timezone,
      offset: offset,
      unix: Math.floor(now.getTime() / 1000),
      iso: formatInTimeZone(now, timezone, "yyyy-MM-dd'T'HH:mm:ss.SSSXXX"),
    };
  }