Home Explore Help
Sign In
lucky
/
astro-mcp
1
0
Fork 0
Files Issues 0 Pull Requests 0 Wiki
Branch: main
Branches Tags
astro-mcp
/
IMPLEMENTATION_PLAN_v0.2.0.md

IMPLEMENTATION_PLAN_v0.2.0.md 5.6 KB
Permalink History Raw

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:

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

The natal chart resource implemented in v0.2.0 is:

astro://charts/natal/{person_id}

Example:

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:

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

Examples:

/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:

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:

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.