@openephemeris/mcp-server 4.8.0 → 4.10.0

package/CHANGELOG.md

@@ -7,6 +7,69 @@ Version numbering follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [4.10.0] — 2026-08-05
+
+### Fixed
+- **BaZi tools never forwarded `timezone` to the API.** `parseBaziArgs` used it
+  only to read a zoned `datetime` back into local calendar components, then
+  dropped it — every BaZi request from MCP (`chinese_bazi`, `bazi_ten_gods`,
+  `bazi_element_balance`, `bazi_luck_pillars`, `bazi_chart`,
+  `explore_bazi_chart`, `bazi_compatibility`) landed on the API with no zone,
+  which resolves the year/month solar-term boundary (Li Chun, the Jié) against
+  the naive local clock instead of the true birth instant — exactly the defect
+  [#532](https://github.com/openephemeris/openephemeris/pull/532) fixes at the
+  API. A birth within roughly the birthplace's UTC offset of a boundary could
+  land on the wrong side and get the wrong year or month pillar. `timezone` is
+  now forwarded on every BaZi tool.
+
+### Added
+- **BaZi convention parameters.** `minute`, `year_boundary`
+  (`lichun`/`cny`), `day_boundary` (`zi_hour`/`midnight`), `true_solar_time`,
+  and `latitude`/`longitude` are now request parameters on every BaZi tool
+  that accepts them at the API — `bazi_compatibility` takes them per chart
+  (`chart_a_*`/`chart_b_*`), since partners are often born under different
+  conventions or in different timezones.
+
+## [4.9.0] — 2026-08-03
+
+### Fixed
+- **`location_search` gave pre-1970 birthplaces the wrong UTC offset.** With a
+  `date` before 1970 it answered from local tzdata alone — and tzdata models
+  only a zone's *reference city* before 1970, which is exactly the error the
+  API's historical correction overlay exists to remove. Dallas on 1952-07-15
+  came back `-05:00` (Chicago observed daylight time that summer; Texas did
+  not) instead of the correct `-06:00`. Because this tool is the documented
+  one-call alternative to `timezone_resolve`, an agent that took the top match
+  and built a zone-suffixed datetime from it produced a chart an hour off with
+  nothing downstream able to detect it. The top match is now corrected through
+  the API (1 extra credit, pre-1970 only); remaining matches keep their tzdata
+  estimate and stay labelled `historical_estimate`. Post-1970 is unchanged and
+  still free.
+
+### Added
+- **Historical-correction provenance now reaches MCP consumers.**
+  `timezone_resolve` and `location_search` forwarded only `tzRuleSource` out of
+  the five fields the API publishes. They now also return `tzOverlayVersion`,
+  `tzOverlayHash`, `tzRuleCitation` and `serverVersion`. The first two are the
+  change signal — without them a consumer cannot tell that the correction
+  dataset moved underneath charts it already computed. `tzRuleCitation` carries
+  the actual primary source behind a correction (a statute reference, an agency
+  order, a dated almanac page), so a corrected time can show its work instead of
+  asking to be trusted. Keys are omitted rather than emitted as nulls when the
+  API sends none.
+
+## [4.8.1] — 2026-08-02
+
+### Fixed
+- Every tool now declares all four MCP annotation hints explicitly
+  (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`).
+  Notably `dev_write_api` is `destructiveHint: false` — every allowlisted
+  write is stateless chart computation — so strict clients no longer gate it
+  behind a confirmation, and `openWorldHint` is uniformly `false` (the server
+  reaches only the fixed OpenEphemeris API).
+- `account_usage` reports a real authentication failure as a tool error
+  (`isError: true`) instead of a success-shaped message.
+
 ## [4.8.0] — 2026-08-02
 
 ### Added

package/dist/tools/apps/bazi-app.js

@@ -25,7 +25,7 @@ import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
 // One BaZi component parser, shared with the specialized tools. The local copy
 // this replaces used `new Date(naive)`, which resolves in the host process's
 // timezone and silently shifted the hour pillar on any non-UTC server.
-import { parseBaziArgs } from "../specialized/bazi.js";
+import { parseBaziArgs, buildBaziConventionFields, CONVENTION_PROPERTIES } from "../specialized/bazi.js";
 // ── Constants ─────────────────────────────────────────────────────────────────
 export const BAZI_RESOURCE_URI = "ui://openephemeris/bazi";
 export const BAZI_MIME_TYPE = "text/html;profile=mcp-app";
@@ -66,10 +66,11 @@ export function clearBaziBundleCache() {
  * Go-rendered SVG (bazi.RenderBaziChartSVG), same shape the strict
  * /chinese/bazi handler returns with a `visual` key attached.
  */
-async function fetchBaziChart(components, theme = "dark") {
+async function fetchBaziChart(components, theme = "dark", conventionFields = {}) {
     const client = getActiveClient();
     const body = {
         ...components,
+        ...conventionFields,
         include_visual: true,
         visual_config: { format: "svg", theme, size: 800 },
     };
@@ -129,6 +130,10 @@ registerTool({
                 description: "Birth hour (0–23). Optional, defaults to 12 (noon). " +
                     "Chinese shí hours are 2-hour blocks — precision within a 2-hour window is sufficient.",
             },
+            minute: {
+                type: "integer",
+                description: "Birth minute (0–59). Optional, defaults to 0. Only matters under true_solar_time or near a boundary.",
+            },
             datetime: {
                 type: "string",
                 description: "Alternative to year/month/day: ISO 8601 datetime read as LOCAL wall-clock time at the " +
@@ -137,9 +142,10 @@ registerTool({
             },
             timezone: {
                 type: "string",
-                description: "IANA timezone name for the birth place, e.g. 'Asia/Shanghai'. Only needed when " +
-                    "datetime carries a 'Z' or ±HH:MM offset.",
+                description: "IANA timezone name for the birth place, e.g. 'Asia/Shanghai'. Required to convert a zoned " +
+                    "datetime back to local clock; also frames the year/month solar-term boundary.",
             },
+            ...CONVENTION_PROPERTIES,
         },
         additionalProperties: false,
     },
@@ -159,17 +165,18 @@ registerTool({
     },
     handler: async (args) => {
         const components = parseBaziArgs(args);
+        const conventionFields = buildBaziConventionFields(args);
         const bundleAvailable = Boolean(getBaziBundle());
         const theme = "dark";
         if (!bundleAvailable) {
             // Text-fallback hosts have no use for the SVG — skip the visual surcharge.
             const data = await getActiveClient().request("POST", "/chinese/bazi", {
-                data: components,
+                data: { ...components, ...conventionFields },
             });
             const payload = buildModelPayload(data, components, theme);
             return { content: [{ type: "text", text: buildSummary(payload) }] };
         }
-        const data = await fetchBaziChart(components, theme);
+        const data = await fetchBaziChart(components, theme, conventionFields);
         const payload = buildModelPayload(data, components, theme);
         const summary = buildSummary(payload);
         // MCP Apps wire format: the UI is declared via `_meta.ui.resourceUri` and
@@ -204,7 +211,7 @@ registerTool({
         required: ["year", "month", "day"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Recalculate BaZi Chart", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Recalculate BaZi Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BAZI_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const components = parseBaziArgs(args);

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

@@ -588,7 +588,7 @@ registerTool({
         required: ["mode", "person1_datetime", "person1_latitude", "person1_longitude", "person2_datetime"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Recalculate Bi-Wheel", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Recalculate Bi-Wheel", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BI_WHEEL_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const client = getActiveClient();
@@ -644,7 +644,7 @@ registerTool({
         required: ["planet1", "planet2", "aspect_type"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Cross-Aspect Interpretation", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Cross-Aspect Interpretation", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BI_WHEEL_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const p1 = capitalize(String(args.planet1));
@@ -683,7 +683,7 @@ registerTool({
         required: ["planet", "wheel", "longitude"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Bi-Wheel Planet Interpretation", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Bi-Wheel Planet Interpretation", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BI_WHEEL_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const planet = String(args.planet);
@@ -884,7 +884,7 @@ registerTool({
         required: ["house_number"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Bi-Wheel House Interpretation", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Bi-Wheel House Interpretation", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BI_WHEEL_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const num = Number(args.house_number);
@@ -944,7 +944,7 @@ registerTool({
         required: ["mode"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Bi-Wheel Synopsis", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Bi-Wheel Synopsis", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BI_WHEEL_RESOURCE_URI, visibility: ["app", "model"] } },
     handler: async (args) => {
         const mode = args.mode ?? "synastry";

package/dist/tools/apps/bodygraph-app.js

@@ -471,7 +471,7 @@ registerTool({
         required: ["datetime"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Recalculate Bodygraph", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Recalculate Bodygraph", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BODYGRAPH_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const client = getActiveClient();
@@ -536,7 +536,7 @@ registerTool({
         required: ["center", "defined"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Center Interpretation", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Center Interpretation", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BODYGRAPH_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const center = String(args.center);
@@ -594,7 +594,7 @@ registerTool({
         required: ["gate"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Gate Interpretation", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Gate Interpretation", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BODYGRAPH_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const gate = Number(args.gate);
@@ -649,7 +649,7 @@ registerTool({
         required: ["channel"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Channel Interpretation", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Channel Interpretation", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BODYGRAPH_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const channelStr = String(args.channel);
@@ -751,7 +751,7 @@ registerTool({
         required: ["channel"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Connection Channel Interpretation", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Connection Channel Interpretation", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BODYGRAPH_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const channelStr = String(args.channel ?? "");
@@ -807,7 +807,7 @@ registerTool({
         required: ["channel"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Transit Channel Interpretation", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Transit Channel Interpretation", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BODYGRAPH_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const channelStr = String(args.channel ?? "");
@@ -1135,7 +1135,7 @@ registerTool({
         required: ["planet", "column"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Planet Sidebar Interpretation", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Planet Sidebar Interpretation", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BODYGRAPH_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const planet = String(args.planet);
@@ -1204,7 +1204,7 @@ registerTool({
         required: ["variable", "direction"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Variable Arrow Interpretation", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Variable Arrow Interpretation", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BODYGRAPH_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const variable = String(args.variable).toLowerCase();

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

@@ -259,7 +259,7 @@ registerTool({
         required: ["planet", "longitude"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Planet Interpretation", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Planet Interpretation", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: CHART_WHEEL_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const planet = String(args.planet);
@@ -294,7 +294,7 @@ registerTool({
         required: ["house_number"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "House Interpretation", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "House Interpretation", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: CHART_WHEEL_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const num = Number(args.house_number);
@@ -330,7 +330,7 @@ registerTool({
         required: ["planet1", "planet2"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Aspect Interpretation", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Aspect Interpretation", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: CHART_WHEEL_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const p1 = capitalize(String(args.planet1));
@@ -379,7 +379,7 @@ registerTool({
         required: ["datetime", "latitude", "longitude", "house_system"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Recalculate Chart", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Recalculate Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: CHART_WHEEL_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const client = getActiveClient();

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

@@ -2,6 +2,34 @@ import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
 import { TZDATA_AUTHORITATIVE_FROM_YEAR } from "../datetime-historical.js";
+/**
+ * Lift the API's historical-correction provenance onto an MCP result.
+ *
+ * The server publishes five fields that say *why* a pre-1970 offset is what it
+ * is, and until now this server forwarded exactly one of them. That left an
+ * agent unable to tell a cited statutory correction from a tzdata guess, and
+ * left every MCP consumer blind to the overlay dataset changing underneath
+ * previously-computed charts — which is the whole reason the version signal
+ * exists.
+ *
+ * Placement mirrors the REST contract: `tz_overlay_version`/`tz_overlay_hash`
+ * sit at the top level of the /timezone/offset response alongside
+ * `tz_rule_source`; `tz_rule_citation` and `server_version` live in
+ * `calculation_metadata`.
+ */
+function historicalProvenance(off) {
+    const meta = (off?.calculation_metadata ?? {});
+    const citation = meta.tz_rule_citation;
+    const serverVersion = meta.server_version;
+    return {
+        ...(typeof off.tz_rule_source === "string" ? { tzRuleSource: off.tz_rule_source } : {}),
+        ...(typeof off.datetime_status === "string" ? { datetimeStatus: off.datetime_status } : {}),
+        ...(typeof off.tz_overlay_version === "number" ? { tzOverlayVersion: off.tz_overlay_version } : {}),
+        ...(typeof off.tz_overlay_hash === "string" ? { tzOverlayHash: off.tz_overlay_hash } : {}),
+        ...(typeof citation === "string" && citation !== "" ? { tzRuleCitation: citation } : {}),
+        ...(typeof serverVersion === "string" && serverVersion !== "" ? { serverVersion } : {}),
+    };
+}
 /** Render minutes east of UTC as `±HH:MM`. */
 function formatOffsetMinutes(offsetMinutes) {
     const sign = offsetMinutes < 0 ? "-" : "+";
@@ -98,7 +126,7 @@ function offsetAtLocalNoon(timezone, date) {
 }
 registerTool({
     name: "location_search",
-    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.",
+    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). Post-1970 dates resolve locally and cost no extra credits; a pre-1970 date consults the API's historical correction overlay for the top match (1 extra credit) and returns its provenance — tzRuleSource, tzRuleCitation, tzOverlayVersion. 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: {
@@ -124,14 +152,14 @@ registerTool({
             },
             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.",
+                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. Post-1970 is free (local resolution, no API call). Pre-1970, the top match is additionally corrected through the API's historical overlay (1 extra credit) because tzdata models only the zone's reference city before 1970; the remaining suggestions keep their tzdata estimate and are labelled historical_estimate.",
             },
         },
         required: ["query"],
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Location Search", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Location Search", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     // 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.
@@ -178,6 +206,41 @@ registerTool({
             }
             return mapped;
         });
+        // Pre-1970, the tzdata offsets just attached are the very answers the
+        // historical-correction overlay exists to replace: a 1961 Robbinsdale
+        // date gets -05:00 from tzdata where state law says -06:00. This tool
+        // is documented as the one-call alternative to timezone_resolve, so an
+        // agent that takes the top hit and builds a zone-suffixed datetime from
+        // it would produce a chart an hour off — and nothing downstream could
+        // detect it.
+        //
+        // Correct the TOP suggestion through the server (one extra credit, the
+        // same cost timezone_resolve documents). Correcting all eight would
+        // multiply that for rows the caller almost never uses; the remaining
+        // rows keep their tzdata offsets and their historical_estimate label.
+        const topHit = suggestions[0];
+        if (preTzdataEra && date && topHit && typeof topHit.latitude === "number" && typeof topHit.longitude === "number") {
+            try {
+                const off = (await getActiveClient().request("POST", "/timezone/offset", {
+                    data: { lat: topHit.latitude, lon: topHit.longitude, datetime_local: `${date.slice(0, 10)}T12:00:00` },
+                }));
+                if (typeof off?.offset_seconds === "number") {
+                    const minutes = off.offset_seconds / 60;
+                    Object.assign(topHit, {
+                        utcOffsetAtDate: formatOffsetMinutes(minutes),
+                        utcOffsetMinutes: minutes,
+                        isDst: Boolean(off.is_dst),
+                        tzConfidence: typeof off.tz_confidence === "string" ? off.tz_confidence : "historical_estimate",
+                        ...historicalProvenance(off),
+                    });
+                }
+            }
+            catch {
+                // Server path unavailable — the tzdata estimate stands, still
+                // labelled historical_estimate. Degrading to a labelled
+                // estimate is acceptable; failing the whole search is not.
+            }
+        }
         // 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.
@@ -235,7 +298,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Timezone Resolve", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Timezone Resolve", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: {
         ui: {
             visibility: ["model", "app"],
@@ -272,8 +335,7 @@ registerTool({
                             isDst: Boolean(off.is_dst),
                             date,
                             tzConfidence: typeof off.tz_confidence === "string" ? off.tz_confidence : "historical_estimate",
-                            ...(typeof off.tz_rule_source === "string" ? { tzRuleSource: off.tz_rule_source } : {}),
-                            ...(typeof off.datetime_status === "string" ? { datetimeStatus: off.datetime_status } : {}),
+                            ...historicalProvenance(off),
                         };
                     }
                 }

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

@@ -295,7 +295,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Recalculate Moon Phase", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Recalculate Moon Phase", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: MOON_PHASE_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const { summary, uiPayload } = await computeMoonData(args);

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

@@ -240,7 +240,7 @@ registerTool({
         required: ["datetime"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Recalculate Vedic Chart", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Recalculate Vedic Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: VEDIC_CHART_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const client = getActiveClient();

package/dist/tools/auth.js

@@ -24,6 +24,10 @@ registerTool({
         title: "Connect Account",
         readOnlyHint: false,
         destructiveHint: false,
+        // Each call starts a fresh device-auth flow with a new code — repeating
+        // it is harmless but not a no-op.
+        idempotentHint: false,
+        openWorldHint: false,
     },
     stdioOnly: true,
     handler: async () => {
@@ -105,6 +109,8 @@ registerTool({
         title: "Auth Status",
         readOnlyHint: true,
         destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
     },
     stdioOnly: true,
     handler: async () => {
@@ -191,6 +197,8 @@ registerTool({
         title: "Disconnect Account",
         readOnlyHint: false,
         destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
     },
     stdioOnly: true,
     handler: async () => {

package/dist/tools/dev.js

@@ -196,8 +196,10 @@ registerTool({
         DEV_API_REFERENCE,
     inputSchema: makeProxyInputSchema(READ_METHODS),
     outputSchema: OUTPUT_SCHEMA_JSON,
-    // GET-only: never mutates server state.
-    annotations: { title: "API Read", readOnlyHint: true, openWorldHint: true },
+    // GET-only: never mutates server state. openWorldHint false — the proxy
+    // reaches only the fixed, allowlisted OpenEphemeris API (a closed world),
+    // same as every typed tool.
+    annotations: { title: "API Read", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: makeProxyHandler(READ_METHODS, "GET"),
 });
 registerTool({
@@ -209,8 +211,16 @@ registerTool({
         DEV_API_REFERENCE,
     inputSchema: makeProxyInputSchema(WRITE_METHODS),
     outputSchema: OUTPUT_SCHEMA_JSON,
-    // Issues POST/PUT/PATCH/DELETE — must not be advertised as read-only.
-    annotations: { title: "API Write", readOnlyHint: false, openWorldHint: true },
+    // Issues POST/PUT/PATCH/DELETE — must not be advertised as read-only. But
+    // destructiveHint is explicitly FALSE: every allowlisted write operation is
+    // stateless chart computation (natal, synastry, ACG, returns…) that debits
+    // credits and returns a result — nothing on the allowlist mutates or deletes
+    // user data, and the deny rules block /auth, /billing, /account, /api-keys.
+    // Left unset, strict clients default destructiveHint to true and gate every
+    // call behind a confirmation. idempotentHint true for the same reason: the
+    // same body yields the same chart. openWorldHint false — fixed allowlisted
+    // API only, a closed world.
+    annotations: { title: "API Write", readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: makeProxyHandler(WRITE_METHODS, "POST"),
 });
 registerTool({
@@ -226,7 +236,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "List Allowed API Operations", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "List Allowed API Operations", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async () => {
         const allowlist = loadAllowlist();
         return {

package/dist/tools/specialized/account.js

@@ -27,7 +27,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Account Usage", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Account Usage", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         const params = {};
         if (args?.month)
@@ -39,7 +39,11 @@ registerTool({
         }
         catch (error) {
             if (error instanceof BackendError && error.status === 401) {
+                // A real auth failure must carry isError — a success-shaped response
+                // teaches the model the call worked and it stops trying to fix auth.
+                // The guidance text is kept so hosts still show the user a way forward.
                 return {
+                    isError: true,
                     content: [{
                             type: "text",
                             text: `**Not signed in.** To check usage, connect an OpenEphemeris account first.\n\n` +

package/dist/tools/specialized/acg.js

@@ -60,7 +60,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Astrocartography Lines", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Astrocartography Lines", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, ["birth_datetime", "birth_latitude", "birth_longitude"]);
         const body = {
@@ -157,7 +157,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Astrocartography Location Hits", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Astrocartography Location Hits", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, ["birth_datetime", "birth_latitude", "birth_longitude", "query_latitude", "query_longitude"]);
         const body = {

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

@@ -3,5 +3,43 @@ export interface BaziComponents {
     month: number;
     day: number;
     hour?: number;
+    minute?: number;
 }
 export declare function parseBaziArgs(args: any, datetimeField?: string): BaziComponents;
+/**
+ * Build the optional BaZi convention fields (year_boundary, day_boundary,
+ * true_solar_time, latitude, longitude, timezone) to spread into a request
+ * body. `timezone` is wrapped to the API's `TimezoneInput` object shape.
+ *
+ * Kept separate from `parseBaziArgs`/`BaziComponents`: these fields frame
+ * which convention resolves the pillars rather than naming the birth moment
+ * itself, and bazi_compatibility needs the same set built twice under a
+ * `chart_a_`/`chart_b_` prefix.
+ */
+export declare function buildBaziConventionFields(args: any): Record<string, unknown>;
+/** `buildBaziConventionFields`, reading `<prefix>_<field>` args — used by bazi_compatibility. */
+export declare function buildBaziConventionFieldsPrefixed(args: any, prefix: string): Record<string, unknown>;
+export declare const CONVENTION_PROPERTIES: {
+    readonly year_boundary: {
+        readonly type: "string";
+        readonly enum: readonly ["lichun", "cny"];
+        readonly description: "Year-pillar cutover convention. Default lichun.";
+    };
+    readonly day_boundary: {
+        readonly type: "string";
+        readonly enum: readonly ["zi_hour", "midnight"];
+        readonly description: "Day-pillar cutover convention. Default zi_hour.";
+    };
+    readonly true_solar_time: {
+        readonly type: "boolean";
+        readonly description: "Apply true solar time correction (needs latitude+longitude).";
+    };
+    readonly latitude: {
+        readonly type: "number";
+        readonly description: "Birth latitude, decimal degrees (north+).";
+    };
+    readonly longitude: {
+        readonly type: "number";
+        readonly description: "Birth longitude, decimal degrees (east+).";
+    };
+};