astro-mcp/agent-guides/server-guide.md

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

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:

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:

astro://charts/natal/{person_id}

Example:

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

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

Examples:

/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

calculate_natal_chart_by_id(person_id="einstein")

Get a rendered natal chart for a stored person

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

Display a rendered natal chart in a browser

GET /charts/natal/einstein.svg

Calculate a one-off chart

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.