ether-to-astro 1.0.2 → 1.2.0

package/dist/tool-registry.js

@@ -58,9 +58,109 @@ export const MCP_TOOL_SPECS = [
             return { kind: 'state', data: result.data, text: result.text, natalChart: result.chart };
         },
     },
+    {
+        name: 'get_rising_sign_windows',
+        description: 'Get local-time windows for which zodiac signs are rising on a given date and location. Returns deterministic intervals only (no ranking or interpretation).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                date: {
+                    type: 'string',
+                    description: 'Target local date (YYYY-MM-DD)',
+                },
+                latitude: { type: 'number', description: 'Latitude in decimal degrees (-90 to 90)' },
+                longitude: {
+                    type: 'number',
+                    description: 'Longitude in decimal degrees (-180 to 180)',
+                },
+                timezone: {
+                    type: 'string',
+                    description: 'IANA timezone (e.g., America/New_York)',
+                },
+                mode: {
+                    type: 'string',
+                    enum: ['approximate', 'exact'],
+                    description: 'Boundary mode. approximate uses coarser stepping; exact refines sign-change boundaries.',
+                    default: 'approximate',
+                },
+            },
+            required: ['date', 'latitude', 'longitude', 'timezone'],
+        },
+        requiresNatalChart: false,
+        execute: (ctx, args) => {
+            const result = ctx.service.getRisingSignWindows({
+                date: args.date,
+                latitude: args.latitude,
+                longitude: args.longitude,
+                timezone: args.timezone,
+                mode: args.mode,
+            });
+            return { kind: 'state', data: result.data, text: result.text };
+        },
+    },
+    {
+        name: 'get_electional_context',
+        description: 'Get stateless electional context for a specific local date, time, and location. Returns deterministic timing facts such as ascendant, sect/day-night classification, Moon phase, applying aspects, and optional ascendant-ruler basics. This tool does not require a natal chart and is separate from get_transits.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                date: {
+                    type: 'string',
+                    description: 'Target local date (YYYY-MM-DD)',
+                },
+                time: {
+                    type: 'string',
+                    description: 'Target local time (HH:mm or HH:mm:ss). DST-ambiguous or nonexistent local times are rejected.',
+                },
+                timezone: {
+                    type: 'string',
+                    description: 'IANA timezone (e.g., America/New_York)',
+                },
+                latitude: { type: 'number', description: 'Latitude in decimal degrees (-90 to 90)' },
+                longitude: {
+                    type: 'number',
+                    description: 'Longitude in decimal degrees (-180 to 180)',
+                },
+                house_system: {
+                    type: 'string',
+                    enum: ['P', 'K', 'W', 'R'],
+                    description: 'House system used for ascendant extraction: P=Placidus (default), K=Koch, W=Whole Sign, R=Regiomontanus.',
+                },
+                include_ruler_basics: {
+                    type: 'boolean',
+                    description: 'Include ascendant-ruler position, speed, and retrograde flag. Defaults to false.',
+                },
+                include_planetary_applications: {
+                    type: 'boolean',
+                    description: 'Include applying major aspects between current planets. Defaults to true.',
+                },
+                orb_degrees: {
+                    type: 'number',
+                    description: 'Orb for electional aspect detection in degrees. Defaults to 3 and must be between 0.1 and 10.',
+                    default: 3,
+                },
+            },
+            required: ['date', 'time', 'timezone', 'latitude', 'longitude'],
+        },
+        requiresNatalChart: false,
+        execute: (ctx, args) => {
+            const result = ctx.service.getElectionalContext({
+                date: args.date,
+                time: args.time,
+                timezone: args.timezone,
+                latitude: args.latitude,
+                longitude: args.longitude,
+                house_system: args.house_system,
+                include_ruler_basics: args.include_ruler_basics,
+                include_planetary_applications: args.include_planetary_applications,
+                orb_degrees: args.orb_degrees,
+            });
+            return { kind: 'state', data: result.data, text: result.text };
+        },
+    },
     {
         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.',
+        description: 'Get transits (aspects between current/future planets and natal chart). Each transit includes additive placement metadata for both sides (sign, degree, house) so clients can render activation context without reconstructing house logic. Supports mode=snapshot (single-day), mode=best_hit (multi-day compressed preview), and mode=forecast (day-grouped output). If mode is omitted, legacy behavior is preserved: days_ahead=0 resolves to snapshot and days_ahead>0 resolves to best_hit.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -79,9 +179,14 @@ export const MCP_TOOL_SPECS = [
                 },
                 days_ahead: {
                     type: 'number',
-                    description: 'Number of days to look ahead for upcoming transits. 0 = today only. Defaults to 0.',
+                    description: 'Number of days to look ahead. In snapshot mode only the start day is used. If mode is omitted, legacy behavior is preserved: 0 resolves to snapshot and values > 0 resolve to best_hit.',
                     default: 0,
                 },
+                mode: {
+                    type: 'string',
+                    enum: ['snapshot', 'best_hit', 'forecast'],
+                    description: 'Transit output mode: snapshot=single-day, best_hit=compressed preview across range, forecast=day-grouped output. If omitted, legacy behavior is preserved.',
+                },
                 max_orb: {
                     type: 'number',
                     description: 'Maximum orb in degrees to include. Defaults to 8.',
@@ -104,6 +209,7 @@ export const MCP_TOOL_SPECS = [
                 categories: args.categories,
                 include_mundane: args.include_mundane,
                 days_ahead: args.days_ahead,
+                mode: args.mode,
                 max_orb: args.max_orb,
                 exact_only: args.exact_only,
                 applying_only: args.applying_only,
@@ -139,7 +245,7 @@ export const MCP_TOOL_SPECS = [
         inputSchema: { type: 'object', properties: {} },
         requiresNatalChart: false,
         execute: (ctx, args) => {
-            const timezone = args.timezone ?? ctx.natalChart?.location.timezone ?? 'UTC';
+            const timezone = ctx.service.resolveReportingTimezone(args.timezone, ctx.natalChart?.location?.timezone);
             const result = ctx.service.getRetrogradePlanets(timezone);
             return { kind: 'state', data: result.data, text: result.text };
         },
@@ -160,7 +266,7 @@ export const MCP_TOOL_SPECS = [
         inputSchema: { type: 'object', properties: {} },
         requiresNatalChart: false,
         execute: (ctx, args) => {
-            const timezone = args.timezone ?? ctx.natalChart?.location.timezone ?? 'UTC';
+            const timezone = ctx.service.resolveReportingTimezone(args.timezone, ctx.natalChart?.location?.timezone);
             const result = ctx.service.getAsteroidPositions(timezone);
             return { kind: 'state', data: result.data, text: result.text };
         },
@@ -171,7 +277,7 @@ export const MCP_TOOL_SPECS = [
         inputSchema: { type: 'object', properties: {} },
         requiresNatalChart: false,
         execute: (ctx, args) => {
-            const timezone = args.timezone ?? ctx.natalChart?.location.timezone ?? 'UTC';
+            const timezone = ctx.service.resolveReportingTimezone(args.timezone, ctx.natalChart?.location?.timezone);
             const result = ctx.service.getNextEclipses(timezone);
             return { kind: 'state', data: result.data, text: result.text };
         },

package/dist/tool-result.d.ts

@@ -125,6 +125,14 @@ export declare function mcpError(error: ToolIssue): {
  * agent-recoverable error codes with suggested fixes.
  */
 export declare function mapSweError(context: string, err: unknown, details?: Record<string, unknown>): ToolIssue;
+/**
+ * Map generic error messages to structured tool issue codes.
+ *
+ * @remarks
+ * Primarily used at the MCP boundary when unknown errors are caught
+ * and need a best-effort classification.
+ */
+export declare function mapToolErrorMessageToCode(errorMessage: string): ToolIssueCode;
 /**
  * Create a structured error for missing rise/set events
  *

package/dist/tool-result.js

@@ -107,6 +107,45 @@ export function mapSweError(context, err, details) {
         details: { ...details, rawMessage: message },
     };
 }
+/**
+ * Map generic error messages to structured tool issue codes.
+ *
+ * @remarks
+ * Primarily used at the MCP boundary when unknown errors are caught
+ * and need a best-effort classification.
+ */
+export function mapToolErrorMessageToCode(errorMessage) {
+    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') ||
+        errorMessage.includes('Invalid mode') ||
+        errorMessage.includes('Invalid latitude') ||
+        errorMessage.includes('Invalid longitude')) {
+        return 'INVALID_INPUT';
+    }
+    if (errorMessage.includes('Invalid timezone') || errorMessage.includes('timezone')) {
+        return 'INVALID_TIMEZONE';
+    }
+    if (errorMessage.includes('Invalid house system')) {
+        return 'INVALID_HOUSE_SYSTEM';
+    }
+    if (errorMessage.includes('Ephemeris') || errorMessage.includes('ephemeris')) {
+        return 'EPHEMERIS_COMPUTE_FAILED';
+    }
+    if (errorMessage.includes('write') ||
+        errorMessage.includes('ENOENT') ||
+        errorMessage.includes('EACCES')) {
+        return 'FILE_WRITE_FAILED';
+    }
+    if (errorMessage.includes('render') || errorMessage.includes('chart')) {
+        return 'CHART_RENDER_FAILED';
+    }
+    return 'INTERNAL_ERROR';
+}
 /**
  * Create a structured error for missing rise/set events
  *

package/dist/types.d.ts

@@ -54,6 +54,12 @@ export interface NatalChart {
      * For polar latitudes (>66°), Whole Sign ('W') may be used as fallback.
      */
     houseSystem?: HouseSystem;
+    /**
+     * Explicit house system requested when the natal chart was created
+     * @remarks
+     * This stays undefined when the caller relied on runtime defaults.
+     */
+    requestedHouseSystem?: HouseSystem;
     /**
      * UTC equivalent of birth time
      * @remarks
@@ -181,6 +187,18 @@ export interface TransitData extends BaseTransit {
      * May be undefined if aspect is not within orb or exact time not calculated
      */
     exactTime?: string;
+    /** Zodiac sign of the transiting planet */
+    transitSign?: string;
+    /** Degree of the transiting planet within its sign (0-30) */
+    transitDegree?: number;
+    /** House occupied by the transiting planet at the transit calculation time */
+    transitHouse?: number;
+    /** Zodiac sign of the natal planet */
+    natalSign?: string;
+    /** Degree of the natal planet within its sign (0-30) */
+    natalDegree?: number;
+    /** House occupied by the natal planet in the natal chart */
+    natalHouse?: number;
 }
 /**
  * Response wrapper for transit data
@@ -192,8 +210,12 @@ export interface TransitData extends BaseTransit {
 export interface TransitResponse {
     /** ISO date of the transit calculation (YYYY-MM-DD) */
     date: string;
-    /** Timezone used for the calculation */
+    /** Timezone used for reporting and user-facing day labels */
     timezone: string;
+    /** Natal/local timezone used for date interpretation and astro calculations */
+    calculation_timezone?: string;
+    /** Timezone used for reporting and user-facing day labels */
+    reporting_timezone?: string;
     /** Array of all active transits for the date */
     transits: TransitData[];
 }
@@ -211,6 +233,7 @@ export interface PlanetPositionResponse {
     /** Array of planet positions */
     positions: PlanetPosition[];
 }
+export type ElectionalHouseSystem = Extract<HouseSystem, 'P' | 'K' | 'W' | 'R'>;
 /**
  * Types of astrological aspects
  *
@@ -219,6 +242,61 @@ export interface PlanetPositionResponse {
  * specific types of interactions and energies.
  */
 export type AspectType = 'conjunction' | 'opposition' | 'square' | 'trine' | 'sextile';
+export type ElectionalPhaseName = 'new' | 'crescent' | 'first_quarter' | 'gibbous' | 'full' | 'disseminating' | 'last_quarter' | 'balsamic';
+export interface ElectionalAspect {
+    from_body: PlanetName;
+    to_body: PlanetName;
+    aspect: AspectType;
+    orb: number;
+    applying: boolean;
+    exact_at_utc?: string;
+}
+export interface ElectionalContextResponse {
+    input: {
+        date: string;
+        time: string;
+        timezone: string;
+        latitude: number;
+        longitude: number;
+        house_system: ElectionalHouseSystem;
+        instant_utc: string;
+        jd_ut: number;
+    };
+    ascendant: {
+        longitude: number;
+        sign: string;
+        degree_in_sign: number;
+    };
+    sect: {
+        is_day_chart: boolean;
+        sun_altitude_degrees: number;
+        classification: 'day' | 'night';
+    };
+    moon: {
+        longitude: number;
+        sign: string;
+        phase_angle: number;
+        phase_name: ElectionalPhaseName;
+        is_void_of_course: boolean | null;
+        applying_aspects?: ElectionalAspect[];
+    };
+    applying_aspects?: ElectionalAspect[];
+    ruler_basics?: {
+        asc_sign_ruler: {
+            body: PlanetName;
+            longitude: number;
+            sign: string;
+            speed: number;
+            is_retrograde: boolean;
+        };
+    };
+    meta: {
+        deterministic: true;
+        requires_natal: false;
+        warnings: string[];
+        deferred_features: string[];
+    };
+}
 /**
  * Aspect definitions with angles and default orbs
  *

package/docs/product/adrs/0001-mcp-vs-skill-boundary.md

@@ -0,0 +1,96 @@
+# ADR 0001: MCP Vs Skill Boundary
+
+- Status: Accepted
+- Date: 2026-03-28
+
+## Context
+
+`ether-to-astro` is evolving from a set of astrology utilities into infrastructure for AI-native workflows.
+
+Recent product exploration introduced requests for:
+
+- daily and weekly transit reporting,
+- mundane baseline plus natal modifier reasoning,
+- electional support,
+- Whole Sign-first house activation reporting,
+- and preference-aware planning workflows.
+
+Without an explicit boundary, it would be easy to grow the MCP surface into a large collection of personalized reporting tools. That would make the product harder to maintain, harder to reuse, and harder to reason about.
+
+## Decision
+
+We will keep the boundary as follows:
+
+- `MCP tools` own reusable astrological computation and structured primitives.
+- `Skills or workflows` own synthesis, ranking, personalization, and report generation.
+- `MCP prompts` may expose common workflows for discovery, but they do not become the main home for product logic.
+- `Profiles or preferences` own durable user-specific output choices and heuristics.
+
+## Consequences
+
+### Positive
+
+- MCP stays focused and reusable.
+- Skills can evolve quickly without destabilizing the computational layer.
+- Personalized reporting can improve without forcing product-wide API churn.
+- New agents and clients get a clearer mental model of the system.
+
+### Negative
+
+- Some workflows will require multiple calls instead of one large convenience tool.
+- Skill authors must still do synthesis work rather than relying on all-in-one MCP endpoints.
+- We need stronger docs and examples so the boundary remains easy to apply.
+
+## Decision Rules
+
+Add a capability to MCP when:
+
+- it is deterministic or mostly deterministic,
+- it is computation-heavy,
+- reusable across multiple workflows,
+- and risky or repetitive to reconstruct client-side.
+
+Keep a capability in a skill when:
+
+- it is interpretation-heavy,
+- it is deterministic but mainly encodes workflow policy or ranking,
+- user-specific,
+- likely to evolve rapidly,
+- or achievable by a competent LLM in two calls to stable primitives.
+
+## Examples
+
+### Belongs In MCP
+
+- transit forecast data grouped by day
+- mundane aspects
+- house activation metadata
+- electional primitives
+- rising-sign windows
+
+### Belongs In Skills
+
+- daily briefing
+- weekly overview synthesis
+- “top influences” ranking
+- best-use guidance
+- personalized electional scoring
+
+### Does Not Belong In MCP
+
+- one-user workflow tags
+- customized work or life advice
+- generic prose-generation tools that a skill could perform from structured data
+
+## Follow-Up
+
+This ADR implies:
+
+- future MCP proposals should justify why the capability cannot stay in a skill,
+- new reporting workflows should start life outside MCP,
+- and docs should make the two-call skill model the default design assumption.
+
+## Related Docs
+
+- [Product Tenets](/Users/salted/Code/astro-mcp/docs/product/product-tenets.md)
+- [Architecture Boundaries](/Users/salted/Code/astro-mcp/docs/product/architecture-boundaries.md)

package/docs/product/architecture-boundaries.md

@@ -0,0 +1,223 @@
+# Architecture Boundaries
+
+This document translates the product tenets into concrete repository and interface boundaries.
+
+## System Layers
+
+The product has four distinct layers:
+
+1. `MCP tools`
+   Source of truth for reusable astrological computation.
+2. `MCP prompts`
+   Thin public entry points that help clients discover or initiate common workflows.
+3. `Assistant skills or workflows`
+   AI-native orchestration, synthesis, ranking, and formatting built on top of MCP tools.
+4. `Profiles or preferences`
+   User- or workflow-specific settings that shape output without polluting generic tool contracts.
+
+## The Boundary In One Sentence
+
+MCP computes and exposes facts. Skills decide what matters, how to rank it, and how to present it.
+
+## Determinism Rule
+
+Deterministic, generic astrology outputs are strong candidates for MCP.
+
+This includes:
+
+- added flags on existing tools,
+- expanded date windows,
+- grouped forecast output,
+- generic derived astro signals,
+- and reusable metadata that multiple clients would otherwise reconstruct themselves.
+
+Determinism is not sufficient by itself.
+
+Deterministic outputs should still stay out of MCP when they primarily encode:
+
+- personalized policy,
+- workflow-specific scoring,
+- subjective ranking,
+- or narrative conclusions.
+
+## What Counts As A Primitive
+
+A primitive is a structured output that:
+
+- represents reusable astrological truth,
+- is deterministic or mostly deterministic for the same inputs,
+- is stable across multiple workflows,
+- and does not depend on one user’s preferred interpretation style.
+
+Examples of good primitives:
+
+- transit events
+- date-grouped forecast windows
+- mundane aspects
+- house activations
+- Moon condition
+- ASC sign and ruler condition
+- rising-sign windows
+
+Examples of non-primitives:
+
+- “top 3 influences today”
+- “best time to influence leadership”
+- “high opportunity” versus “mixed-intense”
+- custom tags like “report readout” or “spiritual ritual”
+
+## MCP Tool Design Rules
+
+### Prefer Generic Modes Over Tool Proliferation
+
+Good:
+
+- one transit tool with explicit modes such as `snapshot`, `best_hit`, and `forecast`
+- one electional-context tool with optional include flags for rising windows, Moon condition, and house context
+
+Bad:
+
+- `get_daily_transits`
+- `get_weekly_transits`
+- `get_best_transits_for_work`
+- `get_spiritual_transits`
+
+### Favor Structured Data Over Prose
+
+Good MCP output:
+
+- date-grouped JSON
+- exact-time metadata
+- sign, degree, house, and applying/separating state
+
+Bad MCP output:
+
+- opinionated text summaries
+- personalized advice
+- user-specific ranking labels baked into the contract
+
+### Keep Personalization Out Of MCP
+
+Do not hardcode into MCP:
+
+- one user’s preferred house system for reporting
+- one user’s preferred electional rulers
+- one user’s work or life categories
+- one user’s “good” and “bad” framing
+
+Instead:
+
+- expose the raw or lightly structured inputs,
+- then let skills and preferences shape the output.
+
+## Skill Design Rules
+
+Skills should:
+
+- call the smallest useful set of MCP primitives,
+- avoid reimplementing astro logic,
+- own synthesis and narrative structure,
+- and encode workflow-level decisions such as section order, ranking, tone, and user-preference application.
+
+The default target is a one-call or two-call skill flow.
+
+Skill-layer examples in this repo are primarily boundary examples and workflow incubators.
+
+They should not be read as automatic commitments to build or maintain every listed workflow as a first-class product artifact.
+
+### Good Skill Flow
+
+1. Call forecast primitives.
+2. Optionally call electional primitives for narrowed windows.
+3. Synthesize the report.
+
+### Bad Skill Flow
+
+- dozens of tiny MCP calls that should have been a reusable primitive
+- custom astro math in the skill
+- pretending uncertain interpretation is hard computation
+
+## Prompt Design Rules
+
+Prompts are optional adapters, not the core product logic.
+
+Use prompts when you want:
+
+- discoverability in MCP-aware clients,
+- a stable public workflow entry point,
+- and a generic wrapper around one or more tools.
+
+Do not use prompts as a substitute for:
+
+- a missing MCP primitive,
+- or a real skill/workflow spec.
+
+## Preference Design Rules
+
+Profiles or preferences should contain durable output preferences and user heuristics.
+
+Examples:
+
+- reporting timezone
+- preferred house system for interpretation
+- favored electional filters
+- preferred report sections
+- recurring tags or domain labels
+
+Preferences should not:
+
+- alter astro computation silently,
+- fork the meaning of a generic MCP tool,
+- or create multiple incompatible interpretations of the same primitive.
+
+## When To Add A New MCP Primitive
+
+Add a new MCP primitive when all or most of the following are true:
+
+- it is deterministic or mostly deterministic,
+- it is computational,
+- it is reusable,
+- multiple skills or clients need it,
+- it would be brittle to reconstruct client-side,
+- and it reduces total system complexity.
+
+## When Not To Add A New MCP Primitive
+
+Do not add a new MCP primitive when:
+
+- it mainly produces prose,
+- it mainly encodes policy rather than astro fact,
+- it mainly reflects one user’s preferences,
+- the same result can be achieved by a competent LLM in two calls,
+- or it would create a specialized tool for a narrow workflow instead of strengthening a generic primitive.
+
+## Current Repo Implications
+
+Based on the current product direction:
+
+### Strong candidates for MCP
+
+- range-aware transit forecast data
+- mundane aspect data
+- house-aware transit activations
+- electional primitives
+- rising-sign window helpers
+
+### Candidate workflow experiments after primitive stabilization
+
+- daily brief generation
+- weekly overview synthesis
+- electional overlay and ranking
+- action-oriented summaries
+- user-specific framing and categorization
+
+### Strong candidates for docs or examples
+
+- reference workflows that show how to combine forecast plus electional context
+- examples of what lives in skills versus MCP
+- preference contract guidance for user-facing reporting
+
+## Related Docs
+
+- [Product Tenets](/Users/salted/Code/astro-mcp/docs/product/product-tenets.md)
+- [ADR 0001: MCP Vs Skill Boundary](/Users/salted/Code/astro-mcp/docs/product/adrs/0001-mcp-vs-skill-boundary.md)