@openephemeris/mcp-server 3.24.0 → 4.1.0

package/dist/tools/specialized/relocation.js

@@ -1,6 +1,7 @@
 import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
+import { DATETIME_DESC, TIMEZONE_PROPERTY, assertZonedDatetime } from "../datetime.js";
 registerTool({
     name: "ephemeris_relocation",
     description: "Calculate a relocation chart — the same natal planetary positions re-cast for a different " +
@@ -8,18 +9,20 @@ registerTool({
         "and angles, without changing the planetary longitudes in the chart.\n\n" +
         "CREDIT COST: 1 credit per call.\n\n" +
         "EXAMPLE: How does moving from Chicago to London change someone's chart?\n" +
-        "  natal_datetime='1990-04-15T14:30:00', natal_latitude=41.8781, natal_longitude=-87.6298,\n" +
+        "  natal_datetime='1990-04-15T14:30:00', timezone='America/Chicago',\n" +
+        "  natal_latitude=41.8781, natal_longitude=-87.6298,\n" +
         "  relocation_latitude=51.5074, relocation_longitude=-0.1278",
     inputSchema: {
         type: "object",
         properties: {
             natal_datetime: {
                 type: "string",
-                description: "ISO 8601 birth datetime (local time at birth location).",
+                description: DATETIME_DESC,
             },
+            timezone: TIMEZONE_PROPERTY,
             natal_latitude: {
                 type: "number",
-                description: "Latitude of birth location in decimal degrees.",
+                description: "Latitude of birth location in decimal degrees. Resolve from a place name with location_search; never recall coordinates from memory.",
             },
             natal_longitude: {
                 type: "number",
@@ -51,6 +54,7 @@ registerTool({
     annotations: { title: "Relocation Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, ["natal_datetime", "natal_latitude", "natal_longitude", "relocation_latitude", "relocation_longitude"]);
+        assertZonedDatetime("natal_datetime", args.natal_datetime, args.timezone);
         const body = {
             natal: {
                 subject: {
@@ -59,6 +63,8 @@ registerTool({
                     birth_location: {
                         latitude: { decimal: args.natal_latitude },
                         longitude: { decimal: args.natal_longitude },
+                        // The server resolves the IANA zone, so historical DST stays correct.
+                        ...(args.timezone ? { timezone: { iana_name: args.timezone } } : {}),
                     },
                 },
             },

package/dist/tools/specialized/returns.js

@@ -1,6 +1,7 @@
 import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
-import { OUTPUT_SCHEMA_IMAGE_AND_JSON } from "../output-schemas.js";
+import { OUTPUT_SCHEMA_IMAGE_AND_JSON, OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
+import { DATETIME_DESC, TIMEZONE_PROPERTY, assertZonedDatetime, localToUtcIso } from "../datetime.js";
 // POST /predictive/returns/solar
 registerTool({
     name: "ephemeris_solar_return",
@@ -18,8 +19,9 @@ registerTool({
         properties: {
             birth_datetime: {
                 type: "string",
-                description: "ISO 8601 birth date/time. Include offset or Z (e.g. '1985-06-21T14:00:00-05:00').",
+                description: DATETIME_DESC,
             },
+            timezone: TIMEZONE_PROPERTY,
             target_datetime: {
                 type: "string",
                 description: "Date/time near which to find the Solar Return (ISO 8601 with offset or Z). " +
@@ -64,11 +66,13 @@ registerTool({
     annotations: { title: "Solar Return", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, ["birth_datetime"]);
+        assertZonedDatetime("birth_datetime", args.birth_datetime, args.timezone);
+        assertZonedDatetime("target_datetime", args.target_datetime, args.timezone);
         // 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: targetDt },
+            birth_datetime: { iso: localToUtcIso("birth_datetime", args.birth_datetime, args.timezone) },
+            target_datetime: { iso: localToUtcIso("target_datetime", targetDt, args.timezone) },
         };
         if (args.birth_latitude != null && args.birth_longitude != null) {
             body.location = {
@@ -110,8 +114,9 @@ registerTool({
         properties: {
             birth_datetime: {
                 type: "string",
-                description: "ISO 8601 birth date/time. Include offset or Z.",
+                description: DATETIME_DESC,
             },
+            timezone: TIMEZONE_PROPERTY,
             target_datetime: {
                 type: "string",
                 description: "Date/time near which to find the Lunar Return (ISO 8601 with offset or Z). " +
@@ -129,14 +134,17 @@ registerTool({
         required: ["birth_datetime"],
         additionalProperties: false,
     },
-    outputSchema: OUTPUT_SCHEMA_IMAGE_AND_JSON,
+    // JSON only: this tool never sets include_visual, so it cannot return an image.
+    outputSchema: OUTPUT_SCHEMA_JSON,
     annotations: { title: "Lunar Return", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, ["birth_datetime"]);
+        assertZonedDatetime("birth_datetime", args.birth_datetime, args.timezone);
+        assertZonedDatetime("target_datetime", args.target_datetime, args.timezone);
         const targetDt = args.target_datetime ?? new Date().toISOString();
         const body = {
-            birth_datetime: { iso: args.birth_datetime },
-            target_datetime: { iso: targetDt },
+            birth_datetime: { iso: localToUtcIso("birth_datetime", args.birth_datetime, args.timezone) },
+            target_datetime: { iso: localToUtcIso("target_datetime", targetDt, args.timezone) },
         };
         if (args.birth_latitude != null && args.birth_longitude != null) {
             body.location = {
@@ -167,15 +175,16 @@ registerTool({
             },
             birth_datetime: {
                 type: "string",
-                description: "ISO 8601 birth date/time. MUST include offset or Z.",
+                description: DATETIME_DESC,
             },
+            timezone: TIMEZONE_PROPERTY,
             target_datetime: {
                 type: "string",
                 description: "Date/time near which to find the return (ISO 8601). MUST include offset or Z. Required.",
             },
             birth_latitude: {
                 type: "number",
-                description: "Birth latitude in decimal degrees. Required to get a full return chart (house cusps, angles).",
+                description: "Birth latitude in decimal degrees. Required to get a full return chart (house cusps, angles). Resolve from a place name with location_search; never recall coordinates from memory.",
             },
             birth_longitude: {
                 type: "number",
@@ -185,10 +194,13 @@ registerTool({
         required: ["body", "birth_datetime", "target_datetime"],
         additionalProperties: false,
     },
-    outputSchema: OUTPUT_SCHEMA_IMAGE_AND_JSON,
+    // JSON only: this tool never sets include_visual, so it cannot return an image.
+    outputSchema: OUTPUT_SCHEMA_JSON,
     annotations: { title: "Planetary Return", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, ["body", "birth_datetime", "target_datetime"]);
+        assertZonedDatetime("birth_datetime", args.birth_datetime, args.timezone);
+        assertZonedDatetime("target_datetime", args.target_datetime, args.timezone);
         const requestBody = {
             body: args.body,
             birth_datetime: { iso: args.birth_datetime },

package/dist/tools/specialized/synastry.js

@@ -1,22 +1,27 @@
 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, assertZonedDatetime, timezoneProperty } from "../datetime.js";
 registerTool({
     name: "ephemeris_synastry",
     description: "Calculate a synastry chart comparing two people's natal charts. Returns inter-aspects " +
         "(planetary connections between the two charts), composite points, and relationship indicators. " +
         "Use this for compatibility analysis, relationship timing, or partnership insights.\n\n" +
         "CREDIT COST: 3 credits per call.\n\n" +
-        "EXAMPLE: Compare two people's charts:\n" +
-        "  person_a_datetime='1990-04-15T14:30:00', person_a_latitude=41.8781, person_a_longitude=-87.6298,\n" +
-        "  person_b_datetime='1988-09-22T08:15:00', person_b_latitude=34.0522, person_b_longitude=-118.2437",
+        "EXAMPLE: Compare two people's charts (local birth times, each with its zone):\n" +
+        "  person_a_datetime='1990-04-15T14:30:00', person_a_timezone='America/Chicago',\n" +
+        "  person_a_latitude=41.8781, person_a_longitude=-87.6298,\n" +
+        "  person_b_datetime='1988-09-22T08:15:00', person_b_timezone='America/Los_Angeles',\n" +
+        "  person_b_latitude=34.0522, person_b_longitude=-118.2437",
     inputSchema: {
         type: "object",
         properties: {
-            person_a_datetime: { type: "string", description: "Person A birth datetime (ISO 8601)." },
-            person_a_latitude: { type: "number", description: "Person A birth latitude." },
+            person_a_datetime: { type: "string", description: DATETIME_DESC },
+            person_a_timezone: timezoneProperty("Person A's birth location"),
+            person_a_latitude: { type: "number", description: "Person A birth latitude. Resolve from a place name with location_search; never recall coordinates from memory." },
             person_a_longitude: { type: "number", description: "Person A birth longitude." },
-            person_b_datetime: { type: "string", description: "Person B birth datetime (ISO 8601)." },
+            person_b_datetime: { type: "string", description: DATETIME_DESC },
+            person_b_timezone: timezoneProperty("Person B's birth location", "America/Los_Angeles"),
             person_b_latitude: { type: "number", description: "Person B birth latitude." },
             person_b_longitude: { type: "number", description: "Person B birth longitude." },
             house_system: {
@@ -58,6 +63,8 @@ registerTool({
             "person_a_datetime", "person_a_latitude", "person_a_longitude",
             "person_b_datetime", "person_b_latitude", "person_b_longitude",
         ]);
+        assertZonedDatetime("person_a_datetime", args.person_a_datetime, args.person_a_timezone, "person_a_timezone");
+        assertZonedDatetime("person_b_datetime", args.person_b_datetime, args.person_b_timezone, "person_b_timezone");
         const body = {
             subject_a: {
                 name: "Person A",
@@ -65,6 +72,9 @@ registerTool({
                 birth_location: {
                     latitude: { decimal: args.person_a_latitude },
                     longitude: { decimal: args.person_a_longitude },
+                    // The server resolves the zone; sending the IANA name keeps
+                    // historical DST correct instead of resolving it here.
+                    ...(args.person_a_timezone ? { timezone: { iana_name: args.person_a_timezone } } : {}),
                 },
             },
             subject_b: {
@@ -73,6 +83,7 @@ registerTool({
                 birth_location: {
                     latitude: { decimal: args.person_b_latitude },
                     longitude: { decimal: args.person_b_longitude },
+                    ...(args.person_b_timezone ? { timezone: { iana_name: args.person_b_timezone } } : {}),
                 },
             },
         };

package/dist/tools/specialized/transits.js

@@ -1,6 +1,7 @@
 import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
+import { DATETIME_DESC, WINDOW_DATE_DESC, timezoneProperty } from "../datetime.js";
 registerTool({
     name: "ephemeris_transits",
     description: "Search for astrological transit events affecting a natal chart over a date range. " +
@@ -22,11 +23,12 @@ registerTool({
         properties: {
             natal_datetime: {
                 type: "string",
-                description: "ISO 8601 birth datetime for the natal chart.",
+                description: DATETIME_DESC,
             },
+            natal_timezone: timezoneProperty("the natal birth location"),
             natal_latitude: {
                 type: "number",
-                description: "Latitude of birth location in decimal degrees.",
+                description: "Latitude of birth location in decimal degrees. Resolve from a place name with location_search; never recall coordinates from memory.",
             },
             natal_longitude: {
                 type: "number",
@@ -34,11 +36,11 @@ registerTool({
             },
             start_date: {
                 type: "string",
-                description: "Start of the transit search window, ISO 8601 date or datetime (e.g. '2026-01-01').",
+                description: "Start of the transit search window. " + WINDOW_DATE_DESC,
             },
             end_date: {
                 type: "string",
-                description: "End of the transit search window, ISO 8601 date or datetime (e.g. '2026-06-30').",
+                description: "End of the transit search window. " + WINDOW_DATE_DESC,
             },
             transiting_planets: {
                 type: "array",
@@ -72,7 +74,9 @@ registerTool({
                 birth_datetime: { iso: args.natal_datetime },
                 birth_location: {
                     latitude: { decimal: args.natal_latitude },
-                    longitude: { decimal: args.natal_longitude }
+                    longitude: { decimal: args.natal_longitude },
+                    // The server resolves the IANA zone, so historical DST stays correct.
+                    ...(args.natal_timezone ? { timezone: { iana_name: args.natal_timezone } } : {}),
                 },
             },
         };

package/dist/tools/specialized/vedic.js

@@ -1,6 +1,7 @@
 import { registerTool, validateRequired, validateCoordinates } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
+import { DATETIME_DESC, TIMEZONE_PROPERTY, localToUtcIso } from "../datetime.js";
 registerTool({
     name: "vedic_chart",
     description: "Calculate a Vedic (Jyotish) natal chart with sidereal positions. Returns planet placements " +
@@ -15,11 +16,12 @@ registerTool({
         properties: {
             datetime: {
                 type: "string",
-                description: "ISO 8601 birth datetime in UTC, e.g. '1990-01-15T08:30:00Z'. Include 'Z' or timezone offset.",
+                description: DATETIME_DESC,
             },
+            timezone: TIMEZONE_PROPERTY,
             latitude: {
                 type: "number",
-                description: "Birth latitude in decimal degrees (north positive).",
+                description: "Birth latitude in decimal degrees (north positive). Resolve from a place name with location_search; never recall coordinates from memory.",
             },
             longitude: {
                 type: "number",
@@ -40,7 +42,7 @@ registerTool({
         validateRequired(args, ["datetime", "latitude", "longitude"]);
         validateCoordinates(args, "latitude", "longitude");
         const body = {
-            datetime_utc: args.datetime,
+            datetime_utc: localToUtcIso("datetime", args.datetime, args.timezone),
             latitude: args.latitude,
             longitude: args.longitude,
         };

package/dist/tools/specialized/venus_star_points.js

@@ -1,13 +1,16 @@
 import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
-function buildSubject(datetime, lat, lon) {
+import { DATETIME_DESC, TIMEZONE_PROPERTY, assertZonedDatetime } from "../datetime.js";
+function buildSubject(datetime, lat, lon, timezone) {
     return {
         name: "Subject",
         birth_datetime: { iso: datetime },
         birth_location: {
             latitude: { decimal: lat },
             longitude: { decimal: lon },
+            // The server resolves the IANA zone, so historical DST stays correct.
+            ...(timezone ? { timezone: { iana_name: timezone } } : {}),
         },
     };
 }
@@ -16,13 +19,14 @@ registerTool({
     name: "venus_star_points",
     description: "Get Venus Star Points — the Sun-Venus conjunction events nearest to a birth date. " +
         "Shows the quality of each conjunction (cazimi, combust, under beams) with zodiac details.\n\n" +
-        "CREDIT COST: 2 credits per call.\n\n" +
+        "CREDIT COST: 1 credit per call.\n\n" +
         "EXAMPLE: Venus star points for someone born 1990-04-15:\n" +
-        "  datetime='1990-04-15T14:30:00', latitude=41.88, longitude=-87.63",
+        "  datetime='1990-04-15T14:30:00', timezone='America/Chicago', latitude=41.88, longitude=-87.63",
     inputSchema: {
         type: "object",
         properties: {
-            datetime: { type: "string", description: "Birth datetime (ISO 8601)." },
+            datetime: { type: "string", description: DATETIME_DESC },
+            timezone: TIMEZONE_PROPERTY,
             latitude: { type: "number", description: "Birth latitude." },
             longitude: { type: "number", description: "Birth longitude." },
             format: { type: "string", enum: ["json", "llm"], description: "Output format." },
@@ -34,11 +38,12 @@ registerTool({
     annotations: { title: "Venus Star Points", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, ["datetime", "latitude", "longitude"]);
+        assertZonedDatetime("datetime", args.datetime, args.timezone);
         const query = {};
         if (args.format)
             query.format = args.format;
         return await getActiveClient().request("POST", "/ephemeris/venus-star-points", {
-            data: { subject: buildSubject(args.datetime, args.latitude, args.longitude) },
+            data: { subject: buildSubject(args.datetime, args.latitude, args.longitude, args.timezone) },
             params: query,
         });
     },
@@ -48,7 +53,7 @@ registerTool({
     name: "venus_star_points_conjunctions",
     description: "Find all Sun-Venus conjunctions in a date range. Returns each conjunction with " +
         "its exact timestamp, zodiac position, orb, visibility (morning/evening star), and dignity.\n\n" +
-        "CREDIT COST: 2 credits per call.\n\n" +
+        "CREDIT COST: 1 credit per call.\n\n" +
         "EXAMPLE: Find Venus conjunctions in 2026:\n" +
         "  start_date='2026-01-01', end_date='2026-12-31'",
     inputSchema: {
@@ -80,7 +85,7 @@ registerTool({
     description: "Compute the 8-year Venus Star pattern — the pentagram of 5 Venus-Sun conjunctions " +
         "that trace a near-perfect star over 8 years (the Venus synodic cycle). Returns the 5 " +
         "vertices with their zodiac positions.\n\n" +
-        "CREDIT COST: 2 credits per call.\n\n" +
+        "CREDIT COST: 1 credit per call.\n\n" +
         "EXAMPLE: 8-year star starting from 2020:\n" +
         "  date='2020-01-01'",
     inputSchema: {
@@ -141,7 +146,7 @@ registerTool({
     name: "venus_elongations",
     description: "Find Venus greatest elongation events (when Venus is farthest from the Sun in the sky). " +
         "Returns east (evening star) and west (morning star) elongation peaks.\n\n" +
-        "CREDIT COST: 2 credits per call.",
+        "CREDIT COST: 1 credit per call.",
     inputSchema: {
         type: "object",
         properties: {
@@ -170,7 +175,7 @@ registerTool({
     name: "venus_stations",
     description: "Find Venus retrograde and direct stations in a date range. Returns the exact " +
         "moment Venus appears to stop and reverse direction.\n\n" +
-        "CREDIT COST: 2 credits per call.\n\n" +
+        "CREDIT COST: 1 credit per call.\n\n" +
         "EXAMPLE: Venus stations in 2026:\n" +
         "  start_date='2026-01-01', end_date='2026-12-31'",
     inputSchema: {