# AGENTS.md — Astro-MCP Agent Guide

## Datetime Convention (CRITICAL)

This server has **two distinct datetime formats**. Using the wrong one produces
silent errors.

### 1. Person Database (persons table)

- `birth_datetime`: **naive local time** — no `Z`, no `+01:00`
- `timezone`: IANA name (e.g. `"America/Chicago"`, `"Europe/Berlin"`)

Example: Chaka Khan born 9:05 PM in Chicago → store as:
- `birth_datetime = "1953-03-23T21:05:00"`
- `timezone = "America/Chicago"`

The conversion to UTC happens inside `_get_person_birth_data()` using
`zoneinfo.ZoneInfo`. Do NOT pre-convert to UTC before storing.

### 2. Direct-Call Tools (calculate_natal_chart, render_natal_chart, etc.)

- `birth_datetime`: **UTC or offset-aware** ISO 8601

Examples:
- UTC: `"1990-05-15T10:30:00Z"` or `"1990-05-15T10:30:00+00:00"`
- Offset-aware: `"1990-05-15T12:30:00+02:00"`

These tools pass the datetime directly to the ephemeris server. No timezone
conversion is performed.

### 3. _byId Tools (calculate_natal_chart_by_id, render_natal_chart_by_id)

- Pass `person_id` (or nickname) only.
- Timezone conversion is handled automatically by `_get_person_birth_data()`.

### Historical Dates (pre-1890)

Before standardized timezones, IANA data uses Local Mean Time (LMT) which can
differ from modern UTC offsets by minutes. For example:
- Einstein, 1879, Ulm: LMT = UTC+0:53:28 (not modern CET UTC+1)
- The `zoneinfo` module handles this correctly when given the IANA name.

Always provide the `tz` field with the IANA name. Do NOT compute the UTC offset
manually for historical dates.

## Quick Reference

| Context | Format | Example |
|---------|--------|---------|
| DB `birth_datetime` | Naive local | `"1953-03-23T21:05:00"` |
| DB `timezone` | IANA name | `"America/Chicago"` |
| Direct-call tools | UTC or offset-aware | `"1953-03-24T03:05:00Z"` |
| _byId tools | person_id only | `"chaka"` |

## Common Mistakes

1. **Storing UTC in the DB** — produces wrong charts because `_get_person_birth_data()`
   expects local time. If you store `"03:05:00"` (UTC) without a timezone, the
   server treats it as 3:05 AM local Chicago = 08:05 UTC (wrong by 5 hours).
2. **Storing offset-aware datetime in the DB** — if `birth_datetime` has an offset
   (e.g. `"-07:05"`), `_normalize_datetime()` uses that offset directly and
   ignores the `timezone` column. The offset may be wrong (e.g. Chicago is CST
   = UTC-6, not UTC-7).
3. **Missing `tz` field** — falls back to LMT from longitude, which is approximately
   correct but not precise. Always set `tz`.