@openephemeris/mcp-server 3.24.0 → 4.1.0

package/dist/tools/specialized/ephemeris_extended.js

@@ -1,6 +1,7 @@
-import { registerTool, validateRequired } from "../index.js";
+import { registerTool, validateRequired, validateCoordinates } 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,16 @@ 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" +
-        "Optionally pass planet_id (0-9) to query a single planet.",
+        "✅  Answers 'is X retrograde?' at ONE instant. For WHEN a planet turns retrograde or " +
+        "direct, or whether it stations anywhere in a date range, use electional_station_tracker.\n\n" +
+        "CREDIT COST: for a single planet — the common case — pass planet_id (0-9, e.g. 2 for " +
+        "Mercury): 1 credit. Omitting planet_id runs the all-planets sweep: 10 credits (the " +
+        "backend bills one credit per body and this fans out to 10).",
     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 +113,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 +148,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 +161,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,
         });
@@ -161,13 +170,28 @@ registerTool({
 // POST /ephemeris/fixed-stars
 registerTool({
     name: "ephemeris_fixed_stars",
-    description: "Calculate positions of fixed stars and conjunctions to natal planets. " +
-        "Returns star longitude, magnitude, and any planets within orb.\n\n" +
+    description: "Fixed star positions (ecliptic longitude, magnitude) and the chart points conjunct them. " +
+        "Always scans the ten traditional planets.\n\n" +
+        "⚠️  ANGLES REQUIRE A LOCATION: 'what stars are on my Ascendant?' is only answerable with " +
+        "latitude AND longitude — ASC/MC/DSC/IC depend on place, not just time. Supply both and the " +
+        "four angles join the scan; omit them and the result covers PLANETS ONLY. Each conjunction " +
+        "is tagged point_type 'planet' or 'angle', and the angle longitudes used come back in " +
+        "`angles`, so never report a planetary hit as an Ascendant hit.\n\n" +
         "CREDIT COST: 1 credit per call.",
     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 in decimal degrees. Required (with longitude) to scan the angles. " +
+                    "Resolve from a place name with location_search; never recall coordinates from memory.",
+            },
+            longitude: {
+                type: "number",
+                description: "Observer longitude in decimal degrees. Required (with latitude) to scan the angles.",
+            },
             star_names: {
                 type: "array",
                 items: { type: "string" },
@@ -182,45 +206,26 @@ registerTool({
     annotations: { title: "Fixed Stars", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, ["datetime"]);
+        // A lone latitude would silently drop the angles from the scan, which is
+        // the exact failure this tool exists to avoid — reject it instead.
+        validateCoordinates(args, "latitude", "longitude");
         const body = {
-            date_time: { iso: args.datetime },
+            date_time: { iso: localToUtcIso("datetime", args.datetime, args.timezone) },
         };
+        if (args.latitude != null)
+            body.latitude = args.latitude;
+        if (args.longitude != null)
+            body.longitude = args.longitude;
         if (args.star_names)
             body.star_names = args.star_names;
         if (args.orb != null)
             body.orb = args.orb;
-        const raw = await getActiveClient().post("/ephemeris/fixed-stars", body);
-        // Bug 6 workaround: backend returns longitude as degrees-within-sign (0–30),
-        // not full ecliptic longitude (0–360). Compute full_longitude from sign name.
-        const SIGN_ORDER = {
-            Aries: 0, Taurus: 1, Gemini: 2, Cancer: 3, Leo: 4, Virgo: 5,
-            Libra: 6, Scorpio: 7, Sagittarius: 8, Capricorn: 9, Aquarius: 10, Pisces: 11,
-        };
-        function enrichStar(star) {
-            if (!star || typeof star !== "object")
-                return star;
-            const signLon = typeof star.longitude === "number" ? star.longitude : 0;
-            const signName = star.sign ?? star.sign_name ?? "";
-            const signIndex = SIGN_ORDER[signName] ?? -1;
-            const fullLon = signIndex >= 0 ? signIndex * 30 + signLon : signLon;
-            return {
-                ...star,
-                longitude: fullLon, // ecliptic longitude 0–360
-                sign_longitude: signLon, // original within-sign degrees preserved
-                sign: signName || undefined,
-            };
-        }
-        // Normalise the response — backend may return array or { stars: [...] }
-        if (Array.isArray(raw)) {
-            return raw.map(enrichStar);
-        }
-        if (raw && typeof raw === "object") {
-            const starsKey = ["stars", "data", "fixed_stars", "results"].find((k) => Array.isArray(raw[k]));
-            if (starsKey) {
-                return { ...raw, [starsKey]: raw[starsKey].map(enrichStar) };
-            }
-        }
-        return raw;
+        // No response rewriting: /ephemeris/fixed-stars returns full ecliptic
+        // longitude (0–360) directly. It previously returned degrees-within-sign,
+        // and the workaround here reconstructed the full value from a `sign`
+        // field the endpoint never actually sent — so it was inert. Both the
+        // backend bug and the dead workaround are gone.
+        return await getActiveClient().post("/ephemeris/fixed-stars", body);
     },
 });
 // POST /ephemeris/hermetic-lots
@@ -232,7 +237,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 +250,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 +265,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 +278,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"]);

package/dist/tools/specialized/hd_cycles.js

@@ -1,16 +1,7 @@
 import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
-/**
- * Ensure a datetime string has a timezone offset for Go's time.Time parsing.
- */
-function ensureTimezone(dt) {
-    if (!dt)
-        return dt;
-    if (/[Zz]$/.test(dt) || /[+-]\d{2}:\d{2}$/.test(dt) || /[+-]\d{4}$/.test(dt))
-        return dt;
-    return dt + "Z";
-}
+import { DATETIME_DESC, TIMEZONE_PROPERTY, localToUtcIso } from "../datetime.js";
 registerTool({
     name: "hd_planetary_return",
     description: "Calculate a Human Design planetary return chart — full HD chart " +
@@ -35,8 +26,9 @@ registerTool({
             },
             datetime: {
                 type: "string",
-                description: "ISO 8601 birth datetime in UTC, e.g. '1990-04-15T19:30:00Z'.",
+                description: DATETIME_DESC,
             },
+            timezone: TIMEZONE_PROPERTY,
             return_year: {
                 type: "integer",
                 description: "Year to find the return near (e.g. 2020 for a Saturn return at ~age 29).",
@@ -57,7 +49,7 @@ registerTool({
         return await getActiveClient().request("POST", "/human-design/cycles/return", {
             data: {
                 planet: args.planet,
-                birth_datetime_utc: ensureTimezone(args.datetime),
+                birth_datetime_utc: localToUtcIso("datetime", args.datetime, args.timezone),
                 return_year: args.return_year,
                 format: args.format,
                 include_chiron: args.include_chiron,
@@ -87,8 +79,9 @@ registerTool({
             },
             datetime: {
                 type: "string",
-                description: "ISO 8601 birth datetime in UTC, e.g. '1983-07-15T12:00:00Z'.",
+                description: DATETIME_DESC,
             },
+            timezone: TIMEZONE_PROPERTY,
             target_year: {
                 type: "integer",
                 description: "Year to search for the opposition near.",
@@ -109,7 +102,7 @@ registerTool({
         return await getActiveClient().request("POST", "/human-design/cycles/opposition", {
             data: {
                 planet: args.planet,
-                birth_datetime_utc: ensureTimezone(args.datetime),
+                birth_datetime_utc: localToUtcIso("datetime", args.datetime, args.timezone),
                 target_year: args.target_year,
                 format: args.format,
                 include_chiron: args.include_chiron,

package/dist/tools/specialized/hd_group.js

@@ -1,25 +1,31 @@
 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";
 // POST /human-design/composite — OE-027
 registerTool({
     name: "human_design_composite",
     description: "Calculate a Human Design composite chart for two people. Merges both bodygraphs " +
         "to show shared channels, authority dynamics, and relationship type.\n\n" +
         "CREDIT COST: 4 credits per call.\n\n" +
-        "EXAMPLE:\n" +
-        "  person_a_datetime='1990-04-15T14:30:00Z', person_b_datetime='1988-09-22T08:15:00Z'",
+        "EXAMPLE (local times + zones):\n" +
+        "  person_a_datetime='1990-04-15T14:30:00', person_a_timezone='America/Chicago',\n" +
+        "  person_b_datetime='1988-09-22T08:15:00', person_b_timezone='America/Los_Angeles'\n" +
+        "EXAMPLE (already in UTC):\n" +
+        "  person_a_datetime='1990-04-15T19:30:00Z', person_b_datetime='1988-09-22T15:15:00Z'",
     inputSchema: {
         type: "object",
         properties: {
             person_a_datetime: {
                 type: "string",
-                description: "Person A birth datetime as ISO 8601 UTC (e.g. '1990-04-15T14:30:00Z').",
+                description: DATETIME_DESC,
             },
+            person_a_timezone: timezoneProperty("Person A's birth location"),
             person_b_datetime: {
                 type: "string",
-                description: "Person B birth datetime as ISO 8601 UTC.",
+                description: DATETIME_DESC,
             },
+            person_b_timezone: timezoneProperty("Person B's birth location", "America/Los_Angeles"),
             format: {
                 type: "string",
                 enum: ["json", "llm"],
@@ -35,10 +41,10 @@ registerTool({
         validateRequired(args, ["person_a_datetime", "person_b_datetime"]);
         const body = {
             subject_1: {
-                birth_datetime_utc: args.person_a_datetime,
+                birth_datetime_utc: localToUtcIso("person_a_datetime", args.person_a_datetime, args.person_a_timezone, "person_a_timezone"),
             },
             subject_2: {
-                birth_datetime_utc: args.person_b_datetime,
+                birth_datetime_utc: localToUtcIso("person_b_datetime", args.person_b_datetime, args.person_b_timezone, "person_b_timezone"),
             },
         };
         if (args.format)
@@ -52,12 +58,12 @@ registerTool({
     description: "Calculate a Human Design Penta (group) chart for 3-5 people. Shows functional " +
         "attributes, leadership dynamics, channels, redundancies, and a group stability score.\n\n" +
         "CREDIT COST: 6 credits per call.\n\n" +
-        "EXAMPLE (3 people):\n" +
+        "EXAMPLE (3 people — each datetime states its zone):\n" +
         "  group_name='Team Alpha',\n" +
         "  members=[\n" +
-        "    {id: 'alice', name: 'Alice', datetime: '1990-04-15T14:30:00Z'},\n" +
-        "    {id: 'bob',   name: 'Bob',   datetime: '1988-09-22T08:15:00Z'},\n" +
-        "    {id: 'carol', name: 'Carol', datetime: '1995-01-10T11:00:00Z'}\n" +
+        "    {id: 'alice', name: 'Alice', datetime: '1990-04-15T14:30:00', timezone: 'America/Chicago'},\n" +
+        "    {id: 'bob',   name: 'Bob',   datetime: '1988-09-22T15:15:00Z'},\n" +
+        "    {id: 'carol', name: 'Carol', datetime: '1995-01-10T11:00:00+00:00'}\n" +
         "  ]",
     inputSchema: {
         type: "object",
@@ -73,7 +79,8 @@ registerTool({
                     properties: {
                         id: { type: "string", description: "Unique member ID." },
                         name: { type: "string", description: "Member's name." },
-                        datetime: { type: "string", description: "Birth datetime as ISO 8601 UTC." },
+                        datetime: { type: "string", description: DATETIME_DESC },
+                        timezone: timezoneProperty("this member's birth location"),
                     },
                     required: ["id", "name", "datetime"],
                 },
@@ -94,11 +101,11 @@ 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) => ({
+        const members = args.members.map((m, i) => ({
             id: m.id,
             name: m.name,
             birth_data: {
-                birth_datetime_utc: m.datetime,
+                birth_datetime_utc: localToUtcIso(`members[${i}].datetime`, m.datetime, m.timezone, `members[${i}].timezone`),
             },
         }));
         const body = {

package/dist/tools/specialized/human_design.js

@@ -1,18 +1,7 @@
 import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_IMAGE_AND_JSON } from "../output-schemas.js";
-/**
- * Ensure a datetime string has a timezone offset for Go's time.Time parsing.
- * Go's encoding/json only accepts RFC 3339 (must have Z or +HH:MM offset).
- */
-function ensureTimezone(dt) {
-    if (!dt)
-        return dt;
-    // Already has timezone indicator
-    if (/[Zz]$/.test(dt) || /[+-]\d{2}:\d{2}$/.test(dt) || /[+-]\d{4}$/.test(dt))
-        return dt;
-    return dt + "Z";
-}
+import { DATETIME_DESC, TIMEZONE_PROPERTY, localToUtcIso } from "../datetime.js";
 registerTool({
     name: "human_design_chart",
     description: "Calculate a full Human Design I Ching hexagram chart from birth data. Returns the person's Type " +
@@ -23,19 +12,24 @@ registerTool({
         "CREDIT COST: 2 credits per call.\n\n" +
         "Human Design uses two calculation moments: the birth time (Personality) and ~88° of Sun motion " +
         "before birth (~3 months prior, the Design calculation). The API handles this automatically.\n\n" +
-        "IMPORTANT: The datetime should be in UTC. If you have local birth time, convert to UTC first.\n\n" +
-        "EXAMPLE: Get the Human Design chart for someone born April 15, 1990 at 7:30 PM UTC:\n" +
+        "The datetime must state its zone — pass an offset/'Z', or pass local time plus timezone. " +
+        "A zone-less datetime is rejected rather than assumed to be UTC: Human Design is minute-sensitive, " +
+        "and an hour of error changes the Profile and the Design Sun line.\n\n" +
+        "EXAMPLE (local birth time + zone): someone born 15 April 1990 at 14:30 in 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', latitude=41.8781, longitude=-87.6298",
     inputSchema: {
         type: "object",
         properties: {
             datetime: {
                 type: "string",
-                description: "ISO 8601 birth datetime in UTC, e.g. '1990-04-15T19:30:00Z'. Must include 'Z' or timezone offset.",
+                description: DATETIME_DESC,
             },
+            timezone: TIMEZONE_PROPERTY,
             latitude: {
                 type: "number",
-                description: "Latitude of birth location in decimal degrees (positive = North).",
+                description: "Latitude of birth location in decimal degrees (positive = North). Resolve from a place name with location_search; never recall coordinates from memory.",
             },
             longitude: {
                 type: "number",
@@ -71,7 +65,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),
         };
         if (args.latitude != null)
             body.latitude = args.latitude;

package/dist/tools/specialized/moon.js

@@ -1,12 +1,15 @@
 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";
 registerTool({
     name: "ephemeris_moon_phase",
-    description: "Get the Moon's current phase angle, illumination, and void-of-course status AT a specific " +
-        "point in time. Returns phase name (New, Waxing Crescent, First Quarter, etc.), exact angle, " +
-        "illumination %, and next void-of-course period.\n\n" +
-        "⚠️  THIS TOOL ANSWERS: 'What phase is the moon in right now (or at a given datetime)?'\n" +
+    description: "Get the Moon's current phase angle, illumination, sign and void-of-course status AT a " +
+        "specific point in time. Returns phase name (New, Waxing Crescent, First Quarter, etc.), exact " +
+        "angle, illumination %, the zodiac sign and degree the Moon occupies, and next void-of-course " +
+        "period.\n\n" +
+        "⚠️  THIS TOOL ANSWERS: 'What phase is the moon in right now (or at a given datetime)?' and " +
+        "'What sign is the moon in?'\n" +
         "❌  THIS TOOL DOES NOT ANSWER: 'When is the next new moon / full moon?'\n" +
         "→   For upcoming phase DATES use ephemeris_next_lunar_phase instead.\n\n" +
         "For a user-facing interactive moon-phase dial, use explore_moon_phase instead.\n\n" +
@@ -21,8 +24,11 @@ registerTool({
         properties: {
             datetime: {
                 type: "string",
-                description: "ISO 8601 datetime to query. If omitted, returns the current live moon phase (UTC now).",
+                description: "ISO 8601 datetime to query, stating its zone ('2026-03-20T12:00:00Z' or " +
+                    "'2026-03-20T08:00:00-04:00'), or a local time together with `timezone`. " +
+                    "If omitted, returns the current live moon phase (UTC now).",
             },
+            timezone: TIMEZONE_PROPERTY,
             latitude: {
                 type: "number",
                 description: "Observer latitude (optional, used for local void-of-course calculations).",
@@ -42,7 +48,9 @@ registerTool({
         const params = {};
         // Backend requires datetime even though the schema marks it optional.
         // Default to current UTC time when caller omits it.
-        params.datetime = args.datetime ?? new Date().toISOString();
+        params.datetime = args.datetime
+            ? localToUtcIso("datetime", args.datetime, args.timezone)
+            : new Date().toISOString();
         if (args.latitude != null)
             params.latitude = args.latitude;
         if (args.longitude != null)

package/dist/tools/specialized/natal.js

@@ -1,8 +1,7 @@
 import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_IMAGE_AND_JSON } 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";
 /** Map human-readable house system names to standard single-letter codes */
 const HOUSE_SYSTEM_MAP = {
     placidus: "P", whole_sign: "W", equal: "E", koch: "K",
@@ -17,8 +16,9 @@ registerTool({
         "essential dignities, retrograde status, house system data, and major aspect grid. Asteroids are automatically included. " +
         "Returns raw JSON. For a user-facing visual chart, use explore_natal_chart instead.\n\n" +
         "CREDIT COST: 1 credit per call.\n\n" +
-        "EXAMPLE: Calculate the natal chart for someone born April 15, 1990 at 2:30 PM 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 — pass the local time and name the zone:\n" +
+        "  datetime='1990-04-15T14:30:00', timezone='America/Chicago', latitude=41.8781, longitude=-87.6298\n" +
+        "Equivalently, put the zone on the datetime: datetime='1990-04-15T14:30:00-05:00' (or the UTC instant '1990-04-15T19:30:00Z').",
     inputSchema: {
         type: "object",
         properties: {
@@ -26,13 +26,10 @@ 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).",
+                description: "Geographic latitude of birth location in decimal degrees (positive = North). Resolve from a place name with location_search; never recall coordinates from memory.",
             },
             longitude: {
                 type: "number",
@@ -79,6 +76,7 @@ registerTool({
     annotations: { title: "Natal Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, ["datetime", "latitude", "longitude"]);
+        assertZonedDatetime("datetime", args.datetime, args.timezone);
         const body = {
             subject: {
                 name: "MCP Request",

package/dist/tools/specialized/progressed.js

@@ -1,27 +1,27 @@
 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, WINDOW_DATE_DESC, assertZonedDatetime } from "../datetime.js";
 registerTool({
     name: "ephemeris_progressed_chart",
     description: "Calculate a Secondary Progressed (or Solar Arc / Tertiary) chart. " +
         "Advances the natal chart symbolically — 1 day = 1 year (secondary), or using solar arc motion. " +
         "Returns progressed planet positions, house cusps, aspects, and retrograde status.\n\n" +
         "CREDIT COST: 1 credit per call.\n\n" +
-        "EXAMPLE: Secondary progressions for someone born 1985-06-21, progressed to 2026-01-01:\n" +
-        "  birth_datetime='1985-06-21T14:00:00', birth_latitude=51.5, birth_longitude=-0.12,\n" +
-        "  target_datetime='2026-01-01', method='secondary'",
+        "EXAMPLE: Secondary progressions for someone born 1985-06-21 at 2:00 PM in London, progressed to 2026-01-01:\n" +
+        "  birth_datetime='1985-06-21T14:00:00', timezone='Europe/London',\n" +
+        "  birth_latitude=51.5, birth_longitude=-0.12, target_datetime='2026-01-01', method='secondary'",
     inputSchema: {
         type: "object",
         properties: {
             birth_datetime: {
                 type: "string",
-                description: "ISO 8601 natal birth date/time. MUST include a UTC offset (or 'Z'), " +
-                    "e.g. '1990-05-15T14:30:00-05:00'. A naive datetime (no offset) is " +
-                    "interpreted as UTC and will shift the progressed positions.",
+                description: DATETIME_DESC,
             },
+            timezone: TIMEZONE_PROPERTY,
             birth_latitude: {
                 type: "number",
-                description: "Birth latitude in decimal degrees.",
+                description: "Birth latitude in decimal degrees. Resolve from a place name with location_search; never recall coordinates from memory.",
             },
             birth_longitude: {
                 type: "number",
@@ -29,7 +29,7 @@ registerTool({
             },
             target_datetime: {
                 type: "string",
-                description: "Target date to progress the chart to (ISO 8601).",
+                description: "Date to progress the chart to. " + WINDOW_DATE_DESC,
             },
             method: {
                 type: "string",
@@ -63,6 +63,8 @@ registerTool({
     annotations: { title: "Progressed Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, ["birth_datetime", "birth_latitude", "birth_longitude", "target_datetime"]);
+        assertZonedDatetime("birth_datetime", args.birth_datetime, args.timezone);
+        assertZonedDatetime("target_datetime", args.target_datetime);
         const body = {
             subject: {
                 name: "Progressed Subject",
@@ -70,6 +72,8 @@ registerTool({
                 birth_location: {
                     latitude: { decimal: args.birth_latitude },
                     longitude: { decimal: args.birth_longitude },
+                    // The server resolves the IANA zone, so historical DST stays correct.
+                    ...(args.timezone ? { timezone: { iana_name: args.timezone } } : {}),
                 },
             },
             target_datetime: { iso: args.target_datetime },