# Ephemeris MCP

Ephemeris MCP is a standalone celestial computation engine exposed through MCP.
v0.1 ships the core sky-state slice: planetary positions, solar events, lunar
state, moon phase, sidereal time, constellation lookup, discovery, health,
and root. Satellite tooling remains planned for later slices.

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

## What it is

- A shared sky-state service for time- and location-dependent calculations
- A source of planetary positions, solar events, lunar state, sidereal time, and constellation lookup
- A convenience moon-phase tool for quick manual checks
- A utility layer for downstream consumers that want raw sky data

## What it is not

- Not an interpretation engine
- Not a charting service
- Not a consumer-facing astrology app
- Not a finished satellite tracking stack in v0.1

## Project direction

The implementation is intentionally split between:

- objective ephemeris computation
- 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
- `tests.sh` - test runner
- `data/` - local ephemeris/cache data
- `logs/` - runtime logs
- `mcporter` - preferred manual client for smoke tests

## 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-16T03:18:00Z",
    "in_text": "5d 15h 18m"
  }
}
```

```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.249:7015` and mounts 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.1 yet.