@openephemeris/mcp-server 4.19.0 → 4.20.0

package/CHANGELOG.md

@@ -7,6 +7,19 @@ Version numbering follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [4.20.0] — 2026-09-27
+
+### Added
+- **Six more tools can show their chart as an image.** Pass `include_visual: true` (+2 credits) to
+  `ephemeris_progressed_chart` (natal inside, progressed outside), `ephemeris_relocation` (the
+  relocated wheel), `ephemeris_composite` (the Davison relationship wheel), `ephemeris_overlay` (both
+  charts as a bi-wheel), `hd_planetary_return` and `hd_opposition` (the bodygraph for that moment).
+  The picture appears in the conversation next to the data.
+
+### Fixed
+- `ephemeris_composite` described itself as a planet-by-planet midpoint composite; it returns a
+  Davison relationship chart. For the midpoint method use `ephemeris_composite_midpoint`.
+
 ## [4.19.0] — 2026-09-27
 
 ### Changed

package/dist/tools/specialized/comparative.js

@@ -1,6 +1,7 @@
 import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
-import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
+import { OUTPUT_SCHEMA_IMAGE_AND_JSON, OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
+import { applyVisual, visualProperties } from "../visual.js";
 import { DATETIME_DESC, assertZonedDatetime, toDateTimeInputBody, timezoneProperty } from "../datetime.js";
 /** Reject a zone-less person datetime here, before a credit is spent on it. */
 function assertPersonZoned(prefix, args) {
@@ -23,8 +24,9 @@ function buildSubject(name, datetime, lat, lon, timezone) {
 // POST /comparative/composite
 registerTool({
     name: "ephemeris_composite",
-    description: "Calculate a composite chart from two or more natal charts. The composite " +
-        "uses midpoints of each planet pair to derive a single relationship chart.\n\n" +
+    description: "Calculate a Davison relationship chart for two people — a real chart cast for the " +
+        "midpoint in time and place between the two births, with its own houses and angles. " +
+        "For the planet-by-planet midpoint composite use ephemeris_composite_midpoint.\n\n" +
         "CREDIT COST: 3 credits per call.\n\n" +
         "EXAMPLE: Composite for two people:\n" +
         "  person_a_datetime='1990-04-15T14:30:00', person_a_timezone='America/Chicago',\n" +
@@ -43,6 +45,7 @@ registerTool({
             person_b_latitude: { type: "number", description: "Person B birth latitude." },
             person_b_longitude: { type: "number", description: "Person B birth longitude." },
             format: { type: "string", enum: ["json", "llm"], description: "Use 'llm' for token-efficient LLM projection." },
+            ...visualProperties("the relationship chart wheel"),
         },
         required: [
             "person_a_datetime", "person_a_latitude", "person_a_longitude",
@@ -50,7 +53,7 @@ registerTool({
         ],
         additionalProperties: false,
     },
-    outputSchema: OUTPUT_SCHEMA_JSON,
+    outputSchema: OUTPUT_SCHEMA_IMAGE_AND_JSON,
     annotations: { title: "Davison Relationship Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, [
@@ -62,15 +65,14 @@ registerTool({
         const query = {};
         if (args.format)
             query.format = args.format;
-        return await getActiveClient().request("POST", "/comparative/composite", {
-            params: query,
-            data: {
-                subjects: [
-                    buildSubject("Person A", args.person_a_datetime, args.person_a_latitude, args.person_a_longitude, args.person_a_timezone),
-                    buildSubject("Person B", args.person_b_datetime, args.person_b_latitude, args.person_b_longitude, args.person_b_timezone),
-                ],
-            }
-        });
+        const body = {
+            subjects: [
+                buildSubject("Person A", args.person_a_datetime, args.person_a_latitude, args.person_a_longitude, args.person_a_timezone),
+                buildSubject("Person B", args.person_b_datetime, args.person_b_latitude, args.person_b_longitude, args.person_b_timezone),
+            ],
+        };
+        applyVisual(body, args);
+        return await getActiveClient().request("POST", "/comparative/composite", { params: query, data: body });
     },
 });
 // POST /comparative/composite/midpoint
@@ -139,6 +141,7 @@ registerTool({
             person_b_latitude: { type: "number", description: "Person B birth latitude." },
             person_b_longitude: { type: "number", description: "Person B birth longitude." },
             format: { type: "string", enum: ["json", "llm"], description: "Use 'llm' for token-efficient LLM projection." },
+            ...visualProperties("a bi-wheel of the two charts"),
         },
         required: [
             "person_a_datetime", "person_a_latitude", "person_a_longitude",
@@ -146,7 +149,7 @@ registerTool({
         ],
         additionalProperties: false,
     },
-    outputSchema: OUTPUT_SCHEMA_JSON,
+    outputSchema: OUTPUT_SCHEMA_IMAGE_AND_JSON,
     annotations: { title: "Synastry House Overlay", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, [
@@ -158,15 +161,14 @@ registerTool({
         const query = {};
         if (args.format)
             query.format = args.format;
-        return await getActiveClient().request("POST", "/comparative/overlay", {
-            params: query,
-            data: {
-                subjects: [
-                    buildSubject("Person A", args.person_a_datetime, args.person_a_latitude, args.person_a_longitude, args.person_a_timezone),
-                    buildSubject("Person B", args.person_b_datetime, args.person_b_latitude, args.person_b_longitude, args.person_b_timezone),
-                ],
-            }
-        });
+        const body = {
+            subjects: [
+                buildSubject("Person A", args.person_a_datetime, args.person_a_latitude, args.person_a_longitude, args.person_a_timezone),
+                buildSubject("Person B", args.person_b_datetime, args.person_b_latitude, args.person_b_longitude, args.person_b_timezone),
+            ],
+        };
+        applyVisual(body, args);
+        return await getActiveClient().request("POST", "/comparative/overlay", { params: query, data: body });
     },
 });
 // POST /comparative/natal-transits

package/dist/tools/specialized/hd_cycles.js

@@ -1,6 +1,7 @@
 import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
-import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
+import { OUTPUT_SCHEMA_IMAGE_AND_JSON } from "../output-schemas.js";
+import { applyVisual, visualProperties } from "../visual.js";
 import { DATETIME_DESC, TIMEZONE_PROPERTY } from "../datetime.js";
 import { localToUtcIsoHistorical } from "../datetime-historical.js";
 /** Optional birth coordinates, present only to feed the historical timezone
@@ -53,24 +54,23 @@ registerTool({
                 enum: ["json", "llm"],
                 description: "Output format. 'llm' returns compact projection for token efficiency.",
             },
+            ...visualProperties("the bodygraph for that moment"),
         },
         required: ["planet", "datetime", "return_year"],
         additionalProperties: false,
     },
-    outputSchema: OUTPUT_SCHEMA_JSON,
+    outputSchema: OUTPUT_SCHEMA_IMAGE_AND_JSON,
     annotations: { title: "HD Planetary Return", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, ["planet", "datetime", "return_year"]);
-        return await getActiveClient().request("POST", "/human-design/cycles/return", {
-            data: {
-                planet: args.planet,
-                birth_datetime_utc: await localToUtcIsoHistorical("datetime", args.datetime, args.timezone, { latitude: args.latitude, longitude: args.longitude }),
-                return_year: args.return_year,
-                format: args.format,
-                include_chiron: args.include_chiron,
-                include_lilith: args.include_lilith,
-            },
-        });
+        const body = {
+            planet: args.planet,
+            birth_datetime_utc: await localToUtcIsoHistorical("datetime", args.datetime, args.timezone, { latitude: args.latitude, longitude: args.longitude }),
+            return_year: args.return_year,
+            format: args.format,
+        };
+        applyVisual(body, args);
+        return await getActiveClient().request("POST", "/human-design/cycles/return", { data: body });
     },
 });
 registerTool({
@@ -107,23 +107,22 @@ registerTool({
                 enum: ["json", "llm"],
                 description: "Output format. 'llm' returns compact projection for token efficiency.",
             },
+            ...visualProperties("the bodygraph for that moment"),
         },
         required: ["planet", "datetime", "target_year"],
         additionalProperties: false,
     },
-    outputSchema: OUTPUT_SCHEMA_JSON,
+    outputSchema: OUTPUT_SCHEMA_IMAGE_AND_JSON,
     annotations: { title: "HD Opposition Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, ["planet", "datetime", "target_year"]);
-        return await getActiveClient().request("POST", "/human-design/cycles/opposition", {
-            data: {
-                planet: args.planet,
-                birth_datetime_utc: await localToUtcIsoHistorical("datetime", args.datetime, args.timezone, { latitude: args.latitude, longitude: args.longitude }),
-                target_year: args.target_year,
-                format: args.format,
-                include_chiron: args.include_chiron,
-                include_lilith: args.include_lilith,
-            },
-        });
+        const body = {
+            planet: args.planet,
+            birth_datetime_utc: await localToUtcIsoHistorical("datetime", args.datetime, args.timezone, { latitude: args.latitude, longitude: args.longitude }),
+            target_year: args.target_year,
+            format: args.format,
+        };
+        applyVisual(body, args);
+        return await getActiveClient().request("POST", "/human-design/cycles/opposition", { data: body });
     },
 });

package/dist/tools/specialized/progressed.js

@@ -1,6 +1,7 @@
 import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
-import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
+import { OUTPUT_SCHEMA_IMAGE_AND_JSON } from "../output-schemas.js";
+import { applyVisual, visualProperties } from "../visual.js";
 import { DATETIME_DESC, TIMEZONE_PROPERTY, WINDOW_DATE_DESC, assertZonedDatetime } from "../datetime.js";
 registerTool({
     name: "ephemeris_progressed_chart",
@@ -44,11 +45,12 @@ registerTool({
                 type: "boolean",
                 description: "Whether to include aspect grid in the response. Default false.",
             },
+            ...visualProperties("a natal-inside, progressed-outside bi-wheel"),
         },
         required: ["birth_datetime", "birth_latitude", "birth_longitude", "target_datetime"],
         additionalProperties: false,
     },
-    outputSchema: OUTPUT_SCHEMA_JSON,
+    outputSchema: OUTPUT_SCHEMA_IMAGE_AND_JSON,
     annotations: { title: "Progressed Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, ["birth_datetime", "birth_latitude", "birth_longitude", "target_datetime"]);
@@ -76,6 +78,7 @@ registerTool({
         if (args.include_aspects != null) {
             body.options = { include_aspects: args.include_aspects };
         }
+        applyVisual(body, args);
         return await getActiveClient().post("/ephemeris/progressed", body);
     },
 });

package/dist/tools/specialized/relocation.js

@@ -1,6 +1,7 @@
 import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
-import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
+import { OUTPUT_SCHEMA_IMAGE_AND_JSON } from "../output-schemas.js";
+import { applyVisual, visualProperties } from "../visual.js";
 import { DATETIME_DESC, TIMEZONE_PROPERTY, assertZonedDatetime } from "../datetime.js";
 registerTool({
     name: "ephemeris_relocation",
@@ -45,11 +46,12 @@ registerTool({
                 enum: ["json", "llm"],
                 description: "Output format. 'llm' = compact token-efficient output (available on all tiers).",
             },
+            ...visualProperties("the relocated chart wheel"),
         },
         required: ["natal_datetime", "natal_latitude", "natal_longitude", "relocation_latitude", "relocation_longitude"],
         additionalProperties: false,
     },
-    outputSchema: OUTPUT_SCHEMA_JSON,
+    outputSchema: OUTPUT_SCHEMA_IMAGE_AND_JSON,
     annotations: { title: "Relocation Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     handler: async (args) => {
         validateRequired(args, ["natal_datetime", "natal_latitude", "natal_longitude", "relocation_latitude", "relocation_longitude"]);
@@ -72,6 +74,7 @@ registerTool({
         };
         if (args.house_system)
             body.house_system = args.house_system;
+        applyVisual(body, args);
         const query = {};
         if (args.format)
             query.format = args.format;

package/dist/tools/visual.d.ts

@@ -0,0 +1,15 @@
+/**
+ * include_visual for data tools whose endpoint can embed a rendered picture
+ * (+2 credits). formatToolResponse turns the returned `visual` into an image
+ * block next to the JSON. Kept to one terse flag: tool text is re-sent to the
+ * model on every pass (see tool-surface-budget.test.ts).
+ */
+/** Input-schema property; `what` names the picture, e.g. "the relocated wheel". */
+export declare function visualProperties(what: string): {
+    readonly include_visual: {
+        readonly type: "boolean";
+        readonly description: `Also return ${string} as an image (+2 credits).`;
+    };
+};
+/** Copies the visual request onto the API body. Always SVG: the MCP host rasterizes nothing. */
+export declare function applyVisual(body: Record<string, unknown>, args: any): void;

package/dist/tools/visual.js

@@ -0,0 +1,22 @@
+/**
+ * include_visual for data tools whose endpoint can embed a rendered picture
+ * (+2 credits). formatToolResponse turns the returned `visual` into an image
+ * block next to the JSON. Kept to one terse flag: tool text is re-sent to the
+ * model on every pass (see tool-surface-budget.test.ts).
+ */
+/** Input-schema property; `what` names the picture, e.g. "the relocated wheel". */
+export function visualProperties(what) {
+    return {
+        include_visual: {
+            type: "boolean",
+            description: `Also return ${what} as an image (+2 credits).`,
+        },
+    };
+}
+/** Copies the visual request onto the API body. Always SVG: the MCP host rasterizes nothing. */
+export function applyVisual(body, args) {
+    if (!args.include_visual)
+        return;
+    body.include_visual = true;
+    body.visual_config = { format: "svg", theme: "light", size: 800 };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openephemeris/mcp-server",
-  "version": "4.19.0",
+  "version": "4.20.0",
   "description": "MCP server for Open Ephemeris — NASA JPL DE440 astrology and astronomy, with interactive charts that render inline in Claude and ChatGPT",
   "type": "module",
   "main": "dist/index.js",