@openephemeris/mcp-server 4.11.0 → 4.11.2

package/CHANGELOG.md

@@ -7,6 +7,55 @@ Version numbering follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [4.11.2] — 2026-08-13
+
+### Fixed
+- **Location resolver rejected `"City, Country"` as ambiguous.** The
+  ambiguity qualifier matched a region name, a US state abbreviation, or a
+  two-letter ISO country *code* — but never a country *name*. So
+  `location: "Paris, France"` lost the qualification check against its US
+  namesakes and threw, while the far rarer `"Paris, fr"` resolved fine.
+  Live, `"Paris, France"` matches 8 same-named places and `"London, UK"`
+  matches 6, so the most natural phrasing for a foreign birthplace failed
+  outright. Country names now qualify via `Intl.DisplayNames` (the runtime's
+  own code→name table, so there is no list to maintain), plus colloquial
+  aliases Intl doesn't emit (`uk` → GB). Completes the class of fix started
+  for US state abbreviations in 4.11.1.
+
+### Changed
+- **Location resolver errors now carry a stable `code`.** `mcp_tool_error`
+  telemetry records no message and no stack, so every resolver rejection
+  arrived as `code: "none"` / `error_kind: "local"` — indistinguishable from
+  a genuine server-side crash. Throws now carry `location_ambiguous`,
+  `location_not_found`, `location_missing_coordinates`, `location_empty`, or
+  `coords_partial` on the property the event already ships. The codes are
+  constants; no user input is added to telemetry.
+
+---
+
+## [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,24 +15,68 @@
 // 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",
+};
+// The API reports the country as an ISO code ("FR"), but callers type the
+// country *name* — "Paris, France" is the phrasing a model reaches for when
+// it has a foreign birthplace. Matching only the code meant that query lost
+// the qualification check against its US namesake (Paris, TX) and threw
+// ambiguous, while the far rarer "Paris, fr" resolved fine. Intl.DisplayNames
+// is the runtime's own code→name table, so there is no list to keep in sync.
+const REGION_NAMES = new Intl.DisplayNames(["en"], { type: "region" });
+function countryNameFor(code) {
+    try {
+        return String(REGION_NAMES.of(code.toUpperCase()) ?? "").toLowerCase();
+    }
+    catch {
+        return ""; // not a valid region subtag — fall through to the other checks
+    }
+}
+// Colloquial forms Intl does not produce: it renders GB as "United Kingdom",
+// so a bare "uk" token would otherwise miss.
+const COUNTRY_ALIASES = { uk: "gb", usa: "us", uae: "ae" };
+// `code` rides along to PostHog via the existing `code` property on
+// mcp_tool_error. The event deliberately records no message or stack, so
+// without a code every one of these lands as code:"none" / error_kind:"local"
+// and is indistinguishable from a genuine server-side crash.
+function codedError(code, message) {
+    return Object.assign(new Error(message), { code });
+}
 /**
  * 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();
     if (query === "") {
-        throw new Error("location is empty");
+        throw codedError("location_empty", "location is empty");
     }
     const raw = (await getActiveClient().request("GET", "/location/autocomplete", {
         params: { query },
     }));
     const list = Array.isArray(raw?.suggestions) ? raw.suggestions : [];
     if (list.length === 0) {
-        throw new Error(`location "${query}" did not match any known place. Call location_search directly to inspect suggestions, ` +
+        throw codedError("location_not_found", `location "${query}" did not match any known place. Call location_search directly to inspect suggestions, ` +
             `or supply latitude/longitude explicitly.`);
     }
     const norm = (v) => String(v ?? "").trim().toLowerCase();
@@ -40,18 +84,24 @@ 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))) ||
-        (norm(top.country_code) !== "" && qTokens.has(norm(top.country_code)));
+    const topRegion = norm(top.region);
+    const topCountry = norm(top.country_code);
+    const topCountryName = topCountry === "" ? "" : countryNameFor(topCountry);
+    const qualified = (topRegion !== "" && q.includes(topRegion)) ||
+        (topRegion !== "" && [...qTokens].some((t) => US_STATE_ABBREVIATIONS[t] === topRegion)) ||
+        (topCountry !== "" && qTokens.has(topCountry)) ||
+        (topCountryName !== "" && q.includes(topCountryName)) ||
+        (topCountry !== "" && [...qTokens].some((t) => COUNTRY_ALIASES[t] === topCountry));
     const ambiguous = rivals.length > 1 && !qualified;
     if (ambiguous) {
         const options = rivals
             .slice(0, 4)
             .map((s) => `${s.display_name ?? s.short_name} (${s.country_code ?? "??"})`)
             .join("; ");
-        throw new Error(`location "${query}" is ambiguous — matches ${rivals.length} places (${options}${rivals.length > 4 ? ", …" : ""}). Call location_search directly and pass the disambiguated place, or supply latitude/longitude explicitly.`);
+        throw codedError("location_ambiguous", `location "${query}" is ambiguous — matches ${rivals.length} places (${options}${rivals.length > 4 ? ", …" : ""}). Call location_search directly and pass the disambiguated place, or supply latitude/longitude explicitly.`);
     }
     if (top.latitude == null || top.longitude == null) {
-        throw new Error(`location "${query}" matched "${top.display_name ?? top.short_name}" but the record is missing coordinates. ` +
+        throw codedError("location_missing_coordinates", `location "${query}" matched "${top.display_name ?? top.short_name}" but the record is missing coordinates. ` +
             `Supply latitude/longitude explicitly.`);
     }
     return {
@@ -80,7 +130,7 @@ export async function coordsFromArgsOrLocation(args) {
         return { latitude: lat, longitude: lon, timezone: tz, location: loc, resolvedFromLocation: false };
     }
     if (latSet !== lonSet) {
-        throw new Error("latitude and longitude must both be supplied (or both omitted with a `location` name).");
+        throw codedError("coords_partial", "latitude and longitude must both be supplied (or both omitted with a `location` name).");
     }
     if (!loc || String(loc).trim() === "") {
         // Neither coords nor location — leave undefined; the tool's own

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.2",
   "description": "Model Context Protocol server for the Open Ephemeris astronomical computation API",
   "type": "module",
   "main": "dist/index.js",