Servidor MCP datetime

Un servidor Model Context Protocol que proporciona consultas de fecha/hora actual, escrito en TypeScript y diseñado para desplegarse en AWS Lambda, sirviendo a través de HTTP Streamable.

Características

• Dos herramientas MCP: get_date, get_datetime, con salida en formato ISO 8601

• Parámetro de zona horaria opcional: admite nombres de zona horaria IANA (Asia/Shanghai) y desplazamientos UTC (+08:00), por defecto UTC

• Cero librerías de tiempo de terceros: completamente basado en el Intl integrado de Node.js (ICU), sin dependencias de moment/luxon/dayjs

• Despliegue serverless: bundle de un solo archivo (~2 MB) + Lambda Web Adapter, con respuesta en milisegundos en instancias calientes tras el arranque en frío

• Cumple con el estándar MCP más reciente: transporte HTTP Streamable, modo de ejecución stateless, negociación de versión de protocolo gestionada por el SDK oficial

Related MCP server: date-today-mcp

Arquitectura

MCP Client ──HTTP POST /mcp──▶ Function URL ──▶ Lambda 函数
                                                │
                                                ├─ LWA Layer (AWS_LAMBDA_EXEC_WRAPPER=/opt/bootstrap)
                                                │    └─ 执行 zip 根目录 bootstrap → node dist/index.js
                                                │
                                                └─ Express app (端口 8080)
                                                     └─ POST /mcp → StreamableHTTPServerTransport
                                                          （stateless：每请求新建 transport，
                                                            enableJsonResponse 返回普通 JSON）

Mecanismos clave:

Herramientas MCP

get_date

Devuelve la fecha de calendario actual, ISO 8601 YYYY-MM-DD.

{"result":{"content":[{"type":"text","text":"2026-08-24"}]}}

get_datetime

Devuelve la fecha y hora actuales, ISO 8601 con sufijo de desplazamiento (la salida UTC usa Z).

{"result":{"content":[{"type":"text","text":"2026-08-23T14:30:00+08:00"}]}}

Comportamiento de errores

• Zona horaria ausente o cadena vacía → se trata como UTC

• Zona horaria no vacía pero inválida → devuelve un resultado con isError: true, con mensaje informativo:

Error: Invalid IANA timezone "Mars/Olympus". Use a name like "UTC", "Asia/Shanghai" or "America/New_York".

• Errores a nivel de protocolo (como falta de cabecera Accept) los devuelve el SDK como error JSON-RPC estándar

Fuente de tiempo y precisión

La hora se lee del reloj del sistema del entorno de ejecución (new Date()). En local es el reloj de la máquina (depende de la calibración NTP); en Lambda, el reloj del host se sincroniza automáticamente mediante Amazon Time Sync Service (fuente GPS/reloj atómico, PTP/NTP), con error inferior al milisegundo, sin necesidad de configuración.

Deliberadamente no se consulta NTP externo en cada petición: el reloj de AWS ya está sincronizado continuamente, y una consulta externa solo añadiría latencia (+10~100 ms), introduciría superficie de fallo de red y problemas de limitación, sin mayor precisión.

La resolución de salida es de segundos (los milisegundos se truncan). La conversión de zona horaria es aritmética pura: todas las zonas horarias obtienen el mismo instante absoluto, solo difiere la representación de la hora de pared.

Desarrollo local

Requiere Node.js ≥ 22.

npm install        # 安装依赖
npm run dev        # 构建 + 启动（默认 http://localhost:3000/mcp）
npm test           # vitest 单测（14 个用例）
npm run typecheck  # tsc --noEmit
npm run lint       # eslint
npm run build      # esbuild 打包为 CJS 单文件 dist/index.js

Prueba manual local (la cabecera Accept debe declarar ambos tipos de medio, es la validación de protocolo del SDK):

curl -s http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_datetime","arguments":{"timezone":"Asia/Shanghai"}}}'

También se puede usar el depurador oficial: npx @modelcontextprotocol/inspector, tipo de conexión HTTP Streamable.

Nota: si la máquina local tiene la variable de entorno http_proxy configurada, curl necesita --noproxy '*', de lo contrario las peticiones a localhost serán interceptadas por el proxy y devolverán 502.

Estructura del proyecto

├── src/
│   ├── time.ts      # 核心纯函数：ISO 格式化、时区校验（可独立单测）
│   ├── server.ts    # McpServer 实例 + 工具注册
│   └── index.ts     # Express app + stateless transport 挂载 + 进程入口
├── test/
│   └── time.test.ts # 固定时间戳验证多时区/DST/半小时偏移/错误输入
├── build.mjs        # esbuild 构建脚本（bundle: platform=node22, format=cjs）
├── bootstrap        # LWA 进入口（zip 根目录，需可执行位 755）
├── deploy.sh        # CLI 一键部署脚本
├── function.zip     # 部署包（构建产物，不入库）
└── dist/index.js    # 打包产物（约 2MB，零运行时依赖安装）

Puntos clave de implementación técnica

El formateo de zonas horarias se realiza íntegramente con Intl.DateTimeFormat, con técnicas clave:

1. Fecha: el locale en-CA produce naturalmente YYYY-MM-DD, sin ensamblaje manual

2. Hora con desplazamiento: formatToParts obtiene los campos de hora de pared de la zona horaria objetivo → se usa Date.UTC() para recalcular como si fuera UTC → se resta del instante original para obtener el offset en minutos → se formatea como ±HH:MM o Z

3. hourCycle: "h23": evita el bug de borde de la hora "24" que produce hour12: false en algunos locales

4. DST y zonas horarias especiales: el offset se calcula en el momento de la petición, el cambio de horario de verano es naturalmente correcto (Nueva York -04:00→-05:00); zonas horarias de media hora/cuarto de hora (India +05:30, Nepal +05:45, Chatham +12:45) están cubiertas por pruebas unitarias

5. Caché de formateadores: se cachean las instancias de Intl.DateTimeFormat por zona horaria, cero coste de construcción en llamadas repetidas en instancias calientes

6. Validación de zona horaria: try/catch al construir Intl.DateTimeFormat; si lanza RangeError se considera inválida. El nuevo ECMA-402 hace que ICU acepte también cadenas de desplazamiento UTC (como +08:00), verificado que toda la cadena produce salida correcta e incluido en las pruebas

Despliegue en AWS Lambda

Requisitos previos: credenciales configuradas en AWS CLI; un rol de ejecución con permisos AWSLambdaBasicExecutionRole (si no existe, se puede crear con el siguiente comando):

aws iam create-role --role-name datetime-mcp-role \
  --assume-role-policy-document '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":{"Service":"lambda.amazonaws.com"},"Action":"sts:AssumeRole"}]}'

aws iam attach-role-policy --role-name datetime-mcp-role \
  --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole

Opción 1: Script CLI

ROLE_ARN=arn:aws:iam::<账号ID>:role/datetime-mcp-role ./deploy.sh

Variables de entorno opcionales: AWS_REGION (por defecto us-east-1), FUNCTION_NAME (por defecto datetime-mcp), ARCH (arm64/x86_64, por defecto arm64).

Flujo del script: consulta dinámicamente la versión más reciente del Layer LWA de la región → build con esbuild → empaquetado con bsdtar (el sistema no tiene comando zip) → create/update de la función (nodejs22.x, 512 MB, timeout 10 s) → creación de Function URL sin autenticación y autorización de invocación pública → salida del endpoint. La ejecución repetida es segura, toma automáticamente la ruta de actualización.

Opción 2: Consola de AWS

1. Empaquetado local:

   npm run build && bsdtar --format zip -cf function.zip bootstrap dist/index.js

2. Consola de Lambda → Create function → Author from scratch

   • Runtime: Node.js 22.x; Architecture: arm64

   • Permissions: Create a new role with basic Lambda permissions

3. Pestaña Code → Upload from → .zip file → seleccionar function.zip (la estructura interna debe ser bootstrap en la raíz + dist/index.js)

4. Sección Layers → Add a layer → AWS layers → LambdaAdapterLayerArm64 (seleccionar la versión más reciente)

5. Configuration → Environment variables:

   Key	Value
   AWS_LAMBDA_EXEC_WRAPPER	/opt/bootstrap
   PORT	8080

6. Configuration → General configuration → Memory 512 MB、Timeout 10 s

7. Configuration → Function URL → Create → Auth type NONE

Al crear un Function URL de tipo NONE desde la consola se añade automáticamente la política de recursos para invocación pública, no es necesario ejecutar add-permission (esta es la diferencia con el CLI).

Acceder directamente al Function URL desde el navegador devolviendo 405 es normal (solo se permite POST). Para actualizar el código en el futuro: reconstruir y reempaquetar, y volver a subir en la pestaña Code.

Integración con clientes MCP

Con opencode como ejemplo, añadir el servidor MCP remoto en la configuración:

{
  "mcp": {
    "datetime": {
      "type": "remote",
      "url": "https://<identifier>.lambda-url.<region>.on.aws/mcp"
    }
  }
}

Registro de decisiones de diseño

Resolución de problemas

Limitaciones conocidas y mejoras futuras

• Handler defensivo no añadido: si se ejecuta directamente en el runtime Node.js por defecto (sin LWA), el mensaje de error es confuso. Se podría exportar un handler de marcador de posición informativo para mejorar la experiencia de error en configuración incorrecta, con impacto cero en la ruta normal

• La salida solo tiene precisión de segundos, no expone milisegundos

• Sin autenticación ni limitación de tasa: un endpoint público podría ser abusado para inflar el número de llamadas (aunque el coste por llamada tiende a cero)

• La tabla de alias de Intl.supportedValuesOf("timeZone") no se usa para sugerencias de parámetros, el mensaje de error solo da tres ejemplos

• Cuando el SDK migre de la versión estable 1.x a los paquetes divididos (soporte de la revisión de 2026-07-28), habrá que seguir los cambios de API

Licencia

ISC