# Astro MCP v0.2.0 Implementation Plan

## Purpose

Replace the current MCP chart-rendering tools with resource-based delivery for agents and HTTP URL-based delivery for humans.

This version concerns only how already-rendered charts are exposed and delivered. The existing chart drawing and rendering implementation is stable and must not be changed.

## Scope

### In scope

- Remove all MCP tools whose names begin with `render_`.
- Expose database-backed natal chart graphics as MCP resources.
- Expose database-backed natal chart graphics through a human-facing HTTP URL.
- Reuse the existing natal chart calculation and rendering code without changing its behavior.
- Implement natal chart delivery in this version.
- Reserve the URI namespace for future chart types without implementing them now.

### Out of scope

- Changes to chart calculations.
- Changes to chart drawing, layout, styles, colors, dimensions, or format conversion.
- Changes to `chart_renderer.py` or its rendering functions.
- New rendering features or rendering options.
- Transit, synastry, composite, or Davison chart resources.
- Legacy wrappers, compatibility routes, migration behavior, or transition support.
- Reordering or canonicalizing `person1_id` and `person2_id`.

## Agreed URI scheme

The resource namespace is organized by chart type:

```text
astro://charts/{chart_type}/{identifiers}?{options}
```

The natal chart resource implemented in v0.2.0 is:

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

Example:

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

The chart is rendered for a person resolved from the persons database. Only database-backed person identifiers are accepted.

Query parameters may be supported only when they already map to capabilities of the current implementation. No new rendering behavior is introduced by this plan.

## MCP resource behavior

The natal resource handler will:

1. Receive a natal chart resource URI.
2. Extract and validate `person_id`.
3. Resolve the person using the existing database lookup behavior.
4. Use the existing database-backed natal chart calculation path.
5. Call the existing natal chart renderer unchanged.
6. Return the rendered chart as MCP resource content with the appropriate MIME type.

The resource is intended to give an agent a graphic artifact that it can read, save, or attach. It must not expose the current large and complicated `render_*` tool interface.

The v0.2.0 MCP resource returns the default SVG artifact with MIME type `image/svg+xml`. The resource URI has no rendering-option query parameters in this implementation.

## Human-facing HTTP delivery

Add an HTTP chart URL for the same database-backed natal chart artifact:

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

Examples:

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

The HTTP endpoint accepts the renderer's existing format suffixes (`svg`, `png`, `jpg`, `jpeg`) and the existing `size` query parameter. It must call the same existing natal calculation and rendering path and return the resulting artifact with the correct HTTP `Content-Type`.

The HTTP endpoint must not modify or duplicate chart drawing logic.

## Shared delivery path

MCP resource delivery and HTTP delivery should share the non-rendering orchestration needed to:

- Parse the chart identity.
- Validate the person identifier.
- Resolve the person from the database.
- Invoke the existing natal chart calculation path.
- Invoke the existing natal chart renderer.
- Package the result for MCP or HTTP delivery.

The renderer itself remains untouched. Any required adapter should be limited to delivery integration.

## MCP tool removal

Remove every MCP tool whose name begins with `render_` from the exposed tool surface and delete the associated tool wrappers. No render tool remains in v0.2.0.

Do not remove or alter the underlying renderer functions, including the existing natal wheel renderer. They remain internal implementation code for artifact generation.

Do not remove or alter the chart calculation tools.

## Future namespace reservation

The namespace leaves room for these future resource families:

```text
astro://charts/transit/{person_id}
astro://charts/synastry/{person1_id}/{person2_id}
astro://charts/composite/{person1_id}/{person2_id}
astro://charts/davison/{person1_id}/{person2_id}
```

These are not implemented in v0.2.0.

For future two-person chart types, `person1_id` and `person2_id` are intentionally distinct. The drawing roles are not assumed to be interchangeable, so the identifiers must not be reordered or canonicalized by this plan.

## Verification requirements

Before v0.2.0 is considered complete, verify that:

- The `render_*` MCP tools are no longer registered or exposed.
- Existing chart calculation tools remain available.
- `astro://charts/natal/{person_id}` is discoverable as a resource template.
- A valid database person produces an SVG natal chart resource.
- Supported raster output is delivered with the correct MIME type.
- Unknown persons produce an appropriate resource error.
- Invalid resource input is rejected appropriately.
- The human-facing natal chart URL returns the existing rendered artifact.
- The MCP resource and HTTP endpoint use the existing rendering behavior.
- No chart drawing or rendering implementation files were changed unnecessarily.

## Implementation boundary

The implementation is complete when the following delivery model works:

```text
MCP resource URI or HTTP chart URL
    -> database-backed person lookup
    -> existing natal chart calculation
    -> existing chart renderer
    -> MCP artifact or HTTP artifact response
```

No additional chart features or rendering changes belong in v0.2.0.