ether-to-astro 1.0.2 → 1.2.0

package/src/cli.ts

@@ -56,11 +56,25 @@ interface TransitOptions extends SharedOptions {
   categories?: string;
   includeMundane?: boolean;
   daysAhead?: string;
+  mode?: 'snapshot' | 'best_hit' | 'forecast';
   maxOrb?: string;
   exactOnly?: boolean;
   applyingOnly?: boolean;
 }
 
+interface ElectionalContextOptions {
+  date?: string;
+  time?: string;
+  timezone?: string;
+  latitude?: string;
+  longitude?: string;
+  houseSystem?: 'P' | 'K' | 'W' | 'R';
+  includeRulerBasics?: boolean;
+  planetaryApplications?: boolean;
+  orbDegrees?: string;
+  pretty?: boolean;
+}
+
 interface HousesOptions extends SharedOptions {
   system?: string;
 }
@@ -441,6 +455,69 @@ export async function runCli(
       emitExecution(io, result, options.pretty ?? false);
     });
 
+  program
+    .command('get-electional-context')
+    .description(mustTool('get_electional_context').description)
+    .requiredOption(
+      '--date <yyyy-mm-dd>',
+      toolSchemaProperty('get_electional_context', 'date').description ?? 'Target local date'
+    )
+    .requiredOption(
+      '--time <hh:mm[:ss]>',
+      toolSchemaProperty('get_electional_context', 'time').description ?? 'Target local time'
+    )
+    .requiredOption(
+      '--timezone <tz>',
+      toolSchemaProperty('get_electional_context', 'timezone').description ?? 'Timezone'
+    )
+    .requiredOption(
+      '--latitude <number>',
+      toolSchemaProperty('get_electional_context', 'latitude').description ?? 'Latitude'
+    )
+    .requiredOption(
+      '--longitude <number>',
+      toolSchemaProperty('get_electional_context', 'longitude').description ?? 'Longitude'
+    )
+    .addOption(
+      new Option(
+        '--house-system <system>',
+        toolSchemaProperty('get_electional_context', 'house_system').description ?? 'House system'
+      ).choices(['P', 'K', 'W', 'R'])
+    )
+    .option(
+      '--include-ruler-basics',
+      toolSchemaProperty('get_electional_context', 'include_ruler_basics').description ??
+        'Include ascendant-ruler basics'
+    )
+    .option(
+      '--no-planetary-applications',
+      'Exclude applying major aspects from the electional context response'
+    )
+    .option(
+      '--orb-degrees <number>',
+      toolSchemaProperty('get_electional_context', 'orb_degrees').description ?? 'Aspect orb'
+    )
+    .option('--pretty', 'Human-readable output instead of JSON')
+    .action(async (options: ElectionalContextOptions) => {
+      const spec = mustTool('get_electional_context');
+      const result = await spec.execute(
+        { service, natalChart: null },
+        {
+          date: options.date,
+          time: options.time,
+          timezone: options.timezone,
+          latitude: toNumber(options.latitude, 'latitude'),
+          longitude: toNumber(options.longitude, 'longitude'),
+          house_system: options.houseSystem,
+          include_ruler_basics: options.includeRulerBasics,
+          include_planetary_applications: options.planetaryApplications,
+          orb_degrees:
+            options.orbDegrees == null ? undefined : toNumber(options.orbDegrees, 'orb-degrees'),
+        }
+      );
+      emitExecution(io, result, options.pretty ?? false);
+    });
+
   const profiles = program
     .command('profiles')
     .description('Inspect and validate CLI profile files');
@@ -533,6 +610,12 @@ export async function runCli(
       '--days-ahead <number>',
       toolSchemaProperty('get_transits', 'days_ahead').description ?? 'Days ahead'
     )
+    .addOption(
+      new Option(
+        '--mode <mode>',
+        toolSchemaProperty('get_transits', 'mode').description ?? 'Transit mode'
+      ).choices(['snapshot', 'best_hit', 'forecast'])
+    )
     .option(
       '--max-orb <number>',
       toolSchemaProperty('get_transits', 'max_orb').description ?? 'Max orb'
@@ -557,6 +640,7 @@ export async function runCli(
           include_mundane: options.includeMundane,
           days_ahead:
             options.daysAhead == null ? undefined : toNumber(options.daysAhead, 'days-ahead'),
+          mode: options.mode,
           max_orb: options.maxOrb == null ? undefined : toNumber(options.maxOrb, 'max-orb'),
           exact_only: options.exactOnly,
           applying_only: options.applyingOnly,

package/src/entrypoint.ts

@@ -0,0 +1,118 @@
+import path from 'node:path';
+import { isValidTimezone } from './time-utils.js';
+import type { HouseSystem } from './types.js';
+
+export interface McpStartupDefaults {
+  preferredTimezone?: string;
+  preferredHouseStyle?: HouseSystem;
+  weekdayLabels?: boolean;
+}
+
+export interface EntrypointResolution {
+  mode: 'cli' | 'mcp';
+  cliArgv: string[];
+  mcpHelpRequested: boolean;
+  mcpStartupDefaults: Readonly<McpStartupDefaults>;
+}
+
+const VALID_HOUSE_STYLES = new Set<HouseSystem>(['P', 'W', 'K', 'E']);
+
+function readOptionValue(argv: string[], index: number, flag: string) {
+  const current = argv[index];
+  const prefix = `${flag}=`;
+  if (current.startsWith(prefix)) {
+    return {
+      value: current.slice(prefix.length),
+      nextIndex: index,
+    };
+  }
+
+  const next = argv[index + 1];
+  if (next === undefined || next.startsWith('--')) {
+    throw new Error(`Missing value for ${flag}`);
+  }
+  return {
+    value: next,
+    nextIndex: index + 1,
+  };
+}
+
+export function resolveEntrypoint(
+  argv: string[],
+  invokedPath = process.argv[1] ?? ''
+): EntrypointResolution {
+  let mode: 'cli' | 'mcp' = path.basename(invokedPath).startsWith('e2a-mcp') ? 'mcp' : 'cli';
+  const cliArgv: string[] = [];
+  const defaults: McpStartupDefaults = {};
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+
+    if (arg === '--mcp') {
+      mode = 'mcp';
+      continue;
+    }
+
+    if (arg === '--weekday-labels') {
+      defaults.weekdayLabels = true;
+      continue;
+    }
+
+    if (arg === '--no-weekday-labels') {
+      defaults.weekdayLabels = false;
+      continue;
+    }
+
+    if (arg === '--preferred-tz' || arg.startsWith('--preferred-tz=')) {
+      const { value, nextIndex } = readOptionValue(argv, i, '--preferred-tz');
+      defaults.preferredTimezone = value;
+      i = nextIndex;
+      continue;
+    }
+
+    if (arg === '--preferred-house-style' || arg.startsWith('--preferred-house-style=')) {
+      const { value, nextIndex } = readOptionValue(argv, i, '--preferred-house-style');
+      defaults.preferredHouseStyle = value as HouseSystem;
+      i = nextIndex;
+      continue;
+    }
+
+    cliArgv.push(arg);
+  }
+
+  const usedMcpOnlyFlag =
+    defaults.preferredTimezone !== undefined ||
+    defaults.preferredHouseStyle !== undefined ||
+    defaults.weekdayLabels !== undefined;
+  if (mode !== 'mcp' && usedMcpOnlyFlag) {
+    throw new Error(
+      'MCP startup defaults require MCP mode. Use e2a --mcp, or launch via the e2a-mcp compatibility alias.'
+    );
+  }
+
+  if (defaults.preferredTimezone && !isValidTimezone(defaults.preferredTimezone)) {
+    throw new Error(`Invalid timezone: ${defaults.preferredTimezone}`);
+  }
+
+  if (defaults.preferredHouseStyle && !VALID_HOUSE_STYLES.has(defaults.preferredHouseStyle)) {
+    throw new Error(
+      `Invalid preferred house style: ${defaults.preferredHouseStyle} (must be one of P, W, K, E)`
+    );
+  }
+
+  const mcpHelpRequested =
+    mode === 'mcp' &&
+    cliArgv.length > 0 &&
+    cliArgv.every((arg) => arg === '--help' || arg === '-h');
+
+  if (mode === 'mcp' && cliArgv.length > 0 && !mcpHelpRequested) {
+    throw new Error(`Unexpected CLI arguments in MCP mode: ${cliArgv.join(' ')}`);
+  }
+
+  return {
+    mode,
+    cliArgv,
+    mcpHelpRequested,
+    mcpStartupDefaults: Object.freeze({ ...defaults }),
+  };
+}

package/src/ephemeris.ts

@@ -200,6 +200,50 @@ export class EphemerisCalculator {
     return diff;
   }
 
+  /**
+   * Convert ecliptic coordinates to local horizontal coordinates
+   *
+   * @param jd - Julian Day in UT
+   * @param position - Planetary ecliptic coordinates
+   * @param longitude - Observer longitude in degrees
+   * @param latitude - Observer latitude in degrees
+   * @param altitude - Observer altitude in meters (default: 0)
+   * @returns Horizontal coordinates including true and apparent altitude
+   */
+  getHorizontalCoordinates(
+    jd: number,
+    position: Pick<PlanetPosition, 'longitude' | 'latitude' | 'distance'>,
+    longitude: number,
+    latitude: number,
+    altitude: number = 0
+  ): { azimuth: number; trueAltitude: number; apparentAltitude: number } {
+    if (!this.eph) throw new Error('Ephemeris not initialized');
+    if (!Number.isFinite(jd)) {
+      throw new Error(`Invalid Julian Day: ${jd} (must be finite)`);
+    }
+    if (!Number.isFinite(longitude) || !Number.isFinite(latitude) || !Number.isFinite(altitude)) {
+      throw new Error(
+        'Invalid geographic coordinates: longitude, latitude, and altitude must be finite'
+      );
+    }
+
+    const result = this.eph.azalt(jd, Constants.SE_ECL2HOR, [longitude, latitude, altitude], 0, 0, [
+      position.longitude,
+      position.latitude,
+      position.distance,
+    ]);
+
+    if (!Array.isArray(result) || result.length < 3) {
+      throw new Error('Failed to calculate horizontal coordinates');
+    }
+
+    return {
+      azimuth: result[0],
+      trueAltitude: result[1],
+      apparentAltitude: result[2],
+    };
+  }
+
   /**
    * Find all exact times when planet reaches a specific longitude
    *

package/src/formatter.ts

@@ -1,4 +1,12 @@
-export function formatInTimezone(date: Date, timezone: string): string {
+interface FormatInTimezoneOptions {
+  weekday?: boolean;
+}
+
+export function formatInTimezone(
+  date: Date,
+  timezone: string,
+  formatOptions: FormatInTimezoneOptions = {}
+): string {
   const options: Intl.DateTimeFormatOptions = {
     timeZone: timezone,
     year: 'numeric',
@@ -10,6 +18,10 @@ export function formatInTimezone(date: Date, timezone: string): string {
     timeZoneName: 'short',
   };
 
+  if (formatOptions.weekday) {
+    options.weekday = 'short';
+  }
+
   return new Intl.DateTimeFormat('en-US', options).format(date);
 }
 

package/src/index.ts

@@ -16,142 +16,98 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { AstroService } from './astro-service.js';
+import type { McpStartupDefaults } from './entrypoint.js';
 import { logger } from './logger.js';
 import { getToolSpec, MCP_TOOL_SPECS } from './tool-registry.js';
-import { mcpError, mcpResult, missingNatalChart } from './tool-result.js';
+import {
+  mapToolErrorMessageToCode,
+  mcpError,
+  mcpResult,
+  missingNatalChart,
+} from './tool-result.js';
 import type { NatalChart } from './types.js';
 
-const server = new Server(
-  {
-    name: 'e2a-mcp',
-    version: '1.0.0',
-  },
-  {
-    capabilities: {
-      tools: {},
+function createServer(startupDefaults: Readonly<McpStartupDefaults> = {}) {
+  const server = new Server(
+    {
+      name: 'e2a-mcp',
+      version: '1.0.0',
     },
-  }
-);
-
-/**
- * In-memory natal chart — the server's sole piece of mutable state.
- *
- * Lifecycle:
- *  - Starts as `null` when the process launches.
- *  - Set by `set_natal_chart`; overwritten on each call.
- *  - Persists for the lifetime of this stdio process (one per MCP client).
- *  - Tools that require it (`get_transits`, `get_houses`, `get_rise_set_times`,
- *    `generate_natal_chart`, `generate_transit_chart`) return a structured
- *    MISSING_NATAL_CHART error if it is null.
- *  - Use `get_server_status` to inspect whether a chart is loaded.
- *
- * Thread safety: Each MCP client connection spawns a separate Node.js process
- * via stdio transport, so this variable is isolated per client.
- * No synchronization needed as requests are serialized within a single process.
- */
-let natalChart: NatalChart | null = null;
-
-// Calculator instances (initialized on demand)
-const astroService = new AstroService();
-
-server.setRequestHandler(ListToolsRequestSchema, async () => {
-  return {
-    tools: MCP_TOOL_SPECS.map((spec) => ({
-      name: spec.name,
-      description: spec.description,
-      inputSchema: spec.inputSchema,
-    })),
-  };
-});
-
-/**
- * Handle MCP tool requests
- *
- * @param request - The MCP tool request
- * @returns Tool response with data or error
- * @throws Error for unhandled tools
- *
- * @remarks
- * Routes requests to appropriate handlers. Initializes ephemeris on first use.
- * All handlers return structured responses suitable for MCP clients.
- */
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-  const { name, arguments: args = {} } = request.params;
-
-  try {
-    const spec = getToolSpec(name);
-    if (!spec) {
-      return mcpError({
-        code: 'INVALID_INPUT',
-        message: `Unknown tool: ${name}`,
-        retryable: false,
-        suggestedFix: 'Check the tool name against the list returned by ListTools.',
-      });
+    {
+      capabilities: {
+        tools: {},
+      },
     }
+  );
+
+  let natalChart: NatalChart | null = null;
+  const astroService = new AstroService({ mcpStartupDefaults: startupDefaults });
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+      tools: MCP_TOOL_SPECS.map((spec) => ({
+        name: spec.name,
+        description: spec.description,
+        inputSchema: spec.inputSchema,
+      })),
+    };
+  });
 
-    if (spec.requiresNatalChart && !natalChart) {
-      return mcpError(missingNatalChart());
-    }
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args = {} } = request.params;
+
+    try {
+      const spec = getToolSpec(name);
+      if (!spec) {
+        return mcpError({
+          code: 'INVALID_INPUT',
+          message: `Unknown tool: ${name}`,
+          retryable: false,
+          suggestedFix: 'Check the tool name against the list returned by ListTools.',
+        });
+      }
 
-    const result = await spec.execute(
-      {
-        service: astroService,
-        natalChart,
-      },
-      args as Record<string, unknown>
-    );
+      if (spec.requiresNatalChart && !natalChart) {
+        return mcpError(missingNatalChart());
+      }
 
-    if (result.kind === 'state') {
-      if (result.natalChart !== undefined) {
-        natalChart = result.natalChart;
+      const result = await spec.execute(
+        {
+          service: astroService,
+          natalChart,
+        },
+        args as Record<string, unknown>
+      );
+
+      if (result.kind === 'state') {
+        if (result.natalChart !== undefined) {
+          natalChart = result.natalChart;
+        }
+        return mcpResult(result.data, result.text);
       }
-      return mcpResult(result.data, result.text);
-    }
 
-    return { content: result.content };
-  } catch (error) {
-    const errorMessage = error instanceof Error ? error.message : String(error);
+      return { content: result.content };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      const code = mapToolErrorMessageToCode(errorMessage);
 
-    // Map known error patterns to appropriate codes
-    let code: import('./tool-result.js').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')
-    ) {
-      code = 'INVALID_INPUT';
-    } else if (errorMessage.includes('Invalid timezone') || errorMessage.includes('timezone')) {
-      code = 'INVALID_TIMEZONE';
-    } else if (errorMessage.includes('Invalid house system')) {
-      code = 'INVALID_HOUSE_SYSTEM';
-    } else if (errorMessage.includes('Ephemeris') || errorMessage.includes('ephemeris')) {
-      code = 'EPHEMERIS_COMPUTE_FAILED';
-    } else if (
-      errorMessage.includes('write') ||
-      errorMessage.includes('ENOENT') ||
-      errorMessage.includes('EACCES')
-    ) {
-      code = 'FILE_WRITE_FAILED';
-    } else if (errorMessage.includes('render') || errorMessage.includes('chart')) {
-      code = 'CHART_RENDER_FAILED';
-    } else {
-      code = 'INTERNAL_ERROR';
+      return mcpError({
+        code,
+        message: errorMessage,
+        retryable: code === 'EPHEMERIS_COMPUTE_FAILED' || code === 'FILE_WRITE_FAILED',
+        details: { tool: name },
+      });
     }
+  });
 
-    return mcpError({
-      code,
-      message: errorMessage,
-      retryable: code === 'EPHEMERIS_COMPUTE_FAILED' || code === 'FILE_WRITE_FAILED',
-      details: { tool: name },
-    });
-  }
-});
+  return {
+    server,
+    astroService,
+  };
+}
 
-export async function main() {
+export async function main(startupDefaults: Readonly<McpStartupDefaults> = {}) {
+  const { server, astroService } = createServer(startupDefaults);
   logger.info('Initializing Swiss Ephemeris');
   await astroService.init();
   logger.info('Ephemeris initialized');

package/src/loader.ts

@@ -4,33 +4,77 @@ import { readFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 // Set up browser globals for astrochart library BEFORE any imports
 import { JSDOM } from 'jsdom';
+import { resolveEntrypoint } from './entrypoint.js';
 
-const dom = new JSDOM('<!DOCTYPE html><html><body></body></html>');
-(globalThis as any).window = dom.window;
-(globalThis as any).document = dom.window.document;
-(globalThis as any).self = globalThis; // Critical: astrochart checks for 'self' - see https://github.com/AstroDraw/AstroChart/issues/85
-(globalThis as any).SVGElement = dom.window.SVGElement;
-
-// Polyfill fetch for file:// URLs used by chart tooling in Node.
-const originalFetch = globalThis.fetch;
-(globalThis as any).fetch = async (url: string | URL, ...args: any[]) => {
-  const urlStr = url.toString();
-  if (urlStr.startsWith('file://')) {
-    const filePath = fileURLToPath(urlStr);
-    const buffer = await readFile(filePath);
-    return {
-      ok: true,
-      arrayBuffer: async () =>
-        buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength),
-    };
+function initializeRuntime() {
+  const dom = new JSDOM('<!DOCTYPE html><html><body></body></html>');
+  (globalThis as any).window = dom.window;
+  (globalThis as any).document = dom.window.document;
+  (globalThis as any).self = globalThis; // Critical: astrochart checks for 'self' - see https://github.com/AstroDraw/AstroChart/issues/85
+  (globalThis as any).SVGElement = dom.window.SVGElement;
+
+  // Polyfill fetch for file:// URLs used by chart tooling in Node.
+  const originalFetch = globalThis.fetch;
+  (globalThis as any).fetch = async (url: string | URL, ...args: any[]) => {
+    const urlStr = url.toString();
+    if (urlStr.startsWith('file://')) {
+      const filePath = fileURLToPath(urlStr);
+      const buffer = await readFile(filePath);
+      return {
+        ok: true,
+        arrayBuffer: async () =>
+          buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength),
+      };
+    }
+    return originalFetch(url, ...args);
+  };
+}
+
+function emitMcpHelp(invokedPath = process.argv[1] ?? '') {
+  const invokedName = invokedPath.includes('e2a-mcp') ? 'e2a-mcp' : 'e2a';
+  const launchExample =
+    invokedName === 'e2a-mcp'
+      ? 'e2a-mcp --preferred-tz America/Los_Angeles --preferred-house-style W --weekday-labels'
+      : 'e2a --mcp --preferred-tz America/Los_Angeles --preferred-house-style W --weekday-labels';
+
+  console.log(`Usage: ${invokedName === 'e2a-mcp' ? 'e2a-mcp' : 'e2a --mcp'} [options]
+
+Start the ether-to-astro MCP server with optional deterministic startup defaults.
+
+Options:
+  --preferred-tz <iana>           Default reporting timezone for MCP surfaces
+  --preferred-house-style <P|W|K|E>
+                                  Default house-style preference for MCP surfaces
+  --weekday-labels                Include weekday labels in human-readable MCP text output
+  --no-weekday-labels             Disable weekday labels in human-readable MCP text output
+  -h, --help                      Show this help
+
+Example:
+  ${launchExample}`);
+}
+
+export async function runEntrypoint(argv = process.argv.slice(2), invokedPath = process.argv[1]) {
+  initializeRuntime();
+  const resolved = resolveEntrypoint(argv, invokedPath);
+
+  if (resolved.mode === 'mcp') {
+    if (resolved.mcpHelpRequested) {
+      emitMcpHelp(invokedPath);
+      return;
+    }
+    const { main } = await import('./index.js');
+    await main(resolved.mcpStartupDefaults);
+    return;
   }
-  return originalFetch(url, ...args);
-};
 
-// Use dynamic import() so the above globals are set BEFORE index.js (and charts.js) load
-import('./index.js').then(({ main }) => {
-  main().catch((error) => {
-    console.error('[ERROR] Failed to start server:', error);
+  const { runCli } = await import('./cli.js');
+  const code = await runCli(resolved.cliArgv);
+  process.exit(code);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  runEntrypoint().catch((error) => {
+    console.error('[ERROR] Failed to start program:', error);
     process.exit(1);
   });
-});
+}

package/src/mcp-alias.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+import { runEntrypoint } from './loader.js';
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  runEntrypoint(['--mcp', ...process.argv.slice(2)], process.argv[1]).catch((error) => {
+    console.error('[ERROR] Failed to start program:', error);
+    process.exit(1);
+  });
+}

package/src/time-utils.ts

@@ -165,3 +165,21 @@ export function addLocalDays(local: LocalDateTime, timezone: string, days: numbe
   const zonedDateTime = newPlainDateTime.toZonedDateTime(timezone);
   return new Date(zonedDateTime.epochMilliseconds);
 }
+
+/**
+ * Format a UTC instant as a local ISO-8601 timestamp with timezone offset.
+ *
+ * @param utc - UTC Date object
+ * @param timezone - IANA timezone string
+ * @returns Local timestamp in the form YYYY-MM-DDTHH:mm:ss±HH:MM
+ */
+export function formatLocalTimestampWithOffset(utc: Date, timezone: string): string {
+  const local = utcToLocal(utc, timezone);
+  const offsetMinutes = getTimezoneOffset(utc, timezone);
+  const offsetSign = offsetMinutes >= 0 ? '+' : '-';
+  const offsetAbs = Math.abs(offsetMinutes);
+  const offsetHours = String(Math.floor(offsetAbs / 60)).padStart(2, '0');
+  const offsetMins = String(offsetAbs % 60).padStart(2, '0');
+
+  return `${String(local.year).padStart(4, '0')}-${String(local.month).padStart(2, '0')}-${String(local.day).padStart(2, '0')}T${String(local.hour).padStart(2, '0')}:${String(local.minute).padStart(2, '0')}:${String(local.second ?? 0).padStart(2, '0')}${offsetSign}${offsetHours}:${offsetMins}`;
+}