astro-mcp/PROJECT.md

Astro-MCP v0.2.0

Purpose

Astro-MCP is a Python MCP server that consumes ephemeris-mcp:get_sky_state through MCP-over-SSE and provides structured astrological calculations backed by a SQLite persons database.

Version 0.2.0 adds the finalized delivery boundary for rendered charts:

• Calculation remains exposed through MCP tools.
• Rendered natal charts are exposed through the MCP resource astro://charts/natal/{person_id}.
• Rendered natal charts are exposed to human-facing clients through /charts/natal/{person_id}.{format}.
• The previous render_* MCP tools are removed.
• Existing chart drawing and rendering code is reused unchanged.

Runtime

• Python 3.13
• FastAPI
• FastMCP
• MCP SSE transport
• SQLite person database
• Jinja2 dashboard
• Existing SVG/PNG/JPG chart renderer

The server listens on port 7016 by default. ASTRO_PORT controls the port.

Runtime structure

src/astro_mcp/
├── server.py              # FastAPI app, MCP server, resources, HTTP route
├── tools.py               # Tool registration facade
├── chart_tools.py         # Direct calculation tools
├── by_id_tools.py         # Database-backed calculation tools
├── chart_resources.py     # Natal chart artifact delivery
├── chart_renderer.py      # Stable chart drawing and format conversion
├── chart_helpers.py       # Renderer output helpers
├── chart_styles.py        # Renderer styles and proportions
├── storage.py             # SQLite persistence
├── dashboard.py           # Person-management routes
└── ephemeris_client.py    # Upstream MCP client

chart_renderer.py, chart_helpers.py, and chart_styles.py are the chart production implementation. v0.2.0 changes delivery only; those files are not part of the delivery redesign.

MCP surface

Calculation tools

The server exposes tools for planetary positions, natal charts, transit charts, synastry, composite and Davison calculations, transit previews, relationship summaries, person management, and house-system listing. Direct tools accept birth data. _by_id variants resolve persons from the database.

Rendered chart resource

The implemented v0.2.0 resource template is:

astro://charts/natal/{person_id}

A resource read resolves the person, calls the existing calculate_natal_chart_by_id path, calls the existing render_natal_wheel function, and returns the resulting chart artifact with its MIME type.

No render_* MCP tool exists in v0.2.0.

Human-facing chart URL

/charts/natal/{person_id}.{format}

The supported format suffixes are those already supported by the renderer: svg, png, jpg, and jpeg. The existing size query parameter may also be supplied.

The route returns the rendered bytes/text with the corresponding image content type. It reuses the same artifact path as the MCP resource.

Persons database

The persons database stores:

• birth_datetime: naive local time with no UTC offset
• timezone: IANA timezone name
• latitude, longitude, and optional elevation
• identity and descriptive fields

The conversion from stored local time to UTC occurs in _get_person_birth_data() and must not be duplicated by delivery code.

v0.2.0 status

Implemented:

• Structured chart calculation tools
• Database-backed person lookup
• Stable natal chart drawing and output conversion
• MCP natal chart resource
• HTTP natal chart artifact route
• Removal of all render_* MCP tools
• Dashboard and person management

Not implemented in v0.2.0:

• Transit chart resources
• Synastry resources
• Composite resources
• Davison resources
• New chart drawing features
• New rendering styles, formats, or options
• Caching, compatibility wrappers, or migration routes

These are explicit non-goals, not unfinished items within the v0.2.0 delivery change.

Verification

Run:

pytest

The v0.2.0 verification must confirm that calculation tools remain available, render_* tools are absent, the natal resource template is registered, and the HTTP chart route returns the existing rendered artifact.

The detailed delivery plan is IMPLEMENTATION_PLAN_v0.2.0.md.