DateTime MCP Server

Instructions

Implementation Reference

• src/index.ts:126-188 (handler)

  The core handler logic for executing the 'get_current_datetime' tool. Validates timezone input, determines timezone to use, formats current date/time appropriately (ISO for UTC, date-fns-tz for others), and returns formatted text response in MCP content format.

  case "get_current_datetime": {
    try {
      const args = request.params.arguments as DateTimeToolArgs | undefined;
      const requestedTimezone = args?.timezone;
      
      // Determine which timezone to use
      let timezone: string;
      
      if (requestedTimezone) {
        // User provided a timezone parameter - validate it
        if (!isValidTimezone(requestedTimezone)) {
          throw new McpError(
            ErrorCode.InvalidParams,
            `Invalid timezone: ${requestedTimezone}. Please use a valid IANA timezone identifier (e.g., 'America/New_York', 'Europe/London', 'Asia/Tokyo').`
          );
        }
        timezone = requestedTimezone;
      } else {
        // Use default timezone from server config or fallback
        timezone = getDefaultTimezone(serverConfig);
      }
      
      const now = new Date();
      
      // Format the datetime in the specified timezone
      let dateTimeString: string;
      let timezoneInfo: string;
      
      if (timezone === 'UTC') {
        // For UTC, use the standard ISO format
        dateTimeString = now.toISOString();
        timezoneInfo = 'UTC';
      } else {
        // For other timezones, use date-fns-tz to format in the timezone
        // Format as ISO-like string but with timezone offset
        const formatPattern = "yyyy-MM-dd'T'HH:mm:ss.SSSxxx";
        dateTimeString = formatInTimeZone(now, timezone, formatPattern);
        timezoneInfo = timezone;
      }
      
      // Create a user-friendly response
      const responseText = requestedTimezone 
        ? `The current date and time in ${timezoneInfo} is: ${dateTimeString}`
        : `The current date and time is: ${dateTimeString} (${timezoneInfo})`;
      
      return {
        content: [{
          type: "text",
          text: responseText
        }]
      };
    } catch (error) {
      // Re-throw McpErrors as-is
      if (error instanceof McpError) {
        throw error;
      }
      // Wrap other errors in an McpError
      throw new McpError(
        ErrorCode.InternalError,
        `Failed to get current datetime: ${error instanceof Error ? error.message : 'Unknown error'}`
      );
    }
  }

• src/index.ts:106-114 (schema)

  The JSON schema defining the input parameters for the 'get_current_datetime' tool: an optional 'timezone' string.

  inputSchema: {
    type: "object",
    properties: {
      timezone: {
        type: "string",
        description: "Optional timezone identifier (e.g., 'America/New_York', 'Europe/London', 'Asia/Tokyo'). If not provided, uses the server's default timezone or UTC."
      }
    },
  }

• src/index.ts:103-116 (registration)

  The tool definition object registered in the listTools handler, including name, description, and input schema.

    {
      name: "get_current_datetime",
      description: "Get the current server date and time. Optionally specify a timezone (e.g., 'America/New_York', 'Europe/London', 'Asia/Tokyo'). Defaults to server's configured timezone or UTC.",
      inputSchema: {
        type: "object",
        properties: {
          timezone: {
            type: "string",
            description: "Optional timezone identifier (e.g., 'America/New_York', 'Europe/London', 'Asia/Tokyo'). If not provided, uses the server's default timezone or UTC."
          }
        },
      }
    }
  ]

• src/index.ts:36-52 (helper)

  Helper function used by the handler to validate if a provided timezone identifier is supported.

  function isValidTimezone(timezone: string): boolean {
    try {
      // Use Intl.supportedValuesOf to get all supported timezones
      // This is more robust than try/catch with toLocaleString
      if (typeof Intl !== 'undefined' && 'supportedValuesOf' in Intl) {
        const supportedTimezones = Intl.supportedValuesOf('timeZone');
        return supportedTimezones.includes(timezone);
      }
      
      // Fallback: Try to create a date and format it in the timezone
      // If it throws, the timezone is invalid
      new Intl.DateTimeFormat('en', { timeZone: timezone }).format(new Date());
      return true;
    } catch {
      return false;
    }
  }

• src/index.ts:59-70 (helper)

  Helper function to determine the default timezone, prioritizing server config, then TZ env var, then UTC.

  function getDefaultTimezone(config?: ServerConfig): string {
    // Priority: config.defaultTimezone > process.env.TZ > 'UTC'
    if (config?.defaultTimezone && isValidTimezone(config.defaultTimezone)) {
      return config.defaultTimezone;
    }
    
    if (process.env.TZ && isValidTimezone(process.env.TZ)) {
      return process.env.TZ;
    }
    
    return 'UTC';
  }