ephemeris-mcp/AGENTS.md

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.