@openephemeris/mcp-server 4.6.0 → 4.8.0

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/index.d.ts

@@ -57,7 +57,11 @@ export interface ToolDefinition {
  * multi-tenant HTTP server cannot vary it per session, and an unregistered
  * tool becomes uncallable rather than merely hidden.
  */
-export type ToolSurface = "core" | "full";
+export type ToolSurface = "core" | "full" | ToolsetSurface;
+/** A caller-chosen set of traditions, e.g. `?profile=hd,bazi`. */
+export interface ToolsetSurface {
+    readonly toolsets: readonly string[];
+}
 /**
  * The default advertised surface: everyday astrology work, one tool per job.
  *
@@ -80,6 +84,28 @@ export type ToolSurface = "core" | "full";
  * explore_natal_chart are present. Do not remove those four.
  */
 export declare const CORE_TOOL_NAMES: ReadonlySet<string>;
+/**
+ * Tool surfaces grouped by tradition, so a caller pays context only for the
+ * work they actually do: `?profile=hd,bazi` on HTTP, `OPENEPHEMERIS_TOOLS=hd`
+ * on stdio. BASE_TOOLSET is always included.
+ *
+ * This is the same *view* filter as `core`/`full` — nothing is unregistered,
+ * every tool stays callable by name — so a toolset is a context-budget choice,
+ * never a capability one.
+ *
+ * Why this exists: the core surface is re-sent on every model pass and sat at
+ * its ceiling with ~0 headroom, and the only levers left were deleting the
+ * disambiguation prose that makes tool selection work. Grouping by tradition
+ * is the structural fix — a Human Design user should not pay for Venus Star
+ * Points on every message.
+ *
+ * Names here are asserted against the registry by a test; a typo fails the
+ * build rather than silently narrowing someone's surface.
+ */
+export declare const TOOLSETS: Readonly<Record<string, readonly string[]>>;
+export declare const TOOLSET_NAMES: readonly string[];
+/** Resolve a toolset selection to the tool names it advertises. */
+export declare function toolsetSelectionNames(names: readonly string[]): Set<string>;
 /**
  * Returns tools that should be exposed to Claude in the ListTools response.
  * Filters out tools that have visibility restricted to the UI (app-only),
@@ -87,8 +113,21 @@ export declare const CORE_TOOL_NAMES: ReadonlySet<string>;
  * "core" — everything outside CORE_TOOL_NAMES.
  */
 export declare function modelVisibleTools(transport?: "stdio" | "http", surface?: ToolSurface): ToolDefinition[];
-/** Parses a caller-supplied surface hint. Anything unrecognised means "core". */
+/**
+ * Parses a caller-supplied surface hint.
+ *
+ *   "full"          -> every model-visible tool
+ *   "hd" | "hd,bazi" -> those traditions plus BASE_TOOLSET
+ *   anything else   -> "core" (the curated default)
+ *
+ * Unknown names in a comma list are ignored rather than rejected: a typo
+ * degrades to a smaller surface, never to an error at `initialize` that would
+ * leave the connector dead. If NO name in the list is recognised, fall back to
+ * "core" so a mistyped profile can't strand a caller on BASE alone.
+ */
 export declare function parseToolSurface(raw: unknown): ToolSurface;
+/** Stable label for logs/analytics — an object surface has no useful toString. */
+export declare function describeSurface(surface: ToolSurface): string;
 export declare const toolRegistry: Record<string, ToolDefinition>;
 export declare function registerTool(tool: ToolDefinition): void;
 export type ToolProfile = "dev" | "legacy";

package/dist/tools/index.js

@@ -12,6 +12,9 @@ export const SERVER_VERSION = (() => {
         return "0.0.0-unknown";
     }
 })();
+function isToolsetSurface(s) {
+    return typeof s === "object" && Array.isArray(s.toolsets);
+}
 /**
  * The default advertised surface: everyday astrology work, one tool per job.
  *
@@ -53,6 +56,13 @@ export const CORE_TOOL_NAMES = new Set([
     "ephemeris_transits",
     "ephemeris_synastry",
     "ephemeris_retrograde_status",
+    // Promoted 2026-08-02 on usage: both were reachable only via profile=full,
+    // yet ephemeris_aspect_check drew 19 calls from 3 users over 90 days (more
+    // than 20 of the tools already in this set) and ephemeris_angles_points drew
+    // 9. People found them while they were hidden; advertising them is cheap
+    // (202 and 227 tokens) and earns its place.
+    "ephemeris_aspect_check",
+    "ephemeris_angles_points",
     "ephemeris_next_eclipse",
     "ephemeris_relocation",
     "ephemeris_progressed_chart",
@@ -60,13 +70,31 @@ export const CORE_TOOL_NAMES = new Set([
     // Traditions
     "human_design_chart",
     "vedic_chart",
-    "chinese_bazi",
     "bazi_annual_pillar",
+    // chinese_bazi demoted 2026-08-02: explore_bazi_chart POSTs the same
+    // /chinese/bazi at the same 1-credit base and keeps every substantive field
+    // (year/month/day/hour pillars + day_master), dropping only the `metadata`
+    // and `success` envelope keys — verified against a live response, not
+    // inferred from the names. It also degrades to a text summary on hosts that
+    // cannot render the iframe, so nothing is lost without an MCP Apps host.
+    // chinese_bazi drew 0 calls in 90 days while advertised; explore_bazi_chart
+    // drew 3. Still registered and callable by name, and still in profile=full.
+    //
+    // NOTE: this reasoning does NOT extend to the sibling pairs. vedic_chart (1
+    // credit) vs explore_vedic_chart (3), and human_design_chart (2 credits, full
+    // response) vs explore_human_design (4 credits, and buildHdModelPayload drops
+    // activations/design/personality/strategy/variables) are not folds — they
+    // would cost users money and data. Verify in the handler before adding to
+    // this list.
     // Timing
     "ephemeris_electional",
     "electional_moment_analysis",
     "electional_station_tracker",
-    "electional_angle_crossings",
+    // electional_angle_crossings demoted 2026-08-02: 715 tokens (the fattest
+    // non-proxy tool in this set) for 0 calls in 90 days, and at 5 credits it is
+    // advanced-practitioner work rather than an everyday ask. Three electional
+    // entry points remain advertised; this one is a profile=full / skill-named
+    // tool now.
     // Astrocartography
     "acg_power_lines",
     "acg_hits",
@@ -83,6 +111,141 @@ export const CORE_TOOL_NAMES = new Set([
     "auth_status",
     "auth_logout",
 ]);
+/**
+ * Tools every session needs regardless of tradition: turning a place name into
+ * coordinates, checking credits, and the allowlist-gated escape hatch. Always
+ * unioned into a toolset selection — a caller who asks for `hd` still has to be
+ * able to resolve a birthplace, or they are back to recalling coordinates from
+ * memory, which is the bug BASE exists to prevent.
+ */
+const BASE_TOOLSET = [
+    "location_search",
+    "timezone_resolve",
+    "account_usage",
+    "dev_read_api",
+    // The write half of the escape hatch. 26 of the 31 allowlisted operations
+    // are POST — BASE without dev_write_api would strand a toolset caller with
+    // only the 5 GET proxies. (Deliberately NOT advertised in `core`, where the
+    // curated typed tools cover the write surface; a toolset selection has no
+    // such coverage, so it needs the proxy whole.)
+    "dev_write_api",
+    "dev_list_allowed",
+    "auth_login",
+    "auth_status",
+    "auth_logout",
+];
+/**
+ * Tool surfaces grouped by tradition, so a caller pays context only for the
+ * work they actually do: `?profile=hd,bazi` on HTTP, `OPENEPHEMERIS_TOOLS=hd`
+ * on stdio. BASE_TOOLSET is always included.
+ *
+ * This is the same *view* filter as `core`/`full` — nothing is unregistered,
+ * every tool stays callable by name — so a toolset is a context-budget choice,
+ * never a capability one.
+ *
+ * Why this exists: the core surface is re-sent on every model pass and sat at
+ * its ceiling with ~0 headroom, and the only levers left were deleting the
+ * disambiguation prose that makes tool selection work. Grouping by tradition
+ * is the structural fix — a Human Design user should not pay for Venus Star
+ * Points on every message.
+ *
+ * Names here are asserted against the registry by a test; a typo fails the
+ * build rather than silently narrowing someone's surface.
+ */
+export const TOOLSETS = {
+    /** Western natal/predictive work — the default tradition. */
+    astrology: [
+        "ephemeris_natal_chart",
+        "explore_natal_chart",
+        "ephemeris_planet_position",
+        "ephemeris_house_cusps",
+        "ephemeris_angles_points",
+        "ephemeris_aspect_check",
+        "ephemeris_transits",
+        "ephemeris_natal_transits",
+        "explore_transit_timeline",
+        "ephemeris_synastry",
+        "explore_bi_wheel",
+        "bi_wheel_synopsis",
+        "ephemeris_retrograde_status",
+        "ephemeris_progressed_chart",
+        "ephemeris_solar_return",
+        "ephemeris_lunar_return",
+        "ephemeris_planetary_return",
+        "ephemeris_relocation",
+        "ephemeris_dignities",
+        "ephemeris_midpoints",
+        "ephemeris_hermetic_lots",
+        "ephemeris_fixed_stars",
+        "ephemeris_composite",
+        "ephemeris_composite_midpoint",
+        "ephemeris_overlay",
+        "ephemeris_chart_wheel",
+        "ephemeris_bi_wheel",
+        "ephemeris_natal_batch",
+    ],
+    /** Lunar phase, void-of-course and eclipse work. */
+    moon: [
+        "ephemeris_moon_phase",
+        "explore_moon_phase",
+        "ephemeris_next_lunar_phase",
+        "ephemeris_next_eclipse",
+    ],
+    /** Human Design. */
+    hd: [
+        "human_design_chart",
+        "explore_human_design",
+        "explore_human_design_transit",
+        "explore_human_design_connection",
+        "human_design_bodygraph",
+        "human_design_composite",
+        "human_design_penta",
+        "hd_opposition",
+        "hd_planetary_return",
+    ],
+    /** Chinese BaZi / Four Pillars. */
+    bazi: [
+        "explore_bazi_chart",
+        "chinese_bazi",
+        "bazi_chart",
+        "bazi_ten_gods",
+        "bazi_element_balance",
+        "bazi_luck_pillars",
+        "bazi_annual_pillar",
+        "bazi_compatibility",
+    ],
+    /** Vedic / Jyotish. */
+    vedic: ["vedic_chart", "explore_vedic_chart"],
+    /** Astrocartography. */
+    acg: ["acg_hits", "acg_power_lines"],
+    /** Electional timing. */
+    electional: [
+        "ephemeris_electional",
+        "electional_moment_analysis",
+        "electional_station_tracker",
+        "electional_angle_crossings",
+        "electional_aspect_search",
+    ],
+    /** Venus Star Point / synodic-cycle work. */
+    venus: [
+        "venus_star_points",
+        "venus_star_points_conjunctions",
+        "venus_phase",
+        "venus_elongations",
+        "venus_stations",
+        "venus_eight_year_star",
+    ],
+};
+export const TOOLSET_NAMES = Object.keys(TOOLSETS);
+/** Resolve a toolset selection to the tool names it advertises. */
+export function toolsetSelectionNames(names) {
+    const out = new Set(BASE_TOOLSET);
+    for (const n of names) {
+        for (const t of TOOLSETS[n] ?? [])
+            out.add(t);
+    }
+    return out;
+}
 /**
  * Returns tools that should be exposed to Claude in the ListTools response.
  * Filters out tools that have visibility restricted to the UI (app-only),
@@ -90,6 +253,9 @@ export const CORE_TOOL_NAMES = new Set([
  * "core" — everything outside CORE_TOOL_NAMES.
  */
 export function modelVisibleTools(transport = "stdio", surface = "full") {
+    const allowed = isToolsetSurface(surface)
+        ? toolsetSelectionNames(surface.toolsets)
+        : null;
     return Object.values(toolRegistry).filter((t) => {
         if (transport === "http" && t.stdioOnly)
             return false;
@@ -97,14 +263,45 @@ export function modelVisibleTools(transport = "stdio", surface = "full") {
         // If visibility is explicitly ["app"] (no "model"), hide from model
         if (vis && !vis.includes("model") && vis.includes("app"))
             return false;
+        if (allowed)
+            return allowed.has(t.name);
         if (surface === "core" && !CORE_TOOL_NAMES.has(t.name))
             return false;
         return true;
     });
 }
-/** Parses a caller-supplied surface hint. Anything unrecognised means "core". */
+/**
+ * Parses a caller-supplied surface hint.
+ *
+ *   "full"          -> every model-visible tool
+ *   "hd" | "hd,bazi" -> those traditions plus BASE_TOOLSET
+ *   anything else   -> "core" (the curated default)
+ *
+ * Unknown names in a comma list are ignored rather than rejected: a typo
+ * degrades to a smaller surface, never to an error at `initialize` that would
+ * leave the connector dead. If NO name in the list is recognised, fall back to
+ * "core" so a mistyped profile can't strand a caller on BASE alone.
+ */
 export function parseToolSurface(raw) {
-    return typeof raw === "string" && raw.toLowerCase() === "full" ? "full" : "core";
+    if (typeof raw !== "string")
+        return "core";
+    const value = raw.trim().toLowerCase();
+    if (value === "full")
+        return "full";
+    if (value === "" || value === "core")
+        return "core";
+    const requested = value
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    const known = requested.filter((n) => Object.hasOwn(TOOLSETS, n));
+    if (known.length === 0)
+        return "core";
+    return { toolsets: known };
+}
+/** Stable label for logs/analytics — an object surface has no useful toString. */
+export function describeSurface(surface) {
+    return isToolsetSurface(surface) ? surface.toolsets.join("+") : surface;
 }
 export const toolRegistry = {};
 export function registerTool(tool) {

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;