@openephemeris/mcp-server 3.6.1 → 3.8.0

package/CHANGELOG.md

@@ -7,6 +7,20 @@ Version numbering follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [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

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,7 +239,7 @@ 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?

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-22T01:16:37.771Z",
+  "openapi_sha256": "c649b6a9ba32e1576f9f12d2d78f1706d5bc279d7733a29f1e69a8ca042024d6",
   "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/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 Ela Map for geographic rendering.",
+                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/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.8.0",
   "description": "Model Context Protocol server for the Open Ephemeris astronomical computation API",
   "type": "module",
   "main": "dist/index.js",