@openephemeris/mcp-server 4.6.0 → 4.7.0

package/CHANGELOG.md

@@ -7,6 +7,44 @@ Version numbering follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [4.7.0] — 2026-08-02
+
+Historically correct birth-time conversion. IANA timezone databases — including
+the one inside every JavaScript runtime — are only authoritative from 1970.
+Before the US Uniform Time Act took effect in 1967, daylight saving was state
+and municipal law, and a zone like `America/Chicago` models Chicago alone. A
+1961 Minnesota birth converted with standard timezone math lands an hour off,
+which flips the Ascendant sign and the Human Design design-Moon gate.
+
+### Added
+
+- **Pre-1970 births now resolve through the API's historical correction
+  overlay.** Any tool given a naive local birth time with a timezone and
+  coordinates — natal, Human Design (chart, composite, penta, cycles, groups),
+  Vedic, BaZi apps, ACG, moon tools, and the embedded chart apps — routes the
+  local→UTC conversion through the API's `/timezone/offset` `datetime_local`
+  mode, which applies primary-source-cited state and local law (with a
+  `tz_confidence` grade and rule citation) instead of assuming the reference
+  city's rules. Post-1970 conversions stay on the local, zero-latency path,
+  which is exactly as authoritative as the server. If the server is
+  unreachable, tools fall back to the previous local conversion rather than
+  failing the chart call.
+- **`timezone_resolve`** consults the same historical path for pre-1970 dates
+  and reports `tzConfidence`, `tzRuleSource`, and `datetimeStatus` (ambiguous
+  DST-fold and nonexistent-gap times are called out explicitly).
+- **`location_search`** tags each suggestion's historical offset with a
+  confidence grade and a note when a pre-1970 date may be affected by
+  state/local law divergence.
+
+### Fixed
+
+- Three skills and one prompt still instructed the model to convert local
+  birth times to UTC itself with generic timezone math — the exact manual
+  conversion the historical overlay exists to prevent. They now direct all
+  conversion through the API.
+
+---
+
 ## [4.6.0] — 2026-07-30
 
 Fixes the tool that could not answer the question it is named for, closes the

package/dist/prompts.js

@@ -377,8 +377,9 @@ export const PROMPTS = [
             "even 10–15 minutes can shift the Type, Authority, or Profile. If truly unknown, " +
             "proceed with solar noon but flag that results may be imprecise.\n" +
             "4. **Birth city and country** — needed for timezone conversion\n\n" +
-            "## Step 2 — CRITICAL: Convert to UTC\n" +
-            "Human Design requires **UTC datetime**. The tool rejects local times without a UTC offset.\n\n" +
+            "## Step 2 — Resolve Coordinates and Timezone\n" +
+            "Human Design needs the exact birth instant; the tool resolves it from local time + " +
+            "timezone + coordinates automatically (historically correct even pre-1970).\n\n" +
             "**Resolve the birth place with `location_search`** — pass `query: 'Birth City, Country'` " +
             "and `date` set to the birth date (`YYYY-MM-DD`). One call returns decimal lat/lon, the " +
             "IANA timezone, and `utcOffsetAtDate` — the offset that actually applied at that place on " +

package/dist/tools/apps/bodygraph-app.js

@@ -25,7 +25,7 @@ import { fileURLToPath } from "node:url";
 import { registerTool, SERVER_VERSION } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
-import { localToUtcIso } from "../datetime.js";
+import { localToUtcIsoHistorical } from "../datetime-historical.js";
 import { coordsFromArgsOrLocation } from "./_location-resolver.js";
 // ── Constants ─────────────────────────────────────────────────────────────
 export const BODYGRAPH_RESOURCE_URI = "ui://openephemeris/bodygraph";
@@ -372,9 +372,9 @@ registerTool({
             location: args.location,
         });
         const timezone = args.timezone ?? resolved.timezone;
-        const datetime = localToUtcIso("datetime", String(args.datetime), timezone);
         const lat = resolved.latitude;
         const lon = resolved.longitude;
+        const datetime = await localToUtcIsoHistorical("datetime", String(args.datetime), timezone, { latitude: lat, longitude: lon });
         if (lat == null || lon == null) {
             throw new Error("explore_human_design requires either `latitude` + `longitude` or a resolvable `location` name. " +
                 "Human Design is sensitive to birth location; a chart at 0°N 0°E is silently wrong.");
@@ -473,10 +473,11 @@ registerTool({
     handler: async (args) => {
         const client = getActiveClient();
         const timezone = args.timezone;
-        // Convert local-time input → UTC using IANA timezone when provided
-        const datetime = localToUtcIso("datetime", String(args.datetime), timezone);
         const lat = args.latitude;
         const lon = args.longitude;
+        // Convert local-time input → UTC using IANA timezone when provided;
+        // pre-1970 births route through the API's historical correction overlay.
+        const datetime = await localToUtcIsoHistorical("datetime", String(args.datetime), timezone, { latitude: lat, longitude: lon });
         const theme = args.theme === "light" ? "light" : "dark";
         const layout = args.layout === "mandala" ? "mandala" : undefined;
         const rings = typeof args.rings === "string" ? args.rings : undefined;
@@ -1365,9 +1366,9 @@ registerTool({
             location: args.location,
         });
         const timezone = args.timezone ?? resolved.timezone;
-        const natalIso = localToUtcIso("datetime", String(args.datetime), timezone);
         const lat = resolved.latitude;
         const lon = resolved.longitude;
+        const natalIso = await localToUtcIsoHistorical("datetime", String(args.datetime), timezone, { latitude: lat, longitude: lon });
         if (lat == null || lon == null) {
             throw new Error("explore_human_design_transit requires either `latitude` + `longitude` or a resolvable `location` name. " +
                 "Human Design is sensitive to birth location; a chart at 0°N 0°E is silently wrong.");
@@ -1389,7 +1390,7 @@ registerTool({
         };
         if (args.transit_datetime) {
             body.transit_datetime = {
-                iso: localToUtcIso("transit_datetime", String(args.transit_datetime), args.timezone),
+                iso: await localToUtcIsoHistorical("transit_datetime", String(args.transit_datetime), args.timezone, { latitude: lat, longitude: lon }),
             };
         }
         const bundleAvailable = Boolean(getBodygraphBundle());
@@ -1520,7 +1521,7 @@ registerTool({
                     "Human Design is sensitive to birth location; a chart at 0°N 0°E is silently wrong.");
             }
             return {
-                birth_datetime_utc: localToUtcIso(`${label}.datetime`, String(p?.datetime), tz, `${label}.timezone`),
+                birth_datetime_utc: await localToUtcIsoHistorical(`${label}.datetime`, String(p?.datetime), tz, { latitude: lat, longitude: lon }, `${label}.timezone`),
                 latitude: lat,
                 longitude: lon,
             };

package/dist/tools/apps/location-tools.js

@@ -1,6 +1,15 @@
 import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
+import { TZDATA_AUTHORITATIVE_FROM_YEAR } from "../datetime-historical.js";
+/** Render minutes east of UTC as `±HH:MM`. */
+function formatOffsetMinutes(offsetMinutes) {
+    const sign = offsetMinutes < 0 ? "-" : "+";
+    const abs = Math.abs(offsetMinutes);
+    const hh = String(Math.floor(abs / 60)).padStart(2, "0");
+    const mm = String(Math.round(abs % 60)).padStart(2, "0");
+    return `${sign}${hh}:${mm}`;
+}
 /**
  * The UTC offset of an IANA zone is a function of place AND date: 1987 US DST
  * rules are not today's rules, and America/Chicago ran on CDT through the whole
@@ -143,6 +152,8 @@ registerTool({
         // Map the API's snake_case response to the camelCase shape the app UI consumes.
         const list = Array.isArray(raw?.suggestions) ? raw.suggestions : [];
         const date = args.date != null && String(args.date).trim() !== "" ? String(args.date).trim() : null;
+        const dateYear = date ? Number(date.slice(0, 4)) : null;
+        const preTzdataEra = dateYear != null && Number.isFinite(dateYear) && dateYear < TZDATA_AUTHORITATIVE_FROM_YEAR;
         const suggestions = list.map((s) => {
             const mapped = {
                 displayName: s.display_name,
@@ -154,8 +165,17 @@ registerTool({
                 longitude: s.longitude,
                 timezone: s.timezone,
             };
-            if (date && s.timezone)
-                Object.assign(mapped, offsetAtLocalNoon(s.timezone, date) ?? {});
+            if (date && s.timezone) {
+                const offset = offsetAtLocalNoon(s.timezone, date);
+                if (offset) {
+                    // These offsets come from local tzdata, which is only
+                    // authoritative from 1970 — before that it models the
+                    // zone's reference city, not state/local law.
+                    Object.assign(mapped, offset, {
+                        tzConfidence: preTzdataEra ? "historical_estimate" : "authoritative",
+                    });
+                }
+            }
             return mapped;
         });
         // Ambiguity signal. "portland" really does match Oregon, Maine, Texas,
@@ -180,6 +200,11 @@ registerTool({
         return {
             suggestions,
             matchCount: suggestions.length,
+            ...(preTzdataEra
+                ? {
+                    historicalNote: "Pre-1970 date: tzdata offsets are reference-city estimates. For the chosen place, call timezone_resolve with the same date (or submit the naive local time + timezone + coordinates to the chart endpoint) to apply the API's historical correction overlay.",
+                }
+                : {}),
             ambiguous,
             ...(ambiguous
                 ? {
@@ -203,7 +228,7 @@ registerTool({
             longitude: { type: "number" },
             date: {
                 type: "string",
-                description: "Optional birth/event date as 'YYYY-MM-DD'. When given, the result also carries utcOffsetAtDate / utcOffsetMinutes / isDst for that date under that zone's historical DST rules. Free: adds no API call and no credits.",
+                description: "Optional birth/event date 'YYYY-MM-DD'. Adds utcOffsetAtDate / utcOffsetMinutes / isDst / tzConfidence. Post-1970 resolves locally (free); pre-1970 consults the API's historical correction overlay (1 extra credit).",
             },
         },
         required: ["latitude", "longitude"],
@@ -228,9 +253,46 @@ registerTool({
         const date = args.date != null && String(args.date).trim() !== "" ? String(args.date).trim() : null;
         const tz = typeof result?.timezone === "string" ? result.timezone : null;
         if (date && tz) {
+            // Pre-1970 dates: tzdata (Node's and Go's alike) models the zone's
+            // reference city only, so ask the API — its historical correction
+            // overlay knows where state law diverged (e.g. Minnesota 1959-66).
+            // Costs one extra credit, only for pre-1970 dates.
+            const year = Number(date.slice(0, 4));
+            if (Number.isFinite(year) && year < TZDATA_AUTHORITATIVE_FROM_YEAR) {
+                try {
+                    const off = (await getActiveClient().request("POST", "/timezone/offset", {
+                        data: { lat: args.latitude, lon: args.longitude, datetime_local: `${date.slice(0, 10)}T12:00:00` },
+                    }));
+                    if (typeof off?.offset_seconds === "number") {
+                        const minutes = off.offset_seconds / 60;
+                        return {
+                            ...result,
+                            utcOffsetAtDate: formatOffsetMinutes(minutes),
+                            utcOffsetMinutes: minutes,
+                            isDst: Boolean(off.is_dst),
+                            date,
+                            tzConfidence: typeof off.tz_confidence === "string" ? off.tz_confidence : "historical_estimate",
+                            ...(typeof off.tz_rule_source === "string" ? { tzRuleSource: off.tz_rule_source } : {}),
+                            ...(typeof off.datetime_status === "string" ? { datetimeStatus: off.datetime_status } : {}),
+                        };
+                    }
+                }
+                catch {
+                    // Server path unavailable — fall through to the local
+                    // tzdata estimate below, flagged as such.
+                }
+            }
             const offset = offsetAtLocalNoon(tz, date);
-            if (offset)
-                return { ...result, ...offset, date };
+            if (offset) {
+                return {
+                    ...result,
+                    ...offset,
+                    date,
+                    tzConfidence: Number.isFinite(year) && year < TZDATA_AUTHORITATIVE_FROM_YEAR
+                        ? "historical_estimate"
+                        : "authoritative",
+                };
+            }
         }
         return result;
     },

package/dist/tools/apps/moon-phase-app.js

@@ -17,7 +17,8 @@ import { fileURLToPath } from "node:url";
 import { registerTool, validateCoordinates, SERVER_VERSION } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
-import { TIMEZONE_PROPERTY, localToUtcIso } from "../datetime.js";
+import { TIMEZONE_PROPERTY } from "../datetime.js";
+import { localToUtcIsoHistorical } from "../datetime-historical.js";
 // ── Constants ─────────────────────────────────────────────────────────────────
 export const MOON_PHASE_RESOURCE_URI = "ui://openephemeris/moon-phase";
 export const MOON_PHASE_MIME_TYPE = "text/html;profile=mcp-app";
@@ -98,7 +99,7 @@ async function computeMoonData(args) {
     const client = getActiveClient();
     const params = {};
     params.datetime = args.datetime
-        ? localToUtcIso("datetime", String(args.datetime), args.timezone)
+        ? await localToUtcIsoHistorical("datetime", String(args.datetime), args.timezone, { latitude: args.latitude, longitude: args.longitude })
         : new Date().toISOString();
     if (args.latitude != null)
         params.latitude = args.latitude;

package/dist/tools/apps/vedic-chart-app.js

@@ -23,7 +23,7 @@ import { fileURLToPath } from "node:url";
 import { registerTool, validateRequired, validateCoordinates, SERVER_VERSION } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
-import { localToUtcIso } from "../datetime.js";
+import { localToUtcIsoHistorical } from "../datetime-historical.js";
 import { coordsFromArgsOrLocation } from "./_location-resolver.js";
 // ── Constants ─────────────────────────────────────────────────────────────────
 export const VEDIC_CHART_RESOURCE_URI = "ui://openephemeris/vedic-chart";
@@ -165,9 +165,9 @@ registerTool({
         validateCoordinates(argsWithResolved, "latitude", "longitude");
         const client = getActiveClient();
         const timezone = args.timezone ?? resolved.timezone;
-        const datetime = localToUtcIso("datetime", String(args.datetime), timezone);
         const lat = Number(resolved.latitude);
         const lon = Number(resolved.longitude);
+        const datetime = await localToUtcIsoHistorical("datetime", String(args.datetime), timezone, { latitude: lat, longitude: lon });
         const ayanamsa = args.ayanamsa;
         const location = String(resolved.location ?? args.location ?? `${lat}, ${lon}`).slice(0, 120);
         const bundleAvailable = Boolean(getVedicChartBundle());
@@ -244,9 +244,9 @@ registerTool({
     _meta: { ui: { resourceUri: VEDIC_CHART_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const client = getActiveClient();
-        const datetime = localToUtcIso("datetime", String(args.datetime), args.timezone);
         const lat = args.latitude != null ? Number(args.latitude) : undefined;
         const lon = args.longitude != null ? Number(args.longitude) : undefined;
+        const datetime = await localToUtcIsoHistorical("datetime", String(args.datetime), args.timezone, { latitude: lat, longitude: lon });
         const ayanamsa = args.ayanamsa;
         const theme = args.theme === "light" ? "light" : "dark";
         const body = {

package/dist/tools/datetime-historical.d.ts

@@ -0,0 +1,19 @@
+/** Where IANA tzdata stops being reference-city best effort. */
+export declare const TZDATA_AUTHORITATIVE_FROM_YEAR = 1970;
+export interface BirthCoords {
+    latitude?: number | null;
+    longitude?: number | null;
+}
+/** True when a naive local datetime needs the server-side historical path. */
+export declare function needsHistoricalResolution(dt: string, coords?: BirthCoords): boolean;
+/**
+ * `localToUtcIso`, but historically correct when it matters.
+ *
+ * Same contract as `localToUtcIso` (naive value with no `tz` throws the
+ * ambiguous-datetime error; zone-suffixed and date-only values pass through).
+ * For a pre-1970 naive value with known coordinates, the conversion is done
+ * by the API's `/timezone/offset` `datetime_local` mode so the historical
+ * correction overlay applies. Everything else — including every post-1970
+ * conversion — stays on the local, zero-latency Intl path.
+ */
+export declare function localToUtcIsoHistorical(field: string, dt: string, tz?: string, coords?: BirthCoords, timezoneField?: string): Promise<string>;

package/dist/tools/datetime-historical.js

@@ -0,0 +1,77 @@
+/**
+ * Historically-correct local → UTC conversion.
+ *
+ * IANA tzdata — Node's Intl and the Go engine's tzdata alike — is only
+ * authoritative from 1970. Before the US Uniform Time Act (effective 1967),
+ * DST was a state and municipal matter, and tzdata models each zone's
+ * reference city only. `localToUtcIso`'s Intl math is therefore silently an
+ * hour off for births like Robbinsdale, MN 1961-10-09 17:56 (Minnesota was on
+ * CST while America/Chicago says CDT), which flips the Ascendant sign and the
+ * HD design-Moon gate.
+ *
+ * The Go API owns the correction: `POST /timezone/offset` with
+ * `datetime_local` + coordinates resolves through its historical-correction
+ * overlay (apps/api/go-sidecar/internal/historicaltz) and returns the true
+ * instant plus a `tz_confidence` grade. This module routes the conversions
+ * that need it — pre-1970, naive, with known coordinates — through that
+ * endpoint, and leaves every other case on the local Intl path, which is
+ * exactly as authoritative as the server for 1970+.
+ *
+ * Fallback discipline: if the server call fails or resolves a different zone
+ * than the caller explicitly named, we fall back to `localToUtcIso` — the
+ * pre-existing behavior — rather than failing the chart call. Best effort
+ * beats an outage; the server remains the single authority whenever it is
+ * reachable.
+ */
+import { getActiveClient } from "../backend/client.js";
+import { hasZoneSuffix, isNaiveClockTime, localToUtcIso } from "./datetime.js";
+/** Where IANA tzdata stops being reference-city best effort. */
+export const TZDATA_AUTHORITATIVE_FROM_YEAR = 1970;
+/** True when a naive local datetime needs the server-side historical path. */
+export function needsHistoricalResolution(dt, coords) {
+    const value = (dt ?? "").trim();
+    if (!isNaiveClockTime(value) || hasZoneSuffix(value))
+        return false;
+    const year = Number(value.slice(0, 4));
+    return (Number.isFinite(year) &&
+        year < TZDATA_AUTHORITATIVE_FROM_YEAR &&
+        typeof coords?.latitude === "number" &&
+        typeof coords?.longitude === "number");
+}
+/**
+ * `localToUtcIso`, but historically correct when it matters.
+ *
+ * Same contract as `localToUtcIso` (naive value with no `tz` throws the
+ * ambiguous-datetime error; zone-suffixed and date-only values pass through).
+ * For a pre-1970 naive value with known coordinates, the conversion is done
+ * by the API's `/timezone/offset` `datetime_local` mode so the historical
+ * correction overlay applies. Everything else — including every post-1970
+ * conversion — stays on the local, zero-latency Intl path.
+ */
+export async function localToUtcIsoHistorical(field, dt, tz, coords, timezoneField = "timezone") {
+    const value = (dt ?? "").trim();
+    if (!needsHistoricalResolution(value, coords) || !tz || tz.trim() === "") {
+        // Includes the naive-without-tz case, which must throw the same
+        // ambiguous-datetime error localToUtcIso throws.
+        return localToUtcIso(field, dt, tz, timezoneField);
+    }
+    try {
+        const res = (await getActiveClient().request("POST", "/timezone/offset", {
+            data: {
+                lat: coords.latitude,
+                lon: coords.longitude,
+                datetime_local: value,
+            },
+        }));
+        // Respect an explicit caller zone: the server resolves the zone from
+        // the coordinates, so only trust its instant when the zones agree.
+        if (res?.resolved_utc && (!res.timezone || res.timezone === tz.trim())) {
+            return res.resolved_utc;
+        }
+    }
+    catch {
+        // Server unreachable or rejected the request — fall through to the
+        // local conversion rather than failing the chart call.
+    }
+    return localToUtcIso(field, dt, tz, timezoneField);
+}

package/dist/tools/specialized/acg.js

@@ -1,7 +1,8 @@
 import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
-import { DATETIME_DESC, TIMEZONE_PROPERTY, localToUtcIso } from "../datetime.js";
+import { DATETIME_DESC, TIMEZONE_PROPERTY } from "../datetime.js";
+import { localToUtcIsoHistorical } from "../datetime-historical.js";
 const ACG_BODY_DESCRIPTION = "List of celestial bodies for line calculation. " +
     "E.g. ['Sun', 'Moon', 'Venus', 'Mars', 'Jupiter', 'Saturn']. " +
     "Aliases: 'NorthNode'/'Node'/'Rahu' → MeanNode, 'SouthNode'/'Ketu' → SouthNode. " +
@@ -67,7 +68,7 @@ registerTool({
                 birthplace_lat: args.birth_latitude,
                 birthplace_lon: args.birth_longitude,
             },
-            epoch: localToUtcIso("birth_datetime", args.birth_datetime, args.timezone),
+            epoch: await localToUtcIsoHistorical("birth_datetime", args.birth_datetime, args.timezone, { latitude: args.birth_latitude, longitude: args.birth_longitude }),
         };
         if (args.bodies)
             body.bodies = args.bodies;
@@ -164,7 +165,7 @@ registerTool({
                 birthplace_lat: args.birth_latitude,
                 birthplace_lon: args.birth_longitude,
             },
-            epoch: localToUtcIso("birth_datetime", args.birth_datetime, args.timezone),
+            epoch: await localToUtcIsoHistorical("birth_datetime", args.birth_datetime, args.timezone, { latitude: args.birth_latitude, longitude: args.birth_longitude }),
             query_lat: args.query_latitude,
             query_lon: args.query_longitude,
         };

package/dist/tools/specialized/hd_bodygraph.js

@@ -1,7 +1,8 @@
 import { registerTool, validateRequired, pickEnum } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
-import { DATETIME_DESC, TIMEZONE_PROPERTY, localToUtcIso } from "../datetime.js";
+import { DATETIME_DESC, TIMEZONE_PROPERTY } from "../datetime.js";
+import { localToUtcIsoHistorical } from "../datetime-historical.js";
 registerTool({
     name: "human_design_bodygraph",
     description: "Generate a Human Design Bodygraph image (SVG) from a birth datetime (UTC). " +
@@ -12,7 +13,7 @@ registerTool({
         "For a user-facing interactive bodygraph explorer, use explore_human_design instead.\n\n" +
         "CREDIT COST: 2 credits per call.\n\n" +
         "EXAMPLE (local birth time + zone): born 15 April 1990 at 14:30 in Chicago:\n" +
-        "  datetime='1990-04-15T14:30:00', timezone='America/Chicago'\n" +
+        "  datetime='1990-04-15T14:30:00', timezone='America/Chicago', latitude=41.8781, longitude=-87.6298\n" +
         "EXAMPLE (already in UTC):\n" +
         "  datetime='1990-04-15T19:30:00Z'",
     inputSchema: {
@@ -24,6 +25,14 @@ registerTool({
                     " Human Design is time-sensitive — accuracy to the minute matters.",
             },
             timezone: TIMEZONE_PROPERTY,
+            latitude: {
+                type: "number",
+                description: "Optional birth latitude in decimal degrees. Only used to apply the historical timezone correction for pre-1970 local birth times (e.g. state-level DST deviations); has no effect on the bodygraph itself.",
+            },
+            longitude: {
+                type: "number",
+                description: "Optional birth longitude in decimal degrees. See latitude.",
+            },
             style: {
                 type: "string",
                 enum: ["light", "dark", "mono"],
@@ -44,7 +53,7 @@ registerTool({
     handler: async (args) => {
         validateRequired(args, ["datetime"]);
         const body = {
-            birth_datetime_utc: localToUtcIso("datetime", args.datetime, args.timezone),
+            birth_datetime_utc: await localToUtcIsoHistorical("datetime", args.datetime, args.timezone, { latitude: args.latitude, longitude: args.longitude }),
         };
         const format = pickEnum(args.format, ["svg", "png"]) || "svg";
         const style = pickEnum(args.style, ["light", "dark", "mono"]);

package/dist/tools/specialized/hd_cycles.js

@@ -1,7 +1,21 @@
 import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
-import { DATETIME_DESC, TIMEZONE_PROPERTY, localToUtcIso } from "../datetime.js";
+import { DATETIME_DESC, TIMEZONE_PROPERTY } from "../datetime.js";
+import { localToUtcIsoHistorical } from "../datetime-historical.js";
+/** Optional birth coordinates, present only to feed the historical timezone
+ * correction for pre-1970 naive local birth times — not sent to the Go
+ * endpoint, which is non-relocational. */
+const OPTIONAL_BIRTH_COORDS = {
+    latitude: {
+        type: "number",
+        description: "Optional birth latitude in decimal degrees. Only used to apply the historical timezone correction for pre-1970 local birth times; has no other effect.",
+    },
+    longitude: {
+        type: "number",
+        description: "Optional birth longitude in decimal degrees. See latitude.",
+    },
+};
 registerTool({
     name: "hd_planetary_return",
     description: "Calculate a Human Design planetary return chart — full HD chart " +
@@ -29,6 +43,7 @@ registerTool({
                 description: DATETIME_DESC,
             },
             timezone: TIMEZONE_PROPERTY,
+            ...OPTIONAL_BIRTH_COORDS,
             return_year: {
                 type: "integer",
                 description: "Year to find the return near (e.g. 2020 for a Saturn return at ~age 29).",
@@ -49,7 +64,7 @@ registerTool({
         return await getActiveClient().request("POST", "/human-design/cycles/return", {
             data: {
                 planet: args.planet,
-                birth_datetime_utc: localToUtcIso("datetime", args.datetime, args.timezone),
+                birth_datetime_utc: await localToUtcIsoHistorical("datetime", args.datetime, args.timezone, { latitude: args.latitude, longitude: args.longitude }),
                 return_year: args.return_year,
                 format: args.format,
                 include_chiron: args.include_chiron,
@@ -82,6 +97,7 @@ registerTool({
                 description: DATETIME_DESC,
             },
             timezone: TIMEZONE_PROPERTY,
+            ...OPTIONAL_BIRTH_COORDS,
             target_year: {
                 type: "integer",
                 description: "Year to search for the opposition near.",
@@ -102,7 +118,7 @@ registerTool({
         return await getActiveClient().request("POST", "/human-design/cycles/opposition", {
             data: {
                 planet: args.planet,
-                birth_datetime_utc: localToUtcIso("datetime", args.datetime, args.timezone),
+                birth_datetime_utc: await localToUtcIsoHistorical("datetime", args.datetime, args.timezone, { latitude: args.latitude, longitude: args.longitude }),
                 target_year: args.target_year,
                 format: args.format,
                 include_chiron: args.include_chiron,

package/dist/tools/specialized/hd_group.js

@@ -1,7 +1,8 @@
 import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
-import { DATETIME_DESC, localToUtcIso, timezoneProperty } from "../datetime.js";
+import { DATETIME_DESC, timezoneProperty } from "../datetime.js";
+import { localToUtcIsoHistorical } from "../datetime-historical.js";
 // POST /human-design/composite — OE-027
 registerTool({
     name: "human_design_composite",
@@ -21,11 +22,27 @@ registerTool({
                 description: DATETIME_DESC,
             },
             person_a_timezone: timezoneProperty("Person A's birth location"),
+            person_a_latitude: {
+                type: "number",
+                description: "Optional Person A birth latitude in decimal degrees. Only used to apply the historical timezone correction for pre-1970 local birth times; has no other effect.",
+            },
+            person_a_longitude: {
+                type: "number",
+                description: "Optional Person A birth longitude in decimal degrees. See person_a_latitude.",
+            },
             person_b_datetime: {
                 type: "string",
                 description: DATETIME_DESC,
             },
             person_b_timezone: timezoneProperty("Person B's birth location", "America/Los_Angeles"),
+            person_b_latitude: {
+                type: "number",
+                description: "Optional Person B birth latitude in decimal degrees. See person_a_latitude.",
+            },
+            person_b_longitude: {
+                type: "number",
+                description: "Optional Person B birth longitude in decimal degrees.",
+            },
             format: {
                 type: "string",
                 enum: ["json", "llm"],
@@ -41,10 +58,10 @@ registerTool({
         validateRequired(args, ["person_a_datetime", "person_b_datetime"]);
         const body = {
             subject_1: {
-                birth_datetime_utc: localToUtcIso("person_a_datetime", args.person_a_datetime, args.person_a_timezone, "person_a_timezone"),
+                birth_datetime_utc: await localToUtcIsoHistorical("person_a_datetime", args.person_a_datetime, args.person_a_timezone, { latitude: args.person_a_latitude, longitude: args.person_a_longitude }, "person_a_timezone"),
             },
             subject_2: {
-                birth_datetime_utc: localToUtcIso("person_b_datetime", args.person_b_datetime, args.person_b_timezone, "person_b_timezone"),
+                birth_datetime_utc: await localToUtcIsoHistorical("person_b_datetime", args.person_b_datetime, args.person_b_timezone, { latitude: args.person_b_latitude, longitude: args.person_b_longitude }, "person_b_timezone"),
             },
         };
         if (args.format)
@@ -81,6 +98,14 @@ registerTool({
                         name: { type: "string", description: "Member's name." },
                         datetime: { type: "string", description: DATETIME_DESC },
                         timezone: timezoneProperty("this member's birth location"),
+                        latitude: {
+                            type: "number",
+                            description: "Optional birth latitude in decimal degrees. Only used to apply the historical timezone correction for pre-1970 local birth times; has no other effect.",
+                        },
+                        longitude: {
+                            type: "number",
+                            description: "Optional birth longitude in decimal degrees. See latitude.",
+                        },
                     },
                     required: ["id", "name", "datetime"],
                 },
@@ -101,13 +126,13 @@ registerTool({
     annotations: { title: "HD Penta Group Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, ["group_name", "members"]);
-        const members = args.members.map((m, i) => ({
+        const members = await Promise.all(args.members.map(async (m, i) => ({
             id: m.id,
             name: m.name,
             birth_data: {
-                birth_datetime_utc: localToUtcIso(`members[${i}].datetime`, m.datetime, m.timezone, `members[${i}].timezone`),
+                birth_datetime_utc: await localToUtcIsoHistorical(`members[${i}].datetime`, m.datetime, m.timezone, { latitude: m.latitude, longitude: m.longitude }, `members[${i}].timezone`),
             },
-        }));
+        })));
         const body = {
             group_name: args.group_name,
             members,

package/dist/tools/specialized/human_design.js

@@ -1,7 +1,8 @@
 import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_IMAGE_AND_JSON } from "../output-schemas.js";
-import { DATETIME_DESC, TIMEZONE_PROPERTY, localToUtcIso } from "../datetime.js";
+import { DATETIME_DESC, TIMEZONE_PROPERTY } from "../datetime.js";
+import { localToUtcIsoHistorical } from "../datetime-historical.js";
 registerTool({
     name: "human_design_chart",
     description: "Calculate a full Human Design I Ching hexagram chart from birth data. Returns the person's Type " +
@@ -65,7 +66,7 @@ registerTool({
     handler: async (args) => {
         validateRequired(args, ["datetime"]);
         const body = {
-            birth_datetime_utc: localToUtcIso("datetime", args.datetime, args.timezone),
+            birth_datetime_utc: await localToUtcIsoHistorical("datetime", args.datetime, args.timezone, { latitude: args.latitude, longitude: args.longitude }),
         };
         if (args.latitude != null)
             body.latitude = args.latitude;

package/dist/tools/specialized/moon.js

@@ -1,7 +1,8 @@
 import { registerTool, validateCoordinates } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
-import { TIMEZONE_PROPERTY, localToUtcIso } from "../datetime.js";
+import { TIMEZONE_PROPERTY } from "../datetime.js";
+import { localToUtcIsoHistorical } from "../datetime-historical.js";
 registerTool({
     name: "ephemeris_moon_phase",
     description: "Get the Moon's current phase angle, illumination, sign and void-of-course status AT a " +
@@ -49,7 +50,7 @@ registerTool({
         // Backend requires datetime even though the schema marks it optional.
         // Default to current UTC time when caller omits it.
         params.datetime = args.datetime
-            ? localToUtcIso("datetime", args.datetime, args.timezone)
+            ? await localToUtcIsoHistorical("datetime", args.datetime, args.timezone, { latitude: args.latitude, longitude: args.longitude })
             : new Date().toISOString();
         if (args.latitude != null)
             params.latitude = args.latitude;