@openephemeris/mcp-server 3.23.1 → 4.0.0

package/CHANGELOG.md

@@ -7,6 +7,111 @@ Version numbering follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [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.
+
+### Added
+- **Mandala layout toggle** in the Human Design Bodygraph Explorer — a power-user view alongside the default graph layout, reusing the existing theme-recalculate round-trip. The render cache now keys on layout × theme × houses, so toggling any axis back and forth never re-bills within a session. Requests an explicit hexagram-free ring set (the decorative hexagram ring cells no longer carry `data-gate` at all, fixing a hover mislabel and roughly halving the keyboard tab-stop count).
+- **House rings — a distinct, explicitly metered opt-in** — a location-gated "Add house rings (+1 credit)" checkbox, off by default even when the mandala is on, disabled without a birth location or outside the mandala layout.
+
 ## [3.23.0] — 2026-07-19
 
 Coverage build-out (4 → 7 live iframe apps), tool-data bug fixes from live probing, and Human Design trademark hygiene. Registered tool count: 84 → 90.

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

@@ -3,8 +3,10 @@
 [![smithery badge](https://smithery.ai/badge/open-ephemeris/openephemeris)](https://smithery.ai/servers/open-ephemeris/openephemeris)
 [![npm version](https://img.shields.io/npm/v/@openephemeris/mcp-server)](https://www.npmjs.com/package/@openephemeris/mcp-server)
 [![System Status](https://img.shields.io/badge/Status-Operational-brightgreen)](https://status.openephemeris.com/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue)](LICENSE)
+[![Ephemeris: JPL DE440](https://img.shields.io/badge/Ephemeris-JPL%20DE440-6f42c1)](https://ssd.jpl.nasa.gov/planets/eph_export.html)
 
-![OpenEphemeris in Claude — ask in plain language, get a real computed chart](https://raw.githubusercontent.com/openephemeris/openephemeris/main/docs/internal/PH-ASSETS/hero-demo.gif)
+![OpenEphemeris in Claude — ask in plain language, get a real computed chart](https://raw.githubusercontent.com/openephemeris/openephemeris-MCP/main/assets/hero-demo.gif)
 
 Model Context Protocol server for OpenEphemeris — typed astrology tools powered by the NASA JPL DE440 ephemeris. Zero hallucination on planetary positions, dates, and degrees. Covers 1,100 years of astronomical data.
 
@@ -279,6 +281,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 |
@@ -286,6 +290,51 @@ 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.
+- **Want to contribute?** See [CONTRIBUTING.md](CONTRIBUTING.md). Integration examples and new skills are the most useful things you can add.
+- **Found a security problem?** Please report it privately — see [SECURITY.md](SECURITY.md).
+- **Tools timing out?** Check [status.openephemeris.com](https://status.openephemeris.com) first.
+
+If this saved you from an LLM confidently inventing a Saturn position, a ⭐ helps other people find it.
+
 ## Legal
 
 This package is licensed under the [MIT License](./LICENSE). However, use of this package to access the OpenEphemeris API constitutes use of the Service and is governed by the [OpenEphemeris Terms of Service](https://openephemeris.com/terms). By using this package, you agree to those terms. See also the [Privacy Policy](https://openephemeris.com/privacy) and [Acceptable Use Policy](https://openephemeris.com/acceptable-use).
@@ -359,8 +408,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");
 }

package/dist/oauth/session-utils.d.ts

@@ -1,21 +1,3 @@
-/**
- * src/oauth/session-utils.ts — Pure helpers for session reliability.
- *
- * Two concerns live here so they can be unit-tested without spinning up the
- * full SSE server:
- *
- *   1. JWT expiry decoding — read the `exp` claim WITHOUT signature
- *      verification. The signature is validated downstream by the Go API's
- *      ValidateSupabaseJWT; here we only need to know whether a token is
- *      already expired so the /mcp gate can trigger the host's OAuth refresh
- *      (401 invalid_token) instead of letting it die as a confusing tool error.
- *
- *   2. Machine-scoped session IDs — Fly runs min_machines_running >= 2, but the
- *      HTTP/SSE session store is a per-process Map. A resume request can land on
- *      a different machine and 404. We embed the FLY_MACHINE_ID into generated
- *      session IDs so an incoming request can be re-routed to the owning machine
- *      via the `fly-replay` header. Local/dev (no FLY_MACHINE_ID) is a no-op.
- */
 /**
  * Decode a JWT's payload without verifying the signature and return its `exp`
  * claim (seconds since epoch), or null if the token is malformed / has no exp.
@@ -57,3 +39,45 @@ export declare function replayTargetMachine(sessionId: string, opts: {
     selfMachineId?: string;
     alreadyReplayed: boolean;
 }): string | null;
+/**
+ * Decode a JWT's `sub` (subject) claim without verifying the signature.
+ * The subject is the stable Supabase user id — it survives token refresh,
+ * whereas the raw JWT string rotates roughly hourly. Returns null when the
+ * token is malformed or carries no usable string `sub`.
+ */
+export declare function decodeJwtSub(token: string): string | null;
+/**
+ * Compute the STABLE binding token for a presented credential — the value a
+ * session is bound to at init and re-checked on every resume:
+ *
+ *   - API key → the raw key. A given key is re-presented verbatim on every
+ *     request, so binding to it is exact.
+ *   - JWT     → the `sub` claim (Supabase user id), NOT the raw token. claude.ai
+ *     rotates the Bearer JWT ~hourly via /oauth/token; binding to the raw token
+ *     would 403 every legitimate refresh. The subject is constant across
+ *     refreshes for the same user, so binding survives rotation while still
+ *     rejecting a different user's token.
+ *   - JWT with no decodable `sub` → fall back to the raw token (best effort;
+ *     Supabase access tokens always carry `sub`, so this is a degenerate case).
+ *
+ * Returns null when neither credential is present.
+ */
+export declare function credentialBindingToken(auth: {
+    apiKey?: string;
+    jwt?: string;
+}): string | null;
+/** SHA-256 hex digest of a binding token — what we store on the session record. */
+export declare function hashBindingToken(token: string): string;
+/**
+ * Compute the stored/compared binding hash for a request's auth, or null when
+ * the request carries no credential.
+ */
+export declare function credentialBindingHash(auth: {
+    apiKey?: string;
+    jwt?: string;
+}): string | null;
+/**
+ * Constant-time comparison of two binding hashes. Both are fixed-length hex
+ * digests; a length mismatch (or a null presented hash) is a non-match.
+ */
+export declare function bindingHashMatches(stored: string, presented: string | null): boolean;