ether-to-astro 1.0.0

package/dist/index.js

@@ -0,0 +1,150 @@
+/**
+ * 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';
+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 = 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);
+        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;
+        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/dist/loader.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/loader.js

@@ -0,0 +1,31 @@
+#!/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.window = dom.window;
+globalThis.document = dom.window.document;
+globalThis.self = globalThis; // Critical: astrochart checks for 'self' - see https://github.com/AstroDraw/AstroChart/issues/85
+globalThis.SVGElement = dom.window.SVGElement;
+// Polyfill fetch for file:// URLs used by chart tooling in Node.
+const originalFetch = globalThis.fetch;
+globalThis.fetch = async (url, ...args) => {
+    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/dist/logger.d.ts

@@ -0,0 +1,25 @@
+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;
+}
+declare class Logger {
+    private shouldLog;
+    private formatEntry;
+    private log;
+    debug(message: string, context?: Record<string, unknown>): void;
+    info(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+    error(message: string, category: ErrorCategoryType, error?: Error, context?: Record<string, unknown>): void;
+    ephemerisWarning(warning: string): void;
+}
+export declare const logger: Logger;
+export {};

package/dist/logger.js

@@ -0,0 +1,73 @@
+import { LogLevel } from './constants.js';
+class Logger {
+    shouldLog(level) {
+        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);
+    }
+    formatEntry(entry) {
+        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)}` : ''}`;
+    }
+    log(entry) {
+        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, context) {
+        this.log({
+            timestamp: new Date().toISOString(),
+            level: LogLevel.DEBUG,
+            message,
+            context,
+        });
+    }
+    info(message, context) {
+        this.log({
+            timestamp: new Date().toISOString(),
+            level: LogLevel.INFO,
+            message,
+            context,
+        });
+    }
+    warn(message, context) {
+        this.log({
+            timestamp: new Date().toISOString(),
+            level: LogLevel.WARN,
+            message,
+            context,
+        });
+    }
+    error(message, category, error, context) {
+        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) {
+        // 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/dist/profile-store.d.ts

@@ -0,0 +1,48 @@
+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 declare class ProfileStoreError extends Error {
+    readonly code: ProfileErrorCode;
+    constructor(code: ProfileErrorCode, message: string);
+}
+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;
+}
+export declare function resolveProfileFilePath(options: ResolveProfileOptions, required: boolean): Promise<string | null>;
+export declare function loadAstroProfileFile(filePath: string): Promise<AstroProfileFile>;
+export declare function resolveProfileSelection(options: ResolveProfileOptions): Promise<ResolvedProfileSelection | null>;
+export declare function loadResolvedProfileFile(options: ResolveProfileOptions): Promise<{
+    filePath: string;
+    file: AstroProfileFile;
+}>;
+export declare function toNatalInput(profile: AstroProfile): SetNatalChartInput;
+export {};

package/dist/profile-store.js

@@ -0,0 +1,156 @@
+import { constants as fsConstants } from 'node:fs';
+import { access, readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+export class ProfileStoreError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'ProfileStoreError';
+    }
+}
+async function exists(filePath) {
+    try {
+        await access(filePath, fsConstants.R_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function requireString(value, label, profileName) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new ProfileStoreError('PROFILE_VALIDATION_FAILED', `Profile "${profileName}" is invalid: ${label} is missing`);
+    }
+    return value;
+}
+function requireNumber(value, label, profileName) {
+    if (typeof value !== 'number' || Number.isNaN(value)) {
+        throw new ProfileStoreError('PROFILE_VALIDATION_FAILED', `Profile "${profileName}" is invalid: ${label} is missing`);
+    }
+    return value;
+}
+function requireEnum(value, label, allowed, profileName) {
+    if (typeof value !== 'string' || !allowed.includes(value)) {
+        throw new ProfileStoreError('PROFILE_VALIDATION_FAILED', `Profile "${profileName}" is invalid: ${label} must be one of ${allowed.join(', ')}`);
+    }
+    return value;
+}
+function normalizeProfile(profileName, value) {
+    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),
+        birth_time_disambiguation: disambiguation === undefined
+            ? undefined
+            : requireEnum(disambiguation, 'birth_time_disambiguation', ['compatible', 'earlier', 'later', 'reject'], profileName),
+    };
+}
+export async function resolveProfileFilePath(options, required) {
+    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) {
+    let parsed;
+    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 = {};
+    for (const [profileName, profileValue] of Object.entries(parsed.profiles)) {
+        normalizedProfiles[profileName] = normalizeProfile(profileName, profileValue);
+    }
+    return {
+        version: 1,
+        defaultProfile: parsed.defaultProfile,
+        profiles: normalizedProfiles,
+    };
+}
+export async function resolveProfileSelection(options) {
+    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) {
+    const filePath = await resolveProfileFilePath(options, true);
+    const file = await loadAstroProfileFile(filePath);
+    return { filePath: filePath, file };
+}
+export function toNatalInput(profile) {
+    return { ...profile };
+}

package/dist/riseset.d.ts

@@ -0,0 +1,82 @@
+import type { EphemerisCalculator } from './ephemeris.js';
+import { type RiseSetTime } from './types.js';
+/**
+ * Calculator for rise, set, and meridian transit times
+ *
+ * @remarks
+ * Calculates when celestial bodies rise above and set below the horizon,
+ * plus upper and lower meridian transits. Handles circumpolar objects
+ * and atmospheric refraction corrections.
+ */
+export declare class RiseSetCalculator {
+    /** Ephemeris calculator instance */
+    private ephem;
+    /**
+     * Create a new rise/set calculator
+     *
+     * @param ephem - Initialized ephemeris calculator
+     * @throws Error if ephemeris is not initialized
+     *
+     * @remarks
+     * The ephemeris calculator must be initialized before passing
+     * to the RiseSetCalculator constructor.
+     */
+    constructor(ephem: EphemerisCalculator);
+    /**
+     * Calculate rise, set, and meridian transit times for a celestial body
+     *
+     * Uses standard astronomical definitions:
+     * - Rise/Set: Upper limb of disc with atmospheric refraction considered
+     * - Atmospheric pressure: Estimated from altitude (sea level if altitude=0)
+     * - Temperature: 0°C (default assumption)
+     * - Upper meridian: Highest point in sky (culmination)
+     * - Lower meridian: Lowest point in sky (anti-culmination)
+     *
+     * Swiss Ephemeris return codes:
+     * - 0 or positive: Event found successfully
+     * - -1: Calculation error (hard failure)
+     * - -2: No event exists (circumpolar object)
+     *
+     * @param julianDay - Julian Day to start search from (typically midnight of target date)
+     * @param planetId - Swiss Ephemeris planet ID
+     * @param latitude - Observer latitude in degrees (-90 to 90)
+     * @param longitude - Observer longitude in degrees
+     * @param altitude - Observer altitude in meters (default: 0 = sea level)
+     * @returns Rise/set/transit times, or undefined fields if event doesn't occur
+     * @throws {Error} If ephemeris not initialized, invalid inputs, or hard calculation error
+     */
+    calculateRiseSet(julianDay: number, planetId: number, latitude: number, longitude: number, altitude?: number): RiseSetTime;
+    /**
+     * Get rise/set times for all planets for a given date
+     *
+     * @param date - Date/time to use as search anchor (typically current instant or midnight of target date)
+     * @param latitude - Observer latitude in degrees (-90 to 90)
+     * @param longitude - Observer longitude in degrees
+     * @param altitude - Observer altitude in meters (default: 0)
+     * @returns Array of rise/set times for all planets
+     * @throws Error if ephemeris not initialized or invalid inputs
+     *
+     * @remarks
+     * Calculates for Sun through Pluto. Some fields may be undefined
+     * for circumpolar objects at extreme latitudes.
+     *
+     * Swiss Ephemeris searches for the NEXT event after the given instant,
+     * so to get events for a specific civil date, pass midnight of that date.
+     */
+    getAllRiseSet(date: Date, latitude: number, longitude: number, altitude?: number): Promise<RiseSetTime[]>;
+    /**
+     * Get Sun rise/set times for the current instant
+     *
+     * @param latitude - Observer latitude in degrees (-90 to 90)
+     * @param longitude - Observer longitude in degrees
+     * @param altitude - Observer altitude in meters (default: 0)
+     * @returns Rise/set times for the Sun
+     * @throws Error if ephemeris not initialized or invalid inputs
+     *
+     * @remarks
+     * Searches for the next sunrise/sunset after the current instant.
+     * If called in the afternoon, sunrise will be tomorrow.
+     * For events on a specific civil date, use calculateRiseSet with midnight JD.
+     */
+    getSunRiseSet(latitude: number, longitude: number, altitude?: number): Promise<RiseSetTime>;
+}