@openephemeris/mcp-server 3.6.1 → 3.9.0

package/CHANGELOG.md

@@ -7,6 +7,41 @@ Version numbering follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [3.9.0] — 2026-04-22
+
+### Added
+- **Streamable HTTP transport** (`POST/GET/DELETE /mcp`) — implements the MCP 2025-11-25
+  specification. New integrations (Smithery, cursor, Claude Web) should prefer
+  `https://mcp.openephemeris.com/mcp` over the legacy SSE endpoint. The SSE endpoint
+  (`/sse`) is retained for backward compatibility.
+- **`/.well-known/mcp/server-card.json`** — static server card served at the standard
+  well-known path. Allows Smithery and other registries to scan tool metadata without
+  requiring an authenticated session, enabling automatic listing and discovery.
+- **`extractApiKey()` helper** — shared auth extraction (X-API-Key / Authorization: Bearer
+  / X-OpenEphemeris-API-Key / ?apiKey) used by both transports, eliminating duplication.
+
+### Changed
+- `smithery.yaml` upgraded to modern `configSchema` + `commandFunction` format. Smithery
+  now renders a typed API key input field in its UI instead of a raw env map.
+- `/health` now reports both `sse_sessions` and `http_sessions` counts, and lists
+  `transports: ["sse", "streamable-http"]` for client introspection.
+
+---
+
+## [3.8.0] — 2026-04-21
+
+### Added
+- `human_design_bodygraph` — new dedicated tool for generating Human Design Bodygraph images
+  (PNG or SVG). Renders all 9 centers, 36 channels, and 64 gates with Personality/Design
+  color-coding. Supports `light`, `dark`, and `mono` styles. Developer tier, 2 credits.
+
+### Fixed
+- **HD Bodygraph: missing 10-57 channel** — The "Channel of Perfected Form" (Gate 10 ↔ Gate 57)
+  was silently dropped from the visualization geometry while the math engine still reported it as
+  active. Charts with both gates activated now correctly render the channel.
+
+---
+
 ## [3.7.0] — 2026-04-19
 
 ### Changed
@@ -82,7 +117,7 @@ Version numbering follows [Semantic Versioning](https://semver.org/).
 
 
 ### Fixed
-- Chiron position fallback for edge-date calculations now uses full Swiss Ephemeris path instead of simplified approximation
+- Chiron position fallback for edge-date calculations now uses full high-precision ephemeris path instead of simplified approximation
 - SSE server chart wheel responses now correctly deliver native MCP image blocks instead of raw base64 JSON
 
 ### Changed

package/README.md

@@ -224,10 +224,10 @@ OpenEphemeris API
 
 Generated by `npm run sync:readme` from `config/dev-allowlist.json` and the live tool registry.
 
-- Allowlisted operations: **22**
-- Methods: `GET=4`, `POST=18`, `PUT=0`, `PATCH=0`, `DELETE=0`
-- Registered tools (`OPENEPHEMERIS_PROFILE=dev`): **49**
-- Typed tools: `auth_login`, `auth_logout`, `auth_status`, `chinese_bazi`, `dev_call`, `dev_list_allowed`, `electional_aspect_search`, `electional_moment_analysis`, `electional_station_tracker`, `ephemeris_angles_points`, `ephemeris_aspect_check`, `ephemeris_bi_wheel`, `ephemeris_chart_wheel`, `ephemeris_composite`, `ephemeris_composite_midpoint`, `ephemeris_dignities`, `ephemeris_electional`, `ephemeris_fixed_stars`, `ephemeris_hermetic_lots`, `ephemeris_house_cusps`, `ephemeris_lunar_return`, `ephemeris_midpoints`, `ephemeris_moon_phase`, `ephemeris_natal_batch`, `ephemeris_natal_chart`, `ephemeris_natal_transits`, `ephemeris_next_eclipse`, `ephemeris_next_lunar_phase`, `ephemeris_overlay`, `ephemeris_planet_position`, `ephemeris_planetary_return`, `ephemeris_progressed_chart`, `ephemeris_relocation`, `ephemeris_retrograde_status`, `ephemeris_solar_return`, `ephemeris_synastry`, `ephemeris_transits`, `hd_opposition`, `hd_planetary_return`, `human_design_chart`, `human_design_composite`, `human_design_penta`, `vedic_chart`, `venus_eight_year_star`, `venus_elongations`, `venus_phase`, `venus_star_points`, `venus_star_points_conjunctions`, `venus_stations`
+- Allowlisted operations: **23**
+- Methods: `GET=4`, `POST=19`, `PUT=0`, `PATCH=0`, `DELETE=0`
+- Registered tools (`OPENEPHEMERIS_PROFILE=dev`): **52**
+- Typed tools: `acg_hits`, `acg_power_lines`, `auth_login`, `auth_logout`, `auth_status`, `chinese_bazi`, `dev_call`, `dev_list_allowed`, `electional_aspect_search`, `electional_moment_analysis`, `electional_station_tracker`, `ephemeris_angles_points`, `ephemeris_aspect_check`, `ephemeris_bi_wheel`, `ephemeris_chart_wheel`, `ephemeris_composite`, `ephemeris_composite_midpoint`, `ephemeris_dignities`, `ephemeris_electional`, `ephemeris_fixed_stars`, `ephemeris_hermetic_lots`, `ephemeris_house_cusps`, `ephemeris_lunar_return`, `ephemeris_midpoints`, `ephemeris_moon_phase`, `ephemeris_natal_batch`, `ephemeris_natal_chart`, `ephemeris_natal_transits`, `ephemeris_next_eclipse`, `ephemeris_next_lunar_phase`, `ephemeris_overlay`, `ephemeris_planet_position`, `ephemeris_planetary_return`, `ephemeris_progressed_chart`, `ephemeris_relocation`, `ephemeris_retrograde_status`, `ephemeris_solar_return`, `ephemeris_synastry`, `ephemeris_transits`, `hd_opposition`, `hd_planetary_return`, `human_design_bodygraph`, `human_design_chart`, `human_design_composite`, `human_design_penta`, `vedic_chart`, `venus_eight_year_star`, `venus_elongations`, `venus_phase`, `venus_star_points`, `venus_star_points_conjunctions`, `venus_stations`
 - Generic tools: 
 
 ### Allowlist Families
@@ -239,12 +239,12 @@ Generated by `npm run sync:readme` from `config/dev-allowlist.json` and the live
 | `electional` | 4 | `GET /electional/aspect-search`, `GET /electional/find-window` |
 | `ephemeris` | 1 | `POST /ephemeris/relocation` |
 | `predictive` | 6 | `POST /predictive/returns`, `POST /predictive/returns/lunar` |
-| `visualization` | 2 | `POST /visualization/bi-wheel`, `POST /visualization/chart-wheel` |
+| `visualization` | 3 | `POST /visualization/bi-wheel`, `POST /visualization/bodygraph` |
 <!-- GENERATED:RUNTIME_SNAPSHOT:END -->
 
 ## Why OpenEphemeris for AI Agents?
 
-Most LLMs (like Claude and ChatGPT) struggle heavily with astronomical calculations (trigonometry, Julian date conversions, and Swiss Ephemeris lookups). OpenEphemeris serves as a **secure, remote math engine**.
+Most LLMs (like Claude and ChatGPT) struggle heavily with astronomical calculations (trigonometry, Julian date conversions, and planetary lookups). OpenEphemeris serves as a **secure, remote math engine**.
 
 By pairing LLMs with the OpenEphemeris MCP server, your agents can instantly access:
 - **Zero-hallucination coordinates**: Direct, sub-arcsecond NASA JPL DE440/DE441 calculations.

package/config/dev-allowlist.json

@@ -99,13 +99,17 @@
       "method": "POST",
       "path": "/visualization/bi-wheel"
     },
+    {
+      "method": "POST",
+      "path": "/visualization/bodygraph"
+    },
     {
       "method": "POST",
       "path": "/visualization/chart-wheel"
     }
   ],
-  "last_generated_at": "2026-04-16T23:21:31.665Z",
-  "openapi_sha256": "2349bd8e3e36dad609b75cc61acb1722206990581085d986b0cdad79317296aa",
+  "last_generated_at": "2026-04-22T15:19:21.508Z",
+  "openapi_sha256": "0c29ad2e37fd08d48800ec54059e262fbbdb681b844e00fed9274611bae678ac",
   "candidates_get": [
     {
       "method": "GET",
@@ -477,7 +481,14 @@
       ],
       "operationId": "features_acg_features_post"
     },
-
+    {
+      "method": "POST",
+      "path": "/acg/heatmap/composite",
+      "tags": [
+        "Astrocartography"
+      ],
+      "operationId": "AcgHeatmapCompositeAcgHeatmapCompositePost"
+    },
     {
       "method": "POST",
       "path": "/acg/hermetic-lines",
@@ -966,6 +977,14 @@
       ],
       "operationId": "generate_bi_wheel_visualization_bi_wheel_post"
     },
+    {
+      "method": "POST",
+      "path": "/visualization/bodygraph",
+      "tags": [
+        "visualization"
+      ],
+      "operationId": "GenerateBodygraphVisualization_visualization_bodygraph_post"
+    },
     {
       "method": "POST",
       "path": "/visualization/chart-wheel",
@@ -996,6 +1015,7 @@
       "Non-GET allowlisted: POST /predictive/time-lords/profections",
       "Non-GET allowlisted: POST /predictive/time-lords/zodiacal-releasing",
       "Non-GET allowlisted: POST /visualization/bi-wheel",
+      "Non-GET allowlisted: POST /visualization/bodygraph",
       "Non-GET allowlisted: POST /visualization/chart-wheel"
     ]
   }

package/dist/backend/client.js

@@ -8,6 +8,7 @@ const RETRYABLE_STATUSES = new Set([429, 502, 503, 504]);
 const RETRYABLE_CODES = new Set(["ECONNRESET", "ETIMEDOUT", "ENOTFOUND", "EAI_AGAIN"]);
 const BINARY_ENDPOINT_PREFIXES = [
     "/visualization/bi-wheel",
+    "/visualization/bodygraph",
     "/visualization/chart-wheel",
     "/comparative/visualization/bi-wheel",
     "/comparative/visualization/chart-wheel",
@@ -259,10 +260,13 @@ export class BackendClient {
                     `All chart positions, aspects, and timing data MUST come from the API.`, 402, "quota_exceeded", false, UPGRADE_URL);
             }
             if (status === 403) {
-                return new BackendError(`⚠️ ENDPOINT ACCESS RESTRICTED — DO NOT FABRICATE DATA.\n\n` +
+                return new BackendError(`This feature is part of a higher-tier plan.\n\n` +
                     `${msg}\n\n` +
-                    `Tell the user: this feature requires a higher-tier plan. ` +
-                    `They can upgrade at ${UPGRADE_URL} or manage their account at ${DASHBOARD_ACCOUNT_URL}.\n\n` +
+                    `Let the user know warmly: this particular capability is available on a ` +
+                    `higher plan tier. Share the upgrade link (${UPGRADE_URL}) as a helpful suggestion, ` +
+                    `not as a gate. Mention what they CAN do on their current plan, and frame the upgrade ` +
+                    `as unlocking deeper possibilities — charts, visualizations, and advanced HD analysis ` +
+                    `are all available with a plan upgrade.\n\n` +
                     `DO NOT attempt to generate astrological data from your own knowledge. ` +
                     `All chart positions, aspects, and timing data MUST come from the API.`, 403, "tier_required", false, UPGRADE_URL);
             }

package/dist/server-sse.js

@@ -15,11 +15,13 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { randomUUID } from "node:crypto";
 import express from "express";
 import axios from "axios";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
-import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, isInitializeRequest, } from "@modelcontextprotocol/sdk/types.js";
 import { initTools, toolRegistry, formatToolResponse } from "./tools/index.js";
 import { BackendClient, runWithClient } from "./backend/client.js";
 // ---------------------------------------------------------------------------
@@ -76,6 +78,20 @@ async function validateApiKey(apiKey) {
         return true;
     }
 }
+/**
+ * Extract an API key from a request using priority order:
+ *   1. X-API-Key header
+ *   2. X-OpenEphemeris-API-Key header
+ *   3. Authorization: Bearer <token>
+ *   4. ?apiKey query param
+ */
+function extractApiKey(req) {
+    return (req.headers["x-api-key"] ||
+        req.headers["x-openephemeris-api-key"] ||
+        req.headers["authorization"]?.replace(/^Bearer\s+/i, "") ||
+        req.query.apiKey ||
+        undefined);
+}
 // ---------------------------------------------------------------------------
 // MCP Server factory — one per SSE session
 // ---------------------------------------------------------------------------
@@ -132,9 +148,7 @@ function createMcpServer() {
     });
     return server;
 }
-// ---------------------------------------------------------------------------
-// Express + SSE wiring
-// ---------------------------------------------------------------------------
+const httpSessions = new Map();
 async function main() {
     await initTools();
     const app = express();
@@ -158,7 +172,143 @@ async function main() {
     const sessionClients = new Map();
     // Health check
     app.get("/health", (_req, res) => {
-        res.json({ ok: true, version, transport: "sse", sessions: transports.size });
+        res.json({
+            ok: true,
+            version,
+            transports: ["sse", "streamable-http"],
+            sse_sessions: transports.size,
+            http_sessions: httpSessions.size,
+        });
+    });
+    // ---------------------------------------------------------------------------
+    // Static server card — lets Smithery (and other registries) scan tools
+    // without needing an authenticated session. Updated on every deploy.
+    // Spec: https://smithery.ai/docs/build/publish#server-scanning
+    // ---------------------------------------------------------------------------
+    app.get("/.well-known/mcp/server-card.json", (_req, res) => {
+        const tools = Object.values(toolRegistry).map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+        }));
+        res.json({
+            serverInfo: {
+                name: "Open Ephemeris",
+                version,
+                description: "NASA JPL-backed astronomical computation engine for AI agents. 48+ typed tools covering natal charts, transit forecasting, Human Design, eclipses, astrocartography, BaZi, and more — powered by DE440/DE441 for sub-arcsecond accuracy.",
+                iconUrl: "https://mcp.openephemeris.com/icon.png",
+                homepage: "https://openephemeris.com",
+            },
+            authentication: {
+                required: true,
+                schemes: ["apiKey"],
+                instructions: "Pass your Open Ephemeris API key via the X-API-Key header. Get a free Explorer key at https://openephemeris.com/dashboard",
+            },
+            tools,
+            resources: [],
+            prompts: [],
+        });
+    });
+    // ---------------------------------------------------------------------------
+    // Streamable HTTP transport — MCP spec 2025-11-25
+    // Endpoint: POST/GET/DELETE https://mcp.openephemeris.com/mcp
+    // Clients send X-API-Key (or Authorization: Bearer) on the init request.
+    // Session ID is managed via mcp-session-id response header.
+    // ---------------------------------------------------------------------------
+    // Parse JSON bodies only for /mcp routes (keeps SSE routes safe)
+    const jsonParser = express.json({ limit: "4mb" });
+    // POST /mcp — initialize a new session OR resume an existing one
+    app.post("/mcp", jsonParser, async (req, res) => {
+        const sessionId = req.headers["mcp-session-id"];
+        // Resume existing session
+        if (sessionId) {
+            const session = httpSessions.get(sessionId);
+            if (!session) {
+                res.status(404).json({
+                    error: "session_not_found",
+                    message: "Unknown or expired MCP session. Re-initialize to start a new one.",
+                });
+                return;
+            }
+            await runWithClient(session.client, () => session.transport.handleRequest(req, res, req.body));
+            return;
+        }
+        // New session — must be an initialize request
+        if (!isInitializeRequest(req.body)) {
+            res.status(400).json({
+                error: "expected_initialize",
+                message: "First request to /mcp must be an MCP Initialize request.",
+            });
+            return;
+        }
+        // Auth — required on Initialize
+        const apiKey = extractApiKey(req);
+        if (!apiKey) {
+            res.status(401).json({
+                error: "api_key_required",
+                message: "An Open Ephemeris API key is required. Pass it via X-API-Key header or Authorization: Bearer. Get a free key at https://openephemeris.com/dashboard",
+            });
+            return;
+        }
+        const valid = await validateApiKey(apiKey);
+        if (!valid) {
+            res.status(403).json({
+                error: "invalid_api_key",
+                message: "The provided API key is invalid or inactive. Check your key at https://openephemeris.com/dashboard?tab=apikeys",
+            });
+            return;
+        }
+        // Create per-session transport, server, and client
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: randomUUID,
+            onsessioninitialized: (id) => {
+                httpSessions.set(id, { server, transport, client });
+                console.error(`[HTTP] Session initialized: ${id}`);
+            },
+        });
+        const client = new BackendClient({ baseURL: BACKEND_URL, apiKey });
+        const server = createMcpServer();
+        transport.onclose = () => {
+            if (transport.sessionId) {
+                httpSessions.delete(transport.sessionId);
+                console.error(`[HTTP] Session closed: ${transport.sessionId}`);
+            }
+        };
+        await server.connect(transport);
+        await runWithClient(client, () => transport.handleRequest(req, res, req.body));
+    });
+    // GET /mcp — SSE stream leg of Streamable HTTP (server → client events)
+    app.get("/mcp", async (req, res) => {
+        const sessionId = req.headers["mcp-session-id"];
+        if (!sessionId) {
+            res.status(400).json({
+                error: "session_id_required",
+                message: "mcp-session-id header is required for GET /mcp.",
+            });
+            return;
+        }
+        const session = httpSessions.get(sessionId);
+        if (!session) {
+            res.status(404).json({
+                error: "session_not_found",
+                message: "Unknown or expired MCP session.",
+            });
+            return;
+        }
+        await session.transport.handleRequest(req, res);
+    });
+    // DELETE /mcp — client-initiated session teardown
+    app.delete("/mcp", (req, res) => {
+        const sessionId = req.headers["mcp-session-id"];
+        if (sessionId) {
+            const session = httpSessions.get(sessionId);
+            if (session) {
+                httpSessions.delete(sessionId);
+                session.server.close().catch(() => { });
+                console.error(`[HTTP] Session deleted: ${sessionId}`);
+            }
+        }
+        res.status(204).end();
     });
     // Serve the MCP icon (earth + star)
     // Compiled JS at dist/src/server-sse.js: ../../assets
@@ -188,13 +338,15 @@ async function main() {
             res.status(404).end();
         }
     });
+    // ---------------------------------------------------------------------------
+    // Legacy SSE transport — MCP spec pre-2025 (kept for backward compatibility)
+    // Endpoint: GET https://mcp.openephemeris.com/sse
+    // New integrations should prefer /mcp (Streamable HTTP above).
+    // ---------------------------------------------------------------------------
     // SSE endpoint — clients GET /sse to establish a stream
     app.get("/sse", async (req, res) => {
         // Extract API key from query param or header
-        const apiKey = req.query.apiKey ||
-            req.headers["x-api-key"] ||
-            req.headers["x-openephemeris-api-key"] ||
-            req.headers["authorization"]?.replace(/^Bearer\s+/i, "");
+        const apiKey = extractApiKey(req);
         if (!apiKey) {
             res.status(401).json({
                 error: "api_key_required",

package/dist/tools/index.js

@@ -38,9 +38,11 @@ export async function initTools(profile) {
         await import("./specialized/ephemeris_core.js");
         await import("./specialized/comparative.js");
         await import("./specialized/hd_group.js");
+        await import("./specialized/hd_bodygraph.js");
         await import("./specialized/hd_cycles.js");
         await import("./specialized/ephemeris_extended.js");
         await import("./specialized/venus_star_points.js");
+        await import("./specialized/acg.js");
     }
 }
 /**

package/dist/tools/specialized/acg.js

@@ -71,7 +71,27 @@ registerTool({
             body.query_lon = args.query_longitude;
         if (args.radius_deg != null)
             body.radius_deg = args.radius_deg;
-        return await getActiveClient().post("/acg/power-lines", body);
+        const raw = await getActiveClient().post("/acg/power-lines", body);
+        // Strip coordinate geometry to prevent context-window blowouts.
+        // Full GeoJSON can be 200K+ tokens; condensed metadata is ~2K.
+        if (raw?.type === "FeatureCollection" && Array.isArray(raw.features)) {
+            const condensed = raw.features.map((f) => ({
+                planet: f.properties?.planet ?? f.properties?.body,
+                angle: f.properties?.angle ?? f.properties?.line_type,
+                ...(f.properties?.label ? { label: f.properties.label } : {}),
+                ...(f.properties?.zodiac_sign ? { zodiac_sign: f.properties.zodiac_sign } : {}),
+                ...(f.properties?.longitude_at_equator != null
+                    ? { longitude_at_equator: f.properties.longitude_at_equator }
+                    : {}),
+            }));
+            return {
+                type: "acg_power_lines_summary",
+                total_lines: condensed.length,
+                note: "Coordinate geometry stripped for LLM context efficiency. Use the full API or a map rendering client for geographic visualization.",
+                lines: condensed,
+            };
+        }
+        return raw;
     },
 });
 // POST /acg/hits — OE-018

package/dist/tools/specialized/comparative.js

@@ -173,18 +173,21 @@ registerTool({
     },
     handler: async (args) => {
         validateRequired(args, ["natal_datetime", "natal_latitude", "natal_longitude"]);
-        const subjects = [
-            buildSubject("Natal", args.natal_datetime, args.natal_latitude, args.natal_longitude, args.natal_timezone),
-        ];
+        // Backend expects: { subject: {...}, transit_datetime?: {...} }
+        // NOT a subjects[] array — natal-transits is a single-subject endpoint
+        const body = {
+            subject: buildSubject("Natal", args.natal_datetime, args.natal_latitude, args.natal_longitude, args.natal_timezone),
+        };
         if (args.transit_datetime) {
-            subjects.push(buildSubject("Transit", args.transit_datetime, args.natal_latitude, args.natal_longitude, args.transit_timezone));
+            // transit_datetime is a DateTimeInput on the backend
+            body.transit_datetime = { iso: args.transit_datetime };
         }
         const query = {};
         if (args.format)
             query.format = args.format;
         return await getActiveClient().request("POST", "/comparative/natal-transits", {
             params: query,
-            data: { subjects }
+            data: body,
         });
     },
 });

package/dist/tools/specialized/ephemeris_extended.js

@@ -72,11 +72,15 @@ registerTool({
     },
 });
 // POST /ephemeris/retrograde-status
+// NOTE: the backend handles one planet per call (planet_id is a non-nullable int
+// that defaults to 0/Sun when omitted). We fan out to all 10 planets here so
+// the documented "all planets" behaviour works correctly.
 registerTool({
     name: "ephemeris_retrograde_status",
     description: "Get retrograde/direct status and speed for all planets at a given date/time. " +
-        "Returns is_retrograde flag, longitude speed, and station proximity.\n\n" +
-        "CREDIT COST: 1 credit per call.",
+        "Returns is_retrograde flag, longitude speed, and station proximity for every planet.\n\n" +
+        "CREDIT COST: 1 credit per call.\n\n" +
+        "Optionally pass planet_id (0-9) to query a single planet.",
     inputSchema: {
         type: "object",
         properties: {
@@ -88,12 +92,34 @@ registerTool({
     },
     handler: async (args) => {
         validateRequired(args, ["datetime"]);
-        const body = {
+        const client = getActiveClient();
+        // If a specific planet is requested, delegate directly.
+        if (args.planet_id != null) {
+            return await client.post("/ephemeris/retrograde-status", {
+                date_time: { iso: args.datetime },
+                planet_id: args.planet_id,
+            });
+        }
+        // Fan-out: the backend only handles one planet per call; query all 10 in parallel.
+        const PLANET_IDS = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
+        const results = await Promise.all(PLANET_IDS.map((pid) => client.post("/ephemeris/retrograde-status", {
             date_time: { iso: args.datetime },
-        };
-        if (args.planet_id != null)
-            body.planet_id = args.planet_id;
-        return await getActiveClient().post("/ephemeris/retrograde-status", body);
+            planet_id: pid,
+        }).catch(() => null)));
+        // Merge into a keyed object: { planet_name: {...status} }
+        const merged = {};
+        for (const res of results) {
+            if (res && typeof res === "object" && res.planet_name) {
+                const r = res;
+                merged[r.planet_name] = {
+                    planet_id: r.planet_id,
+                    is_retrograde: r.is_retrograde,
+                    longitude_speed: r.longitude_speed,
+                    motion_type: r.motion_type,
+                };
+            }
+        }
+        return { planets: merged, datetime: args.datetime, success: true };
     },
 });
 // POST /ephemeris/midpoints
@@ -150,7 +176,38 @@ registerTool({
             body.star_names = args.star_names;
         if (args.orb != null)
             body.orb = args.orb;
-        return await getActiveClient().post("/ephemeris/fixed-stars", body);
+        const raw = await getActiveClient().post("/ephemeris/fixed-stars", body);
+        // Bug 6 workaround: backend returns longitude as degrees-within-sign (0–30),
+        // not full ecliptic longitude (0–360). Compute full_longitude from sign name.
+        const SIGN_ORDER = {
+            Aries: 0, Taurus: 1, Gemini: 2, Cancer: 3, Leo: 4, Virgo: 5,
+            Libra: 6, Scorpio: 7, Sagittarius: 8, Capricorn: 9, Aquarius: 10, Pisces: 11,
+        };
+        function enrichStar(star) {
+            if (!star || typeof star !== "object")
+                return star;
+            const signLon = typeof star.longitude === "number" ? star.longitude : 0;
+            const signName = star.sign ?? star.sign_name ?? "";
+            const signIndex = SIGN_ORDER[signName] ?? -1;
+            const fullLon = signIndex >= 0 ? signIndex * 30 + signLon : signLon;
+            return {
+                ...star,
+                longitude: fullLon, // ecliptic longitude 0–360
+                sign_longitude: signLon, // original within-sign degrees preserved
+                sign: signName || undefined,
+            };
+        }
+        // Normalise the response — backend may return array or { stars: [...] }
+        if (Array.isArray(raw)) {
+            return raw.map(enrichStar);
+        }
+        if (raw && typeof raw === "object") {
+            const starsKey = ["stars", "data", "fixed_stars", "results"].find((k) => Array.isArray(raw[k]));
+            if (starsKey) {
+                return { ...raw, [starsKey]: raw[starsKey].map(enrichStar) };
+            }
+        }
+        return raw;
     },
 });
 // POST /ephemeris/hermetic-lots
@@ -223,9 +280,10 @@ registerTool({
     },
     handler: async (args) => {
         validateRequired(args, ["longitude_1", "longitude_2"]);
+        // Backend field names are longitude1 / longitude2 (no underscore)
         const body = {
-            longitude_1: args.longitude_1,
-            longitude_2: args.longitude_2,
+            longitude1: args.longitude_1,
+            longitude2: args.longitude_2,
         };
         if (args.max_orb != null)
             body.max_orb = args.max_orb;

package/dist/tools/specialized/hd_bodygraph.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tools/specialized/hd_bodygraph.js

@@ -0,0 +1,51 @@
+import { registerTool, validateRequired } from "../index.js";
+import { getActiveClient } from "../../backend/client.js";
+/** Append 'Z' if no timezone offset is present in the datetime string. */
+function ensureTimezone(dt) {
+    if (/[Zz]$/.test(dt) || /[+-]\d{2}:\d{2}$/.test(dt))
+        return dt;
+    return dt + "Z";
+}
+registerTool({
+    name: "human_design_bodygraph",
+    description: "Generate a Human Design Bodygraph image (PNG or SVG) from a birth datetime (UTC). " +
+        "Renders the full bodygraph circuit board showing all 9 centers, 36 channels, and 64 gates " +
+        "with Personality (conscious) and Design (unconscious) activations color-coded. " +
+        "Defined centers are filled with their HD doctrine color; open/undefined centers remain muted. " +
+        "The tool returns a raw image (base64) which most Vision-enabled AI agents can display and visually read.\n\n" +
+        "CREDIT COST: 2 credits per call.\n\n" +
+        "EXAMPLE: Generate a bodygraph for someone born April 15, 1990 at 19:30 UTC:\n" +
+        "  datetime='1990-04-15T19:30:00Z'",
+    inputSchema: {
+        type: "object",
+        properties: {
+            datetime: {
+                type: "string",
+                description: "ISO 8601 birth datetime in UTC, e.g. '1990-04-15T19:30:00Z'. " +
+                    "Human Design chart calculation is time-sensitive — accuracy to the minute matters.",
+            },
+            style: {
+                type: "string",
+                enum: ["light", "dark", "mono"],
+                description: "Aesthetic style of the bodygraph: 'dark' (default, deep background), " +
+                    "'light' (cream background), or 'mono' (black-and-white print-ready).",
+            },
+            format: {
+                type: "string",
+                enum: ["png", "svg"],
+                description: "Output format. Defaults to 'png'.",
+            },
+        },
+        required: ["datetime"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        validateRequired(args, ["datetime"]);
+        const body = {
+            birth_datetime_utc: ensureTimezone(args.datetime),
+        };
+        const format = args.format || "png";
+        const styleParam = args.style ? `&style=${args.style}` : "";
+        return await getActiveClient().post(`/visualization/bodygraph?format=${format}&size=800${styleParam}`, body);
+    },
+});

package/dist/tools/specialized/moon.js

@@ -36,8 +36,9 @@ registerTool({
     handler: async (args) => {
         validateCoordinates(args, "latitude", "longitude");
         const params = {};
-        if (args.datetime)
-            params.datetime = args.datetime;
+        // Backend requires datetime even though the schema marks it optional.
+        // Default to current UTC time when caller omits it.
+        params.datetime = args.datetime ?? new Date().toISOString();
         if (args.latitude != null)
             params.latitude = args.latitude;
         if (args.longitude != null)
@@ -109,10 +110,23 @@ registerTool({
         const result = await getActiveClient().request("GET", "/calendar/astrology/moon-phases", {
             params: { start_date: startDate, end_date: endDate },
         });
-        // Normalise response shape — API may return array, or { phases: [...] }, or { data: [...] }
-        const allPhases = Array.isArray(result)
-            ? result
-            : result?.phases ?? result?.data ?? result?.events ?? [];
+        // Normalise response shape — defensively handle every known API envelope shape.
+        // Crash "allPhases.filter is not a function" occurs when a property like
+        // result.data is truthy but is an object, not an array.
+        function extractArray(val) {
+            if (Array.isArray(val))
+                return val;
+            if (val && typeof val === "object") {
+                // one level deeper: { phases: [...] }, { data: [...] }, etc.
+                for (const key of ["phases", "data", "events", "moon_phases", "results", "items"]) {
+                    const nested = val[key];
+                    if (Array.isArray(nested))
+                        return nested;
+                }
+            }
+            return null;
+        }
+        const allPhases = extractArray(result) ?? [];
         const matching = allPhases
             .filter((p) => {
             const name = (p.phase_name ?? p.name ?? p.phase ?? "").toLowerCase();

package/dist/tools/specialized/natal.js

@@ -2,7 +2,7 @@ import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 const DATETIME_DESC = "ISO 8601 datetime string, e.g. '1990-04-15T14:30:00' (local time at birth location). " +
     "Include timezone offset if known, e.g. '1990-04-15T14:30:00-05:00'.";
-/** Map human-readable house system names to Swiss Ephemeris single-letter codes */
+/** Map human-readable house system names to standard single-letter codes */
 const HOUSE_SYSTEM_MAP = {
     placidus: "P", whole_sign: "W", equal: "E", koch: "K",
     campanus: "C", regiomontanus: "R", porphyry: "O",

package/dist/tools/specialized/returns.js

@@ -127,9 +127,9 @@ registerTool({
         "Uranus returns (~84 years), etc.\n\n" +
         "CREDIT COST: 5 credits per call.\n\n" +
         "EXAMPLE: Saturn return for birth 1990-04-15 near year 2019:\n" +
-        "  body='saturn', birth_datetime='1990-04-15T14:30:00', target_datetime='2019-01-01'\n" +
+        "  body='saturn', birth_datetime='1990-04-15T14:30:00Z', target_datetime='2019-01-01T00:00:00Z'\n" +
         "EXAMPLE: Chiron return for birth 1975-03-10 near age 50:\n" +
-        "  body='chiron', birth_datetime='1975-03-10T08:00:00', target_datetime='2025-01-01'",
+        "  body='chiron', birth_datetime='1975-03-10T08:00:00Z', target_datetime='2025-01-01T00:00:00Z'",
     inputSchema: {
         type: "object",
         properties: {
@@ -145,16 +145,33 @@ registerTool({
                 type: "string",
                 description: "Date/time near which to find the return (ISO 8601). MUST include offset or Z. Required.",
             },
+            birth_latitude: {
+                type: "number",
+                description: "Birth latitude in decimal degrees. Required to get a full return chart (house cusps, angles).",
+            },
+            birth_longitude: {
+                type: "number",
+                description: "Birth longitude in decimal degrees. Required to get a full return chart (house cusps, angles).",
+            },
         },
         required: ["body", "birth_datetime", "target_datetime"],
         additionalProperties: false,
     },
     handler: async (args) => {
         validateRequired(args, ["body", "birth_datetime", "target_datetime"]);
-        return await getActiveClient().post("/predictive/returns", {
+        const requestBody = {
             body: args.body,
             birth_datetime: { iso: args.birth_datetime },
             target_datetime: { iso: args.target_datetime },
-        });
+        };
+        // Forward birth coordinates so the backend can compute the full return chart.
+        // Without these, computeReturnChartData sees {lat:0, lon:0} and returns nil.
+        if (args.birth_latitude != null && args.birth_longitude != null) {
+            requestBody.location = {
+                latitude: { decimal: args.birth_latitude },
+                longitude: { decimal: args.birth_longitude },
+            };
+        }
+        return await getActiveClient().post("/predictive/returns", requestBody);
     },
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openephemeris/mcp-server",
-  "version": "3.6.1",
+  "version": "3.9.0",
   "description": "Model Context Protocol server for the Open Ephemeris astronomical computation API",
   "type": "module",
   "main": "dist/index.js",
@@ -52,7 +52,7 @@
     "llm",
     "claude",
     "ai",
-    "swiss ephemeris"
+    "ephemeris"
   ],
   "author": "Open Ephemeris",
   "homepage": "https://openephemeris.com",