# astro-mcp

MCP server for astrological chart calculations. Consumes `ephemeris-mcp:get_sky_state`
via MCP-over-SSE client and exposes calculated astrological data (natal charts, transits,
synastry, transit previews) as structured JSON tools.

## Quick Start

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
./run.sh
```

Server listens on port 7016 (configurable via `ASTRO_PORT`).

## Docker

```bash
docker compose up --build
```

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

## MCP Endpoint

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

## Tools

### Core tools (raw birth data)

| Tool | Description |
|---|---|
| `get_planetary_positions` | Planetary positions with zodiac signs, degrees, retrograde flags |
| `calculate_natal_chart` | Complete natal chart (planets, houses, aspects, angles). Params: birth_datetime, latitude, longitude |
| `calculate_transit_chart` | Transit chart with natal-to-transit aspects. Params: birth_datetime, transit_datetime, latitude, longitude, transit_latitude, transit_longitude |
| `calculate_synastry_chart` | Relationship chart for two people. Params: person1_datetime/lat/lon, person2_datetime/lat/lon |
| `calculate_composite_chart` | Composite chart via midpoint method. Params: same as synastry |
| `get_transit_preview` | Daily transit-to-natal aspect snapshot. Params: birth_datetime, latitude, longitude, start_date, end_date |
| `person_manage` | CRUD for persons database (name, nickname, birthplace, birth_datetime, lat/lon, elevation) |
| `list_house_systems` | List supported house systems |

### _byId tools (database-backed)

Each core chart tool has a `_byId` variant that accepts a `person_id` (from the persons
database) instead of raw birth data. All other optional parameters override the defaults.

| Tool | Description |
|---|---|
| `calculate_natal_chart_by_id` | Natal chart by person_id |
| `calculate_transit_chart_by_id` | Transit chart by person_id + transit_datetime |
| `calculate_synastry_chart_by_id` | Synastry chart for person1_id + person2_id |
| `calculate_composite_chart_by_id` | Composite chart for person1_id + person2_id |
| `get_transit_preview_by_id` | Transit preview by person_id + date range |

### Person database

`person_manage` supports actions: `add`, `get` (by id or nickname), `list`, `update`, `delete`.

Example workflow:
```
person_manage(action="add", name="Me", birth_datetime="1965-07-02T00:05:00+02:00",
              birthplace="Graz, Austria", latitude=47.076668, longitude=15.421371)
=> {"person": {"id": "abc12345", ...}}

# Then use the _byId tools:
calculate_natal_chart_by_id(person_id="abc12345")
calculate_transit_chart_by_id(person_id="abc12345", transit_datetime="2026-06-02T12:00:00")
```

## Dashboard

Person management dashboard at `http://localhost:7016/dashboard`