feat(hyperdx): accept flexible time inputs to fix LLM epoch-ms failures by vibegui · Pull Request #403 · decocms/mcps

vibegui · 2026-04-25T13:50:33Z

Summary

When a user asks the HyperDX agent something like "at around 14:00 GMT-3 we had a spike of errors, what was it?", the agent has to convert local time + timezone + today's date into epoch milliseconds before it can call QUERY_CHART_DATA. That math routinely fails — the LLM has no reliable current clock and falls back to guessing now from stale data (the actual screenshot from this report: "last timestamps I saw in the data were around 1777037400000 ms epoch"), so even correct TZ math against a guessed now produces a wrong window and the chart query fails.

This PR shifts the time math to the server, which has a real Date.now().

All 8 time-range tools (SEARCH_LOGS, GET_LOG_DETAILS, QUERY_CHART_DATA, QUERY_SPANS, QUERY_METRICS, GET_SERVICE_HEALTH, COMPARE_TIME_RANGES, DISCOVER_DATA) now accept number | string for startTime/endTime. Accepted string forms:
- ISO 8601 with timezone — "2026-04-24T14:00:00-03:00", "…Z", "…+05:30"
- now arithmetic — "now", "now-1h", "now+15m", compound "now-2h30m"
- Shorthand "N ago" — "30m", "2h", "7d", compound "2h30m"
- Date only (UTC midnight) — "2026-04-24"
- Naive ISO without timezone is rejected with an actionable error the LLM can self-correct from.
New RESOLVE_TIME_RANGE tool — cheap, no-side-effect preview. The agent can call it to confirm its interpretation of ambiguous phrasing before firing a heavy chart query. Returns { startTime, endTime, startIso, endIso, durationMs, humanReadable }.
New HYPERDX_AGENT_GUIDE prompt resource — top-level instructions for an agent connecting to this MCP. Listed first in prompts/list so clients surface it as the natural entry point. Covers onboarding (DISCOVER_DATA first), time syntax with the GMT-3 worked example, tool selection, search essentials, and common pitfalls. Existing HYPERDX_QUERY_GUIDE also gained a Time Range Syntax section.
35 unit tests in time.test.ts covering every accepted form, all rejection cases, and the regression where "1h-30m" used to emit a misleading "no timezone" error.

Backward compatible — numeric epoch ms still works everywhere; existing numeric defaults (Date.now() − 15 * 60 * 1000 etc.) are untouched.

Test plan

bun test hyperdx/server/lib/time.test.ts — 35/35 pass
tools/list exports "type": ["number","string"] for every time param with the new union description
RESOLVE_TIME_RANGE resolves all 4 input shapes correctly via live MCP call (epoch ms / ISO+TZ / now-1h / 2h30m)
Naive ISO emits "Timestamp '…' has no timezone. Append 'Z' for UTC or an offset like '-03:00'."
Malformed "1h-30m" emits "Could not parse '1h-30m' as a duration" (not the misleading TZ error)
prompts/list returns 3 prompts with HYPERDX_AGENT_GUIDE first
HYPERDX_AGENT_GUIDE body renders with the GMT-3 worked example and all required sections

Notes

TypeScript pre-existing errors in this MCP (103 baseline) come from a monorepo-wide @decocms/runtime@1.1.3 ↔ zod@3.25 version mismatch tracked in fix(shared): bump @decocms/runtime from 1.1.3 to 1.3.1 #350 / chore: bump @decocms/runtime to 1.4.0, migrate createPrivateTool #372. This PR adds 4 errors of the same kind to the new tool/schema — same upstream root cause, not a new failure mode. Runtime behavior is verified end-to-end.
IANA timezone names (e.g. America/Sao_Paulo) are intentionally out of scope for v1 — LLMs reliably convert "GMT-3" → -03:00, and IANA support would require Intl offset lookup with DST handling.

🤖 Generated with Claude Code

Summary by cubic

Shifted time parsing to the server and added flexible time inputs across all HyperDX tools, fixing failures caused by the agent guessing epoch milliseconds. Also added a time-window preview tool and updated prompts so local times like “14:00 GMT-3” work without manual math.

New Features
- All 8 time-range tools now accept number | string for startTime/endTime.
- Accepted forms: ISO 8601 with timezone; now/now±<duration>; shorthand like 30m/2h30m; date-only YYYY-MM-DD (UTC midnight). Naive ISO without timezone is rejected with a clear fix.
- Added RESOLVE_TIME_RANGE to preview resolved { startTime, endTime, startIso, endIso, durationMs, humanReadable } with no side effects.
- Added HYPERDX_AGENT_GUIDE (listed first) and updated HYPERDX_QUERY_GUIDE with Time Range Syntax.
- Backward compatible — numeric epoch ms still works; existing defaults unchanged.

^{Written for commit 4a0dabe. Summary will update on new commits.}

…ailures When a user asks "around 14:00 GMT-3 we had a spike of errors" the agent had to compute epoch ms manually — and routinely guessed `now` from stale data ("last timestamp I saw was around 1777037400000 ms"), making the chart query fail. Shifts time math to the server, which has a real clock. - All 8 time-range tools now accept `number | string` for time params: ISO 8601 with timezone, "now"/"now±<duration>", shorthand "30m"/"2h"/"7d", and date-only YYYY-MM-DD. Naive ISO without TZ is rejected with an actionable error the LLM can self-correct from. - New RESOLVE_TIME_RANGE tool: cheap, side-effect-free preview of any expression pair. The agent can confirm "around 14:00 GMT-3" before firing a heavy chart query. - New HYPERDX_AGENT_GUIDE prompt resource — top-level entry-point system prompt covering onboarding, time syntax with the GMT-3 worked example, tool selection, search essentials, and pitfalls. Listed first in prompts/list so MCP clients surface it as the natural starting point. - Extended HYPERDX_QUERY_GUIDE with a Time Range Syntax section. - Adds 35 unit tests in time.test.ts covering every accepted form, every rejection case, and the regression where "1h-30m" used to emit a misleading "no timezone" error. Backward compatible: numeric epoch ms still works everywhere. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

decobot · 2026-04-25T13:50:39Z