@openephemeris/mcp-server 4.8.1 → 4.10.0

package/CHANGELOG.md

@@ -7,6 +7,57 @@ 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

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

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,7 +152,7 @@ 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"],
@@ -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.
@@ -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/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+).";
+    };
+};

package/dist/tools/specialized/bazi.js

@@ -2,7 +2,7 @@ import { registerTool } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_IMAGE_AND_JSON } from "../output-schemas.js";
 export function parseBaziArgs(args, datetimeField = "datetime") {
-    let { year, month, day, hour } = args;
+    let { year, month, day, hour, minute } = args;
     const datetime = args[datetimeField];
     if (datetime && (!year || !month || !day)) {
         const parts = baziLocalComponents(datetime, args.timezone, datetimeField);
@@ -11,6 +11,8 @@ export function parseBaziArgs(args, datetimeField = "datetime") {
         day = parts.day;
         if (hour == null)
             hour = parts.hour;
+        if (minute == null)
+            minute = parts.minute;
     }
     if (!year || !month || !day) {
         throw new Error("Provide year/month/day fields, or a datetime ISO string. " +
@@ -19,8 +21,48 @@ export function parseBaziArgs(args, datetimeField = "datetime") {
     const out = { year, month, day };
     if (hour != null)
         out.hour = hour;
+    if (minute != null)
+        out.minute = minute;
     return out;
 }
+/**
+ * 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 function buildBaziConventionFields(args) {
+    const fields = {};
+    if (args.year_boundary != null)
+        fields.year_boundary = args.year_boundary;
+    if (args.day_boundary != null)
+        fields.day_boundary = args.day_boundary;
+    if (args.true_solar_time != null)
+        fields.true_solar_time = args.true_solar_time;
+    if (args.latitude != null)
+        fields.latitude = args.latitude;
+    if (args.longitude != null)
+        fields.longitude = args.longitude;
+    if (typeof args.timezone === "string" && args.timezone.trim() !== "") {
+        fields.timezone = { iana_name: args.timezone };
+    }
+    return fields;
+}
+/** `buildBaziConventionFields`, reading `<prefix>_<field>` args — used by bazi_compatibility. */
+export function buildBaziConventionFieldsPrefixed(args, prefix) {
+    return buildBaziConventionFields({
+        year_boundary: args[`${prefix}_year_boundary`],
+        day_boundary: args[`${prefix}_day_boundary`],
+        true_solar_time: args[`${prefix}_true_solar_time`],
+        latitude: args[`${prefix}_latitude`],
+        longitude: args[`${prefix}_longitude`],
+        timezone: args[`${prefix}_timezone`],
+    });
+}
 /**
  * Extract the LOCAL calendar/clock components a BaZi chart is built from.
  *
@@ -50,7 +92,7 @@ function baziLocalComponents(datetime, timezone, field) {
             hour: "2-digit", minute: "2-digit",
         }).formatToParts(new Date(value));
         const get = (t) => Number(parts.find((p) => p.type === t)?.value);
-        return { year: get("year"), month: get("month"), day: get("day"), hour: get("hour") % 24 };
+        return { year: get("year"), month: get("month"), day: get("day"), hour: get("hour") % 24, minute: get("minute") };
     }
     const m = /^(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2}))?/.exec(value);
     if (!m) {
@@ -62,6 +104,7 @@ function baziLocalComponents(datetime, timezone, field) {
         month: Number(m[2]),
         day: Number(m[3]),
         hour: m[4] != null ? Number(m[4]) : undefined,
+        minute: m[5] != null ? Number(m[5]) : undefined,
     };
 }
 // Shared datetime input schema fragment — used across all BaZiRequest tools.
@@ -83,6 +126,10 @@ const DATETIME_PROPERTIES = {
         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 " +
@@ -93,11 +140,49 @@ const DATETIME_PROPERTIES = {
     },
     timezone: {
         type: "string",
-        description: "IANA timezone name for the birth place, e.g. 'Asia/Shanghai'. Only needed when " +
-            "`datetime` carries a 'Z' or ±HH:MM offset, to convert that instant back to the local " +
-            "clock the pillars are built from.",
+        description: "IANA timezone name for the birth place, e.g. 'Asia/Shanghai'. Required to convert a " +
+            "zoned `datetime` back to local clock; also passed to the API to frame the year/month " +
+            "solar-term boundary at the true birth instant instead of naive local clock.",
+    },
+};
+// Optional convention fields, shared across every BaZiRequest-shaped tool —
+// see BaZiRequest in the Go API. Kept terse: core tool-surface budget is
+// near its ceiling (test/tool-surface-budget.test.ts).
+export const CONVENTION_PROPERTIES = {
+    year_boundary: {
+        type: "string",
+        enum: ["lichun", "cny"],
+        description: "Year-pillar cutover convention. Default lichun.",
+    },
+    day_boundary: {
+        type: "string",
+        enum: ["zi_hour", "midnight"],
+        description: "Day-pillar cutover convention. Default zi_hour.",
+    },
+    true_solar_time: {
+        type: "boolean",
+        description: "Apply true solar time correction (needs latitude+longitude).",
+    },
+    latitude: {
+        type: "number",
+        description: "Birth latitude, decimal degrees (north+).",
+    },
+    longitude: {
+        type: "number",
+        description: "Birth longitude, decimal degrees (east+).",
     },
 };
+/** CONVENTION_PROPERTIES (+ minute) under a `chart_a_`/`chart_b_` prefix — used by bazi_compatibility. */
+function chartConventionProperties(label) {
+    return {
+        [`chart_${label.toLowerCase()}_minute`]: { type: "integer", description: `Chart ${label} minute (0–59).` },
+        [`chart_${label.toLowerCase()}_year_boundary`]: { type: "string", enum: ["lichun", "cny"], description: `Chart ${label} year-pillar cutover.` },
+        [`chart_${label.toLowerCase()}_day_boundary`]: { type: "string", enum: ["zi_hour", "midnight"], description: `Chart ${label} day-pillar cutover.` },
+        [`chart_${label.toLowerCase()}_true_solar_time`]: { type: "boolean", description: `Chart ${label}: true solar time correction.` },
+        [`chart_${label.toLowerCase()}_latitude`]: { type: "number", description: `Chart ${label} latitude (decimal degrees, north+).` },
+        [`chart_${label.toLowerCase()}_longitude`]: { type: "number", description: `Chart ${label} longitude (decimal degrees, east+).` },
+    };
+}
 // Shared visual input schema fragment — mirrors natal.ts pattern.
 const VISUAL_PROPERTIES = {
     include_visual: {
@@ -153,6 +238,7 @@ registerTool({
         type: "object",
         properties: {
             ...DATETIME_PROPERTIES,
+            ...CONVENTION_PROPERTIES,
             ...VISUAL_PROPERTIES,
         },
         additionalProperties: false,
@@ -160,7 +246,7 @@ registerTool({
     outputSchema: OUTPUT_SCHEMA_IMAGE_AND_JSON,
     annotations: { title: "BaZi Four Pillars Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
-        const body = { ...parseBaziArgs(args) };
+        const body = { ...parseBaziArgs(args), ...buildBaziConventionFields(args) };
         applyVisualConfig(body, args);
         return await getActiveClient().request("POST", "/chinese/bazi", { data: body });
     },
@@ -190,6 +276,7 @@ registerTool({
         type: "object",
         properties: {
             ...DATETIME_PROPERTIES,
+            ...CONVENTION_PROPERTIES,
             ...VISUAL_PROPERTIES,
         },
         additionalProperties: false,
@@ -197,7 +284,7 @@ registerTool({
     outputSchema: OUTPUT_SCHEMA_IMAGE_AND_JSON,
     annotations: { title: "BaZi Ten Gods", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
-        const body = { ...parseBaziArgs(args) };
+        const body = { ...parseBaziArgs(args), ...buildBaziConventionFields(args) };
         applyVisualConfig(body, args);
         return await getActiveClient().request("POST", "/chinese/bazi/ten-gods", { data: body });
     },
@@ -225,6 +312,7 @@ registerTool({
         type: "object",
         properties: {
             ...DATETIME_PROPERTIES,
+            ...CONVENTION_PROPERTIES,
             ...VISUAL_PROPERTIES,
         },
         additionalProperties: false,
@@ -232,7 +320,7 @@ registerTool({
     outputSchema: OUTPUT_SCHEMA_IMAGE_AND_JSON,
     annotations: { title: "BaZi Element Balance", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
-        const body = { ...parseBaziArgs(args) };
+        const body = { ...parseBaziArgs(args), ...buildBaziConventionFields(args) };
         applyVisualConfig(body, args);
         return await getActiveClient().request("POST", "/chinese/bazi/element-balance", { data: body });
     },
@@ -261,6 +349,7 @@ registerTool({
         type: "object",
         properties: {
             ...DATETIME_PROPERTIES,
+            ...CONVENTION_PROPERTIES,
             gender: {
                 type: "string",
                 enum: ["male", "female"],
@@ -279,10 +368,15 @@ registerTool({
             throw new Error("gender is required for luck pillar calculation. " +
                 "Provide 'male' or 'female' — the direction of Da Yun depends on gender and year polarity.");
         }
-        const { year, month, day, hour } = parseBaziArgs(args);
-        const body = { year, month, day, gender: args.gender };
+        const { year, month, day, hour, minute } = parseBaziArgs(args);
+        const body = {
+            year, month, day, gender: args.gender,
+            ...buildBaziConventionFields(args),
+        };
         if (hour != null)
             body.hour = hour;
+        if (minute != null)
+            body.minute = minute;
         return await getActiveClient().request("POST", "/chinese/bazi/luck-pillars", { data: body });
     },
 });
@@ -362,9 +456,10 @@ registerTool({
             },
             chart_a_timezone: {
                 type: "string",
-                description: "IANA timezone for Chart A's birth place, e.g. 'Asia/Shanghai'. Only needed when " +
-                    "chart_a_datetime carries a 'Z' or ±HH:MM offset.",
+                description: "IANA timezone for Chart A's birth place, e.g. 'Asia/Shanghai'. Needed when " +
+                    "chart_a_datetime carries a 'Z' or ±HH:MM offset; also frames Chart A's year/month boundary.",
             },
+            ...chartConventionProperties("A"),
             // Chart B
             chart_b_year: { type: "integer", description: "Chart B birth year." },
             chart_b_month: { type: "integer", description: "Chart B birth month (1–12)." },
@@ -378,9 +473,10 @@ registerTool({
             },
             chart_b_timezone: {
                 type: "string",
-                description: "IANA timezone for Chart B's birth place, e.g. 'Asia/Shanghai'. Only needed when " +
-                    "chart_b_datetime carries a 'Z' or ±HH:MM offset.",
+                description: "IANA timezone for Chart B's birth place, e.g. 'Asia/Shanghai'. Needed when " +
+                    "chart_b_datetime carries a 'Z' or ±HH:MM offset; also frames Chart B's year/month boundary.",
             },
+            ...chartConventionProperties("B"),
         },
         additionalProperties: false,
     },
@@ -392,6 +488,7 @@ registerTool({
             month: args.chart_a_month,
             day: args.chart_a_day,
             hour: args.chart_a_hour,
+            minute: args.chart_a_minute,
             datetime: args.chart_a_datetime,
             timezone: args.chart_a_timezone,
         });
@@ -400,13 +497,14 @@ registerTool({
             month: args.chart_b_month,
             day: args.chart_b_day,
             hour: args.chart_b_hour,
+            minute: args.chart_b_minute,
             datetime: args.chart_b_datetime,
             timezone: args.chart_b_timezone,
         });
         return await getActiveClient().request("POST", "/chinese/bazi/compatibility", {
             data: {
-                chart_a: chartAComponents,
-                chart_b: chartBComponents,
+                chart_a: { ...chartAComponents, ...buildBaziConventionFieldsPrefixed(args, "chart_a") },
+                chart_b: { ...chartBComponents, ...buildBaziConventionFieldsPrefixed(args, "chart_b") },
             },
         });
     },
@@ -434,6 +532,7 @@ registerTool({
         type: "object",
         properties: {
             ...DATETIME_PROPERTIES,
+            ...CONVENTION_PROPERTIES,
             theme: {
                 type: "string",
                 enum: ["light", "dark", "mono"],
@@ -449,7 +548,7 @@ registerTool({
     outputSchema: OUTPUT_SCHEMA_IMAGE_AND_JSON,
     annotations: { title: "BaZi Chart (Visual)", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
-        const { year, month, day, hour } = parseBaziArgs(args);
+        const { year, month, day, hour, minute } = parseBaziArgs(args);
         const body = {
             year, month, day,
             visual_config: {
@@ -457,9 +556,12 @@ registerTool({
                 theme: args.theme ?? "light",
                 size: args.size ?? 800,
             },
+            ...buildBaziConventionFields(args),
         };
         if (hour != null)
             body.hour = hour;
+        if (minute != null)
+            body.minute = minute;
         return await getActiveClient().request("POST", "/chinese/bazi/chart", { data: body });
     },
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openephemeris/mcp-server",
-  "version": "4.8.1",
+  "version": "4.10.0",
   "description": "Model Context Protocol server for the Open Ephemeris astronomical computation API",
   "type": "module",
   "main": "dist/index.js",