@openephemeris/mcp-server 4.6.0 → 4.8.0

package/CHANGELOG.md

@@ -7,6 +7,75 @@ Version numbering follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [4.8.0] — 2026-08-02
+
+### Added
+- **Toolsets by tradition.** Tool definitions are re-sent to the model on every
+  message, so callers who work in one tradition can now advertise just that
+  tradition instead of the general-purpose default: `OPENEPHEMERIS_TOOLS=hd`
+  (stdio) or `?profile=hd,bazi` (hosted). Eight toolsets — `astrology`, `moon`,
+  `hd`, `bazi`, `vedic`, `acg`, `electional`, `venus` — each including
+  geocoding, account usage, and the API escape hatch. A Human Design session
+  drops from ~19,100 to ~7,800 advertised tokens (−59%); Vedic to ~3,400
+  (−82%). `astrology,moon` matches the default's tool count at ~1,700 fewer
+  tokens while covering the long tail (dignities, midpoints, hermetic lots,
+  fixed stars, composites) the curated set omits. As with `core`/`full`, this
+  filters `tools/list` only — every tool stays callable by name. Also exposed
+  as the `toolSurface` option in the Smithery config.
+
+### Fixed
+- `explore_human_design` now states its real credit cost: 4 where the bodygraph
+  renders (2 chart + 2 visual), 2 in text-only hosts — it previously claimed a
+  flat 2. `ephemeris_moon_phase` (2, not 1) and `ephemeris_next_lunar_phase`
+  (1–2 per occurrence) corrected the same way.
+- `explore_bi_wheel` in synastry mode now requires Person 2's coordinates (or a
+  resolvable `person2_location`) instead of silently casting Person 2's chart
+  for 0°N 0°E.
+- Chart-wheel widget escapes birth parameters before rendering them into the
+  info chips.
+- OAuth token endpoint binds authorization codes to their `redirect_uri` and
+  `client_id`; both checks were previously skippable by omitting the parameter.
+
+---
+
+## [4.7.0] — 2026-08-02
+
+Historically correct birth-time conversion. IANA timezone databases — including
+the one inside every JavaScript runtime — are only authoritative from 1970.
+Before the US Uniform Time Act took effect in 1967, daylight saving was state
+and municipal law, and a zone like `America/Chicago` models Chicago alone. A
+1961 Minnesota birth converted with standard timezone math lands an hour off,
+which flips the Ascendant sign and the Human Design design-Moon gate.
+
+### Added
+
+- **Pre-1970 births now resolve through the API's historical correction
+  overlay.** Any tool given a naive local birth time with a timezone and
+  coordinates — natal, Human Design (chart, composite, penta, cycles, groups),
+  Vedic, BaZi apps, ACG, moon tools, and the embedded chart apps — routes the
+  local→UTC conversion through the API's `/timezone/offset` `datetime_local`
+  mode, which applies primary-source-cited state and local law (with a
+  `tz_confidence` grade and rule citation) instead of assuming the reference
+  city's rules. Post-1970 conversions stay on the local, zero-latency path,
+  which is exactly as authoritative as the server. If the server is
+  unreachable, tools fall back to the previous local conversion rather than
+  failing the chart call.
+- **`timezone_resolve`** consults the same historical path for pre-1970 dates
+  and reports `tzConfidence`, `tzRuleSource`, and `datetimeStatus` (ambiguous
+  DST-fold and nonexistent-gap times are called out explicitly).
+- **`location_search`** tags each suggestion's historical offset with a
+  confidence grade and a note when a pre-1970 date may be affected by
+  state/local law divergence.
+
+### Fixed
+
+- Three skills and one prompt still instructed the model to convert local
+  birth times to UTC itself with generic timezone math — the exact manual
+  conversion the historical overlay exists to prevent. They now direct all
+  conversion through the API.
+
+---
+
 ## [4.6.0] — 2026-07-30
 
 Fixes the tool that could not answer the question it is named for, closes the

package/README.md

@@ -358,6 +358,38 @@ On the remote HTTP server, append `?profile=full` to the connector URL (or send
 https://mcp.openephemeris.com/mcp?profile=full
 ```
 
+### Toolsets by tradition
+
+If you work in one tradition, ask for it by name instead of taking the general-purpose default. You get that tradition in full — including the long-tail tools the core set leaves out — for a fraction of the context.
+
+```bash
+OPENEPHEMERIS_TOOLS=hd npx -y @openephemeris/mcp-server        # Human Design
+OPENEPHEMERIS_TOOLS=astrology,moon npx -y @openephemeris/mcp-server
+```
+
+```
+https://mcp.openephemeris.com/mcp?profile=hd,bazi
+```
+
+| Toolset | What it covers | Tools | Approx. tokens |
+|---|---|---:|---:|
+| `astrology` | Natal, transits, synastry, progressions, returns, relocation, dignities, midpoints, lots, fixed stars, composites | 32 | 15,800 |
+| `hd` | Human Design charts, transits, connection charts, penta, bodygraph | 14 | 7,800 |
+| `bazi` | Four Pillars, Ten Gods, element balance, luck pillars, compatibility | 13 | 7,200 |
+| `electional` | Timing windows, angle crossings, stations, moment analysis | 10 | 4,600 |
+| `moon` | Phases, void-of-course, eclipses | 9 | 4,100 |
+| `venus` | Star points, phases, elongations, stations | 11 | 3,700 |
+| `acg` | Astrocartography lines and hits | 7 | 3,700 |
+| `vedic` | Jyotish Rashi chart | 7 | 3,400 |
+| — | *core (default)* | 36 | 19,100 |
+| — | *full* | 70 | 34,600 |
+
+Every selection also includes geocoding (`location_search`, `timezone_resolve`), `account_usage`, and the allowlist-gated proxy — so a birthplace is always resolvable and nothing is stranded.
+
+Combine with commas; unknown names are ignored rather than rejected, so a typo degrades to a smaller surface instead of a dead connector. As with `core`/`full`, this only filters `tools/list` — every tool remains callable by name.
+
+Why it matters: tool definitions are re-sent to the model on **every** pass. `astrology,moon` advertises the same number of tools as the default but costs ~1,700 fewer tokens per message and covers more of the tradition.
+
 The surface is fixed when the session initializes — this server does not advertise `tools.listChanged`, so switching requires reconnecting. `dev_list_allowed` enumerates every operation reachable through the generic proxy regardless of surface.
 
 ## Contributing & Support
@@ -443,8 +475,8 @@ Generated by `npm run sync:readme` from `config/dev-allowlist.json` and the live
 - Allowlisted operations: **31**
 - Methods: `GET=5`, `POST=26`, `PUT=0`, `PATCH=0`, `DELETE=0`
 - Registered tools (`OPENEPHEMERIS_PROFILE=dev`): **92**
-- Typed tools: `account_usage`, `acg_hits`, `acg_power_lines`, `auth_login`, `auth_logout`, `auth_status`, `bazi_annual_pillar`, `bazi_chart`, `bazi_compatibility`, `bazi_element_balance`, `bazi_luck_pillars`, `bazi_recalculate`, `bazi_ten_gods`, `bi_wheel_on_cross_aspect_click`, `bi_wheel_on_house_click`, `bi_wheel_on_planet_click`, `bi_wheel_recalculate`, `bi_wheel_synopsis`, `bodygraph_recalculate`, `chart_wheel_on_aspect_click`, `chart_wheel_on_house_click`, `chart_wheel_on_planet_click`, `chart_wheel_recalculate`, `chinese_bazi`, `dev_list_allowed`, `dev_read_api`, `dev_write_api`, `electional_angle_crossings`, `electional_aspect_search`, `electional_moment_analysis`, `electional_station_tracker`, `ephemeris_angles_points`, `ephemeris_aspect_check`, `ephemeris_bi_wheel`, `ephemeris_chart_wheel`, `ephemeris_composite`, `ephemeris_composite_midpoint`, `ephemeris_dignities`, `ephemeris_electional`, `ephemeris_fixed_stars`, `ephemeris_hermetic_lots`, `ephemeris_house_cusps`, `ephemeris_lunar_return`, `ephemeris_midpoints`, `ephemeris_moon_phase`, `ephemeris_natal_batch`, `ephemeris_natal_chart`, `ephemeris_natal_transits`, `ephemeris_next_eclipse`, `ephemeris_next_lunar_phase`, `ephemeris_overlay`, `ephemeris_planet_position`, `ephemeris_planetary_return`, `ephemeris_progressed_chart`, `ephemeris_relocation`, `ephemeris_retrograde_status`, `ephemeris_solar_return`, `ephemeris_synastry`, `ephemeris_transits`, `explore_bazi_chart`, `explore_bi_wheel`, `explore_human_design`, `explore_human_design_connection`, `explore_human_design_transit`, `explore_moon_phase`, `explore_natal_chart`, `explore_transit_timeline`, `explore_vedic_chart`, `hd_on_center_click`, `hd_on_channel_click`, `hd_on_connection_channel_click`, `hd_on_gate_click`, `hd_on_planet_click`, `hd_on_transit_channel_click`, `hd_on_variable_click`, `hd_opposition`, `hd_planetary_return`, `human_design_bodygraph`, `human_design_chart`, `human_design_composite`, `human_design_penta`, `location_search`, `moon_phase_recalculate`, `timezone_resolve`, `vedic_chart`, `vedic_chart_recalculate`, `venus_eight_year_star`, `venus_elongations`, `venus_phase`, `venus_star_points`, `venus_star_points_conjunctions`, `venus_stations`
-- Generic tools: 
+- Typed tools: `account_usage`, `acg_hits`, `acg_power_lines`, `auth_login`, `auth_logout`, `auth_status`, `bazi_annual_pillar`, `bazi_chart`, `bazi_compatibility`, `bazi_element_balance`, `bazi_luck_pillars`, `bazi_recalculate`, `bazi_ten_gods`, `bi_wheel_on_cross_aspect_click`, `bi_wheel_on_house_click`, `bi_wheel_on_planet_click`, `bi_wheel_recalculate`, `bi_wheel_synopsis`, `bodygraph_recalculate`, `chart_wheel_on_aspect_click`, `chart_wheel_on_house_click`, `chart_wheel_on_planet_click`, `chart_wheel_recalculate`, `chinese_bazi`, `electional_angle_crossings`, `electional_aspect_search`, `electional_moment_analysis`, `electional_station_tracker`, `ephemeris_angles_points`, `ephemeris_aspect_check`, `ephemeris_bi_wheel`, `ephemeris_chart_wheel`, `ephemeris_composite`, `ephemeris_composite_midpoint`, `ephemeris_dignities`, `ephemeris_electional`, `ephemeris_fixed_stars`, `ephemeris_hermetic_lots`, `ephemeris_house_cusps`, `ephemeris_lunar_return`, `ephemeris_midpoints`, `ephemeris_moon_phase`, `ephemeris_natal_batch`, `ephemeris_natal_chart`, `ephemeris_natal_transits`, `ephemeris_next_eclipse`, `ephemeris_next_lunar_phase`, `ephemeris_overlay`, `ephemeris_planet_position`, `ephemeris_planetary_return`, `ephemeris_progressed_chart`, `ephemeris_relocation`, `ephemeris_retrograde_status`, `ephemeris_solar_return`, `ephemeris_synastry`, `ephemeris_transits`, `explore_bazi_chart`, `explore_bi_wheel`, `explore_human_design`, `explore_human_design_connection`, `explore_human_design_transit`, `explore_moon_phase`, `explore_natal_chart`, `explore_transit_timeline`, `explore_vedic_chart`, `hd_on_center_click`, `hd_on_channel_click`, `hd_on_connection_channel_click`, `hd_on_gate_click`, `hd_on_planet_click`, `hd_on_transit_channel_click`, `hd_on_variable_click`, `hd_opposition`, `hd_planetary_return`, `human_design_bodygraph`, `human_design_chart`, `human_design_composite`, `human_design_penta`, `location_search`, `moon_phase_recalculate`, `timezone_resolve`, `vedic_chart`, `vedic_chart_recalculate`, `venus_eight_year_star`, `venus_elongations`, `venus_phase`, `venus_star_points`, `venus_star_points_conjunctions`, `venus_stations`
+- Generic tools: `dev_list_allowed`, `dev_read_api`, `dev_write_api`
 
 ### Allowlist Families
 
@@ -466,5 +498,5 @@ Most LLMs (like Claude and ChatGPT) struggle heavily with astronomical calculati
 
 By pairing LLMs with the OpenEphemeris MCP server, your agents can instantly access:
 - **Zero-hallucination coordinates**: Direct, sub-arcsecond NASA JPL DE440 calculations spanning 1,100 years of astronomical data.
-- **LLM-optimized tokens (`format=llm`)**: We compress standard 25,000 token JSON chart responses into minimal text blocks, cutting your inference costs by 50%.
+- **LLM-optimized tokens (`format=llm`)**: We compress standard 25,000 token JSON chart responses into minimal text blocks, cutting your inference costs by 50–73% depending on endpoint.
 - **Ready-to-use astrology layers**: Built-in support for Astrocartography geoJSON lines, Hermetic Lots, Fixed Stars, and complex Human Design matrix generation.

package/dist/index.js

@@ -73,9 +73,12 @@ const server = new Server({
         "See the 'welcome_to_open_ephemeris' prompt for orientation.\n\n" +
         DATETIME_CONTRACT_INSTRUCTIONS,
 });
-// Which slice of the registry this process advertises. Tools outside the core
+// Which slice of the registry this process advertises. Tools outside the
 // surface stay callable by name — this only controls what tools/list returns.
-// Set OPENEPHEMERIS_TOOLS=full to advertise everything.
+//   OPENEPHEMERIS_TOOLS=full      advertise everything
+//   OPENEPHEMERIS_TOOLS=hd,bazi   advertise those traditions (+ geocoding,
+//                                 account and the escape hatch)
+//   unset                          the curated core set
 const STDIO_SURFACE = parseToolSurface(process.env.OPENEPHEMERIS_TOOLS);
 /**
  * Stable pseudonymous id for this install. Derived from the configured

package/dist/oauth/token.js

@@ -106,11 +106,38 @@ async function handleAuthorizationCode(req, res, store) {
         });
         return;
     }
-    // Verify redirect_uri exact match
-    if (redirect_uri && !timingSafeStringEqual(redirect_uri, stored.redirect_uri)) {
+    // Verify redirect_uri exact match.
+    //
+    // This used to read `if (redirect_uri && ...)`, so a client that simply omitted
+    // the parameter skipped the check entirely. RFC 6749 §4.1.3 requires the value
+    // to be present AND identical whenever the authorization request carried one,
+    // precisely so a dropped parameter cannot be the bypass. PKCE still gates the
+    // exchange, but that is the last line, not the only one.
+    if (stored.redirect_uri) {
+        if (!redirect_uri) {
+            res.status(400).json({
+                error: "invalid_request",
+                error_description: "Missing redirect_uri. It is required because the authorization request included one.",
+            });
+            return;
+        }
+        if (!timingSafeStringEqual(redirect_uri, stored.redirect_uri)) {
+            res.status(400).json({
+                error: "invalid_grant",
+                error_description: "redirect_uri does not match the value used during authorization.",
+            });
+            return;
+        }
+    }
+    // Bind the code to the client it was issued to. `client_id` was read off the
+    // request but never compared, so any client holding the verifier could redeem
+    // another client's code. DCR client_ids are deterministic and non-secret
+    // (see oauth/dcr.ts), which makes this binding the only thing distinguishing
+    // one registered client from another.
+    if (stored.client_id && client_id && !timingSafeStringEqual(client_id, stored.client_id)) {
         res.status(400).json({
             error: "invalid_grant",
-            error_description: "redirect_uri does not match the value used during authorization.",
+            error_description: "client_id does not match the client the authorization code was issued to.",
         });
         return;
     }

package/dist/prompts.js

@@ -377,8 +377,9 @@ export const PROMPTS = [
             "even 10–15 minutes can shift the Type, Authority, or Profile. If truly unknown, " +
             "proceed with solar noon but flag that results may be imprecise.\n" +
             "4. **Birth city and country** — needed for timezone conversion\n\n" +
-            "## Step 2 — CRITICAL: Convert to UTC\n" +
-            "Human Design requires **UTC datetime**. The tool rejects local times without a UTC offset.\n\n" +
+            "## Step 2 — Resolve Coordinates and Timezone\n" +
+            "Human Design needs the exact birth instant; the tool resolves it from local time + " +
+            "timezone + coordinates automatically (historically correct even pre-1970).\n\n" +
             "**Resolve the birth place with `location_search`** — pass `query: 'Birth City, Country'` " +
             "and `date` set to the birth date (`YYYY-MM-DD`). One call returns decimal lat/lon, the " +
             "IANA timezone, and `utcOffsetAtDate` — the offset that actually applied at that place on " +

package/dist/server-sse.js

@@ -23,7 +23,7 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
 import { InMemoryEventStore } from "./event-store.js";
 import { captureEvent, distinctIdFor } from "./analytics.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, isInitializeRequest, } from "@modelcontextprotocol/sdk/types.js";
-import { initTools, toolRegistry, formatToolResponse, formatToolError, modelVisibleTools, parseToolSurface } from "./tools/index.js";
+import { initTools, toolRegistry, formatToolResponse, formatToolError, modelVisibleTools, parseToolSurface, describeSurface } from "./tools/index.js";
 import { DATETIME_CONTRACT_INSTRUCTIONS } from "./tools/datetime.js";
 import { BackendClient, runWithClient } from "./backend/client.js";
 import { CHART_WHEEL_RESOURCE_URI, CHART_WHEEL_MIME_TYPE, getChartWheelBundle, } from "./tools/apps/chart-wheel-app.js";
@@ -215,7 +215,10 @@ function transportProps(server, surface) {
     const info = server.getClientVersion();
     return {
         transport: "http",
-        surface,
+        // describeSurface, not the raw value: a toolset selection is an object and
+        // would land in PostHog as "[object Object]", making the property useless
+        // for exactly the question it exists to answer — which surfaces get used.
+        surface: describeSurface(surface),
         client_name: info?.name ?? "unknown",
         client_version: info?.version ?? "unknown",
         server_version: version,
@@ -848,6 +851,8 @@ export async function createSseApp() {
         // `tools.listChanged`, so a host has no obligation to re-fetch the list.
         // Opt into the full surface with `?profile=full` on the connector URL, or
         // an `X-OE-Tool-Surface: full` header where the host allows custom headers.
+        // A comma list of traditions works the same way — `?profile=hd,bazi` —
+        // and advertises just those plus geocoding, account and the escape hatch.
         const surface = parseToolSurface(req.query.profile ?? req.headers["x-oe-tool-surface"]);
         const server = createMcpServer(analyticsId, surface);
         // Fire session_init after the handshake so getClientVersion() is populated

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

@@ -115,9 +115,9 @@ registerTool({
         "(Year = ancestry/early life, Month = parents/career, Day = self/spouse, Hour = children/later life).\n\n" +
         "CREDIT COST: 3 credits per call (1 base + 2 visual render).\n\n" +
         "Use this for a rich, interactive BaZi experience in MCP Apps-capable hosts (Claude Desktop). " +
-        "Falls back to a text summary in other hosts. For non-visual data lookups, use chinese_bazi " +
-        "instead; deeper derivations (Ten Gods, element balance, luck pillars) have dedicated tools " +
-        "on the full tool surface (`?profile=full`).",
+        "Falls back to a text summary in other hosts, so it is also the right call without a " +
+        "renderer. Deeper derivations (Ten Gods, element balance, luck pillars) and a plain " +
+        "non-visual pillars lookup have dedicated tools on the full surface (`?profile=full`).",
     inputSchema: {
         type: "object",
         properties: {

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

@@ -104,13 +104,21 @@ const HOUSE_SYSTEM_MAP = {
     campanus: "C", regiomontanus: "R",
 };
 function buildNatalBody(datetime, lat, lon, timezone, houseSystem = "placidus") {
+    // A natal chart with no birthplace is never meaningful — houses and angles are
+    // derived entirely from it. This used to read `lat ?? 0`, which cast the chart
+    // for 0°N 0°E and returned it as though nothing were wrong. Callers that can
+    // legitimately omit coords resolve them first (see coordsFromArgsOrLocation) or
+    // fall back to Person 1's; anything reaching here without them is a bug.
+    if (lat == null || lon == null) {
+        throw new Error("Internal: buildNatalBody requires latitude and longitude — refusing to cast a chart for 0°N 0°E.");
+    }
     const body = {
         subject: {
             name: "MCP Request",
             birth_datetime: { iso: datetime },
             birth_location: {
-                latitude: { decimal: lat ?? 0 },
-                longitude: { decimal: lon ?? 0 },
+                latitude: { decimal: lat },
+                longitude: { decimal: lon },
             },
         },
         configuration: {
@@ -413,16 +421,15 @@ registerTool({
         "CREDIT COST: 2 credits per call for most modes (1 per wheel computed); " +
         "solar_return/lunar_return modes cost 6 (5 for the return + 1 for the natal wheel).\n\n" +
         "The inner wheel is always Person 1's natal chart. The outer ring depends on mode:\n" +
-        "• synastry     — Person 2's natal chart (two-person compatibility). 1 credit.\n" +
-        "• transit      — Transiting planets for a given date. 1 credit.\n" +
-        "• progressed   — Secondary progressed positions (person2_datetime = target date). 1 credit.\n" +
-        "• solar_return — Nearest solar return chart (person2_datetime = year to return for). 5 credits.\n" +
-        "• lunar_return — Nearest lunar return chart (person2_datetime = target month). 5 credits.\n" +
-        "• solar_arc    — Solar arc directed positions (person2_datetime = target date). 1 credit.\n" +
-        "Cross-aspects between both wheels are computed and displayed as coloured dashed lines. " +
-        "Click any planet, aspect line, or house cusp for interpretation. " +
-        "Prefer this whenever the user should SEE the comparison — it renders interactively in " +
-        "MCP Apps-capable hosts (Claude Desktop) and falls back to static SVG in other hosts. " +
+        "• synastry     — Person 2's natal chart (needs Person 2's own birthplace).\n" +
+        "• transit      — Transiting planets for a given date.\n" +
+        "• progressed   — Secondary progressed positions (person2_datetime = target date).\n" +
+        "• solar_return — Nearest solar return chart (person2_datetime = year to return for).\n" +
+        "• lunar_return — Nearest lunar return chart (person2_datetime = target month).\n" +
+        "• solar_arc    — Solar arc directed positions (person2_datetime = target date).\n" +
+        "Cross-aspects are drawn as coloured dashed lines; click any planet, aspect line, or " +
+        "house cusp for interpretation. Prefer this whenever the user should SEE the comparison " +
+        "— it renders interactively in MCP Apps hosts and falls back to static SVG elsewhere. " +
         "For raw synastry data without a visual, use ephemeris_synastry.",
     inputSchema: {
         type: "object",
@@ -444,8 +451,8 @@ registerTool({
                     "synastry = Person 2 birth datetime; transit/progressed/solar_arc = target date; " +
                     "solar_return/lunar_return = any date within the target year/month. " + DATETIME_DESC,
             },
-            person2_latitude: { type: "number", description: "Birth latitude for Person 2 (synastry) or return/transit location. Defaults to Person 1 coords for single-person modes." },
-            person2_longitude: { type: "number", description: "Birth longitude for Person 2 (synastry) or return/transit location. Defaults to Person 1 coords for single-person modes." },
+            person2_latitude: { type: "number", description: "Birth latitude for Person 2. REQUIRED in synastry unless `person2_location` is given — never inferred from Person 1. Other modes default to Person 1's coords." },
+            person2_longitude: { type: "number", description: "Birth longitude for Person 2. REQUIRED in synastry unless `person2_location` is given. Other modes default to Person 1's coords." },
             person2_timezone: timezoneProperty("Person 2 / the outer chart", "America/Chicago"),
             person2_name: {
                 type: "string",
@@ -453,7 +460,11 @@ registerTool({
             },
             location: {
                 type: "string",
-                description: "Person 1 / Natal location. Prefer a plain place name like 'New York, NY' — the server resolves it via the same lookup `location_search` uses (unambiguous names → coords + timezone; ambiguous names throw with a disambiguation hint). Supplied person1_latitude/person1_longitude always win.",
+                description: "Person 1 / Natal location. Prefer a plain place name like 'New York, NY' — resolved via the same lookup `location_search` uses; ambiguous names throw with a disambiguation hint. Supplied person1_latitude/person1_longitude win.",
+            },
+            person2_location: {
+                type: "string",
+                description: "Person 2 / outer-chart place name, resolved like `location`. person2_latitude/person2_longitude win.",
             },
             mode: {
                 type: "string",
@@ -493,10 +504,26 @@ registerTool({
         const lat1 = resolved1.latitude;
         const lon1 = resolved1.longitude;
         const tz1 = args.person1_timezone ?? resolved1.timezone;
+        const resolved2 = await coordsFromArgsOrLocation({
+            latitude: args.person2_latitude,
+            longitude: args.person2_longitude,
+            timezone: args.person2_timezone,
+            location: args.person2_location,
+        });
+        // Only synastry casts a standalone chart from Person 2's own birthplace. The
+        // other modes either fall back to Person 1's coords (transit, *_return) or
+        // ignore lat2/lon2 entirely (progressed, solar_arc), so an unresolved Person 2
+        // is a hard error there alone. Without this the coords fell through to
+        // `lat ?? 0` in buildNatalBody and silently produced a chart cast for
+        // 0°N 0°E — no error, no warning, wrong houses and angles.
+        if (mode === "synastry" && (resolved2.latitude == null || resolved2.longitude == null)) {
+            throw new Error("explore_bi_wheel in synastry mode requires either `person2_latitude` + `person2_longitude` " +
+                "or a resolvable `person2_location` name. Person 2's birthplace is never inferred from Person 1's.");
+        }
         const dt2 = String(args.person2_datetime);
-        const lat2 = args.person2_latitude;
-        const lon2 = args.person2_longitude;
-        const tz2 = args.person2_timezone;
+        const lat2 = resolved2.latitude;
+        const lon2 = resolved2.longitude;
+        const tz2 = args.person2_timezone ?? resolved2.timezone;
         const loc1 = String(args.person1_name ?? resolved1.location ?? args.location ?? `${lat1},${lon1}`);
         const loc2 = MODE_META[mode].outerLabel(dt2, args.person2_name);
         // Fetch inner (natal) and outer (mode-dependent) charts in parallel where possible
@@ -575,6 +602,13 @@ registerTool({
         const lat2 = args.person2_latitude;
         const lon2 = args.person2_longitude;
         const tz2 = args.person2_timezone;
+        // Same 0°N 0°E trap as explore_bi_wheel: person1 coords are required by the
+        // schema but person2's cannot be (they are only needed in synastry mode), so
+        // the mode-specific requirement is enforced here. The widget always supplies
+        // them; a hand-rolled call need not.
+        if (mode === "synastry" && (lat2 == null || lon2 == null)) {
+            throw new Error("bi_wheel_recalculate in synastry mode requires `person2_latitude` and `person2_longitude`.");
+        }
         const loc1 = String(args.person1_name ?? args.location ?? `${lat1 ?? "?"},${lon1 ?? "?"}`);
         const loc2 = MODE_META[mode].outerLabel(dt2, args.person2_name);
         const [innerData, outerData] = await Promise.all([

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

@@ -25,7 +25,7 @@ import { fileURLToPath } from "node:url";
 import { registerTool, SERVER_VERSION } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
-import { localToUtcIso } from "../datetime.js";
+import { localToUtcIsoHistorical } from "../datetime-historical.js";
 import { coordsFromArgsOrLocation } from "./_location-resolver.js";
 // ── Constants ─────────────────────────────────────────────────────────────
 export const BODYGRAPH_RESOURCE_URI = "ui://openephemeris/bodygraph";
@@ -306,7 +306,10 @@ function buildHdSummary(payload, location) {
 registerTool({
     name: "explore_human_design",
     description: "Generate an interactive Human Design Bodygraph with clickable centers, gates, and channels.\n\n" +
-        "CREDIT COST: 2 credits per call.\n\n" +
+        "CREDIT COST: 4 credits where the bodygraph renders (2 for the chart + 2 for the " +
+        "visual), 2 in text-only hosts that skip the render. For chart data alone at 2 " +
+        "credits — including the activations, design, personality, strategy and variables " +
+        "this tool does not return — use human_design_chart.\n\n" +
         "Returns an embedded visual bodygraph explorer that lets you click any center or gate " +
         "for instant Human Design interpretation. " +
         "Shows defined/undefined centers, active gates, channels, Type, Profile, Authority, " +
@@ -372,9 +375,9 @@ registerTool({
             location: args.location,
         });
         const timezone = args.timezone ?? resolved.timezone;
-        const datetime = localToUtcIso("datetime", String(args.datetime), timezone);
         const lat = resolved.latitude;
         const lon = resolved.longitude;
+        const datetime = await localToUtcIsoHistorical("datetime", String(args.datetime), timezone, { latitude: lat, longitude: lon });
         if (lat == null || lon == null) {
             throw new Error("explore_human_design requires either `latitude` + `longitude` or a resolvable `location` name. " +
                 "Human Design is sensitive to birth location; a chart at 0°N 0°E is silently wrong.");
@@ -473,10 +476,11 @@ registerTool({
     handler: async (args) => {
         const client = getActiveClient();
         const timezone = args.timezone;
-        // Convert local-time input → UTC using IANA timezone when provided
-        const datetime = localToUtcIso("datetime", String(args.datetime), timezone);
         const lat = args.latitude;
         const lon = args.longitude;
+        // Convert local-time input → UTC using IANA timezone when provided;
+        // pre-1970 births route through the API's historical correction overlay.
+        const datetime = await localToUtcIsoHistorical("datetime", String(args.datetime), timezone, { latitude: lat, longitude: lon });
         const theme = args.theme === "light" ? "light" : "dark";
         const layout = args.layout === "mandala" ? "mandala" : undefined;
         const rings = typeof args.rings === "string" ? args.rings : undefined;
@@ -1365,9 +1369,9 @@ registerTool({
             location: args.location,
         });
         const timezone = args.timezone ?? resolved.timezone;
-        const natalIso = localToUtcIso("datetime", String(args.datetime), timezone);
         const lat = resolved.latitude;
         const lon = resolved.longitude;
+        const natalIso = await localToUtcIsoHistorical("datetime", String(args.datetime), timezone, { latitude: lat, longitude: lon });
         if (lat == null || lon == null) {
             throw new Error("explore_human_design_transit requires either `latitude` + `longitude` or a resolvable `location` name. " +
                 "Human Design is sensitive to birth location; a chart at 0°N 0°E is silently wrong.");
@@ -1389,7 +1393,7 @@ registerTool({
         };
         if (args.transit_datetime) {
             body.transit_datetime = {
-                iso: localToUtcIso("transit_datetime", String(args.transit_datetime), args.timezone),
+                iso: await localToUtcIsoHistorical("transit_datetime", String(args.transit_datetime), args.timezone, { latitude: lat, longitude: lon }),
             };
         }
         const bundleAvailable = Boolean(getBodygraphBundle());
@@ -1520,7 +1524,7 @@ registerTool({
                     "Human Design is sensitive to birth location; a chart at 0°N 0°E is silently wrong.");
             }
             return {
-                birth_datetime_utc: localToUtcIso(`${label}.datetime`, String(p?.datetime), tz, `${label}.timezone`),
+                birth_datetime_utc: await localToUtcIsoHistorical(`${label}.datetime`, String(p?.datetime), tz, { latitude: lat, longitude: lon }, `${label}.timezone`),
                 latitude: lat,
                 longitude: lon,
             };

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

@@ -1,6 +1,15 @@
 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";
+/** Render minutes east of UTC as `±HH:MM`. */
+function formatOffsetMinutes(offsetMinutes) {
+    const sign = offsetMinutes < 0 ? "-" : "+";
+    const abs = Math.abs(offsetMinutes);
+    const hh = String(Math.floor(abs / 60)).padStart(2, "0");
+    const mm = String(Math.round(abs % 60)).padStart(2, "0");
+    return `${sign}${hh}:${mm}`;
+}
 /**
  * The UTC offset of an IANA zone is a function of place AND date: 1987 US DST
  * rules are not today's rules, and America/Chicago ran on CDT through the whole
@@ -143,6 +152,8 @@ registerTool({
         // Map the API's snake_case response to the camelCase shape the app UI consumes.
         const list = Array.isArray(raw?.suggestions) ? raw.suggestions : [];
         const date = args.date != null && String(args.date).trim() !== "" ? String(args.date).trim() : null;
+        const dateYear = date ? Number(date.slice(0, 4)) : null;
+        const preTzdataEra = dateYear != null && Number.isFinite(dateYear) && dateYear < TZDATA_AUTHORITATIVE_FROM_YEAR;
         const suggestions = list.map((s) => {
             const mapped = {
                 displayName: s.display_name,
@@ -154,8 +165,17 @@ registerTool({
                 longitude: s.longitude,
                 timezone: s.timezone,
             };
-            if (date && s.timezone)
-                Object.assign(mapped, offsetAtLocalNoon(s.timezone, date) ?? {});
+            if (date && s.timezone) {
+                const offset = offsetAtLocalNoon(s.timezone, date);
+                if (offset) {
+                    // These offsets come from local tzdata, which is only
+                    // authoritative from 1970 — before that it models the
+                    // zone's reference city, not state/local law.
+                    Object.assign(mapped, offset, {
+                        tzConfidence: preTzdataEra ? "historical_estimate" : "authoritative",
+                    });
+                }
+            }
             return mapped;
         });
         // Ambiguity signal. "portland" really does match Oregon, Maine, Texas,
@@ -180,6 +200,11 @@ registerTool({
         return {
             suggestions,
             matchCount: suggestions.length,
+            ...(preTzdataEra
+                ? {
+                    historicalNote: "Pre-1970 date: tzdata offsets are reference-city estimates. For the chosen place, call timezone_resolve with the same date (or submit the naive local time + timezone + coordinates to the chart endpoint) to apply the API's historical correction overlay.",
+                }
+                : {}),
             ambiguous,
             ...(ambiguous
                 ? {
@@ -203,7 +228,7 @@ registerTool({
             longitude: { type: "number" },
             date: {
                 type: "string",
-                description: "Optional birth/event date as 'YYYY-MM-DD'. When given, the result also carries utcOffsetAtDate / utcOffsetMinutes / isDst for that date under that zone's historical DST rules. Free: adds no API call and no credits.",
+                description: "Optional birth/event date 'YYYY-MM-DD'. Adds utcOffsetAtDate / utcOffsetMinutes / isDst / tzConfidence. Post-1970 resolves locally (free); pre-1970 consults the API's historical correction overlay (1 extra credit).",
             },
         },
         required: ["latitude", "longitude"],
@@ -228,9 +253,46 @@ registerTool({
         const date = args.date != null && String(args.date).trim() !== "" ? String(args.date).trim() : null;
         const tz = typeof result?.timezone === "string" ? result.timezone : null;
         if (date && tz) {
+            // Pre-1970 dates: tzdata (Node's and Go's alike) models the zone's
+            // reference city only, so ask the API — its historical correction
+            // overlay knows where state law diverged (e.g. Minnesota 1959-66).
+            // Costs one extra credit, only for pre-1970 dates.
+            const year = Number(date.slice(0, 4));
+            if (Number.isFinite(year) && year < TZDATA_AUTHORITATIVE_FROM_YEAR) {
+                try {
+                    const off = (await getActiveClient().request("POST", "/timezone/offset", {
+                        data: { lat: args.latitude, lon: args.longitude, datetime_local: `${date.slice(0, 10)}T12:00:00` },
+                    }));
+                    if (typeof off?.offset_seconds === "number") {
+                        const minutes = off.offset_seconds / 60;
+                        return {
+                            ...result,
+                            utcOffsetAtDate: formatOffsetMinutes(minutes),
+                            utcOffsetMinutes: minutes,
+                            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 } : {}),
+                        };
+                    }
+                }
+                catch {
+                    // Server path unavailable — fall through to the local
+                    // tzdata estimate below, flagged as such.
+                }
+            }
             const offset = offsetAtLocalNoon(tz, date);
-            if (offset)
-                return { ...result, ...offset, date };
+            if (offset) {
+                return {
+                    ...result,
+                    ...offset,
+                    date,
+                    tzConfidence: Number.isFinite(year) && year < TZDATA_AUTHORITATIVE_FROM_YEAR
+                        ? "historical_estimate"
+                        : "authoritative",
+                };
+            }
         }
         return result;
     },

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

@@ -17,7 +17,8 @@ import { fileURLToPath } from "node:url";
 import { registerTool, validateCoordinates, SERVER_VERSION } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
-import { TIMEZONE_PROPERTY, localToUtcIso } from "../datetime.js";
+import { TIMEZONE_PROPERTY } from "../datetime.js";
+import { localToUtcIsoHistorical } from "../datetime-historical.js";
 // ── Constants ─────────────────────────────────────────────────────────────────
 export const MOON_PHASE_RESOURCE_URI = "ui://openephemeris/moon-phase";
 export const MOON_PHASE_MIME_TYPE = "text/html;profile=mcp-app";
@@ -98,7 +99,7 @@ async function computeMoonData(args) {
     const client = getActiveClient();
     const params = {};
     params.datetime = args.datetime
-        ? localToUtcIso("datetime", String(args.datetime), args.timezone)
+        ? await localToUtcIsoHistorical("datetime", String(args.datetime), args.timezone, { latitude: args.latitude, longitude: args.longitude })
         : new Date().toISOString();
     if (args.latitude != null)
         params.latitude = args.latitude;

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

@@ -23,7 +23,7 @@ import { fileURLToPath } from "node:url";
 import { registerTool, validateRequired, validateCoordinates, SERVER_VERSION } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
-import { localToUtcIso } from "../datetime.js";
+import { localToUtcIsoHistorical } from "../datetime-historical.js";
 import { coordsFromArgsOrLocation } from "./_location-resolver.js";
 // ── Constants ─────────────────────────────────────────────────────────────────
 export const VEDIC_CHART_RESOURCE_URI = "ui://openephemeris/vedic-chart";
@@ -165,9 +165,9 @@ registerTool({
         validateCoordinates(argsWithResolved, "latitude", "longitude");
         const client = getActiveClient();
         const timezone = args.timezone ?? resolved.timezone;
-        const datetime = localToUtcIso("datetime", String(args.datetime), timezone);
         const lat = Number(resolved.latitude);
         const lon = Number(resolved.longitude);
+        const datetime = await localToUtcIsoHistorical("datetime", String(args.datetime), timezone, { latitude: lat, longitude: lon });
         const ayanamsa = args.ayanamsa;
         const location = String(resolved.location ?? args.location ?? `${lat}, ${lon}`).slice(0, 120);
         const bundleAvailable = Boolean(getVedicChartBundle());
@@ -244,9 +244,9 @@ registerTool({
     _meta: { ui: { resourceUri: VEDIC_CHART_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const client = getActiveClient();
-        const datetime = localToUtcIso("datetime", String(args.datetime), args.timezone);
         const lat = args.latitude != null ? Number(args.latitude) : undefined;
         const lon = args.longitude != null ? Number(args.longitude) : undefined;
+        const datetime = await localToUtcIsoHistorical("datetime", String(args.datetime), args.timezone, { latitude: lat, longitude: lon });
         const ayanamsa = args.ayanamsa;
         const theme = args.theme === "light" ? "light" : "dark";
         const body = {