@openephemeris/mcp-server 4.11.2 → 4.13.0

package/CHANGELOG.md

@@ -7,6 +7,102 @@ Version numbering follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [4.13.0] — 2026-08-27
+
+### Added
+- **Sidereal charts on `ephemeris_natal_chart`.** New `zodiac_type`
+  (`tropical` | `sidereal`) and `ayanamsa` (Lahiri, Fagan-Bradley,
+  Krishnamurti, Raman, Yukteshwar). Sidereal subtracts the ayanamsa from every
+  longitude, so signs, dignities and element balance all move by roughly a
+  whole sign; aspects and house numbers do not change, because a uniform
+  offset preserves angular separation and which side of a cusp a body falls
+  on. The response names the zodiac and the ayanamsa that produced it. Naming
+  an ayanamsa without asking for sidereal is now an error rather than a
+  quietly tropical chart.
+
+  The API had accepted `zodiac_type` for as long as the natal contract has
+  existed and read it nowhere, so a request for a sidereal chart came back
+  tropical — not imprecise, a different chart — with nothing in the payload
+  saying which zodiac you had been given. That is fixed on the server, which
+  is the only reason the parameter is exposed here.
+
+- **Whole-chart analytics on `ephemeris_natal_chart`.** `analytics` accepts any
+  of `element_balance`, `hemisphere_emphasis`, `aspect_patterns` and
+  `harmonics`. No extra credits. The endpoint has always computed these on
+  request and this server never asked for them, so they were unreachable from
+  MCP no matter what a caller wanted.
+
+- **`include_minor_aspects` on `ephemeris_natal_chart`.** Adds quincunx,
+  semisextile, semisquare, sesquiquadrate, quintile and biquintile to the
+  aspect grid. Minors use their own orbs, so this widens the grid without
+  changing any major aspect.
+
+- **`latitude` / `longitude` on `electional_moment_analysis`.** Both optional —
+  the tool is documented as taking no arguments at all and still does — but
+  without them sect falls back to diurnal, so a night moment is scored with
+  the day triplicity rulers. Pass both whenever the place is known.
+
+### Removed
+- **`include_fixed_stars` on `ephemeris_natal_chart`.** It never did anything.
+  The natal endpoint reads no fixed-star configuration on any of the keys this
+  flag was routed to, so the response was identical either way. Tool
+  definitions are re-sent on every model pass, which means a parameter that
+  does nothing is still paid for by every user on every request. Fixed stars
+  come from `ephemeris_fixed_stars`, which also reports which chart points sit
+  conjunct them. Unknown arguments are not rejected, so a caller still sending
+  the old flag is ignored exactly as it was before.
+
+- **The `alcabitius` and `morinus` house systems.** Advertised on three tools
+  and broken on all of them: the codes sent for them are accepted by no code
+  path, so every call naming one came back a validation error. The seven
+  systems that remain are the whole set the engine implements.
+
+### Fixed
+- **`dev_read_api` advertised fifteen POST endpoints it rejects.** It is
+  GET-only, and it shared one reference block with the write proxy, so most of
+  its description documented calls it cannot make. It is on the default tool
+  surface, so every client paid for that text on every model pass. Each proxy
+  now lists only the calls it accepts.
+
+- **The compact `llm` output could not express a minor aspect.** Its aspect
+  dictionary declared five entries while the engine can now emit eleven, so a
+  minor aspect had no valid code to travel under. All eleven are declared.
+
+### Changed
+- **Endpoint count corrected to 120** across the bundled skills, and the
+  plugin skill's fixed-star guidance now points at `ephemeris_fixed_stars`
+  rather than a flag that never worked.
+
+---
+
+## [4.12.0] — 2026-08-13
+
+### Fixed
+- **Server `instructions` told the model a tool needed no arguments when it
+  did.** The zero-data-entry-point line named `ephemeris_retrograde_status` as
+  needing no arguments; its schema has `required: ["datetime"]`. An agent
+  that took the line literally made a zero-argument call and got a validation
+  error as its first experience of the server. Now names
+  `explore_moon_phase` and `electional_moment_analysis` — both genuinely
+  zero-argument — and both are asserted against the real tool schemas in CI
+  so this cannot silently drift again.
+
+### Added
+- **Connector first-run activation telemetry.** `mcp_tools_listed` (both
+  transports, once per session) and `mcp_session_silent` (HTTP, on teardown
+  when tools were listed but never called) close the gap where "connected but
+  never used it" was only an absence of events — indistinguishable from a
+  session that died mid-handshake. Funnel: `mcp_session_init` →
+  `mcp_tools_listed` → `first_tool_call`.
+
+### Changed
+- **Server `instructions` deduplicated** into `src/instructions.ts`, shared by
+  both transports. They were previously copy-pasted verbatim into each
+  transport file, which is how the argument-count claim above drifted from
+  the schemas undetected.
+
+---
+
 ## [4.11.2] — 2026-08-13
 
 ### Fixed
@@ -347,6 +443,27 @@ the code.
   `options.include_hermetic_lots: true`); only the descriptions were
   stale.
 
+  > **Correction (2026-08-23).** Half of the entry above is wrong, and it is
+  > left standing rather than deleted so the record shows what was claimed.
+  >
+  > `include_arabic_parts` is accurate: the natal endpoint reads
+  > `include_hermetic_lots` at the top level, under `options`, and under
+  > `enhanced_options`, and has done so all along.
+  >
+  > `include_fixed_stars` was **not** wired and still is not. The natal
+  > endpoint reads no fixed-star configuration at any of the three keys —
+  > not `configuration.fixed_star_options`, not
+  > `enhanced_options.include_fixed_stars`, not
+  > `options.include_fixed_stars` — so setting the flag changes nothing in
+  > the response and never has. What made it look wired is that the
+  > identical `configuration.fixed_star_options` block genuinely does work
+  > on the chart-wheel and bi-wheel renderers, which share the request
+  > shape but not the code path.
+  >
+  > Until the natal endpoint honours it, `POST /ephemeris/fixed-stars` is
+  > the way to get fixed-star positions; it accepts the same star names,
+  > groups, and magnitude limits and returns conjunctions to the angles.
+
 ---
 
 ## [4.3.1] — 2026-07-29

package/README.md

@@ -10,6 +10,8 @@
 
 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.
 
+![The catalog: 90 bodies and 124 fixed stars — asteroids, trans-Neptunians, Uranian points, computed in one engine](https://raw.githubusercontent.com/openephemeris/openephemeris-MCP/main/assets/catalog-90-bodies.png)
+
 **Hosted endpoint:** `https://mcp.openephemeris.com/mcp` (Streamable HTTP, MCP 2025-11-25 spec)
 
 ## Quick Start

package/dist/analytics.d.ts

@@ -1,3 +1,13 @@
-/** Stable, non-reversible identity from a credential. */
+/** Stable identity from a credential — the Supabase user id for OAuth, else a hash of the API key. */
 export declare function distinctIdFor(credential: string | undefined): string;
+/**
+ * Fire `first_tool_call` the first time a given identity completes a tool
+ * call, so activation (site visit → connector install → first real use) is a
+ * queryable event instead of "earliest mcp_tool_call per person" math. Never
+ * fires for "anonymous" (no credential at all — nothing to attribute
+ * activation to). Best-effort dedup only: the set is per-process, so a
+ * session that lands on a different Fly machine can refire once — acceptable
+ * for an activation metric read in aggregate.
+ */
+export declare function captureFirstToolCallOnce(distinctId: string, properties?: Record<string, unknown>): void;
 export declare function captureEvent(event: string, distinctId: string, properties?: Record<string, unknown>): void;

package/dist/analytics.js

@@ -6,6 +6,21 @@
  * the 402 paywall. These events close that gap. Everything is best-effort:
  * analytics must never slow down or fail a tool call.
  *
+ * Events, in funnel order:
+ *   mcp_session_init    — handshake completed
+ *   mcp_tools_listed    — host fetched tools/list (once per session)
+ *   first_tool_call     — this identity's first-ever completed tool call
+ *   mcp_tool_call       — every completed call
+ *   mcp_tool_error      — every failed call
+ *   mcp_session_silent  — HTTP only: listed tools, never attempted one. See
+ *                         reportSilentSession() in server-sse.ts for its two
+ *                         reading caveats (late arrival, undercount).
+ *
+ * mcp_session_init → mcp_tools_listed → first_tool_call is the activation
+ * funnel. Before mcp_tools_listed existed, "connected but never used it" was
+ * only an absence of events and could not be told apart from a host that never
+ * listed, or a session that died mid-handshake.
+ *
  * Configuration:
  *   POSTHOG_API_KEY  — project API key (phc_...). On the Fly-hosted remote
  *                      server this comes from a secret. On stdio (the npm
@@ -18,12 +33,18 @@
  *   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. No birth data, coordinates, names, or tool arguments are
- * ever sent — only the tool NAME, duration, error status, and client name.
+ * Identity: we never send raw API keys. API-key sessions get a SHA-256
+ * prefix of the key, stable per user across sessions but useless for
+ * authentication. OAuth (Supabase JWT) sessions instead use the JWT's `sub`
+ * claim directly as the distinct_id — that's the same Supabase user id the
+ * web app passes to posthog.identify() at apps/web/contexts/AuthContext.tsx,
+ * so an MCP session and a browser session for the same account land on one
+ * PostHog person instead of two unmergeable ones. 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";
+import { decodeJwtSub } from "./oauth/session-utils.js";
 const POSTHOG_HOST = process.env.POSTHOG_HOST || "https://us.i.posthog.com";
 /**
  * Public, write-only PostHog project ingestion key.
@@ -51,13 +72,45 @@ function apiKey() {
         return configured;
     return DEFAULT_INGEST_KEY.startsWith("phc_") ? DEFAULT_INGEST_KEY : undefined;
 }
-/** Stable, non-reversible identity from a credential. */
+/** Stable identity from a credential — the Supabase user id for OAuth, else a hash of the API key. */
 export function distinctIdFor(credential) {
     if (!credential)
         return "anonymous";
+    if (credential.startsWith("eyJ")) {
+        const sub = decodeJwtSub(credential);
+        if (sub)
+            return sub;
+    }
     return "mcp_" + createHash("sha256").update(credential).digest("hex").slice(0, 24);
 }
+const identitiesWithFirstToolCall = new Set();
+/**
+ * Fire `first_tool_call` the first time a given identity completes a tool
+ * call, so activation (site visit → connector install → first real use) is a
+ * queryable event instead of "earliest mcp_tool_call per person" math. Never
+ * fires for "anonymous" (no credential at all — nothing to attribute
+ * activation to). Best-effort dedup only: the set is per-process, so a
+ * session that lands on a different Fly machine can refire once — acceptable
+ * for an activation metric read in aggregate.
+ */
+export function captureFirstToolCallOnce(distinctId, properties = {}) {
+    if (distinctId === "anonymous" || identitiesWithFirstToolCall.has(distinctId))
+        return;
+    identitiesWithFirstToolCall.add(distinctId);
+    captureEvent("first_tool_call", distinctId, properties);
+}
+// Our own e2e/harness/canary scripts declare an MCP clientInfo.name that ends
+// up in every event's `client_name` property (see transportProps() in
+// server-sse.ts / index.ts) — e.g. "e2e-http-client", "harness-fixture-capture".
+// Their runs were previously indistinguishable from real users in PostHog.
+const INTERNAL_CLIENT_PREFIXES = ["e2e-", "harness-", "test-", "canary-", "deploy-state-check", "local-agent-mode", "verify"];
+/** True if a captured `client_name` identifies one of our own test/harness/canary scripts. */
+function isInternalClientName(name) {
+    return typeof name === "string" && INTERNAL_CLIENT_PREFIXES.some((prefix) => name.startsWith(prefix));
+}
 export function captureEvent(event, distinctId, properties = {}) {
+    if (isInternalClientName(properties.client_name))
+        return;
     const key = apiKey();
     if (!key)
         return;

package/dist/index.js

@@ -6,8 +6,8 @@ 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, parseToolSurface, SERVER_VERSION } from "./tools/index.js";
-import { DATETIME_CONTRACT_INSTRUCTIONS } from "./tools/datetime.js";
-import { captureEvent, distinctIdFor } from "./analytics.js";
+import { SERVER_INSTRUCTIONS } from "./instructions.js";
+import { captureEvent, captureFirstToolCallOnce, 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";
@@ -63,15 +63,7 @@ const server = new Server({
             },
         },
     },
-    instructions: "Open Ephemeris computes real astronomy (JPL DE440, sub-arcsecond) — never guess " +
-        "or approximate positions yourself; always call a tool. " +
-        "For anything the user should SEE (natal chart, bi-wheel, bodygraph, moon phase), " +
-        "prefer the explore_* tools — they render interactive visuals inline. " +
-        "ephemeris_* tools return data; use format='llm' on them for compact output. " +
-        "If the user has no birth data handy, start with the sky right now — " +
-        "explore_moon_phase and ephemeris_retrograde_status need none. " +
-        "See the 'welcome_to_open_ephemeris' prompt for orientation.\n\n" +
-        DATETIME_CONTRACT_INSTRUCTIONS,
+    instructions: SERVER_INSTRUCTIONS,
 });
 // Which slice of the registry this process advertises. Tools outside the
 // surface stay callable by name — this only controls what tools/list returns.
@@ -110,34 +102,49 @@ function transportProps() {
         server_version: SERVER_VERSION,
     };
 }
+// One-shot latch for mcp_tools_listed. A stdio process serves exactly one
+// session for its whole lifetime, so process scope IS session scope here.
+//
+// There is deliberately no stdio equivalent of the HTTP transport's
+// `mcp_session_silent`: the only teardown signal is process exit, and
+// captureEvent is a fire-and-forget fetch that would not flush before the
+// process is gone. On stdio, "listed but never called" is a PostHog query
+// (mcp_tools_listed with no following first_tool_call), not an event.
+let toolsListedReported = false;
 // List available tools
 server.setRequestHandler(ListToolsRequestSchema, async () => {
-    return {
-        tools: modelVisibleTools("stdio", STDIO_SURFACE).map((tool) => ({
-            name: tool.name,
-            description: tool.description,
-            inputSchema: tool.inputSchema,
-            annotations: {
-                title: tool.annotations?.title ?? tool.name,
-                readOnlyHint: tool.annotations?.readOnlyHint ?? true,
-                destructiveHint: tool.annotations?.destructiveHint ?? false,
-                idempotentHint: tool.annotations?.idempotentHint ?? true,
-                openWorldHint: tool.annotations?.openWorldHint ?? false,
-            },
-            // Expose MCP Apps UI linkage so Claude Desktop can prefetch the resource
-            ...(tool._meta?.ui?.resourceUri
-                ? {
-                    _meta: {
-                        "ui/resourceUri": tool._meta.ui.resourceUri,
-                        ui: {
-                            resourceUri: tool._meta.ui.resourceUri,
-                            visibility: tool._meta.ui.visibility ?? ["model", "app"],
-                        },
+    const tools = modelVisibleTools("stdio", STDIO_SURFACE).map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        annotations: {
+            title: tool.annotations?.title ?? tool.name,
+            readOnlyHint: tool.annotations?.readOnlyHint ?? true,
+            destructiveHint: tool.annotations?.destructiveHint ?? false,
+            idempotentHint: tool.annotations?.idempotentHint ?? true,
+            openWorldHint: tool.annotations?.openWorldHint ?? false,
+        },
+        // Expose MCP Apps UI linkage so Claude Desktop can prefetch the resource
+        ...(tool._meta?.ui?.resourceUri
+            ? {
+                _meta: {
+                    "ui/resourceUri": tool._meta.ui.resourceUri,
+                    ui: {
+                        resourceUri: tool._meta.ui.resourceUri,
+                        visibility: tool._meta.ui.visibility ?? ["model", "app"],
                     },
-                }
-                : {}),
-        })),
-    };
+                },
+            }
+            : {}),
+    }));
+    if (!toolsListedReported) {
+        toolsListedReported = true;
+        captureEvent("mcp_tools_listed", analyticsId(), {
+            tool_count: tools.length,
+            ...transportProps(),
+        });
+    }
+    return { tools };
 });
 // List available prompts
 server.setRequestHandler(ListPromptsRequestSchema, async () => {
@@ -279,11 +286,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     try {
         const result = await tool.handler(request.params.arguments ?? {});
         const durationMs = Date.now() - startTime;
-        captureEvent("mcp_tool_call", analyticsId(), {
+        const id = analyticsId();
+        captureEvent("mcp_tool_call", id, {
             tool: toolName,
             duration_ms: durationMs,
             ...transportProps(),
         });
+        captureFirstToolCallOnce(id, { tool: toolName, ...transportProps() });
         return formatToolResponse(toolName, result, durationMs);
     }
     catch (error) {

package/dist/instructions.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Tools an agent can call with literally no arguments — the entry points for a
+ * user who has not offered birth data.
+ *
+ * Asserted against the real schemas in test/description-cross-references.test.ts:
+ * each name here must be registered, must be on the CORE surface (most hosts
+ * refuse to call a tool absent from tools/list), and must genuinely have no
+ * required fields. Naming a tool here that needs an argument puts the model's
+ * very first call on a path to a validation error, which is the exact failure
+ * this list exists to prevent.
+ *
+ * Order is deliberate: the visual one leads, because a rendered dial is a
+ * better first impression than a score.
+ */
+export declare const ZERO_ARG_ENTRY_TOOLS: readonly ["explore_moon_phase", "electional_moment_analysis"];
+export declare const SERVER_INSTRUCTIONS: string;

package/dist/instructions.js

@@ -0,0 +1,51 @@
+/**
+ * instructions.ts — the server `instructions` string, shared by both transports.
+ *
+ * This is the highest-leverage text in the product. It is the only guidance a
+ * host puts in front of the model before the user's first message, and the
+ * connector funnel is where we lose people: of the MCP connector identities
+ * seen in a 60-day window, ~1 in 8 ever invoked a tool at all.
+ *
+ * It previously lived inline and duplicated verbatim in src/index.ts and
+ * src/server-sse.ts. That duplication is how it came to advertise
+ * `ephemeris_retrograde_status` as needing no arguments when its schema has
+ * `required: ["datetime"]` — an agent that took the line literally made a
+ * zero-argument call and got a validation error as its first experience of the
+ * server. Defining the text once, next to the list it interpolates, lets a test
+ * check the claim against the real schemas (see description-cross-references).
+ *
+ * Kept OUT of the tool surface on purpose: `instructions` is sent once at
+ * initialize and is not counted by the tool-surface token budget (GATE 4, see
+ * test/tool-surface-budget.test.ts), which is at ~19.6k of its 20k ceiling.
+ * First-run routing guidance therefore belongs here rather than in a tool
+ * description that every model pass re-pays for.
+ */
+import { DATETIME_CONTRACT_INSTRUCTIONS } from "./tools/datetime.js";
+/**
+ * Tools an agent can call with literally no arguments — the entry points for a
+ * user who has not offered birth data.
+ *
+ * Asserted against the real schemas in test/description-cross-references.test.ts:
+ * each name here must be registered, must be on the CORE surface (most hosts
+ * refuse to call a tool absent from tools/list), and must genuinely have no
+ * required fields. Naming a tool here that needs an argument puts the model's
+ * very first call on a path to a validation error, which is the exact failure
+ * this list exists to prevent.
+ *
+ * Order is deliberate: the visual one leads, because a rendered dial is a
+ * better first impression than a score.
+ */
+export const ZERO_ARG_ENTRY_TOOLS = [
+    "explore_moon_phase",
+    "electional_moment_analysis",
+];
+export const SERVER_INSTRUCTIONS = "Open Ephemeris computes real astronomy (JPL DE440, sub-arcsecond) — never guess " +
+    "or approximate positions yourself; always call a tool. " +
+    "For anything the user should SEE (natal chart, bi-wheel, bodygraph, moon phase), " +
+    "prefer the explore_* tools — they render interactive visuals inline. " +
+    "ephemeris_* tools return data; use format='llm' on them for compact output. " +
+    "If the user has no birth data handy, open with the sky right now: " +
+    `${ZERO_ARG_ENTRY_TOOLS.join(" and ")} take no arguments at all — ` +
+    "call one rather than asking for a birth date first. " +
+    "See the 'welcome_to_open_ephemeris' prompt for orientation.\n\n" +
+    DATETIME_CONTRACT_INSTRUCTIONS;

package/dist/prompts.js

@@ -16,7 +16,9 @@ export const PROMPTS = [
         description: "Orientation guide for the Open Ephemeris MCP. Understand available tools, key concepts, " +
             "and how to pick the right prompt for the task.",
         text: "Welcome to the **Open Ephemeris MCP Server** — an enterprise-grade astrological and astronomical " +
-            "computation engine powered by NASA JPL DE440 ephemeris data (1550–2650 CE).\n\n" +
+            "computation engine powered by NASA JPL DE440 ephemeris data (1550–2650 CE for the Sun, " +
+            "Moon, and planets; 1600–2200 CE for the extended asteroid, centaur, and trans-Neptunian " +
+            "catalog).\n\n" +
             "## Available Workflows\n" +
             "There are specialized prompts for each of the following. Ask the user which they'd like, " +
             "or jump in directly if they've already told you:\n\n" +

package/dist/schema-packs/llm.d.ts

@@ -3,8 +3,8 @@ export declare const LLM_V2_POINTS_SCHEMA: readonly ["id", "kind", "src", "lon",
 export declare const LLM_V2_ASPECTS_SCHEMA: readonly ["a_i", "b_i", "t", "orb", "orb_pct", "app", "str"];
 export declare const LLM_V2_DICT: {
     readonly sign_id: readonly ["ari", "tau", "gem", "can", "leo", "vir", "lib", "sco", "sag", "cap", "aqu", "pis"];
-    readonly aspect_id: readonly ["con", "opp", "tri", "sqr", "sex"];
-    readonly aspect_angle: readonly [0, 180, 120, 90, 60];
+    readonly aspect_id: readonly ["con", "opp", "tri", "sqr", "sex", "ssx", "ssq", "qui", "sqq", "bqu", "qcx"];
+    readonly aspect_angle: readonly [0, 180, 120, 90, 60, 30, 45, 72, 135, 144, 150];
     readonly kind_id: readonly ["planet", "angle", "node", "lilith", "asteroid", "other"];
 };
 export declare const LlmV2PayloadSchema: z.ZodObject<{

package/dist/schema-packs/llm.js

@@ -18,10 +18,19 @@ export const LLM_V2_POINTS_SCHEMA = [
     "on_cusp",
 ];
 export const LLM_V2_ASPECTS_SCHEMA = ["a_i", "b_i", "t", "orb", "orb_pct", "app", "str"];
+// aspect_id / aspect_angle mirror the Go projection's dictionary
+// (llmAspectIDs / llmAspectAngles in internal/api/handlers/llm_projection.go).
+// The six minor aspects became detectable behind options.include_minor_aspects,
+// so they are enumerated here too — a `t` value the pack does not declare fails
+// DictZ, which is a strict tuple of literals, and check:schema-packs gates the
+// release on it.
+//
+// APPEND ONLY, and in the Go dictionary's order: the index is the wire value of
+// the aspects table's `t` column, so reordering re-points every stored row.
 export const LLM_V2_DICT = {
     sign_id: ["ari", "tau", "gem", "can", "leo", "vir", "lib", "sco", "sag", "cap", "aqu", "pis"],
-    aspect_id: ["con", "opp", "tri", "sqr", "sex"],
-    aspect_angle: [0, 180, 120, 90, 60],
+    aspect_id: ["con", "opp", "tri", "sqr", "sex", "ssx", "ssq", "qui", "sqq", "bqu", "qcx"],
+    aspect_angle: [0, 180, 120, 90, 60, 30, 45, 72, 135, 144, 150],
     kind_id: ["planet", "angle", "node", "lilith", "asteroid", "other"],
 };
 const PointsSchemaZ = z.tuple(LLM_V2_POINTS_SCHEMA.map((v) => z.literal(v)));

package/dist/server-sse.js

@@ -21,10 +21,10 @@ import axios from "axios";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { InMemoryEventStore } from "./event-store.js";
-import { captureEvent, distinctIdFor } from "./analytics.js";
+import { captureEvent, captureFirstToolCallOnce, distinctIdFor } from "./analytics.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, isInitializeRequest, } from "@modelcontextprotocol/sdk/types.js";
 import { initTools, toolRegistry, formatToolResponse, formatToolError, modelVisibleTools, parseToolSurface, describeSurface } from "./tools/index.js";
-import { DATETIME_CONTRACT_INSTRUCTIONS } from "./tools/datetime.js";
+import { SERVER_INSTRUCTIONS } from "./instructions.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";
 import { BODYGRAPH_RESOURCE_URI, BODYGRAPH_MIME_TYPE, getBodygraphBundle, } from "./tools/apps/bodygraph-app.js";
@@ -224,7 +224,36 @@ function transportProps(server, surface) {
         server_version: version,
     };
 }
-function createMcpServer(analyticsId = "anonymous", surface = "core") {
+function newSessionActivity() {
+    return { startedAt: Date.now(), listedTools: false, attemptedTool: false, silenceReported: false };
+}
+/**
+ * Emit `mcp_session_silent` for a session that saw the tool list and never tried
+ * to use it — the measurable form of the connector drop-off.
+ *
+ * Two caveats for whoever reads this in PostHog, because they change the query:
+ *
+ *  1. The event lands when the session TEARS DOWN, not when it went quiet. A
+ *     host that vanishes without a DELETE is only cleaned up by the idle reaper,
+ *     so its event can arrive SESSION_IDLE_TTL_MS + up to one 10-minute sweep
+ *     after the fact. Read it in daily aggregate, not as a live signal, and use
+ *     `session_duration_ms` to separate "closed straight away" from "sat open
+ *     and unused".
+ *  2. It UNDERCOUNTS. A process restart (i.e. every deploy) drops the sessions
+ *     still pending teardown. `mcp_tools_listed` with no following
+ *     `first_tool_call` is the reliable denominator; this event is the richer
+ *     but lossier view.
+ */
+function reportSilentSession(server, analyticsId, surface, activity) {
+    if (!activity.listedTools || activity.attemptedTool || activity.silenceReported)
+        return;
+    activity.silenceReported = true;
+    captureEvent("mcp_session_silent", analyticsId, {
+        session_duration_ms: Date.now() - activity.startedAt,
+        ...transportProps(server, surface),
+    });
+}
+function createMcpServer(analyticsId = "anonymous", surface = "core", activity = newSessionActivity()) {
     const server = new Server({
         name: "openephemeris-mcp",
         title: "Open Ephemeris",
@@ -266,19 +295,11 @@ function createMcpServer(analyticsId = "anonymous", surface = "core") {
                 },
             },
         },
-        instructions: "Open Ephemeris computes real astronomy (JPL DE440, sub-arcsecond) — never guess " +
-            "or approximate positions yourself; always call a tool. " +
-            "For anything the user should SEE (natal chart, bi-wheel, bodygraph, moon phase), " +
-            "prefer the explore_* tools — they render interactive visuals inline. " +
-            "ephemeris_* tools return data; use format='llm' on them for compact output. " +
-            "If the user has no birth data handy, start with the sky right now — " +
-            "explore_moon_phase and ephemeris_retrograde_status need none. " +
-            "See the 'welcome_to_open_ephemeris' prompt for orientation.\n\n" +
-            DATETIME_CONTRACT_INSTRUCTIONS,
+        instructions: SERVER_INSTRUCTIONS,
     });
     // --- Tool handlers ---
-    server.setRequestHandler(ListToolsRequestSchema, async () => ({
-        tools: modelVisibleTools("http", surface).map((tool) => ({
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        const tools = modelVisibleTools("http", surface).map((tool) => ({
             name: tool.name,
             description: tool.description,
             inputSchema: tool.inputSchema,
@@ -295,8 +316,18 @@ function createMcpServer(analyticsId = "anonymous", surface = "core") {
                     },
                 }
                 : {}),
-        })),
-    }));
+        }));
+        // Once per session: the host has fetched the surface. Everything after this
+        // point is the model's choice, so this is the denominator for activation.
+        if (!activity.listedTools) {
+            activity.listedTools = true;
+            captureEvent("mcp_tools_listed", analyticsId, {
+                tool_count: tools.length,
+                ...transportProps(server, surface),
+            });
+        }
+        return { tools };
+    });
     // --- Prompt handlers ---
     server.setRequestHandler(ListPromptsRequestSchema, async () => ({
         prompts: [WELCOME_PROMPT],
@@ -313,6 +344,9 @@ function createMcpServer(analyticsId = "anonymous", surface = "core") {
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const toolName = request.params.name;
         const tool = toolRegistry[toolName];
+        // Marked before the registry check: reaching for a tool that does not exist
+        // is still a session that tried, and must not be counted as silence.
+        activity.attemptedTool = true;
         if (!tool || tool.stdioOnly) {
             // stdioOnly tools (device auth) mutate process-global state and must not
             // be callable on the multi-tenant HTTP transport, even by name.
@@ -331,6 +365,7 @@ function createMcpServer(analyticsId = "anonymous", surface = "core") {
                 duration_ms: durationMs,
                 ...transportProps(server, surface),
             });
+            captureFirstToolCallOnce(analyticsId, { tool: toolName, ...transportProps(server, surface) });
             return formatToolResponse(toolName, result, durationMs);
         }
         catch (error) {
@@ -854,7 +889,8 @@ export async function createSseApp() {
         // 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);
+        const activity = newSessionActivity();
+        const server = createMcpServer(analyticsId, surface, activity);
         // Fire session_init after the handshake so getClientVersion() is populated
         // — without this the connecting host is unknown and we cannot tell which
         // clients the remote server is actually serving.
@@ -869,6 +905,10 @@ export async function createSseApp() {
                 httpSessions.delete(transport.sessionId);
                 console.error(`[HTTP] Session closed: ${transport.sessionId}`);
             }
+            // All three teardown paths (transport close, DELETE /mcp, idle reaper)
+            // converge here — server.close() closes the transport — so this is the one
+            // place the silence verdict has to be made.
+            reportSilentSession(server, analyticsId, surface, activity);
         };
         await server.connect(transport);
         await runWithClient(client, () => transport.handleRequest(req, res, req.body));

package/dist/tools/apps/_location-resolver.d.ts

@@ -5,6 +5,17 @@ export interface ResolvedLocation {
     displayName: string;
     placeId: string | null;
 }
+/**
+ * Whether the query itself already pins the top hit — "dallas texas",
+ * "san francisco, ca", "paris, france", "london uk" — so rival cities of
+ * the same short name are not actually ambiguous.
+ *
+ * Single source of truth for the ambiguity qualifier: both
+ * `resolveLocationOrThrow` and the `location_search` tool call this. The
+ * two call sites read differently-named fields (raw `region`/`country_code`
+ * vs mapped `region`/`countryCode`), so this takes plain strings.
+ */
+export declare function isQualifiedForTopHit(query: string, region: unknown, countryCode: unknown): boolean;
 /**
  * Resolve a place name to lat/lon/tz. Throws if ambiguous or unresolvable.
  *

package/dist/tools/apps/_location-resolver.js

@@ -52,6 +52,29 @@ function countryNameFor(code) {
 // Colloquial forms Intl does not produce: it renders GB as "United Kingdom",
 // so a bare "uk" token would otherwise miss.
 const COUNTRY_ALIASES = { uk: "gb", usa: "us", uae: "ae" };
+/**
+ * Whether the query itself already pins the top hit — "dallas texas",
+ * "san francisco, ca", "paris, france", "london uk" — so rival cities of
+ * the same short name are not actually ambiguous.
+ *
+ * Single source of truth for the ambiguity qualifier: both
+ * `resolveLocationOrThrow` and the `location_search` tool call this. The
+ * two call sites read differently-named fields (raw `region`/`country_code`
+ * vs mapped `region`/`countryCode`), so this takes plain strings.
+ */
+export function isQualifiedForTopHit(query, region, countryCode) {
+    const norm = (v) => String(v ?? "").trim().toLowerCase();
+    const q = norm(query);
+    const qTokens = new Set(q.split(/[^a-z0-9]+/).filter(Boolean));
+    const topRegion = norm(region);
+    const topCountry = norm(countryCode);
+    const topCountryName = topCountry === "" ? "" : countryNameFor(topCountry);
+    return ((topRegion !== "" && q.includes(topRegion)) ||
+        (topRegion !== "" && [...qTokens].some((t) => US_STATE_ABBREVIATIONS[t] === topRegion)) ||
+        (topCountry !== "" && qTokens.has(topCountry)) ||
+        (topCountryName !== "" && q.includes(topCountryName)) ||
+        (topCountry !== "" && [...qTokens].some((t) => COUNTRY_ALIASES[t] === topCountry)));
+}
 // `code` rides along to PostHog via the existing `code` property on
 // mcp_tool_error. The event deliberately records no message or stack, so
 // without a code every one of these lands as code:"none" / error_kind:"local"
@@ -82,16 +105,7 @@ export async function resolveLocationOrThrow(location) {
     const norm = (v) => String(v ?? "").trim().toLowerCase();
     const top = list[0];
     const rivals = list.filter((s) => norm(s.short_name) === norm(top.short_name));
-    const q = norm(query);
-    const qTokens = new Set(q.split(/[^a-z0-9]+/).filter(Boolean));
-    const topRegion = norm(top.region);
-    const topCountry = norm(top.country_code);
-    const topCountryName = topCountry === "" ? "" : countryNameFor(topCountry);
-    const qualified = (topRegion !== "" && q.includes(topRegion)) ||
-        (topRegion !== "" && [...qTokens].some((t) => US_STATE_ABBREVIATIONS[t] === topRegion)) ||
-        (topCountry !== "" && qTokens.has(topCountry)) ||
-        (topCountryName !== "" && q.includes(topCountryName)) ||
-        (topCountry !== "" && [...qTokens].some((t) => COUNTRY_ALIASES[t] === topCountry));
+    const qualified = isQualifiedForTopHit(query, top.region, top.country_code);
     const ambiguous = rivals.length > 1 && !qualified;
     if (ambiguous) {
         const options = rivals

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

@@ -88,7 +88,16 @@ function prettyHouseSystem(hs) {
     return hs.split("_").map(capitalize).join(" ");
 }
 /** Build the nested request body expected by /ephemeris/natal-chart (POST). */
-function buildNatalBody(datetime, lat, lon, houseSystem, timezone) {
+function buildNatalBody(datetime, lat, lon, houseSystem, timezone, additionalObjects) {
+    const configuration = {
+        house_system: HOUSE_SYSTEM_MAP[houseSystem] ?? "P",
+    };
+    if (additionalObjects && additionalObjects.length > 0) {
+        // additional_objects is additive on top of the API's fixed base roster
+        // (classical planets, nodes, Chiron, major asteroids) — it does not
+        // replace it. See handler_ephemeris2.go's body-ID resolution.
+        configuration.additional_objects = additionalObjects;
+    }
     const body = {
         subject: {
             name: "MCP Request",
@@ -98,9 +107,7 @@ function buildNatalBody(datetime, lat, lon, houseSystem, timezone) {
                 longitude: { decimal: lon ?? 0 },
             },
         },
-        configuration: {
-            house_system: HOUSE_SYSTEM_MAP[houseSystem] ?? "P",
-        },
+        configuration,
         options: {
             include_aspects: true,
         },
@@ -149,8 +156,10 @@ registerTool({
                 items: { type: "string" },
                 description: "Optional list of body names to include. " +
                     "Defaults to 13 classical bodies (Sun through Pluto + Chiron + Nodes). " +
-                    "Use 'all' as a single item to include every available body (Lilith, Ceres, Juno, Vesta, Pallas, Vertex, etc.). " +
-                    "Example: ['sun','moon','lilith','vertex'].",
+                    "Use 'all' as a single item to include every available body (Lilith, Ceres, Juno, Vesta, Pallas, Vertex, " +
+                    "the 8 trans-Neptunian objects — eris, sedna, makemake, haumea, quaoar, orcus, ixion, varuna — and the " +
+                    "8 Uranian/Hamburg-School points — cupido, hades, zeus, kronos, apollon, admetos, vulkanus, poseidon). " +
+                    "Example: ['sun','moon','lilith','sedna'].",
             },
         },
         required: ["datetime"],
@@ -189,18 +198,22 @@ registerTool({
         // caller's explicit timezone still wins when supplied.
         const effectiveTimezone = args.timezone ?? resolved.timezone;
         const effectiveLocation = resolved.location ?? args.location;
-        const natalBody = buildNatalBody(datetime, lat, lon, houseSystem, effectiveTimezone);
-        // Determine which bodies are requested
+        // Determine which bodies are requested. Recognized extended slugs (TNOs,
+        // Uranian points, Lilith variants, etc.) are sent to the API as
+        // additional_objects so the API actually computes them — previously this
+        // only flipped legacy include_* booleans the natal-chart endpoint's
+        // schema doesn't have, so extended bodies (beyond the ones already in the
+        // API's fixed default roster) never reached the response. See #612-area
+        // catalog-expansion follow-up: TNO/Uranian bodies were addressable via
+        // /catalogs/bodies but unreachable from any chart-computation endpoint.
         const requestedBodies = args.bodies;
         const wantsAll = requestedBodies?.some(b => b.toLowerCase() === "all");
-        const wantsExtended = wantsAll || requestedBodies?.some(b => EXTENDED_BODIES.has(b.toLowerCase()));
-        // Enable extended body computation on the API side when needed
-        if (wantsExtended) {
-            const config = natalBody.configuration;
-            config.include_asteroids = true;
-            config.include_lilith = true;
-            config.include_chiron = true;
-        }
+        const additionalObjects = wantsAll
+            ? Array.from(EXTENDED_BODIES)
+            : (requestedBodies ?? [])
+                .map(b => b.toLowerCase())
+                .filter(b => EXTENDED_BODIES.has(b));
+        const natalBody = buildNatalBody(datetime, lat, lon, houseSystem, effectiveTimezone, additionalObjects);
         // Fetch natal chart JSON. The chart is rendered client-side in the UI iframe,
         // so we do NOT call the /visualization/chart-wheel endpoint — that was the
         // source of the ~90 second blocking delay.
@@ -461,10 +474,15 @@ function canonicalizeBodyName(raw) {
     return lower;
 }
 const EXTENDED_BODIES = new Set([
-    "mean_lilith", "lilith", "true_lilith",
+    // Slugs match the Go API's ephemerisIDForSlug (handler_wheel_resolver.go) so
+    // additional_objects entries actually resolve server-side.
+    "mean_lilith", "lilith", "lilith_true",
     "ceres", "juno", "vesta", "pallas", "pholus",
     "vertex", "part_of_fortune",
-    "eris", "sedna",
+    // Trans-Neptunian objects (all 8 — #603 catalog expansion)
+    "eris", "sedna", "makemake", "haumea", "quaoar", "orcus", "ixion", "varuna",
+    // Uranian / Hamburg School hypothetical points (all 8 — #603 catalog expansion)
+    "cupido", "hades", "zeus", "kronos", "apollon", "admetos", "vulkanus", "poseidon",
 ]);
 const ALL_KNOWN_BODIES = new Set([...CLASSICAL_PLANETS, ...EXTENDED_BODIES]);
 /**

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

@@ -2,6 +2,7 @@ import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
 import { TZDATA_AUTHORITATIVE_FROM_YEAR } from "../datetime-historical.js";
+import { isQualifiedForTopHit } from "./_location-resolver.js";
 /**
  * Lift the API's historical-correction provenance onto an MCP result.
  *
@@ -254,11 +255,7 @@ registerTool({
         const rivals = top ? suggestions.filter((s) => norm(s.shortName) === norm(top.shortName)) : [];
         // If the caller already pinned the place — "dallas texas", "portland uk" —
         // the top hit is what they asked for and there is nothing to ask about.
-        const q = norm(args.query);
-        const qTokens = new Set(q.split(/[^a-z0-9]+/).filter(Boolean));
-        const qualified = !!top &&
-            ((norm(top.region) !== "" && q.includes(norm(top.region))) ||
-                (norm(top.countryCode) !== "" && qTokens.has(norm(top.countryCode))));
+        const qualified = !!top && isQualifiedForTopHit(args.query, top.region, top.countryCode);
         const ambiguous = rivals.length > 1 && !qualified;
         return {
             suggestions,

package/dist/tools/dev.js

@@ -34,7 +34,14 @@ function isAllowedOperation(method, pathname, allow) {
 }
 // Shared reference block appended to both read/write proxy tools. Names the
 // target API (Open Ephemeris) explicitly — required by the directory for
-// freeform-path tools — plus credit costs and common calls.
+// freeform-path tools — plus credit costs.
+//
+// The COMMON CALLS list is NOT shared, because it is method-specific and the
+// two tools do not accept the same methods. It used to be: dev_read_api is
+// GET-only (READ_METHODS), and it was spending most of its description listing
+// fifteen POST endpoints it will reject — on the core surface, which every
+// client pays for on every model pass. Each tool now lists the calls it can
+// actually make.
 const DEV_API_REFERENCE = "Target API: Open Ephemeris REST API (https://api.openephemeris.com). " +
     "Call dev_list_allowed to see all currently available endpoint paths.\n\n" +
     "AUTH: Set OPENEPHEMERIS_API_KEY in your environment. See openephemeris.com/dashboard for active plan limits.\n\n" +
@@ -50,7 +57,27 @@ const DEV_API_REFERENCE = "Target API: Open Ephemeris REST API (https://api.open
     "  • Catalog / metadata / health endpoints: 0 credits\n" +
     "  • Compute surcharge: requests > 30s add 1 credit per 30s (predictive, acg, calendar, electional)\n" +
     "  • format=llm (token-optimized output): available on all tiers\n\n" +
-    "COMMON CALLS:\n" +
+    "BINARY RESPONSES:\n" +
+    "  • Binary/image endpoints return {content_type, content_length, encoding, data_base64}\n" +
+    "    so callers can decode bytes deterministically.\n\n" +
+    "ECLIPSE NOTE: Eclipse endpoints accept format=llm via the query param like other endpoints.\n\n" +
+    "format=llm NOTE: Add query: {format: 'llm'} to natal/synastry/composite/HD endpoints for " +
+    "compact columnar output optimized for LLM token budgets (availability depends on your current plan).";
+const READ_COMMON_CALLS = "COMMON CALLS:\n" +
+    "  GET  /ephemeris/moon/phase             — Current/queried moon phase\n" +
+    "  GET  /ephemeris/moon/void-of-course    — Next void-of-course period\n" +
+    "  GET  /ephemeris/agro/daily             — Biodynamic farming day quality\n" +
+    "  GET  /ephemeris/agro/calendar          — Multi-day biodynamic calendar\n" +
+    "  GET  /ephemeris/agro/void-of-course    — Biodynamic VoC periods\n" +
+    "  GET  /eclipse/next-visible             — Next eclipse visible from a location (query: lat, lon, type=solar|lunar)\n" +
+    "  GET  /eclipse/solar/global             — Next global solar eclipse (query: date=YYYY-MM-DD)\n" +
+    "  GET  /eclipse/solar/local              — Local solar eclipse (query: lat, lon)\n" +
+    "  GET  /tidal/forcing                    — Gravitational tidal forcing index\n" +
+    "  GET  /calendar/astrology/moon-phases   — Moon phase calendar for a date range\n" +
+    "  GET  /location/autocomplete            — Geocode a place name (query: query=City Name)\n" +
+    "  GET  /chinese/zodiac                   — Chinese zodiac year element/animal\n" +
+    "  GET  /catalogs/bodies                  — List all supported celestial bodies\n";
+const WRITE_COMMON_CALLS = "COMMON CALLS:\n" +
     "  POST /ephemeris/natal-chart            — Full natal chart (body: {subject: {name: 'Name', birth_datetime: {iso: '1990-04-15T14:30:00-05:00'}, birth_location: {latitude: {decimal: 40.0}, longitude: {decimal: -70.0}, timezone: {}}}})\n" +
     "  POST /ephemeris/natal/batch            — Up to 50 natal charts in one request\n" +
     "  POST /ephemeris/relocation             — Relocated chart (same natal, new location)\n" +
@@ -61,30 +88,11 @@ const DEV_API_REFERENCE = "Target API: Open Ephemeris REST API (https://api.open
     "  POST /comparative/composite            — Composite (midpoint) chart\n" +
     "  POST /human-design/chart               — Full HD chart (body: {birth_datetime_utc: '1990-04-15T19:30:00Z'}) — lat/lon optional\n" +
     "  POST /time/julian-day                  — Convert date to JD (body: {year: 1987, month: 7, day: 15, hour: 14, minute: 1})\n" +
-    "  GET  /ephemeris/moon/phase             — Current/queried moon phase\n" +
-    "  GET  /ephemeris/moon/void-of-course    — Next void-of-course period\n" +
-    "  GET  /ephemeris/agro/daily             — Biodynamic farming day quality\n" +
-    "  GET  /ephemeris/agro/calendar          — Multi-day biodynamic calendar\n" +
-    "  GET  /ephemeris/agro/void-of-course    — Biodynamic VoC periods\n" +
-    "  GET  /eclipse/next-visible             — Next eclipse visible from a location (query: lat, lon, type=solar|lunar)\n" +
-    "  GET  /eclipse/solar/global             — Next global solar eclipse (query: date=YYYY-MM-DD)\n" +
-    "  GET  /eclipse/solar/local              — Local solar eclipse (query: lat, lon)\n" +
-    "  GET  /tidal/forcing                    — Gravitational tidal forcing index\n" +
     "  POST /acg/power-lines                 — Astrocartography power lines (lat/lon GeoJSON)\n" +
     "  POST /acg/hits                         — ACG power at a specific location\n" +
-    "  GET  /calendar/astrology/moon-phases   — Moon phase calendar for a date range\n" +
-    "  GET  /location/autocomplete            — Geocode a place name (query: query=City Name)\n" +
     "  POST /timezone/lookup                  — Resolve timezone + UTC offset for a location\n" +
     "  POST /chinese/bazi                     — Chinese Ba Zi (Four Pillars) chart (body: {year, month, day, hour})\n" +
-    "  GET  /chinese/zodiac                   — Chinese zodiac year element/animal\n" +
-    "  POST /vedic/chart                      — Vedic (Jyotish) natal chart (body: {datetime_utc, latitude, longitude})\n" +
-    "  GET  /catalogs/bodies                  — List all supported celestial bodies\n\n" +
-    "BINARY RESPONSES:\n" +
-    "  • Binary/image endpoints return {content_type, content_length, encoding, data_base64}\n" +
-    "    so callers can decode bytes deterministically.\n\n" +
-    "ECLIPSE NOTE: Eclipse endpoints accept format=llm via the query param like other endpoints.\n\n" +
-    "format=llm NOTE: Add query: {format: 'llm'} to natal/synastry/composite/HD endpoints for " +
-    "compact columnar output optimized for LLM token budgets (availability depends on your current plan).";
+    "  POST /vedic/chart                      — Vedic (Jyotish) natal chart (body: {datetime_utc, latitude, longitude})";
 // The read and write proxies are kept as separate tools (not one method-switching
 // tool) so that safe GET reads never share a surface with state-changing writes —
 // a hard requirement of the Anthropic connector directory.
@@ -193,7 +201,7 @@ registerTool({
         "first for common operations. Endpoints that compute via POST (natal-chart, synastry, etc.) " +
         "are covered by the typed tools; the generic POST proxy is only exposed on the full tool " +
         "surface (`?profile=full`).\n\n" +
-        DEV_API_REFERENCE,
+        DEV_API_REFERENCE + "\n\n" + READ_COMMON_CALLS,
     inputSchema: makeProxyInputSchema(READ_METHODS),
     outputSchema: OUTPUT_SCHEMA_JSON,
     // GET-only: never mutates server state. openWorldHint false — the proxy
@@ -208,7 +216,7 @@ registerTool({
         "Most chart computations (natal-chart, synastry, composite, transits/search, returns, ACG) are " +
         "POST endpoints and use this tool. Use the typed tools first for common operations; use dev_read_api " +
         "for GET endpoints.\n\n" +
-        DEV_API_REFERENCE,
+        DEV_API_REFERENCE + "\n\n" + WRITE_COMMON_CALLS,
     inputSchema: makeProxyInputSchema(WRITE_METHODS),
     outputSchema: OUTPUT_SCHEMA_JSON,
     // Issues POST/PUT/PATCH/DELETE — must not be advertised as read-only. But

package/dist/tools/specialized/bi_wheel.js

@@ -2,10 +2,11 @@ import { registerTool, validateRequired, pickEnum } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_IMAGE } from "../output-schemas.js";
 import { DATETIME_DESC, assertZonedDatetime, timezoneProperty } from "../datetime.js";
+// The seven systems the engine accepts (internal/math/houses.go).
+// Do not re-add alcabitius/morinus — see the note in natal.ts.
 const HOUSE_SYSTEM_MAP = {
     placidus: "P", whole_sign: "W", equal: "E", koch: "K",
     campanus: "C", regiomontanus: "R", porphyry: "O",
-    alcabitius: "B", morinus: "M",
 };
 registerTool({
     name: "ephemeris_bi_wheel",
@@ -27,7 +28,7 @@ registerTool({
             longitude_b: { type: "number", description: "Longitude for subject B" },
             house_system: {
                 type: "string",
-                enum: ["placidus", "whole_sign", "equal", "koch", "campanus", "regiomontanus", "porphyry", "alcabitius", "morinus"],
+                enum: ["placidus", "whole_sign", "equal", "koch", "campanus", "regiomontanus", "porphyry"],
                 description: "House system to use. Defaults to 'placidus' if omitted.",
             },
             style: {

package/dist/tools/specialized/chart_wheel.js

@@ -2,10 +2,11 @@ import { registerTool, validateRequired, pickEnum } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_IMAGE } from "../output-schemas.js";
 import { DATETIME_DESC, TIMEZONE_PROPERTY, assertZonedDatetime } from "../datetime.js";
+// The seven systems the engine accepts (internal/math/houses.go).
+// Do not re-add alcabitius/morinus — see the note in natal.ts.
 const HOUSE_SYSTEM_MAP = {
     placidus: "P", whole_sign: "W", equal: "E", koch: "K",
     campanus: "C", regiomontanus: "R", porphyry: "O",
-    alcabitius: "B", morinus: "M",
 };
 registerTool({
     name: "ephemeris_chart_wheel",
@@ -32,7 +33,7 @@ registerTool({
             },
             house_system: {
                 type: "string",
-                enum: ["placidus", "whole_sign", "equal", "koch", "campanus", "regiomontanus", "porphyry", "alcabitius", "morinus"],
+                enum: ["placidus", "whole_sign", "equal", "koch", "campanus", "regiomontanus", "porphyry"],
                 description: "House system to use. Defaults to 'placidus' if omitted.",
             },
             style: {

package/dist/tools/specialized/electional.js

@@ -85,14 +85,27 @@ registerTool({
     },
 });
 // GET /electional/moment-analysis
+//
+// latitude/longitude are OPTIONAL here and required on ephemeris_electional
+// above, deliberately. This tool is one of two ZERO_ARG_ENTRY_TOOLS
+// (src/instructions.ts): the server instructions promise a host it "takes no
+// arguments at all", and test/description-cross-references.test.ts asserts the
+// schema keeps that promise. Requiring coordinates would turn the cold-open
+// call — the first thing a model does for a user who has offered no data — into
+// a validation error, which is the exact failure that list exists to prevent.
+//
+// The scoring risk is handled in the parameter descriptions instead: the Go
+// handler falls back to a day chart without coordinates and says so in
+// score_detail.sect_basis ("default_diurnal_no_coordinates"), so a caller that
+// omits them gets a wrong-half-of-the-day score that is at least labelled.
 registerTool({
     name: "electional_moment_analysis",
     description: "Analyze the astrological quality of a specific moment: planet positions, aspects, " +
-        "void of course status, lunar phase, day ruler, and an overall electional score (0-100). " +
+        "void of course status, lunar phase, day ruler, sect, and an overall electional score (0-100). " +
         "Perfect for evaluating whether 'right now' or a specific date/time is good for action.\n\n" +
         "CREDIT COST: 5 credits per call.\n\n" +
-        "EXAMPLE: Analyze March 21, 2026 at noon:\n" +
-        "  date='2026-03-21T12:00:00Z'",
+        "EXAMPLE: Analyze March 21, 2026 at noon in New York:\n" +
+        "  date='2026-03-21T12:00:00Z', latitude=40.7128, longitude=-74.0060",
     inputSchema: {
         type: "object",
         properties: {
@@ -100,6 +113,14 @@ registerTool({
                 type: "string",
                 description: "ISO 8601 datetime to analyze, with a zone (e.g., '2026-03-21T12:00:00Z' or '2026-03-21T08:00:00-04:00'). Defaults to now.",
             },
+            latitude: {
+                type: "number",
+                description: "Latitude of location in decimal degrees (positive = North). Resolve from a place name with location_search; never recall coordinates from memory. Optional, but pass both whenever the place is known — without them sect falls back to diurnal and a night moment is scored with the DAY triplicity rulers.",
+            },
+            longitude: {
+                type: "number",
+                description: "Longitude of location in decimal degrees (positive = East). Needed alongside latitude — day/night is a local fact that neither coordinate settles alone.",
+            },
             format: {
                 type: "string",
                 enum: ["json", "llm"],
@@ -115,6 +136,13 @@ registerTool({
         const query = {};
         if (args.date)
             query.date = args.date;
+        // `!== undefined`, not truthiness: latitude 0 (equator) and longitude 0
+        // (Greenwich) are real places, and a falsy check would drop them and
+        // silently score those elections as day charts.
+        if (args.latitude !== undefined)
+            query.latitude = args.latitude;
+        if (args.longitude !== undefined)
+            query.longitude = args.longitude;
         if (args.format)
             query.format = args.format;
         return await getActiveClient().request("GET", "/electional/moment-analysis", {

package/dist/tools/specialized/ephemeris_extended.js

@@ -276,7 +276,9 @@ registerTool({
 registerTool({
     name: "ephemeris_angles_points",
     description: "Calculate chart angles and sensitive points (ASC, MC, DSC, IC, Vertex, " +
-        "East Point, etc.) for a given date/time and location.\n\n" +
+        "Equatorial Ascendant/Descendant) for a given date/time and location. " +
+        "The equatorial ascendant is also returned under the key `east_point` — " +
+        "a synonym for the same point, not a separate one.\n\n" +
         "CREDIT COST: 1 credit per call.",
     inputSchema: {
         type: "object",

package/dist/tools/specialized/natal.js

@@ -2,11 +2,25 @@ import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_IMAGE_AND_JSON } from "../output-schemas.js";
 import { DATETIME_DESC, TIMEZONE_PROPERTY, assertZonedDatetime } from "../datetime.js";
-/** Map human-readable house system names to standard single-letter codes */
+/**
+ * Map human-readable house system names to standard single-letter codes.
+ *
+ * These seven are the whole set. They are exactly what
+ * `CanonicalHouseSystemCode` accepts (`internal/math/houses.go`) and exactly
+ * what `GET /ephemeris/house-systems` returns.
+ *
+ * Do not add `alcabitius: "B"` or `morinus: "M"` back. They were advertised
+ * here through 4.4.0 and never worked: the codes "B" and "M" are accepted by
+ * no code path, so every call naming them came back
+ * `422 Validation error: house_system is invalid`. The engine does take the
+ * *slugs* "alcabitius"/"morinus", but only by silently aliasing them to Koch
+ * and Regiomontanus — so wiring the slug through would answer a request for
+ * one system with a different system's cusps. Neither is implemented; until
+ * one is, neither belongs in a schema.
+ */
 const HOUSE_SYSTEM_MAP = {
     placidus: "P", whole_sign: "W", equal: "E", koch: "K",
     campanus: "C", regiomontanus: "R", porphyry: "O",
-    alcabitius: "B", morinus: "M",
 };
 registerTool({
     name: "ephemeris_natal_chart",
@@ -37,7 +51,7 @@ registerTool({
             },
             house_system: {
                 type: "string",
-                enum: ["placidus", "whole_sign", "equal", "koch", "campanus", "regiomontanus", "porphyry", "alcabitius", "morinus"],
+                enum: ["placidus", "whole_sign", "equal", "koch", "campanus", "regiomontanus", "porphyry"],
                 description: "House system to use. Defaults to 'placidus' if omitted.",
             },
             format: {
@@ -49,9 +63,34 @@ registerTool({
                 type: "boolean",
                 description: "Include Hermetic Lots / Arabic Parts in the natal response (routed as `options.include_hermetic_lots: true`). For a standalone lots-only payload without a full natal chart, use `/ephemeris/hermetic-lots` instead.",
             },
-            include_fixed_stars: {
+            zodiac_type: {
+                type: "string",
+                enum: ["tropical", "sidereal"],
+                description: "Zodiac frame. Default tropical. `sidereal` subtracts the ayanamsa (~24°) from every " +
+                    "longitude, so signs, dignities and element balance all move; aspects and house numbers " +
+                    "do not. The response names the frame it used.",
+            },
+            ayanamsa: {
+                type: "string",
+                enum: ["lahiri", "fagan_bradley", "krishnamurti", "raman", "yukteshwar"],
+                description: "Sidereal system. Default lahiri. Only read when zodiac_type is `sidereal`.",
+            },
+            analytics: {
+                type: "array",
+                items: {
+                    type: "string",
+                    enum: ["element_balance", "hemisphere_emphasis", "aspect_patterns", "harmonics"],
+                },
+                description: "Optional whole-chart analytics, off by default: element_balance (fire/earth/air/water plus " +
+                    "modality counts over the classical ten, unweighted), hemisphere_emphasis (above/below and " +
+                    "east/west from the angles), aspect_patterns (aspect matrix + detected patterns), harmonics. " +
+                    "No extra credits. Absent from format='llm'.",
+            },
+            include_minor_aspects: {
                 type: "boolean",
-                description: "Include fixed-star positions in the natal response (routed as `configuration.fixed_star_options.include: true`). For a standalone fixed-stars payload without a full natal chart, use `/ephemeris/fixed-stars` instead.",
+                description: "Add quincunx, semisextile, semisquare, sesquiquadrate, quintile and biquintile to the aspect " +
+                    "grid. Off by default; minors use their own orbs, so this widens the grid without changing " +
+                    "any major aspect.",
             },
             include_visual: {
                 type: "boolean",
@@ -98,10 +137,43 @@ registerTool({
             const code = HOUSE_SYSTEM_MAP[args.house_system] ?? args.house_system;
             body.configuration = { house_system: code };
         }
-        if (args.include_fixed_stars) {
+        // Sidereal. The endpoint accepted zodiac_type on paper for as long as
+        // NatalConfig has existed and read it nowhere, so asking for a sidereal
+        // chart returned a tropical one with every body most of a whole sign
+        // out and nothing in the payload saying so. It is honoured now, which
+        // is the only reason this is exposed here.
+        if (args.zodiac_type === "sidereal") {
             body.configuration = {
                 ...(body.configuration || {}),
-                fixed_star_options: { include: true }
+                zodiac_type: "sidereal",
+                ...(args.ayanamsa ? { ayanamsa: args.ayanamsa } : {}),
+            };
+        }
+        else if (args.ayanamsa) {
+            // Naming a system and getting the tropical chart anyway is the same
+            // silence this parameter spent its whole life as. Say so instead.
+            throw new Error("ayanamsa only applies when zodiac_type is 'sidereal' — the tropical zodiac has no ayanamsa.");
+        }
+        // enhanced_options is where the Go engine keeps whole-chart analytics.
+        // The endpoint has always accepted these; nothing here ever sent them,
+        // so every one of these capabilities was unreachable from MCP.
+        if (Array.isArray(args.analytics) && args.analytics.length > 0) {
+            const want = new Set(args.analytics);
+            const enhanced = {};
+            if (want.has("element_balance"))
+                enhanced.element_balance = true;
+            if (want.has("hemisphere_emphasis"))
+                enhanced.hemisphere_emphasis = true;
+            if (want.has("aspect_patterns"))
+                enhanced.aspect_patterns = true;
+            if (want.has("harmonics"))
+                enhanced.include_harmonics = true;
+            body.enhanced_options = enhanced;
+        }
+        if (args.include_minor_aspects) {
+            body.options = {
+                ...body.options,
+                include_minor_aspects: true,
             };
         }
         if (args.include_arabic_parts) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openephemeris/mcp-server",
-  "version": "4.11.2",
+  "version": "4.13.0",
   "description": "Model Context Protocol server for the Open Ephemeris astronomical computation API",
   "type": "module",
   "main": "dist/index.js",
@@ -92,7 +92,7 @@
     "@types/adm-zip": "^0.5.8",
     "@types/express": "^5.0.3",
     "@types/node": "^25.0.1",
-    "adm-zip": "^0.5.17",
+    "adm-zip": "^0.6.0",
     "cross-env": "^10.1.0",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",