ether-to-astro 1.0.0

package/example-usage.md

@@ -0,0 +1,131 @@
+# Example Usage
+
+This document shows how to use the Astro MCP server with an AI agent like Claude.
+
+**Note:** The natal chart is stored in memory for the duration of your session. If you disconnect and reconnect, you'll need to call `set_natal_chart` again.
+
+## Important: Time Handling
+
+**Always provide birth time in LOCAL time** (not UTC):
+- Use the time as it appeared on the clock at the birth location
+- Specify the IANA timezone (e.g., `America/New_York`, not `EST`)
+- The server will convert to UTC and handle DST automatically
+- You'll receive verification feedback showing both local and UTC times
+
+## Setting Up Your Wife's Natal Chart
+
+First, she needs to provide her birth data. Ask your AI agent:
+
+```
+Please set my natal chart:
+- Name: Jane
+- Birth: January 15, 1985 at 14:30 (2:30 PM)
+- Location: Los Angeles, CA (34.0522°N, 118.2437°W)
+- Timezone: America/Los_Angeles
+```
+
+The agent will call `set_natal_chart` with:
+```json
+{
+  "name": "Jane",
+  "year": 1985,
+  "month": 1,
+  "day": 15,
+  "hour": 14,
+  "minute": 30,
+  "latitude": 34.0522,
+  "longitude": -118.2437,
+  "timezone": "America/Los_Angeles",
+  "house_system": "P"
+}
+```
+
+**Note:** Hour is in LOCAL time (14:30 = 2:30 PM). The server converts to UTC automatically.
+
+The server responds with verification:
+```
+Natal chart saved for Jane
+
+Birth Details:
+- Local Time: 1/15/1985 14:30 (America/Los_Angeles)
+- UTC Time: 1/15/1985 22:30 UTC
+- Location: 34.05°N, -118.24°W
+
+Chart Angles:
+- Sun: 25° Capricorn
+- Moon: 12° Gemini
+- Ascendant: 8° Taurus
+- MC: 15° Capricorn
+
+House System: Placidus
+```
+
+## Daily Transit Queries
+
+### Morning Check-In
+"What are my transits for today?"
+
+The agent will call:
+- `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` - Slower moving planets
+
+### Specific Questions
+
+**"When will the Moon conjunct my Venus be exact?"**
+- Agent calls `get_exact_transit_times`
+- Returns precise time when aspect is 0° orb
+
+**"What transits are coming up this week?"**
+- Agent calls `get_upcoming_transits` with `days: 7`
+- Shows all transits approaching within 2° orb
+
+**"Show me just the outer planet transits"**
+- Agent calls `get_outer_planet_transits`
+- Returns Jupiter, Saturn, Uranus, Neptune, Pluto aspects
+
+## Sample Output
+
+### Moon Transits
+```
+Moon Transits:
+
+Moon conjunction Venus: 0.45° orb (applying) - Exact: 2026-03-27T03:24:15.000Z
+Moon sextile Mars: 1.23° orb (separating)
+Moon trine Jupiter: 2.87° orb (applying)
+```
+
+### Personal Planet Transits
+```
+Personal Planet Transits:
+
+Sun square natal Moon: 0.89° orb (applying) - Exact: 2026-03-27T18:45:32.000Z
+Venus trine natal Sun: 3.21° orb (separating)
+Mars opposition natal Mercury: 5.67° orb (applying)
+```
+
+### Upcoming Transits (7 days)
+```
+Upcoming Transits (next 7 days):
+
+Jupiter trine natal Venus: 1.45° orb (applying) - Exact: 2026-03-29T12:30:00.000Z
+Saturn square natal Mars: 1.89° orb (applying) - Exact: 2026-04-01T08:15:45.000Z
+```
+
+## Understanding the Output
+
+- **Orb**: How close the aspect is (0° = exact)
+- **Applying**: Transit is getting closer to exact
+- **Separating**: Transit is moving away from exact
+- **Exact time**: When the aspect becomes 0° orb (only shown for transits within 2°)
+
+## Tips for Your Wife
+
+1. **Morning routine**: Check daily transits each morning
+2. **Plan ahead**: Use `get_upcoming_transits` to see what's coming
+3. **Track exact times**: Important transits show exact timing for planning
+4. **Focus on what matters**: 
+   - Moon transits change quickly (every few hours)
+   - Personal planets change daily/weekly
+   - Outer planets can last weeks/months

package/natal-chart.json

@@ -0,0 +1,187 @@
+{
+  "name": "User Whole Sign",
+  "birthDate": {
+    "year": 1977,
+    "month": 10,
+    "day": 17,
+    "hour": 13,
+    "minute": 6
+  },
+  "location": {
+    "latitude": 40.7526,
+    "longitude": -80.3198,
+    "timezone": "America/New_York"
+  },
+  "planets": [
+    {
+      "planet": "Sun",
+      "longitude": 204.05218050976873,
+      "latitude": 0.0001615388556612532,
+      "distance": 0.9964210583337456,
+      "speed": 0.9928259050042711,
+      "sign": "Libra",
+      "degree": 24.052180509768732,
+      "isRetrograde": false
+    },
+    {
+      "planet": "Moon",
+      "longitude": 267.7474069899507,
+      "latitude": 5.03828787700736,
+      "distance": 0.0024531797587498657,
+      "speed": 14.457512480190383,
+      "sign": "Sagittarius",
+      "degree": 27.74740698995072,
+      "isRetrograde": false
+    },
+    {
+      "planet": "Mercury",
+      "longitude": 203.05615113717954,
+      "latitude": 0.956300075310156,
+      "distance": 1.4134856844175427,
+      "speed": 1.7001421021313727,
+      "sign": "Libra",
+      "degree": 23.05615113717954,
+      "isRetrograde": false
+    },
+    {
+      "planet": "Venus",
+      "longitude": 180.59233174758765,
+      "latitude": 1.520411261036414,
+      "distance": 1.5124130040316783,
+      "speed": 1.2383468359522916,
+      "sign": "Libra",
+      "degree": 0.5923317475876502,
+      "isRetrograde": false
+    },
+    {
+      "planet": "Mars",
+      "longitude": 115.83306761812116,
+      "latitude": 1.0377403010723354,
+      "distance": 1.1984622765651196,
+      "speed": 0.47310831677259674,
+      "sign": "Cancer",
+      "degree": 25.833067618121163,
+      "isRetrograde": false
+    },
+    {
+      "planet": "Jupiter",
+      "longitude": 96.06324009530363,
+      "latitude": -0.3624170362523381,
+      "distance": 4.715321463223517,
+      "speed": 0.022806312817944503,
+      "sign": "Cancer",
+      "degree": 6.063240095303627,
+      "isRetrograde": false
+    },
+    {
+      "planet": "Saturn",
+      "longitude": 147.9183963947238,
+      "latitude": 1.1514198531366935,
+      "distance": 9.71241768931636,
+      "speed": 0.08930814127132901,
+      "sign": "Leo",
+      "degree": 27.9183963947238,
+      "isRetrograde": false
+    },
+    {
+      "planet": "Uranus",
+      "longitude": 220.99220136598956,
+      "latitude": 0.39006096397372564,
+      "distance": 19.547124554119833,
+      "speed": 0.06054899513110079,
+      "sign": "Scorpio",
+      "degree": 10.992201365989558,
+      "isRetrograde": false
+    },
+    {
+      "planet": "Neptune",
+      "longitude": 254.1099953294147,
+      "latitude": 1.4392507913670756,
+      "distance": 30.91780788606139,
+      "speed": 0.026698768271311017,
+      "sign": "Sagittarius",
+      "degree": 14.109995329414687,
+      "isRetrograde": false
+    },
+    {
+      "planet": "Pluto",
+      "longitude": 194.47902308697212,
+      "latitude": 16.530727897276424,
+      "distance": 31.37683977306858,
+      "speed": 0.038963569772553476,
+      "sign": "Libra",
+      "degree": 14.47902308697212,
+      "isRetrograde": false
+    },
+    {
+      "planet": "North Node (Mean)",
+      "longitude": 194.5511103273211,
+      "latitude": 0,
+      "distance": 0.0025695552897999903,
+      "speed": -0.05293530033441037,
+      "sign": "Libra",
+      "degree": 14.551110327321112,
+      "isRetrograde": true
+    },
+    {
+      "planet": "North Node (True)",
+      "longitude": 195.2274831010368,
+      "latitude": 0,
+      "distance": 0.0024556133228558225,
+      "speed": -0.013109185725915731,
+      "sign": "Libra",
+      "degree": 15.227483101036796,
+      "isRetrograde": true
+    },
+    {
+      "planet": "Chiron",
+      "longitude": 33.86707264166279,
+      "latitude": -0.5386594883172258,
+      "distance": 16.867648288381556,
+      "speed": -0.046728100146171576,
+      "sign": "Taurus",
+      "degree": 3.867072641662787,
+      "isRetrograde": true
+    },
+    {
+      "planet": "Ceres",
+      "longitude": 225.17925484526404,
+      "latitude": 3.722322777056521,
+      "distance": 3.6128220583215915,
+      "speed": 0.42320521586905213,
+      "sign": "Scorpio",
+      "degree": 15.17925484526404,
+      "isRetrograde": false
+    },
+    {
+      "planet": "Pallas",
+      "longitude": 204.86164458449048,
+      "latitude": 14.672306160015758,
+      "distance": 3.548347696867575,
+      "speed": 0.4450325558858604,
+      "sign": "Libra",
+      "degree": 24.861644584490477,
+      "isRetrograde": false
+    },
+    {
+      "planet": "Juno",
+      "longitude": 243.42276981356122,
+      "latitude": 10.664052131434042,
+      "distance": 3.9911632546316698,
+      "speed": 0.313194206647786,
+      "sign": "Sagittarius",
+      "degree": 3.4227698135612172,
+      "isRetrograde": false
+    },
+    {
+      "planet": "Vesta",
+      "longitude": 188.4269007577168,
+      "latitude": 4.9410232440203075,
+      "distance": 3.2207217522128566,
+      "speed": 0.5021548471029085,
+      "sign": "Libra",
+      "degree": 8.426900757716794,
+      "isRetrograde": false
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "ether-to-astro",
+  "version": "1.0.0",
+  "description": "Local-first astrology toolkit with a CLI (e2a) and MCP server (e2a-mcp) for charts, transits, rendering, and agent workflows.",
+  "type": "module",
+  "main": "dist/index.js",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "e2a-mcp": "dist/loader.js",
+    "e2a": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "dev:watch": "tsx watch src/loader.ts",
+    "start": "node dist/loader.js",
+    "start:cli": "node dist/cli.js",
+    "postinstall": "node scripts/download-ephemeris.js",
+    "test": "vitest tests/unit",
+    "validate:astro": "vitest run tests/validation",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run tests/unit --coverage",
+    "calculate-expected": "tsx tests/fixtures/calculate-expected.ts",
+    "quality:gate": "npm run build && npm run lint && npm test -- --run",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write ."
+  },
+  "keywords": [
+    "mcp",
+    "astrology",
+    "swiss-ephemeris",
+    "transits"
+  ],
+  "author": "",
+  "license": "AGPL-3.0-or-later",
+  "dependencies": {
+    "@astrodraw/astrochart": "^3.0.2",
+    "@js-temporal/polyfill": "^0.5.1",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@std/datetime": "npm:@jsr/std__datetime@^0.225.7",
+    "commander": "^14.0.3",
+    "picocolors": "^1.1.1",
+    "sharp": "^0.34.5",
+    "sweph": "2.10.3-b-1"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.9",
+    "@types/jsdom": "^28.0.1",
+    "@types/node": "^20.0.0",
+    "@vitest/coverage-v8": "^4.1.2",
+    "@vitest/ui": "^4.1.2",
+    "happy-dom": "^20.8.9",
+    "jsdom": "^29.0.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.1.2"
+  }
+}

package/scripts/download-ephemeris.js

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+
+import { access, mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DATA_DIR = join(__dirname, '..', 'data', 'ephemeris');
+
+// Environment variable controls which version to download
+// EPHEMERIS_VERSION=short (600 years, ~2MB) | long (6000 years, ~5MB, DEFAULT) | moshier (none, use built-in)
+const VERSION = (process.env.EPHEMERIS_VERSION || 'long').toLowerCase();
+
+const SHORT_FILES = [
+  { name: 'sepl_18.se1', desc: 'Main planets (Sun-Pluto) [600yr]' },
+  { name: 'semo_18.se1', desc: 'High-precision Moon [600yr]' },
+  { name: 'seas_18.se1', desc: 'Asteroids [600yr]' },
+];
+
+const LONG_FILES = [
+  { name: 'sepl_18.se1', desc: 'Main planets (Sun-Pluto) [6000yr]' },
+  { name: 'semo_18.se1', desc: 'High-precision Moon [6000yr]' },
+  { name: 'seas_18.se1', desc: 'Asteroids [6000yr]' },
+];
+
+const BASE_URL_SHORT = 'https://raw.githubusercontent.com/aloistr/swisseph/master/ephe';
+const BASE_URL_LONG = 'https://raw.githubusercontent.com/aloistr/swisseph/master/ephe';
+
+async function fileExists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function downloadFile(filename, description, baseUrl) {
+  const filePath = join(DATA_DIR, filename);
+
+  if (await fileExists(filePath)) {
+    console.log(`✓ ${description} already exists`);
+    return true;
+  }
+
+  const url = `${baseUrl}/${filename}`;
+  console.log(`Downloading ${description}...`);
+
+  try {
+    const response = await fetch(url);
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    const buffer = await response.arrayBuffer();
+    await writeFile(filePath, Buffer.from(buffer));
+
+    const sizeMB = (buffer.byteLength / 1024 / 1024).toFixed(2);
+    console.log(`✓ Downloaded ${description} (${sizeMB}MB)`);
+    return true;
+  } catch (error) {
+    console.warn(`⚠ Failed to download ${description}: ${error.message}`);
+    return false;
+  }
+}
+
+async function main() {
+  console.log(`Setting up Swiss Ephemeris data files (${VERSION} version)...\n`);
+
+  // Moshier mode - skip downloads entirely
+  if (VERSION === 'moshier') {
+    console.log('✓ Using Moshier ephemeris (built-in approximation, no downloads)');
+    console.log('  Lower precision but works offline\n');
+    process.exit(0);
+  }
+
+  // Determine which files to download
+  const FILES = VERSION === 'short' ? SHORT_FILES : LONG_FILES;
+  const BASE_URL = VERSION === 'short' ? BASE_URL_SHORT : BASE_URL_LONG;
+
+  if (!['short', 'long'].includes(VERSION)) {
+    console.warn(`⚠ Unknown EPHEMERIS_VERSION: "${VERSION}"`);
+    console.warn('Valid options: short, long (default), moshier');
+    console.warn('Defaulting to long version...\n');
+  }
+
+  try {
+    await mkdir(DATA_DIR, { recursive: true });
+  } catch (error) {
+    console.error(`Failed to create data directory: ${error.message}`);
+    process.exit(0); // Fail silently - will use Moshier fallback
+  }
+
+  let successCount = 0;
+  for (const file of FILES) {
+    const success = await downloadFile(file.name, file.desc, BASE_URL);
+    if (success) successCount++;
+  }
+
+  console.log(`\n${successCount}/${FILES.length} ephemeris files ready`);
+
+  if (successCount === 0) {
+    console.warn('\n⚠ Warning: No ephemeris files downloaded.');
+    console.warn('The server will use Moshier ephemeris (lower precision).');
+    console.warn('You can manually download files from:');
+    console.warn('https://github.com/aloistr/swisseph/tree/master/ephe\n');
+  } else {
+    const rangeDesc = VERSION === 'short' ? '1800-2400 AD' : '3000 BC - 3000 AD';
+    console.log(`Date range: ${rangeDesc}\n`);
+  }
+
+  process.exit(0);
+}
+
+main();

package/setup.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+
+echo "Setting up Astro MCP Server..."
+
+echo "Installing npm dependencies..."
+npm install
+
+echo "Building TypeScript..."
+npm run build
+
+echo ""
+echo "✅ Setup complete!"
+echo ""
+echo "The server uses WebAssembly Swiss Ephemeris - no data files needed!"
+echo ""
+echo "Next steps:"
+echo "1. Add this server to your MCP settings"
+echo "2. Use set_natal_chart to store birth data"
+echo "3. Query transits with your AI agent"
+echo ""
+echo "See README.md for detailed usage instructions."