ether-to-astro 1.0.2 → 1.2.0

package/src/tool-registry.ts

@@ -1,6 +1,6 @@
 import type { AstroService } from './astro-service.js';
 import type { Disambiguation } from './time-utils.js';
-import type { HouseSystem, NatalChart } from './types.js';
+import type { ElectionalHouseSystem, HouseSystem, NatalChart } from './types.js';
 
 type ToolContent =
   | { type: 'text'; text: string }
@@ -91,10 +91,117 @@ export const MCP_TOOL_SPECS: ToolSpec[] = [
       return { kind: 'state', data: result.data, text: result.text, natalChart: result.chart };
     },
   },
+  {
+    name: 'get_rising_sign_windows',
+    description:
+      'Get local-time windows for which zodiac signs are rising on a given date and location. Returns deterministic intervals only (no ranking or interpretation).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        date: {
+          type: 'string',
+          description: 'Target local date (YYYY-MM-DD)',
+        },
+        latitude: { type: 'number', description: 'Latitude in decimal degrees (-90 to 90)' },
+        longitude: {
+          type: 'number',
+          description: 'Longitude in decimal degrees (-180 to 180)',
+        },
+        timezone: {
+          type: 'string',
+          description: 'IANA timezone (e.g., America/New_York)',
+        },
+        mode: {
+          type: 'string',
+          enum: ['approximate', 'exact'],
+          description:
+            'Boundary mode. approximate uses coarser stepping; exact refines sign-change boundaries.',
+          default: 'approximate',
+        },
+      },
+      required: ['date', 'latitude', 'longitude', 'timezone'],
+    },
+    requiresNatalChart: false,
+    execute: (ctx, args) => {
+      const result = ctx.service.getRisingSignWindows({
+        date: args.date as string,
+        latitude: args.latitude as number,
+        longitude: args.longitude as number,
+        timezone: args.timezone as string,
+        mode: args.mode as 'approximate' | 'exact' | undefined,
+      });
+      return { kind: 'state', data: result.data, text: result.text };
+    },
+  },
+  {
+    name: 'get_electional_context',
+    description:
+      'Get stateless electional context for a specific local date, time, and location. Returns deterministic timing facts such as ascendant, sect/day-night classification, Moon phase, applying aspects, and optional ascendant-ruler basics. This tool does not require a natal chart and is separate from get_transits.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        date: {
+          type: 'string',
+          description: 'Target local date (YYYY-MM-DD)',
+        },
+        time: {
+          type: 'string',
+          description:
+            'Target local time (HH:mm or HH:mm:ss). DST-ambiguous or nonexistent local times are rejected.',
+        },
+        timezone: {
+          type: 'string',
+          description: 'IANA timezone (e.g., America/New_York)',
+        },
+        latitude: { type: 'number', description: 'Latitude in decimal degrees (-90 to 90)' },
+        longitude: {
+          type: 'number',
+          description: 'Longitude in decimal degrees (-180 to 180)',
+        },
+        house_system: {
+          type: 'string',
+          enum: ['P', 'K', 'W', 'R'],
+          description:
+            'House system used for ascendant extraction: P=Placidus (default), K=Koch, W=Whole Sign, R=Regiomontanus.',
+        },
+        include_ruler_basics: {
+          type: 'boolean',
+          description:
+            'Include ascendant-ruler position, speed, and retrograde flag. Defaults to false.',
+        },
+        include_planetary_applications: {
+          type: 'boolean',
+          description: 'Include applying major aspects between current planets. Defaults to true.',
+        },
+        orb_degrees: {
+          type: 'number',
+          description:
+            'Orb for electional aspect detection in degrees. Defaults to 3 and must be between 0.1 and 10.',
+          default: 3,
+        },
+      },
+      required: ['date', 'time', 'timezone', 'latitude', 'longitude'],
+    },
+    requiresNatalChart: false,
+    execute: (ctx, args) => {
+      const result = ctx.service.getElectionalContext({
+        date: args.date as string,
+        time: args.time as string,
+        timezone: args.timezone as string,
+        latitude: args.latitude as number,
+        longitude: args.longitude as number,
+        house_system: args.house_system as ElectionalHouseSystem | undefined,
+        include_ruler_basics: args.include_ruler_basics as boolean | undefined,
+        include_planetary_applications: args.include_planetary_applications as boolean | undefined,
+        orb_degrees: args.orb_degrees as number | undefined,
+      });
+      return { kind: 'state', data: result.data, text: result.text };
+    },
+  },
   {
     name: 'get_transits',
     description:
-      'Get transits (aspects between current/future planets and natal chart). Returns aspects within orb, with exact timing when close. Date defaults to today at local noon in the natal chart timezone.',
+      'Get transits (aspects between current/future planets and natal chart). Each transit includes additive placement metadata for both sides (sign, degree, house) so clients can render activation context without reconstructing house logic. Supports mode=snapshot (single-day), mode=best_hit (multi-day compressed preview), and mode=forecast (day-grouped output). If mode is omitted, legacy behavior is preserved: days_ahead=0 resolves to snapshot and days_ahead>0 resolves to best_hit.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -116,9 +223,15 @@ export const MCP_TOOL_SPECS: ToolSpec[] = [
         days_ahead: {
           type: 'number',
           description:
-            'Number of days to look ahead for upcoming transits. 0 = today only. Defaults to 0.',
+            'Number of days to look ahead. In snapshot mode only the start day is used. If mode is omitted, legacy behavior is preserved: 0 resolves to snapshot and values > 0 resolve to best_hit.',
           default: 0,
         },
+        mode: {
+          type: 'string',
+          enum: ['snapshot', 'best_hit', 'forecast'],
+          description:
+            'Transit output mode: snapshot=single-day, best_hit=compressed preview across range, forecast=day-grouped output. If omitted, legacy behavior is preserved.',
+        },
         max_orb: {
           type: 'number',
           description: 'Maximum orb in degrees to include. Defaults to 8.',
@@ -142,6 +255,7 @@ export const MCP_TOOL_SPECS: ToolSpec[] = [
         categories: args.categories as string[] | undefined,
         include_mundane: args.include_mundane as boolean | undefined,
         days_ahead: args.days_ahead as number | undefined,
+        mode: args.mode as 'snapshot' | 'best_hit' | 'forecast' | undefined,
         max_orb: args.max_orb as number | undefined,
         exact_only: args.exact_only as boolean | undefined,
         applying_only: args.applying_only as boolean | undefined,
@@ -178,8 +292,10 @@ export const MCP_TOOL_SPECS: ToolSpec[] = [
     inputSchema: { type: 'object', properties: {} },
     requiresNatalChart: false,
     execute: (ctx, args) => {
-      const timezone =
-        (args.timezone as string | undefined) ?? ctx.natalChart?.location.timezone ?? 'UTC';
+      const timezone = ctx.service.resolveReportingTimezone(
+        args.timezone as string | undefined,
+        ctx.natalChart?.location?.timezone
+      );
       const result = ctx.service.getRetrogradePlanets(timezone);
       return { kind: 'state', data: result.data, text: result.text };
     },
@@ -200,8 +316,10 @@ export const MCP_TOOL_SPECS: ToolSpec[] = [
     inputSchema: { type: 'object', properties: {} },
     requiresNatalChart: false,
     execute: (ctx, args) => {
-      const timezone =
-        (args.timezone as string | undefined) ?? ctx.natalChart?.location.timezone ?? 'UTC';
+      const timezone = ctx.service.resolveReportingTimezone(
+        args.timezone as string | undefined,
+        ctx.natalChart?.location?.timezone
+      );
       const result = ctx.service.getAsteroidPositions(timezone);
       return { kind: 'state', data: result.data, text: result.text };
     },
@@ -212,8 +330,10 @@ export const MCP_TOOL_SPECS: ToolSpec[] = [
     inputSchema: { type: 'object', properties: {} },
     requiresNatalChart: false,
     execute: (ctx, args) => {
-      const timezone =
-        (args.timezone as string | undefined) ?? ctx.natalChart?.location.timezone ?? 'UTC';
+      const timezone = ctx.service.resolveReportingTimezone(
+        args.timezone as string | undefined,
+        ctx.natalChart?.location?.timezone
+      );
       const result = ctx.service.getNextEclipses(timezone);
       return { kind: 'state', data: result.data, text: result.text };
     },

package/src/tool-result.ts

@@ -189,6 +189,50 @@ export function mapSweError(
   };
 }
 
+/**
+ * Map generic error messages to structured tool issue codes.
+ *
+ * @remarks
+ * Primarily used at the MCP boundary when unknown errors are caught
+ * and need a best-effort classification.
+ */
+export function mapToolErrorMessageToCode(errorMessage: string): ToolIssueCode {
+  if (
+    errorMessage.includes('Invalid date format') ||
+    errorMessage.includes('Invalid calendar date') ||
+    errorMessage.includes('Invalid month') ||
+    errorMessage.includes('Invalid day') ||
+    errorMessage.includes('days_ahead') ||
+    errorMessage.includes('max_orb') ||
+    errorMessage.includes('missing julianDay') ||
+    errorMessage.includes('Invalid mode') ||
+    errorMessage.includes('Invalid latitude') ||
+    errorMessage.includes('Invalid longitude')
+  ) {
+    return 'INVALID_INPUT';
+  }
+  if (errorMessage.includes('Invalid timezone') || errorMessage.includes('timezone')) {
+    return 'INVALID_TIMEZONE';
+  }
+  if (errorMessage.includes('Invalid house system')) {
+    return 'INVALID_HOUSE_SYSTEM';
+  }
+  if (errorMessage.includes('Ephemeris') || errorMessage.includes('ephemeris')) {
+    return 'EPHEMERIS_COMPUTE_FAILED';
+  }
+  if (
+    errorMessage.includes('write') ||
+    errorMessage.includes('ENOENT') ||
+    errorMessage.includes('EACCES')
+  ) {
+    return 'FILE_WRITE_FAILED';
+  }
+  if (errorMessage.includes('render') || errorMessage.includes('chart')) {
+    return 'CHART_RENDER_FAILED';
+  }
+  return 'INTERNAL_ERROR';
+}
+
 /**
  * Create a structured error for missing rise/set events
  *

package/src/types.ts

@@ -86,6 +86,12 @@ export interface NatalChart {
    * For polar latitudes (>66°), Whole Sign ('W') may be used as fallback.
    */
   houseSystem?: HouseSystem;
+  /**
+   * Explicit house system requested when the natal chart was created
+   * @remarks
+   * This stays undefined when the caller relied on runtime defaults.
+   */
+  requestedHouseSystem?: HouseSystem;
   /**
    * UTC equivalent of birth time
    * @remarks
@@ -217,6 +223,18 @@ export interface TransitData extends BaseTransit {
    * May be undefined if aspect is not within orb or exact time not calculated
    */
   exactTime?: string; // ISO timestamp
+  /** Zodiac sign of the transiting planet */
+  transitSign?: string;
+  /** Degree of the transiting planet within its sign (0-30) */
+  transitDegree?: number;
+  /** House occupied by the transiting planet at the transit calculation time */
+  transitHouse?: number;
+  /** Zodiac sign of the natal planet */
+  natalSign?: string;
+  /** Degree of the natal planet within its sign (0-30) */
+  natalDegree?: number;
+  /** House occupied by the natal planet in the natal chart */
+  natalHouse?: number;
 }
 
 /**
@@ -229,8 +247,12 @@ export interface TransitData extends BaseTransit {
 export interface TransitResponse {
   /** ISO date of the transit calculation (YYYY-MM-DD) */
   date: string;
-  /** Timezone used for the calculation */
+  /** Timezone used for reporting and user-facing day labels */
   timezone: string;
+  /** Natal/local timezone used for date interpretation and astro calculations */
+  calculation_timezone?: string;
+  /** Timezone used for reporting and user-facing day labels */
+  reporting_timezone?: string;
   /** Array of all active transits for the date */
   transits: TransitData[];
 }
@@ -250,6 +272,8 @@ export interface PlanetPositionResponse {
   positions: PlanetPosition[];
 }
 
+export type ElectionalHouseSystem = Extract<HouseSystem, 'P' | 'K' | 'W' | 'R'>;
+
 /**
  * Types of astrological aspects
  *
@@ -259,6 +283,72 @@ export interface PlanetPositionResponse {
  */
 export type AspectType = 'conjunction' | 'opposition' | 'square' | 'trine' | 'sextile';
 
+export type ElectionalPhaseName =
+  | 'new'
+  | 'crescent'
+  | 'first_quarter'
+  | 'gibbous'
+  | 'full'
+  | 'disseminating'
+  | 'last_quarter'
+  | 'balsamic';
+
+export interface ElectionalAspect {
+  from_body: PlanetName;
+  to_body: PlanetName;
+  aspect: AspectType;
+  orb: number;
+  applying: boolean;
+  exact_at_utc?: string;
+}
+
+export interface ElectionalContextResponse {
+  input: {
+    date: string;
+    time: string;
+    timezone: string;
+    latitude: number;
+    longitude: number;
+    house_system: ElectionalHouseSystem;
+    instant_utc: string;
+    jd_ut: number;
+  };
+  ascendant: {
+    longitude: number;
+    sign: string;
+    degree_in_sign: number;
+  };
+  sect: {
+    is_day_chart: boolean;
+    sun_altitude_degrees: number;
+    classification: 'day' | 'night';
+  };
+  moon: {
+    longitude: number;
+    sign: string;
+    phase_angle: number;
+    phase_name: ElectionalPhaseName;
+    is_void_of_course: boolean | null;
+    applying_aspects?: ElectionalAspect[];
+  };
+  applying_aspects?: ElectionalAspect[];
+  ruler_basics?: {
+    asc_sign_ruler: {
+      body: PlanetName;
+      longitude: number;
+      sign: string;
+      speed: number;
+      is_retrograde: boolean;
+    };
+  };
+  meta: {
+    deterministic: true;
+    requires_natal: false;
+    warnings: string[];
+    deferred_features: string[];
+  };
+}
+
 /**
  * Aspect definitions with angles and default orbs
  *