@openephemeris/mcp-server 3.24.0 → 4.1.0

package/CHANGELOG.md

@@ -7,6 +7,179 @@ Version numbering follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [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.
+
+This release also carries everything from 3.26.0, which was written up but never published to npm (`latest` was 3.24.0). Nothing is lost; the 3.26.0 entry below is part of what ships here.
+
+### Fixed
+
+- **A birth time without a timezone was silently read as UTC, producing the wrong houses and angles.** This is the headline fix, and it is a correctness bug rather than a cosmetic one.
+
+  Given `datetime='1987-07-15T09:01:00'` with Dallas coordinates — 9:01 AM local, which is 14:01 UTC in July — the API computed the chart for 09:01 **UTC**: five hours early. Every planet keeps its sign at that error scale, so the output passed casual inspection, while the Ascendant landed in Gemini instead of Leo (77.97° vs 143.12°), the Midheaven moved nearly three signs, and every house placement was wrong. In Human Design the same input returned profile 2/4 instead of 2/5 and a Design Sun on gate 42 line 4 instead of line 5.
+
+  A datetime that states a clock time but not the zone that clock is in does not name a moment, so the server no longer guesses. It is now a `400` with an RFC 7807 `ambiguous_datetime` problem that names **both** fixes — put a `Z`/`±HH:MM` offset on the value, or pass the local time together with a `timezone`. Rejecting is the right default for a chart-correctness product: a loud failure costs one retry, a silent five-hour shift costs the whole reading.
+
+  A date with no clock time (`'1987-07-15'`) is unaffected and still resolves to 12:00 UTC — there is nothing ambiguous about it, and every search-window parameter in the API depends on it.
+
+- **Every tool that takes a datetime now takes a `timezone`.** Previously only four did (`ephemeris_natal_chart`, `ephemeris_chart_wheel`, `ephemeris_bi_wheel`, and the `explore_*` apps), which left callers of `ephemeris_synastry`, `ephemeris_relocation`, the return tools, the ACG tools, `ephemeris_angles_points`, `ephemeris_house_cusps` and the rest with **no correct way to express a local birth time at all**. There is now a test that fails if a tool gains a datetime parameter without one.
+
+- **The Human Design tools documented `"Must include 'Z' or timezone offset"` and then silently appended a `Z` themselves.** Four separate copies of an `ensureTimezone` helper turned any zone-less value into a UTC assertion the caller never made — which is precisely what made the error invisible. `human_design_composite` and `human_design_penta` skipped even that and passed the naive string straight through. All of them now take a `timezone`, resolve it properly (including historical DST — 1987 Chicago is UTC-5, not UTC-6), and refuse to invent a zone.
+
+- **The documentation taught the bug.** `ephemeris_natal_chart`'s example was `datetime='1990-04-15T14:30:00'` with Chicago coordinates, no offset and no timezone — copied verbatim by models reading it. `acg_power_lines`, `acg_hits` and `ephemeris_progressed_chart` each carried a naive example that directly contradicted their own parameter description warning against naive input. Every ISO example across the tool surface now states its zone, and a repo test fails the build if a new one appears.
+
+- **BaZi charts depended on the server's own timezone.** `parseBaziArgs` did `new Date('1987-07-15T14:00:00')`, which JavaScript resolves in the *host process's* zone, then read `.getUTCHours()`. On any server not running in UTC this shifted the hour pillar, and near midnight the day pillar. Components are now read from the string itself. (BaZi pillars are built from local wall-clock time by definition, so a zone-less datetime is correct there — it was the reading that was wrong, not the input.)
+
+- **`ephemeris_natal_transits` declared a `transit_timezone` parameter that the handler never read.** It is now applied.
+
+- **`vedic_chart_recalculate` dropped the `timezone` that `explore_vedic_chart` accepts**, so re-rendering the same chart from the iframe interpreted the birth time as UTC and produced a different chart than the one on screen.
+
+### Changed
+
+- Responses now echo the instant they were actually computed for: `resolved_utc`, plus `datetime_zone_source` (`offset` / `timezone` / `date_only`) and the zone itself. When a chart looks wrong, the first question is which moment it was cast for, and the answer is now in the response.
+
+---
+
+## [3.26.0] — 2026-07-25
+
+A leaner default tool list, and a sweep of documentation and billing corrections found while auditing it.
+
+The server has grown to 91 registered tools, 69 of which were advertised to the model on every single connection. That is roughly 28,000 tokens of tool definitions consumed before the user has said anything, and a 69-item menu to choose from on questions that almost always want one of about a dozen tools. This release changes what gets *advertised* without changing what exists.
+
+### Added
+
+- **Tool surfaces — a focused default, with the full catalog one flag away.** `tools/list` now returns a curated core set (32 tools over HTTP, 35 over stdio) instead of everything: one interactive app per tradition, the primary data tool per domain, geocoding, account usage, and the allowlist-gated generic proxy. Measured tool-definition payload drops from ~27,800 to ~15,100 tokens.
+
+  **No capability was removed.** This is a filter on `tools/list` alone — every tool remains registered and remains callable by name. If a client knows the tool it wants, it works whether or not it was listed. There is a regression test asserting exactly this, because a surface filter that quietly became a capability cut would be a very easy mistake to ship.
+
+  Opt into the full catalog with `OPENEPHEMERIS_TOOLS=full` (stdio) or `?profile=full` / `X-OE-Tool-Surface: full` (remote HTTP). The surface is fixed at session initialize — this server does not advertise `tools.listChanged`, so switching means reconnecting. The public server card at `/.well-known/mcp/server-card.json` deliberately still lists everything: it is a registry catalog, not model context.
+
+- **Usage reporting now covers the stdio transport, and identifies the connecting client.** Telemetry previously existed only on the remote HTTP server, so the entire npm install base — every Claude Desktop, Cursor and Windsurf user — was invisible. Both transports now emit the same three events with the same properties (`transport`, `surface`, `client_name`, `client_version`, `server_version`), so a single query can compare them. `client_name` comes from the MCP initialize handshake and is the only way to know which hosts this package actually runs in.
+
+  **This is disclosed and opt-out-able**, because it runs on your machine: see [Telemetry](README.md#telemetry). Tool name, duration, error status, client name and a one-way hash of your API key are sent. Your key, birth data, coordinates, tool arguments and tool results never are. Disable with `OPENEPHEMERIS_TELEMETRY=0` or the cross-tool standard `DO_NOT_TRACK=1`; both are checked before anything is sent, and are covered by tests.
+
+- **`location_search` and `timezone_resolve` are now visible to the model.** Both existed but were marked app-only, so the model could not call them — which is why prompts had to geocode through `dev_read_api /location/autocomplete` instead. Turning a birth city into coordinates and an IANA timezone is now a first-class two-step.
+
+### Fixed
+
+- **`ephemeris_planet_position` documented the wrong body for `planet_id=11`.** The description advertised `10=North Node, 11=South Node`. The API actually returns `10` = North Node (Mean) and `11` = North Node (**True**) — there is no South Node id at all. A request for a South Node returned the North Node with no error and no warning: a silently wrong answer, roughly 180° off. The description now documents the real ids and explains that the South Node is the North Node opposed (add 180°, mod 360).
+
+- **Ten tools misstated their credit cost.** Costs are metered server-side on the URL path, so billing was always correct — but the descriptions the model reads were not, which meant plans and cost estimates built on them were wrong. Corrected: the BaZi analytical tools (`bazi_ten_gods`, `bazi_element_balance`, `bazi_luck_pillars`, `bazi_annual_pillar` — 1 → 3; `bazi_compatibility` — 2 → 3), the electional tools (`electional_moment_analysis` and `electional_aspect_search` — 2 → 5; `electional_station_tracker` — 3 → 5), and the Venus tools, which were **overstated** at 2 and actually cost 1. `ephemeris_retrograde_status` now discloses that its all-planets sweep fans out to ten backend calls and costs 10 credits, not 1.
+
+- **`/chinese/bazi/chart` charged 4 credits while documenting 3.** The handler reserved base + visual render, but the route is mounted behind the usage-tracking middleware, which had already debited the base credit — so every BaZi chart render double-charged its base credit. The handler now reserves only the visual surcharge, matching the pattern already used by the `include_visual` wrapper. Actual cost is now 3, as documented.
+
+- **Progressed chart recalculation in the chart-wheel app posted to `/predictive/progressed`, which does not exist.** The real path is `/ephemeris/progressed`; every progressed recalculate from the iframe was 404ing.
+
+- **`ephemeris_lunar_return` and `ephemeris_planetary_return` declared an output schema promising an image** they can never return — neither tool sends `include_visual`. Both now declare the JSON-only schema they actually produce.
+
+- **Tool-error telemetry could not distinguish a backend outage from a client-side argument error.** Errors thrown locally carry no HTTP status, so they were all recorded as `status: "unknown"` alongside genuine backend failures. Error events now carry `error_kind` (`backend` / `local`) and the error code.
+
+- **WCAG AA contrast restored in the dark widget palette.** The 3.24.0 theme unification left five of the seven embedded apps — bodygraph, moon-phase, transit-timeline, vedic-chart and bazi — with muted and secondary text below the minimum contrast ratio. Those bundles ship inside this package (`dist/ui`), so anyone rendering the iframe apps saw it. The visual gate that should have caught it now audits **both** palettes per app and state; previously it only ever rendered one, which is how a whole-palette regression stayed green.
+
+- **A release could not pass its own gate.** `npm publish` runs `verify:release` → `check:public`, which byte-compares the files mirrored to the public repo. Neither side pinned line endings, so a Windows checkout rewrote them to CRLF and the check reported permanent drift on files nobody had edited. Both repos now pin LF.
+
+- **Stale references in the skill packs and plugin docs.** The setup and API-reference skills still described `dev.call` / `dev.list_allowed`, names retired in 3.15.0 (the tools are `dev_read_api`, `dev_write_api`, `dev_list_allowed`). The plugin skill listed `electional_ingress_calendar`, which is not a tool this server has ever registered. Endpoint counts corrected to 118.
+
+### Notes
+
+Registered tool count is unchanged at 91 — this release changes what is advertised, not what exists.
+
+---
+
+## [3.25.0] — 2026-07-22
+
+New account-usage tool, remote-transport session-security hardening, plus text-encoding and telemetry fixes. Registered tool count: 90 → 91.
+
+### Added
+- **`account_usage`** — a free (0-credit) tool that answers "how many credits do I have left?" directly in chat: plan tier, billing period, credits used / included / remaining, percent of quota used, total API calls, and subscription status with renewal date, plus the right next step (wallet top-up or plan upgrade) for the user's tier. Accepts an optional `month` (YYYY-MM) to review past periods.
+
+### Security
+- **Sessions are now bound to the credential that created them.** Previously the resume path (`POST /mcp` with an `mcp-session-id`) accepted *any* syntactically valid API key or unexpired Bearer token — it never checked that the presented credential matched the one that initialized the session. A leaked or guessed session id combined with a *different* valid credential could attach to another user's session. Each session now stores a SHA-256 hash of a stable binding token (the raw API key, or the JWT `sub`/subject for OAuth so legitimate ~hourly token refresh still matches) and every resume must present a credential whose hash matches, compared in constant time. Mismatches get a `403 application/problem+json`.
+- **The SSE stream leg (`GET /mcp`) now requires authentication.** It previously checked only the `mcp-session-id` header with no credential at all, so a leaked session id alone let an attacker attach to another user's server→client event stream. It now requires a credential (401 without one) and the same credential-binding match as resume (403 on mismatch).
+
+### Fixed
+- **Bodygraph gate/center text encoding repaired** — the Human Design bodygraph click-handler tools contained double-encoded UTF-8 (mojibake) in em-dashes, ranges, and status emoji across all 64 gate hexagram names and the center descriptions; they now render correctly.
+- **Tool-error telemetry now records HTTP status** — the remote server's error events always reported "unknown" instead of the actual status (402 paywall / 429 rate-limit), making those uncountable in analytics.
+- **`autoStartDeviceAuth` race (stdio device-auth):** concurrent first requests could each launch a device-auth flow (two codes, two poll loops) because the in-flight guard was only assigned after the async start resolved. The guard promise is now assigned synchronously before the first await.
+- **Corrected a stale code comment** claiming HTTP 429 responses are retried — they are deliberately not (retrying a metered POST would double-charge; only idempotent GETs over 502/503/504 + transient transport codes retry).
+
 ## [3.24.0] — 2026-07-21
 
 Mandala layout for the bodygraph iframe app — an in-iframe toggle between the classic graph and the concentric-rings mandala view, plus a metered house-ring opt-in.

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025-2026 Open Ephemeris
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025-2026 Open Ephemeris
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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 |
@@ -281,6 +315,8 @@ The server is hosted at `https://mcp.openephemeris.com/mcp` with full Streamable
 | `ASTROMCP_API_KEY` | No | Legacy alias for `OPENEPHEMERIS_API_KEY` (checked as fallback) |
 | `OPENEPHEMERIS_BACKEND_URL` | No | Defaults to `https://api.openephemeris.com` |
 | `OPENEPHEMERIS_PROFILE` | No | `dev` by default |
+| `OPENEPHEMERIS_TOOLS` | No | `core` (default) advertises a focused everyday tool set; `full` advertises every tool. See [Tool surface](#tool-surface) |
+| `OPENEPHEMERIS_TELEMETRY` | No | Set to `0`/`false`/`off` to disable anonymous usage reporting. `DO_NOT_TRACK=1` also works. See [Telemetry](#telemetry) |
 | `OPENEPHEMERIS_SERVICE_KEY` | No | Internal service auth |
 | `OPENEPHEMERIS_JWT` | No | Bearer token auth |
 | `OPENEPHEMERIS_DEV_ALLOWLIST_PATH` | No | Override allowlist file path |
@@ -288,6 +324,42 @@ The server is hosted at `https://mcp.openephemeris.com/mcp` with full Streamable
 
 Legacy aliases (`ASTROMCP_*`, `MERIDIAN_*`) remain supported.
 
+## Telemetry
+
+This server reports anonymous usage so we know which tools are worth maintaining and which are broken. Three events: session start, tool call, tool error.
+
+**What is sent:** the tool name, how long it took, error status, which MCP client connected (e.g. Claude Desktop, Cursor) and its version, the server version, and a one-way SHA-256 prefix of your API key used as a stable anonymous id.
+
+**What is never sent:** your API key or token, birth data, dates, names, coordinates, tool arguments, or tool results. No request or response bodies, ever.
+
+**To turn it off** — either works, checked before anything is sent:
+
+```bash
+OPENEPHEMERIS_TELEMETRY=0
+# or the cross-tool standard
+DO_NOT_TRACK=1
+```
+
+## Tool surface
+
+By default the server advertises a **focused core set** of everyday tools rather than the entire catalog. Large tool lists cost context and make model tool-selection worse, so the default is tuned for real conversations: one interactive app per tradition, the primary data tool per domain, geocoding, and the allowlist-gated generic proxy.
+
+**Nothing is removed.** The surface is a filter on `tools/list` only — every tool stays registered and stays callable by name. If you know the tool you want, call it and it works, listed or not.
+
+To advertise the full catalog:
+
+```bash
+OPENEPHEMERIS_TOOLS=full npx -y @openephemeris/mcp-server
+```
+
+On the remote HTTP server, append `?profile=full` to the connector URL (or send `X-OE-Tool-Surface: full`):
+
+```
+https://mcp.openephemeris.com/mcp?profile=full
+```
+
+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
 
 - **Something wrong with a result?** [Open an issue](https://github.com/openephemeris/openephemeris-MCP/issues/new/choose) — include the tool, your inputs, and what you expected.
@@ -370,8 +442,8 @@ Generated by `npm run sync:readme` from `config/dev-allowlist.json` and the live
 
 - Allowlisted operations: **28**
 - Methods: `GET=4`, `POST=24`, `PUT=0`, `PATCH=0`, `DELETE=0`
-- Registered tools (`OPENEPHEMERIS_PROFILE=dev`): **90**
-- Typed tools: `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_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`
+- Registered tools (`OPENEPHEMERIS_PROFILE=dev`): **91**
+- 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_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: 
 
 ### Allowlist Families

package/dist/analytics.js

@@ -1,23 +1,55 @@
 /**
- * analytics.ts — fire-and-forget PostHog events for the remote MCP server.
+ * analytics.ts — fire-and-forget PostHog events for both MCP transports.
  *
  * The launch was previously unmeasurable from the MCP side: no way to see how
  * many sessions initialized, which tools drove usage, or how many users hit
  * the 402 paywall. These events close that gap. Everything is best-effort:
  * analytics must never slow down or fail a tool call.
  *
- * Configuration (Fly secrets / env):
- *   POSTHOG_API_KEY  — the project API key (phc_...); absent → all no-ops.
+ * Configuration:
+ *   POSTHOG_API_KEY  — project API key (phc_...). On the Fly-hosted remote
+ *                      server this comes from a secret. On stdio (the npm
+ *                      package running on a user's machine) there is no env to
+ *                      set, so DEFAULT_INGEST_KEY below is compiled in.
  *   POSTHOG_HOST     — capture host, default https://us.i.posthog.com.
  *
+ * OPT-OUT — respected on every transport, checked before anything is sent:
+ *   OPENEPHEMERIS_TELEMETRY=0|false|off|no
+ *   DO_NOT_TRACK=1                      (de-facto cross-tool standard)
+ * Disclosed in README.md under "Telemetry".
+ *
  * Identity: we never send raw API keys or JWTs. The distinct_id is a SHA-256
  * prefix of the credential, stable per user across sessions but useless for
- * authentication.
+ * authentication. No birth data, coordinates, names, or tool arguments are
+ * ever sent — only the tool NAME, duration, error status, and client name.
  */
 import { createHash } from "node:crypto";
 const POSTHOG_HOST = process.env.POSTHOG_HOST || "https://us.i.posthog.com";
+/**
+ * Public, write-only PostHog project ingestion key.
+ *
+ * This is the same key class that ships in the openephemeris.com browser
+ * bundle (NEXT_PUBLIC_POSTHOG_KEY) — it can only append events, cannot read
+ * anything back, and is public by design. It is compiled in so the stdio
+ * package (which has no env to configure) is measurable at all; without it
+ * the entire npm install base is invisible.
+ */
+const DEFAULT_INGEST_KEY = "phc_tDomsYBMTZyFOb2DYKpWprUr4ATJ4v0QQh3fYqDdh9P";
+/** True when the user has opted out of telemetry by either supported signal. */
+function telemetryDisabled() {
+    const flag = (process.env.OPENEPHEMERIS_TELEMETRY ?? "").trim().toLowerCase();
+    if (flag === "0" || flag === "false" || flag === "off" || flag === "no")
+        return true;
+    const dnt = (process.env.DO_NOT_TRACK ?? "").trim();
+    return dnt === "1" || dnt.toLowerCase() === "true";
+}
 function apiKey() {
-    return process.env.POSTHOG_API_KEY || undefined;
+    if (telemetryDisabled())
+        return undefined;
+    const configured = process.env.POSTHOG_API_KEY;
+    if (configured)
+        return configured;
+    return DEFAULT_INGEST_KEY.startsWith("phc_") ? DEFAULT_INGEST_KEY : undefined;
 }
 /** Stable, non-reversible identity from a credential. */
 export function distinctIdFor(credential) {

package/dist/backend/client.d.ts

@@ -21,6 +21,10 @@ export interface BinaryBackendResponse {
     encoding: "base64";
     data_base64: string;
 }
+export declare const DASHBOARD_ACCOUNT_URL = "https://openephemeris.com/dashboard?tab=account";
+export declare const LOGIN_SIGNUP_URL = "https://openephemeris.com/login?signup=true&redirect=%2Fdashboard%3Ftab%3Daccount";
+export declare const UPGRADE_URL = "https://openephemeris.com/pricing";
+export declare const WALLET_TOPUP_URL = "https://openephemeris.com/wallet";
 export declare class BackendError extends Error {
     readonly status: number;
     readonly code: string;
@@ -59,6 +63,9 @@ export declare class BackendClient {
      * Idempotent — only starts once per client lifetime.
      */
     private autoStartDeviceAuth;
+    /** The actual device-auth start + background poll. Kicked off by (and stored
+     * on) autoStartDeviceAuth so the guard is race-safe. */
+    private _runDeviceAuth;
     private expectsBinaryResponse;
     private toBuffer;
     private decodePayload;

package/dist/backend/client.js

@@ -19,9 +19,10 @@ const BINARY_ENDPOINT_PREFIXES = [
     "/comparative/visualization/bi-wheel",
     "/comparative/visualization/chart-wheel",
 ];
-const DASHBOARD_ACCOUNT_URL = "https://openephemeris.com/dashboard?tab=account";
-const LOGIN_SIGNUP_URL = "https://openephemeris.com/login?signup=true&redirect=%2Fdashboard%3Ftab%3Daccount";
-const UPGRADE_URL = "https://openephemeris.com/pricing";
+export const DASHBOARD_ACCOUNT_URL = "https://openephemeris.com/dashboard?tab=account";
+export const LOGIN_SIGNUP_URL = "https://openephemeris.com/login?signup=true&redirect=%2Fdashboard%3Ftab%3Daccount";
+export const UPGRADE_URL = "https://openephemeris.com/pricing";
+export const WALLET_TOPUP_URL = "https://openephemeris.com/wallet";
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -143,40 +144,38 @@ export class BackendClient {
     async autoStartDeviceAuth() {
         if (this._pendingAuthFlow)
             return; // Already started
-        try {
-            const flow = new DeviceAuthFlow();
-            const startResult = await flow.start();
-            this._authFlowResult = {
-                verification_uri: startResult.verification_uri,
-                user_code: startResult.user_code,
-                verification_uri_complete: startResult.verification_uri_complete,
-            };
-            // Print to stderr so it's visible in MCP host logs
-            console.error(`\n🔗 OpenEphemeris: Account connection required.\n` +
-                `   Visit: ${startResult.verification_uri}\n` +
-                `   Code:  ${startResult.user_code}\n` +
-                `   Or:    ${startResult.verification_uri_complete}\n`);
-            // Poll in background (don't await)
-            this._pendingAuthFlow = flow
-                .poll(startResult.device_code, (attempt) => {
-                if (attempt % 12 === 0) {
-                    console.error(`   Still waiting... Enter code ${startResult.user_code} at ${startResult.verification_uri}`);
-                }
-            })
-                .then(() => {
-                console.error(`✅ Authenticated! Subsequent requests will use your account.`);
-                this._authFlowResult = null;
-            })
-                .catch((err) => {
-                console.error(`❌ Device auth failed: ${err.message}`);
-                this._pendingAuthFlow = null; // Allow retry
-            });
-        }
-        catch (err) {
-            console.error(`Could not start device auth: ${err.message}`);
-            // Don't block — the request will go out unauthenticated and
-            // the 401 response will surface the error message to the user.
-        }
+        // Assign the in-flight promise SYNCHRONOUSLY — before the first await inside
+        // _runDeviceAuth — so concurrent callers in the same tick observe a non-null
+        // _pendingAuthFlow and bail instead of each launching a duplicate device-auth
+        // flow (which would print two codes and open two poll loops). On any failure
+        // we reset to null so a later request can retry.
+        this._pendingAuthFlow = this._runDeviceAuth().catch((err) => {
+            console.error(`❌ Device auth failed: ${err?.message ?? err}`);
+            this._pendingAuthFlow = null; // Allow retry
+        });
+    }
+    /** The actual device-auth start + background poll. Kicked off by (and stored
+     * on) autoStartDeviceAuth so the guard is race-safe. */
+    async _runDeviceAuth() {
+        const flow = new DeviceAuthFlow();
+        const startResult = await flow.start();
+        this._authFlowResult = {
+            verification_uri: startResult.verification_uri,
+            user_code: startResult.user_code,
+            verification_uri_complete: startResult.verification_uri_complete,
+        };
+        // Print to stderr so it's visible in MCP host logs
+        console.error(`\n🔗 OpenEphemeris: Account connection required.\n` +
+            `   Visit: ${startResult.verification_uri}\n` +
+            `   Code:  ${startResult.user_code}\n` +
+            `   Or:    ${startResult.verification_uri_complete}\n`);
+        await flow.poll(startResult.device_code, (attempt) => {
+            if (attempt % 12 === 0) {
+                console.error(`   Still waiting... Enter code ${startResult.user_code} at ${startResult.verification_uri}`);
+            }
+        });
+        console.error(`✅ Authenticated! Subsequent requests will use your account.`);
+        this._authFlowResult = null;
     }
     expectsBinaryResponse(path, options) {
         const normalizedPath = path.split("?")[0].trim().toLowerCase();
@@ -361,7 +360,9 @@ export class BackendClient {
         const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
         const expectsBinary = this.expectsBinaryResponse(path, options);
         let lastError = new Error("Unknown error");
-        // Attempt + retries on transient failures (429, 502, 503, 504, network errors)
+        // Attempt + retries on transient failures. Retryable set is deliberately
+        // GET-only over {502, 503, 504} + transient transport codes — NOT 429 (see
+        // the RETRYABLE_STATUSES NOTE above: retrying a metered POST double-charges).
         for (let attempt = 0; attempt <= RETRY_DELAYS_MS.length; attempt++) {
             try {
                 const response = await this.client.request({

package/dist/index.js

@@ -5,7 +5,8 @@ import { fileURLToPath } from "node:url";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-import { initTools, toolRegistry, formatToolResponse, formatToolError, modelVisibleTools } from "./tools/index.js";
+import { initTools, toolRegistry, formatToolResponse, formatToolError, modelVisibleTools, parseToolSurface, SERVER_VERSION } from "./tools/index.js";
+import { captureEvent, distinctIdFor } from "./analytics.js";
 import { listPrompts, getPromptContent } from "./prompts.js";
 // ── MCP App resource imports ────────────────────────────────────────────────
 import { CHART_WHEEL_RESOURCE_URI, CHART_WHEEL_MIME_TYPE, getChartWheelBundle, } from "./tools/apps/chart-wheel-app.js";
@@ -62,10 +63,44 @@ const server = new Server({
         },
     },
 });
+// Which slice of the registry this process advertises. Tools outside the core
+// surface stay callable by name — this only controls what tools/list returns.
+// Set OPENEPHEMERIS_TOOLS=full to advertise everything.
+const STDIO_SURFACE = parseToolSurface(process.env.OPENEPHEMERIS_TOOLS);
+/**
+ * Stable pseudonymous id for this install. Derived from the configured
+ * credential exactly like the remote server, so one user shows up as the same
+ * person whether they connect over stdio or HTTP. Falls back to "anonymous"
+ * when no credential is configured yet.
+ */
+function analyticsId() {
+    return distinctIdFor(process.env.OPENEPHEMERIS_API_KEY ||
+        process.env.ASTROMCP_API_KEY ||
+        process.env.OPENEPHEMERIS_JWT ||
+        undefined);
+}
+/**
+ * Properties attached to every stdio event.
+ *
+ * `client_name` is the host that connected (Claude Desktop, Cursor, Windsurf,
+ * …) from the MCP initialize handshake — this is the only way to know which
+ * hosts the npm install base actually runs in, and therefore which of them
+ * ever exercise the iframe apps.
+ */
+function transportProps() {
+    const info = server.getClientVersion();
+    return {
+        transport: "stdio",
+        surface: STDIO_SURFACE,
+        client_name: info?.name ?? "unknown",
+        client_version: info?.version ?? "unknown",
+        server_version: SERVER_VERSION,
+    };
+}
 // List available tools
 server.setRequestHandler(ListToolsRequestSchema, async () => {
     return {
-        tools: modelVisibleTools().map((tool) => ({
+        tools: modelVisibleTools("stdio", STDIO_SURFACE).map((tool) => ({
             name: tool.name,
             description: tool.description,
             inputSchema: tool.inputSchema,
@@ -231,12 +266,25 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     try {
         const result = await tool.handler(request.params.arguments ?? {});
         const durationMs = Date.now() - startTime;
+        captureEvent("mcp_tool_call", analyticsId(), {
+            tool: toolName,
+            duration_ms: durationMs,
+            ...transportProps(),
+        });
         return formatToolResponse(toolName, result, durationMs);
     }
     catch (error) {
         const durationMs = Date.now() - startTime;
         const errorMessage = error instanceof Error ? error.message : String(error);
         console.error(`[MCP] ❌ Failed: ${toolName} (${durationMs}ms) - ${errorMessage}`);
+        const err = error;
+        captureEvent("mcp_tool_error", analyticsId(), {
+            tool: toolName,
+            status: err?.status ?? "unknown",
+            error_kind: err?.status != null ? "backend" : "local",
+            code: err?.code ?? "none",
+            ...transportProps(),
+        });
         // isError: true for every failure so the host recovers, EXCEPT the stdio
         // device-auth-pending case (model must relay the verification link).
         return formatToolError(error);
@@ -246,6 +294,20 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 async function main() {
     await initTools();
     const transport = new StdioServerTransport();
+    // oninitialized fires after the handshake, so getClientVersion() is
+    // populated — this is the one place we learn which host we are running in.
+    server.oninitialized = () => {
+        const info = server.getClientVersion();
+        console.error(`[MCP] Connected to ${info?.name ?? "unknown host"} ${info?.version ?? ""}`.trim());
+        captureEvent("mcp_session_init", analyticsId(), {
+            auth: process.env.OPENEPHEMERIS_API_KEY || process.env.ASTROMCP_API_KEY
+                ? "api_key"
+                : process.env.OPENEPHEMERIS_JWT
+                    ? "jwt"
+                    : "none",
+            ...transportProps(),
+        });
+    };
     await server.connect(transport);
     console.error("Open Ephemeris MCP server running on stdio");
 }