ether-to-astro 1.0.0

package/src/tool-registry.ts

@@ -0,0 +1,357 @@
+import type { AstroService } from './astro-service.js';
+import type { Disambiguation } from './time-utils.js';
+import type { HouseSystem, NatalChart } from './types.js';
+
+type ToolContent =
+  | { type: 'text'; text: string }
+  | { type: 'image'; data: string; mimeType: string };
+
+export type ToolExecutionResult =
+  | { kind: 'state'; data: Record<string, unknown>; text: string; natalChart?: NatalChart }
+  | { kind: 'content'; content: ToolContent[] };
+
+export interface ToolExecutionContext {
+  service: AstroService;
+  natalChart: NatalChart | null;
+}
+
+type ToolArgs = Record<string, unknown>;
+
+export interface ToolSpec {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  requiresNatalChart: boolean;
+  execute: (
+    ctx: ToolExecutionContext,
+    args: ToolArgs
+  ) => Promise<ToolExecutionResult> | ToolExecutionResult;
+}
+
+export const MCP_TOOL_SPECS: ToolSpec[] = [
+  {
+    name: 'set_natal_chart',
+    description:
+      'Store natal chart data for transit calculations. Birth time should be LOCAL time at the birth location (not UTC). The server converts to UTC using the timezone parameter. Optional birth_time_disambiguation handles DST overlap/gap edge cases (default: reject).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Name for this chart' },
+        year: { type: 'number', description: 'Birth year' },
+        month: { type: 'number', description: 'Birth month (1-12)' },
+        day: { type: 'number', description: 'Birth day' },
+        hour: { type: 'number', description: 'Birth hour (0-23, LOCAL TIME at birth location)' },
+        minute: { type: 'number', description: 'Birth minute' },
+        latitude: { type: 'number', description: 'Birth location latitude' },
+        longitude: { type: 'number', description: 'Birth location longitude' },
+        timezone: {
+          type: 'string',
+          description: 'Timezone (e.g., America/New_York, Europe/London)',
+        },
+        birth_time_disambiguation: {
+          type: 'string',
+          enum: ['compatible', 'earlier', 'later', 'reject'],
+          description:
+            'How to handle DST-ambiguous or nonexistent local birth times. Default: reject.',
+        },
+        house_system: {
+          type: 'string',
+          description:
+            'House system preference: P=Placidus (default), W=Whole Sign, K=Koch, E=Equal',
+          enum: ['P', 'W', 'K', 'E'],
+        },
+      },
+      required: [
+        'name',
+        'year',
+        'month',
+        'day',
+        'hour',
+        'minute',
+        'latitude',
+        'longitude',
+        'timezone',
+      ],
+    },
+    requiresNatalChart: false,
+    execute: (ctx, args) => {
+      const result = ctx.service.setNatalChart({
+        name: args.name as string,
+        year: args.year as number,
+        month: args.month as number,
+        day: args.day as number,
+        hour: args.hour as number,
+        minute: args.minute as number,
+        latitude: args.latitude as number,
+        longitude: args.longitude as number,
+        timezone: args.timezone as string,
+        house_system: args.house_system as HouseSystem | undefined,
+        birth_time_disambiguation: args.birth_time_disambiguation as Disambiguation | undefined,
+      });
+      return { kind: 'state', data: result.data, text: result.text, natalChart: result.chart };
+    },
+  },
+  {
+    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.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        date: {
+          type: 'string',
+          description: 'Date for transits (ISO format YYYY-MM-DD). Defaults to today.',
+        },
+        categories: {
+          type: 'array',
+          items: { type: 'string', enum: ['moon', 'personal', 'outer', 'all'] },
+          description:
+            'Planet categories to include: moon, personal (Sun/Mercury/Venus/Mars), outer (Jupiter/Saturn/Uranus/Neptune/Pluto), or all. Defaults to ["all"].',
+        },
+        include_mundane: {
+          type: 'boolean',
+          description:
+            'Include current planetary positions (not transits to natal chart). Defaults to false.',
+        },
+        days_ahead: {
+          type: 'number',
+          description:
+            'Number of days to look ahead for upcoming transits. 0 = today only. Defaults to 0.',
+          default: 0,
+        },
+        max_orb: {
+          type: 'number',
+          description: 'Maximum orb in degrees to include. Defaults to 8.',
+          default: 8,
+        },
+        exact_only: {
+          type: 'boolean',
+          description:
+            'Only return transits with exact times calculated (within 2° orb). Defaults to false.',
+        },
+        applying_only: {
+          type: 'boolean',
+          description: 'Only return applying (tightening) transits. Defaults to false.',
+        },
+      },
+    },
+    requiresNatalChart: true,
+    execute: (ctx, args) => {
+      const result = ctx.service.getTransits(ctx.natalChart as NatalChart, {
+        date: args.date as string | undefined,
+        categories: args.categories as string[] | undefined,
+        include_mundane: args.include_mundane as boolean | undefined,
+        days_ahead: args.days_ahead as number | 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,
+      });
+      return { kind: 'state', data: result.data, text: result.text };
+    },
+  },
+  {
+    name: 'get_houses',
+    description:
+      'Calculate house cusps, Ascendant, and Midheaven for the natal chart using the specified house system',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        system: {
+          type: 'string',
+          enum: ['P', 'K', 'W', 'E'],
+          description: 'House system: P=Placidus (default), K=Koch, W=Whole Sign, E=Equal',
+          default: 'P',
+        },
+      },
+    },
+    requiresNatalChart: true,
+    execute: (ctx, args) => {
+      const result = ctx.service.getHouses(ctx.natalChart as NatalChart, {
+        system: args.system as string | undefined,
+      });
+      return { kind: 'state', data: result.data, text: result.text };
+    },
+  },
+  {
+    name: 'get_retrograde_planets',
+    description: 'Show which planets are currently retrograde',
+    inputSchema: { type: 'object', properties: {} },
+    requiresNatalChart: false,
+    execute: (ctx, args) => {
+      const timezone =
+        (args.timezone as string | undefined) ?? ctx.natalChart?.location.timezone ?? 'UTC';
+      const result = ctx.service.getRetrogradePlanets(timezone);
+      return { kind: 'state', data: result.data, text: result.text };
+    },
+  },
+  {
+    name: 'get_rise_set_times',
+    description: 'Get sunrise, sunset, moonrise, moonset times for today',
+    inputSchema: { type: 'object', properties: {} },
+    requiresNatalChart: true,
+    execute: async (ctx) => {
+      const result = await ctx.service.getRiseSetTimes(ctx.natalChart as NatalChart);
+      return { kind: 'state', data: result.data, text: result.text };
+    },
+  },
+  {
+    name: 'get_asteroid_positions',
+    description: 'Get positions of major asteroids (Chiron, Ceres, Pallas, Juno, Vesta) and Nodes',
+    inputSchema: { type: 'object', properties: {} },
+    requiresNatalChart: false,
+    execute: (ctx, args) => {
+      const timezone =
+        (args.timezone as string | undefined) ?? ctx.natalChart?.location.timezone ?? 'UTC';
+      const result = ctx.service.getAsteroidPositions(timezone);
+      return { kind: 'state', data: result.data, text: result.text };
+    },
+  },
+  {
+    name: 'get_next_eclipses',
+    description: 'Find the next solar and lunar eclipses',
+    inputSchema: { type: 'object', properties: {} },
+    requiresNatalChart: false,
+    execute: (ctx, args) => {
+      const timezone =
+        (args.timezone as string | undefined) ?? ctx.natalChart?.location.timezone ?? 'UTC';
+      const result = ctx.service.getNextEclipses(timezone);
+      return { kind: 'state', data: result.data, text: result.text };
+    },
+  },
+  {
+    name: 'get_server_status',
+    description:
+      'Inspect the current server state: whether a natal chart is loaded, its name and timezone, and the server version. Call this before making assumptions about loaded context.',
+    inputSchema: { type: 'object', properties: {} },
+    requiresNatalChart: false,
+    execute: (ctx) => {
+      const result = ctx.service.getServerStatus(ctx.natalChart);
+      return { kind: 'state', data: result.data, text: result.text };
+    },
+  },
+  {
+    name: 'generate_natal_chart',
+    description:
+      'Generate a visual natal chart wheel with planets, houses, and aspects. Supports SVG, PNG, and WebP formats. Theme defaults to dark (6pm-6am) or light (6am-6pm) based on current time, but can be overridden with the theme parameter.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        theme: {
+          type: 'string',
+          enum: ['light', 'dark'],
+          description:
+            'Color theme override. Defaults to time-based: dark (6pm-6am) or light (6am-6pm)',
+        },
+        format: {
+          type: 'string',
+          enum: ['svg', 'png', 'webp'],
+          description: 'Output format (svg, png, or webp), defaults to svg',
+        },
+        output_path: {
+          type: 'string',
+          description: 'Optional absolute file path to save the chart (e.g., /path/to/chart.webp)',
+        },
+      },
+    },
+    requiresNatalChart: true,
+    execute: async (ctx, args) => {
+      const result = await ctx.service.generateNatalChart(ctx.natalChart as NatalChart, {
+        theme: args.theme as 'light' | 'dark' | undefined,
+        format: args.format as 'svg' | 'png' | 'webp' | undefined,
+        output_path: args.output_path as string | undefined,
+      });
+      if (result.outputPath) {
+        return { kind: 'content', content: [{ type: 'text', text: result.text }] };
+      }
+      if (result.format === 'svg' && result.svg) {
+        return {
+          kind: 'content',
+          content: [
+            { type: 'text', text: result.text },
+            { type: 'text', text: result.svg },
+          ],
+        };
+      }
+      if (result.image) {
+        return {
+          kind: 'content',
+          content: [
+            { type: 'text', text: result.text },
+            { type: 'image', data: result.image.data, mimeType: result.image.mimeType },
+          ],
+        };
+      }
+      throw new Error('Chart generation returned no payload.');
+    },
+  },
+  {
+    name: 'generate_transit_chart',
+    description:
+      'Generate a visual transit chart showing current transits overlaid on the natal chart. Date defaults to today at local noon in the natal chart timezone. Supports SVG, PNG, and WebP formats with light or dark themes.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        date: {
+          type: 'string',
+          description: 'Optional date for transits (ISO format), defaults to today at local noon',
+        },
+        theme: {
+          type: 'string',
+          enum: ['light', 'dark'],
+          description:
+            'Color theme override. Defaults to time-based: dark (6pm-6am) or light (6am-6pm)',
+        },
+        format: {
+          type: 'string',
+          enum: ['svg', 'png', 'webp'],
+          description: 'Output format (svg, png, or webp), defaults to svg',
+        },
+        output_path: {
+          type: 'string',
+          description: 'Optional absolute file path to save the chart (e.g., /path/to/chart.webp)',
+        },
+      },
+    },
+    requiresNatalChart: true,
+    execute: async (ctx, args) => {
+      const result = await ctx.service.generateTransitChart(ctx.natalChart as NatalChart, {
+        date: args.date as string | undefined,
+        theme: args.theme as 'light' | 'dark' | undefined,
+        format: args.format as 'svg' | 'png' | 'webp' | undefined,
+        output_path: args.output_path as string | undefined,
+      });
+      if (result.outputPath) {
+        return { kind: 'content', content: [{ type: 'text', text: result.text }] };
+      }
+      if (result.format === 'svg' && result.svg) {
+        return {
+          kind: 'content',
+          content: [
+            { type: 'text', text: result.text },
+            { type: 'text', text: result.svg },
+          ],
+        };
+      }
+      if (result.image) {
+        return {
+          kind: 'content',
+          content: [
+            { type: 'text', text: result.text },
+            { type: 'image', data: result.image.data, mimeType: result.image.mimeType },
+          ],
+        };
+      }
+      throw new Error('Transit chart generation returned no payload.');
+    },
+  },
+];
+
+export function createToolSpecIndex(specs: ToolSpec[] = MCP_TOOL_SPECS): Map<string, ToolSpec> {
+  return new Map(specs.map((spec) => [spec.name, spec]));
+}
+
+const TOOL_INDEX = createToolSpecIndex();
+
+export function getToolSpec(name: string): ToolSpec | undefined {
+  return TOOL_INDEX.get(name);
+}

package/src/tool-result.ts

@@ -0,0 +1,283 @@
+/**
+ * Structured error handling for MCP tool results
+ *
+ * @remarks
+ * Provides agent-recoverable error codes and suggestions for self-correction.
+ * Distinguishes between recoverable domain errors and hard infrastructure failures.
+ *
+ * Each error code includes whether it's retryable and suggested fixes
+ * to help the agent recover from errors automatically.
+ */
+
+/**
+ * Error codes for MCP tool operations
+ *
+ * @remarks
+ * Each code represents a specific category of error that can occur
+ * during astrological calculations. The codes are designed to be
+ * machine-readable while still being descriptive.
+ */
+export type ToolIssueCode =
+  | 'INVALID_INPUT'
+  | 'UNKNOWN_PLANET'
+  | 'NO_RISE_SET_EVENT'
+  | 'CIRCUMPOLAR_OBJECT'
+  | 'POLAR_LATITUDE_LIMIT'
+  | 'EPHEMERIS_NOT_INITIALIZED'
+  | 'EPHEMERIS_COMPUTE_FAILED'
+  | 'TIMEZONE_ERROR'
+  | 'INVALID_TIMEZONE'
+  | 'MISSING_NATAL_CHART'
+  | 'INVALID_DATE'
+  | 'INVALID_HOUSE_SYSTEM'
+  | 'FILE_WRITE_FAILED'
+  | 'CHART_RENDER_FAILED'
+  | 'INTERNAL_ERROR';
+
+/**
+ * Structured error information for tool operations
+ *
+ * @remarks
+ * Contains the error code, human-readable message, and metadata
+ * to help agents understand and recover from errors.
+ */
+export interface ToolIssue {
+  /** Machine-readable error code */
+  code: ToolIssueCode;
+  /** Human-readable error description */
+  message: string;
+  /** Whether the operation can be retried */
+  retryable: boolean;
+  /** Suggested fix for the agent (optional) */
+  suggestedFix?: string;
+  /** Additional error context (optional) */
+  details?: Record<string, unknown>;
+}
+
+/**
+ * Result type for MCP tool operations
+ *
+ * @remarks
+ * Discriminated union that distinguishes between successful
+ * and failed operations. Success includes data and optional warnings,
+ * while failure includes structured error information.
+ */
+export type ToolResult<T> =
+  | {
+      /** Success flag */
+      ok: true;
+      /** Result data */
+      data: T;
+      /** Optional warnings about the operation */
+      warnings?: ToolIssue[];
+    }
+  | {
+      /** Failure flag */
+      ok: false;
+      /** Error information */
+      error: ToolIssue;
+    };
+
+/**
+ * Create a successful tool result
+ *
+ * @param data - The successful result data
+ * @param warnings - Optional warnings about the operation
+ * @returns Success result with data
+ *
+ * @remarks
+ * Use this to wrap successful operation results. Warnings are
+ * optional and can indicate non-fatal issues.
+ */
+export function success<T>(data: T, warnings?: ToolIssue[]): ToolResult<T> {
+  return warnings ? { ok: true, data, warnings } : { ok: true, data };
+}
+
+/**
+ * Create a failed tool result
+ *
+ * @param error - Structured error information
+ * @returns Failure result with error
+ *
+ * @remarks
+ * Use this to wrap failed operations. The error should include
+ * a code, message, and optionally retry/suggestion information.
+ */
+export function failure(error: ToolIssue): ToolResult<never> {
+  return { ok: false, error };
+}
+
+/**
+ * Schema version for structured responses.
+ * Increment on breaking changes to response shapes.
+ */
+export const SCHEMA_VERSION = '1.0';
+
+/**
+ * Build a successful MCP tool response with structured data + human text.
+ *
+ * @param data - Structured payload
+ * @param humanText - Human-readable summary
+ * @param warnings - Optional warnings
+ * @returns MCP content array (JSON first, text second)
+ */
+export function mcpResult<T>(data: T, humanText: string, warnings?: ToolIssue[]) {
+  const envelope = warnings
+    ? { ok: true as const, schemaVersion: SCHEMA_VERSION, data, warnings }
+    : { ok: true as const, schemaVersion: SCHEMA_VERSION, data };
+  return {
+    content: [
+      { type: 'text' as const, text: JSON.stringify(envelope, null, 2) },
+      { type: 'text' as const, text: humanText },
+    ],
+  };
+}
+
+/**
+ * Build an error MCP tool response with structured error.
+ *
+ * @param error - Structured error information
+ * @returns MCP content array with isError flag
+ */
+export function mcpError(error: ToolIssue) {
+  return {
+    content: [
+      {
+        type: 'text' as const,
+        text: JSON.stringify({ ok: false, schemaVersion: SCHEMA_VERSION, error }, null, 2),
+      },
+    ],
+    isError: true,
+  };
+}
+
+/**
+ * Map Swiss Ephemeris errors to structured tool issues
+ *
+ * @param context - Operation context where error occurred
+ * @param err - Raw error from Swiss Ephemeris
+ * @param details - Additional error context
+ * @returns Structured tool issue with retry information
+ *
+ * @remarks
+ * Converts low-level Swiss Ephemeris errors into structured,
+ * agent-recoverable error codes with suggested fixes.
+ */
+export function mapSweError(
+  context: string,
+  err: unknown,
+  details?: Record<string, unknown>
+): ToolIssue {
+  const message = err instanceof Error ? err.message : String(err);
+
+  if (/not initialized/i.test(message)) {
+    return {
+      code: 'EPHEMERIS_NOT_INITIALIZED',
+      message: 'Swiss Ephemeris is not initialized.',
+      retryable: false,
+      suggestedFix: 'Initialize the ephemeris engine before requesting calculations.',
+      details,
+    };
+  }
+
+  return {
+    code: 'EPHEMERIS_COMPUTE_FAILED',
+    message: `Swiss Ephemeris failed during ${context}.`,
+    retryable: false,
+    suggestedFix: 'Check inputs and ephemeris configuration.',
+    details: { ...details, rawMessage: message },
+  };
+}
+
+/**
+ * Create a structured error for missing rise/set events
+ *
+ * @param eventType - Type of event that was missing
+ * @param planet - Planet name for context
+ * @param details - Additional error context
+ * @returns Structured tool issue indicating no event
+ *
+ * @remarks
+ * Used when a planet doesn't rise/set at a location (circumpolar)
+ * or when meridian transits don't occur.
+ */
+export function noRiseSetEvent(
+  eventType: 'rise' | 'set' | 'upper_meridian' | 'lower_meridian',
+  planet: string,
+  details: Record<string, unknown>
+): ToolIssue {
+  return {
+    code: 'NO_RISE_SET_EVENT',
+    message: `No ${eventType} event for ${planet} at the specified date and location.`,
+    retryable: true,
+    suggestedFix:
+      'Try another date, location, or request a different event type. Object may be circumpolar.',
+    details,
+  };
+}
+
+/**
+ * Create a structured error for circumpolar objects
+ *
+ * @param planet - Planet name for context
+ * @param latitude - Observer latitude where object is circumpolar
+ * @param details - Additional error context
+ * @returns Structured tool issue for circumpolar object
+ *
+ * @remarks
+ * Used when a planet never rises or sets at extreme latitudes.
+ * The object is either always above or always below the horizon.
+ */
+export function circumpolarObject(
+  planet: string,
+  latitude: number,
+  details?: Record<string, unknown>
+): ToolIssue {
+  return {
+    code: 'CIRCUMPOLAR_OBJECT',
+    message: `${planet} is circumpolar at latitude ${latitude.toFixed(1)}° - it does not rise or set.`,
+    retryable: true,
+    suggestedFix: 'Request meridian transit times instead, or try a different location.',
+    details: { planet, latitude, ...details },
+  };
+}
+
+/**
+ * Create a structured error for missing natal chart
+ *
+ * @returns Structured tool issue for missing natal chart
+ *
+ * @remarks
+ * Used when transit or chart operations are requested
+ * before a natal chart has been set.
+ */
+export function missingNatalChart(): ToolIssue {
+  return {
+    code: 'MISSING_NATAL_CHART',
+    message: 'No natal chart found. Please set natal chart first.',
+    retryable: true,
+    suggestedFix:
+      'Call set_natal_chart with birth details (date, time, location, timezone) before requesting transits or chart calculations.',
+  };
+}
+
+/**
+ * Create a warning for polar latitude limitations
+ *
+ * @param latitude - Observer latitude in degrees
+ * @param houseSystem - House system being used
+ * @returns Structured tool issue warning about polar limitations
+ *
+ * @remarks
+ * Some house systems (Placidus, Koch) fail at extreme latitudes.
+ * This warns the user and suggests Whole Sign as a fallback.
+ */
+export function polarLatitudeWarning(latitude: number, houseSystem: string): ToolIssue {
+  return {
+    code: 'POLAR_LATITUDE_LIMIT',
+    message: `${houseSystem} house system may be inaccurate at polar latitudes (${latitude.toFixed(1)}°).`,
+    retryable: true,
+    suggestedFix: 'Consider using Whole Sign house system for latitudes >66°.',
+    details: { latitude, houseSystem },
+  };
+}