caelus-mcp 0.3.0 → 0.4.0

package/README.md

@@ -1,9 +1,10 @@
 # caelus-mcp
 
 MCP server for the [caelus](https://github.com/heavyblotto/caelus) ephemeris
-engine: six chart tools over stdio. Computation only — positions, houses,
-aspects with orbs — the model does the interpreting. No API keys, no
-ephemeris files, no network calls; the engine data ships inside the package.
+engine: seven chart tools over stdio. Computation only — positions, houses,
+aspects with orbs, event search — the model does the interpreting. No API
+keys, no ephemeris files, no network calls; the engine data ships inside the
+package.
 
 ## Setup
 
@@ -31,10 +32,15 @@ Any MCP client that speaks stdio:
 | `synastry` | Two charts compared: inter-chart aspects, house overlays both ways |
 | `find_aspect_dates` | Exact dates a transiting body aspects a longitude or another body, retrograde re-hits included |
 | `rectification_grid` | ASC/MC sweep across a window of hours for birth-time rectification |
+| `sky_events` | Rise/set/meridian transits, lunar phases, stations, zodiac crossings in a date range (≤370 days) |
 
-Bodies: sun through pluto, chiron, mean and true node. House systems:
-placidus (default), whole_sign, equal, porphyry. Placidus falls back to
-whole_sign above the polar circles and says so in the payload.
+Bodies (core chart): sun through pluto, chiron, mean and true node. Optional
+bodies (mean/true Lilith, asteroids, Uranians) follow engine data on the Node
+loader path. House systems: twelve total — placidus (default), whole_sign,
+equal, porphyry, koch, regiomontanus, campanus, alcabitius, morinus,
+meridian, polich_page, vehlow. Placidus and Koch fall back to whole_sign
+above the polar circles and say so in the payload. `zodiac` supports tropical
+(default) and five sidereal ayanamsas on chart tools.
 
 ## Output
 
@@ -66,7 +72,8 @@ east-positive everywhere; the Americas are negative.
 
 Checked against Swiss Ephemeris across 1900–2099: Sun–Saturn ≤1″,
 Uranus ≤1.9″, Neptune ≤4.6″, Moon ≤2.5″, Pluto ≤2.5″ (series valid
-1885–2099), Chiron ≤1″, nodes ≤1″. Tables:
+1885–2099), Chiron ≤1″, mean node ≤1″, true node ≤1′ vs SE's built-in
+ephemeris, asteroids ≤1″ (Horizons fits), Uranians ≤2.3″. Tables:
 [ephemengine.com/validation](https://ephemengine.com/validation).
 
 ## The caelus packages

package/dist/src/server.d.ts

@@ -3,7 +3,7 @@
  * caelus-mcp -- MCP server for the caelus ephemeris engine.
  *
  * Design (per 2026 MCP practice): one bounded context (chart computation),
- * a small curated tool surface (6 outcome-level tools, not API wrappers),
+ * a small curated tool surface (7 outcome-level tools, not API wrappers),
  * and token-frugal outputs (positions to 0.01 deg, terse keys, no prose --
  * the model does the interpreting, the server does the math).
  *
@@ -603,6 +603,39 @@ export declare const rectificationGridOut: z.ZodObject<{
         mc: string;
     }[];
 }>;
+export declare const skyEventsOut: z.ZodObject<{
+    start: z.ZodString;
+    end: z.ZodString;
+    events: z.ZodArray<z.ZodObject<{
+        t: z.ZodString;
+        kind: z.ZodEnum<["rise", "set", "mtransit", "itransit", "phase", "station", "crossing"]>;
+        detail: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        t: string;
+        kind: "set" | "rise" | "mtransit" | "itransit" | "phase" | "station" | "crossing";
+        detail?: string | undefined;
+    }, {
+        t: string;
+        kind: "set" | "rise" | "mtransit" | "itransit" | "phase" | "station" | "crossing";
+        detail?: string | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    start: string;
+    end: string;
+    events: {
+        t: string;
+        kind: "set" | "rise" | "mtransit" | "itransit" | "phase" | "station" | "crossing";
+        detail?: string | undefined;
+    }[];
+}, {
+    start: string;
+    end: string;
+    events: {
+        t: string;
+        kind: "set" | "rise" | "mtransit" | "itransit" | "phase" | "station" | "crossing";
+        detail?: string | undefined;
+    }[];
+}>;
 export declare const OUTPUT_SCHEMAS: {
     readonly natal_chart: z.ZodObject<{
         utc: z.ZodString;
@@ -1306,5 +1339,38 @@ export declare const OUTPUT_SCHEMAS: {
             mc: string;
         }[];
     }>;
+    readonly sky_events: z.ZodObject<{
+        start: z.ZodString;
+        end: z.ZodString;
+        events: z.ZodArray<z.ZodObject<{
+            t: z.ZodString;
+            kind: z.ZodEnum<["rise", "set", "mtransit", "itransit", "phase", "station", "crossing"]>;
+            detail: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            t: string;
+            kind: "set" | "rise" | "mtransit" | "itransit" | "phase" | "station" | "crossing";
+            detail?: string | undefined;
+        }, {
+            t: string;
+            kind: "set" | "rise" | "mtransit" | "itransit" | "phase" | "station" | "crossing";
+            detail?: string | undefined;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        start: string;
+        end: string;
+        events: {
+            t: string;
+            kind: "set" | "rise" | "mtransit" | "itransit" | "phase" | "station" | "crossing";
+            detail?: string | undefined;
+        }[];
+    }, {
+        start: string;
+        end: string;
+        events: {
+            t: string;
+            kind: "set" | "rise" | "mtransit" | "itransit" | "phase" | "station" | "crossing";
+            detail?: string | undefined;
+        }[];
+    }>;
 };
 export declare function buildServer(): McpServer;

package/dist/src/server.js

@@ -3,7 +3,7 @@
  * caelus-mcp -- MCP server for the caelus ephemeris engine.
  *
  * Design (per 2026 MCP practice): one bounded context (chart computation),
- * a small curated tool surface (6 outcome-level tools, not API wrappers),
+ * a small curated tool surface (7 outcome-level tools, not API wrappers),
  * and token-frugal outputs (positions to 0.01 deg, terse keys, no prose --
  * the model does the interpreting, the server does the math).
  *
@@ -17,7 +17,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
 import { realpathSync } from "node:fs";
-import { Engine, BODIES, julianDay, mod } from "caelus";
+import { Engine, BODIES, julianDay, mod, riseSet, crossings, lunarPhases, stations, } from "caelus";
 import { loadNodeData } from "caelus/node";
 const require = createRequire(import.meta.url);
 const VERSION = require("caelus-mcp/package.json").version;
@@ -136,6 +136,15 @@ export const rectificationGridOut = z.object({
     asc_sign_changes: z.array(z.string()),
     grid: z.array(z.object({ utc: z.string(), asc: z.string(), mc: z.string() })),
 });
+export const skyEventsOut = z.object({
+    start: z.string(),
+    end: z.string(),
+    events: z.array(z.object({
+        t: z.string(),
+        kind: z.enum(["rise", "set", "mtransit", "itransit", "phase", "station", "crossing"]),
+        detail: z.string().optional(),
+    })),
+});
 export const OUTPUT_SCHEMAS = {
     natal_chart: chartOut,
     current_sky: chartOut,
@@ -143,12 +152,13 @@ export const OUTPUT_SCHEMAS = {
     synastry: synastryOut,
     find_aspect_dates: findAspectDatesOut,
     rectification_grid: rectificationGridOut,
+    sky_events: skyEventsOut,
 };
 // ---------------------------------------------------------------- server
 export function buildServer() {
     const server = new McpServer({ name: "caelus", version: VERSION });
     server.registerTool("natal_chart", {
-        description: "A person's birth chart. Requires their exact birth date+time and birthplace (all three: date, lat, lon). Use this — not current_sky — whenever the question is about someone's natal/birth chart. Returns 13 bodies (sun–pluto, chiron, nodes) with sign, house, retrograde, speed; ASC/MC; cusps; major aspects with orbs. Vs Swiss Ephemeris (1900–2099): Sun–Saturn ≤1″, Uranus ≤1.9″, Neptune ≤4.6″, Moon ≤2.5″, Pluto ≤2.5″ (series valid 1885–2099), Chiron ≤1″, nodes ≤1″.",
+        description: "A person's birth chart. Requires their exact birth date+time and birthplace (all three: date, lat, lon). Use this — not current_sky — whenever the question is about someone's natal/birth chart. Returns 13 bodies (sun–pluto, chiron, nodes) with sign, house, retrograde, speed; ASC/MC; cusps; major aspects with orbs. Vs Swiss Ephemeris (1900–2099): Sun–Saturn ≤1″, Uranus ≤1.9″, Neptune ≤4.6″, Moon ≤2.5″, Pluto ≤2.5″ (series valid 1885–2099), Chiron ≤1″, mean node ≤1″, true node ≤ 1′ vs SE's built-in ephemeris.",
         inputSchema: { ...birth, house_system: houseSys, zodiac: zodiacSchema },
     }, async ({ date, lat, lon, house_system, zodiac }) => text(chartPayload(date, lat, lon, house_system, zodiac)));
     server.registerTool("current_sky", {
@@ -338,6 +348,67 @@ export function buildServer() {
         }
         return text({ date: date.slice(0, 10), lat, lon, asc_sign_changes: boundaries, grid });
     });
+    server.registerTool("sky_events", {
+        description: "Sky events in a UTC date range: rise/set/meridian transits (need lat+lon+body), lunar phases (new/quarters/full), stations (body turns retrograde/direct; needs body), zodiac degree crossings (needs body + target_lon). Times to the second vs Swiss Ephemeris (stations to ~1 min: ill-conditioned by nature). Range <= 370 days.",
+        inputSchema: {
+            start: z.string().describe("UTC ISO start date (convert from local first)"),
+            end: z.string().describe("UTC ISO end date; range <= 370 days"),
+            kinds: z.array(z.enum(["rise", "set", "mtransit", "itransit", "phase", "station", "crossing"]))
+                .min(1).describe("Event kinds to include"),
+            body: z.enum(BODIES).optional()
+                .describe("Required for rise/set/transit/station/crossing"),
+            lat: latSchema.optional().describe("Required for rise/set/transit"),
+            lon: lonSchema.optional().describe("Required for rise/set/transit"),
+            target_lon: z.number().min(0).max(360).optional()
+                .describe("Zodiac longitude for 'crossing', degrees"),
+            zodiac: zodiacSchema.describe("Zodiac for 'crossing' longitudes"),
+        },
+    }, async ({ start, end, kinds, body, lat, lon, target_lon, zodiac }) => {
+        const jd0 = jdFromIso(start);
+        const jd1 = jdFromIso(end);
+        if (jd1 - jd0 > 370)
+            throw new Error("Range too large (max 370 days)");
+        const iso = (jd) => new Date((jd - 2440587.5) * 86400000).toISOString().slice(0, 19) + "Z";
+        const events = [];
+        const riseKinds = kinds.filter((k) => k === "rise" || k === "set" || k === "mtransit" || k === "itransit");
+        if (riseKinds.length) {
+            if (body === undefined || lat === undefined || lon === undefined) {
+                throw new Error("rise/set/transit need body, lat, lon");
+            }
+            for (const k of riseKinds) {
+                let t = jd0;
+                while (t < jd1 && events.length < 200) {
+                    const hit = riseSet(engine, body, t, lat, lon, k);
+                    if (hit === null || hit > jd1)
+                        break;
+                    events.push({ t: iso(hit), kind: k });
+                    t = hit + 1e-4;
+                }
+            }
+        }
+        if (kinds.includes("phase")) {
+            for (const [t, name] of lunarPhases(engine, jd0, jd1)) {
+                events.push({ t: iso(t), kind: "phase", detail: name });
+            }
+        }
+        if (kinds.includes("station")) {
+            if (body === undefined)
+                throw new Error("station needs body");
+            for (const [t, dir] of stations(engine, body, jd0, jd1)) {
+                events.push({ t: iso(t), kind: "station", detail: dir });
+            }
+        }
+        if (kinds.includes("crossing")) {
+            if (body === undefined || target_lon === undefined) {
+                throw new Error("crossing needs body and target_lon");
+            }
+            for (const t of crossings(engine, body, target_lon, jd0, jd1, zodiac)) {
+                events.push({ t: iso(t), kind: "crossing", detail: `${target_lon}°` });
+            }
+        }
+        events.sort((a, b) => a.t.localeCompare(b.t));
+        return text({ start, end, events });
+    });
     return server;
 }
 // ---------------------------------------------------------------- main

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "caelus-mcp",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "MCP server for caelus chart computation.",
   "type": "module",
   "bin": {
@@ -14,7 +14,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
     "zod": "^3.24.0",
-    "caelus": "^0.3.0"
+    "caelus": "^0.4.0"
   },
   "devDependencies": {
     "ajv": "^8.17.1"