timestamp_to_date

Convert Unix timestamps (seconds or milliseconds) to human-readable ISO 8601 date strings with timezone support.

Instructions

Convert a Unix timestamp (seconds or milliseconds) to a human-readable ISO 8601 date string.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`timestamp`	Yes	Unix timestamp (seconds or milliseconds)
`timezone`	No	IANA timezone (e.g., 'America/New_York', 'Europe/London', default: UTC)	UTC

Implementation Reference

src/tools/converters.ts:16-56 (handler)

The asynchronous handler function that processes the Unix timestamp input, performs the conversion, and formats the output.

async ({ timestamp, timezone }) => {
  try {
    // Auto-detect seconds vs milliseconds
    const ms = timestamp > 1e12 ? timestamp : timestamp * 1000;
    const date = new Date(ms);

    if (isNaN(date.getTime())) {
      return {
        content: [
          { type: "text" as const, text: "Error: Invalid timestamp" },
        ],
        isError: true,
      };
    }

    const result = {
      iso: date.toISOString(),
      utc: date.toUTCString(),
      local: date.toLocaleString("en-US", { timeZone: timezone }),
      timezone,
      unix_seconds: Math.floor(ms / 1000),
      unix_milliseconds: ms,
    };

    return {
      content: [
        { type: "text" as const, text: JSON.stringify(result, null, 2) },
      ],
    };
  } catch (e) {
    return {
      content: [
        {
          type: "text" as const,
          text: `Error: ${e instanceof Error ? e.message : String(e)}`,
        },
      ],
      isError: true,
    };
  }
}

src/tools/converters.ts:9-15 (schema)

Zod schema defining the input parameters for the 'timestamp_to_date' tool.

{
  timestamp: z.number().describe("Unix timestamp (seconds or milliseconds)"),
  timezone: z
    .string()
    .default("UTC")
    .describe("IANA timezone (e.g., 'America/New_York', 'Europe/London', default: UTC)"),
},

src/tools/converters.ts:6-15 (registration)

The registration of the 'timestamp_to_date' tool within the MCP server using server.tool.

server.tool(
  "timestamp_to_date",
  "Convert a Unix timestamp (seconds or milliseconds) to a human-readable ISO 8601 date string.",
  {
    timestamp: z.number().describe("Unix timestamp (seconds or milliseconds)"),
    timezone: z
      .string()
      .default("UTC")
      .describe("IANA timezone (e.g., 'America/New_York', 'Europe/London', default: UTC)"),
  },

devutils-mcp-server