ether-to-astro 1.0.0

package/.env.example

@@ -0,0 +1,13 @@
+# Ephemeris Version Configuration
+# Controls which Swiss Ephemeris data files to download
+# 
+# Options:
+#   short   - 600 years (1800-2400 AD), ~2MB total
+#   long    - 6000 years (3000 BC - 3000 AD), ~5MB total (DEFAULT)
+#   moshier - No downloads, use built-in Moshier approximation (lower precision)
+#
+EPHEMERIS_VERSION=long
+
+# Logging Level
+# Options: DEBUG, INFO, WARN, ERROR
+LOG_LEVEL=INFO

package/.github/pull_request_template.md

@@ -0,0 +1,16 @@
+## Summary
+
+- What changed:
+- Why:
+
+## Verification
+
+- [ ] `npm run build`
+- [ ] `npm run lint`
+- [ ] `npm test -- --run`
+
+## Checklist
+
+- [ ] Scope is focused and avoids unrelated churn
+- [ ] Tests were added or updated when behavior changed
+- [ ] Docs were updated when workflow or interfaces changed

package/.github/workflows/release.yml

@@ -0,0 +1,35 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js 20
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          registry-url: https://registry.npmjs.org
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Unit tests
+        run: npm test -- --run
+
+      - name: Publish to npm
+        run: npm publish --access public --provenance

package/.github/workflows/test.yml

@@ -0,0 +1,32 @@
+name: Quality Gate
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js 20
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Unit tests
+        run: npm test -- --run

package/AGENTS.md

@@ -0,0 +1,99 @@
+# AGENTS.md
+
+## Purpose
+This file is for coding agents working in `astro-mcp`. It documents the real architecture and safe change workflow so edits stay correct and low-risk.
+
+## Current Runtime Facts
+- Engine is native Node binding: `sweph` (not WASM/WASI).
+- `sweph` is version-pinned in `package.json` to keep numeric baselines stable for fixtures/validation.
+- MCP entrypoint is `src/loader.ts` -> `src/index.ts`.
+- CLI entrypoint is `src/cli.ts` (`e2a` bin), designed for single-shot stateless usage.
+- CLI profiles are read from `.astro.json` via `src/profile-store.ts` (read-only in v1).
+- Ephemeris files are expected under `data/ephemeris` and configured via `set_ephe_path()`.
+- Server state is process-local and in-memory: one mutable `natalChart` in `src/index.ts`.
+
+## Fast Commands
+- Install: `npm install`
+- Build: `npm run build`
+- CLI: `npm run start:cli -- --help`
+- Unit/integration tests: `npm test -- --run`
+- Routine quality gate: `npm run quality:gate`
+- Validation harness: `npm run validate:astro`
+- Strict dead-code check: `npm run build -- --noUnusedLocals --noUnusedParameters`
+- Lint: `npm run lint`
+
+## Code Map
+- `src/astro-service.ts`: shared business logic used by both MCP and CLI.
+- `src/index.ts`: MCP tool schemas + request handling + stateful orchestration.
+- `src/cli.ts`: commander-based single-shot CLI surface.
+- `src/profile-store.ts`: `.astro.json` profile resolution + schema validation for CLI.
+- `src/ephemeris.ts`: low-level ephemeris adapter, JD/date conversion, position calc, exact root solver.
+- `src/transits.ts`: transit detection, exact-time policy, applying/separating selection, dedupe.
+- `src/houses.ts`: house cusps + polar fallback behavior.
+- `src/riseset.ts`: rise/set/meridian event semantics.
+- `src/eclipses.ts`: next solar/lunar eclipse lookup.
+- `src/time-utils.ts`: Temporal-based timezone/DST conversions.
+- `src/charts.ts`: AstroChart SVG rendering and image conversion.
+
+## Validation Harness Map
+- `tests/validation/validation.spec.ts`: end-to-end validation suite.
+- `tests/validation/utils/denseRootOracle.ts`: independent dense-scan oracle for root finding.
+- `tests/validation/compare/*`: subsystem comparators and mismatch severity.
+- `tests/validation/adapters/internal.ts`: normalized adapter over production code.
+- `tests/validation/adapters/astrolog.ts`: optional external CLI parity.
+- Report output: `/tmp/astro-validation-report.json`.
+
+## Non-Negotiable Behavior Invariants
+- Root solver and oracle must stay logically independent.
+- Root count mismatches are hard failures (not warnings).
+- Transit exact-time status semantics must remain explicit:
+  - `within_preview`
+  - `outside_preview`
+  - `not_found`
+  - `unsupported_body`
+  - `undefined` means exact-time was not attempted because orb is too wide.
+- Rise/set semantics are “next event after anchor instant”, not “civil-day bucket”.
+- DST ambiguity/nonexistent local times for birth data must honor disambiguation policy.
+
+## Tolerances (Validation)
+Defined in `tests/validation/utils/tolerances.ts`:
+- Position longitude/latitude/speed: `0.0001`
+- Houses: `0.01°`
+- Root timing preferred: `2 min`
+- Root timing hard fail: `10 min`
+- Rise/set and eclipse timing (same-engine refs): `1 min`
+- Root dedupe epsilon: `1 min`
+
+## High-Risk Areas (Change Carefully)
+- `EphemerisCalculator.findExactTransitTimes()` in `src/ephemeris.ts`.
+- Transit root-selection policy in `src/transits.ts`.
+- Time conversion/disambiguation in `src/time-utils.ts`.
+- Capability checks and comparator severity in validation harness.
+
+## Safe Change Workflow
+1. Make focused edits (avoid broad refactors).
+2. Run `npm run quality:gate` for normal changes.
+3. Run `npm run validate:astro` for high-risk astro engine changes.
+4. If root mismatches appear, inspect `/tmp/astro-validation-report.json` details:
+   - production roots
+   - oracle roots
+   - residuals
+   - sampled trace
+   - crossing metadata
+5. Only relax fixtures/tolerances with explicit justification.
+
+## Repo Contract
+- Routine merge gate is `npm run build`, `npm run lint`, and `npm test -- --run`.
+- `npm run validate:astro` is targeted validation, not the default gate for every change.
+- Biome is the source of truth for formatting, import order, and linting.
+- Preferred commit types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `build`, `ci`.
+- Keep commits scoped to one coherent change whenever possible.
+
+## Known Gotchas
+- `sweph` has process-wide settings (e.g., ephemeris path); avoid per-request mutation.
+
+## Agent Style for This Repo
+- Prefer minimal, typed, fixture-driven changes.
+- Keep adapter normalization stable when comparing outputs.
+- Do not mask solver regressions with broad dedupe/tolerance changes.
+- Keep external CLI parity optional and auto-skippable.

package/LICENSE

@@ -0,0 +1,18 @@
+GNU Affero General Public License v3.0 or later
+
+Copyright (c) 2026 Ether-to-Astro MCP Server
+
+This project is distributed under the terms of the GNU Affero General Public
+License, version 3 or (at your option) any later version.
+
+You should have received a copy of the GNU Affero General Public License along
+with this project. If not, see https://www.gnu.org/licenses/agpl-3.0.html
+
+Licensing note:
+
+- This repository uses the `sweph` package as a core runtime dependency.
+- `sweph` declares licensing as `(AGPL-3.0-or-later OR LGPL-3.0-or-later)`.
+- The LGPL path is available only under the conditions stated by `sweph`
+  and Swiss Ephemeris licensing terms.
+- This repository adopts the AGPL-3.0-or-later path so the published package
+  and source distribution remain honest and internally consistent.

package/NOTICE.md

@@ -0,0 +1,45 @@
+# Third-Party Notices
+
+This software incorporates components from the following projects:
+
+## Swiss Ephemeris
+
+**License**: AGPL-3.0 / Commercial (dual-licensed)  
+**Copyright**: Copyright (c) 1997-2021 Astrodienst AG, Switzerland  
+**Source**: https://www.astro.com/swisseph/
+
+Swiss Ephemeris is the high-precision ephemeris developed by Astrodienst AG.
+It is dual-licensed under AGPL-3.0 for non-commercial use and requires a
+commercial license for commercial applications.
+
+**Important**: If you use this software commercially, you must obtain a
+commercial license from Astrodienst AG.
+
+## AstroChart
+
+**License**: MIT  
+**Copyright**: Copyright (c) Radek Krejčík  
+**Source**: https://github.com/Kibo/AstroChart
+
+AstroChart is a JavaScript library for generating astrological charts.
+
+## Sharp
+
+**License**: Apache-2.0  
+**Copyright**: Copyright 2013 Lovell Fuller and contributors  
+**Source**: https://github.com/lovell/sharp
+
+Sharp is a high-performance Node.js image processing library.
+
+## Model Context Protocol SDK
+
+**License**: MIT  
+**Copyright**: Copyright (c) Anthropic  
+**Source**: https://github.com/modelcontextprotocol/typescript-sdk
+
+The official TypeScript SDK for the Model Context Protocol.
+
+---
+
+For complete license texts, see the LICENSE file and the respective
+node_modules directories.

package/README.md

@@ -0,0 +1,301 @@
+# ether-to-astro
+
+```
+███████╗██████╗  █████╗
+██╔════╝╚════██╗██╔══██╗
+█████╗   █████╔╝███████║
+██╔══╝  ██╔═══╝ ██╔══██║
+███████╗███████╗██║  ██║
+╚══════╝╚══════╝╚═╝  ╚═╝
+    ether-to-astro
+```
+
+Astrology tooling for agent workflows.
+
+`ether-to-astro` is a local-first astrology toolkit with two surfaces: `e2a`, a CLI, and `e2a-mcp`, an MCP server.
+
+This started as a side project because my wife is the real user, and I wasn’t impressed with the tooling around her astrology fascination. I’ve worked on plenty of AI tools and have a pretty high bar for them. Most of what I found in this space felt flimsy, closed-off, or not designed for serious agent workflows.
+
+So I built the version I wanted to exist: local-first, scriptable, tested, and structured to work well both from the command line and through MCP. I’m the builder. She’s the user. That turned out to be a pretty good way to make the product better.
+
+## Features
+
+Your wife can ask her AI agent about:
+
+### Transits
+- **Daily mundane transits** - Current planetary positions
+- **Moon transits** - Fast-moving Moon aspects to natal planets
+- **Personal planet transits** - Sun, Mercury, Venus, Mars aspects to natal chart
+- **Outer planet transits** - Jupiter, Saturn, Uranus, Neptune, Pluto aspects
+- **Exact transit times** - Precise timing when transits become exact (0° orb)
+- **Upcoming transits** - Multi-day forecast for transits approaching within 2°
+
+### Advanced Features
+- **House cusps** - Ascendant, Midheaven, and all 12 houses (multiple systems)
+- **Retrograde status** - Which planets are currently retrograde
+- **Rise/Set times** - Sunrise, sunset, moonrise, moonset
+- **Asteroids & Nodes** - Chiron, Ceres, Pallas, Juno, Vesta, North Node
+- **Eclipses** - Next solar and lunar eclipse dates
+- **Visual Charts** - Generate SVG natal and transit chart wheels with aspects
+
+## Installation
+
+```bash
+./setup.sh
+```
+
+### Ephemeris Data Configuration
+
+The server downloads Swiss Ephemeris data files during installation. You can control which version using the `EPHEMERIS_VERSION` environment variable:
+
+**Options:**
+- `long` (default) - 6000 years (3000 BC - 3000 AD), ~5MB, recommended for professional use
+- `short` - 600 years (1800-2400 AD), ~2MB, sufficient for modern charts
+- `moshier` - No downloads, uses built-in Moshier approximation (lower precision)
+
+**Examples:**
+```bash
+# Default (long version)
+npm install
+
+# Short version
+EPHEMERIS_VERSION=short npm install
+
+# Moshier only (no downloads)
+EPHEMERIS_VERSION=moshier npm install
+```
+
+Or manually:
+```bash
+npm install
+npm run build
+```
+
+## Engineering Contract
+
+This repo uses a lightweight, agent-friendly operating contract:
+
+- Keep changes focused and avoid unrelated churn in the same diff.
+- Treat Biome as the source of truth for formatting, import order, and linting.
+- Use conventional commit messages: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `build`, `ci`.
+- Keep PR descriptions short and explicit about what changed and how it was verified.
+
+Required routine quality gate:
+
+```bash
+npm run quality:gate
+```
+
+This runs:
+
+- `npm run build`
+- `npm run lint`
+- `npm test -- --run`
+
+Use `npm run validate:astro` for high-risk astrology engine work such as ephemeris/root-solver/transit-timing changes. It is intentionally not part of the default routine gate.
+
+Commit examples:
+
+```text
+fix(cli): resolve injected cwd for relative profile paths
+test(profiles): cover default profile precedence
+refactor(transits): simplify exact-time formatting
+docs(readme): document remote-ready repo contract
+```
+
+Pull request checklist:
+
+- Scope is focused and coherent.
+- `npm run quality:gate` passed locally.
+- Tests were added or updated when behavior changed.
+- Docs were updated when workflow or interfaces changed.
+- PR description includes:
+  - What changed
+  - How it was verified
+
+## Setup
+
+1. Run setup script or install manually (see above)
+
+2. Build:
+
+```bash
+npm run build
+```
+
+3. Add MCP to your MCP settings (e.g., Claude Desktop config):
+
+```json
+{
+  "mcpServers": {
+    "astro": {
+      "command": "e2a-mcp"
+    }
+  }
+}
+```
+
+Package/binary names:
+- Package: `ether-to-astro`
+- CLI command: `e2a`
+- MCP command: `e2a-mcp`
+
+## Runtime Surfaces
+
+### MCP server (stateful per process)
+
+### In-Memory Storage
+The MCP server uses **in-memory storage** for natal chart data:
+- Each client connection gets its own Node.js process instance
+- Natal chart is stored in RAM for the duration of the connection
+- When you disconnect, the process exits and memory is automatically freed
+- No files are created or persisted to disk
+- Simply call `set_natal_chart` again when reconnecting
+
+This design is **MCP-compliant** for stdio transport and ensures complete isolation between different clients.
+
+### CLI (single-shot, stateless)
+
+`e2a` is JSON-first for agent usage and supports `--pretty` for human-readable output.
+
+Examples:
+
+```bash
+# Help
+npx e2a --help
+
+# Set natal chart and print JSON
+npx e2a set-natal-chart --name "Test" --year 1990 --month 1 --day 1 --hour 12 --minute 0 --latitude 40.7 --longitude -74.0 --timezone America/New_York
+
+# Human-readable transit output
+npx e2a get-transits --natal-file ./natal.json --date 2026-03-27 --pretty
+```
+
+### CLI Profiles (`.astro.json`)
+
+The CLI supports profile-based natal input for one-shot commands.
+
+- `--profile <name>`: profile to use
+- `--profile-file <path>`: explicit profile file path
+- `ASTRO_PROFILE`, `ASTRO_PROFILE_FILE`: env var equivalents
+
+Profile file resolution order:
+1. `--profile-file`
+2. `ASTRO_PROFILE_FILE`
+3. `./.astro.json`
+4. `~/.astro.json`
+
+Profile name resolution order:
+1. `--profile`
+2. `ASTRO_PROFILE`
+3. `defaultProfile` in the profile file
+
+Read-only helper commands:
+
+```bash
+npx e2a profiles list
+npx e2a profiles show --profile elwyn
+npx e2a profiles validate
+```
+
+Recommended: add project-local `.astro.json` to `.gitignore` because it contains birth data.
+
+### Time Handling
+The server accepts **local birth time** (not UTC):
+- Provide birth time in local time at the birth location
+- Specify the IANA timezone (e.g., `America/New_York`, `Europe/London`)
+- The server automatically converts to UTC and handles DST correctly
+- Verification feedback shows both local and UTC times for confirmation
+
+**Example:** Born October 17, 1977 at 1:06 PM in Beaver Falls, PA:
+- Input: `hour: 13, minute: 6, timezone: 'America/New_York'`
+- Server converts: 1:06 PM EDT → 5:06 PM UTC
+- Calculates correct Moon sign (0° Capricorn) and Ascendant (0° Capricorn)
+
+### House Systems
+Supports multiple house systems:
+- **Placidus** (default) - Most common in modern Western astrology
+- **Whole Sign** - Traditional system, works at all latitudes
+- **Koch** - Popular in Europe
+- **Equal** - Simple 30° divisions
+
+The server automatically uses Whole Sign for polar latitudes (>66°) where Placidus fails mathematically. You can specify your preferred system with the `house_system` parameter.
+
+## Usage
+
+### 1. Set Natal Chart (First Time)
+
+```
+Use the set_natal_chart tool with:
+- name: "Your Name"
+- year, month, day, hour, minute (birth time in LOCAL time)
+- latitude, longitude (birth location)
+- timezone (e.g., "America/New_York", "Europe/London")
+- house_system (optional): "P" (Placidus), "W" (Whole Sign), "K" (Koch), "E" (Equal)
+```
+
+### 2. Query Transits
+
+Ask your AI agent:
+- "What are today's transits?"
+- "Show me Moon transits"
+- "What outer planet transits are active?"
+- "When will this transit be exact?"
+- "What transits are coming up this week?"
+
+## MCP Tools Available
+
+### Setup
+- `set_natal_chart` - Store birth chart data
+
+### Transits
+- `get_transits` - Category-filtered transits with optional exact-time data
+
+### Advanced Tools
+- `get_houses` - House cusps, Ascendant, Midheaven (Placidus, Koch, Whole Sign, Equal)
+- `get_retrograde_planets` - Show which planets are retrograde
+- `get_rise_set_times` - Sunrise, sunset, moonrise, moonset
+- `get_asteroid_positions` - Chiron, Ceres, Pallas, Juno, Vesta, Nodes
+- `get_next_eclipses` - Next solar and lunar eclipses
+
+### Visual Charts
+- `generate_natal_chart` - Natal chart wheel (SVG/PNG/WebP)
+- `generate_transit_chart` - Transit overlay chart (SVG/PNG/WebP)
+
+## CLI Commands Available
+
+- `set-natal-chart`
+- `get-transits`
+- `get-houses`
+- `get-retrograde-planets`
+- `get-rise-set-times`
+- `get-asteroid-positions`
+- `get-next-eclipses`
+- `generate-natal-chart`
+- `generate-transit-chart`
+
+## Technical Details
+
+- **Engine**: Native Swiss Ephemeris via Node `sweph` bindings
+- **Dependency policy**: `sweph` is pinned to an exact version to keep validation fixtures and numerical baselines stable across installs
+- **Accuracy**:
+  - Primary mode: Swiss Ephemeris data files (`SEFLG_SWIEPH`) for highest precision
+  - Fallback mode: Moshier (`EPHEMERIS_VERSION=moshier` or missing ephemeris files), lower precision but fully functional
+- **Chart Rendering**: @astrodraw/astrochart with JSDOM for server-side SVG generation
+- **Orb settings**: 
+  - Conjunction/Opposition: 8°
+  - Square: 7°
+  - Trine: 7°
+  - Sextile: 6°
+- **Aspects tracked**: Conjunction (0°), Opposition (180°), Square (90°), Trine (120°), Sextile (60°)
+- **Supported bodies**: All planets, Chiron, Ceres, Pallas, Juno, Vesta, North Node
+- **Exact time calculation**: Uses binary search interpolation for precision
+- **Advance warnings**: Shows transits within 2° orb
+
+## License
+
+AGPL-3.0-or-later
+
+This package adopts the AGPL path because it depends on `sweph`, which declares
+`(AGPL-3.0-or-later OR LGPL-3.0-or-later)` and reserves the LGPL path for the
+conditions described by the Swiss Ephemeris licensing terms.

package/SETUP.md

@@ -0,0 +1,70 @@
+# Quick Setup Guide
+
+## Installation
+
+```bash
+./setup.sh
+```
+
+This will:
+1. Install npm dependencies (including WebAssembly Swiss Ephemeris)
+2. Build TypeScript to JavaScript
+
+## Add to Claude Desktop
+
+Edit your Claude Desktop config file:
+- **Mac**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+Add this MCP server:
+
+```json
+{
+  "mcpServers": {
+    "astro": {
+      "command": "node",
+      "args": ["/path/to/ether-to-astro-mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+**Important**: Replace `/path/to/ether-to-astro-mcp` with your actual path!
+
+## First Use
+
+1. Restart Claude Desktop
+2. Set your wife's natal chart:
+
+```
+Please set my natal chart:
+- Name: [Name]
+- Birth: [Month] [Day], [Year] at [Hour]:[Minute] 
+- Location: [City] ([Latitude], [Longitude])
+- Timezone: [e.g., America/Los_Angeles]
+```
+
+3. Query transits:
+
+```
+What are my transits today?
+Show me upcoming transits this week
+When will the Moon conjunct my Venus be exact?
+```
+
+## MCP Tools Available
+
+- `set_natal_chart` - Store birth data
+- `get_daily_transits` - Current planetary positions
+- `get_moon_transits` - Moon aspects to natal planets
+- `get_personal_planet_transits` - Sun/Mercury/Venus/Mars aspects
+- `get_outer_planet_transits` - Jupiter/Saturn/Uranus/Neptune/Pluto aspects
+- `get_exact_transit_times` - Calculate exact times for current transits
+- `get_upcoming_transits` - Multi-day forecast (default 7 days)
+
+## Technical Notes
+
+- Uses WebAssembly Swiss Ephemeris (no native compilation!)
+- Moshier mode provides ~1 arcsecond precision
+- No ephemeris data files needed
+- Works on Mac/Linux (Node.js required)