ether-to-astro 1.0.0

package/src/index.ts

@@ -0,0 +1,170 @@
+/**
+ * Main MCP server for astrological calculations
+ *
+ * @remarks
+ * Provides tools for:
+ * - Setting and managing natal charts
+ * - Calculating planetary positions and transits
+ * - Generating astrological charts
+ * - Computing houses, rise/set times, and eclipses
+ *
+ * Uses Swiss Ephemeris for accurate astronomical calculations.
+ * All calculations are tropical (not sidereal) and geocentric.
+ */
+
+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 { logger } from './logger.js';
+import { getToolSpec, MCP_TOOL_SPECS } from './tool-registry.js';
+import { 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: {},
+    },
+  }
+);
+
+/**
+ * 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.',
+      });
+    }
+
+    if (spec.requiresNatalChart && !natalChart) {
+      return mcpError(missingNatalChart());
+    }
+
+    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 { content: result.content };
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+
+    // 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 },
+    });
+  }
+});
+
+export async function main() {
+  logger.info('Initializing Swiss Ephemeris');
+  await astroService.init();
+  logger.info('Ephemeris initialized');
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  logger.info('Astro MCP server running on stdio');
+}
+
+// Only run if this is the main module
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((error) => {
+    console.error('Server error:', error);
+    process.exit(1);
+  });
+}

package/src/loader.ts

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+
+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';
+
+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);
+};
+
+// 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);
+    process.exit(1);
+  });
+});

package/src/logger.ts

@@ -0,0 +1,104 @@
+import { type ErrorCategoryType, LogLevel, type LogLevelType } from './constants.js';
+
+export interface LogEntry {
+  timestamp: string;
+  level: LogLevelType;
+  message: string;
+  context?: Record<string, unknown>;
+}
+
+export interface ErrorLogEntry extends LogEntry {
+  level: typeof LogLevel.ERROR;
+  category: ErrorCategoryType;
+  error?: Error;
+  stack?: string;
+}
+
+class Logger {
+  private shouldLog(level: LogLevelType): boolean {
+    const minLevel = process.env.LOG_LEVEL || LogLevel.INFO;
+    const levels = [LogLevel.DEBUG, LogLevel.INFO, LogLevel.WARN, LogLevel.ERROR];
+    return levels.indexOf(level) >= levels.indexOf(minLevel as LogLevelType);
+  }
+
+  private formatEntry(entry: LogEntry | ErrorLogEntry): string {
+    const base = `[${entry.timestamp}] ${entry.level}: ${entry.message}`;
+
+    if ('category' in entry) {
+      return `${base} (${entry.category})${entry.context ? ` ${JSON.stringify(entry.context)}` : ''}`;
+    }
+
+    return `${base}${entry.context ? ` ${JSON.stringify(entry.context)}` : ''}`;
+  }
+
+  private log(entry: LogEntry | ErrorLogEntry): void {
+    if (!this.shouldLog(entry.level)) return;
+
+    const output = this.formatEntry(entry);
+
+    // MCP servers use stderr for logging (stdout is for protocol)
+    console.error(output);
+
+    if ('error' in entry && entry.error) {
+      console.error(entry.error);
+    }
+  }
+
+  debug(message: string, context?: Record<string, unknown>): void {
+    this.log({
+      timestamp: new Date().toISOString(),
+      level: LogLevel.DEBUG,
+      message,
+      context,
+    });
+  }
+
+  info(message: string, context?: Record<string, unknown>): void {
+    this.log({
+      timestamp: new Date().toISOString(),
+      level: LogLevel.INFO,
+      message,
+      context,
+    });
+  }
+
+  warn(message: string, context?: Record<string, unknown>): void {
+    this.log({
+      timestamp: new Date().toISOString(),
+      level: LogLevel.WARN,
+      message,
+      context,
+    });
+  }
+
+  error(
+    message: string,
+    category: ErrorCategoryType,
+    error?: Error,
+    context?: Record<string, unknown>
+  ): void {
+    this.log({
+      timestamp: new Date().toISOString(),
+      level: LogLevel.ERROR,
+      category,
+      message,
+      error,
+      stack: error?.stack,
+      context,
+    });
+  }
+
+  // Special handler for Swiss Ephemeris warnings (not actual errors)
+  ephemerisWarning(warning: string): void {
+    // Only log Moshier fallback at debug level since it's expected
+    if (warning.includes('using Moshier')) {
+      this.debug('Using Moshier ephemeris (high-precision data files not found)', {
+        warning,
+      });
+    } else {
+      this.warn('Swiss Ephemeris warning', { warning });
+    }
+  }
+}
+
+export const logger = new Logger();

package/src/profile-store.ts

@@ -0,0 +1,285 @@
+import { constants as fsConstants } from 'node:fs';
+import { access, readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import type { SetNatalChartInput } from './astro-service.js';
+
+type HouseSystem = 'P' | 'W' | 'K' | 'E';
+type BirthTimeDisambiguation = 'compatible' | 'earlier' | 'later' | 'reject';
+
+export interface AstroProfile {
+  name: string;
+  year: number;
+  month: number;
+  day: number;
+  hour: number;
+  minute: number;
+  latitude: number;
+  longitude: number;
+  timezone: string;
+  house_system?: HouseSystem;
+  birth_time_disambiguation?: BirthTimeDisambiguation;
+}
+
+export interface AstroProfileFile {
+  version: 1;
+  defaultProfile?: string;
+  profiles: Record<string, AstroProfile>;
+}
+
+export type ProfileErrorCode =
+  | 'PROFILE_FILE_NOT_FOUND'
+  | 'INVALID_PROFILE_FILE'
+  | 'PROFILE_NOT_FOUND'
+  | 'DEFAULT_PROFILE_NOT_FOUND'
+  | 'PROFILE_VALIDATION_FAILED';
+
+export class ProfileStoreError extends Error {
+  readonly code: ProfileErrorCode;
+
+  constructor(code: ProfileErrorCode, message: string) {
+    super(message);
+    this.code = code;
+    this.name = 'ProfileStoreError';
+  }
+}
+
+export interface ResolveProfileOptions {
+  profileName?: string;
+  profileFile?: string;
+  env?: NodeJS.ProcessEnv;
+  cwd?: string;
+  homeDir?: string;
+}
+
+export interface ResolvedProfileSelection {
+  filePath: string;
+  file: AstroProfileFile;
+  profileName: string;
+  profile: AstroProfile;
+}
+
+async function exists(filePath: string): Promise<boolean> {
+  try {
+    await access(filePath, fsConstants.R_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function requireString(value: unknown, label: string, profileName: string): string {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new ProfileStoreError(
+      'PROFILE_VALIDATION_FAILED',
+      `Profile "${profileName}" is invalid: ${label} is missing`
+    );
+  }
+  return value;
+}
+
+function requireNumber(value: unknown, label: string, profileName: string): number {
+  if (typeof value !== 'number' || Number.isNaN(value)) {
+    throw new ProfileStoreError(
+      'PROFILE_VALIDATION_FAILED',
+      `Profile "${profileName}" is invalid: ${label} is missing`
+    );
+  }
+  return value;
+}
+
+function requireEnum<T extends string>(
+  value: unknown,
+  label: string,
+  allowed: readonly T[],
+  profileName: string
+): T {
+  if (typeof value !== 'string' || !allowed.includes(value as T)) {
+    throw new ProfileStoreError(
+      'PROFILE_VALIDATION_FAILED',
+      `Profile "${profileName}" is invalid: ${label} must be one of ${allowed.join(', ')}`
+    );
+  }
+  return value as T;
+}
+
+function normalizeProfile(profileName: string, value: unknown): AstroProfile {
+  if (!isRecord(value)) {
+    throw new ProfileStoreError(
+      'PROFILE_VALIDATION_FAILED',
+      `Profile "${profileName}" is invalid: profile must be an object`
+    );
+  }
+
+  const houseSystem = value.house_system;
+  const disambiguation = value.birth_time_disambiguation;
+
+  return {
+    name: requireString(value.name, 'name', profileName),
+    year: requireNumber(value.year, 'year', profileName),
+    month: requireNumber(value.month, 'month', profileName),
+    day: requireNumber(value.day, 'day', profileName),
+    hour: requireNumber(value.hour, 'hour', profileName),
+    minute: requireNumber(value.minute, 'minute', profileName),
+    latitude: requireNumber(value.latitude, 'latitude', profileName),
+    longitude: requireNumber(value.longitude, 'longitude', profileName),
+    timezone: requireString(value.timezone, 'timezone', profileName),
+    house_system:
+      houseSystem === undefined
+        ? undefined
+        : (requireEnum(
+            houseSystem,
+            'house_system',
+            ['P', 'W', 'K', 'E'],
+            profileName
+          ) as HouseSystem),
+    birth_time_disambiguation:
+      disambiguation === undefined
+        ? undefined
+        : (requireEnum(
+            disambiguation,
+            'birth_time_disambiguation',
+            ['compatible', 'earlier', 'later', 'reject'],
+            profileName
+          ) as BirthTimeDisambiguation),
+  };
+}
+
+export async function resolveProfileFilePath(
+  options: ResolveProfileOptions,
+  required: boolean
+): Promise<string | null> {
+  const env = options.env ?? process.env;
+  const cwd = options.cwd ?? process.cwd();
+  const homeDir = options.homeDir ?? homedir();
+
+  const explicitPath = options.profileFile ?? env.ASTRO_PROFILE_FILE;
+  if (explicitPath) {
+    const resolved = path.resolve(cwd, explicitPath);
+    if (!(await exists(resolved))) {
+      throw new ProfileStoreError('PROFILE_FILE_NOT_FOUND', `Profile file not found: ${resolved}`);
+    }
+    return resolved;
+  }
+
+  const localPath = path.resolve(cwd, '.astro.json');
+  if (await exists(localPath)) {
+    return localPath;
+  }
+
+  const homePath = path.resolve(homeDir, '.astro.json');
+  if (await exists(homePath)) {
+    return homePath;
+  }
+
+  if (required) {
+    throw new ProfileStoreError(
+      'PROFILE_FILE_NOT_FOUND',
+      `Profile file not found: searched ${localPath} and ${homePath}`
+    );
+  }
+  return null;
+}
+
+export async function loadAstroProfileFile(filePath: string): Promise<AstroProfileFile> {
+  let parsed: unknown;
+  try {
+    const raw = await readFile(filePath, 'utf8');
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new ProfileStoreError(
+      'INVALID_PROFILE_FILE',
+      `Invalid profile file: ${filePath} (${message})`
+    );
+  }
+
+  if (!isRecord(parsed)) {
+    throw new ProfileStoreError(
+      'INVALID_PROFILE_FILE',
+      `Invalid profile file: ${filePath} (root must be an object)`
+    );
+  }
+  if (parsed.version !== 1) {
+    throw new ProfileStoreError(
+      'INVALID_PROFILE_FILE',
+      `Invalid profile file: ${filePath} (version must be 1)`
+    );
+  }
+  if (!isRecord(parsed.profiles)) {
+    throw new ProfileStoreError(
+      'INVALID_PROFILE_FILE',
+      `Invalid profile file: ${filePath} (profiles must be an object)`
+    );
+  }
+  if (parsed.defaultProfile !== undefined && typeof parsed.defaultProfile !== 'string') {
+    throw new ProfileStoreError(
+      'INVALID_PROFILE_FILE',
+      `Invalid profile file: ${filePath} (defaultProfile must be a string)`
+    );
+  }
+
+  const normalizedProfiles: Record<string, AstroProfile> = {};
+  for (const [profileName, profileValue] of Object.entries(parsed.profiles)) {
+    normalizedProfiles[profileName] = normalizeProfile(profileName, profileValue);
+  }
+
+  return {
+    version: 1,
+    defaultProfile: parsed.defaultProfile as string | undefined,
+    profiles: normalizedProfiles,
+  };
+}
+
+export async function resolveProfileSelection(
+  options: ResolveProfileOptions
+): Promise<ResolvedProfileSelection | null> {
+  const env = options.env ?? process.env;
+  const filePath = await resolveProfileFilePath(options, false);
+  if (!filePath) {
+    return null;
+  }
+
+  const file = await loadAstroProfileFile(filePath);
+  const profileName = options.profileName ?? env.ASTRO_PROFILE ?? file.defaultProfile;
+  if (!profileName) {
+    return null;
+  }
+
+  const profile = file.profiles[profileName];
+  if (!profile) {
+    if (!options.profileName && !env.ASTRO_PROFILE && file.defaultProfile === profileName) {
+      throw new ProfileStoreError(
+        'DEFAULT_PROFILE_NOT_FOUND',
+        `defaultProfile is set to "${profileName}", but no such profile exists`
+      );
+    }
+    throw new ProfileStoreError(
+      'PROFILE_NOT_FOUND',
+      `Profile "${profileName}" not found in ${filePath}`
+    );
+  }
+
+  return {
+    filePath,
+    file,
+    profileName,
+    profile,
+  };
+}
+
+export async function loadResolvedProfileFile(
+  options: ResolveProfileOptions
+): Promise<{ filePath: string; file: AstroProfileFile }> {
+  const filePath = await resolveProfileFilePath(options, true);
+  const file = await loadAstroProfileFile(filePath as string);
+  return { filePath: filePath as string, file };
+}
+
+export function toNatalInput(profile: AstroProfile): SetNatalChartInput {
+  return { ...profile };
+}