@openephemeris/mcp-server 3.24.0 → 4.1.0

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

@@ -21,6 +21,7 @@ import { fileURLToPath } from "node:url";
 import { registerTool, SERVER_VERSION } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
+import { DATETIME_DESC, TIMEZONE_PROPERTY } from "../datetime.js";
 // ── Constants ─────────────────────────────────────────────────────────────
 export const CHART_WHEEL_RESOURCE_URI = "ui://openephemeris/chart-wheel";
 export const CHART_WHEEL_MIME_TYPE = "text/html;profile=mcp-app";
@@ -81,6 +82,10 @@ const HOUSE_SYSTEM_MAP = {
     placidus: "P", whole_sign: "W", equal: "E", koch: "K",
     campanus: "C", regiomontanus: "R",
 };
+/** "whole_sign" → "Whole Sign" for display in text summaries. */
+function prettyHouseSystem(hs) {
+    return hs.split("_").map(capitalize).join(" ");
+}
 /** Build the nested request body expected by /ephemeris/natal-chart (POST). */
 function buildNatalBody(datetime, lat, lon, houseSystem, timezone) {
     const body = {
@@ -111,23 +116,16 @@ registerTool({
         "CREDIT COST: 1 credit per call.\n\n" +
         "Supports house system switching (Placidus, Whole Sign, Equal, Koch). " +
         "The chart is computed using NASA JPL DE440 ephemerides for sub-arcsecond precision. " +
-        "Use this instead of ephemeris_chart_wheel for a richer, interactive experience in " +
-        "MCP Apps-capable hosts (Claude Desktop). Falls back to static SVG in other hosts.",
+        "Renders interactively in MCP Apps-capable hosts (Claude Desktop) and falls back to " +
+        "static SVG in other hosts.",
     inputSchema: {
         type: "object",
         properties: {
-            datetime: {
-                type: "string",
-                description: "ISO 8601 datetime string, e.g. '1990-04-15T14:30:00'. " +
-                    "Include timezone offset if known, e.g. '1990-04-15T14:30:00-05:00'.",
-            },
-            timezone: {
-                type: "string",
-                description: "IANA timezone name (e.g. 'America/New_York'). Used if datetime has no UTC offset.",
-            },
+            datetime: { type: "string", description: DATETIME_DESC },
+            timezone: TIMEZONE_PROPERTY,
             latitude: {
                 type: "number",
-                description: "Birth latitude in decimal degrees (positive = North).",
+                description: "Birth latitude in decimal degrees (positive = North). Resolve from a place name with location_search; never recall coordinates from memory.",
             },
             longitude: {
                 type: "number",
@@ -135,7 +133,7 @@ registerTool({
             },
             location: {
                 type: "string",
-                description: "Location name for display only (e.g. 'New York, NY').",
+                description: "Location name for display only (e.g. 'New York, NY'). This is a caption, NOT a geocoder — it does not set the chart location. Supply latitude/longitude too (resolve them with location_search), or the chart is computed at 0N 0E.",
             },
             house_system: {
                 type: "string",
@@ -190,7 +188,7 @@ registerTool({
         // source of the ~90 second blocking delay.
         const chartData = await client.post("/ephemeris/natal-chart", natalBody);
         // Build human-readable summary for the LLM context
-        const summary = buildChartSummary(chartData, String(args.location ?? `${lat}, ${lon}`));
+        const summary = buildChartSummary(chartData, String(args.location ?? `${lat}, ${lon}`), houseSystem);
         // Build the UI payload (planets normalised to array, server aspects mapped)
         const modelPayload = buildModelPayload(chartData, {
             datetime,
@@ -343,8 +341,8 @@ registerTool({
     inputSchema: {
         type: "object",
         properties: {
-            datetime: { type: "string", description: "ISO 8601 natal datetime string" },
-            timezone: { type: "string", description: "IANA timezone name (e.g. 'America/New_York')" },
+            datetime: { type: "string", description: DATETIME_DESC },
+            timezone: TIMEZONE_PROPERTY,
             latitude: { type: "number", description: "Birth latitude in decimal degrees (positive = North)" },
             longitude: { type: "number", description: "Birth longitude in decimal degrees (positive = East)" },
             location: { type: "string", description: "Location name for display only (e.g. 'New York, NY')" },
@@ -360,7 +358,7 @@ registerTool({
             },
             target_datetime: {
                 type: "string",
-                description: "ISO 8601 target datetime string. Reguired for solar_return or progressed calculations."
+                description: "Target datetime. Required for solar_return or progressed calculations. " + DATETIME_DESC
             }
         },
         required: ["datetime", "latitude", "longitude", "house_system"],
@@ -383,7 +381,9 @@ registerTool({
             requestBody.configuration.target_datetime = { iso: args.target_datetime ?? datetime };
         }
         else if (chartType === "progressed") {
-            endpoint = "/predictive/progressed";
+            // openapi.json exposes /ephemeris/progressed — /predictive/progressed
+            // does not exist and 404'd every progressed recalculate in the iframe.
+            endpoint = "/ephemeris/progressed";
             requestBody.configuration.target_datetime = { iso: args.target_datetime ?? datetime };
             requestBody.configuration.method = "secondary";
         }
@@ -560,7 +560,7 @@ function buildModelPayload(chartData, birthParams, houseSystem, svgBase, bodyFil
         house_system: houseSystem,
     };
 }
-function buildChartSummary(data, location) {
+function buildChartSummary(data, location, houseSystem) {
     // The natal API returns planets as a keyed object { sun: {...}, moon: {...} }.
     // Normalise to an array before processing.
     const raw = data.planets ?? {};
@@ -621,7 +621,8 @@ function buildChartSummary(data, location) {
     const strongestNote = strongest
         ? `Closest aspect: ${capitalize(strongest.planet1)} ${strongest.type} ${capitalize(strongest.planet2)} (${strongest.orb.toFixed(1)}° orb)`
         : "";
-    const enrichment = [sectNote, domElement ? `Dominant element: ${domElement[0]} (${domElement[1]})` : "", strongestNote]
+    const housesNote = houseSystem ? `Houses: ${prettyHouseSystem(houseSystem)}` : "";
+    const enrichment = [housesNote, sectNote, domElement ? `Dominant element: ${domElement[0]} (${domElement[1]})` : "", strongestNote]
         .filter(Boolean).join(" · ");
     return (`**Natal Chart — ${location}**\n\n` +
         (enrichment ? `${enrichment}\n\n` : "") +

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

@@ -1,9 +1,95 @@
 import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
+/**
+ * The UTC offset of an IANA zone is a function of place AND date: 1987 US DST
+ * rules are not today's rules, and America/Chicago ran on CDT through the whole
+ * of January 1974. A bare zone name is therefore not enough to turn a local
+ * birth time into an instant — the caller needs the offset *on the birth date*.
+ *
+ * We resolve it here from Node's bundled IANA tzdata rather than by calling
+ * `/timezone/offset`, for two reasons:
+ *   1. Credits meter per URL path, so resolving N suggestions server-side would
+ *      cost N extra credits per search. Local resolution costs nothing.
+ *   2. Node's ICU tzdata and the Go sidecar's tzdata agree on every historical
+ *      discriminator we test (see test/location-tools.test.ts), so there is no
+ *      accuracy argument for the round trip.
+ *
+ * The offset is evaluated at 12:00 **local** time on the given date. DST
+ * transitions happen around 02:00 local, so local noon is unambiguous for every
+ * real zone — this avoids both the "which side of the boundary" problem and the
+ * date-rollover problem that evaluating at 12:00 UTC would create for zones at
+ * extreme offsets (e.g. Pacific/Kiritimati at +14).
+ */
+function offsetAtLocalNoon(timezone, date) {
+    const m = /^(\d{4})-(\d{2})-(\d{2})/.exec(String(date).trim());
+    if (!m || !timezone)
+        return null;
+    const [year, month, day] = [Number(m[1]), Number(m[2]), Number(m[3])];
+    try {
+        // Offset (in ms) that must be ADDED to a UTC instant to get local wall time.
+        const offsetMsAt = (utcMs) => {
+            const parts = new Intl.DateTimeFormat("en-US", {
+                timeZone: timezone,
+                year: "numeric", month: "2-digit", day: "2-digit",
+                hour: "2-digit", minute: "2-digit", second: "2-digit",
+                hour12: false,
+            }).formatToParts(new Date(utcMs));
+            const get = (t) => Number(parts.find((p) => p.type === t)?.value ?? 0);
+            const wallMs = Date.UTC(get("year"), get("month") - 1, get("day"), get("hour") % 24, get("minute"), get("second"));
+            return wallMs - utcMs;
+        };
+        // Find the UTC instant corresponding to 12:00 local on `date`. Two passes
+        // settle the fixed point (the first guess can land on the wrong side of a
+        // transition; noon never sits close enough to one for a third to matter).
+        const wantWallMs = Date.UTC(year, month - 1, day, 12, 0, 0);
+        let utcMs = wantWallMs - offsetMsAt(wantWallMs);
+        utcMs = wantWallMs - offsetMsAt(utcMs);
+        const offsetMinutes = offsetMsAt(utcMs) / 60000;
+        if (!Number.isFinite(offsetMinutes))
+            return null;
+        // DST flag. The long zone name is tzdata's own answer and is the only
+        // reliable source: comparing against a January/July baseline gets 1974
+        // wrong, because the US observed DST for the WHOLE of that year, so
+        // both bracket months are daylight time and the comparison reports
+        // "not DST" for a date that genuinely was. Locale is pinned to en-US so
+        // the wording is stable.
+        let isDst;
+        const longName = new Intl.DateTimeFormat("en-US", { timeZone: timezone, timeZoneName: "long" })
+            .formatToParts(new Date(utcMs))
+            .find((p) => p.type === "timeZoneName")?.value ?? "";
+        if (/daylight|summer/i.test(longName)) {
+            isDst = true;
+        }
+        else if (/standard/i.test(longName)) {
+            isDst = false;
+        }
+        else {
+            // Zone has no localized name (Intl fell back to "GMT+11"). Bracket the
+            // year instead: the smaller of the January and July offsets is standard
+            // time in either hemisphere.
+            const janOffset = offsetMsAt(Date.UTC(year, 0, 15, 12, 0, 0)) / 60000;
+            const julOffset = offsetMsAt(Date.UTC(year, 6, 15, 12, 0, 0)) / 60000;
+            isDst = offsetMinutes > Math.min(janOffset, julOffset);
+        }
+        const sign = offsetMinutes < 0 ? "-" : "+";
+        const abs = Math.abs(offsetMinutes);
+        const hh = String(Math.floor(abs / 60)).padStart(2, "0");
+        const mm = String(Math.round(abs % 60)).padStart(2, "0");
+        return {
+            utcOffsetAtDate: `${sign}${hh}:${mm}`,
+            utcOffsetMinutes: offsetMinutes,
+            isDst,
+        };
+    }
+    catch {
+        // Unknown/invalid zone — the caller still gets the IANA name back.
+        return null;
+    }
+}
 registerTool({
     name: "location_search",
-    description: "App-only tool for getting location autocomplete suggestions. CREDIT COST: 1 credit per call. Returns display name, region (state/province), latitude, longitude, and IANA timezone. Optional bias params (country/region/near) improve ranking; a trailing \"City, ST\" qualifier in the query is also honored.",
+    description: "Resolve a place name to coordinates and IANA timezone — use this first whenever a user gives a birth city rather than latitude/longitude. NEVER recall coordinates from memory; always resolve them here. CREDIT COST: 1 credit per call. Returns display name, region (state/province), latitude, longitude, and IANA timezone. Pass the birth date as `date` to also get `utcOffsetAtDate`, the historically-correct UTC offset for that place on that date (1987 DST rules differ from today's) — this costs no extra credits. When the result is `ambiguous` (several places share the name, e.g. \"portland\"), ASK the user which one they mean rather than assuming the first. Optional bias params (country/region/near) improve ranking; a trailing \"City, ST\" qualifier in the query is also honored.",
     inputSchema: {
         type: "object",
         properties: {
@@ -27,14 +113,22 @@ registerTool({
                 type: "string",
                 description: "Optional 'lat,lon' proximity hint (e.g. '37.77,-122.42') to bias ranking toward nearby places.",
             },
+            date: {
+                type: "string",
+                description: "Optional birth/event date as 'YYYY-MM-DD'. When given, each suggestion also carries utcOffsetAtDate / utcOffsetMinutes / isDst — the UTC offset that actually applied at that place on that date, using historical DST rules. Free: adds no API call and no credits.",
+            },
         },
         required: ["query"],
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
+    annotations: { title: "Location Search", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    // Model-visible as well as app-visible: without this the model had no
+    // geocoding tool and every prompt had to route through
+    // `dev_read_api /location/autocomplete` instead.
     _meta: {
         ui: {
-            visibility: ["app"],
+            visibility: ["model", "app"],
         },
     },
     handler: async (args) => {
@@ -48,41 +142,96 @@ registerTool({
         const raw = (await getActiveClient().request("GET", "/location/autocomplete", { params }));
         // Map the API's snake_case response to the camelCase shape the app UI consumes.
         const list = Array.isArray(raw?.suggestions) ? raw.suggestions : [];
-        const suggestions = list.map((s) => ({
-            displayName: s.display_name,
-            shortName: s.short_name,
-            region: s.region,
-            countryCode: s.country_code,
-            placeId: s.place_id,
-            latitude: s.latitude,
-            longitude: s.longitude,
-            timezone: s.timezone,
-        }));
-        return { suggestions };
+        const date = args.date != null && String(args.date).trim() !== "" ? String(args.date).trim() : null;
+        const suggestions = list.map((s) => {
+            const mapped = {
+                displayName: s.display_name,
+                shortName: s.short_name,
+                region: s.region,
+                countryCode: s.country_code,
+                placeId: s.place_id,
+                latitude: s.latitude,
+                longitude: s.longitude,
+                timezone: s.timezone,
+            };
+            if (date && s.timezone)
+                Object.assign(mapped, offsetAtLocalNoon(s.timezone, date) ?? {});
+            return mapped;
+        });
+        // Ambiguity signal. "portland" really does match Oregon, Maine, Texas,
+        // England, ... — an agent that silently takes suggestions[0] produces a
+        // chart nothing downstream can detect as wrong.
+        //
+        // What matters is *rivals for the top hit*, not the row count. The
+        // endpoint pads toward its limit of 8, so "dallas texas" comes back with
+        // eight rows (Dallas GA, Dallas OR, ...) even though the query is already
+        // unambiguous — counting rows would flag essentially every search.
+        const norm = (v) => String(v ?? "").trim().toLowerCase();
+        const top = suggestions[0];
+        const rivals = top ? suggestions.filter((s) => norm(s.shortName) === norm(top.shortName)) : [];
+        // If the caller already pinned the place — "dallas texas", "portland uk" —
+        // the top hit is what they asked for and there is nothing to ask about.
+        const q = norm(args.query);
+        const qTokens = new Set(q.split(/[^a-z0-9]+/).filter(Boolean));
+        const qualified = !!top &&
+            ((norm(top.region) !== "" && q.includes(norm(top.region))) ||
+                (norm(top.countryCode) !== "" && qTokens.has(norm(top.countryCode))));
+        const ambiguous = rivals.length > 1 && !qualified;
+        return {
+            suggestions,
+            matchCount: suggestions.length,
+            ambiguous,
+            ...(ambiguous
+                ? {
+                    disambiguationHint: `"${args.query}" matches ${rivals.length} places of that name (${rivals
+                        .slice(0, 4)
+                        .map((s) => s.region ?? s.countryCode)
+                        .filter(Boolean)
+                        .join(", ")}${rivals.length > 4 ? ", ..." : ""}). Confirm which one the user means before building a chart — do not assume the first result.`,
+                }
+                : {}),
+        };
     },
 });
 registerTool({
     name: "timezone_resolve",
-    description: "App-only tool for resolving IANA timezone by latitude and longitude. CREDIT COST: 1 credit per call.",
+    description: "Resolve the IANA timezone for a latitude/longitude pair. Use when you have coordinates but need the timezone to interpret a local birth time. Pass `date` to also get the historically-correct UTC offset that applied on that date. CREDIT COST: 1 credit per call. If you are starting from a place name rather than coordinates, use location_search instead — it returns the timezone too, in the same single call.",
     inputSchema: {
         type: "object",
         properties: {
             latitude: { type: "number" },
             longitude: { type: "number" },
+            date: {
+                type: "string",
+                description: "Optional birth/event date as 'YYYY-MM-DD'. When given, the result also carries utcOffsetAtDate / utcOffsetMinutes / isDst for that date under that zone's historical DST rules. Free: adds no API call and no credits.",
+            },
         },
         required: ["latitude", "longitude"],
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
+    annotations: { title: "Timezone Resolve", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     _meta: {
         ui: {
-            visibility: ["app"],
+            visibility: ["model", "app"],
         },
     },
     handler: async (args) => {
         validateRequired(args, ["latitude", "longitude"]);
-        return await getActiveClient().request("GET", "/timezone/lookup", {
-            params: { lat: args.latitude.toString(), lon: args.longitude.toString() },
-        });
+        // /timezone/lookup is registered POST-only (main.go via api.gen.go) and
+        // takes latitude/longitude in the BODY. This tool used to issue
+        // `GET /timezone/lookup?lat=&lon=`, which the API answered with 405 —
+        // i.e. the tool failed 100% of the time in production.
+        const result = (await getActiveClient().request("POST", "/timezone/lookup", {
+            data: { latitude: args.latitude, longitude: args.longitude },
+        }));
+        const date = args.date != null && String(args.date).trim() !== "" ? String(args.date).trim() : null;
+        const tz = typeof result?.timezone === "string" ? result.timezone : null;
+        if (date && tz) {
+            const offset = offsetAtLocalNoon(tz, date);
+            if (offset)
+                return { ...result, ...offset, date };
+        }
+        return result;
     },
 });

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

@@ -17,6 +17,7 @@ import { fileURLToPath } from "node:url";
 import { registerTool, validateCoordinates, SERVER_VERSION } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
+import { TIMEZONE_PROPERTY, localToUtcIso } from "../datetime.js";
 // ── Constants ─────────────────────────────────────────────────────────────────
 export const MOON_PHASE_RESOURCE_URI = "ui://openephemeris/moon-phase";
 export const MOON_PHASE_MIME_TYPE = "text/html;profile=mcp-app";
@@ -96,7 +97,9 @@ async function computeMoonData(args) {
     validateCoordinates(args, "latitude", "longitude");
     const client = getActiveClient();
     const params = {};
-    params.datetime = args.datetime ?? new Date().toISOString();
+    params.datetime = args.datetime
+        ? localToUtcIso("datetime", String(args.datetime), args.timezone)
+        : new Date().toISOString();
     if (args.latitude != null)
         params.latitude = args.latitude;
     if (args.longitude != null)
@@ -206,8 +209,10 @@ 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 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).",
@@ -272,8 +277,10 @@ registerTool({
         properties: {
             datetime: {
                 type: "string",
-                description: "ISO 8601 datetime to query. If omitted, uses the current live moon phase (UTC now).",
+                description: "ISO 8601 datetime to query, stating its zone ('2026-03-20T12:00:00Z'), or a local " +
+                    "time together with timezone. If omitted, uses the current live moon phase (UTC now).",
             },
+            timezone: TIMEZONE_PROPERTY,
             latitude: {
                 type: "number",
                 description: "Observer latitude (optional, used for local void-of-course calculations).",

package/dist/tools/apps/transit-timeline-app.js

@@ -18,6 +18,7 @@ import { fileURLToPath } from "node:url";
 import { registerTool, validateRequired, SERVER_VERSION } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
+import { DATETIME_DESC, WINDOW_DATE_DESC, timezoneProperty } from "../datetime.js";
 // ── Constants ─────────────────────────────────────────────────────────────────
 export const TRANSIT_TIMELINE_RESOURCE_URI = "ui://openephemeris/transit-timeline";
 export const TRANSIT_TIMELINE_MIME_TYPE = "text/html;profile=mcp-app";
@@ -109,11 +110,12 @@ registerTool({
     inputSchema: {
         type: "object",
         properties: {
-            natal_datetime: { type: "string", description: "ISO 8601 birth datetime for the natal chart." },
-            natal_latitude: { type: "number", description: "Latitude of birth location in decimal degrees." },
+            natal_datetime: { type: "string", description: DATETIME_DESC },
+            natal_timezone: timezoneProperty("the natal birth location"),
+            natal_latitude: { type: "number", description: "Latitude of birth location in decimal degrees. Resolve from a place name with location_search; never recall coordinates from memory." },
             natal_longitude: { type: "number", description: "Longitude of birth location in decimal degrees." },
-            start_date: { type: "string", description: "Start of the transit search window, ISO 8601 date or datetime (e.g. '2026-01-01')." },
-            end_date: { type: "string", description: "End of the transit search window, ISO 8601 date or datetime (e.g. '2026-12-31')." },
+            start_date: { type: "string", description: "Start of the transit search window. " + WINDOW_DATE_DESC },
+            end_date: { type: "string", description: "End of the transit search window. " + WINDOW_DATE_DESC },
             transiting_planets: {
                 type: "array", items: { type: "string" },
                 description: "Transiting planet IDs to search, e.g. ['saturn','jupiter','uranus','pluto','chiron']. Omit to search all outer planets.",

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

@@ -23,6 +23,7 @@ import { fileURLToPath } from "node:url";
 import { registerTool, validateRequired, validateCoordinates, SERVER_VERSION } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
+import { localToUtcIso } from "../datetime.js";
 // ── Constants ─────────────────────────────────────────────────────────────────
 export const VEDIC_CHART_RESOURCE_URI = "ui://openephemeris/vedic-chart";
 export const VEDIC_CHART_MIME_TYPE = "text/html;profile=mcp-app";
@@ -57,50 +58,6 @@ export function getVedicChartBundle() {
 export function clearVedicChartBundleCache() {
     cachedBundle = null;
 }
-// ── Helpers ──────────────────────────────────────────────────────────────────
-/** Ensure datetime has a UTC offset for Go time.Time parsing. */
-function ensureTimezone(dt) {
-    if (!dt)
-        return dt;
-    if (/[Zz]$/.test(dt) || /[+-]\d{2}:\d{2}$/.test(dt))
-        return dt;
-    return dt + "Z";
-}
-/**
- * Convert a local datetime string (no offset) to a UTC ISO 8601 string using
- * the IANA timezone. Mirrors bodygraph-app.ts's localToUtcIso.
- */
-function localToUtcIso(dt, tz) {
-    if (!dt || /[Zz]$/.test(dt) || /[+-]\d{2}:\d{2}$/.test(dt))
-        return ensureTimezone(dt);
-    if (!tz)
-        return dt + "Z";
-    try {
-        const [datePart, timePart = "00:00:00"] = dt.split("T");
-        const [year, month, day] = datePart.split("-").map(Number);
-        const [hour, min, sec = 0] = timePart.split(":").map(Number);
-        const candidateUtcMs = Date.UTC(year, month - 1, day, hour, min, sec);
-        const getOffsetMs = (utcMs) => {
-            const fmtParts = new Intl.DateTimeFormat("en-US", {
-                timeZone: tz,
-                year: "numeric", month: "2-digit", day: "2-digit",
-                hour: "2-digit", minute: "2-digit", second: "2-digit",
-                hour12: false,
-            }).formatToParts(new Date(utcMs));
-            const get = (t) => Number(fmtParts.find((p) => p.type === t)?.value ?? 0);
-            const localizedUtcMs = Date.UTC(get("year"), get("month") - 1, get("day"), get("hour") % 24, get("minute"), get("second"));
-            return utcMs - localizedUtcMs;
-        };
-        const offsetMs1 = getOffsetMs(candidateUtcMs);
-        const correctedUtcMs1 = candidateUtcMs + offsetMs1;
-        const offsetMs2 = getOffsetMs(correctedUtcMs1);
-        const finalUtcMs = candidateUtcMs + offsetMs2;
-        return new Date(finalUtcMs).toISOString();
-    }
-    catch {
-        return dt + "Z";
-    }
-}
 /**
  * Build the compact iframe model from the raw Go /vedic/chart response.
  * The Go response nests ayanamsha/lagna under `metadata` (radians→degrees
@@ -155,7 +112,7 @@ registerTool({
             },
             latitude: {
                 type: "number",
-                description: "Birth latitude in decimal degrees (positive = North).",
+                description: "Birth latitude in decimal degrees (positive = North). Resolve from a place name with location_search; never recall coordinates from memory.",
             },
             longitude: {
                 type: "number",
@@ -163,7 +120,7 @@ registerTool({
             },
             location: {
                 type: "string",
-                description: "Location name for display only (e.g. 'Mumbai, India').",
+                description: "Location name for display only (e.g. 'Mumbai, India'). This is a caption, NOT a geocoder — it does not set the chart location. Supply latitude/longitude too (resolve them with location_search), or the chart is computed at 0N 0E.",
             },
             timezone: {
                 type: "string",
@@ -197,7 +154,7 @@ registerTool({
         validateCoordinates(args, "latitude", "longitude");
         const client = getActiveClient();
         const timezone = args.timezone;
-        const datetime = localToUtcIso(String(args.datetime), timezone);
+        const datetime = localToUtcIso("datetime", String(args.datetime), timezone);
         const lat = Number(args.latitude);
         const lon = Number(args.longitude);
         const ayanamsa = args.ayanamsa;
@@ -250,7 +207,16 @@ registerTool({
     inputSchema: {
         type: "object",
         properties: {
-            datetime: { type: "string" },
+            datetime: {
+                type: "string",
+                description: "ISO 8601 birth datetime stating its zone, or a local time together with timezone. " +
+                    "Must match the value used by explore_vedic_chart or the re-render will show a different chart.",
+            },
+            timezone: {
+                type: "string",
+                description: "IANA timezone name for the birth location (e.g. 'Asia/Kolkata'). Required when datetime " +
+                    "has no 'Z' or ±HH:MM offset — the same value passed to explore_vedic_chart.",
+            },
             latitude: { type: "number" },
             longitude: { type: "number" },
             ayanamsa: { type: "string" },
@@ -267,7 +233,7 @@ registerTool({
     _meta: { ui: { resourceUri: VEDIC_CHART_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const client = getActiveClient();
-        const datetime = ensureTimezone(String(args.datetime));
+        const datetime = localToUtcIso("datetime", String(args.datetime), args.timezone);
         const lat = args.latitude != null ? Number(args.latitude) : undefined;
         const lon = args.longitude != null ? Number(args.longitude) : undefined;
         const ayanamsa = args.ayanamsa;

package/dist/tools/datetime.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The datetime contract, stated once for the whole tool surface.
+ *
+ * A datetime that names a clock time but not a zone does not name an instant.
+ * The API used to read such a value as UTC, so a birth time of 09:01 in Chicago
+ * was computed as 09:01 UTC — five hours early. Every planet keeps its sign at
+ * that error scale, so the answer looked right while the Ascendant was two signs
+ * off and every house placement was wrong.
+ *
+ * The rules, identical here and in the Go engine
+ * (apps/api/go-sidecar/internal/api/handlers/datetime_contract.go):
+ *
+ *   1. A datetime WITH a clock time must carry its zone — either a `Z`/`±HH:MM`
+ *      suffix on the string, or a companion `timezone` argument.
+ *   2. A date-only value ("1987-07-15") has no clock time to be ambiguous about
+ *      and resolves to 12:00 UTC.
+ *   3. Nothing in this layer ever appends a `Z` to a zone-less value. Doing so
+ *      asserts a fact the caller never stated.
+ *
+ * Violations are rejected here rather than at the API so the model gets the
+ * correction immediately and no credit is spent on a chart that is wrong.
+ */
+/** True when `value` states a clock time but not the zone that clock is in. */
+export declare function isNaiveClockTime(value: string): boolean;
+/** True when `value` already carries its own zone. */
+export declare function hasZoneSuffix(value: string): boolean;
+/** The canonical description for a birth / chart-moment datetime parameter. */
+export declare const DATETIME_DESC: string;
+/** The canonical description for the companion `timezone` parameter. */
+export declare const TIMEZONE_DESC: string;
+/** The canonical description for a search-window date parameter (date or datetime). */
+export declare const WINDOW_DATE_DESC: string;
+/** The `timezone` property to spread into a tool's inputSchema. */
+export declare const TIMEZONE_PROPERTY: {
+    readonly type: "string";
+    readonly description: string;
+};
+/** Build a `<prefix>_timezone` property with a tailored example. */
+export declare function timezoneProperty(label: string, example?: string): {
+    readonly type: "string";
+    readonly description: string;
+};
+/**
+ * The rejection message. Names both remedies, rewriting the caller's own value
+ * into each — the commonest failure is not realising the value was ambiguous.
+ */
+export declare function ambiguousDatetimeMessage(field: string, value: string, timezoneField?: string): string;
+/**
+ * Throws unless `value` names an unambiguous instant.
+ *
+ * Call this in every tool handler before building a request body. Passing a
+ * `timezone` satisfies the contract for a zone-less value; the zone itself is
+ * resolved server-side (or by `localToUtcIso` for the `*_utc` endpoints).
+ */
+export declare function assertZonedDatetime(field: string, value: unknown, timezone?: unknown, timezoneField?: string): void;
+/**
+ * Convert a datetime to a UTC ISO 8601 string for the endpoints whose field is
+ * named `*_utc` and whose Go type is a strict RFC 3339 `time.Time`.
+ *
+ * Unlike the four ad-hoc `ensureTimezone` helpers this replaces, it never
+ * appends a bare "Z" to a zone-less value — it throws instead. Appending Z
+ * asserts the input was UTC, which is exactly the silent assumption that made
+ * the original defect invisible.
+ */
+export declare function localToUtcIso(field: string, dt: string, tz?: string, timezoneField?: string): string;