# Ephemeris MCP

Ephemeris MCP is a standalone Swiss Ephemeris computation service exposed through MCP.
v0.2 provides planetary positions, house cusps, lunar state, sidereal time, and
related astronomical data to downstream consumers. astro-mcp is the first
downstream consumer; others (e.g. satrack-mcp) are planned.

The server binds to `0.0.0.0` and the current reachable instance is
`192.168.0.200:7015`.

## What it is

- A shared Swiss Ephemeris service so downstream servers don't have to bundle it
- Source of planetary positions, house cusps, solar events, lunar state, sidereal time, and constellation lookup
- A convenience moon-phase tool for quick manual checks
- A raw sky-state snapshot tool (`get_sky_state`) for downstream chart engines
- 22 house systems available for house cusp computation

## What it is not

- Not an interpretation engine (no element balance, stelliums, aspect patterns)
- Not a charting service (no aspects, transits, synastry)
- Not a consumer-facing astrology app
- Not a finished satellite tracking stack in v0.2

## Project direction

The implementation is intentionally split between:

- Swiss Ephemeris computation as a service (positions, houses, lunar, solar, sidereal)
- Cache-backed retrieval of repeatable results
- A small MCP surface for downstream consumers
- A later satellite slice that will add TLE and pass prediction support

The current design and tool intent are described in:

- [`initial_idea.md`](./initial_idea.md)
- [`IMPLEMENTATION_PLAN.md`](./IMPLEMENTATION_PLAN.md)
- [`AGENTS.md`](./AGENTS.md)
- Wiki project page: `/home/lucky/wiki/entities/projects/ephemeris-mcp.md`

## Repo layout

- `main.py` — uvicorn entry point
- `src/ephemeris_mcp/` — application code
- `tests/` — automated checks
- `run.sh` / `restart.sh` / `killserver.sh` — service helpers
- `Dockerfile` / `docker-compose.yml` — container entry points
- `data/ephe/` — Swiss Ephemeris .se1 files (git-tracked, image-bundled)
- `data/cache/` — runtime sqlite cache (gitignored, volume-mounted)
- `logs/` — runtime logs

## mcporter Examples

Use the repo's configured MCP client pattern:

```bash
mcporter --config "$CONFIG" list ephemeris
```

Tool calls follow the same shape:

```bash
mcporter --config "$CONFIG" call ephemeris.get_moon_phase --args '{"datetime":"2026-05-10T12:00:00Z"}'
```

The moon-phase response includes the next major phase as both an ISO timestamp
and a compact relative string:

```json
{
  "phase_name": "Last Quarter",
  "next_major_phase": {
    "phase_name": "New Moon",
    "at_utc": "2026-05-16T20:01:04Z",
    "in_text": "6d 8h 1m"
  }
}
```

```bash
mcporter --config "$CONFIG" call ephemeris.get_lunar_state --args '{"datetime":"2026-05-10T12:00:00Z","lat":52.52,"lon":13.405}'
```

```bash
mcporter --config "$CONFIG" call ephemeris.get_planetary_positions --args '{"datetime":"2026-05-10T12:00:00Z","lat":52.52,"lon":13.405}'
```

The server is exposed on the LAN at `192.168.0.200:7015` and mounts MCP at
`/mcp/sse`.

## Astro-client contract

- `get_sky_state` is the preferred raw snapshot for downstream chart engines.
- It contains planetary positions, lunar state, sidereal time, and solar events.
- When `house_system` is provided, it also includes house cusps and angles.
- 22 house systems: P=Placidus, K=Koch, E=Equal, W=Whole Sign, A=Alcabitius,
  C=Campanus, M=Morinus, R=Porphyry, T=Polich/Page, U=Krusinski-Pisa,
  V=Vehlow Equal, X=Meridian, Y=Horizontal, H=Azimuthal, O=Equal/MC,
  F=Carter poli-eq, D=Equal (15° Aries), G=Gauquelin sectors, I=Sunshine,
  J=Sunshine alt, L=Pullen SD, N=Equal/1, Q=Pullen SR, S=Sripati, Z=APC houses.

## Data files

- Swiss Ephemeris data lives in `./data/ephe/` and is bundled into the Docker image.
- Chiron requires `seas_18.se1` (and related `seas_*.se1` files) — all included.
- The time-segmented files `seas_00.se1` through `seas_168.se1` cover Chiron from ~675 CE to ~4650 CE.
- The files `sepl_*.se1` and `semo_*.se1` are needed for far-future dates (beyond 3000 CE).
- Runtime cache (`ephemeris.sqlite3`) lives in `./data/cache/` and is NOT bundled — it's volume-mounted at runtime.
- All .se1 files are from the Swiss Ephemeris distribution (based on JPL DE441), available at https://github.com/aloistr/swisseph/tree/master/ephe

## Docker

- Build and run the service with `docker compose up --build`.
- `data/ephe/` is COPY'd into the image (self-contained, no volume mount needed).
- `data/cache/` is volume-mounted for persistent runtime cache.
- The container listens on port `7015` and serves MCP at `/mcp/sse`.

## Working notes

- Keep the server deterministic and easy to reason about.
- Prefer structured outputs over free-form text.
- Keep the repo docs and wiki reference aligned when the scope changes.
- Keep future ideas in the plan even if they are not in v0.2 yet.