# Astro-MCP v0.2.0 Server Guide

## Overview

Astro-MCP calculates astrological chart data from the `ephemeris-mcp` Swiss Ephemeris backend. It also provides database-backed natal chart graphics through an MCP resource and a human-facing HTTP URL.

The server does not interpret charts. Calculation tools return structured data; rendered chart delivery returns graphic artifacts.

## Architecture

```text
Agent or human client
       |
       v
astro-mcp v0.2.0
       | MCP client
       v
ephemeris-mcp
```

Astro-MCP handles person storage, timezone conversion, astrological calculations, stable chart rendering, MCP tools/resources, dashboard routes, and HTTP chart delivery. Ephemeris-MCP handles astronomical calculations.

## Datetime rules

The persons database stores:

- `birth_datetime`: naive local time with no offset
- `timezone`: IANA timezone name

Example:

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

`_get_person_birth_data()` is the single conversion point for database-backed chart calls. It combines the local datetime with the IANA timezone and produces the UTC value used by the ephemeris client.

Direct calculation tools require UTC or offset-aware ISO 8601 datetimes. Database-backed calculation tools require only a person ID or nickname.

For historical dates, provide the IANA timezone. `zoneinfo` handles historical Local Mean Time where applicable.

## Calculation tools

The current tool surface includes:

- `get_planetary_positions`
- `calculate_natal_chart`
- `calculate_transit_chart`
- `calculate_synastry_chart`
- `calculate_composite_chart`
- `calculate_davison_chart`
- `get_transit_preview`
- `get_composite_transit_preview`
- `get_davison_transit_preview`
- `get_karmic_relationship_summary`
- `calculate_natal_chart_by_id`
- `calculate_transit_chart_by_id`
- `calculate_synastry_chart_by_id`
- `calculate_composite_chart_by_id`
- `calculate_davison_chart_by_id`
- `get_transit_preview_by_id`
- `person_manage`
- `list_house_systems`

Calculation tools return structured data. There are no `render_*` MCP tools in v0.2.0.

## Rendered natal chart resource

The implemented chart resource template is:

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

Example:

```text
astro://charts/natal/einstein
```

Reading this resource resolves the person from the database, calculates the natal chart, invokes the existing natal chart renderer, and returns the graphic artifact. The agent can read the resource and save or attach the returned artifact.

Only database-backed natal chart delivery is implemented in v0.2.0.

## Human-facing chart URL

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

Examples:

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

The route returns the existing rendered artifact with the correct image MIME type. It shares the artifact-generation path with the MCP resource.

## Stable rendering boundary

The chart drawing implementation is stable and is not part of the v0.2.0 delivery change. Delivery code calls the existing renderer; it does not alter chart geometry, layout, styles, colors, dimensions, or format conversion.

## Other MCP resources

The server also exposes interpretation guides:

- `astro://guides/natal-astrology`
- `astro://guides/karmic-astrology`
- `astro://guides/relationship-astrology`
- `astro://guides/financial-astrology`
- `astro://guides/server-guide`

## Common workflows

### Get natal data for a stored person

```text
calculate_natal_chart_by_id(person_id="einstein")
```

### Get a rendered natal chart for a stored person

```text
Read resource: astro://charts/natal/einstein
```

### Display a rendered natal chart in a browser

```text
GET /charts/natal/einstein.svg
```

### Calculate a one-off chart

```text
calculate_natal_chart(
    birth_datetime="1990-05-15T10:30:00+01:00",
    latitude=47.07,
    longitude=15.42
)
```

## Errors

Calculation tools use structured error results. Resource reads and HTTP chart requests reject unknown persons and unsupported request values. A person resource requires an identifier that resolves by database ID or nickname.

## v0.2.0 non-goals

The following are not implemented as chart resources in this version:

- Transit charts
- Synastry charts
- Composite charts
- Davison charts
- New rendering features or options
- Caching or compatibility routes

They must not be described as available chart resources until implemented.