@openephemeris/mcp-server 3.5.3 → 3.6.0

package/CHANGELOG.md

@@ -7,6 +7,34 @@ 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

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-03T20:52:05.270Z",
-  "openapi_sha256": "1203c3d6fd62c4af1b04ad983f9495a27f1799a13fcfd8aedc5189d118d5279a",
+  "last_generated_at": "2026-04-16T23:21:31.665Z",
+  "openapi_sha256": "2349bd8e3e36dad609b75cc61acb1722206990581085d986b0cdad79317296aa",
   "candidates_get": [
     {
       "method": "GET",

package/dist/server-sse.js

@@ -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
         });

package/dist/tools/specialized/acg.js

@@ -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" +
@@ -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" +

package/dist/tools/specialized/eclipse.js

@@ -2,13 +2,19 @@ import { registerTool, validateRequired, validateCoordinates } from "../index.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 getActiveClient().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

@@ -117,21 +117,24 @@ registerTool({
         });
     },
 });
-// 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,12 +157,26 @@ 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 getActiveClient().request("GET", "/electional/station-tracker", {

package/dist/tools/specialized/moon.js

@@ -2,9 +2,12 @@ import { registerTool, validateCoordinates } from "../index.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" +
@@ -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/returns.js

@@ -3,21 +3,26 @@ 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 = {
@@ -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 = {

package/dist/tools/specialized/venus_star_points.js

@@ -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 getActiveClient().request("POST", "/ephemeris/venus-star-points/phase", {
-            data: { date: args.date },
+            data: { date: args.date ?? new Date().toISOString().split("T")[0] },
             params: query,
         });
     },

package/package.json

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