@openephemeris/mcp-server 4.7.0 → 4.8.1

package/CHANGELOG.md

@@ -7,6 +7,49 @@ Version numbering follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [4.8.1] — 2026-08-02
+
+### Fixed
+- Every tool now declares all four MCP annotation hints explicitly
+  (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`).
+  Notably `dev_write_api` is `destructiveHint: false` — every allowlisted
+  write is stateless chart computation — so strict clients no longer gate it
+  behind a confirmation, and `openWorldHint` is uniformly `false` (the server
+  reaches only the fixed OpenEphemeris API).
+- `account_usage` reports a real authentication failure as a tool error
+  (`isError: true`) instead of a success-shaped message.
+
+## [4.8.0] — 2026-08-02
+
+### Added
+- **Toolsets by tradition.** Tool definitions are re-sent to the model on every
+  message, so callers who work in one tradition can now advertise just that
+  tradition instead of the general-purpose default: `OPENEPHEMERIS_TOOLS=hd`
+  (stdio) or `?profile=hd,bazi` (hosted). Eight toolsets — `astrology`, `moon`,
+  `hd`, `bazi`, `vedic`, `acg`, `electional`, `venus` — each including
+  geocoding, account usage, and the API escape hatch. A Human Design session
+  drops from ~19,100 to ~7,800 advertised tokens (−59%); Vedic to ~3,400
+  (−82%). `astrology,moon` matches the default's tool count at ~1,700 fewer
+  tokens while covering the long tail (dignities, midpoints, hermetic lots,
+  fixed stars, composites) the curated set omits. As with `core`/`full`, this
+  filters `tools/list` only — every tool stays callable by name. Also exposed
+  as the `toolSurface` option in the Smithery config.
+
+### Fixed
+- `explore_human_design` now states its real credit cost: 4 where the bodygraph
+  renders (2 chart + 2 visual), 2 in text-only hosts — it previously claimed a
+  flat 2. `ephemeris_moon_phase` (2, not 1) and `ephemeris_next_lunar_phase`
+  (1–2 per occurrence) corrected the same way.
+- `explore_bi_wheel` in synastry mode now requires Person 2's coordinates (or a
+  resolvable `person2_location`) instead of silently casting Person 2's chart
+  for 0°N 0°E.
+- Chart-wheel widget escapes birth parameters before rendering them into the
+  info chips.
+- OAuth token endpoint binds authorization codes to their `redirect_uri` and
+  `client_id`; both checks were previously skippable by omitting the parameter.
+
+---
+
 ## [4.7.0] — 2026-08-02
 
 Historically correct birth-time conversion. IANA timezone databases — including

package/README.md

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

package/dist/index.js

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

package/dist/oauth/token.js

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

package/dist/server-sse.js

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

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

@@ -115,9 +115,9 @@ registerTool({
         "(Year = ancestry/early life, Month = parents/career, Day = self/spouse, Hour = children/later life).\n\n" +
         "CREDIT COST: 3 credits per call (1 base + 2 visual render).\n\n" +
         "Use this for a rich, interactive BaZi experience in MCP Apps-capable hosts (Claude Desktop). " +
-        "Falls back to a text summary in other hosts. For non-visual data lookups, use chinese_bazi " +
-        "instead; deeper derivations (Ten Gods, element balance, luck pillars) have dedicated tools " +
-        "on the full tool surface (`?profile=full`).",
+        "Falls back to a text summary in other hosts, so it is also the right call without a " +
+        "renderer. Deeper derivations (Ten Gods, element balance, luck pillars) and a plain " +
+        "non-visual pillars lookup have dedicated tools on the full surface (`?profile=full`).",
     inputSchema: {
         type: "object",
         properties: {
@@ -204,7 +204,7 @@ registerTool({
         required: ["year", "month", "day"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Recalculate BaZi Chart", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Recalculate BaZi Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BAZI_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const components = parseBaziArgs(args);

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

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

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

@@ -306,7 +306,10 @@ function buildHdSummary(payload, location) {
 registerTool({
     name: "explore_human_design",
     description: "Generate an interactive Human Design Bodygraph with clickable centers, gates, and channels.\n\n" +
-        "CREDIT COST: 2 credits per call.\n\n" +
+        "CREDIT COST: 4 credits where the bodygraph renders (2 for the chart + 2 for the " +
+        "visual), 2 in text-only hosts that skip the render. For chart data alone at 2 " +
+        "credits — including the activations, design, personality, strategy and variables " +
+        "this tool does not return — use human_design_chart.\n\n" +
         "Returns an embedded visual bodygraph explorer that lets you click any center or gate " +
         "for instant Human Design interpretation. " +
         "Shows defined/undefined centers, active gates, channels, Type, Profile, Authority, " +
@@ -468,7 +471,7 @@ registerTool({
         required: ["datetime"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Recalculate Bodygraph", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Recalculate Bodygraph", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BODYGRAPH_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const client = getActiveClient();
@@ -533,7 +536,7 @@ registerTool({
         required: ["center", "defined"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Center Interpretation", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Center Interpretation", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BODYGRAPH_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const center = String(args.center);
@@ -591,7 +594,7 @@ registerTool({
         required: ["gate"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Gate Interpretation", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Gate Interpretation", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BODYGRAPH_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const gate = Number(args.gate);
@@ -646,7 +649,7 @@ registerTool({
         required: ["channel"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Channel Interpretation", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Channel Interpretation", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BODYGRAPH_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const channelStr = String(args.channel);
@@ -748,7 +751,7 @@ registerTool({
         required: ["channel"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Connection Channel Interpretation", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Connection Channel Interpretation", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BODYGRAPH_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const channelStr = String(args.channel ?? "");
@@ -804,7 +807,7 @@ registerTool({
         required: ["channel"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Transit Channel Interpretation", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Transit Channel Interpretation", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BODYGRAPH_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const channelStr = String(args.channel ?? "");
@@ -1132,7 +1135,7 @@ registerTool({
         required: ["planet", "column"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Planet Sidebar Interpretation", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Planet Sidebar Interpretation", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BODYGRAPH_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const planet = String(args.planet);
@@ -1201,7 +1204,7 @@ registerTool({
         required: ["variable", "direction"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Variable Arrow Interpretation", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Variable Arrow Interpretation", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: BODYGRAPH_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const variable = String(args.variable).toLowerCase();

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

@@ -259,7 +259,7 @@ registerTool({
         required: ["planet", "longitude"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Planet Interpretation", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Planet Interpretation", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: CHART_WHEEL_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const planet = String(args.planet);
@@ -294,7 +294,7 @@ registerTool({
         required: ["house_number"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "House Interpretation", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "House Interpretation", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: CHART_WHEEL_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const num = Number(args.house_number);
@@ -330,7 +330,7 @@ registerTool({
         required: ["planet1", "planet2"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Aspect Interpretation", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Aspect Interpretation", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: CHART_WHEEL_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const p1 = capitalize(String(args.planet1));
@@ -379,7 +379,7 @@ registerTool({
         required: ["datetime", "latitude", "longitude", "house_system"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Recalculate Chart", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Recalculate Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: CHART_WHEEL_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const client = getActiveClient();

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

@@ -131,7 +131,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Location Search", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Location Search", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     // Model-visible as well as app-visible: without this the model had no
     // geocoding tool and every prompt had to route through
     // `dev_read_api /location/autocomplete` instead.
@@ -235,7 +235,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Timezone Resolve", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    annotations: { title: "Timezone Resolve", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: {
         ui: {
             visibility: ["model", "app"],

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

@@ -295,7 +295,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Recalculate Moon Phase", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Recalculate Moon Phase", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: MOON_PHASE_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const { summary, uiPayload } = await computeMoonData(args);

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

@@ -240,7 +240,7 @@ registerTool({
         required: ["datetime"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "Recalculate Vedic Chart", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "Recalculate Vedic Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     _meta: { ui: { resourceUri: VEDIC_CHART_RESOURCE_URI, visibility: ["app"] } },
     handler: async (args) => {
         const client = getActiveClient();

package/dist/tools/auth.js

@@ -24,6 +24,10 @@ registerTool({
         title: "Connect Account",
         readOnlyHint: false,
         destructiveHint: false,
+        // Each call starts a fresh device-auth flow with a new code — repeating
+        // it is harmless but not a no-op.
+        idempotentHint: false,
+        openWorldHint: false,
     },
     stdioOnly: true,
     handler: async () => {
@@ -105,6 +109,8 @@ registerTool({
         title: "Auth Status",
         readOnlyHint: true,
         destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
     },
     stdioOnly: true,
     handler: async () => {
@@ -191,6 +197,8 @@ registerTool({
         title: "Disconnect Account",
         readOnlyHint: false,
         destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
     },
     stdioOnly: true,
     handler: async () => {

package/dist/tools/dev.js

@@ -196,8 +196,10 @@ registerTool({
         DEV_API_REFERENCE,
     inputSchema: makeProxyInputSchema(READ_METHODS),
     outputSchema: OUTPUT_SCHEMA_JSON,
-    // GET-only: never mutates server state.
-    annotations: { title: "API Read", readOnlyHint: true, openWorldHint: true },
+    // GET-only: never mutates server state. openWorldHint false — the proxy
+    // reaches only the fixed, allowlisted OpenEphemeris API (a closed world),
+    // same as every typed tool.
+    annotations: { title: "API Read", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: makeProxyHandler(READ_METHODS, "GET"),
 });
 registerTool({
@@ -209,8 +211,16 @@ registerTool({
         DEV_API_REFERENCE,
     inputSchema: makeProxyInputSchema(WRITE_METHODS),
     outputSchema: OUTPUT_SCHEMA_JSON,
-    // Issues POST/PUT/PATCH/DELETE — must not be advertised as read-only.
-    annotations: { title: "API Write", readOnlyHint: false, openWorldHint: true },
+    // Issues POST/PUT/PATCH/DELETE — must not be advertised as read-only. But
+    // destructiveHint is explicitly FALSE: every allowlisted write operation is
+    // stateless chart computation (natal, synastry, ACG, returns…) that debits
+    // credits and returns a result — nothing on the allowlist mutates or deletes
+    // user data, and the deny rules block /auth, /billing, /account, /api-keys.
+    // Left unset, strict clients default destructiveHint to true and gate every
+    // call behind a confirmation. idempotentHint true for the same reason: the
+    // same body yields the same chart. openWorldHint false — fixed allowlisted
+    // API only, a closed world.
+    annotations: { title: "API Write", readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: makeProxyHandler(WRITE_METHODS, "POST"),
 });
 registerTool({
@@ -226,7 +236,7 @@ registerTool({
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
-    annotations: { title: "List Allowed API Operations", readOnlyHint: true, openWorldHint: false },
+    annotations: { title: "List Allowed API Operations", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async () => {
         const allowlist = loadAllowlist();
         return {