@openephemeris/mcp-server 4.11.0 → 4.11.1

package/CHANGELOG.md

@@ -7,6 +7,29 @@ Version numbering follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [4.11.1] — 2026-08-12
+
+### Fixed
+- **Location resolver didn't recognize US state abbreviations.**
+  `location: "San Francisco, CA"` was rejected as ambiguous while the
+  equivalent `"San Francisco, California"` resolved fine — the API returns
+  the full state name in `region`, and the ambiguity qualifier only matched
+  full-name substrings or ISO country-code tokens. Added a USPS abbreviation
+  lookup (50 states + DC + territories) so `"City, ST"` qualifies the same
+  as `"City, State Name"`.
+- **`bazi_recalculate` double-charged for theme-only re-renders.** Its only
+  caller is the BaZi app's automatic host-theme reconciliation — never a
+  birth-data change — but it billed the full 3 credits as if it were a fresh
+  chart, on top of the identical charge already paid via `explore_bazi_chart`
+  moments earlier. Theme-only reconcile now skips the 2-credit visual-render
+  reservation.
+- **Datetime tool descriptions could invite a silent 1-hour-off chart.**
+  Extended the shared datetime contract instructions to explicitly tell
+  callers to pass local wall-clock time + IANA `timezone` rather than
+  converting to UTC themselves — a calling model's own conversion mistake
+  (e.g. treating July San Francisco as PST instead of PDT) previously sailed
+  through with zero server-side errors and a confidently wrong chart.
+
 ## [4.11.0] — 2026-08-07
 
 ### Fixed

package/dist/tools/apps/_location-resolver.d.ts

@@ -10,7 +10,7 @@ export interface ResolvedLocation {
  *
  * Ambiguity is detected the same way `location_search` reports it — a
  * count of *rivals* for the top short_name, unless the query itself
- * qualifies the place (e.g. "portland uk", "dallas texas").
+ * qualifies the place (e.g. "portland uk", "dallas texas", "dallas, tx").
  */
 export declare function resolveLocationOrThrow(location: string): Promise<ResolvedLocation>;
 /**

package/dist/tools/apps/_location-resolver.js

@@ -15,12 +15,31 @@
 // produces a chart nothing downstream can detect as wrong. Same failure
 // class as the naive-UTC ASC and the unlabelled cusp longitudes.
 import { getActiveClient } from "../../backend/client.js";
+// The API returns the full state name in `region` ("Oregon", not "OR"), but
+// most callers naturally type the USPS abbreviation ("Portland, OR"). Without
+// this table, "San Francisco, CA" was flagged ambiguous while the equivalent
+// "San Francisco, California" resolved fine — same query, arbitrarily
+// different outcome depending on which form the caller happened to type.
+const US_STATE_ABBREVIATIONS = {
+    al: "alabama", ak: "alaska", az: "arizona", ar: "arkansas", ca: "california",
+    co: "colorado", ct: "connecticut", de: "delaware", fl: "florida", ga: "georgia",
+    hi: "hawaii", id: "idaho", il: "illinois", in: "indiana", ia: "iowa",
+    ks: "kansas", ky: "kentucky", la: "louisiana", me: "maine", md: "maryland",
+    ma: "massachusetts", mi: "michigan", mn: "minnesota", ms: "mississippi", mo: "missouri",
+    mt: "montana", ne: "nebraska", nv: "nevada", nh: "new hampshire", nj: "new jersey",
+    nm: "new mexico", ny: "new york", nc: "north carolina", nd: "north dakota", oh: "ohio",
+    ok: "oklahoma", or: "oregon", pa: "pennsylvania", ri: "rhode island", sc: "south carolina",
+    sd: "south dakota", tn: "tennessee", tx: "texas", ut: "utah", vt: "vermont",
+    va: "virginia", wa: "washington", wv: "west virginia", wi: "wisconsin", wy: "wyoming",
+    dc: "district of columbia", pr: "puerto rico", vi: "virgin islands", gu: "guam",
+    as: "american samoa", mp: "northern mariana islands",
+};
 /**
  * Resolve a place name to lat/lon/tz. Throws if ambiguous or unresolvable.
  *
  * Ambiguity is detected the same way `location_search` reports it — a
  * count of *rivals* for the top short_name, unless the query itself
- * qualifies the place (e.g. "portland uk", "dallas texas").
+ * qualifies the place (e.g. "portland uk", "dallas texas", "dallas, tx").
  */
 export async function resolveLocationOrThrow(location) {
     const query = location.trim();
@@ -40,7 +59,9 @@ export async function resolveLocationOrThrow(location) {
     const rivals = list.filter((s) => norm(s.short_name) === norm(top.short_name));
     const q = norm(query);
     const qTokens = new Set(q.split(/[^a-z0-9]+/).filter(Boolean));
-    const qualified = (norm(top.region) !== "" && q.includes(norm(top.region))) ||
+    const topRegion = norm(top.region);
+    const qualified = (topRegion !== "" && q.includes(topRegion)) ||
+        (topRegion !== "" && [...qTokens].some((t) => US_STATE_ABBREVIATIONS[t] === topRegion)) ||
         (norm(top.country_code) !== "" && qTokens.has(norm(top.country_code)));
     const ambiguous = rivals.length > 1 && !qualified;
     if (ambiguous) {

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

@@ -66,13 +66,16 @@ 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", conventionFields = {}) {
+async function fetchBaziChart(components, theme = "dark", conventionFields = {}, reconcile = false) {
     const client = getActiveClient();
     const body = {
         ...components,
         ...conventionFields,
         include_visual: true,
         visual_config: { format: "svg", theme, size: 800 },
+        // Set only by bazi_recalculate's theme-reconcile path below — waives the
+        // visual surcharge server-side for a same-birth-data re-render (#551).
+        ...(reconcile ? { _visual_reconcile: true } : {}),
     };
     return await client.request("POST", "/chinese/bazi", { data: body });
 }
@@ -194,7 +197,11 @@ registerTool({
 // ── Tool: bazi_recalculate [app-only] ────────────────────────────────────────
 registerTool({
     name: "bazi_recalculate",
-    description: "Recalculates a BaZi Four Pillars chart with new birth data or theme.",
+    description: "Recalculates a BaZi Four Pillars chart with new birth data or theme. " +
+        "App-only: called by the embedded chart itself to reconcile the initial " +
+        "server-rendered SVG to the host's actual light/dark theme. Billed at 1 " +
+        "credit (base only) — the visual-render surcharge is waived because this " +
+        "re-renders already-computed data, not a new chart.",
     inputSchema: {
         type: "object",
         properties: {
@@ -216,7 +223,7 @@ registerTool({
     handler: async (args) => {
         const components = parseBaziArgs(args);
         const theme = args.theme === "light" ? "light" : "dark";
-        const data = await fetchBaziChart(components, theme);
+        const data = await fetchBaziChart(components, theme, {}, true);
         const payload = buildModelPayload(data, components, theme);
         return {
             content: [{ type: "text", text: JSON.stringify({ ...payload, server_version: SERVER_VERSION }) }],

package/dist/tools/datetime.js

@@ -81,7 +81,16 @@ export const DATETIME_CONTRACT_INSTRUCTIONS = "Datetime contract: every clock ti
     "the naive local time and name the zone in the sibling `timezone` argument (IANA name, " +
     "e.g. `America/Chicago`). A zone-less clock time is a hard 400 — the engine never " +
     "guesses UTC, because an unstated zone shifts the Ascendant by ~15° per hour and moves " +
-    "every house placement. A bare date (no clock time) resolves to 12:00 UTC.";
+    "every house placement. A bare date (no clock time) resolves to 12:00 UTC.\n\n" +
+    "PREFER the local-time + `timezone` form over converting to UTC yourself. The server " +
+    "resolves the IANA zone against the actual date, including historical DST rules — that " +
+    "arithmetic (which offset applied on that specific day, in that specific year) is easy " +
+    "to get wrong by hand and the server will not catch it: a value that already carries a " +
+    "`Z`/±HH:MM suffix is trusted as the stated instant, so a self-computed offset that is " +
+    "off by an hour (e.g. daylight vs. standard time) produces a chart that is confidently " +
+    "wrong with no error raised. If the user states a local clock time (\"2:30 PM in San " +
+    "Francisco\"), pass that wall-clock string verbatim with `timezone` — do not do the " +
+    "UTC conversion mentally first.";
 // ─── Enforcement ─────────────────────────────────────────────────────────────
 /**
  * The rejection message. Names both remedies, rewriting the caller's own value

package/package.json

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