@openephemeris/mcp-server 3.24.0 → 4.0.0

package/dist/tools/datetime.js

@@ -0,0 +1,153 @@
+/**
+ * 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.
+ */
+/** Matches a `Z`, `±HH:MM`, or `±HHMM` zone suffix. */
+const ZONE_SUFFIX = /([Zz]|[+-]\d{2}:?\d{2})$/;
+/** Matches an ISO value that carries a clock time (as opposed to a bare date). */
+const HAS_CLOCK_TIME = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}/;
+/** True when `value` states a clock time but not the zone that clock is in. */
+export function isNaiveClockTime(value) {
+    const s = (value ?? "").trim();
+    return HAS_CLOCK_TIME.test(s) && !ZONE_SUFFIX.test(s);
+}
+/** True when `value` already carries its own zone. */
+export function hasZoneSuffix(value) {
+    return ZONE_SUFFIX.test((value ?? "").trim());
+}
+// ─── Canonical parameter documentation ───────────────────────────────────────
+// Every tool that accepts a datetime uses these strings verbatim, so the contract
+// reads identically everywhere. `test/datetime-contract.test.ts` fails if a tool
+// description grows an ISO example that violates it.
+/** The canonical description for a birth / chart-moment datetime parameter. */
+// Kept deliberately terse: this string is repeated on every datetime-accepting
+// tool, so each character costs ~40x across the surface and is re-sent on every
+// model pass. Every RULE stays; the rationale for the rule lives in the module
+// docstring above, which the model never sees.
+export const DATETIME_DESC = "ISO 8601 datetime that states its zone. Either put the zone on the value " +
+    "('1987-07-15T09:01:00-05:00', or '...T14:01:00Z' for UTC), or pass local " +
+    "wall-clock time plus the `timezone` argument. A zone-less time is REJECTED. " +
+    "A date with no time ('1987-07-15') resolves to 12:00 UTC.";
+/** The canonical description for the companion `timezone` parameter. */
+export const TIMEZONE_DESC = "IANA timezone name for the birth/observation location, e.g. 'America/Chicago'. " +
+    "Required when the datetime has no 'Z' or ±HH:MM offset; ignored when it does. " +
+    "Historical DST is resolved correctly.";
+/** The canonical description for a search-window date parameter (date or datetime). */
+export const WINDOW_DATE_DESC = "ISO 8601 date ('2026-01-01') or a zoned datetime ('2026-01-01T00:00:00Z'). " +
+    "A date with no time resolves to 12:00 UTC. A time without a 'Z' or ±HH:MM offset " +
+    "is rejected as ambiguous.";
+/** The `timezone` property to spread into a tool's inputSchema. */
+export const TIMEZONE_PROPERTY = {
+    type: "string",
+    description: TIMEZONE_DESC,
+};
+/** Build a `<prefix>_timezone` property with a tailored example. */
+export function timezoneProperty(label, example = "America/Chicago") {
+    return {
+        type: "string",
+        description: `IANA timezone name for ${label}, e.g. '${example}'. ` +
+            "Required when that datetime has no 'Z' or ±HH:MM offset; ignored when it does.",
+    };
+}
+// ─── Enforcement ─────────────────────────────────────────────────────────────
+/**
+ * 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 function ambiguousDatetimeMessage(field, value, timezoneField = "timezone") {
+    const v = (value ?? "").trim();
+    return (`\`${field}\` is "${v}", which states a clock time but not the zone that clock is in, ` +
+        `so it does not name a moment. OpenEphemeris will not guess. Fix it either way:\n` +
+        `  1. Put the zone on the datetime: ${field}="${v}-05:00" for a local time, ` +
+        `or ${field}="${v}Z" if it really is UTC.\n` +
+        `  2. Keep the local wall-clock time and name the zone: ` +
+        `${field}="${v}", ${timezoneField}="America/Chicago".\n` +
+        `An unstated zone moves the Ascendant by ~15° per hour and shifts every house placement.`);
+}
+/**
+ * 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 function assertZonedDatetime(field, value, timezone, timezoneField = "timezone") {
+    if (typeof value !== "string" || value.trim() === "")
+        return; // required-ness is checked elsewhere
+    if (!isNaiveClockTime(value))
+        return;
+    if (typeof timezone === "string" && timezone.trim() !== "")
+        return;
+    throw new Error(ambiguousDatetimeMessage(field, value, timezoneField));
+}
+/**
+ * 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 function localToUtcIso(field, dt, tz, timezoneField = "timezone") {
+    const value = (dt ?? "").trim();
+    if (hasZoneSuffix(value)) {
+        // Normalise `±HHMM` to `±HH:MM` for Go's RFC 3339 parser.
+        return value.replace(/([+-]\d{2})(\d{2})$/, "$1:$2");
+    }
+    if (!isNaiveClockTime(value)) {
+        // Date-only or unrecognised: leave it to the server to interpret or reject.
+        return value;
+    }
+    if (!tz || tz.trim() === "") {
+        throw new Error(ambiguousDatetimeMessage(field, value, timezoneField));
+    }
+    const [datePart, timePart = "00:00:00"] = value.split(/[T ]/);
+    const [year, month, day] = datePart.split("-").map(Number);
+    const [hour, min, sec = 0] = timePart.split(":").map(Number);
+    // Treat the components as local wall-clock time in `tz`, then shift by the
+    // offset Intl reports for that instant. Iterate twice: the offset at the UTC
+    // candidate can differ from the offset at the true instant across a DST edge.
+    const offsetMsAt = (utcMs) => {
+        const parts = new Intl.DateTimeFormat("en-US", {
+            timeZone: tz,
+            hour12: false,
+            year: "numeric",
+            month: "2-digit",
+            day: "2-digit",
+            hour: "2-digit",
+            minute: "2-digit",
+            second: "2-digit",
+        }).formatToParts(new Date(utcMs));
+        const get = (t) => Number(parts.find((p) => p.type === t)?.value);
+        const asUtc = Date.UTC(get("year"), get("month") - 1, get("day"), get("hour") % 24, get("minute"), get("second"));
+        return asUtc - utcMs;
+    };
+    let utcMs = Date.UTC(year, month - 1, day, hour, min, sec);
+    utcMs -= offsetMsAt(utcMs);
+    utcMs = Date.UTC(year, month - 1, day, hour, min, sec) - offsetMsAt(utcMs);
+    const iso = new Date(utcMs).toISOString();
+    if (Number.isNaN(utcMs)) {
+        throw new Error(`\`${field}\` could not be resolved: "${value}" in timezone "${tz}". ` +
+            "Check the datetime format and that the IANA zone name is spelled correctly.");
+    }
+    return iso.replace(/\.000Z$/, "Z");
+}

package/dist/tools/index.d.ts

@@ -40,12 +40,55 @@ export interface ToolDefinition {
     stdioOnly?: boolean;
     handler: (args: any) => Promise<any>;
 }
+/**
+ * Which slice of the registry a ListTools response advertises.
+ *
+ * - `core`: the curated everyday set (see CORE_TOOL_NAMES).
+ * - `full`: every model-visible tool.
+ *
+ * This is a *view* filter, not a registration filter. Tools outside the core
+ * set stay registered and stay callable by name — CallTool resolves straight
+ * out of toolRegistry (src/index.ts, src/server-sse.ts) and never consults the
+ * surface. Narrowing the surface therefore costs zero capability; it only
+ * shrinks the tool-definition payload the model has to reason over.
+ *
+ * Registration-time filtering (a third ToolProfile) would NOT work here: the
+ * registry is process-global with a one-shot `toolsInitialized` latch, so the
+ * multi-tenant HTTP server cannot vary it per session, and an unregistered
+ * tool becomes uncallable rather than merely hidden.
+ */
+export type ToolSurface = "core" | "full";
+/**
+ * The default advertised surface: everyday astrology work, one tool per job.
+ *
+ * Selection rules:
+ *  - every explore_* app (the visual entry point to each tradition),
+ *  - the primary data tool per domain,
+ *  - geocoding (location_search / timezone_resolve) so charts can be built
+ *    from a place name without falling back to dev_read_api,
+ *  - the dev escape hatch, which reaches 28 further endpoints via the
+ *    allowlist and is how anything outside this set gets discovered.
+ *
+ * Everything omitted here — the Venus family, the typed BaZi derivations, the
+ * comparative and returns long tail, the standalone SVG renderers — remains
+ * fully callable by name, and is listed by `dev_list_allowed` where the
+ * allowlist covers it. Clients that want the whole surface advertised can ask
+ * for it: `?profile=full` on HTTP, `OPENEPHEMERIS_TOOLS=full` on stdio.
+ *
+ * NOTE: scripts/test-mcp-http.ts (the 6-hourly production canary) asserts
+ * dev_read_api, ephemeris_moon_phase, ephemeris_natal_chart and
+ * explore_natal_chart are present. Do not remove those four.
+ */
+export declare const CORE_TOOL_NAMES: ReadonlySet<string>;
 /**
  * Returns tools that should be exposed to Claude in the ListTools response.
  * Filters out tools that have visibility restricted to the UI (app-only),
- * and — for the HTTP transport — tools marked stdioOnly.
+ * for the HTTP transport tools marked stdioOnly, and — when `surface` is
+ * "core" — everything outside CORE_TOOL_NAMES.
  */
-export declare function modelVisibleTools(transport?: "stdio" | "http"): ToolDefinition[];
+export declare function modelVisibleTools(transport?: "stdio" | "http", surface?: ToolSurface): ToolDefinition[];
+/** Parses a caller-supplied surface hint. Anything unrecognised means "core". */
+export declare function parseToolSurface(raw: unknown): ToolSurface;
 export declare const toolRegistry: Record<string, ToolDefinition>;
 export declare function registerTool(tool: ToolDefinition): void;
 export type ToolProfile = "dev" | "legacy";

package/dist/tools/index.js

@@ -12,12 +12,80 @@ export const SERVER_VERSION = (() => {
         return "0.0.0-unknown";
     }
 })();
+/**
+ * The default advertised surface: everyday astrology work, one tool per job.
+ *
+ * Selection rules:
+ *  - every explore_* app (the visual entry point to each tradition),
+ *  - the primary data tool per domain,
+ *  - geocoding (location_search / timezone_resolve) so charts can be built
+ *    from a place name without falling back to dev_read_api,
+ *  - the dev escape hatch, which reaches 28 further endpoints via the
+ *    allowlist and is how anything outside this set gets discovered.
+ *
+ * Everything omitted here — the Venus family, the typed BaZi derivations, the
+ * comparative and returns long tail, the standalone SVG renderers — remains
+ * fully callable by name, and is listed by `dev_list_allowed` where the
+ * allowlist covers it. Clients that want the whole surface advertised can ask
+ * for it: `?profile=full` on HTTP, `OPENEPHEMERIS_TOOLS=full` on stdio.
+ *
+ * NOTE: scripts/test-mcp-http.ts (the 6-hourly production canary) asserts
+ * dev_read_api, ephemeris_moon_phase, ephemeris_natal_chart and
+ * explore_natal_chart are present. Do not remove those four.
+ */
+export const CORE_TOOL_NAMES = new Set([
+    // Interactive apps — the visual entry point to each tradition
+    "explore_natal_chart",
+    "explore_bi_wheel",
+    "explore_human_design",
+    "explore_human_design_transit",
+    "explore_human_design_connection",
+    "explore_moon_phase",
+    "explore_transit_timeline",
+    "explore_vedic_chart",
+    "explore_bazi_chart",
+    // Core ephemeris data
+    "ephemeris_natal_chart",
+    "ephemeris_planet_position",
+    "ephemeris_house_cusps",
+    "ephemeris_moon_phase",
+    "ephemeris_transits",
+    "ephemeris_synastry",
+    "ephemeris_retrograde_status",
+    "ephemeris_next_eclipse",
+    "ephemeris_relocation",
+    "ephemeris_progressed_chart",
+    "ephemeris_solar_return",
+    // Traditions
+    "human_design_chart",
+    "vedic_chart",
+    "chinese_bazi",
+    // Timing
+    "ephemeris_electional",
+    "electional_moment_analysis",
+    // Astrocartography
+    "acg_power_lines",
+    "acg_hits",
+    // Geocoding — promoted to model visibility so chart building does not have
+    // to route through dev_read_api /location/autocomplete
+    "location_search",
+    "timezone_resolve",
+    // Account + escape hatch
+    "account_usage",
+    "dev_read_api",
+    "dev_list_allowed",
+    // Auth (stdio transport only — already fenced by stdioOnly)
+    "auth_login",
+    "auth_status",
+    "auth_logout",
+]);
 /**
  * Returns tools that should be exposed to Claude in the ListTools response.
  * Filters out tools that have visibility restricted to the UI (app-only),
- * and — for the HTTP transport — tools marked stdioOnly.
+ * for the HTTP transport tools marked stdioOnly, and — when `surface` is
+ * "core" — everything outside CORE_TOOL_NAMES.
  */
-export function modelVisibleTools(transport = "stdio") {
+export function modelVisibleTools(transport = "stdio", surface = "full") {
     return Object.values(toolRegistry).filter((t) => {
         if (transport === "http" && t.stdioOnly)
             return false;
@@ -25,9 +93,15 @@ export function modelVisibleTools(transport = "stdio") {
         // If visibility is explicitly ["app"] (no "model"), hide from model
         if (vis && !vis.includes("model") && vis.includes("app"))
             return false;
+        if (surface === "core" && !CORE_TOOL_NAMES.has(t.name))
+            return false;
         return true;
     });
 }
+/** Parses a caller-supplied surface hint. Anything unrecognised means "core". */
+export function parseToolSurface(raw) {
+    return typeof raw === "string" && raw.toLowerCase() === "full" ? "full" : "core";
+}
 export const toolRegistry = {};
 export function registerTool(tool) {
     toolRegistry[tool.name] = tool;
@@ -47,6 +121,8 @@ export async function initTools(profile) {
     const resolvedProfile = (profile || process.env.OPENEPHEMERIS_PROFILE || process.env.ASTROMCP_PROFILE || "dev").toLowerCase();
     // Always register auth tools (available in all profiles).
     await import("./auth.js");
+    // Always register account/usage tools (0-credit, useful in all profiles).
+    await import("./specialized/account.js");
     // Always register the generic proxy tools (dev_read_api + dev_write_api + dev_list_allowed).
     await import("./dev.js");
     if (resolvedProfile === "dev") {

package/dist/tools/specialized/account.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/specialized/account.js

@@ -0,0 +1,100 @@
+import { registerTool } from "../index.js";
+import { getActiveClient, BackendError, DASHBOARD_ACCOUNT_URL, LOGIN_SIGNUP_URL, UPGRADE_URL, WALLET_TOPUP_URL, } from "../../backend/client.js";
+import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
+// Tiers where the primary next step is a wallet top-up rather than a plan change.
+const WALLET_TIERS = new Set(["explorer", "free", "payg", "wallet"]);
+registerTool({
+    name: "account_usage",
+    description: "Check the user's OpenEphemeris account usage and remaining credits. " +
+        "Returns their plan tier, billing period, credits used / included / remaining, " +
+        "percent of quota used, total API calls, and subscription status with renewal date.\n\n" +
+        "✅  USE THIS TOOL FOR: 'How many credits do I have left?', 'What's my usage this month?', " +
+        "'Am I close to my limit?', 'What plan am I on?', 'How do I upgrade or top up?'\n\n" +
+        "CREDIT COST: Free (0 credits).\n\n" +
+        "EXAMPLE: Check current usage:\n" +
+        "  (call with no arguments)\n\n" +
+        "EXAMPLE: Check a past month:\n" +
+        "  month='2026-06'",
+    inputSchema: {
+        type: "object",
+        properties: {
+            month: {
+                type: "string",
+                description: "Billing month to query in YYYY-MM format (e.g. '2026-06'). Defaults to the current month.",
+            },
+        },
+        required: [],
+        additionalProperties: false,
+    },
+    outputSchema: OUTPUT_SCHEMA_JSON,
+    annotations: { title: "Account Usage", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    handler: async (args) => {
+        const params = {};
+        if (args?.month)
+            params.month = args.month;
+        let usageRows;
+        try {
+            const raw = await getActiveClient().request("GET", "/api-keys/overage-status", { params });
+            usageRows = Array.isArray(raw) ? raw : [];
+        }
+        catch (error) {
+            if (error instanceof BackendError && error.status === 401) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: `**Not signed in.** To check usage, connect an OpenEphemeris account first.\n\n` +
+                                `${error.message}\n\n` +
+                                `New here? Create a free account at ${LOGIN_SIGNUP_URL}`,
+                        }],
+                };
+            }
+            throw error;
+        }
+        // Subscription info is best-effort — usage is still useful without it.
+        let subscription = null;
+        try {
+            subscription = await getActiveClient().request("GET", "/billing/stripe/me");
+        }
+        catch {
+            // Tolerate failure (e.g. no Stripe customer on free tier).
+        }
+        const row = usageRows[0] ?? {};
+        const tier = (row.tier || subscription?.tier || "explorer").toLowerCase();
+        const period = row.month || args?.month || new Date().toISOString().substring(0, 7);
+        const used = row.total_units ?? 0;
+        const included = row.included_units ?? 0;
+        const remaining = Math.max(included - used, 0);
+        const percent = row.percent_units_used ?? (included > 0 ? Math.round((used / included) * 1000) / 10 : 0);
+        const totalCalls = row.total_calls ?? 0;
+        const lines = [
+            `**OpenEphemeris Account Usage**`,
+            ``,
+            `- **Plan:** ${tier}`,
+            `- **Period:** ${period}`,
+            `- **Credits:** ${used.toLocaleString()} used of ${included.toLocaleString()} included — **${remaining.toLocaleString()} remaining** (${percent}% used)`,
+            `- **Total API calls:** ${totalCalls.toLocaleString()}`,
+        ];
+        if ((row.overage_units ?? 0) > 0) {
+            lines.push(`- **Overage:** ${row.overage_units.toLocaleString()} credits over the included amount`);
+        }
+        if (subscription?.status) {
+            lines.push(`- **Subscription:** ${subscription.status}`);
+        }
+        if (subscription?.current_period_end) {
+            const renewal = new Date(subscription.current_period_end);
+            if (!Number.isNaN(renewal.getTime())) {
+                lines.push(`- **Renews:** ${renewal.toISOString().substring(0, 10)}`);
+            }
+        }
+        lines.push(``);
+        if (WALLET_TIERS.has(tier)) {
+            lines.push(`**Need more credits?** Top up your wallet at ${WALLET_TOPUP_URL} (from $5), ` +
+                `or upgrade to a monthly plan at ${UPGRADE_URL}.`);
+        }
+        else {
+            lines.push(`**Need more credits?** Upgrade your plan at ${UPGRADE_URL}, ` +
+                `or manage your subscription at ${DASHBOARD_ACCOUNT_URL}.`);
+        }
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+    },
+});

package/dist/tools/specialized/acg.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, localToUtcIso } from "../datetime.js";
 const ACG_BODY_DESCRIPTION = "List of celestial bodies for line calculation. " +
     "E.g. ['Sun', 'Moon', 'Venus', 'Mars', 'Jupiter', 'Saturn']. " +
     "Aliases: 'NorthNode'/'Node'/'Rahu' → MeanNode, 'SouthNode'/'Ketu' → SouthNode. " +
@@ -16,21 +17,21 @@ registerTool({
         "→ For a specific city/location analysis, use acg_hits instead (faster and more relevant).\n" +
         "✅  USE FOR: Getting the full global GeoJSON line geometry for map rendering or bulk geographic analysis.\n\n" +
         "CREDIT COST: 10 credits per call.\n\n" +
-        "EXAMPLE: Saturn and Jupiter power lines for a chart born 1990-04-15 in Chicago:\n" +
-        "  birth_datetime='1990-04-15T14:30:00', birth_latitude=41.8781, birth_longitude=-87.6298,\n" +
-        "  bodies=['Saturn', 'Jupiter']",
+        "EXAMPLE: Saturn and Jupiter power lines for a chart born 1990-04-15 at 2:30 PM in Chicago:\n" +
+        "  birth_datetime='1990-04-15T14:30:00', timezone='America/Chicago',\n" +
+        "  birth_latitude=41.8781, birth_longitude=-87.6298, bodies=['Saturn', 'Jupiter']",
     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 place the ACG lines in the wrong location.",
+                description: DATETIME_DESC +
+                    " An unstated zone moves every ACG line by ~15° of longitude per hour.",
             },
+            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",
@@ -66,7 +67,7 @@ registerTool({
                 birthplace_lat: args.birth_latitude,
                 birthplace_lon: args.birth_longitude,
             },
-            epoch: args.birth_datetime,
+            epoch: localToUtcIso("birth_datetime", args.birth_datetime, args.timezone),
         };
         if (args.bodies)
             body.bodies = args.bodies;
@@ -109,20 +110,21 @@ registerTool({
         "❌  NOT FOR: Full global map geometry → use acg_power_lines for that instead.\n\n" +
         "CREDIT COST: 15 credits per call.\n\n" +
         "EXAMPLE: All ACG lines within 3° of Paris for a chart born 1990-04-15 in Chicago:\n" +
-        "  birth_datetime='1990-04-15T14:30:00', birth_latitude=41.8781, birth_longitude=-87.6298,\n" +
+        "  birth_datetime='1990-04-15T14:30:00', timezone='America/Chicago',\n" +
+        "  birth_latitude=41.8781, birth_longitude=-87.6298,\n" +
         "  query_latitude=48.8566, query_longitude=2.3522, radius_deg=3",
     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 place the ACG lines in the wrong location.",
+                description: DATETIME_DESC +
+                    " An unstated zone moves every ACG line by ~15° of longitude per hour.",
             },
+            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",
@@ -162,7 +164,7 @@ registerTool({
                 birthplace_lat: args.birth_latitude,
                 birthplace_lon: args.birth_longitude,
             },
-            epoch: args.birth_datetime,
+            epoch: localToUtcIso("birth_datetime", args.birth_datetime, args.timezone),
             query_lat: args.query_latitude,
             query_lon: args.query_longitude,
         };

package/dist/tools/specialized/bazi.d.ts

@@ -1 +1,7 @@
-export {};
+export interface BaziComponents {
+    year: number;
+    month: number;
+    day: number;
+    hour?: number;
+}
+export declare function parseBaziArgs(args: any, datetimeField?: string): BaziComponents;