astro-mcp/AGENTS.md

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.