@openephemeris/mcp-server 4.0.0 → 4.2.0

package/CHANGELOG.md

@@ -7,6 +7,119 @@ Version numbering follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [4.2.0] — 2026-07-29
+
+`ephemeris_next_lunar_phase` could not answer the question it exists to answer. The
+tool's response shape changes with this fix, hence a minor rather than a patch.
+
+### Fixed
+
+- **`ephemeris_next_lunar_phase` returned zero results for every query.** "When is the
+  next full moon?" answered `result_count: 0` with the note *"No matching phase found in
+  window"* — an empty result that reads like a real one, so the answer came back as
+  "there is no full moon in the next month". Four faults stacked up:
+
+  - the tool sent `start_date`/`end_date`, but the calendar endpoint takes a single
+    `date`, so the search window was silently ignored;
+  - it looked for the phase array at `phases`/`data`/`events`, while the response nests
+    it at `data.events`, so the list was always empty;
+  - it matched phase names as `"full moon"` against the engine's `"full_moon"`, so
+    nothing would have matched even once the list was found;
+  - `last_quarter` had no match at all, because the engine names it `third_quarter`.
+
+  The search now walks the calendar forward one lunation at a time, so `count` above 1
+  works. An empty result is no longer reported as an answer: since every principal phase
+  recurs about every 29.5 days, zero results is a fault and the tool now says so instead
+  of handing back a plausible non-answer.
+
+### Changed
+
+- **`ephemeris_retrograde_status` now leads with the single-planet path.** The
+  description opened on the all-planets sweep and mentioned `planet_id` last, so "is
+  Mercury retrograde?" tended to take the 10-credit route instead of the 1-credit one.
+  `planet_id` now carries the planet-id table and both costs are stated up front.
+- **`ephemeris_next_lunar_phase` no longer claims to return the zodiac sign and degree.**
+  It never did — it returns exact UTC datetimes. It now points at `ephemeris_moon_phase`
+  for the sign, and states that cost scales with `count`.
+
+---
+
+## [4.1.0] — 2026-07-26
+
+Follow-up to 4.0.0. The new `400` was telling REST callers to do something that, on
+most endpoints, was impossible. It now isn't — the remedy it names is real everywhere.
+
+### Added
+
+- **`date_time.timezone` — every datetime in the API now accepts its own zone.** 4.0.0's
+  rejection message offered two fixes: put an offset on the value, or "keep the local
+  wall-clock time and pass the zone alongside it". The second one only worked on requests
+  built around a `subject`, because the zone lived on `subject.birth_location.timezone`.
+  Endpoints that take a bare `date_time` — `/ephemeris/angles-points`, `/ephemeris/house-cusps`,
+  `/ephemeris/planet-position`, `/ephemeris/dignities`, `/ephemeris/midpoints`,
+  `/ephemeris/retrograde-status`, `/ephemeris/fixed-stars`, `/ephemeris/hermetic-lots`
+  and `/ephemeris/lunar-phase` — had nowhere to put a zone, so a caller following the
+  error's own advice got the same `400` back. Nine endpoints, one impossible instruction.
+
+  The zone now belongs to the datetime rather than to the request, so this works
+  everywhere a datetime is accepted:
+
+  ```json
+  { "date_time": { "iso": "1987-07-15T09:01:00",
+                   "timezone": { "iana_name": "America/Chicago" } } }
+  ```
+
+  Purely additive — an omitted `timezone` behaves exactly as before, and where a request
+  already carries a zone (a subject's birth location) that remains the fallback. A zone
+  already written on the string always wins, so a stray `timezone` can never move an
+  instant that the caller had already pinned.
+
+- **`docs/datetime-contract.md`** — one authoritative statement of the rule: when a zone
+  is required, the date-only and `*_utc` carve-outs, how to pass a zone on each request
+  shape, and what the response echoes. The reason four endpoint families drifted to four
+  different readings of "ISO 8601 date-time" is that no such document existed.
+
+### Fixed
+
+- **The `400` no longer advertises a remedy the endpoint doesn't have.** Fields that are
+  a bare datetime *string* rather than an object — the ACG `epoch` family, the Venus date
+  ranges, the `datetime` query parameter on the `GET /ephemeris/moon/*` endpoints — have
+  no `timezone` companion and cannot grow one. Their rejection message now names only the
+  fix that exists: put the zone on the value. Being told to do something impossible is
+  worse than a terse error.
+
+- **The OpenAPI spec now states the contract where callers actually read it.** The
+  `date_time` fields said "ISO 8601 date-time" and nothing more, so the only place the
+  rule appeared was in the error you got for breaking it. The `iso`, `components` and
+  `timezone` fields, the `epoch`/date-range string fields, and the spec's own
+  "Supported Formats" section now all state it. That section had been listing a zone-less
+  `"2000-01-01T12:00:00"` as an accepted input — the exact value the API rejects.
+
+- **`/timezone/offset` documented behaviour it has never had.** Its `datetime_utc` field
+  claimed a naive value was "interpreted as UTC". The field is a strict RFC 3339 instant,
+  so a zone-less value was never interpreted at all — it failed to parse. Now documented
+  as what it is.
+
+- **The spec's front-page example used field names that do not exist** (`iso_string`,
+  a `timezone.name`, and latitude/longitude directly under `subject`). Replaced with the
+  real request shape.
+
+- **Four tool modules were still teaching the pre-4.0.0 contract.** `chart_wheel` told the
+  model to "include timezone offset **if known**"; `ephemeris_composite`,
+  `ephemeris_composite_midpoint`, `ephemeris_overlay`, `ephemeris_natal_transits`, the
+  electional search tools and `explore_bi_wheel` described their datetimes as plain
+  "(ISO 8601)" with no zone requirement. 4.0.0 migrated the rest of the surface and missed
+  these. They now use the same canonical description as every other tool, and the composite
+  tools reject a zone-less datetime locally instead of spending a credit to learn it.
+
+### Changed
+
+- The tool-surface token ceilings are **unchanged** (core 20,000 / full 36,500). The
+  descriptions above cost ~0.4k core / ~1.0k full and fit inside the existing budget;
+  measured after the change, core is 18.7k and full is 34.8k.
+
+---
+
 ## [4.0.0] — 2026-07-26
 
 **Breaking.** A datetime that states a clock time without a zone is now rejected instead of silently assumed to be UTC. Callers who relied on the old behaviour were receiving charts computed for the wrong instant, so the break is the fix — but it is a break, and it is why this is a major version.

package/README.md

@@ -93,7 +93,15 @@ await mcpClient.connect(transport)
 const { tools } = await mcpClient.listTools()
 const result = await mcpClient.callTool({
   name: "ephemeris_natal_chart",
-  arguments: { datetime: "1990-04-15T14:30:00", latitude: 41.8781, longitude: -87.6298, format: "llm" },
+  // A datetime that states a clock time must state its zone: either pass
+  // `timezone` alongside the local time, or put a Z/±HH:MM offset on the value.
+  arguments: {
+    datetime: "1990-04-15T14:30:00",
+    timezone: "America/Chicago",
+    latitude: 41.8781,
+    longitude: -87.6298,
+    format: "llm",
+  },
 })
 ```
 
@@ -219,6 +227,32 @@ The server is hosted at `https://mcp.openephemeris.com/mcp` with full Streamable
 "What is the sidereal time and delta-T right now?"
 ```
 
+## Interactive Charts
+
+Nine of the tools don't answer with JSON. They open a chart in the conversation — a real one, drawn from the same calculation, that you can click around in.
+
+This matters more than it sounds. A natal chart returned as JSON is a list of numbers you have to already understand to read. The same chart rendered as a wheel is something you can point at. Click a planet and you get that placement explained; click a house and you get what's in it. The chart stays on screen while you keep talking, and it doesn't cost another credit to keep looking at it.
+
+These need a host that supports MCP Apps — Claude Desktop is the main one today. In a client without app support the same tools still work; you get the underlying data instead of the picture, so nothing breaks, you just don't get the wheel.
+
+| Tool | What opens | What you can click | Credits |
+|---|---|---|---|
+| `explore_natal_chart` | Natal wheel — planets, houses, aspects, angles | Planets, houses, aspect lines; recalculate with new settings | 1 |
+| `explore_bi_wheel` | Two charts on one wheel: transits, synastry, progressions | Either wheel's planets, houses, and the aspects between them | 2 |
+| `explore_human_design` | Human Design bodygraph, with a mandala view toggle | Centers, gates, channels, planets, variables | 2 |
+| `explore_human_design_transit` | Today's planets laid over a natal bodygraph | Transit-activated channels | 3 |
+| `explore_human_design_connection` | Two bodygraphs combined, every shared channel classified | Connection channels by type | 3 |
+| `explore_vedic_chart` | South Indian Rashi grid — sidereal placements and Lagna | Each rashi, for its placements and nakshatras | 3 |
+| `explore_bazi_chart` | Four Pillars (四柱命盘) — Year, Month, Day, Hour | Each pillar | 3 |
+| `explore_transit_timeline` | Upcoming transit hits in date order | Individual hits | 6 |
+| `explore_moon_phase` | Moon dial — illumination, phase, sign, void-of-course | Recalculate for another moment | 3 |
+
+Ask for these the way you'd ask a person: *"show me my chart"*, *"put today's transits over my Human Design"*, *"what's the moon doing right now"*. The model picks the app.
+
+Two things worth knowing. The chart wheel and bi-wheel accept a click on an aspect line, not just on the two planets it joins — so "why does this line matter" is one click rather than a paragraph of setup. And the bodygraph's mandala toggle rearranges the whole chart into concentric rings without another API call, so switching views is free.
+
+Screenshots of each are on the way.
+
 ## Tools at a Glance
 
 | Category | Tool | Tier |

package/dist/prompts.js

@@ -68,13 +68,15 @@ export const PROMPTS = [
             "   Default to Placidus if they're unsure.\n\n" +
             "## Step 2 — Resolve Coordinates and Timezone (MANDATORY)\n" +
             "**Do NOT guess coordinates or timezones from memory.** Use the API tools to resolve them:\n\n" +
-            "**A) Geocode** — call `dev_read_api` with `path: '/location/autocomplete'`, " +
-            "`query: { q: 'City Name, Country' }`. This returns verified decimal lat/lon.\n\n" +
-            "**B) Timezone** — call `dev_write_api` with `path: '/timezone/lookup'`, " +
-            "`body: { latitude: ..., longitude: ..., datetime: 'YYYY-MM-DDTHH:MM:SS' }`. " +
-            "This returns the correct IANA timezone and UTC offset for the birth year, including historical DST.\n\n" +
-            "- Format: pass `datetime` as local ISO 8601 (e.g. `1990-04-15T14:30:00`) " +
-            "and `timezone` as the IANA name returned by the lookup. Do NOT append Z to a local birth time.\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 " +
+            "that date (1987 US DST rules differ from today's). If the result is `ambiguous`, ASK which " +
+            "place the user means instead of taking the first.\n\n" +
+            "- Pass the local wall-clock time as `datetime` (e.g. `1990-04-15T14:30:00`) together with " +
+            "the `timezone` from the search. Do NOT convert to UTC yourself and do NOT append a Z to a " +
+            "local birth time — a zone-less datetime is rejected, and a hand-converted one is how charts " +
+            "end up hours off.\n\n" +
             "## Step 3 — Tool Call\n" +
             "Make a single call to `explore_natal_chart` (the interactive chart wheel) with:\n" +
             "- `datetime`: local ISO 8601 (no Z)\n" +
@@ -146,10 +148,11 @@ export const PROMPTS = [
             "4. **Any major events coming up** they already know about — reframes the transits around real context\n\n" +
             "## Step 2 — Resolve Coordinates and Timezone (MANDATORY)\n" +
             "**Do NOT guess coordinates or timezones from memory.** Use the API tools:\n\n" +
-            "**A) Geocode** — call `dev_read_api` with `path: '/location/autocomplete'`, " +
-            "`query: { q: 'Birth City, Country' }`. Use the returned decimal lat/lon.\n\n" +
-            "**B) Timezone** — call `dev_write_api` with `path: '/timezone/lookup'`, " +
-            "`body: { latitude: ..., longitude: ..., datetime: 'YYYY-MM-DDTHH:MM:SS' }`.\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 " +
+            "that date (1987 US DST rules differ from today's). If the result is `ambiguous`, ASK which " +
+            "place the user means instead of taking the first.\n\n" +
             "- Set `start_date` to today and `end_date` to the end of the forecast window\n\n" +
             "## Step 3 — Tool Call Sequence\n" +
             "Two calls minimum, run sequentially:\n\n" +
@@ -211,11 +214,13 @@ export const PROMPTS = [
             "7. **House system**: Placidus (default), Whole Sign, Koch, Equal?\n\n" +
             "## Step 2 — Resolve Both Sets of Coordinates (MANDATORY)\n" +
             "**Do NOT guess coordinates or timezones.** For EACH person:\n\n" +
-            "**A) Geocode** — call `dev_read_api` with `path: '/location/autocomplete'`, " +
-            "`query: { q: 'Birth City, Country' }`.\n\n" +
-            "**B) Timezone** — call `dev_write_api` with `path: '/timezone/lookup'`, " +
-            "`body: { latitude: ..., longitude: ..., datetime: 'YYYY-MM-DDTHH:MM:SS' }`.\n\n" +
-            "- Format: local ISO 8601 datetime (no Z) + IANA timezone name separately for each person\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 " +
+            "that date (1987 US DST rules differ from today's). If the result is `ambiguous`, ASK which " +
+            "place the user means instead of taking the first.\n\n" +
+            "- Do this for BOTH people. Pass each local wall-clock datetime with its own `timezone`; " +
+            "never convert to UTC by hand.\n" +
             "- Note if either birth time is unknown — flag this upfront before running tools\n\n" +
             "## Step 3 — Tool Call\n" +
             "Make a single call to `ephemeris_synastry` with:\n" +
@@ -283,12 +288,14 @@ export const PROMPTS = [
             "sometimes it explains why a place felt 'off'\n\n" +
             "## Step 2 — Resolve Coordinates (MANDATORY)\n" +
             "**Do NOT guess coordinates or timezones.** Use the API tools:\n\n" +
-            "**A) Geocode birth city** — call `dev_read_api` with `path: '/location/autocomplete'`, " +
-            "`query: { q: 'Birth City, Country' }`.\n\n" +
-            "**B) Timezone** — call `dev_write_api` with `path: '/timezone/lookup'`, " +
-            "`body: { latitude: ..., longitude: ..., datetime: 'YYYY-MM-DDTHH:MM:SS' }`.\n\n" +
-            "**C) Geocode each target city** — repeat the autocomplete call for each destination city.\n\n" +
-            "- Format birth datetime as local ISO 8601 (no Z), pass IANA timezone separately\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 " +
+            "that date (1987 US DST rules differ from today's). If the result is `ambiguous`, ASK which " +
+            "place the user means instead of taking the first.\n\n" +
+            "**Then geocode each target city** — one `location_search` per destination.\n\n" +
+            "- Pass the birth datetime as local wall-clock time with its `timezone`; never append a Z " +
+            "to a local time.\n\n" +
             "## Step 3 — Tool Call Sequence\n" +
             "Two calls minimum. Start lean, offer more after delivery.\n\n" +
             "**A) City-Level Hits** — for EACH target city, call `acg_hits` with:\n" +
@@ -372,13 +379,15 @@ export const PROMPTS = [
             "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" +
-            "**A) Geocode** — call `dev_read_api` with `path: '/location/autocomplete'`, " +
-            "`query: { q: 'Birth City, Country' }`.\n\n" +
-            "**B) Timezone** — call `dev_write_api` with `path: '/timezone/lookup'`, " +
-            "`body: { latitude: ..., longitude: ..., datetime: 'YYYY-MM-DDTHH:MM:SS' }`.\n" +
-            "This returns the UTC offset for the birth year, including historical DST.\n\n" +
-            "- Use the returned offset to convert local birth time → UTC\n" +
-            "- Format as ISO 8601 with Z: e.g. `1990-04-15T19:30:00Z`\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 " +
+            "that date (1987 US DST rules differ from today's). If the result is `ambiguous`, ASK which " +
+            "place the user means instead of taking the first.\n\n" +
+            "- Pass the local wall-clock time as `datetime` (e.g. `1990-04-15T14:30:00`) together with " +
+            "the `timezone` from the search. Do NOT convert to UTC yourself and do NOT append a Z to a " +
+            "local birth time — a zone-less datetime is rejected, and a hand-converted one is how charts " +
+            "end up hours off.\n\n" +
             "**Why HD needs UTC**: The system calculates two activation moments:\n" +
             "- **Personality (Conscious / Black)**: the birth datetime\n" +
             "- **Design (Unconscious / Red)**: 88° of the Sun's arc before birth (approximately 88–89 days, varying by season)\n" +
@@ -545,13 +554,15 @@ export const PROMPTS = [
             "   Default to Lahiri if unsure.\n\n" +
             "## Step 2 — Convert to UTC (MANDATORY)\n" +
             "The `vedic_chart` tool requires a UTC datetime (with Z suffix):\n\n" +
-            "**A) Geocode** — call `dev_read_api` with `path: '/location/autocomplete'`, " +
-            "`query: { q: 'Birth City, Country' }`.\n\n" +
-            "**B) Timezone** — call `dev_write_api` with `path: '/timezone/lookup'`, " +
-            "`body: { latitude: ..., longitude: ..., datetime: 'YYYY-MM-DDTHH:MM:SS' }`.\n" +
-            "This returns the correct IANA timezone and UTC offset for the birth year, including historical DST.\n\n" +
-            "- Use the returned offset to convert local birth time → UTC\n" +
-            "- Format: `1990-01-15T03:00:00Z`\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 " +
+            "that date (1987 US DST rules differ from today's). If the result is `ambiguous`, ASK which " +
+            "place the user means instead of taking the first.\n\n" +
+            "- Pass the local wall-clock time as `datetime` (e.g. `1990-04-15T14:30:00`) together with " +
+            "the `timezone` from the search. Do NOT convert to UTC yourself and do NOT append a Z to a " +
+            "local birth time — a zone-less datetime is rejected, and a hand-converted one is how charts " +
+            "end up hours off.\n\n" +
             "## Step 3 — Call the Tool\n" +
             "Call `vedic_chart` with:\n" +
             "- `datetime`: UTC ISO 8601 with Z\n" +
@@ -772,12 +783,14 @@ export const PROMPTS = [
             "4. **House system**: Placidus (default), Whole Sign, Koch, Equal?\n\n" +
             "## Step 2 — Resolve Data (MANDATORY)\n" +
             "**Do NOT guess coordinates or timezones.** Use the API tools:\n\n" +
-            "**A) Geocode birth city** — call `dev_read_api` with `path: '/location/autocomplete'`, " +
-            "`query: { q: 'Birth City, Country' }`.\n\n" +
-            "**B) Timezone** — call `dev_write_api` with `path: '/timezone/lookup'`, " +
-            "`body: { latitude: ..., longitude: ..., datetime: 'YYYY-MM-DDTHH:MM:SS' }`.\n\n" +
-            "- For `birth_datetime`, include the UTC offset from the timezone lookup: `1985-06-21T14:00:00-05:00`\n" +
-            "  (or convert to UTC with Z: `1985-06-21T19:00:00Z`)\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 " +
+            "that date (1987 US DST rules differ from today's). If the result is `ambiguous`, ASK which " +
+            "place the user means instead of taking the first.\n\n" +
+            "- For `birth_datetime`, either append `utcOffsetAtDate` from the search " +
+            "(`1985-06-21T14:00:00-05:00`) or pass the local time with its `timezone`. Both are accepted; " +
+            "a zone-less value is not.\n\n" +
             "**C) Geocode birthday location** — repeat the autocomplete call for the city where they'll be " +
             "on their birthday. This becomes `return_latitude`/`return_longitude`.\n\n" +
             "## Step 3 — Tool Call\n" +

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

@@ -115,8 +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 the dedicated " +
-        "chinese_bazi / bazi_ten_gods / bazi_element_balance / bazi_luck_pillars tools instead.",
+        "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`).",
     inputSchema: {
         type: "object",
         properties: {

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

@@ -26,6 +26,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 { DATETIME_DESC, timezoneProperty } from "../datetime.js";
 // ── Constants ─────────────────────────────────────────────────────────────────
 export const BI_WHEEL_RESOURCE_URI = "ui://openephemeris/bi-wheel";
 export const BI_WHEEL_MIME_TYPE = "text/html;profile=mcp-app";
@@ -399,7 +400,8 @@ function buildBiWheelSummary(innerPlanets, outerPlanets, crossAspects, mode, loc
     const label2 = meta.outerRole;
     return (`**${meta.modeLabel} Bi-Wheel**\n\n` +
         `${label1}: ${location1} — ${innerBasics || "chart loaded"}\n` +
-        `${label2}: ${location2}\n\n` +
+        `${label2}: ${location2}\n` +
+        `Houses: Placidus\n\n` +
         `**Top Cross-Aspects:**\n${top5.join("\n") || "No major cross-aspects within orb."}\n\n` +
         "Click any planet or cross-aspect line in the bi-wheel for interpretation.");
 }
@@ -418,31 +420,32 @@ registerTool({
         "• 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. " +
-        "Use this instead of ephemeris_bi_wheel for a richer, interactive experience in " +
-        "MCP Apps-capable hosts (Claude Desktop). Falls back to static SVG in other hosts.",
+        "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. " +
+        "For raw synastry data without a visual, use ephemeris_synastry.",
     inputSchema: {
         type: "object",
         properties: {
             person1_datetime: {
                 type: "string",
-                description: "ISO 8601 datetime for Person 1 / Natal chart (e.g. '1990-04-15T14:30:00-05:00').",
+                description: "Birth datetime for Person 1 / Natal chart. " + DATETIME_DESC,
             },
             person1_latitude: { type: "number", description: "Birth latitude for Person 1 (decimal degrees, positive = North). Resolve from a place name with location_search; never recall coordinates from memory." },
             person1_longitude: { type: "number", description: "Birth longitude for Person 1 (decimal degrees, positive = East)." },
-            person1_timezone: { type: "string", description: "IANA timezone for Person 1 (e.g. 'America/New_York')." },
+            person1_timezone: timezoneProperty("Person 1's birth location", "America/New_York"),
             person1_name: {
                 type: "string",
                 description: "Display name for Person 1 / Natal chart (e.g. 'Alice'). Used in the badge and summary.",
             },
             person2_datetime: {
                 type: "string",
-                description: "ISO 8601 datetime for the outer wheel. Meaning depends on mode: " +
+                description: "Datetime for the outer wheel. Meaning depends on mode: " +
                     "synastry = Person 2 birth datetime; transit/progressed/solar_arc = target date; " +
-                    "solar_return/lunar_return = any date within the target year/month.",
+                    "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_timezone: { type: "string", description: "IANA timezone for Person 2 / outer chart (e.g. 'America/Chicago')." },
+            person2_timezone: timezoneProperty("Person 2 / the outer chart", "America/Chicago"),
             person2_name: {
                 type: "string",
                 description: "Display name for Person 2 (synastry mode). Used in the badge and summary.",
@@ -510,7 +513,7 @@ registerTool({
                 content: [
                     { type: "text", text: summary },
                 ],
-                structuredContent: { ...payload, server_version: SERVER_VERSION },
+                structuredContent: { ...payload, house_system: "placidus", server_version: SERVER_VERSION },
                 _meta: {
                     "ui/resourceUri": BI_WHEEL_RESOURCE_URI,
                     ui: { resourceUri: BI_WHEEL_RESOURCE_URI },

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

@@ -311,7 +311,7 @@ registerTool({
         "Shows defined/undefined centers, active gates, channels, Type, Profile, Authority, " +
         "and Incarnation Cross. " +
         "The chart is calculated using NASA JPL DE440 ephemerides for both Personality and Design positions. " +
-        "Use this instead of human_design_chart or human_design_bodygraph for a richer, interactive HD " +
+        "Use this instead of human_design_chart for a richer, interactive HD " +
         "experience in MCP Apps-capable hosts (Claude Desktop). " +
         "Falls back to a text summary in other hosts." +
         HD_DISCLAIMER,
@@ -1313,7 +1313,7 @@ registerTool({
             timezone: { type: "string", description: "IANA timezone for the birth location (e.g. 'America/New_York')." },
             transit_datetime: {
                 type: "string",
-                description: "Transit moment, ISO 8601. Defaults to now (UTC) when omitted.",
+                description: "Transit moment, ISO 8601; must include 'Z' or an offset. Defaults to now (UTC) when omitted.",
             },
             theme: {
                 type: "string",

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

@@ -21,6 +21,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 { DATETIME_DESC, TIMEZONE_PROPERTY } from "../datetime.js";
 // ── Constants ─────────────────────────────────────────────────────────────
 export const CHART_WHEEL_RESOURCE_URI = "ui://openephemeris/chart-wheel";
 export const CHART_WHEEL_MIME_TYPE = "text/html;profile=mcp-app";
@@ -81,6 +82,10 @@ const HOUSE_SYSTEM_MAP = {
     placidus: "P", whole_sign: "W", equal: "E", koch: "K",
     campanus: "C", regiomontanus: "R",
 };
+/** "whole_sign" → "Whole Sign" for display in text summaries. */
+function prettyHouseSystem(hs) {
+    return hs.split("_").map(capitalize).join(" ");
+}
 /** Build the nested request body expected by /ephemeris/natal-chart (POST). */
 function buildNatalBody(datetime, lat, lon, houseSystem, timezone) {
     const body = {
@@ -111,20 +116,13 @@ registerTool({
         "CREDIT COST: 1 credit per call.\n\n" +
         "Supports house system switching (Placidus, Whole Sign, Equal, Koch). " +
         "The chart is computed using NASA JPL DE440 ephemerides for sub-arcsecond precision. " +
-        "Use this instead of ephemeris_chart_wheel for a richer, interactive experience in " +
-        "MCP Apps-capable hosts (Claude Desktop). Falls back to static SVG in other hosts.",
+        "Renders interactively in MCP Apps-capable hosts (Claude Desktop) and falls back to " +
+        "static SVG in other hosts.",
     inputSchema: {
         type: "object",
         properties: {
-            datetime: {
-                type: "string",
-                description: "ISO 8601 datetime string, e.g. '1990-04-15T14:30:00'. " +
-                    "Include timezone offset if known, e.g. '1990-04-15T14:30:00-05:00'.",
-            },
-            timezone: {
-                type: "string",
-                description: "IANA timezone name (e.g. 'America/New_York'). Used if datetime has no UTC offset.",
-            },
+            datetime: { type: "string", description: DATETIME_DESC },
+            timezone: TIMEZONE_PROPERTY,
             latitude: {
                 type: "number",
                 description: "Birth latitude in decimal degrees (positive = North). Resolve from a place name with location_search; never recall coordinates from memory.",
@@ -190,7 +188,7 @@ registerTool({
         // source of the ~90 second blocking delay.
         const chartData = await client.post("/ephemeris/natal-chart", natalBody);
         // Build human-readable summary for the LLM context
-        const summary = buildChartSummary(chartData, String(args.location ?? `${lat}, ${lon}`));
+        const summary = buildChartSummary(chartData, String(args.location ?? `${lat}, ${lon}`), houseSystem);
         // Build the UI payload (planets normalised to array, server aspects mapped)
         const modelPayload = buildModelPayload(chartData, {
             datetime,
@@ -343,8 +341,8 @@ registerTool({
     inputSchema: {
         type: "object",
         properties: {
-            datetime: { type: "string", description: "ISO 8601 natal datetime string" },
-            timezone: { type: "string", description: "IANA timezone name (e.g. 'America/New_York')" },
+            datetime: { type: "string", description: DATETIME_DESC },
+            timezone: TIMEZONE_PROPERTY,
             latitude: { type: "number", description: "Birth latitude in decimal degrees (positive = North)" },
             longitude: { type: "number", description: "Birth longitude in decimal degrees (positive = East)" },
             location: { type: "string", description: "Location name for display only (e.g. 'New York, NY')" },
@@ -360,7 +358,7 @@ registerTool({
             },
             target_datetime: {
                 type: "string",
-                description: "ISO 8601 target datetime string. Reguired for solar_return or progressed calculations."
+                description: "Target datetime. Required for solar_return or progressed calculations. " + DATETIME_DESC
             }
         },
         required: ["datetime", "latitude", "longitude", "house_system"],
@@ -562,7 +560,7 @@ function buildModelPayload(chartData, birthParams, houseSystem, svgBase, bodyFil
         house_system: houseSystem,
     };
 }
-function buildChartSummary(data, location) {
+function buildChartSummary(data, location, houseSystem) {
     // The natal API returns planets as a keyed object { sun: {...}, moon: {...} }.
     // Normalise to an array before processing.
     const raw = data.planets ?? {};
@@ -623,7 +621,8 @@ function buildChartSummary(data, location) {
     const strongestNote = strongest
         ? `Closest aspect: ${capitalize(strongest.planet1)} ${strongest.type} ${capitalize(strongest.planet2)} (${strongest.orb.toFixed(1)}° orb)`
         : "";
-    const enrichment = [sectNote, domElement ? `Dominant element: ${domElement[0]} (${domElement[1]})` : "", strongestNote]
+    const housesNote = houseSystem ? `Houses: ${prettyHouseSystem(houseSystem)}` : "";
+    const enrichment = [housesNote, sectNote, domElement ? `Dominant element: ${domElement[0]} (${domElement[1]})` : "", strongestNote]
         .filter(Boolean).join(" · ");
     return (`**Natal Chart — ${location}**\n\n` +
         (enrichment ? `${enrichment}\n\n` : "") +

package/dist/tools/dev.js

@@ -190,8 +190,9 @@ registerTool({
     name: "dev_read_api",
     description: "Read from any allowlisted Open Ephemeris API endpoint via HTTP GET. This is the read-only " +
         "power-user escape hatch — use the typed tools (ephemeris_natal_chart, ephemeris_transits, etc.) " +
-        "first for common operations. For endpoints that compute via POST (natal-chart, synastry, etc.), " +
-        "use dev_write_api.\n\n" +
+        "first for common operations. Endpoints that compute via POST (natal-chart, synastry, etc.) " +
+        "are covered by the typed tools; the generic POST proxy is only exposed on the full tool " +
+        "surface (`?profile=full`).\n\n" +
         DEV_API_REFERENCE,
     inputSchema: makeProxyInputSchema(READ_METHODS),
     outputSchema: OUTPUT_SCHEMA_JSON,
@@ -216,7 +217,7 @@ registerTool({
     name: "dev_list_allowed",
     description: "List all API operations (method + path) that this MCP instance is authorized to call. " +
         "Returns endpoint entries grouped by method, plus the active deny rules. " +
-        "Use this to discover what's available before calling dev_read_api / dev_write_api, or to verify an endpoint path. " +
+        "Use this to discover what's available before calling dev_read_api, or to verify an endpoint path. " +
         "Typed shortcut tools (ephemeris_natal_chart, ephemeris_transits, etc.) cover the most common operations — " +
         "check those first before reaching for the generic proxies.",
     inputSchema: {

package/dist/tools/index.js

@@ -49,6 +49,7 @@ export const CORE_TOOL_NAMES = new Set([
     "ephemeris_planet_position",
     "ephemeris_house_cusps",
     "ephemeris_moon_phase",
+    "ephemeris_next_lunar_phase",
     "ephemeris_transits",
     "ephemeris_synastry",
     "ephemeris_retrograde_status",
@@ -60,9 +61,11 @@ export const CORE_TOOL_NAMES = new Set([
     "human_design_chart",
     "vedic_chart",
     "chinese_bazi",
+    "bazi_annual_pillar",
     // Timing
     "ephemeris_electional",
     "electional_moment_analysis",
+    "electional_station_tracker",
     // Astrocartography
     "acg_power_lines",
     "acg_hits",

package/dist/tools/specialized/bazi.js

@@ -144,10 +144,9 @@ registerTool({
         "Includes the Day Master element and basic metadata.\n\n" +
         "CREDIT COST: 1 credit (3 credits when include_visual=true).\n\n" +
         "Set include_visual=true to receive a rendered SVG chart alongside the text data.\n\n" +
-        "For deep analysis, follow up with:\n" +
-        "  • bazi_ten_gods()         — Ten Gods (十神) per pillar including hidden stems\n" +
-        "  • bazi_element_balance()  — Weighted Wu Xing (五行) element scores + Yong Shen\n" +
-        "  • bazi_luck_pillars()     — 8 Da Yun 10-year luck cycles\n\n" +
+        "For deep analysis — Ten Gods (十神) per pillar, weighted Wu Xing (五行) element balance, " +
+        "Da Yun 10-year luck cycles — dedicated tools are available on the full tool surface " +
+        "(`?profile=full` on HTTP, OPENEPHEMERIS_TOOLS=full on stdio).\n\n" +
         "EXAMPLE: BaZi chart for someone born July 15, 1987 at 2 PM:\n" +
         "  year=1987, month=7, day=15, hour=14",
     inputSchema: {

package/dist/tools/specialized/comparative.js

@@ -1,7 +1,11 @@
 import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
-import { localToUtcIso } from "../datetime.js";
+import { DATETIME_DESC, assertZonedDatetime, localToUtcIso, timezoneProperty } from "../datetime.js";
+/** Reject a zone-less person datetime here, before a credit is spent on it. */
+function assertPersonZoned(prefix, args) {
+    assertZonedDatetime(`${prefix}_datetime`, args[`${prefix}_datetime`], args[`${prefix}_timezone`], `${prefix}_timezone`);
+}
 function buildSubject(name, datetime, lat, lon, timezone) {
     const subj = {
         name,
@@ -30,12 +34,12 @@ registerTool({
     inputSchema: {
         type: "object",
         properties: {
-            person_a_datetime: { type: "string", description: "Person A birth datetime (ISO 8601)." },
-            person_a_timezone: { type: "string", description: "IANA timezone name for Person A, e.g. 'America/Denver'." },
+            person_a_datetime: { type: "string", description: DATETIME_DESC },
+            person_a_timezone: timezoneProperty("Person A's birth location", "America/Denver"),
             person_a_latitude: { type: "number", description: "Person A birth latitude." },
             person_a_longitude: { type: "number", description: "Person A birth longitude." },
-            person_b_datetime: { type: "string", description: "Person B birth datetime (ISO 8601)." },
-            person_b_timezone: { type: "string", description: "IANA timezone name for Person B, e.g. 'Europe/London'." },
+            person_b_datetime: { type: "string", description: DATETIME_DESC },
+            person_b_timezone: timezoneProperty("Person B's birth location", "Europe/London"),
             person_b_latitude: { type: "number", description: "Person B birth latitude." },
             person_b_longitude: { type: "number", description: "Person B birth longitude." },
             format: { type: "string", enum: ["json", "llm"], description: "Use 'llm' for token-efficient LLM projection." },
@@ -53,6 +57,8 @@ registerTool({
             "person_a_datetime", "person_a_latitude", "person_a_longitude",
             "person_b_datetime", "person_b_latitude", "person_b_longitude",
         ]);
+        assertPersonZoned("person_a", args);
+        assertPersonZoned("person_b", args);
         const query = {};
         if (args.format)
             query.format = args.format;
@@ -76,12 +82,12 @@ registerTool({
     inputSchema: {
         type: "object",
         properties: {
-            person_a_datetime: { type: "string", description: "Person A birth datetime (ISO 8601)." },
-            person_a_timezone: { type: "string", description: "IANA timezone name for Person A, e.g. 'America/Denver'." },
+            person_a_datetime: { type: "string", description: DATETIME_DESC },
+            person_a_timezone: timezoneProperty("Person A's birth location", "America/Denver"),
             person_a_latitude: { type: "number", description: "Person A birth latitude." },
             person_a_longitude: { type: "number", description: "Person A birth longitude." },
-            person_b_datetime: { type: "string", description: "Person B birth datetime (ISO 8601)." },
-            person_b_timezone: { type: "string", description: "IANA timezone name for Person B, e.g. 'Europe/London'." },
+            person_b_datetime: { type: "string", description: DATETIME_DESC },
+            person_b_timezone: timezoneProperty("Person B's birth location", "Europe/London"),
             person_b_latitude: { type: "number", description: "Person B birth latitude." },
             person_b_longitude: { type: "number", description: "Person B birth longitude." },
             format: { type: "string", enum: ["json", "llm"], description: "Use 'llm' for token-efficient LLM projection." },
@@ -99,6 +105,8 @@ registerTool({
             "person_a_datetime", "person_a_latitude", "person_a_longitude",
             "person_b_datetime", "person_b_latitude", "person_b_longitude",
         ]);
+        assertPersonZoned("person_a", args);
+        assertPersonZoned("person_b", args);
         const query = {};
         if (args.format)
             query.format = args.format;
@@ -122,12 +130,12 @@ registerTool({
     inputSchema: {
         type: "object",
         properties: {
-            person_a_datetime: { type: "string", description: "Person A birth datetime (ISO 8601)." },
-            person_a_timezone: { type: "string", description: "IANA timezone name for Person A, e.g. 'America/Denver'." },
+            person_a_datetime: { type: "string", description: DATETIME_DESC },
+            person_a_timezone: timezoneProperty("Person A's birth location", "America/Denver"),
             person_a_latitude: { type: "number", description: "Person A birth latitude." },
             person_a_longitude: { type: "number", description: "Person A birth longitude." },
-            person_b_datetime: { type: "string", description: "Person B birth datetime (ISO 8601)." },
-            person_b_timezone: { type: "string", description: "IANA timezone name for Person B, e.g. 'Europe/London'." },
+            person_b_datetime: { type: "string", description: DATETIME_DESC },
+            person_b_timezone: timezoneProperty("Person B's birth location", "Europe/London"),
             person_b_latitude: { type: "number", description: "Person B birth latitude." },
             person_b_longitude: { type: "number", description: "Person B birth longitude." },
             format: { type: "string", enum: ["json", "llm"], description: "Use 'llm' for token-efficient LLM projection." },
@@ -145,6 +153,8 @@ registerTool({
             "person_a_datetime", "person_a_latitude", "person_a_longitude",
             "person_b_datetime", "person_b_latitude", "person_b_longitude",
         ]);
+        assertPersonZoned("person_a", args);
+        assertPersonZoned("person_b", args);
         const query = {};
         if (args.format)
             query.format = args.format;
@@ -171,12 +181,12 @@ registerTool({
     inputSchema: {
         type: "object",
         properties: {
-            natal_datetime: { type: "string", description: "Natal birth datetime (ISO 8601)." },
-            natal_timezone: { type: "string", description: "IANA timezone name for Natal, e.g. 'America/Denver'." },
+            natal_datetime: { type: "string", description: DATETIME_DESC },
+            natal_timezone: timezoneProperty("the natal birth location", "America/Denver"),
             natal_latitude: { type: "number", description: "Natal birth latitude." },
             natal_longitude: { type: "number", description: "Natal birth longitude." },
-            transit_datetime: { type: "string", description: "Transit moment (ISO 8601). Defaults to now." },
-            transit_timezone: { type: "string", description: "IANA timezone name for Transit, e.g. 'America/Denver'. Only applicable if transit_datetime is provided without offset." },
+            transit_datetime: { type: "string", description: "Transit moment. Defaults to now. " + DATETIME_DESC },
+            transit_timezone: timezoneProperty("the transit moment", "America/Denver"),
             format: { type: "string", enum: ["json", "llm"], description: "Use 'llm' for token-efficient LLM projection." },
         },
         required: ["natal_datetime", "natal_latitude", "natal_longitude"],
@@ -186,6 +196,7 @@ registerTool({
     annotations: { title: "Transits to Natal Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, ["natal_datetime", "natal_latitude", "natal_longitude"]);
+        assertPersonZoned("natal", args);
         // Backend expects: { subject: {...}, transit_datetime?: {...} }
         // NOT a subjects[] array — natal-transits is a single-subject endpoint
         const body = {

package/dist/tools/specialized/electional.js

@@ -1,6 +1,7 @@
 import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
+import { WINDOW_DATE_DESC } from "../datetime.js";
 // All electional endpoints are GET endpoints with query params.
 // GET /electional/find-window — already existed, keeping it
 registerTool({
@@ -17,11 +18,11 @@ registerTool({
         properties: {
             start_date: {
                 type: "string",
-                description: "ISO 8601 start date or datetime for the search window (e.g., 2026-03-01).",
+                description: "Start of the search window, e.g. '2026-03-01'. " + WINDOW_DATE_DESC,
             },
             end_date: {
                 type: "string",
-                description: "ISO 8601 end date or datetime for the search window.",
+                description: "End of the search window. " + WINDOW_DATE_DESC,
             },
             latitude: {
                 type: "number",
@@ -128,6 +129,8 @@ registerTool({
         "Returns exact station times, longitudes, and signs.\n\n" +
         "USE THIS TOOL FOR: 'When does Mercury go retrograde?', 'Is Venus retrograde this year?', " +
         "'What planets station this month?', 'When does Mars go direct?'\n\n" +
+        "❌  NOT FOR: 'Is Mercury retrograde right now?' — that is the state at a single instant, " +
+        "so use ephemeris_retrograde_status (1 credit for one planet, vs 5 here).\n\n" +
         "All required fields have smart defaults (searches the next 90 days from today).\n\n" +
         "CREDIT COST: 5 credits per call.\n\n" +
         "EXAMPLE: Mercury and Venus stations in the next 3 months (all defaults):\n" +
@@ -206,7 +209,7 @@ registerTool({
         properties: {
             date: {
                 type: "string",
-                description: "ISO 8601 datetime to check. Defaults to now.",
+                description: "Datetime to check. Defaults to now. " + WINDOW_DATE_DESC,
             },
             max_orb: {
                 type: "number",

package/dist/tools/specialized/ephemeris_extended.js

@@ -1,4 +1,4 @@
-import { registerTool, validateRequired } from "../index.js";
+import { registerTool, validateRequired, validateCoordinates } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
 import { DATETIME_DESC, TIMEZONE_PROPERTY, assertZonedDatetime, localToUtcIso } from "../datetime.js";
@@ -88,17 +88,27 @@ registerTool({
 // the documented "all planets" behaviour works correctly.
 registerTool({
     name: "ephemeris_retrograde_status",
-    description: "Get retrograde/direct status and speed for all planets at a given date/time. " +
-        "Returns is_retrograde flag, longitude speed, and station proximity for every planet.\n\n" +
-        "CREDIT COST: 10 credits for the all-planets sweep (the backend bills one " +
-        "credit per body and this fans out to 10), or 1 credit when planet_id is given.\n\n" +
-        "Optionally pass planet_id (0-9) to query a single planet.",
+    description: "Get retrograde/direct status and speed for ONE planet — or, if you ask for it, all " +
+        "ten — at a given date/time. Returns is_retrograde flag, longitude speed, and station " +
+        "proximity.\n\n" +
+        "✅  Answers 'is X retrograde?' at ONE instant. Pass planet_id for the named planet; " +
+        "'is Mercury retrograde?' is planet_id=2, not a whole-sky sweep. For WHEN a planet turns " +
+        "retrograde or direct, or whether it stations anywhere in a date range, use " +
+        "electional_station_tracker.\n\n" +
+        "CREDIT COST: 1 credit for a single planet (pass planet_id). Omitting planet_id runs the " +
+        "all-planets sweep and costs 10 credits — the backend bills one credit per body and this " +
+        "fans out to 10. Only omit it when the question really is about every planet.",
     inputSchema: {
         type: "object",
         properties: {
             datetime: { type: "string", description: DATETIME_DESC },
             timezone: TIMEZONE_PROPERTY,
-            planet_id: { type: "integer", description: "Optional single planet ID (0-9). Omit for all planets." },
+            planet_id: {
+                type: "integer",
+                description: "Single planet ID (0=Sun, 1=Moon, 2=Mercury, 3=Venus, 4=Mars, 5=Jupiter, " +
+                    "6=Saturn, 7=Uranus, 8=Neptune, 9=Pluto). Pass this whenever the question " +
+                    "names a planet — 1 credit. Omit only to sweep all ten — 10 credits.",
+            },
         },
         required: ["datetime"],
         additionalProperties: false,
@@ -168,14 +178,28 @@ registerTool({
 // POST /ephemeris/fixed-stars
 registerTool({
     name: "ephemeris_fixed_stars",
-    description: "Calculate positions of fixed stars and conjunctions to natal planets. " +
-        "Returns star longitude, magnitude, and any planets within orb.\n\n" +
+    description: "Fixed star positions (ecliptic longitude, magnitude) and the chart points conjunct them. " +
+        "Always scans the ten traditional planets.\n\n" +
+        "⚠️  ANGLES REQUIRE A LOCATION: 'what stars are on my Ascendant?' is only answerable with " +
+        "latitude AND longitude — ASC/MC/DSC/IC depend on place, not just time. Supply both and the " +
+        "four angles join the scan; omit them and the result covers PLANETS ONLY. Each conjunction " +
+        "is tagged point_type 'planet' or 'angle', and the angle longitudes used come back in " +
+        "`angles`, so never report a planetary hit as an Ascendant hit.\n\n" +
         "CREDIT COST: 1 credit per call.",
     inputSchema: {
         type: "object",
         properties: {
             datetime: { type: "string", description: DATETIME_DESC },
             timezone: TIMEZONE_PROPERTY,
+            latitude: {
+                type: "number",
+                description: "Observer latitude in decimal degrees. Required (with longitude) to scan the angles. " +
+                    "Resolve from a place name with location_search; never recall coordinates from memory.",
+            },
+            longitude: {
+                type: "number",
+                description: "Observer longitude in decimal degrees. Required (with latitude) to scan the angles.",
+            },
             star_names: {
                 type: "array",
                 items: { type: "string" },
@@ -190,45 +214,26 @@ registerTool({
     annotations: { title: "Fixed Stars", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, ["datetime"]);
+        // A lone latitude would silently drop the angles from the scan, which is
+        // the exact failure this tool exists to avoid — reject it instead.
+        validateCoordinates(args, "latitude", "longitude");
         const body = {
             date_time: { iso: localToUtcIso("datetime", args.datetime, args.timezone) },
         };
+        if (args.latitude != null)
+            body.latitude = args.latitude;
+        if (args.longitude != null)
+            body.longitude = args.longitude;
         if (args.star_names)
             body.star_names = args.star_names;
         if (args.orb != null)
             body.orb = args.orb;
-        const raw = await getActiveClient().post("/ephemeris/fixed-stars", body);
-        // Bug 6 workaround: backend returns longitude as degrees-within-sign (0–30),
-        // not full ecliptic longitude (0–360). Compute full_longitude from sign name.
-        const SIGN_ORDER = {
-            Aries: 0, Taurus: 1, Gemini: 2, Cancer: 3, Leo: 4, Virgo: 5,
-            Libra: 6, Scorpio: 7, Sagittarius: 8, Capricorn: 9, Aquarius: 10, Pisces: 11,
-        };
-        function enrichStar(star) {
-            if (!star || typeof star !== "object")
-                return star;
-            const signLon = typeof star.longitude === "number" ? star.longitude : 0;
-            const signName = star.sign ?? star.sign_name ?? "";
-            const signIndex = SIGN_ORDER[signName] ?? -1;
-            const fullLon = signIndex >= 0 ? signIndex * 30 + signLon : signLon;
-            return {
-                ...star,
-                longitude: fullLon, // ecliptic longitude 0–360
-                sign_longitude: signLon, // original within-sign degrees preserved
-                sign: signName || undefined,
-            };
-        }
-        // Normalise the response — backend may return array or { stars: [...] }
-        if (Array.isArray(raw)) {
-            return raw.map(enrichStar);
-        }
-        if (raw && typeof raw === "object") {
-            const starsKey = ["stars", "data", "fixed_stars", "results"].find((k) => Array.isArray(raw[k]));
-            if (starsKey) {
-                return { ...raw, [starsKey]: raw[starsKey].map(enrichStar) };
-            }
-        }
-        return raw;
+        // No response rewriting: /ephemeris/fixed-stars returns full ecliptic
+        // longitude (0–360) directly. It previously returned degrees-within-sign,
+        // and the workaround here reconstructed the full value from a `sign`
+        // field the endpoint never actually sent — so it was inert. Both the
+        // backend bug and the dead workaround are gone.
+        return await getActiveClient().post("/ephemeris/fixed-stars", body);
     },
 });
 // POST /ephemeris/hermetic-lots

package/dist/tools/specialized/moon.js

@@ -4,10 +4,12 @@ import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
 import { TIMEZONE_PROPERTY, localToUtcIso } from "../datetime.js";
 registerTool({
     name: "ephemeris_moon_phase",
-    description: "Get the Moon's current phase angle, illumination, and void-of-course status AT a specific " +
-        "point in time. Returns phase name (New, Waxing Crescent, First Quarter, etc.), exact angle, " +
-        "illumination %, and next void-of-course period.\n\n" +
-        "⚠️  THIS TOOL ANSWERS: 'What phase is the moon in right now (or at a given datetime)?'\n" +
+    description: "Get the Moon's current phase angle, illumination, sign and void-of-course status AT a " +
+        "specific point in time. Returns phase name (New, Waxing Crescent, First Quarter, etc.), exact " +
+        "angle, illumination %, the zodiac sign and degree the Moon occupies, and next void-of-course " +
+        "period.\n\n" +
+        "⚠️  THIS TOOL ANSWERS: 'What phase is the moon in right now (or at a given datetime)?' and " +
+        "'What sign is the moon in?'\n" +
         "❌  THIS TOOL DOES NOT ANSWER: 'When is the next new moon / full moon?'\n" +
         "→   For upcoming phase DATES use ephemeris_next_lunar_phase instead.\n\n" +
         "For a user-facing interactive moon-phase dial, use explore_moon_phase instead.\n\n" +
@@ -66,10 +68,13 @@ registerTool({
 registerTool({
     name: "ephemeris_next_lunar_phase",
     description: "Find the next occurrence of a specific Moon phase after a given date. " +
-        "Returns the exact UTC datetime, zodiac sign, and degree.\n\n" +
+        "Returns the exact UTC datetime of each occurrence.\n\n" +
         "✅  USE THIS TOOL FOR: 'When is the next new moon?', 'When is the next full moon?', " +
-        "'What date is the next quarter moon?', or any question about UPCOMING phase dates.\n\n" +
-        "CREDIT COST: 1 credit per call.\n\n" +
+        "'What date is the next quarter moon?', or any question about UPCOMING phase dates.\n" +
+        "❌  NOT FOR: 'What phase is the moon in right now?' or 'What sign is the moon in?'\n" +
+        "→   For the phase, sign and degree AT a moment, use ephemeris_moon_phase.\n\n" +
+        "CREDIT COST: about 1 credit per occurrence returned — count=1 costs 1 credit, " +
+        "count=3 costs 3.\n\n" +
         "EXAMPLE: Find the next new moon:\n" +
         "  phase='new_moon'\n\n" +
         "EXAMPLE: Find the next full moon after a specific date:\n" +
@@ -103,64 +108,87 @@ registerTool({
     outputSchema: OUTPUT_SCHEMA_JSON,
     annotations: { title: "Next Lunar Phase", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
-        // Map our clean enum to display names the calendar API returns
-        const phaseNameMap = {
+        const PHASE_LABELS = {
             new_moon: "New Moon",
             full_moon: "Full Moon",
             first_quarter: "First Quarter",
             last_quarter: "Last Quarter",
         };
-        const phaseLabel = phaseNameMap[args.phase] ?? args.phase;
+        // The engine names the waning quarter `third_quarter`; accept both spellings.
+        const PHASE_IDS = {
+            new_moon: ["new_moon"],
+            full_moon: ["full_moon"],
+            first_quarter: ["first_quarter"],
+            last_quarter: ["last_quarter", "third_quarter"],
+        };
+        const phaseLabel = PHASE_LABELS[args.phase];
+        const wanted = PHASE_IDS[args.phase];
+        if (!wanted) {
+            throw new Error(`Unknown phase '${args.phase}'. Use one of: ${Object.keys(PHASE_IDS).join(", ")}.`);
+        }
         const count = Math.max(1, Math.min(12, args.count ?? 1));
-        // Build a search window wide enough to capture `count` occurrences.
-        // Lunar cycle is ~29.5 days, so count * 35 days guarantees coverage.
-        const startDate = args.after_date
-            ? args.after_date.substring(0, 10)
-            : new Date().toISOString().substring(0, 10);
-        const endMs = new Date(startDate + "T00:00:00Z").getTime() + count * 35 * 24 * 60 * 60 * 1000;
-        const endDate = new Date(endMs).toISOString().substring(0, 10);
-        const result = await getActiveClient().request("GET", "/calendar/astrology/moon-phases", {
-            params: { start_date: startDate, end_date: endDate },
-        });
-        // Normalise response shape — defensively handle every known API envelope shape.
-        // Crash "allPhases.filter is not a function" occurs when a property like
-        // result.data is truthy but is an object, not an array.
-        function extractArray(val) {
-            if (Array.isArray(val))
-                return val;
-            if (val && typeof val === "object") {
-                // one level deeper: { phases: [...] }, { data: [...] }, etc.
-                for (const key of ["phases", "data", "events", "moon_phases", "results", "items"]) {
-                    const nested = val[key];
-                    if (Array.isArray(nested))
-                        return nested;
-                }
+        const startDate = (args.after_date ?? new Date().toISOString()).substring(0, 10);
+        const startMs = Date.parse(startDate + "T00:00:00Z");
+        if (Number.isNaN(startMs)) {
+            throw new Error(`after_date must be an ISO date like '2026-06-01', got '${args.after_date}'.`);
+        }
+        const HALF_DAY = 12 * 60 * 60 * 1000;
+        // The calendar endpoint takes a single `date` (it searches forward from noon UTC
+        // that day) and returns the first occurrence of each principal phase within the
+        // following ~30 days. So one request yields at most one hit for the phase we want.
+        async function phaseTimesFrom(probeDay) {
+            const result = await getActiveClient().request("GET", "/calendar/astrology/moon-phases", { params: { date: probeDay } });
+            const events = Array.isArray(result?.data?.events) ? result.data.events : [];
+            // The endpoint prepends the Moon's *current* 8-phase bucket, stamped with the
+            // query instant (noon UTC of `date`) rather than an event time. Left in, it
+            // reads as a real phase occurring at exactly 12:00:00. Computed moments always
+            // carry sub-second precision, so an exact hit on noon is that placeholder.
+            const probeNoonMs = Date.parse(probeDay + "T12:00:00Z");
+            return events
+                .filter((e) => wanted.includes(String(e?.phase ?? e?.phase_name ?? "").toLowerCase()))
+                .map((e) => Date.parse(e?.time ?? e?.iso_time ?? ""))
+                .filter((ms) => !Number.isNaN(ms) && ms !== probeNoonMs)
+                .sort((a, b) => a - b);
+        }
+        // Probe from the day containing `afterMs - 12h`, so its noon-UTC search origin is
+        // always at or before `afterMs` and an occurrence earlier the same day is still
+        // visible. That leaves under a day of slack behind the cursor, which can hold at
+        // most one occurrence (they are ~29.5 days apart) — hence a single re-probe.
+        async function findNext(afterMs) {
+            let probeMs = afterMs - HALF_DAY;
+            for (let probe = 0; probe < 2; probe++) {
+                const hits = await phaseTimesFrom(new Date(probeMs).toISOString().substring(0, 10));
+                const next = hits.find((ms) => ms > afterMs);
+                if (next != null)
+                    return next;
+                if (hits.length === 0)
+                    return null;
+                probeMs = hits[hits.length - 1] + HALF_DAY;
             }
             return null;
         }
-        const allPhases = extractArray(result) ?? [];
-        const matching = allPhases
-            .filter((p) => {
-            const name = (p.phase_name ?? p.name ?? p.phase ?? "").toLowerCase();
-            return (name === phaseLabel.toLowerCase() ||
-                name === args.phase.replace("_", " ").toLowerCase());
-        })
-            .slice(0, count);
-        if (matching.length === 0) {
-            // Return full calendar as fallback so the LLM can inspect it
-            return {
-                requested_phase: phaseLabel,
-                search_window: { start_date: startDate, end_date: endDate },
-                result_count: 0,
-                note: "No matching phase found in window. Full calendar returned for inspection.",
-                full_calendar: allPhases,
-            };
+        const results = [];
+        let cursorMs = startMs - 1; // include an occurrence at exactly 00:00 on after_date
+        for (let i = 0; i < count; i++) {
+            const hitMs = await findNext(cursorMs);
+            if (hitMs == null)
+                break;
+            results.push({ phase: args.phase, datetime: new Date(hitMs).toISOString() });
+            cursorMs = hitMs;
+        }
+        // Every principal phase recurs every ~29.5 days, so an empty result is impossible.
+        // Fail loudly rather than handing back a plausible "there isn't one" non-answer.
+        if (results.length === 0) {
+            throw new Error(`Lunar phase search failed: the backend returned no ${phaseLabel} after ` +
+                `${startDate}. A ${phaseLabel} occurs roughly every 29.5 days, so this is a ` +
+                `backend fault, not a real answer — do not report that there is no upcoming ` +
+                `${phaseLabel}.`);
         }
         return {
             requested_phase: phaseLabel,
             after_date: startDate,
-            results: matching,
-            result_count: matching.length,
+            result_count: results.length,
+            results,
         };
     },
 });

package/package.json

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