@openephemeris/mcp-server 3.24.0 → 4.0.0

package/dist/tools/specialized/bazi.js

@@ -1,17 +1,16 @@
 import { registerTool } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_IMAGE_AND_JSON } from "../output-schemas.js";
-function parseBaziArgs(args) {
+export function parseBaziArgs(args, datetimeField = "datetime") {
     let { year, month, day, hour } = args;
-    if (args.datetime && (!year || !month || !day)) {
-        const dt = new Date(args.datetime);
-        if (!isNaN(dt.getTime())) {
-            year = dt.getUTCFullYear();
-            month = dt.getUTCMonth() + 1;
-            day = dt.getUTCDate();
-            if (hour == null)
-                hour = dt.getUTCHours();
-        }
+    const datetime = args[datetimeField];
+    if (datetime && (!year || !month || !day)) {
+        const parts = baziLocalComponents(datetime, args.timezone, datetimeField);
+        year = parts.year;
+        month = parts.month;
+        day = parts.day;
+        if (hour == null)
+            hour = parts.hour;
     }
     if (!year || !month || !day) {
         throw new Error("Provide year/month/day fields, or a datetime ISO string. " +
@@ -22,6 +21,49 @@ function parseBaziArgs(args) {
         out.hour = hour;
     return out;
 }
+/**
+ * Extract the LOCAL calendar/clock components a BaZi chart is built from.
+ *
+ * BaZi pillars are a function of local wall-clock time at the birth place — the
+ * hour pillar is a two-hour shí block on the local clock — so unlike a western
+ * chart there is no UTC instant to resolve to, and a zone-less datetime is
+ * exactly right here. What was wrong was HOW those components were read: the
+ * previous implementation did `new Date("1987-07-15T14:00:00")`, which JS parses
+ * in the *host process's* timezone, then read `.getUTCHours()`. On any server
+ * not running in UTC that silently shifted the hour pillar, and near midnight
+ * the day pillar too. Reading the components lexically removes the dependency on
+ * where the server happens to be.
+ *
+ * A datetime that carries its own zone (`Z` / `±HH:MM`) is not local wall-clock
+ * time. It is converted into `timezone` when one is supplied; without one, its
+ * own stated zone is taken as the local clock, which is the long-standing
+ * behaviour and the only reading available.
+ */
+function baziLocalComponents(datetime, timezone, field) {
+    const value = String(datetime).trim();
+    const zoned = /([Zz]|[+-]\d{2}:?\d{2})$/.test(value);
+    if (zoned && timezone) {
+        const parts = new Intl.DateTimeFormat("en-US", {
+            timeZone: timezone,
+            hour12: false,
+            year: "numeric", month: "2-digit", day: "2-digit",
+            hour: "2-digit", minute: "2-digit",
+        }).formatToParts(new Date(value));
+        const get = (t) => Number(parts.find((p) => p.type === t)?.value);
+        return { year: get("year"), month: get("month"), day: get("day"), hour: get("hour") % 24 };
+    }
+    const m = /^(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2}))?/.exec(value);
+    if (!m) {
+        throw new Error(`\`${field}\` is "${value}", which is not an ISO 8601 date or datetime. ` +
+            "Example: '1987-07-15T14:00:00' (local time at the birth place).");
+    }
+    return {
+        year: Number(m[1]),
+        month: Number(m[2]),
+        day: Number(m[3]),
+        hour: m[4] != null ? Number(m[4]) : undefined,
+    };
+}
 // Shared datetime input schema fragment — used across all BaZiRequest tools.
 const DATETIME_PROPERTIES = {
     year: {
@@ -43,8 +85,17 @@ const DATETIME_PROPERTIES = {
     },
     datetime: {
         type: "string",
-        description: "Alternative to year/month/day: ISO 8601 datetime (e.g. '1987-07-15T14:00:00'). " +
-            "year/month/day/hour are extracted automatically. Use this OR the individual fields.",
+        description: "Alternative to year/month/day: ISO 8601 datetime read as LOCAL wall-clock time at the " +
+            "birth place — BaZi pillars are local by definition, so a zone-less value like " +
+            "'1987-07-15T14:00:00' is correct here and is NOT converted to UTC. " +
+            "If you pass an instant instead ('1987-07-15T19:00:00Z' or with an offset), also pass " +
+            "`timezone` so the local hour can be derived. Use this OR the individual fields.",
+    },
+    timezone: {
+        type: "string",
+        description: "IANA timezone name for the birth place, e.g. 'Asia/Shanghai'. Only needed when " +
+            "`datetime` carries a 'Z' or ±HH:MM offset, to convert that instant back to the local " +
+            "clock the pillars are built from.",
     },
 };
 // Shared visual input schema fragment — mirrors natal.ts pattern.
@@ -132,7 +183,7 @@ registerTool({
         "  RESOURCE:  Indirect Resource (偏印), Direct Resource (正印)\n\n" +
         "The Day Pillar itself has no Ten God (it IS the Day Master). " +
         "Hidden stems in the Day Branch still receive Ten God labels.\n\n" +
-        "CREDIT COST: 1 credit (3 credits when include_visual=true).\n\n" +
+        "CREDIT COST: 3 credits (5 credits when include_visual=true).\n\n" +
         "Set include_visual=true to receive an SVG Four Pillars chart alongside the Ten Gods data.\n\n" +
         "EXAMPLE: Ten Gods for someone born July 15, 1987 at 2 PM:\n" +
         "  year=1987, month=7, day=15, hour=14",
@@ -167,7 +218,7 @@ registerTool({
         "Also returns:\n" +
         "  • Day Master strength: 'strong' (旺, ≥50% own+resource elements) or 'weak' (弱)\n" +
         "  • Yong Shen (用神): the favorable element — what the chart needs most\n\n" +
-        "CREDIT COST: 1 credit (3 credits when include_visual=true).\n\n" +
+        "CREDIT COST: 3 credits (5 credits when include_visual=true).\n\n" +
         "Set include_visual=true to receive an SVG Four Pillars chart alongside the element data.\n\n" +
         "EXAMPLE: Element balance for 1987-07-15 at 14:00:\n" +
         "  year=1987, month=7, day=15, hour=14",
@@ -204,7 +255,7 @@ registerTool({
         "gender is REQUIRED — the direction of luck pillars is gender-dependent.\n\n" +
         "Returns: starting_age, direction, direction_reason, and 8 pillars each with:\n" +
         "  stem, branch, Chinese characters, element, start_age, end_age\n\n" +
-        "CREDIT COST: 1 credit per call.\n\n" +
+        "CREDIT COST: 3 credits per call.\n\n" +
         "EXAMPLE: Luck pillars for a female born July 15, 1987 at 2 PM:\n" +
         "  year=1987, month=7, day=15, hour=14, gender='female'",
     inputSchema: {
@@ -251,7 +302,7 @@ registerTool({
         "  • Identify the energetic quality of any given year\n" +
         "  • Determine a person's birth year pillar for compatibility context\n" +
         "  • Find the NaYin element for year or day interpretations\n\n" +
-        "CREDIT COST: 1 credit per call.\n\n" +
+        "CREDIT COST: 3 credits per call.\n\n" +
         "EXAMPLE: Year pillar for 2025:\n" +
         "  year=2025",
     inputSchema: {
@@ -292,7 +343,7 @@ registerTool({
         "  -6  Three Penalties (三刑 Sān Xíng) — branch penalty formations\n\n" +
         "Assessment grades:\n" +
         "  90–100: excellent | 70–89: good | 50–69: moderate | below 50: challenging\n\n" +
-        "CREDIT COST: 2 credits per call.\n\n" +
+        "CREDIT COST: 3 credits per call.\n\n" +
         "EXAMPLE: Compatibility between two people:\n" +
         "  chart_a_year=1987, chart_a_month=7, chart_a_day=15, chart_a_hour=14\n" +
         "  chart_b_year=1990, chart_b_month=3, chart_b_day=22, chart_b_hour=8",
@@ -306,7 +357,14 @@ registerTool({
             chart_a_hour: { type: "integer", description: "Chart A birth hour (0–23). Optional." },
             chart_a_datetime: {
                 type: "string",
-                description: "Chart A alternative: ISO 8601 datetime. Extracts year/month/day/hour automatically.",
+                description: "Chart A alternative: ISO 8601 datetime read as LOCAL wall-clock time at the birth " +
+                    "place — a zone-less value is correct here and is not converted to UTC. If it carries " +
+                    "a 'Z' or offset, also pass chart_a_timezone. Extracts year/month/day/hour automatically.",
+            },
+            chart_a_timezone: {
+                type: "string",
+                description: "IANA timezone for Chart A's birth place, e.g. 'Asia/Shanghai'. Only needed when " +
+                    "chart_a_datetime carries a 'Z' or ±HH:MM offset.",
             },
             // Chart B
             chart_b_year: { type: "integer", description: "Chart B birth year." },
@@ -315,7 +373,14 @@ registerTool({
             chart_b_hour: { type: "integer", description: "Chart B birth hour (0–23). Optional." },
             chart_b_datetime: {
                 type: "string",
-                description: "Chart B alternative: ISO 8601 datetime. Extracts year/month/day/hour automatically.",
+                description: "Chart B alternative: ISO 8601 datetime read as LOCAL wall-clock time at the birth " +
+                    "place — a zone-less value is correct here and is not converted to UTC. If it carries " +
+                    "a 'Z' or offset, also pass chart_b_timezone. Extracts year/month/day/hour automatically.",
+            },
+            chart_b_timezone: {
+                type: "string",
+                description: "IANA timezone for Chart B's birth place, e.g. 'Asia/Shanghai'. Only needed when " +
+                    "chart_b_datetime carries a 'Z' or ±HH:MM offset.",
             },
         },
         additionalProperties: false,
@@ -329,6 +394,7 @@ registerTool({
             day: args.chart_a_day,
             hour: args.chart_a_hour,
             datetime: args.chart_a_datetime,
+            timezone: args.chart_a_timezone,
         });
         const chartBComponents = parseBaziArgs({
             year: args.chart_b_year,
@@ -336,6 +402,7 @@ registerTool({
             day: args.chart_b_day,
             hour: args.chart_b_hour,
             datetime: args.chart_b_datetime,
+            timezone: args.chart_b_timezone,
         });
         return await getActiveClient().request("POST", "/chinese/bazi/compatibility", {
             data: {

package/dist/tools/specialized/bi_wheel.js

@@ -1,8 +1,7 @@
 import { registerTool, validateRequired, pickEnum } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_IMAGE } from "../output-schemas.js";
-const DATETIME_DESC = "ISO 8601 datetime string, e.g. '1990-04-15T14:30:00' (local time at birth location). " +
-    "Include timezone offset if known, e.g. '1990-04-15T14:30:00-05:00'.";
+import { DATETIME_DESC, assertZonedDatetime, timezoneProperty } from "../datetime.js";
 const HOUSE_SYSTEM_MAP = {
     placidus: "P", whole_sign: "W", equal: "E", koch: "K",
     campanus: "C", regiomontanus: "R", porphyry: "O",
@@ -19,11 +18,11 @@ registerTool({
         type: "object",
         properties: {
             datetime_a: { type: "string", description: DATETIME_DESC },
-            timezone_a: { type: "string", description: "IANA timezone name for subject A, e.g. 'America/Denver'." },
+            timezone_a: timezoneProperty("subject A's location", "America/Denver"),
             latitude_a: { type: "number", description: "Latitude for subject A" },
             longitude_a: { type: "number", description: "Longitude for subject A" },
             datetime_b: { type: "string", description: DATETIME_DESC },
-            timezone_b: { type: "string", description: "IANA timezone name for subject B, e.g. 'Europe/London'." },
+            timezone_b: timezoneProperty("subject B's location", "Europe/London"),
             latitude_b: { type: "number", description: "Latitude for subject B" },
             longitude_b: { type: "number", description: "Longitude for subject B" },
             house_system: {
@@ -44,6 +43,8 @@ registerTool({
     annotations: { title: "Bi-Wheel Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, ["datetime_a", "latitude_a", "longitude_a", "datetime_b", "latitude_b", "longitude_b"]);
+        assertZonedDatetime("datetime_a", args.datetime_a, args.timezone_a, "timezone_a");
+        assertZonedDatetime("datetime_b", args.datetime_b, args.timezone_b, "timezone_b");
         const body = {
             subject_a: {
                 name: "Subject A",

package/dist/tools/specialized/chart_wheel.js

@@ -1,8 +1,7 @@
 import { registerTool, validateRequired, pickEnum } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_IMAGE } from "../output-schemas.js";
-const DATETIME_DESC = "ISO 8601 datetime string, e.g. '1990-04-15T14:30:00' (local time at birth location). " +
-    "Include timezone offset if known, e.g. '1990-04-15T14:30:00-05:00'.";
+import { DATETIME_DESC, TIMEZONE_PROPERTY, assertZonedDatetime } from "../datetime.js";
 const HOUSE_SYSTEM_MAP = {
     placidus: "P", whole_sign: "W", equal: "E", koch: "K",
     campanus: "C", regiomontanus: "R", porphyry: "O",
@@ -13,8 +12,8 @@ registerTool({
     description: "Generate a classic astrological Chart Wheel image (SVG) for a person/event. This draws a standard circular chart wheel with planets, aspects, and house cusps. The tool returns a native SVG image that Claude displays inline in the conversation — no external tools needed.\n\n" +
         "For a user-facing interactive chart wheel, use explore_natal_chart instead.\n\n" +
         "CREDIT COST: 2 credits per call.\n\n" +
-        "EXAMPLE: Generate a natal chart wheel for someone born April 15, 1990 in Chicago:\n" +
-        "  datetime='1990-04-15T14:30:00', latitude=41.8781, longitude=-87.6298",
+        "EXAMPLE: born 15 April 1990 at 2:30 PM local time in Chicago:\n" +
+        "  datetime='1990-04-15T14:30:00', timezone='America/Chicago', latitude=41.8781, longitude=-87.6298",
     inputSchema: {
         type: "object",
         properties: {
@@ -22,10 +21,7 @@ registerTool({
                 type: "string",
                 description: DATETIME_DESC,
             },
-            timezone: {
-                type: "string",
-                description: "IANA timezone name, e.g. 'America/Denver'. Use this if passing local time without a UTC offset in the datetime string.",
-            },
+            timezone: TIMEZONE_PROPERTY,
             latitude: {
                 type: "number",
                 description: "Geographic latitude of birth location in decimal degrees (positive = North).",
@@ -52,6 +48,7 @@ registerTool({
     annotations: { title: "Chart Wheel SVG", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, ["datetime", "latitude", "longitude"]);
+        assertZonedDatetime("datetime", args.datetime, args.timezone);
         const body = {
             subject: {
                 name: "Chart Wheel Request",

package/dist/tools/specialized/comparative.js

@@ -1,6 +1,7 @@
 import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
+import { localToUtcIso } from "../datetime.js";
 function buildSubject(name, datetime, lat, lon, timezone) {
     const subj = {
         name,
@@ -22,8 +23,10 @@ registerTool({
         "uses midpoints of each planet pair to derive a single relationship chart.\n\n" +
         "CREDIT COST: 3 credits per call.\n\n" +
         "EXAMPLE: Composite for two people:\n" +
-        "  person_a_datetime='1990-04-15T14:30:00', person_a_latitude=41.88, person_a_longitude=-87.63,\n" +
-        "  person_b_datetime='1988-09-22T08:15:00', person_b_latitude=34.05, person_b_longitude=-118.24",
+        "  person_a_datetime='1990-04-15T14:30:00', person_a_timezone='America/Chicago',\n" +
+        "  person_a_latitude=41.88, person_a_longitude=-87.63,\n" +
+        "  person_b_datetime='1988-09-22T08:15:00', person_b_timezone='America/Los_Angeles',\n" +
+        "  person_b_latitude=34.05, person_b_longitude=-118.24",
     inputSchema: {
         type: "object",
         properties: {
@@ -163,7 +166,8 @@ registerTool({
         "are aspecting natal positions. Essential for predictive astrology.\n\n" +
         "CREDIT COST: 3 credits per call.\n\n" +
         "EXAMPLE: Current transits to someone born 1990-04-15:\n" +
-        "  natal_datetime='1990-04-15T14:30:00', natal_latitude=41.88, natal_longitude=-87.63",
+        "  natal_datetime='1990-04-15T14:30:00', natal_timezone='America/Chicago',\n" +
+        "  natal_latitude=41.88, natal_longitude=-87.63",
     inputSchema: {
         type: "object",
         properties: {
@@ -188,8 +192,12 @@ registerTool({
             subject: buildSubject("Natal", args.natal_datetime, args.natal_latitude, args.natal_longitude, args.natal_timezone),
         };
         if (args.transit_datetime) {
-            // transit_datetime is a DateTimeInput on the backend
-            body.transit_datetime = { iso: args.transit_datetime };
+            // transit_datetime is a DateTimeInput on the backend, and unlike the
+            // subject it has no timezone companion — so , which
+            // was declared but never read, is resolved here.
+            body.transit_datetime = {
+                iso: localToUtcIso("transit_datetime", args.transit_datetime, args.transit_timezone, "transit_timezone"),
+            };
         }
         const query = {};
         if (args.format)

package/dist/tools/specialized/electional.js

@@ -25,7 +25,7 @@ registerTool({
             },
             latitude: {
                 type: "number",
-                description: "Latitude of location in decimal degrees (positive = North).",
+                description: "Latitude of location in decimal degrees (positive = North). Resolve from a place name with location_search; never recall coordinates from memory.",
             },
             longitude: {
                 type: "number",
@@ -89,15 +89,15 @@ registerTool({
     description: "Analyze the astrological quality of a specific moment: planet positions, aspects, " +
         "void of course status, lunar phase, day ruler, and an overall electional score (0-100). " +
         "Perfect for evaluating whether 'right now' or a specific date/time is good for action.\n\n" +
-        "CREDIT COST: 2 credits per call.\n\n" +
+        "CREDIT COST: 5 credits per call.\n\n" +
         "EXAMPLE: Analyze March 21, 2026 at noon:\n" +
-        "  date='2026-03-21T12:00:00'",
+        "  date='2026-03-21T12:00:00Z'",
     inputSchema: {
         type: "object",
         properties: {
             date: {
                 type: "string",
-                description: "ISO 8601 datetime to analyze (e.g., '2026-03-21T12:00:00'). Defaults to now.",
+                description: "ISO 8601 datetime to analyze, with a zone (e.g., '2026-03-21T12:00:00Z' or '2026-03-21T08:00:00-04:00'). Defaults to now.",
             },
             format: {
                 type: "string",
@@ -129,7 +129,7 @@ registerTool({
         "USE THIS TOOL FOR: 'When does Mercury go retrograde?', 'Is Venus retrograde this year?', " +
         "'What planets station this month?', 'When does Mars go direct?'\n\n" +
         "All required fields have smart defaults (searches the next 90 days from today).\n\n" +
-        "CREDIT COST: 3 credits per call.\n\n" +
+        "CREDIT COST: 5 credits per call.\n\n" +
         "EXAMPLE: Mercury and Venus stations in the next 3 months (all defaults):\n" +
         "  (no args required, will auto-scan next 90 days for all inner planets)\n\n" +
         "EXAMPLE: Outer planet stations in 2026:\n" +
@@ -198,9 +198,9 @@ registerTool({
     description: "Find all active aspects between planets at a specific moment. Returns aspect type, " +
         "orb, quality score, and whether it's applying or separating. Great for checking " +
         "the 'weather' of a given day.\n\n" +
-        "CREDIT COST: 2 credits per call.\n\n" +
+        "CREDIT COST: 5 credits per call.\n\n" +
         "EXAMPLE: What aspects are active on March 21, 2026?\n" +
-        "  date='2026-03-21T12:00:00'",
+        "  date='2026-03-21T12:00:00Z'",
     inputSchema: {
         type: "object",
         properties: {

package/dist/tools/specialized/ephemeris_core.js

@@ -1,14 +1,17 @@
 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";
 // POST /ephemeris/planet-position — OE-016
 registerTool({
     name: "ephemeris_planet_position",
     description: "Get the precise ecliptic longitude, latitude, distance, speed, and retrograde status " +
         "for a single planet/body at a given date and time. " +
         "Planet IDs: 0=Sun, 1=Moon, 2=Mercury, 3=Venus, 4=Mars, 5=Jupiter, 6=Saturn, " +
-        "7=Uranus, 8=Neptune, 9=Pluto, 10=North Node, 11=South Node, 12=Lilith, " +
-        "15=Chiron, 17=Ceres, 18=Pallas, 19=Juno, 20=Vesta.\n\n" +
+        "7=Uranus, 8=Neptune, 9=Pluto, 10=North Node (Mean), 11=North Node (True), " +
+        "12=Lilith (Mean), 15=Chiron, 17=Ceres, 18=Pallas, 19=Juno, 20=Vesta.\n\n" +
+        "SOUTH NODE: there is no South Node id. The South Node is always exactly " +
+        "opposite the North Node — request id 10 or 11 and add 180° (mod 360).\n\n" +
         "CREDIT COST: 1 credit per call.\n\n" +
         "EXAMPLE: Where is Mars on 2026-03-20 at noon UTC?\n" +
         "  planet_id=4, datetime='2026-03-20T12:00:00Z'",
@@ -17,12 +20,13 @@ registerTool({
         properties: {
             planet_id: {
                 type: "integer",
-                description: "Planet/body ID (0=Sun, 1=Moon, 2=Mercury, 3=Venus, 4=Mars, 5=Jupiter, 6=Saturn, 7=Uranus, 8=Neptune, 9=Pluto, 10=MeanNode, 11=TrueNode, 12=Lilith, 15=Chiron, 17=Ceres, 18=Pallas, 19=Juno, 20=Vesta).",
+                description: "Planet/body ID (0=Sun, 1=Moon, 2=Mercury, 3=Venus, 4=Mars, 5=Jupiter, 6=Saturn, 7=Uranus, 8=Neptune, 9=Pluto, 10=North Node (Mean), 11=North Node (True), 12=Lilith (Mean), 15=Chiron, 17=Ceres, 18=Pallas, 19=Juno, 20=Vesta). There is no South Node id — take the North Node and add 180°.",
             },
             datetime: {
                 type: "string",
-                description: "ISO 8601 date/time in UTC or with offset (e.g. '2026-03-20T12:00:00Z' or '2026-03-20T12:00:00-05:00').",
+                description: DATETIME_DESC,
             },
+            timezone: TIMEZONE_PROPERTY,
             latitude: {
                 type: "number",
                 description: "Observer latitude for topocentric position (optional). Omit for geocentric.",
@@ -41,7 +45,7 @@ registerTool({
         validateRequired(args, ["planet_id", "datetime"]);
         const body = {
             planet_id: args.planet_id,
-            date_time: { iso: args.datetime },
+            date_time: { iso: localToUtcIso("datetime", args.datetime, args.timezone) },
         };
         if (args.latitude != null)
             body.latitude = args.latitude;
@@ -64,11 +68,12 @@ registerTool({
         properties: {
             datetime: {
                 type: "string",
-                description: "ISO 8601 date/time in UTC or with offset (e.g. '2026-03-20T12:00:00Z').",
+                description: DATETIME_DESC,
             },
+            timezone: TIMEZONE_PROPERTY,
             latitude: {
                 type: "number",
-                description: "Observer latitude in decimal degrees.",
+                description: "Observer latitude in decimal degrees. Resolve from a place name with location_search; never recall coordinates from memory.",
             },
             longitude: {
                 type: "number",
@@ -88,7 +93,7 @@ registerTool({
     handler: async (args) => {
         validateRequired(args, ["datetime", "latitude", "longitude"]);
         const body = {
-            date_time: { iso: args.datetime },
+            date_time: { iso: localToUtcIso("datetime", args.datetime, args.timezone) },
             latitude: args.latitude,
             longitude: args.longitude,
         };

package/dist/tools/specialized/ephemeris_extended.js

@@ -1,6 +1,7 @@
 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, assertZonedDatetime, localToUtcIso } from "../datetime.js";
 function buildSubject(name, datetime, lat, lon) {
     return {
         name,
@@ -21,8 +22,8 @@ registerTool({
         "(100 subjects = 100 credits). Confirm with the user before large batches.\n\n" +
         "EXAMPLE: Two people batch:\n" +
         "  subjects: [\n" +
-        "    { name: 'Alice', datetime: '1990-04-15T14:30:00', latitude: 41.88, longitude: -87.63 },\n" +
-        "    { name: 'Bob', datetime: '1988-09-22T08:15:00', latitude: 34.05, longitude: -118.24 }\n" +
+        "    { name: 'Alice', datetime: '1990-04-15T14:30:00', timezone: 'America/Chicago', latitude: 41.88, longitude: -87.63 },\n" +
+        "    { name: 'Bob', datetime: '1988-09-22T15:15:00Z', latitude: 34.05, longitude: -118.24 }\n" +
         "  ]",
     inputSchema: {
         type: "object",
@@ -33,7 +34,8 @@ registerTool({
                     type: "object",
                     properties: {
                         name: { type: "string", description: "Subject name." },
-                        datetime: { type: "string", description: "Birth datetime (ISO 8601)." },
+                        datetime: { type: "string", description: DATETIME_DESC },
+                        timezone: TIMEZONE_PROPERTY,
                         latitude: { type: "number", description: "Birth latitude." },
                         longitude: { type: "number", description: "Birth longitude." },
                     },
@@ -49,6 +51,7 @@ registerTool({
     annotations: { title: "Natal Batch Charts", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, ["subjects"]);
+        args.subjects.forEach((s, i) => assertZonedDatetime(`subjects[${i}].datetime`, s?.datetime, s?.timezone, `subjects[${i}].timezone`));
         const items = args.subjects.map((s) => ({
             subject: buildSubject(s.name, s.datetime, s.latitude, s.longitude),
         }));
@@ -64,7 +67,8 @@ registerTool({
     inputSchema: {
         type: "object",
         properties: {
-            datetime: { type: "string", description: "ISO 8601 date/time." },
+            datetime: { type: "string", description: DATETIME_DESC },
+            timezone: TIMEZONE_PROPERTY,
         },
         required: ["datetime"],
         additionalProperties: false,
@@ -74,7 +78,7 @@ registerTool({
     handler: async (args) => {
         validateRequired(args, ["datetime"]);
         return await getActiveClient().post("/ephemeris/dignities", {
-            date_time: { iso: args.datetime },
+            date_time: { iso: localToUtcIso("datetime", args.datetime, args.timezone) },
         });
     },
 });
@@ -86,12 +90,14 @@ registerTool({
     name: "ephemeris_retrograde_status",
     description: "Get retrograde/direct status and speed for all planets at a given date/time. " +
         "Returns is_retrograde flag, longitude speed, and station proximity for every planet.\n\n" +
-        "CREDIT COST: 1 credit per call.\n\n" +
+        "CREDIT COST: 10 credits for the all-planets sweep (the backend bills one " +
+        "credit per body and this fans out to 10), or 1 credit when planet_id is given.\n\n" +
         "Optionally pass planet_id (0-9) to query a single planet.",
     inputSchema: {
         type: "object",
         properties: {
-            datetime: { type: "string", description: "ISO 8601 date/time." },
+            datetime: { type: "string", description: DATETIME_DESC },
+            timezone: TIMEZONE_PROPERTY,
             planet_id: { type: "integer", description: "Optional single planet ID (0-9). Omit for all planets." },
         },
         required: ["datetime"],
@@ -105,14 +111,14 @@ registerTool({
         // If a specific planet is requested, delegate directly.
         if (args.planet_id != null) {
             return await client.post("/ephemeris/retrograde-status", {
-                date_time: { iso: args.datetime },
+                date_time: { iso: localToUtcIso("datetime", args.datetime, args.timezone) },
                 planet_id: args.planet_id,
             });
         }
         // Fan-out: the backend only handles one planet per call; query all 10 in parallel.
         const PLANET_IDS = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
         const results = await Promise.all(PLANET_IDS.map((pid) => client.post("/ephemeris/retrograde-status", {
-            date_time: { iso: args.datetime },
+            date_time: { iso: localToUtcIso("datetime", args.datetime, args.timezone) },
             planet_id: pid,
         }).catch(() => null)));
         // Merge into a keyed object: { planet_name: {...status} }
@@ -140,7 +146,8 @@ registerTool({
     inputSchema: {
         type: "object",
         properties: {
-            datetime: { type: "string", description: "ISO 8601 date/time." },
+            datetime: { type: "string", description: DATETIME_DESC },
+            timezone: TIMEZONE_PROPERTY,
             latitude: { type: "number", description: "Observer latitude." },
             longitude: { type: "number", description: "Observer longitude." },
         },
@@ -152,7 +159,7 @@ registerTool({
     handler: async (args) => {
         validateRequired(args, ["datetime", "latitude", "longitude"]);
         return await getActiveClient().post("/ephemeris/midpoints", {
-            date_time: { iso: args.datetime },
+            date_time: { iso: localToUtcIso("datetime", args.datetime, args.timezone) },
             latitude: args.latitude,
             longitude: args.longitude,
         });
@@ -167,7 +174,8 @@ registerTool({
     inputSchema: {
         type: "object",
         properties: {
-            datetime: { type: "string", description: "ISO 8601 date/time." },
+            datetime: { type: "string", description: DATETIME_DESC },
+            timezone: TIMEZONE_PROPERTY,
             star_names: {
                 type: "array",
                 items: { type: "string" },
@@ -183,7 +191,7 @@ registerTool({
     handler: async (args) => {
         validateRequired(args, ["datetime"]);
         const body = {
-            date_time: { iso: args.datetime },
+            date_time: { iso: localToUtcIso("datetime", args.datetime, args.timezone) },
         };
         if (args.star_names)
             body.star_names = args.star_names;
@@ -232,7 +240,8 @@ registerTool({
     inputSchema: {
         type: "object",
         properties: {
-            datetime: { type: "string", description: "ISO 8601 date/time." },
+            datetime: { type: "string", description: DATETIME_DESC },
+            timezone: TIMEZONE_PROPERTY,
             latitude: { type: "number", description: "Observer latitude." },
             longitude: { type: "number", description: "Observer longitude." },
         },
@@ -244,7 +253,7 @@ registerTool({
     handler: async (args) => {
         validateRequired(args, ["datetime", "latitude", "longitude"]);
         return await getActiveClient().post("/ephemeris/hermetic-lots", {
-            date_time: { iso: args.datetime },
+            date_time: { iso: localToUtcIso("datetime", args.datetime, args.timezone) },
             latitude: args.latitude,
             longitude: args.longitude,
         });
@@ -259,7 +268,8 @@ registerTool({
     inputSchema: {
         type: "object",
         properties: {
-            datetime: { type: "string", description: "ISO 8601 date/time." },
+            datetime: { type: "string", description: DATETIME_DESC },
+            timezone: TIMEZONE_PROPERTY,
             latitude: { type: "number", description: "Observer latitude." },
             longitude: { type: "number", description: "Observer longitude." },
         },
@@ -271,7 +281,7 @@ registerTool({
     handler: async (args) => {
         validateRequired(args, ["datetime", "latitude", "longitude"]);
         return await getActiveClient().post("/ephemeris/angles-points", {
-            date_time: { iso: args.datetime },
+            date_time: { iso: localToUtcIso("datetime", args.datetime, args.timezone) },
             latitude: args.latitude,
             longitude: args.longitude,
         });

package/dist/tools/specialized/hd_bodygraph.js

@@ -1,12 +1,7 @@
 import { registerTool, validateRequired, pickEnum } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
-/** Append 'Z' if no timezone offset is present in the datetime string. */
-function ensureTimezone(dt) {
-    if (/[Zz]$/.test(dt) || /[+-]\d{2}:\d{2}$/.test(dt))
-        return dt;
-    return dt + "Z";
-}
+import { DATETIME_DESC, TIMEZONE_PROPERTY, localToUtcIso } from "../datetime.js";
 registerTool({
     name: "human_design_bodygraph",
     description: "Generate a Human Design Bodygraph image (SVG) from a birth datetime (UTC). " +
@@ -16,16 +11,19 @@ registerTool({
         "Returns a native SVG that Claude displays inline. Use format='png' to opt into raster output (requires server-side rasterizer).\n\n" +
         "For a user-facing interactive bodygraph explorer, use explore_human_design instead.\n\n" +
         "CREDIT COST: 2 credits per call.\n\n" +
-        "EXAMPLE: Generate a bodygraph for someone born April 15, 1990 at 19:30 UTC:\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" +
+        "EXAMPLE (already in UTC):\n" +
         "  datetime='1990-04-15T19:30:00Z'",
     inputSchema: {
         type: "object",
         properties: {
             datetime: {
                 type: "string",
-                description: "ISO 8601 birth datetime in UTC, e.g. '1990-04-15T19:30:00Z'. " +
-                    "Human Design chart calculation is time-sensitive — accuracy to the minute matters.",
+                description: DATETIME_DESC +
+                    " Human Design is time-sensitive — accuracy to the minute matters.",
             },
+            timezone: TIMEZONE_PROPERTY,
             style: {
                 type: "string",
                 enum: ["light", "dark", "mono"],
@@ -46,7 +44,7 @@ registerTool({
     handler: async (args) => {
         validateRequired(args, ["datetime"]);
         const body = {
-            birth_datetime_utc: ensureTimezone(args.datetime),
+            birth_datetime_utc: localToUtcIso("datetime", args.datetime, args.timezone),
         };
         const format = pickEnum(args.format, ["svg", "png"]) || "svg";
         const style = pickEnum(args.style, ["light", "dark", "mono"]);