@openephemeris/mcp-server 3.2.12 → 3.3.0

package/dist/tools/specialized/returns.js

@@ -0,0 +1,144 @@
+import { registerTool, validateRequired } from "../index.js";
+import { backendClient } 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" +
+        "CREDIT COST: 1 credit 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'",
+    inputSchema: {
+        type: "object",
+        properties: {
+            birth_datetime: {
+                type: "string",
+                description: "ISO 8601 birth date/time (e.g. '1985-06-21T14:00:00').",
+            },
+            target_datetime: {
+                type: "string",
+                description: "Date/time near which to find the Solar Return (ISO 8601). Required.",
+            },
+            birth_latitude: {
+                type: "number",
+                description: "Birth latitude in decimal degrees (optional, for location context).",
+            },
+            birth_longitude: {
+                type: "number",
+                description: "Birth longitude in decimal degrees (optional, for location context).",
+            },
+            return_latitude: {
+                type: "number",
+                description: "Location latitude for the return chart (optional).",
+            },
+            return_longitude: {
+                type: "number",
+                description: "Location longitude for the return chart (optional).",
+            },
+        },
+        required: ["birth_datetime", "target_datetime"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["birth_datetime", "target_datetime"]);
+        const body = {
+            birth_datetime: { iso: args.birth_datetime },
+            target_datetime: { iso: args.target_datetime },
+        };
+        if (args.birth_latitude != null && args.birth_longitude != null) {
+            body.location = {
+                latitude: { decimal: args.birth_latitude },
+                longitude: { decimal: args.birth_longitude },
+            };
+        }
+        if (args.return_latitude != null && args.return_longitude != null) {
+            body.return_location = {
+                latitude: { decimal: args.return_latitude },
+                longitude: { decimal: args.return_longitude },
+            };
+        }
+        return await backendClient.post("/predictive/returns/solar", body);
+    },
+});
+// POST /predictive/returns/lunar
+registerTool({
+    name: "ephemeris_lunar_return",
+    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: 1 credit 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'",
+    inputSchema: {
+        type: "object",
+        properties: {
+            birth_datetime: {
+                type: "string",
+                description: "ISO 8601 birth date/time.",
+            },
+            target_datetime: {
+                type: "string",
+                description: "Date/time near which to find the Lunar Return (ISO 8601). Required.",
+            },
+            birth_latitude: {
+                type: "number",
+                description: "Birth latitude in decimal degrees (optional).",
+            },
+            birth_longitude: {
+                type: "number",
+                description: "Birth longitude in decimal degrees (optional).",
+            },
+        },
+        required: ["birth_datetime", "target_datetime"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["birth_datetime", "target_datetime"]);
+        const body = {
+            birth_datetime: { iso: args.birth_datetime },
+            target_datetime: { iso: args.target_datetime },
+        };
+        if (args.birth_latitude != null && args.birth_longitude != null) {
+            body.location = {
+                latitude: { decimal: args.birth_latitude },
+                longitude: { decimal: args.birth_longitude },
+            };
+        }
+        return await backendClient.post("/predictive/returns/lunar", body);
+    },
+});
+// POST /predictive/returns (generic planetary return)
+registerTool({
+    name: "ephemeris_planetary_return",
+    description: "Calculate a planetary return — when any planet returns to its natal longitude. " +
+        "Useful for Jupiter returns (~12 years), Saturn returns (~29 years), etc.\n\n" +
+        "CREDIT COST: 1 credit per call.\n\n" +
+        "EXAMPLE: Saturn return for birth 1990-04-15 near year 2019:\n" +
+        "  body='saturn', birth_datetime='1990-04-15T14:30:00', target_datetime='2019-01-01'",
+    inputSchema: {
+        type: "object",
+        properties: {
+            body: {
+                type: "string",
+                description: "Planet name: sun, moon, mercury, venus, mars, jupiter, saturn.",
+            },
+            birth_datetime: {
+                type: "string",
+                description: "ISO 8601 birth date/time.",
+            },
+            target_datetime: {
+                type: "string",
+                description: "Date/time near which to find the return (ISO 8601). Required.",
+            },
+        },
+        required: ["body", "birth_datetime", "target_datetime"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["body", "birth_datetime", "target_datetime"]);
+        return await backendClient.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,11 +1,11 @@
-import { registerTool } from "../index.js";
+import { registerTool, validateRequired } from "../index.js";
 import { backendClient } from "../../backend/client.js";
 registerTool({
-    name: "ephemeris.synastry",
+    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: 5 credits per call.\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",
@@ -26,7 +26,7 @@ registerTool({
             format: {
                 type: "string",
                 enum: ["json", "llm"],
-                description: "Output format. 'llm' is compact and token-efficient (Pro tier).",
+                description: "Output format. 'llm' is compact and token-efficient (available on all tiers).",
             },
         },
         required: [
@@ -36,16 +36,26 @@ registerTool({
         additionalProperties: false,
     },
     handler: async (args) => {
+        validateRequired(args, [
+            "person_a_datetime", "person_a_latitude", "person_a_longitude",
+            "person_b_datetime", "person_b_latitude", "person_b_longitude",
+        ]);
         const body = {
-            natal_a: {
-                datetime: args.person_a_datetime,
-                latitude: args.person_a_latitude,
-                longitude: args.person_a_longitude,
+            subject_a: {
+                name: "Person A",
+                birth_datetime: { iso: args.person_a_datetime },
+                birth_location: {
+                    latitude: { decimal: args.person_a_latitude },
+                    longitude: { decimal: args.person_a_longitude },
+                },
             },
-            natal_b: {
-                datetime: args.person_b_datetime,
-                latitude: args.person_b_latitude,
-                longitude: args.person_b_longitude,
+            subject_b: {
+                name: "Person B",
+                birth_datetime: { iso: args.person_b_datetime },
+                birth_location: {
+                    latitude: { decimal: args.person_b_latitude },
+                    longitude: { decimal: args.person_b_longitude },
+                },
             },
         };
         if (args.house_system)

package/dist/tools/specialized/transits.js

@@ -1,12 +1,14 @@
-import { registerTool } from "../index.js";
+import { registerTool, validateRequired } from "../index.js";
 import { backendClient } from "../../backend/client.js";
 registerTool({
-    name: "ephemeris.transits",
+    name: "ephemeris_transits",
     description: "Search for astrological transit events affecting a natal chart over a date range. " +
         "Returns a list of exact transit moments — when transiting planets form specified aspects " +
         "to natal planet positions. Ideal for generating horoscope timelines, event forecasting, or " +
         "finding optimal timing windows.\n\n" +
-        "CREDIT COST: 5 credits per call.\n\n" +
+        "HOW IT WORKS: This tool first calculates the natal chart to extract your actual planetary " +
+        "ecliptic longitudes, then searches for transiting planets crossing those exact degrees.\n\n" +
+        "CREDIT COST: 6 credits per call (1 for natal + 5 for transit search).\n\n" +
         "EXAMPLE: Find all Saturn transits to the natal Sun/Moon for the next 6 months:\n" +
         "  natal_datetime='1990-04-15T14:30:00', natal_latitude=41.8781, natal_longitude=-87.6298,\n" +
         "  start_date='2026-01-01', end_date='2026-06-30', transiting_planets=['saturn']",
@@ -42,39 +44,87 @@ registerTool({
             natal_points: {
                 type: "array",
                 items: { type: "string" },
-                description: "Natal point IDs to receive transits. E.g. ['sun', 'moon', 'asc', 'mc']. Omit for all core points.",
-            },
-            aspects: {
-                type: "array",
-                items: { type: "string", enum: ["conjunction", "opposition", "trine", "square", "sextile"] },
-                description: "Aspect types to include in the search. Defaults to all major aspects.",
-            },
-            orb: {
-                type: "number",
-                description: "Maximum orb in degrees (default: 1.0).",
+                description: "Natal point IDs whose exact longitudes should be targeted. E.g. ['sun', 'moon', 'asc', 'mc']. Omit for all core points.",
             },
         },
         required: ["natal_datetime", "natal_latitude", "natal_longitude", "start_date", "end_date"],
         additionalProperties: false,
     },
     handler: async (args) => {
-        const body = {
-            natal: {
-                datetime: args.natal_datetime,
-                latitude: args.natal_latitude,
-                longitude: args.natal_longitude,
+        validateRequired(args, ["natal_datetime", "natal_latitude", "natal_longitude", "start_date", "end_date"]);
+        // ── Step 1: Compute natal chart to extract real planetary longitudes ──
+        const natalBody = {
+            subject: {
+                name: "Transit Natal Subject",
+                birth_datetime: { iso: args.natal_datetime },
+                birth_location: {
+                    latitude: { decimal: args.natal_latitude },
+                    longitude: { decimal: args.natal_longitude }
+                },
             },
-            start_date: args.start_date,
-            end_date: args.end_date,
+        };
+        const natalResult = await backendClient.post("/ephemeris/natal-chart", natalBody);
+        // Extract ecliptic longitudes from natal chart planets
+        const targetDegrees = [];
+        const natalPositionMap = {};
+        // The natal response typically has a `planets` array or object
+        const planets = natalResult?.planets || natalResult?.data?.planets || [];
+        const planetArray = Array.isArray(planets) ? planets : Object.values(planets);
+        // Filter to requested natal points if specified
+        const wantedPoints = args.natal_points
+            ? new Set(args.natal_points.map((p) => p.toLowerCase()))
+            : null;
+        for (const planet of planetArray) {
+            const name = (planet.name || planet.id || "").toLowerCase();
+            const lon = planet.longitude ?? planet.ecliptic_longitude ?? planet.lon;
+            if (typeof lon !== "number" || !isFinite(lon))
+                continue;
+            if (wantedPoints && !wantedPoints.has(name))
+                continue;
+            targetDegrees.push(Math.round(lon * 100) / 100); // 2 decimal places
+            natalPositionMap[name] = lon;
+        }
+        // Also extract angles (ASC, MC, DSC, IC) if present
+        const angles = natalResult?.angles || natalResult?.data?.angles;
+        if (angles) {
+            const angleEntries = Array.isArray(angles) ? angles : Object.entries(angles).map(([k, v]) => ({ name: k, ...(typeof v === 'object' ? v : { longitude: v }) }));
+            for (const angle of angleEntries) {
+                const name = (angle.name || angle.id || "").toLowerCase();
+                const lon = angle.longitude ?? angle.ecliptic_longitude ?? angle.lon;
+                if (typeof lon !== "number" || !isFinite(lon))
+                    continue;
+                if (wantedPoints && !wantedPoints.has(name))
+                    continue;
+                targetDegrees.push(Math.round(lon * 100) / 100);
+                natalPositionMap[name] = lon;
+            }
+        }
+        if (targetDegrees.length === 0) {
+            throw new Error("Could not extract natal planet longitudes from the natal chart calculation. " +
+                "Please verify your natal_datetime, natal_latitude, and natal_longitude are correct.");
+        }
+        // ── Step 2: Search transits against those real natal longitudes ──
+        let startStr = args.start_date;
+        if (/^\d{4}-\d{2}-\d{2}$/.test(startStr)) {
+            startStr += "T00:00:00Z";
+        }
+        let endStr = args.end_date;
+        if (/^\d{4}-\d{2}-\d{2}$/.test(endStr)) {
+            endStr += "T23:59:59Z";
+        }
+        const transitBody = {
+            start_date: startStr,
+            end_date: endStr,
+            target_degrees: targetDegrees,
         };
         if (args.transiting_planets)
-            body.transiting_planets = args.transiting_planets;
-        if (args.natal_points)
-            body.natal_points = args.natal_points;
-        if (args.aspects)
-            body.aspects = args.aspects;
-        if (args.orb != null)
-            body.orb = args.orb;
-        return await backendClient.request("POST", "/predictive/transits/search", { data: body });
+            transitBody.planet_names = args.transiting_planets;
+        const transitResult = await backendClient.request("POST", "/predictive/transits/search", { data: transitBody });
+        // Return combined context so the LLM knows what natal positions were targeted
+        return {
+            natal_positions: natalPositionMap,
+            target_degrees_used: targetDegrees,
+            transit_results: transitResult,
+        };
     },
 });

package/dist/tools/specialized/venus_star_points.js

@@ -0,0 +1,187 @@
+import { registerTool, validateRequired } from "../index.js";
+import { backendClient } from "../../backend/client.js";
+function buildSubject(datetime, lat, lon) {
+    return {
+        name: "Subject",
+        birth_datetime: { iso: datetime },
+        birth_location: {
+            latitude: { decimal: lat },
+            longitude: { decimal: lon },
+        },
+    };
+}
+// POST /ephemeris/venus-star-points
+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" +
+        "EXAMPLE: Venus star points for someone born 1990-04-15:\n" +
+        "  datetime='1990-04-15T14:30:00', latitude=41.88, longitude=-87.63",
+    inputSchema: {
+        type: "object",
+        properties: {
+            datetime: { type: "string", description: "Birth datetime (ISO 8601)." },
+            latitude: { type: "number", description: "Birth latitude." },
+            longitude: { type: "number", description: "Birth longitude." },
+            format: { type: "string", enum: ["json", "llm"], description: "Output format." },
+        },
+        required: ["datetime", "latitude", "longitude"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["datetime", "latitude", "longitude"]);
+        const query = {};
+        if (args.format)
+            query.format = args.format;
+        return await backendClient.request("POST", "/ephemeris/venus-star-points", {
+            data: { subject: buildSubject(args.datetime, args.latitude, args.longitude) },
+            params: query,
+        });
+    },
+});
+// POST /ephemeris/venus-star-points/conjunctions
+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" +
+        "EXAMPLE: Find Venus conjunctions in 2026:\n" +
+        "  start_date='2026-01-01', end_date='2026-12-31'",
+    inputSchema: {
+        type: "object",
+        properties: {
+            start_date: { type: "string", description: "Start date (ISO 8601)." },
+            end_date: { type: "string", description: "End date (ISO 8601)." },
+            format: { type: "string", enum: ["json", "llm"], description: "Output format." },
+        },
+        required: ["start_date", "end_date"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["start_date", "end_date"]);
+        const query = {};
+        if (args.format)
+            query.format = args.format;
+        return await backendClient.request("POST", "/ephemeris/venus-star-points/conjunctions", {
+            data: { start_date: args.start_date, end_date: args.end_date },
+            params: query,
+        });
+    },
+});
+// POST /ephemeris/venus-star-points/eight-year-star
+registerTool({
+    name: "venus_eight_year_star",
+    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" +
+        "EXAMPLE: 8-year star starting from 2020:\n" +
+        "  date='2020-01-01'",
+    inputSchema: {
+        type: "object",
+        properties: {
+            date: { type: "string", description: "Start date for the 8-year cycle (ISO 8601)." },
+            format: { type: "string", enum: ["json", "llm"], description: "Output format." },
+        },
+        required: ["date"],
+        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/eight-year-star", {
+            data: { date: args.date },
+            params: query,
+        });
+    },
+});
+// POST /ephemeris/venus-star-points/phase
+registerTool({
+    name: "venus_phase",
+    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" +
+        "  date='2026-03-20'",
+    inputSchema: {
+        type: "object",
+        properties: {
+            date: { type: "string", description: "Date to check (ISO 8601). Defaults to now." },
+            format: { type: "string", enum: ["json", "llm"], description: "Output format." },
+        },
+        required: ["date"],
+        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 },
+            params: query,
+        });
+    },
+});
+// POST /ephemeris/venus-star-points/elongations
+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.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            start_date: { type: "string", description: "Start date (ISO 8601)." },
+            end_date: { type: "string", description: "End date (ISO 8601)." },
+            format: { type: "string", enum: ["json", "llm"], description: "Output format." },
+        },
+        required: ["start_date", "end_date"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["start_date", "end_date"]);
+        const query = {};
+        if (args.format)
+            query.format = args.format;
+        return await backendClient.request("POST", "/ephemeris/venus-star-points/elongations", {
+            data: { start_date: args.start_date, end_date: args.end_date },
+            params: query,
+        });
+    },
+});
+// POST /ephemeris/venus-star-points/stations
+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" +
+        "EXAMPLE: Venus stations in 2026:\n" +
+        "  start_date='2026-01-01', end_date='2026-12-31'",
+    inputSchema: {
+        type: "object",
+        properties: {
+            start_date: { type: "string", description: "Start date (ISO 8601)." },
+            end_date: { type: "string", description: "End date (ISO 8601). Defaults to +1 year." },
+            format: { type: "string", enum: ["json", "llm"], description: "Output format." },
+        },
+        required: ["start_date"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["start_date"]);
+        const query = {};
+        if (args.format)
+            query.format = args.format;
+        return await backendClient.request("POST", "/ephemeris/venus-star-points/stations", {
+            data: {
+                start_date: args.start_date,
+                end_date: args.end_date || "",
+            },
+            params: query,
+        });
+    },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openephemeris/mcp-server",
-  "version": "3.2.12",
+  "version": "3.3.0",
   "description": "Model Context Protocol server for the Open Ephemeris astronomical computation API",
   "type": "module",
   "main": "dist/index.js",
@@ -16,11 +16,12 @@
     "test": "test"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "tsc -p tsconfig.build.json",
+    "prebuild": "node -e \"const fs=require('fs');fs.rmSync('dist',{recursive:true,force:true})\"",
     "dev": "tsx watch src/index.ts",
     "dev:sse": "tsx watch src/server-sse.ts",
     "start": "node dist/index.js",
-    "start:sse": "node dist/src/server-sse.js",
+    "start:sse": "node dist/server-sse.js",
     "test": "vitest run --exclude \"dist/**\"",
     "test:watch": "vitest --exclude \"dist/**\"",
     "test:integration": "tsx scripts/test-client.ts",