@openephemeris/mcp-server 3.5.2 → 3.6.0

package/CHANGELOG.md

@@ -7,6 +7,47 @@ Version numbering follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [3.6.0] — 2026-04-17
+
+### Added
+- `ephemeris_next_lunar_phase` — new purpose-built tool for "when is the next new/full/quarter moon?" queries.
+  Replaces a 4–7 step multi-call chain with a single, credit-efficient call. Internally calculates a rolling
+  search window and filters the calendar API response so the LLM receives a clean, normalized answer.
+
+### Changed (Tool Descriptions & LLM Routing)
+- `ephemeris_moon_phase` — sharpened description to clarify it is point-in-time only and cannot answer
+  "upcoming date" questions. Adds explicit `→ use ephemeris_next_lunar_phase` redirect.
+- `ephemeris_next_eclipse` — latitude/longitude are now **optional**. Omitting them triggers a global eclipse
+  search (`/eclipse/solar/global` or `/eclipse/lunar/global`), allowing Claude to answer "when is the next
+  total solar eclipse?" without forcing the user to specify a location.
+- `acg_power_lines` — added explicit ❌/✅ routing guidance distinguishing it from `acg_hits`. This prevents
+  Claude from fetching full global GeoJSON geometry when the user's question is about a specific city.
+- `acg_hits` — symmetric routing guidance added (mirrors `acg_power_lines` change above).
+- `ephemeris_solar_return` — `target_datetime` is now optional; defaults to `new Date().toISOString()` so
+  Claude can answer "What does my solar return look like?" for the current year without stalling for input.
+- `ephemeris_lunar_return` — same treatment; defaults to today so "what's my next lunar return?" resolves
+  in one call.
+- `electional_station_tracker` — `planets` parameter now accepts human-readable names (`mercury,venus,mars`)
+  in addition to numeric IDs. Names are mapped to IDs in the handler. Adds `USE THIS TOOL FOR:` examples
+  for "Mercury retrograde" queries to aid routing.
+- `venus_phase` — `date` is now optional (was incorrectly marked required despite the description
+  saying "Defaults to now"). Handler auto-fills today's date when omitted.
+
+---
+
+## [3.5.3] — 2026-04-10
+
+### Fixed
+- `ephemeris_chart_wheel` and `ephemeris_bi_wheel` tools now correctly advertise the
+  `style` values accepted by the backend (`light`, `dark`, `mono`). The previous enum
+  (`modern`, `classic`, `dark`) caused every non-dark chart request to fail with `400`.
+- SSE sessions are now fully isolated: each connection creates its own `BackendClient`
+  instance keyed to the connecting user's API key. Concurrent sessions no longer
+  overwrite each other's API key on the shared singleton, preventing cross-user
+  billing attribution errors.
+
+---
+
 ## [3.5.1] — 2026-03-31
 
 ### Changed

package/README.md

@@ -226,8 +226,8 @@ Generated by `npm run sync:readme` from `config/dev-allowlist.json` and the live
 
 - Allowlisted operations: **22**
 - Methods: `GET=4`, `POST=18`, `PUT=0`, `PATCH=0`, `DELETE=0`
-- Registered tools (`OPENEPHEMERIS_PROFILE=dev`): **48**
-- Typed tools: `auth_login`, `auth_logout`, `auth_status`, `chinese_bazi`, `dev_call`, `dev_list_allowed`, `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_overlay`, `ephemeris_planet_position`, `ephemeris_planetary_return`, `ephemeris_progressed_chart`, `ephemeris_relocation`, `ephemeris_retrograde_status`, `ephemeris_solar_return`, `ephemeris_synastry`, `ephemeris_transits`, `hd_opposition`, `hd_planetary_return`, `human_design_chart`, `human_design_composite`, `human_design_penta`, `vedic_chart`, `venus_eight_year_star`, `venus_elongations`, `venus_phase`, `venus_star_points`, `venus_star_points_conjunctions`, `venus_stations`
+- Registered tools (`OPENEPHEMERIS_PROFILE=dev`): **49**
+- Typed tools: `auth_login`, `auth_logout`, `auth_status`, `chinese_bazi`, `dev_call`, `dev_list_allowed`, `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`, `hd_opposition`, `hd_planetary_return`, `human_design_chart`, `human_design_composite`, `human_design_penta`, `vedic_chart`, `venus_eight_year_star`, `venus_elongations`, `venus_phase`, `venus_star_points`, `venus_star_points_conjunctions`, `venus_stations`
 - Generic tools: 
 
 ### Allowlist Families

package/config/dev-allowlist.json

@@ -104,8 +104,8 @@
       "path": "/visualization/chart-wheel"
     }
   ],
-  "last_generated_at": "2026-04-02T14:37:22.841Z",
-  "openapi_sha256": "fd75c2b6eae40884622067c1489e61a2d35b9cce9cd57943e989210a6728a197",
+  "last_generated_at": "2026-04-16T23:21:31.665Z",
+  "openapi_sha256": "2349bd8e3e36dad609b75cc61acb1722206990581085d986b0cdad79317296aa",
   "candidates_get": [
     {
       "method": "GET",

package/dist/backend/client.d.ts

@@ -65,3 +65,13 @@ export declare class BackendClient {
     getUserId(): string;
 }
 export declare const backendClient: BackendClient;
+/**
+ * Run `fn` in an async context where `getActiveClient()` returns `client`.
+ * Used by the SSE server to scope each connection to its own BackendClient.
+ */
+export declare function runWithClient<T>(client: BackendClient, fn: () => T): T;
+/**
+ * Returns the per-session BackendClient when called inside `runWithClient`,
+ * otherwise falls back to the module-level singleton (stdio mode).
+ */
+export declare function getActiveClient(): BackendClient;

package/dist/backend/client.js

@@ -1,3 +1,4 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 import axios, { AxiosError } from "axios";
 import { CredentialManager } from "../auth/credentials.js";
 import { DeviceAuthFlow } from "../auth/device-auth.js";
@@ -352,7 +353,8 @@ export class BackendClient {
         return this.userId;
     }
 }
-// Singleton instance
+// Singleton instance — used by stdio server and as the fallback when no
+// session context is active.
 export const backendClient = new BackendClient({
     baseURL: process.env.OPENEPHEMERIS_BACKEND_URL ||
         process.env.ASTROMCP_BACKEND_URL ||
@@ -363,3 +365,24 @@ export const backendClient = new BackendClient({
     serviceKey: process.env.OPENEPHEMERIS_SERVICE_KEY || process.env.ASTROMCP_SERVICE_KEY || process.env.MERIDIAN_SERVICE_KEY,
     apiKey: process.env.OPENEPHEMERIS_API_KEY || process.env.ASTROMCP_API_KEY || process.env.MERIDIAN_API_KEY,
 });
+// ---------------------------------------------------------------------------
+// Per-session client context (SSE isolation)
+// ---------------------------------------------------------------------------
+// Each SSE connection creates its own BackendClient keyed to the user's API
+// key. AsyncLocalStorage propagates that client through the entire async call
+// chain of a tool invocation without touching the shared singleton.
+const _sessionClientStore = new AsyncLocalStorage();
+/**
+ * Run `fn` in an async context where `getActiveClient()` returns `client`.
+ * Used by the SSE server to scope each connection to its own BackendClient.
+ */
+export function runWithClient(client, fn) {
+    return _sessionClientStore.run(client, fn);
+}
+/**
+ * Returns the per-session BackendClient when called inside `runWithClient`,
+ * otherwise falls back to the module-level singleton (stdio mode).
+ */
+export function getActiveClient() {
+    return _sessionClientStore.getStore() ?? backendClient;
+}

package/dist/server-sse.js

@@ -21,7 +21,7 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { initTools, toolRegistry, formatToolResponse } from "./tools/index.js";
-import { backendClient } from "./backend/client.js";
+import { BackendClient, runWithClient } from "./backend/client.js";
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -61,6 +61,7 @@ async function validateApiKey(apiKey) {
     try {
         const resp = await axios.get(`${BACKEND_URL}/ephemeris/moon/phase`, {
             headers: { "X-API-Key": apiKey },
+            params: { datetime: new Date().toISOString() }, // required param per OpenAPI spec
             timeout: 5_000,
             validateStatus: () => true, // don't throw on any status
         });
@@ -153,6 +154,8 @@ async function main() {
     });
     // Track active transports by session ID
     const transports = new Map();
+    // Per-session BackendClient — each connection authenticates independently.
+    const sessionClients = new Map();
     // Health check
     app.get("/health", (_req, res) => {
         res.json({ ok: true, version, transport: "sse", sessions: transports.size });
@@ -208,12 +211,16 @@ async function main() {
             });
             return;
         }
-        // Inject the validated API key into the singleton BackendClient so all
-        // tool calls authenticate as this user and usage is metered correctly.
-        backendClient.setApiKey(apiKey);
         const transport = new SSEServerTransport("/message", res);
         const sessionId = transport.sessionId;
         transports.set(sessionId, transport);
+        // Create a per-session BackendClient so concurrent SSE connections
+        // don't overwrite each other's API key on the shared singleton.
+        const sessionClient = new BackendClient({
+            baseURL: BACKEND_URL,
+            apiKey,
+        });
+        sessionClients.set(sessionId, sessionClient);
         const server = createMcpServer();
         // Guard: prevent double-close from crashing the process
         let closed = false;
@@ -222,6 +229,7 @@ async function main() {
                 return;
             closed = true;
             transports.delete(sessionId);
+            sessionClients.delete(sessionId);
             try {
                 server.close().catch(() => { });
             }
@@ -243,6 +251,7 @@ async function main() {
     app.post("/message", async (req, res) => {
         const sessionId = req.query.sessionId;
         const transport = transports.get(sessionId);
+        const sessionClient = sessionClients.get(sessionId);
         if (!transport) {
             res.status(400).json({
                 error: "invalid_session",
@@ -250,7 +259,14 @@ async function main() {
             });
             return;
         }
-        await transport.handlePostMessage(req, res);
+        // Run handlePostMessage inside the session's client context so all tool
+        // handlers reach getActiveClient() and get this user's BackendClient.
+        if (sessionClient) {
+            await runWithClient(sessionClient, () => transport.handlePostMessage(req, res));
+        }
+        else {
+            await transport.handlePostMessage(req, res);
+        }
     });
     app.listen(PORT, "0.0.0.0", () => {
         console.log(`OpenEphemeris MCP SSE server v${version} listening on port ${PORT}`);

package/dist/tools/dev.js

@@ -1,5 +1,5 @@
 import { registerTool, validateRequired } from "./index.js";
-import { backendClient } from "../backend/client.js";
+import { getActiveClient } from "../backend/client.js";
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -171,7 +171,7 @@ registerTool({
         if (isVisualizationPath && !query.format) {
             query.format = "png";
         }
-        return await backendClient.request(method, pathname, {
+        return await getActiveClient().request(method, pathname, {
             params: query,
             data: body,
         });

package/dist/tools/specialized/acg.js

@@ -1,5 +1,5 @@
 import { registerTool, validateRequired } from "../index.js";
-import { backendClient } from "../../backend/client.js";
+import { getActiveClient } from "../../backend/client.js";
 const ACG_BODY_DESCRIPTION = "List of celestial bodies for line calculation. " +
     "E.g. ['Sun', 'Moon', 'Venus', 'Mars', 'Jupiter', 'Saturn']. " +
     "Aliases: 'NorthNode'/'Node'/'Rahu' → MeanNode, 'SouthNode'/'Ketu' → SouthNode. " +
@@ -11,6 +11,9 @@ registerTool({
         "Returns GeoJSON LineStrings tracing each planetary angle line around the globe. " +
         "These are the latitudinal lines where a planet was rising (AC), setting (DC), " +
         "culminating (MC), or anti-culminating (IC) at birth.\n\n" +
+        "❌  NOT FOR: 'Is [city] good for me?' or 'What planets affect me in Tokyo?' " +
+        "→ For a specific city/location analysis, use acg_hits instead (faster and more relevant).\n" +
+        "✅  USE FOR: Getting the full global GeoJSON line geometry for map rendering or bulk geographic analysis.\n\n" +
         "CREDIT COST: 10 credits per call.\n\n" +
         "EXAMPLE: Saturn and Jupiter power lines for a chart born 1990-04-15 in Chicago:\n" +
         "  birth_datetime='1990-04-15T14:30:00', birth_latitude=41.8781, birth_longitude=-87.6298,\n" +
@@ -68,7 +71,7 @@ registerTool({
             body.query_lon = args.query_longitude;
         if (args.radius_deg != null)
             body.radius_deg = args.radius_deg;
-        return await backendClient.post("/acg/power-lines", body);
+        return await getActiveClient().post("/acg/power-lines", body);
     },
 });
 // POST /acg/hits — OE-018
@@ -76,6 +79,9 @@ registerTool({
     name: "acg_hits",
     description: "Find all Astrocartography lines (power lines + aspect lines) passing near a specific location. " +
         "Returns features sorted by distance, making it easy to interpret planetary influences at a place.\n\n" +
+        "✅  USE THIS TOOL FOR: 'Is [city] good for me?', 'What planets affect me in Tokyo?', " +
+        "'What ACG lines run through Paris for my chart?', 'Which cities are under my Jupiter line?'\n" +
+        "❌  NOT FOR: Full global map geometry → use acg_power_lines for that instead.\n\n" +
         "CREDIT COST: 15 credits per call.\n\n" +
         "EXAMPLE: All ACG lines within 3° of Paris for a chart born 1990-04-15 in Chicago:\n" +
         "  birth_datetime='1990-04-15T14:30:00', birth_latitude=41.8781, birth_longitude=-87.6298,\n" +
@@ -138,6 +144,6 @@ registerTool({
         if (args.include_aspects != null) {
             body.options = { include_aspects: args.include_aspects };
         }
-        return await backendClient.post("/acg/hits", body);
+        return await getActiveClient().post("/acg/hits", body);
     },
 });

package/dist/tools/specialized/bazi.js

@@ -1,5 +1,5 @@
 import { registerTool } from "../index.js";
-import { backendClient } from "../../backend/client.js";
+import { getActiveClient } from "../../backend/client.js";
 registerTool({
     name: "chinese_bazi",
     description: "Calculate a Chinese Ba Zi (Four Pillars of Destiny) chart. Returns the Year, Month, Day, " +
@@ -62,6 +62,6 @@ registerTool({
         const body = { year, month, day };
         if (hour != null)
             body.hour = hour;
-        return await backendClient.request("POST", "/chinese/bazi", { data: body });
+        return await getActiveClient().request("POST", "/chinese/bazi", { data: body });
     },
 });

package/dist/tools/specialized/bi_wheel.js

@@ -1,5 +1,5 @@
 import { registerTool, validateRequired } from "../index.js";
-import { backendClient } from "../../backend/client.js";
+import { getActiveClient } from "../../backend/client.js";
 const DATETIME_DESC = "ISO 8601 datetime string, e.g. '1990-04-15T14:30:00' (local time at birth location). " +
     "Include timezone offset if known, e.g. '1990-04-15T14:30:00-05:00'.";
 const HOUSE_SYSTEM_MAP = {
@@ -31,8 +31,8 @@ registerTool({
             },
             style: {
                 type: "string",
-                enum: ["modern", "classic", "dark"],
-                description: "Aesthetic style of the chart. Defaults to 'modern'.",
+                enum: ["light", "dark", "mono"],
+                description: "Aesthetic style of the chart: 'light' (default, warm cream background), 'dark' (deep navy), or 'mono' (black-and-white print-ready).",
             }
         },
         required: ["datetime_a", "latitude_a", "longitude_a", "datetime_b", "latitude_b", "longitude_b"],
@@ -69,6 +69,6 @@ registerTool({
             body.configuration = { house_system: mappedCode };
         }
         const styleParam = args.style ? `&style=${args.style}` : "";
-        return await backendClient.post(`/visualization/bi-wheel?format=png&size=800${styleParam}`, body);
+        return await getActiveClient().post(`/visualization/bi-wheel?format=png&size=800${styleParam}`, body);
     },
 });

package/dist/tools/specialized/chart_wheel.js

@@ -1,5 +1,5 @@
 import { registerTool, validateRequired } from "../index.js";
-import { backendClient } from "../../backend/client.js";
+import { getActiveClient } from "../../backend/client.js";
 const DATETIME_DESC = "ISO 8601 datetime string, e.g. '1990-04-15T14:30:00' (local time at birth location). " +
     "Include timezone offset if known, e.g. '1990-04-15T14:30:00-05:00'.";
 const HOUSE_SYSTEM_MAP = {
@@ -39,8 +39,8 @@ registerTool({
             },
             style: {
                 type: "string",
-                enum: ["modern", "classic", "dark"],
-                description: "Aesthetic style of the chart. Defaults to 'modern'.",
+                enum: ["light", "dark", "mono"],
+                description: "Aesthetic style of the chart: 'light' (default, warm cream background), 'dark' (deep navy), or 'mono' (black-and-white print-ready).",
             }
         },
         required: ["datetime", "latitude", "longitude"],
@@ -66,6 +66,6 @@ registerTool({
             body.configuration = { house_system: mappedCode };
         }
         const styleParam = args.style ? `&style=${args.style}` : "";
-        return await backendClient.post(`/visualization/chart-wheel?format=png&size=800${styleParam}`, body);
+        return await getActiveClient().post(`/visualization/chart-wheel?format=png&size=800${styleParam}`, body);
     },
 });

package/dist/tools/specialized/comparative.js

@@ -1,5 +1,5 @@
 import { registerTool, validateRequired } from "../index.js";
-import { backendClient } from "../../backend/client.js";
+import { getActiveClient } from "../../backend/client.js";
 function buildSubject(name, datetime, lat, lon, timezone) {
     const subj = {
         name,
@@ -50,7 +50,7 @@ registerTool({
         const query = {};
         if (args.format)
             query.format = args.format;
-        return await backendClient.request("POST", "/comparative/composite", {
+        return await getActiveClient().request("POST", "/comparative/composite", {
             params: query,
             data: {
                 subjects: [
@@ -94,7 +94,7 @@ registerTool({
         const query = {};
         if (args.format)
             query.format = args.format;
-        return await backendClient.request("POST", "/comparative/composite/midpoint", {
+        return await getActiveClient().request("POST", "/comparative/composite/midpoint", {
             params: query,
             data: {
                 subjects: [
@@ -138,7 +138,7 @@ registerTool({
         const query = {};
         if (args.format)
             query.format = args.format;
-        return await backendClient.request("POST", "/comparative/overlay", {
+        return await getActiveClient().request("POST", "/comparative/overlay", {
             params: query,
             data: {
                 subjects: [
@@ -182,7 +182,7 @@ registerTool({
         const query = {};
         if (args.format)
             query.format = args.format;
-        return await backendClient.request("POST", "/comparative/natal-transits", {
+        return await getActiveClient().request("POST", "/comparative/natal-transits", {
             params: query,
             data: { subjects }
         });

package/dist/tools/specialized/eclipse.js

@@ -1,14 +1,20 @@
 import { registerTool, validateRequired, validateCoordinates } from "../index.js";
-import { backendClient } from "../../backend/client.js";
+import { getActiveClient } from "../../backend/client.js";
 registerTool({
     name: "ephemeris_next_eclipse",
-    description: "Find the next solar or lunar eclipse visible from a given location. " +
-        "Returns the eclipse type, date/time of maximum, magnitude, duration of totality (if any), " +
-        "and local contact times.\n\n" +
+    description: "Find the next solar or lunar eclipse. " +
+        "Returns the eclipse type, date/time of maximum, magnitude, and duration of totality (if any).\n\n" +
+        "📍 LOCATION OPTIONAL:\n" +
+        "  • WITH latitude+longitude → returns local contact times and visibility for that specific location.\n" +
+        "  • WITHOUT latitude+longitude → returns the next global eclipse of that type (no location needed).\n\n" +
+        "USE THIS TOOL FOR: 'When is the next solar eclipse?', 'When is the next total lunar eclipse?', " +
+        "'Will there be an eclipse visible from Tokyo?'\n\n" +
         "CREDIT COST: 1 credit per call.\n\n" +
-        "EXAMPLE: Find the next solar eclipse visible from New York:\n" +
+        "EXAMPLE: Next solar eclipse globally (no location needed):\n" +
+        "  eclipse_type='solar'\n\n" +
+        "EXAMPLE: Next solar eclipse visible from New York:\n" +
         "  eclipse_type='solar', latitude=40.7128, longitude=-74.006\n\n" +
-        "EXAMPLE: Find the next lunar eclipse from London:\n" +
+        "EXAMPLE: Next lunar eclipse from London:\n" +
         "  eclipse_type='lunar', latitude=51.5074, longitude=-0.1278",
     inputSchema: {
         type: "object",
@@ -16,35 +22,47 @@ registerTool({
             eclipse_type: {
                 type: "string",
                 enum: ["solar", "lunar", "any"],
-                description: "Eclipse type to search for. Use 'any' for whichever comes first.",
+                description: "Eclipse type to search for. Use 'any' for whichever comes first (solar or lunar).",
             },
             latitude: {
                 type: "number",
-                description: "Observer latitude in decimal degrees (required). Returns local visibility and contact times.",
+                description: "Observer latitude in decimal degrees (optional). When provided with longitude, returns local contact times and visibility.",
             },
             longitude: {
                 type: "number",
-                description: "Observer longitude in decimal degrees (required).",
+                description: "Observer longitude in decimal degrees (optional, pair with latitude).",
             },
             after_date: {
                 type: "string",
                 description: "ISO 8601 date to search after (e.g. '2026-01-01'). Defaults to today if omitted.",
             },
         },
-        required: ["eclipse_type", "latitude", "longitude"],
+        required: ["eclipse_type"],
         additionalProperties: false,
     },
     handler: async (args) => {
-        validateRequired(args, ["eclipse_type", "latitude", "longitude"]);
+        validateRequired(args, ["eclipse_type"]);
         validateCoordinates(args, "latitude", "longitude");
-        const params = {
-            lat: args.latitude,
-            lon: args.longitude,
-        };
-        if (args.after_date)
-            params.date = args.after_date;
-        if (args.eclipse_type && args.eclipse_type !== "any")
-            params.type = args.eclipse_type;
-        return await backendClient.request("GET", "/eclipse/next-visible", { params, timeoutMs: 60_000 });
+        const hasLocation = args.latitude != null && args.longitude != null;
+        if (hasLocation) {
+            // Local visibility query
+            const params = {
+                lat: args.latitude,
+                lon: args.longitude,
+            };
+            if (args.after_date)
+                params.date = args.after_date;
+            if (args.eclipse_type && args.eclipse_type !== "any")
+                params.type = args.eclipse_type;
+            return await getActiveClient().request("GET", "/eclipse/next-visible", { params, timeoutMs: 60_000 });
+        }
+        else {
+            // Global query — route to global endpoint
+            const params = {};
+            if (args.after_date)
+                params.date = args.after_date;
+            const endpoint = args.eclipse_type === "lunar" ? "/eclipse/lunar/global" : "/eclipse/solar/global";
+            return await getActiveClient().request("GET", endpoint, { params, timeoutMs: 60_000 });
+        }
     },
 });

package/dist/tools/specialized/electional.js

@@ -1,5 +1,5 @@
 import { registerTool, validateRequired } from "../index.js";
-import { backendClient } from "../../backend/client.js";
+import { getActiveClient } from "../../backend/client.js";
 // All electional endpoints are GET endpoints with query params.
 // GET /electional/find-window — already existed, keeping it
 registerTool({
@@ -74,7 +74,7 @@ registerTool({
             query.avoid_voc = args.avoid_voc;
         if (args.format)
             query.format = args.format;
-        return await backendClient.request("GET", "/electional/find-window", {
+        return await getActiveClient().request("GET", "/electional/find-window", {
             data: {},
             params: query,
         });
@@ -111,27 +111,30 @@ registerTool({
             query.date = args.date;
         if (args.format)
             query.format = args.format;
-        return await backendClient.request("GET", "/electional/moment-analysis", {
+        return await getActiveClient().request("GET", "/electional/moment-analysis", {
             data: {},
             params: query,
         });
     },
 });
-// GET /electional/station-tracker
 registerTool({
     name: "electional_station_tracker",
     description: "Find all upcoming retrograde and direct stations for planets in a date range. " +
-        "Returns exact station times, longitudes, and signs. Essential for timing around " +
-        "Mercury retrograde, Venus retrograde, etc.\n\n" +
+        "Returns exact station times, longitudes, and signs.\n\n" +
+        "USE THIS TOOL FOR: 'When does Mercury go retrograde?', 'Is Venus retrograde this year?', " +
+        "'What planets station this month?', 'When does Mars go direct?'\n\n" +
+        "All required fields have smart defaults (searches the next 90 days from today).\n\n" +
         "CREDIT COST: 3 credits per call.\n\n" +
-        "EXAMPLE: Stations in the next 3 months:\n" +
-        "  start_date='2026-03-01', end_date='2026-06-01'",
+        "EXAMPLE: Mercury and Venus stations in the next 3 months (all defaults):\n" +
+        "  (no args required, will auto-scan next 90 days for all inner planets)\n\n" +
+        "EXAMPLE: Outer planet stations in 2026:\n" +
+        "  start_date='2026-01-01', end_date='2026-12-31', planets='jupiter,saturn,uranus,neptune,pluto'",
     inputSchema: {
         type: "object",
         properties: {
             start_date: {
                 type: "string",
-                description: "Start date (ISO 8601). Defaults to now.",
+                description: "Start date (ISO 8601). Defaults to today.",
             },
             end_date: {
                 type: "string",
@@ -139,7 +142,9 @@ registerTool({
             },
             planets: {
                 type: "string",
-                description: "Comma-separated planet IDs (e.g., '2,3,4'). Defaults to Mercury-Saturn.",
+                description: "Comma-separated planet names to track. " +
+                    "E.g. 'mercury,venus,mars' or 'jupiter,saturn,uranus,neptune,pluto'. " +
+                    "Defaults to Mercury through Saturn (inner + classical planets).",
             },
             format: {
                 type: "string",
@@ -152,15 +157,29 @@ registerTool({
     },
     handler: async (args) => {
         const query = {};
+        // Map human-readable planet names to IDs if needed
+        const PLANET_NAME_MAP = {
+            mercury: "2", venus: "3", mars: "4",
+            jupiter: "5", saturn: "6", uranus: "7",
+            neptune: "8", pluto: "9",
+        };
         if (args.start_date)
             query.start_date = args.start_date;
         if (args.end_date)
             query.end_date = args.end_date;
-        if (args.planets)
-            query.planets = args.planets;
+        if (args.planets) {
+            // Accept both names ('mercury,venus') and numeric IDs ('2,3')
+            query.planets = args.planets
+                .split(",")
+                .map((p) => {
+                const name = p.trim().toLowerCase();
+                return PLANET_NAME_MAP[name] ?? p.trim();
+            })
+                .join(",");
+        }
         if (args.format)
             query.format = args.format;
-        return await backendClient.request("GET", "/electional/station-tracker", {
+        return await getActiveClient().request("GET", "/electional/station-tracker", {
             data: {},
             params: query,
         });
@@ -202,7 +221,7 @@ registerTool({
             query.max_orb = args.max_orb;
         if (args.aspects)
             query.aspects = args.aspects;
-        return await backendClient.request("GET", "/electional/aspect-search", {
+        return await getActiveClient().request("GET", "/electional/aspect-search", {
             data: {},
             params: query,
         });

package/dist/tools/specialized/ephemeris_core.js

@@ -1,5 +1,5 @@
 import { registerTool, validateRequired } from "../index.js";
-import { backendClient } from "../../backend/client.js";
+import { getActiveClient } from "../../backend/client.js";
 // POST /ephemeris/planet-position — OE-016
 registerTool({
     name: "ephemeris_planet_position",
@@ -44,7 +44,7 @@ registerTool({
             body.latitude = args.latitude;
         if (args.longitude != null)
             body.longitude = args.longitude;
-        return await backendClient.post("/ephemeris/planet-position", body);
+        return await getActiveClient().post("/ephemeris/planet-position", body);
     },
 });
 // POST /ephemeris/house-cusps — OE-017
@@ -89,6 +89,6 @@ registerTool({
         };
         if (args.house_systems)
             body.house_systems = args.house_systems;
-        return await backendClient.post("/ephemeris/house-cusps", body);
+        return await getActiveClient().post("/ephemeris/house-cusps", body);
     },
 });

package/dist/tools/specialized/ephemeris_extended.js

@@ -1,5 +1,5 @@
 import { registerTool, validateRequired } from "../index.js";
-import { backendClient } from "../../backend/client.js";
+import { getActiveClient } from "../../backend/client.js";
 function buildSubject(name, datetime, lat, lon) {
     return {
         name,
@@ -47,7 +47,7 @@ registerTool({
         const items = args.subjects.map((s) => ({
             subject: buildSubject(s.name, s.datetime, s.latitude, s.longitude),
         }));
-        return await backendClient.post("/ephemeris/natal/batch", { items });
+        return await getActiveClient().post("/ephemeris/natal/batch", { items });
     },
 });
 // POST /ephemeris/dignities
@@ -66,7 +66,7 @@ registerTool({
     },
     handler: async (args) => {
         validateRequired(args, ["datetime"]);
-        return await backendClient.post("/ephemeris/dignities", {
+        return await getActiveClient().post("/ephemeris/dignities", {
             date_time: { iso: args.datetime },
         });
     },
@@ -93,7 +93,7 @@ registerTool({
         };
         if (args.planet_id != null)
             body.planet_id = args.planet_id;
-        return await backendClient.post("/ephemeris/retrograde-status", body);
+        return await getActiveClient().post("/ephemeris/retrograde-status", body);
     },
 });
 // POST /ephemeris/midpoints
@@ -114,7 +114,7 @@ registerTool({
     },
     handler: async (args) => {
         validateRequired(args, ["datetime", "latitude", "longitude"]);
-        return await backendClient.post("/ephemeris/midpoints", {
+        return await getActiveClient().post("/ephemeris/midpoints", {
             date_time: { iso: args.datetime },
             latitude: args.latitude,
             longitude: args.longitude,
@@ -150,7 +150,7 @@ registerTool({
             body.star_names = args.star_names;
         if (args.orb != null)
             body.orb = args.orb;
-        return await backendClient.post("/ephemeris/fixed-stars", body);
+        return await getActiveClient().post("/ephemeris/fixed-stars", body);
     },
 });
 // POST /ephemeris/hermetic-lots
@@ -171,7 +171,7 @@ registerTool({
     },
     handler: async (args) => {
         validateRequired(args, ["datetime", "latitude", "longitude"]);
-        return await backendClient.post("/ephemeris/hermetic-lots", {
+        return await getActiveClient().post("/ephemeris/hermetic-lots", {
             date_time: { iso: args.datetime },
             latitude: args.latitude,
             longitude: args.longitude,
@@ -196,7 +196,7 @@ registerTool({
     },
     handler: async (args) => {
         validateRequired(args, ["datetime", "latitude", "longitude"]);
-        return await backendClient.post("/ephemeris/angles-points", {
+        return await getActiveClient().post("/ephemeris/angles-points", {
             date_time: { iso: args.datetime },
             latitude: args.latitude,
             longitude: args.longitude,
@@ -229,6 +229,6 @@ registerTool({
         };
         if (args.max_orb != null)
             body.max_orb = args.max_orb;
-        return await backendClient.post("/ephemeris/aspect-check", body);
+        return await getActiveClient().post("/ephemeris/aspect-check", body);
     },
 });

package/dist/tools/specialized/hd_cycles.js

@@ -1,5 +1,5 @@
 import { registerTool, validateRequired } from "../index.js";
-import { backendClient } from "../../backend/client.js";
+import { getActiveClient } from "../../backend/client.js";
 /**
  * Ensure a datetime string has a timezone offset for Go's time.Time parsing.
  */
@@ -51,7 +51,7 @@ registerTool({
     },
     handler: async (args) => {
         validateRequired(args, ["planet", "datetime", "return_year"]);
-        return await backendClient.request("POST", "/human-design/cycles/return", {
+        return await getActiveClient().request("POST", "/human-design/cycles/return", {
             data: {
                 planet: args.planet,
                 birth_datetime_utc: ensureTimezone(args.datetime),
@@ -101,7 +101,7 @@ registerTool({
     },
     handler: async (args) => {
         validateRequired(args, ["planet", "datetime", "target_year"]);
-        return await backendClient.request("POST", "/human-design/cycles/opposition", {
+        return await getActiveClient().request("POST", "/human-design/cycles/opposition", {
             data: {
                 planet: args.planet,
                 birth_datetime_utc: ensureTimezone(args.datetime),

package/dist/tools/specialized/hd_group.js

@@ -1,5 +1,5 @@
 import { registerTool, validateRequired } from "../index.js";
-import { backendClient } from "../../backend/client.js";
+import { getActiveClient } from "../../backend/client.js";
 // POST /human-design/composite — OE-027
 registerTool({
     name: "human_design_composite",
@@ -40,7 +40,7 @@ registerTool({
         };
         if (args.format)
             body.format = args.format;
-        return await backendClient.post("/human-design/composite", body);
+        return await getActiveClient().post("/human-design/composite", body);
     },
 });
 // POST /human-design/penta — OE-027
@@ -102,6 +102,6 @@ registerTool({
         };
         if (args.format)
             body.format = args.format;
-        return await backendClient.post("/human-design/penta", body);
+        return await getActiveClient().post("/human-design/penta", body);
     },
 });

package/dist/tools/specialized/human_design.js

@@ -1,5 +1,5 @@
 import { registerTool, validateRequired } from "../index.js";
-import { backendClient } from "../../backend/client.js";
+import { getActiveClient } from "../../backend/client.js";
 /**
  * Ensure a datetime string has a timezone offset for Go's time.Time parsing.
  * Go's encoding/json only accepts RFC 3339 (must have Z or +HH:MM offset).
@@ -61,7 +61,7 @@ registerTool({
         const query = {};
         if (args.format)
             query.format = args.format;
-        return await backendClient.request("POST", "/human-design/chart", {
+        return await getActiveClient().request("POST", "/human-design/chart", {
             data: body,
             params: query,
         });

package/dist/tools/specialized/moon.js

@@ -1,10 +1,13 @@
 import { registerTool, validateCoordinates } from "../index.js";
-import { backendClient } from "../../backend/client.js";
+import { getActiveClient } from "../../backend/client.js";
 registerTool({
     name: "ephemeris_moon_phase",
-    description: "Get the current Moon phase and void-of-course status. Returns the Moon's sign, phase name " +
-        "(New, Waxing Crescent, First Quarter, Waxing Gibbous, Full, Waning Gibbous, Last Quarter, " +
-        "Waning Crescent), exact phase angle, illumination percentage, and the next void-of-course period.\n\n" +
+    description: "Get the Moon's current phase angle, illumination, and void-of-course status AT a specific " +
+        "point in time. Returns phase name (New, Waxing Crescent, First Quarter, etc.), exact angle, " +
+        "illumination %, and next void-of-course period.\n\n" +
+        "⚠️  THIS TOOL ANSWERS: 'What phase is the moon in right now (or at a given datetime)?'\n" +
+        "❌  THIS TOOL DOES NOT ANSWER: 'When is the next new moon / full moon?'\n" +
+        "→   For upcoming phase DATES use ephemeris_next_lunar_phase instead.\n\n" +
         "CREDIT COST: 1 credit per call.\n\n" +
         "If no datetime is provided, returns the current (live) moon phase.\n\n" +
         "EXAMPLE: Get moon phase for a specific date/time:\n" +
@@ -40,8 +43,8 @@ registerTool({
         if (args.longitude != null)
             params.longitude = args.longitude;
         const [phase, voc] = await Promise.allSettled([
-            backendClient.request("GET", "/ephemeris/moon/phase", { params }),
-            backendClient.request("GET", "/ephemeris/moon/void-of-course", { params }),
+            getActiveClient().request("GET", "/ephemeris/moon/phase", { params }),
+            getActiveClient().request("GET", "/ephemeris/moon/void-of-course", { params }),
         ]);
         return {
             phase: phase.status === "fulfilled" ? phase.value : { error: phase.reason?.message },
@@ -49,3 +52,89 @@ registerTool({
         };
     },
 });
+registerTool({
+    name: "ephemeris_next_lunar_phase",
+    description: "Find the next occurrence of a specific Moon phase after a given date. " +
+        "Returns the exact UTC datetime, zodiac sign, and degree.\n\n" +
+        "✅  USE THIS TOOL FOR: 'When is the next new moon?', 'When is the next full moon?', " +
+        "'What date is the next quarter moon?', or any question about UPCOMING phase dates.\n\n" +
+        "CREDIT COST: 1 credit per call.\n\n" +
+        "EXAMPLE: Find the next new moon:\n" +
+        "  phase='new_moon'\n\n" +
+        "EXAMPLE: Find the next full moon after a specific date:\n" +
+        "  phase='full_moon', after_date='2026-06-01'\n\n" +
+        "EXAMPLE: Find the next 3 full moons:\n" +
+        "  phase='full_moon', count=3",
+    inputSchema: {
+        type: "object",
+        properties: {
+            phase: {
+                type: "string",
+                enum: ["new_moon", "full_moon", "first_quarter", "last_quarter"],
+                description: "The lunar phase to find. " +
+                    "'new_moon' = conjunction (0° Sun-Moon, start of cycle). " +
+                    "'full_moon' = opposition (180°). " +
+                    "'first_quarter' = 90° waxing. " +
+                    "'last_quarter' = 270° waning.",
+            },
+            after_date: {
+                type: "string",
+                description: "ISO 8601 date to search from (e.g. '2026-06-01'). Defaults to today (UTC) if omitted.",
+            },
+            count: {
+                type: "integer",
+                description: "Number of upcoming occurrences to return (1-12). Default 1.",
+            },
+        },
+        required: ["phase"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        // Map our clean enum to display names the calendar API returns
+        const phaseNameMap = {
+            new_moon: "New Moon",
+            full_moon: "Full Moon",
+            first_quarter: "First Quarter",
+            last_quarter: "Last Quarter",
+        };
+        const phaseLabel = phaseNameMap[args.phase] ?? args.phase;
+        const count = Math.max(1, Math.min(12, args.count ?? 1));
+        // Build a search window wide enough to capture `count` occurrences.
+        // Lunar cycle is ~29.5 days, so count * 35 days guarantees coverage.
+        const startDate = args.after_date
+            ? args.after_date.substring(0, 10)
+            : new Date().toISOString().substring(0, 10);
+        const endMs = new Date(startDate + "T00:00:00Z").getTime() + count * 35 * 24 * 60 * 60 * 1000;
+        const endDate = new Date(endMs).toISOString().substring(0, 10);
+        const result = await getActiveClient().request("GET", "/calendar/astrology/moon-phases", {
+            params: { start_date: startDate, end_date: endDate },
+        });
+        // Normalise response shape — API may return array, or { phases: [...] }, or { data: [...] }
+        const allPhases = Array.isArray(result)
+            ? result
+            : result?.phases ?? result?.data ?? result?.events ?? [];
+        const matching = allPhases
+            .filter((p) => {
+            const name = (p.phase_name ?? p.name ?? p.phase ?? "").toLowerCase();
+            return (name === phaseLabel.toLowerCase() ||
+                name === args.phase.replace("_", " ").toLowerCase());
+        })
+            .slice(0, count);
+        if (matching.length === 0) {
+            // Return full calendar as fallback so the LLM can inspect it
+            return {
+                requested_phase: phaseLabel,
+                search_window: { start_date: startDate, end_date: endDate },
+                result_count: 0,
+                note: "No matching phase found in window. Full calendar returned for inspection.",
+                full_calendar: allPhases,
+            };
+        }
+        return {
+            requested_phase: phaseLabel,
+            after_date: startDate,
+            results: matching,
+            result_count: matching.length,
+        };
+    },
+});

package/dist/tools/specialized/natal.js

@@ -1,5 +1,5 @@
 import { registerTool, validateRequired } from "../index.js";
-import { backendClient } from "../../backend/client.js";
+import { getActiveClient } from "../../backend/client.js";
 const DATETIME_DESC = "ISO 8601 datetime string, e.g. '1990-04-15T14:30:00' (local time at birth location). " +
     "Include timezone offset if known, e.g. '1990-04-15T14:30:00-05:00'.";
 /** Map human-readable house system names to Swiss Ephemeris single-letter codes */
@@ -91,7 +91,7 @@ registerTool({
         const query = {};
         if (args.format)
             query.format = args.format;
-        return await backendClient.request("POST", "/ephemeris/natal-chart", {
+        return await getActiveClient().request("POST", "/ephemeris/natal-chart", {
             data: body,
             params: query,
         });

package/dist/tools/specialized/progressed.js

@@ -1,5 +1,5 @@
 import { registerTool, validateRequired } from "../index.js";
-import { backendClient } from "../../backend/client.js";
+import { getActiveClient } from "../../backend/client.js";
 registerTool({
     name: "ephemeris_progressed_chart",
     description: "Calculate a Secondary Progressed (or Solar Arc / Tertiary) chart. " +
@@ -60,6 +60,6 @@ registerTool({
         if (args.include_aspects != null) {
             body.options = { include_aspects: args.include_aspects };
         }
-        return await backendClient.post("/ephemeris/progressed", body);
+        return await getActiveClient().post("/ephemeris/progressed", body);
     },
 });

package/dist/tools/specialized/relocation.js

@@ -1,5 +1,5 @@
 import { registerTool, validateRequired } from "../index.js";
-import { backendClient } from "../../backend/client.js";
+import { getActiveClient } from "../../backend/client.js";
 registerTool({
     name: "ephemeris_relocation",
     description: "Calculate a relocation chart — the same natal planetary positions re-cast for a different " +
@@ -67,7 +67,7 @@ registerTool({
         const query = {};
         if (args.format)
             query.format = args.format;
-        return await backendClient.request("POST", "/ephemeris/relocation", {
+        return await getActiveClient().request("POST", "/ephemeris/relocation", {
             data: body,
             params: query,
         });

package/dist/tools/specialized/returns.js

@@ -1,23 +1,28 @@
 import { registerTool, validateRequired } from "../index.js";
-import { backendClient } from "../../backend/client.js";
+import { getActiveClient } from "../../backend/client.js";
 // POST /predictive/returns/solar
 registerTool({
     name: "ephemeris_solar_return",
-    description: "Calculate the exact Solar Return date/time — when the Sun returns to its natal ecliptic longitude. " +
-        "Used to cast the Solar Return chart for the year ahead.\n\n" +
+    description: "Calculate the exact Solar Return date/time — when the Sun returns to its natal ecliptic longitude " +
+        "(happens once per year near the birthday). Returns the Solar Return chart for the year ahead.\n\n" +
         "CREDIT COST: 5 credits per call.\n\n" +
-        "EXAMPLE: Solar return for someone born 1985-06-21 near their 2026 birthday:\n" +
-        "  birth_datetime='1985-06-21T14:00:00', target_datetime='2026-06-01'",
+        "TARGET DATE: Provide target_datetime near the desired birthday year. " +
+        "If omitted, defaults to the current year's solar return.\n\n" +
+        "EXAMPLE: Solar return for someone born 1985-06-21 (current year):\n" +
+        "  birth_datetime='1985-06-21T14:00:00Z'\n\n" +
+        "EXAMPLE: Solar return for 2027 specifically:\n" +
+        "  birth_datetime='1985-06-21T14:00:00Z', target_datetime='2027-01-01T00:00:00Z'",
     inputSchema: {
         type: "object",
         properties: {
             birth_datetime: {
                 type: "string",
-                description: "ISO 8601 birth date/time. MUST include offset or Z (e.g. '1985-06-21T14:00:00-05:00').",
+                description: "ISO 8601 birth date/time. Include offset or Z (e.g. '1985-06-21T14:00:00-05:00').",
             },
             target_datetime: {
                 type: "string",
-                description: "Date/time near which to find the Solar Return (ISO 8601). MUST include offset or Z. Required.",
+                description: "Date/time near which to find the Solar Return (ISO 8601 with offset or Z). " +
+                    "Defaults to approximately 1 year from now if omitted.",
             },
             birth_latitude: {
                 type: "number",
@@ -29,21 +34,23 @@ registerTool({
             },
             return_latitude: {
                 type: "number",
-                description: "Location latitude for the return chart (optional).",
+                description: "Location latitude for the return chart (optional, if different from birth location).",
             },
             return_longitude: {
                 type: "number",
                 description: "Location longitude for the return chart (optional).",
             },
         },
-        required: ["birth_datetime", "target_datetime"],
+        required: ["birth_datetime"],
         additionalProperties: false,
     },
     handler: async (args) => {
-        validateRequired(args, ["birth_datetime", "target_datetime"]);
+        validateRequired(args, ["birth_datetime"]);
+        // Default target to current year if not provided
+        const targetDt = args.target_datetime ?? new Date().toISOString();
         const body = {
             birth_datetime: { iso: args.birth_datetime },
-            target_datetime: { iso: args.target_datetime },
+            target_datetime: { iso: targetDt },
         };
         if (args.birth_latitude != null && args.birth_longitude != null) {
             body.location = {
@@ -57,7 +64,7 @@ registerTool({
                 longitude: { decimal: args.return_longitude },
             };
         }
-        return await backendClient.post("/predictive/returns/solar", body);
+        return await getActiveClient().post("/predictive/returns/solar", body);
     },
 });
 // POST /predictive/returns/lunar
@@ -66,18 +73,23 @@ registerTool({
     description: "Calculate the exact Lunar Return date/time — when the Moon returns to its natal ecliptic longitude (~every 27.3 days). " +
         "Used to cast the monthly Lunar Return chart.\n\n" +
         "CREDIT COST: 5 credits per call.\n\n" +
-        "EXAMPLE: Next lunar return after 2026-03-15 for someone born 1990-04-15:\n" +
-        "  birth_datetime='1990-04-15T14:30:00', target_datetime='2026-03-15'",
+        "TARGET DATE: Provide target_datetime near the month you want. " +
+        "If omitted, defaults to the next upcoming lunar return from today.\n\n" +
+        "EXAMPLE: Next lunar return after today for someone born 1990-04-15:\n" +
+        "  birth_datetime='1990-04-15T14:30:00Z'\n\n" +
+        "EXAMPLE: Lunar return nearest March 2026:\n" +
+        "  birth_datetime='1990-04-15T14:30:00Z', target_datetime='2026-03-15T00:00:00Z'",
     inputSchema: {
         type: "object",
         properties: {
             birth_datetime: {
                 type: "string",
-                description: "ISO 8601 birth date/time. MUST include offset or Z.",
+                description: "ISO 8601 birth date/time. Include offset or Z.",
             },
             target_datetime: {
                 type: "string",
-                description: "Date/time near which to find the Lunar Return (ISO 8601). MUST include offset or Z. Required.",
+                description: "Date/time near which to find the Lunar Return (ISO 8601 with offset or Z). " +
+                    "Defaults to today if omitted (finds next return).",
             },
             birth_latitude: {
                 type: "number",
@@ -88,14 +100,15 @@ registerTool({
                 description: "Birth longitude in decimal degrees (optional).",
             },
         },
-        required: ["birth_datetime", "target_datetime"],
+        required: ["birth_datetime"],
         additionalProperties: false,
     },
     handler: async (args) => {
-        validateRequired(args, ["birth_datetime", "target_datetime"]);
+        validateRequired(args, ["birth_datetime"]);
+        const targetDt = args.target_datetime ?? new Date().toISOString();
         const body = {
             birth_datetime: { iso: args.birth_datetime },
-            target_datetime: { iso: args.target_datetime },
+            target_datetime: { iso: targetDt },
         };
         if (args.birth_latitude != null && args.birth_longitude != null) {
             body.location = {
@@ -103,7 +116,7 @@ registerTool({
                 longitude: { decimal: args.birth_longitude },
             };
         }
-        return await backendClient.post("/predictive/returns/lunar", body);
+        return await getActiveClient().post("/predictive/returns/lunar", body);
     },
 });
 // POST /predictive/returns (generic planetary return)
@@ -138,7 +151,7 @@ registerTool({
     },
     handler: async (args) => {
         validateRequired(args, ["body", "birth_datetime", "target_datetime"]);
-        return await backendClient.post("/predictive/returns", {
+        return await getActiveClient().post("/predictive/returns", {
             body: args.body,
             birth_datetime: { iso: args.birth_datetime },
             target_datetime: { iso: args.target_datetime },

package/dist/tools/specialized/synastry.js

@@ -1,5 +1,5 @@
 import { registerTool, validateRequired } from "../index.js";
-import { backendClient } from "../../backend/client.js";
+import { getActiveClient } from "../../backend/client.js";
 registerTool({
     name: "ephemeris_synastry",
     description: "Calculate a synastry chart comparing two people's natal charts. Returns inter-aspects " +
@@ -63,7 +63,7 @@ registerTool({
         const query = {};
         if (args.format)
             query.format = args.format;
-        return await backendClient.request("POST", "/comparative/synastry", {
+        return await getActiveClient().request("POST", "/comparative/synastry", {
             data: body,
             params: query,
         });

package/dist/tools/specialized/transits.js

@@ -1,5 +1,5 @@
 import { registerTool, validateRequired } from "../index.js";
-import { backendClient } from "../../backend/client.js";
+import { getActiveClient } from "../../backend/client.js";
 registerTool({
     name: "ephemeris_transits",
     description: "Search for astrological transit events affecting a natal chart over a date range. " +
@@ -76,7 +76,7 @@ registerTool({
                 },
             },
         };
-        const natalResult = await backendClient.post("/ephemeris/natal-chart", natalBody);
+        const natalResult = await getActiveClient().post("/ephemeris/natal-chart", natalBody);
         // Extract ecliptic longitudes from natal chart planets
         const targetDegrees = [];
         const natalPositionMap = {};
@@ -141,7 +141,7 @@ registerTool({
             // Also include aspect metadata for labeling in results
             transitBody.search_criteria = { aspect_angle: args.aspect_angle };
         }
-        const transitResult = await backendClient.request("POST", "/predictive/transits/search", { data: transitBody });
+        const transitResult = await getActiveClient().request("POST", "/predictive/transits/search", { data: transitBody });
         // Return combined context so the LLM knows what natal positions were targeted
         return {
             natal_positions: natalPositionMap,

package/dist/tools/specialized/vedic.js

@@ -1,5 +1,5 @@
 import { registerTool, validateRequired, validateCoordinates } from "../index.js";
-import { backendClient } from "../../backend/client.js";
+import { getActiveClient } from "../../backend/client.js";
 registerTool({
     name: "vedic_chart",
     description: "Calculate a Vedic (Jyotish) natal chart with sidereal positions. Returns planet placements " +
@@ -43,6 +43,6 @@ registerTool({
         };
         if (args.ayanamsa)
             body.ayanamsa = args.ayanamsa;
-        return await backendClient.request("POST", "/vedic/chart", { data: body });
+        return await getActiveClient().request("POST", "/vedic/chart", { data: body });
     },
 });

package/dist/tools/specialized/venus_star_points.js

@@ -1,5 +1,5 @@
 import { registerTool, validateRequired } from "../index.js";
-import { backendClient } from "../../backend/client.js";
+import { getActiveClient } from "../../backend/client.js";
 function buildSubject(datetime, lat, lon) {
     return {
         name: "Subject",
@@ -34,7 +34,7 @@ registerTool({
         const query = {};
         if (args.format)
             query.format = args.format;
-        return await backendClient.request("POST", "/ephemeris/venus-star-points", {
+        return await getActiveClient().request("POST", "/ephemeris/venus-star-points", {
             data: { subject: buildSubject(args.datetime, args.latitude, args.longitude) },
             params: query,
         });
@@ -63,7 +63,7 @@ registerTool({
         const query = {};
         if (args.format)
             query.format = args.format;
-        return await backendClient.request("POST", "/ephemeris/venus-star-points/conjunctions", {
+        return await getActiveClient().request("POST", "/ephemeris/venus-star-points/conjunctions", {
             data: { start_date: args.start_date, end_date: args.end_date },
             params: query,
         });
@@ -92,7 +92,7 @@ registerTool({
         const query = {};
         if (args.format)
             query.format = args.format;
-        return await backendClient.request("POST", "/ephemeris/venus-star-points/eight-year-star", {
+        return await getActiveClient().request("POST", "/ephemeris/venus-star-points/eight-year-star", {
             data: { date: args.date },
             params: query,
         });
@@ -104,24 +104,25 @@ registerTool({
     description: "Get the current Venus phase — morning star, evening star, or combust. Returns Venus " +
         "longitude, Sun longitude, elongation, retrograde/cazimi status.\n\n" +
         "CREDIT COST: 1 credit per call.\n\n" +
-        "EXAMPLE: Venus phase right now:\n" +
+        "EXAMPLE: Venus phase right now (omit date):\n" +
+        "  (no args required)\n\n" +
+        "EXAMPLE: Venus phase on a specific date:\n" +
         "  date='2026-03-20'",
     inputSchema: {
         type: "object",
         properties: {
-            date: { type: "string", description: "Date to check (ISO 8601). Defaults to now." },
+            date: { type: "string", description: "Date to check (ISO 8601). Omit for today's phase." },
             format: { type: "string", enum: ["json", "llm"], description: "Output format." },
         },
-        required: ["date"],
+        required: [],
         additionalProperties: false,
     },
     handler: async (args) => {
-        validateRequired(args, ["date"]);
         const query = {};
         if (args.format)
             query.format = args.format;
-        return await backendClient.request("POST", "/ephemeris/venus-star-points/phase", {
-            data: { date: args.date },
+        return await getActiveClient().request("POST", "/ephemeris/venus-star-points/phase", {
+            data: { date: args.date ?? new Date().toISOString().split("T")[0] },
             params: query,
         });
     },
@@ -147,7 +148,7 @@ registerTool({
         const query = {};
         if (args.format)
             query.format = args.format;
-        return await backendClient.request("POST", "/ephemeris/venus-star-points/elongations", {
+        return await getActiveClient().request("POST", "/ephemeris/venus-star-points/elongations", {
             data: { start_date: args.start_date, end_date: args.end_date },
             params: query,
         });
@@ -176,7 +177,7 @@ registerTool({
         const query = {};
         if (args.format)
             query.format = args.format;
-        return await backendClient.request("POST", "/ephemeris/venus-star-points/stations", {
+        return await getActiveClient().request("POST", "/ephemeris/venus-star-points/stations", {
             data: {
                 start_date: args.start_date,
                 end_date: args.end_date || "",

package/package.json

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