# Ephemeris MCP

This repo is a standalone Swiss Ephemeris computation service exposed through MCP.
v0.2 provides astronomical positions, house cusps, lunar state, and related data
to downstream consumers. astro-mcp is the first downstream consumer.

## Working rules

- Provide Swiss Ephemeris as a service: positions, house cusps, lunar state, sidereal time, etc.
- Do not add interpretation layers here. Element balance, stelliums, aspect patterns,
  transit interpretation, synastry, zodiac sign meaning, and narrative output belong
  in downstream projects.
- Prefer small, deterministic changes that preserve the existing tool surface and cache behavior.
- Keep time, location, and sky-state calculations internally consistent across tools.
- Keep planned future slices in the docs and plan, even when they are out of v0.2.
- Treat the wiki as the companion source of project context, not a duplicate code dump.

## Primary references

- Wiki project page: `/home/lucky/wiki/entities/projects/ephemeris-mcp.md`
- Wiki schema: `/home/lucky/wiki/SCHEMA.md`
- Wiki index: `/home/lucky/wiki/index.md`

## Repo shape

- `main.py` starts the app.
- `src/ephemeris_mcp/` holds the runtime code.
- `tests/` holds verification.
- `run.sh`, `restart.sh`, `killserver.sh`, and `tests.sh` are the operational entry points.

## Practical expectations

- Keep the implementation aligned with the plan in `IMPLEMENTATION_PLAN.md`.
- Keep `README.md` and the wiki project page aligned with the shipped slice.
- Prefer explicit, reproducible behavior over hidden heuristics.
- If a change affects the public tool surface or data model, update the repo docs in the same pass.