# 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

```text
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:

```text
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

```text
/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:

```text
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`.