ether-to-astro 1.1.0 → 1.2.0

package/SETUP.md

@@ -1,82 +1,129 @@
-# Quick Setup Guide
+# Setup Guide
 
-## Installation
+This guide is for using `ether-to-astro` as a product, not for local development on the repo itself.
 
-```bash
-./setup.sh
-```
+For contributor setup, local builds, tests, and release workflow, see [DEVELOPER.md](/Users/salted/Code/astro-mcp/DEVELOPER.md).
 
-This will:
-1. Install npm dependencies (including native `sweph`)
-2. Build TypeScript to JavaScript
+## Quick Start
 
-## Add to Claude Desktop
+### Use as an MCP server
 
-Edit your Claude Desktop config file:
-- **Mac**: `~/Library/Application Support/Claude/claude_desktop_config.json`
-- **Linux**: `~/.config/Claude/claude_desktop_config.json`
-
-Add this MCP server:
+Add this to your MCP client config:
 
 ```json
 {
   "mcpServers": {
     "astro": {
       "command": "npx",
-      "args": ["--yes", "--package=ether-to-astro", "e2a-mcp"]
+      "args": ["--yes", "--package=ether-to-astro", "e2a", "--mcp"]
     }
   }
 }
 ```
 
-Alternative (after global install):
+Alternative after global install:
 
 ```json
 {
   "mcpServers": {
     "astro": {
-      "command": "e2a-mcp"
+      "command": "e2a",
+      "args": ["--mcp"]
     }
   }
 }
 ```
 
-## First Use
+Then restart your MCP client and call `set_natal_chart` before requesting transits or charts.
 
-1. Restart Claude Desktop
-2. Set your wife's natal chart:
+### Use as a CLI
 
+Run directly with `npx`:
+
+```bash
+npx --yes --package=ether-to-astro e2a --help
 ```
-Please set my natal chart:
-- Name: [Name]
-- Birth: [Month] [Day], [Year] at [Hour]:[Minute] 
-- Location: [City] ([Latitude], [Longitude])
-- Timezone: [e.g., America/Los_Angeles]
+
+Or install globally:
+
+```bash
+npm install -g ether-to-astro
+e2a --help
+e2a --mcp --help
 ```
 
-3. Query transits:
+## Notes
+
+- You do not need to run `npm run build` when installing from npm.
+- `npx e2a` does not work by itself because npm resolves package names first. Use `npx --package=ether-to-astro e2a`.
+- The package downloads Swiss Ephemeris data during install unless you choose `EPHEMERIS_VERSION=moshier`.
+
+## Ephemeris Data Options
+
+The package downloads Swiss Ephemeris data files during installation. You can control which version with `EPHEMERIS_VERSION`.
 
+- `long` (default): 6000 years, recommended for professional use
+- `short`: 600 years, smaller download for modern charts
+- `moshier`: no ephemeris download, lower precision fallback
+
+Examples:
+
+```bash
+npm install -g ether-to-astro
+EPHEMERIS_VERSION=short npm install -g ether-to-astro
+EPHEMERIS_VERSION=moshier npm install -g ether-to-astro
 ```
-What are my transits today?
-Show me upcoming transits this week
-When will the Moon conjunct my Venus be exact?
+
+## First Use
+
+Typical flow:
+
+1. Start the MCP server or use the CLI.
+2. Set the natal chart.
+3. Request transits, houses, or chart rendering.
+
+Example CLI call:
+
+```bash
+npx --yes --package=ether-to-astro e2a set-natal-chart \
+  --name "Test" \
+  --year 1990 \
+  --month 1 \
+  --day 1 \
+  --hour 12 \
+  --minute 0 \
+  --latitude 40.7 \
+  --longitude -74.0 \
+  --timezone America/New_York
 ```
 
-## MCP Tools Available
+Then:
 
-- `set_natal_chart` - Store birth data
-- `get_transits` - Category-filtered transit analysis with optional exact-time data
-- `get_houses` - House cusps plus angles (ASC/MC)
-- `get_retrograde_planets` - Current retrograde status
-- `get_rise_set_times` - Rise/set and meridian events
-- `get_asteroid_positions` - Asteroids and nodes
-- `get_next_eclipses` - Next solar/lunar eclipses
-- `generate_natal_chart` - Render natal chart (SVG/PNG/WebP)
-- `generate_transit_chart` - Render transit chart (SVG/PNG/WebP)
-- `get_server_status` - MCP-side loaded-chart and service status
+```bash
+npx --yes --package=ether-to-astro e2a get-transits --natal-file ./natal.json --date 2026-03-27 --pretty
+```
+
+## Product Surfaces
+
+- `e2a --mcp`: canonical stateful MCP server launch
+- `e2a-mcp`: compatibility alias for MCP launch
+- `e2a`: stateless CLI
 
-## Technical Notes
+Optional MCP startup defaults:
+
+```bash
+e2a --mcp --preferred-tz America/Los_Angeles --preferred-house-style W --weekday-labels
+```
 
-- Uses native `sweph` bindings for Swiss Ephemeris calculations
-- Ephemeris files are downloaded/configured during install
-- Works on macOS/Linux (Node.js 22+)
+## Available Tools
+
+- `set_natal_chart`
+- `get_transits`
+- `get_houses`
+- `get_retrograde_planets`
+- `get_rise_set_times`
+- `get_asteroid_positions`
+- `get_next_eclipses`
+- `generate_natal_chart`
+- `generate_transit_chart`
+- `get_server_status`

package/dist/astro-service.d.ts

@@ -1,11 +1,12 @@
 import { ChartRenderer } from './charts.js';
 import { EclipseCalculator } from './eclipses.js';
+import type { McpStartupDefaults } from './entrypoint.js';
 import { EphemerisCalculator } from './ephemeris.js';
 import { HouseCalculator } from './houses.js';
 import { RiseSetCalculator } from './riseset.js';
 import { type Disambiguation } from './time-utils.js';
 import { TransitCalculator } from './transits.js';
-import { type HouseSystem, type NatalChart } from './types.js';
+import { type AspectType, type ElectionalHouseSystem, type HouseSystem, type NatalChart, type PlanetPosition } from './types.js';
 interface AstroServiceDependencies {
     ephem?: EphemerisCalculator;
     transitCalc?: TransitCalculator;
@@ -13,6 +14,7 @@ interface AstroServiceDependencies {
     riseSetCalc?: RiseSetCalculator;
     eclipseCalc?: EclipseCalculator;
     chartRenderer?: ChartRenderer;
+    mcpStartupDefaults?: McpStartupDefaults;
     now?: () => Date;
     writeFile?: (path: string, data: string | Buffer, encoding?: BufferEncoding) => Promise<void>;
 }
@@ -34,13 +36,32 @@ export interface GetTransitsInput {
     categories?: string[];
     include_mundane?: boolean;
     days_ahead?: number;
+    mode?: 'snapshot' | 'best_hit' | 'forecast';
     max_orb?: number;
     exact_only?: boolean;
     applying_only?: boolean;
 }
+export interface GetElectionalContextInput {
+    date: string;
+    time: string;
+    timezone: string;
+    latitude: number;
+    longitude: number;
+    house_system?: ElectionalHouseSystem;
+    include_ruler_basics?: boolean;
+    include_planetary_applications?: boolean;
+    orb_degrees?: number;
+}
 export interface GetHousesInput {
     system?: string;
 }
+export interface GetRisingSignWindowsInput {
+    date: string;
+    latitude: number;
+    longitude: number;
+    timezone: string;
+    mode?: 'approximate' | 'exact';
+}
 export interface GenerateChartInput {
     theme?: 'light' | 'dark';
     format?: 'svg' | 'png' | 'webp';
@@ -53,7 +74,17 @@ export interface ServiceResult<T> {
     data: T;
     text: string;
 }
-export interface ChartServiceResult {
+export interface MundaneAspect {
+    id: string;
+    planetA: PlanetPosition['planet'];
+    planetB: PlanetPosition['planet'];
+    aspect: AspectType;
+    orb: number;
+    isApplying: boolean;
+    longitudeA: number;
+    longitudeB: number;
+}
+interface ChartServiceResult {
     format: 'svg' | 'png' | 'webp';
     outputPath?: string;
     text: string;
@@ -77,16 +108,34 @@ export declare class AstroService {
     readonly riseSetCalc: RiseSetCalculator;
     readonly eclipseCalc: EclipseCalculator;
     readonly chartRenderer: ChartRenderer;
+    readonly mcpStartupDefaults: Readonly<McpStartupDefaults>;
     private readonly now;
     private readonly writeFileFn;
     constructor(deps?: AstroServiceDependencies);
+    private formatTimestamp;
+    private normalizeLongitude;
+    private getSignAndDegree;
+    private getHouseNumber;
+    private resolveHouseSystem;
+    private resolveTimezones;
+    resolveReportingTimezone(explicitTimezone?: string, natalTimezone?: string): string;
     init(): Promise<void>;
     isInitialized(): boolean;
     setNatalChart(input: SetNatalChartInput): ServiceResult<Record<string, unknown>> & {
         chart: NatalChart;
     };
     getTransits(natalChart: NatalChart, input?: GetTransitsInput): ServiceResult<Record<string, unknown>>;
+    private getMundaneWeather;
+    private getMundaneAspects;
+    private getMundaneDay;
+    getElectionalContext(input: GetElectionalContextInput): ServiceResult<Record<string, unknown>>;
     getHouses(natalChart: NatalChart, input?: GetHousesInput): ServiceResult<Record<string, unknown>>;
+    getRisingSignWindows(input: GetRisingSignWindowsInput): ServiceResult<Record<string, unknown>>;
+    private getElectionalApplyingAspects;
+    private isElectionalAspectApplying;
+    private getSignedAngularDifference;
+    private getElectionalPhaseName;
+    private getTraditionalSignRuler;
     getRetrogradePlanets(timezone?: string): ServiceResult<Record<string, unknown>>;
     getRiseSetTimes(natalChart: NatalChart): Promise<ServiceResult<Record<string, unknown>>>;
     getAsteroidPositions(timezone?: string): ServiceResult<Record<string, unknown>>;