temporal-cortex-datetime

Convert timezones, resolve natural language times ("next Tuesday at 2pm"), compute durations, and adjust timestamps with DST awareness. No credentials needed...

installs

stars

karma

SkillRank score ↗

8.3/ 10

evaluated by implexa, claude-haiku-4-5 · 2026-07-19

temporal-cortex-datetime provides five offline datetime tools for timezone conversion, natural language time parsing (60+ patterns), duration computation, and dst-aware timestamp adjustment. runs locally after one-time binary install, no credentials or network access required at runtime.

structure

9.0

trigger phrases

8.0

procedure

9.0

edge cases

7.0

documentation

8.0

view original SKILL.md from clawhubclick to expand

---
name: temporal-cortex-datetime
description: |-
  Convert timezones, resolve natural language times ("next Tuesday at 2pm"), compute durations, and adjust timestamps with DST awareness. No credentials needed — all tools run fully offline after one-time binary install.
license: MIT
compatibility: |-
  Requires npx (Node.js 18+) or Docker to install the MCP server binary (one-time). After installation, all 5 tools run fully offline with zero network access. No OAuth or credentials needed. Works with Claude Code, Claude Desktop, Cursor, Windsurf, and any MCP-compatible client.
metadata:
  author: temporal-cortex
  version: "0.9.1"
  mcp-server: "@temporal-cortex/cortex-mcp"
  homepage: "https://temporal-cortex.com"
  repository: "https://github.com/temporal-cortex/skills"
  openclaw:
    install:
      - kind: node
        package: "@temporal-cortex/cortex-mcp@0.9.1"
        bins: [cortex-mcp]
    requires:
      bins:
        - npx
      config:
        - ~/.config/temporal-cortex/config.json
---

# Temporal Context & Datetime Resolution

5 tools for temporal orientation and datetime computation. All tools execute locally within the compiled MCP server binary — no external API calls, no network access at runtime, no credential files. The binary is installed once via npm (or built from source with Docker) and all subsequent executions are fully offline. No OAuth or credentials required. Timezone and week-start preferences are stored in `config.json`. Unset fields default to system timezone and Monday week-start.

## Source & Provenance

- **Homepage:** [temporal-cortex.com](https://temporal-cortex.com)
- **Source code:** [github.com/temporal-cortex/mcp](https://github.com/temporal-cortex/mcp) (open-source Rust)
- **npm package:** [@temporal-cortex/cortex-mcp](https://www.npmjs.com/package/@temporal-cortex/cortex-mcp)
- **Skills repo:** [github.com/temporal-cortex/skills](https://github.com/temporal-cortex/skills)

## Tools

| Tool | When to Use |
|------|------------|
| `get_temporal_context` | First call in any session. Returns current time, timezone, UTC offset, DST status, DST prediction, day of week. |
| `resolve_datetime` | Convert human expressions to RFC 3339. Supports 60+ patterns: `"next Tuesday at 2pm"`, `"tomorrow morning"`, `"+2h"`, `"start of next week"`, `"third Friday of March"`. |
| `convert_timezone` | Convert RFC 3339 datetime between IANA timezones. |
| `compute_duration` | Duration between two timestamps (days, hours, minutes). |
| `adjust_timestamp` | DST-aware timestamp adjustment. `"+1d"` across spring-forward = same wall-clock time. |

## Runtime

These tools run inside the [Temporal Cortex MCP server](https://github.com/temporal-cortex/mcp) (`@temporal-cortex/cortex-mcp`), a compiled Rust binary distributed as an npm package.

**Install and startup lifecycle:**
1. `npx` resolves `@temporal-cortex/cortex-mcp` from the npm registry (one-time, cached locally after first download)
2. The postinstall script downloads the platform-specific binary from the [GitHub Release](https://github.com/temporal-cortex/mcp/releases/tag/mcp-v0.9.1) and verifies its SHA256 checksum against the embedded `checksums.json` — **installation halts on mismatch**
3. The MCP server starts as a local process communicating over stdio (no listening ports)
4. All 5 datetime tools execute locally — zero network access, zero filesystem writes, no credentials

**Network access:** Only during the initial npm download. Once cached, subsequent launches are fully offline. The 5 datetime tools make zero network requests — all computation is local.

**File access:** The binary reads `~/.config/temporal-cortex/config.json` for timezone and week-start preferences. Unset or missing fields default to system values. No filesystem writes. No credential files accessed.

**No credentials required.** Unlike the scheduling skill, this skill needs no OAuth tokens or API keys.

**Pre-run verification** (recommended before first use):
1. Inspect the npm package without executing: `npm pack @temporal-cortex/cortex-mcp --dry-run`
2. Verify checksums independently against the [GitHub Release](https://github.com/temporal-cortex/mcp/releases/download/mcp-v0.9.1/SHA256SUMS.txt) (see verification pipeline below)
3. For full containment, run in Docker instead of npx (see Docker containment below)

**Verification pipeline:** Checksums are published independently at each [GitHub Release](https://github.com/temporal-cortex/mcp/releases/tag/mcp-v0.9.1) as `SHA256SUMS.txt` — verify the binary before first use:

```bash
# 1. Fetch checksums from GitHub (independent of the npm package)
curl -sL https://github.com/temporal-cortex/mcp/releases/download/mcp-v0.9.1/SHA256SUMS.txt

# 2. Compare against the npm-installed binary
shasum -a 256 "$(npm root -g)/@temporal-cortex/cortex-mcp/bin/cortex-mcp"
```

As defense-in-depth, the npm package also embeds `checksums.json` and the postinstall script compares SHA256 hashes during install — **installation halts on mismatch** (the binary is deleted, not executed). This automated check supplements, but does not replace, independent verification above.

**Build provenance:** Binaries are cross-compiled from auditable Rust source in [GitHub Actions](https://github.com/temporal-cortex/mcp/actions) across 5 platforms (darwin-arm64, darwin-x64, linux-x64, linux-arm64, win32-x64). Source: [github.com/temporal-cortex/mcp](https://github.com/temporal-cortex/mcp) (MIT-licensed). The CI workflow, build artifacts, and release checksums are all publicly inspectable.

**Docker containment** (recommended for maximum isolation — zero Node.js dependency, zero host filesystem access, zero network after build):

```json
{
  "mcpServers": {
    "temporal-cortex": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--network=none", "cortex-mcp"]
    }
  }
}
```

Build: `docker build -t cortex-mcp https://github.com/temporal-cortex/mcp.git` — No volume mount needed since the datetime skill requires no OAuth tokens or credential files. The `--network=none` flag enforces the zero-network guarantee at the OS level.

## Critical Rules

1. **Always call `get_temporal_context` before time-dependent work** — never assume the time or timezone.
2. **Resolve before querying** — convert `"next Tuesday at 2pm"` to RFC 3339 with `resolve_datetime` before passing to calendar tools.
3. **Timezone awareness** — all datetime tools produce RFC 3339 with timezone offsets.

## resolve_datetime Expression Patterns

The expression parser supports 60+ patterns across 10 categories:

| Category | Examples |
|----------|---------|
| Relative | `"now"`, `"today"`, `"tomorrow"`, `"yesterday"` |
| Named days | `"next Monday"`, `"this Friday"`, `"last Wednesday"` |
| Time of day | `"morning"` (09:00), `"noon"`, `"evening"` (18:00), `"eob"` (17:00) |
| Clock time | `"2pm"`, `"14:00"`, `"3:30pm"` |
| Offsets | `"+2h"`, `"-30m"`, `"in 2 hours"`, `"3 days ago"` |
| Compound | `"next Tuesday at 2pm"`, `"tomorrow morning"`, `"this Friday at noon"` |
| Period boundaries | `"start of week"`, `"end of month"`, `"start of next week"`, `"end of last month"` |
| Ordinal weekday | `"first Monday of March"`, `"third Friday of next month"` |
| RFC 3339 passthrough | `"2026-03-15T14:00:00-04:00"` (returned as-is) |
| Week start aware | Uses configured `WEEK_START` (Monday default, Sunday option) |

## Common Patterns

### Get Current Time Context

```
get_temporal_context()
→ utc, local, timezone, utc_offset, dst_active, dst_next_transition,
  day_of_week, iso_week, is_weekday, day_of_year, week_start
```

### Resolve a Meeting Time

```
resolve_datetime("next Tuesday at 2pm")
→ resolved_utc, resolved_local, timezone, interpretation
```

### Convert Across Timezones

```
1. get_temporal_context → user's timezone
2. convert_timezone(datetime: "2026-03-15T14:00:00-04:00", target_timezone: "Asia/Tokyo")
   → same moment in Tokyo time with DST and offset info
```

### Calculate Duration

```
compute_duration(start: "2026-03-15T09:00:00-04:00", end: "2026-03-15T17:30:00-04:00")
→ total_seconds: 30600, hours: 8, minutes: 30, human_readable: "8 hours 30 minutes"
```

### DST-Aware Adjustment

```
adjust_timestamp(
  datetime: "2026-03-07T23:00:00-05:00",
  adjustment: "+1d",
  timezone: "America/New_York"
) → same wall-clock time (23:00) on March 8, even though DST spring-forward occurs
```

## Additional References

- [Datetime Tools Reference](references/DATETIME-TOOLS.md) — Complete input/output schemas for all 5 tools

don't have the plugin yet? install it then click "run inline in claude" again.

restructured original skill into implexa's 6-part format (intent, inputs, procedure with explicit in/out for each step, decision points covering edge cases and dst ambiguity, output contract defining rfc 3339 formats and file locations, outcome signal for verification), added safety considerations (checksum verification, docker isolation, network-only-at-install), preserved all 5 tools and original procedures, kept voice punchy and lowercase throughout.

temporal-cortex-datetime

intent

convert between timezones, resolve natural language datetime expressions ("next Tuesday at 2pm"), compute durations between timestamps, and adjust times with daylight saving time awareness. use this skill when you need to work with time across zones, parse human-readable time strings, or handle dst edge cases (spring forward, fall back). all computation happens locally after a one-time binary install. zero network calls at runtime, zero credentials required.

inputs

installation:

node.js 18+ with npx, or docker (choose one)
npm package: @temporal-cortex/cortex-mcp@0.9.1
postinstall downloads platform-specific rust binary and verifies sha256 checksum

runtime config (optional):

file: ~/.config/temporal-cortex/config.json
fields: timezone (iana string, e.g. "America/New_York"), week_start ("monday" or "sunday")
unset fields default to system timezone and monday week-start

external connections:

none. the datetime tools run fully offline. network access only occurs during initial npm download (cached thereafter).

procedure

1. install the mcp server

input: shell access, node.js 18+ or docker
run one of:
- npx @temporal-cortex/cortex-mcp@0.9.1 (via npm), or
- docker build -t cortex-mcp https://github.com/temporal-cortex/mcp.git (via docker)
output: binary installed locally at ~/.npm/@temporal-cortex/cortex-mcp/bin/cortex-mcp (npx) or docker image cortex-mcp (docker)
postinstall script fetches binary and halts if sha256 checksum fails

2. verify binary integrity (recommended for first use)

input: installed binary, curl
fetch independent checksums: curl -sL https://github.com/temporal-cortex/mcp/releases/download/mcp-v0.9.1/SHA256SUMS.txt
compare against local binary: shasum -a 256 "$(npm root -g)/@temporal-cortex/cortex-mcp/bin/cortex-mcp"
output: checksum match confirmed (or halt if mismatch)

3. call get_temporal_context() as first step

input: none
output: object with keys: utc (rfc 3339), local (rfc 3339), timezone (iana string), utc_offset (string, e.g. "-04:00"), dst_active (boolean), dst_next_transition (rfc 3339 or null), day_of_week (string), iso_week (number), is_weekday (boolean), day_of_year (number), week_start (string)
establishes baseline time and user's timezone for all downstream calls

4. resolve natural language expressions with resolve_datetime()

input: expression string (60+ patterns supported: "next Tuesday at 2pm", "tomorrow morning", "+2h", "start of next week", "third Friday of March", rfc 3339 passthrough, etc.)
output: object with keys: resolved_utc (rfc 3339), resolved_local (rfc 3339), timezone (iana string), interpretation (string describing how expression was parsed)
converts human-readable time to structured rfc 3339 timestamp

5. convert between timezones with convert_timezone()

input: datetime (rfc 3339 string), target_timezone (iana string, e.g. "Asia/Tokyo")
output: object with keys: original_datetime (rfc 3339), converted_datetime (rfc 3339), original_timezone (iana string), target_timezone (iana string), utc_offset_original (string), utc_offset_target (string), dst_active_target (boolean)
same moment in time, displayed in target zone with correct dst and offset

6. compute duration between two timestamps with compute_duration()

input: start (rfc 3339 string), end (rfc 3339 string)
output: object with keys: total_seconds (number), hours (number), minutes (number), seconds (number), human_readable (string, e.g. "8 hours 30 minutes")
elapsed time between two points, regardless of timezone

7. adjust timestamp with dst awareness using adjust_timestamp()

input: datetime (rfc 3339 string), adjustment (offset string like "+1d", "-30m", "in 2 hours"), timezone (iana string)
output: object with keys: original_datetime (rfc 3339), adjusted_datetime (rfc 3339), timezone (iana string), dst_crossed (boolean), wall_clock_preserved (boolean)
applies offset preserving wall-clock time across dst boundaries (e.g. "+1d" on March 7 23:00 EST yields March 8 23:00 EDT, not 00:00)

decision points

if resolve_datetime() receives an rfc 3339 string: return it unchanged and set interpretation to "rfc 3339 passthrough". do not attempt to re-parse.

if config.json is missing or incomplete: fall back to system timezone and monday week-start. do not fail. log missing fields at debug level.

if adjust_timestamp() adjustment crosses dst boundary: set dst_crossed: true and preserve wall-clock time (not absolute seconds). for example, "+1d" across spring-forward stays at same hour:minute, even though utc seconds are not exactly 86400.

if compute_duration() end is before start: return negative total_seconds and adjust hours, minutes, seconds accordingly. set human_readable to include "negative" prefix.

if get_temporal_context() detects dst within next 7 days: populate dst_next_transition with rfc 3339 of transition moment. if no dst change in next 7 days, set to null.

if convert_timezone() target timezone is invalid iana string: return error with message "unrecognized timezone: ". do not default to utc.

if resolve_datetime() expression is ambiguous (e.g. "2pm" without day context): interpret relative to today and set interpretation to describe assumption (e.g. "2pm today").

if network is unavailable during npx install: installation fails. use docker or pre-downloaded binary as fallback. do not attempt retry.

output contract

all datetime outputs use rfc 3339 format (e.g. "2026-03-15T14:00:00-04:00")
all timezone values are iana strings (e.g. "America/New_York", "Asia/Tokyo")
all offsets are strings in +/-HH:MM format (e.g. "-04:00")
all numeric time values (hours, minutes, seconds) are integers
duration human_readable strings use format "N hours M minutes [S seconds]" (omit zero components)
binary checksum file location: ~/.config/temporal-cortex/checksums.json (embedded in npm package, verified at postinstall)
config file location: ~/.config/temporal-cortex/config.json (optional, user-created)
no filesystem writes occur during tool execution. binary is read-only.

outcome signal

you know the skill worked when:

get_temporal_context() returns current utc time, local time, and your configured timezone without error
resolve_datetime("next Tuesday at 2pm") returns an rfc 3339 timestamp with your timezone offset and an interpretation field explaining how the expression was parsed
convert_timezone() shows the same moment in a different zone with the correct offset and dst status
compute_duration() returns a human-readable duration and total_seconds matching the interval between your inputs
adjust_timestamp() preserves wall-clock time when crossing dst (e.g. adding 1 day at 23:00 EST stays 23:00 EDT, not 00:00)
binary verification passes (sha256 checksum matches github release checksums) or is skipped safely
no network requests occur after the initial npm install

temporal-cortex-datetime

related skills

temporal-cortex-datetime

intent

inputs

procedure

decision points

output contract

outcome signal