# astro-mcp v0.2.0

Version 0.2.0.

Astro-MCP is an MCP server for astrological chart calculations and database-backed chart artifact delivery. It consumes `ephemeris-mcp:get_sky_state` through MCP-over-SSE and exposes structured calculation tools, MCP resources for rendered charts, and HTTP chart URLs for human-facing clients.

## v0.2.0 delivery surface

Chart rendering is implemented internally and is not exposed as MCP tools. The `render_*` MCP tools have been removed.

Rendered natal charts for persons in the database are available as the MCP resource template:

```text
astro://charts/natal/{person_id}
```

The resource returns the default SVG artifact. The human-facing HTTP equivalent accepts the existing renderer format suffixes:

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

Examples:

```text
astro://charts/natal/einstein
/charts/natal/einstein.svg
/charts/natal/einstein.png
```

The MCP resource and HTTP route use the existing natal calculation and chart-rendering implementation. They do not add rendering behavior or alter the chart drawing code.

Only natal chart artifact delivery is implemented in v0.2.0. Other chart resource families are not exposed yet.

## Quick start

```text
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
./run.sh
```

The server listens on port 7016 by default. The port is configurable with `ASTRO_PORT`.

## Docker

```text
docker compose up --build
```

Health check: `GET http://localhost:7016/health`

## Configuration

| Variable | Default | Description |
|---|---|---|
| `ASTRO_HOST` | `0.0.0.0` | Bind address |
| `ASTRO_PORT` | `7016` | Listen port |
| `ASTRO_DATA_DIR` | `./data` | SQLite database directory |
| `ASTRO_LOG_DIR` | `./logs` | Log directory |
| `EPHEMERIS_MCP_URL` | `http://192.168.0.200:7015/mcp/sse` | Ephemeris MCP endpoint |
| `GEONAMES_USERNAME` | empty | GeoNames username for birthplace autocomplete |
| `DASHBOARD_24H_TIME` | `true` | Use 24-hour time in dashboard forms |

## MCP endpoint

SSE transport: `http://localhost:7016/mcp/sse`

## Calculation tools

The calculation surface remains structured-data oriented:

| Tool | Purpose |
|---|---|
| `get_planetary_positions` | Planetary positions with signs, degrees, and retrograde flags |
| `calculate_natal_chart` | Natal chart from direct birth data |
| `calculate_transit_chart` | Transit-to-natal chart calculation |
| `calculate_synastry_chart` | Two-person relationship chart calculation |
| `calculate_composite_chart` | Composite chart calculation |
| `calculate_davison_chart` | Davison chart calculation |
| `get_transit_preview` | Transit-to-natal snapshots over a date range |
| `get_composite_transit_preview` | Composite transit preview |
| `get_davison_transit_preview` | Davison transit preview |
| `get_karmic_relationship_summary` | Structured relationship summary |
| `person_manage` | Person database management |
| `list_house_systems` | Supported house systems |

Database-backed calculation variants include the relevant `_by_id` tools and accept a person ID or nickname.

## Person database datetime convention

The database stores `birth_datetime` as naive local time and `timezone` as an IANA timezone name. For example:

```text
birth_datetime = 1953-03-23T21:05:00
timezone = America/Chicago
```

UTC conversion happens in `_get_person_birth_data()`. Do not store UTC or offset-aware values in the database `birth_datetime` column.

## Dashboard

The person-management dashboard is available at:

```text
http://localhost:7016/dashboard
```

It supports listing, adding, editing, importing, exporting, and deleting persons. Chart artifact delivery is available independently through the `/charts/natal/{person_id}.{format}` HTTP route.

## Verification

Run the test suite with:

```text
pytest
```

The v0.2.0 contract includes removal of all `render_*` MCP tools, registration of `astro://charts/natal/{person_id}`, and the human-facing natal chart HTTP route.