@openephemeris/mcp-server 3.9.2 → 3.10.0

package/CHANGELOG.md

@@ -7,8 +7,41 @@ Version numbering follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [3.10.0] — 2026-04-23
+
+### Added
+- **Native visual rendering (Tier 1 MCP App)** — `ephemeris_natal_chart`, `ephemeris_synastry`,
+  `human_design_chart`, `ephemeris_progressed_chart`, and `ephemeris_solar_return` now accept
+  `include_visual: true` to embed a live chart image directly in the conversation alongside
+  the JSON data. A single tool call returns both interpretation data and a rendered chart.
+- **`visual_config` parameter** — optional `{ theme, size }` object on all visual-capable data
+  tools. Astrology charts default to `theme: "light"`, HD bodygraphs default to `theme: "dark"`
+  (per HD convention). Size range 200–4000 px, default 800.
+- **Dual-content response handler** — `formatToolResponse` in `tools/index.ts` now intercepts
+  embedded `VisualResult` objects: base64-encodes raw SVG strings on the fly, emits an MCP image
+  block (`{ type: "image" }`) first, then a clean JSON text block with the `visual` key stripped.
+  PNG payloads (already base64 from the sidecar) are passed through without double-encoding.
+- **`test/visual-rendering.test.ts`** — 26 new unit tests covering the full visual pipeline:
+  SVG encoding, PNG passthrough, dual-block output, key stripping, standalone binary passthrough,
+  plain JSON fallthrough, and defensive handling of incomplete `visual` keys.
+
+### Changed
+- `ephemeris_chart_wheel`, `ephemeris_bi_wheel`, and `human_design_bodygraph` (standalone
+  visualization tools) now **default to SVG** instead of PNG. This eliminates the `resvg` binary
+  dependency that caused runtime environment mismatches in Docker/Fly deployments. PNG remains
+  available as an explicit opt-in via `format: "png"`.
+- Tool descriptions for standalone visual tools updated to reflect SVG-first rendering.
+
+### Fixed
+- Chart render failures caused by `resvg` binary not being available in the Node.js MCP
+  server runtime environment. SVG is now rendered natively by the Go sidecar with no external
+  binary dependencies.
+
+---
+
 ## [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

package/README.md

@@ -4,7 +4,7 @@
 [![npm version](https://img.shields.io/npm/v/@openephemeris/mcp-server)](https://www.npmjs.com/package/@openephemeris/mcp-server)
 [![System Status](https://img.shields.io/badge/Status-Operational-brightgreen)](https://status.openephemeris.com/)
 
-Model Context Protocol server for OpenEphemeris — 50+ typed astrology tools powered by NASA JPL DE440/DE441 ephemerides. Zero hallucination on planetary positions, dates, and degrees.
+Model Context Protocol server for OpenEphemeris — 52 typed astrology tools powered by the NASA JPL DE440 ephemeris. Zero hallucination on planetary positions, dates, and degrees. Covers 1,100 years of astronomical data.
 
 **Hosted endpoint:** `https://mcp.openephemeris.com/mcp` (Streamable HTTP, MCP 2025-11-25 spec)
 
@@ -343,7 +343,8 @@ When you update the MCP server logic (handlers, bug fixes, hardening), you shoul
               ┌────────────────────────┐
               │  OpenEphemeris API     │
               │  api.openephemeris.com │
-              │  JPL DE440/DE441       │
+              │  NASA JPL DE440        │
+              │  1,100 years of data   │
               └────────────────────────┘
 ```
 
@@ -375,6 +376,6 @@ Generated by `npm run sync:readme` from `config/dev-allowlist.json` and the live
 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.
+- **Zero-hallucination coordinates**: Direct, sub-arcsecond NASA JPL DE440 calculations spanning 1,100 years of astronomical data.
 - **LLM-optimized tokens (`format=llm`)**: We compress standard 25,000 token JSON chart responses into minimal text blocks, cutting your inference costs by 50%.
 - **Ready-to-use astrology layers**: Built-in support for Astrocartography geoJSON lines, Hermetic Lots, Fixed Stars, and complex Human Design matrix generation.

package/dist/index.js

@@ -75,7 +75,7 @@ server.setRequestHandler(GetPromptRequestSchema, async (request) => {
                 content: {
                     type: "text",
                     text: "Welcome to the **Open Ephemeris MCP Server**!\n\n" +
-                        "You are now connected to an enterprise-grade astrological and astronomical computation engine powered by NASA JPL DE440 and DE441 ephemeris data. As a generative guide, here is how you can best utilize these tools to help the user:\n\n" +
+                        "You are now connected to an enterprise-grade astrological and astronomical computation engine powered by NASA JPL DE440 ephemeris data (1550–2650 CE). As a generative guide, here is how you can best utilize these tools to help the user:\n\n" +
                         "### Core Capabilities\n" +
                         "- **Birth Charts:** Use `ephemeris_natal_chart` for full planetary positions, houses, dignities, and aspects.\n" +
                         "- **Predictive Timing:** `ephemeris_transits` searches for exact dates when transiting planets hit natal points.\n" +

package/dist/server-sse.js

@@ -154,7 +154,7 @@ const WELCOME_PROMPT_CONTENT = [
                 "• **Chart Wheels** — visual PNG/SVG wheels and bi-wheels\n" +
                 "• **Time Lords** — Firdaria, Profections, Zodiacal Releasing\n\n" +
                 "**Tips:** Use `format=\"llm\"` on any tool to get ~50% smaller, token-optimized output. " +
-                "All computations are sub-arcsecond precision using JPL DE440/DE441 ephemerides.\n\n" +
+                "All computations are sub-arcsecond precision using JPL DE440 ephemerides.\n\n" +
                 "Just tell me what you'd like to explore!",
         },
     },
@@ -177,17 +177,17 @@ function createMcpServer() {
         // description is in the MCP spec (spec.types.d.ts Implementation interface)
         // but the SDK's Zod schema doesn't include it yet — pass via spread
         ...{
-            description: "NASA JPL-backed astronomical computation engine for AI agents. " +
-                "50+ typed tools covering natal charts, transit forecasting, Human Design " +
+            description: "NASA JPL DE440-backed astronomical computation engine for AI agents. " +
+                "52+ typed tools covering natal charts, transit forecasting, Human Design " +
                 "bodygraphs, eclipses, astrocartography power lines, Venus Star Points, " +
                 "electional timing, synastry, composite charts, Vedic/Jyotish, Chinese BaZi, " +
-                "and more — powered by JPL DE440/DE441 ephemerides for sub-arcsecond accuracy.",
+                "and more — powered by JPL DE440 ephemerides for sub-arcsecond accuracy.",
         },
     }, {
         capabilities: { tools: {}, prompts: {} },
         instructions: "Open Ephemeris is a precision astronomical computation engine. " +
             "Use format='llm' on any tool for compact, token-efficient output. " +
-            "All computations use JPL DE440/DE441 ephemerides for sub-arcsecond accuracy. " +
+            "All computations use JPL DE440 ephemerides for sub-arcsecond accuracy. " +
             "See the 'welcome_to_open_ephemeris' prompt for a full capability overview.",
     });
     // --- Tool handlers ---
@@ -290,10 +290,10 @@ async function main() {
             serverInfo: {
                 name: "Open Ephemeris",
                 version,
-                description: "NASA JPL-backed astronomical computation engine for AI agents. 50+ typed tools covering " +
+                description: "NASA JPL DE440-backed astronomical computation engine for AI agents. 52+ typed tools covering " +
                     "natal charts, transit forecasting, Human Design bodygraphs, eclipses, astrocartography " +
                     "power lines, Venus Star Points, electional timing, synastry, composite charts, Vedic/Jyotish, " +
-                    "Chinese BaZi, and more — powered by JPL DE440/DE441 ephemerides for sub-arcsecond " +
+                    "Chinese BaZi, and more — powered by JPL DE440 ephemerides for sub-arcsecond " +
                     "zero-hallucination accuracy. Free Explorer tier available.",
                 iconUrl: "https://mcp.openephemeris.com/icon.png",
                 homepage: "https://openephemeris.com",

package/dist/tools/index.d.ts

@@ -34,25 +34,26 @@ export declare function validateCoordinates(args: any, latKey: string, lonKey: s
 /**
  * Formats a raw tool response into native MCP content blocks.
  * Intercepts binary image responses (like Chart Wheels) and returns them as native MCP Images.
+ * Intercepts embedded VisualResult objects (include_visual=true) and returns dual content.
  * Applies a safety limit to JSON payloads to prevent crashing LLM contexts.
  */
 export declare function formatToolResponse(toolName: string, result: any, durationMs: number): {
-    content: {
+    content: ({
         type: string;
         data: string;
         mimeType: string;
-    }[];
-    isError?: undefined;
-} | {
-    content: {
+        text?: undefined;
+    } | {
         type: string;
         text: string;
-    }[];
-    isError: boolean;
+        data?: undefined;
+        mimeType?: undefined;
+    })[];
+    isError?: undefined;
 } | {
     content: {
         type: string;
         text: string;
     }[];
-    isError?: undefined;
+    isError: boolean;
 };

package/dist/tools/index.js

@@ -71,10 +71,43 @@ export function validateCoordinates(args, latKey, lonKey) {
 /**
  * Formats a raw tool response into native MCP content blocks.
  * Intercepts binary image responses (like Chart Wheels) and returns them as native MCP Images.
+ * Intercepts embedded VisualResult objects (include_visual=true) and returns dual content.
  * Applies a safety limit to JSON payloads to prevent crashing LLM contexts.
  */
 export function formatToolResponse(toolName, result, durationMs) {
-    // Intercept binary backend responses (like Chart Wheels) to return native MCP Images
+    // Case: data response with embedded visual (include_visual=true)
+    // VisualResult.data for SVG is a raw string; for PNG it is already base64.
+    if (result &&
+        typeof result === "object" &&
+        result.visual &&
+        typeof result.visual === "object" &&
+        result.visual.data &&
+        result.visual.content_type) {
+        const visual = result.visual;
+        const isSvg = visual.content_type === "image/svg+xml";
+        // SVG data comes back as a raw string — must base64-encode for MCP image block.
+        const imageData = isSvg
+            ? Buffer.from(visual.data, "utf8").toString("base64")
+            : visual.data; // PNG is already base64
+        // Strip the visual key from the data payload so the text block is clean.
+        const { visual: _omit, ...dataWithoutVisual } = result;
+        const jsonStr = JSON.stringify(dataWithoutVisual, null, 2);
+        console.error(`[MCP] 🎨 Returning embedded visual (${visual.content_type}) for ${toolName} (${durationMs}ms)`);
+        return {
+            content: [
+                {
+                    type: "image",
+                    data: imageData,
+                    mimeType: visual.content_type,
+                },
+                {
+                    type: "text",
+                    text: jsonStr,
+                },
+            ],
+        };
+    }
+    // Case: standalone binary backend responses (like direct Chart Wheel tool calls)
     if (result &&
         typeof result === "object" &&
         "encoding" in result &&

package/dist/tools/specialized/bi_wheel.js

@@ -9,7 +9,7 @@ const HOUSE_SYSTEM_MAP = {
 };
 registerTool({
     name: "ephemeris_bi_wheel",
-    description: "Generate a Bi-Wheel (Synastry/Transit) image (PNG) comparing two charts. Draws Subject A's planets on the inside wheel and Subject B's on the outside wheel. The tool returns a raw image (base64) which most Vision-enabled AI agents can display.\n\n" +
+    description: "Generate a Bi-Wheel (Synastry/Transit) image (SVG) comparing two charts. Draws Subject A's planets on the inside wheel and Subject B's on the outside wheel. Returns a native SVG that Claude displays inline in the conversation.\n\n" +
         "CREDIT COST: 2 credits per call.\n\n" +
         "EXAMPLE: Compare someone born April 15, 1990 (A) to someone born June 10, 1992 (B):\n" +
         "  datetime_a='...', latitude_a=..., longitude_a=..., datetime_b='...', latitude_b=..., longitude_b=...",
@@ -69,6 +69,6 @@ registerTool({
             body.configuration = { house_system: mappedCode };
         }
         const styleParam = args.style ? `&style=${args.style}` : "";
-        return await getActiveClient().post(`/visualization/bi-wheel?format=png&size=800${styleParam}`, body);
+        return await getActiveClient().post(`/visualization/bi-wheel?format=svg&size=800${styleParam}`, body);
     },
 });

package/dist/tools/specialized/chart_wheel.js

@@ -9,7 +9,7 @@ const HOUSE_SYSTEM_MAP = {
 };
 registerTool({
     name: "ephemeris_chart_wheel",
-    description: "Generate a classic astrological Chart Wheel image (PNG) for a person/event. This draws a standard circular chart wheel with planets, aspects, and house cusps. The tool returns a raw image (base64) which most Vision-enabled AI agents (GPT-4o, Claude 3.5 Sonnet) can display and visually read.\n\n" +
+    description: "Generate a classic astrological Chart Wheel image (SVG) for a person/event. This draws a standard circular chart wheel with planets, aspects, and house cusps. The tool returns a native SVG image that Claude displays inline in the conversation — no external tools needed.\n\n" +
         "CREDIT COST: 2 credits per call.\n\n" +
         "EXAMPLE: Generate a natal chart wheel for someone born April 15, 1990 in Chicago:\n" +
         "  datetime='1990-04-15T14:30:00', latitude=41.8781, longitude=-87.6298",
@@ -66,6 +66,6 @@ registerTool({
             body.configuration = { house_system: mappedCode };
         }
         const styleParam = args.style ? `&style=${args.style}` : "";
-        return await getActiveClient().post(`/visualization/chart-wheel?format=png&size=800${styleParam}`, body);
+        return await getActiveClient().post(`/visualization/chart-wheel?format=svg&size=800${styleParam}`, body);
     },
 });

package/dist/tools/specialized/hd_bodygraph.js

@@ -8,11 +8,11 @@ function ensureTimezone(dt) {
 }
 registerTool({
     name: "human_design_bodygraph",
-    description: "Generate a Human Design Bodygraph image (PNG or SVG) from a birth datetime (UTC). " +
+    description: "Generate a Human Design Bodygraph image (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" +
+        "Returns a native SVG that Claude displays inline. Use format='png' to opt into raster output (requires server-side rasterizer).\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'",
@@ -32,8 +32,8 @@ registerTool({
             },
             format: {
                 type: "string",
-                enum: ["png", "svg"],
-                description: "Output format. Defaults to 'png'.",
+                enum: ["svg", "png"],
+                description: "Output format. Defaults to 'svg' (pure Go renderer — no external deps, displays natively in Claude). Use 'png' for raster output (requires server-side rasterizer).",
             },
         },
         required: ["datetime"],
@@ -44,7 +44,7 @@ registerTool({
         const body = {
             birth_datetime_utc: ensureTimezone(args.datetime),
         };
-        const format = args.format || "png";
+        const format = args.format || "svg";
         const styleParam = args.style ? `&style=${args.style}` : "";
         return await getActiveClient().post(`/visualization/bodygraph?format=${format}&size=800${styleParam}`, body);
     },

package/dist/tools/specialized/human_design.js

@@ -45,6 +45,21 @@ registerTool({
                 description: "Output format. 'llm' returns compact array projection for token efficiency (available on all tiers). " +
                     "'json' returns verbose full output.",
             },
+            include_visual: {
+                type: "boolean",
+                description: "When true, renders the Human Design bodygraph as an SVG and embeds it in the response. " +
+                    "The bodygraph image will display in the conversation alongside the data. " +
+                    "Costs 2 additional credits on top of the base call cost.",
+            },
+            visual_config: {
+                type: "object",
+                description: "Optional rendering preferences (only used when include_visual=true).",
+                properties: {
+                    theme: { type: "string", enum: ["light", "dark"], description: "Color theme. Default: dark (HD convention)." },
+                    size: { type: "number", description: "Canvas size in pixels, 200–4000. Default: 800." },
+                },
+                additionalProperties: false,
+            },
         },
         required: ["datetime"],
         additionalProperties: false,
@@ -61,6 +76,14 @@ registerTool({
         const query = {};
         if (args.format)
             query.format = args.format;
+        if (args.include_visual) {
+            body.include_visual = true;
+            body.visual_config = {
+                format: "svg",
+                theme: args.visual_config?.theme || "dark", // HD convention defaults to dark
+                size: args.visual_config?.size || 800,
+            };
+        }
         return await getActiveClient().request("POST", "/human-design/chart", {
             data: body,
             params: query,

package/dist/tools/specialized/natal.js

@@ -54,6 +54,21 @@ registerTool({
                 type: "boolean",
                 description: "Reserved for future use. Fixed star positions are currently available via the dedicated /ephemeris/fixed-stars endpoint.",
             },
+            include_visual: {
+                type: "boolean",
+                description: "When true, renders the natal chart wheel as an SVG and embeds it directly in the response. " +
+                    "The chart image will display in the conversation alongside the data. " +
+                    "Costs 2 additional credits on top of the base call cost.",
+            },
+            visual_config: {
+                type: "object",
+                description: "Optional rendering preferences (only used when include_visual=true).",
+                properties: {
+                    theme: { type: "string", enum: ["light", "dark"], description: "Color theme. Default: light." },
+                    size: { type: "number", description: "Canvas size in pixels, 200–4000. Default: 800." },
+                },
+                additionalProperties: false,
+            },
         },
         required: ["datetime", "latitude", "longitude"],
         additionalProperties: false,
@@ -91,6 +106,14 @@ registerTool({
         const query = {};
         if (args.format)
             query.format = args.format;
+        if (args.include_visual) {
+            body.include_visual = true;
+            body.visual_config = {
+                format: "svg", // always SVG for MCP — no resvg dependency
+                theme: args.visual_config?.theme || "light",
+                size: args.visual_config?.size || 800,
+            };
+        }
         return await getActiveClient().request("POST", "/ephemeris/natal-chart", {
             data: body,
             params: query,

package/dist/tools/specialized/progressed.js

@@ -37,6 +37,21 @@ registerTool({
                 type: "boolean",
                 description: "Whether to include aspect grid in the response. Default false.",
             },
+            include_visual: {
+                type: "boolean",
+                description: "When true, renders the progressed chart wheel as an SVG and embeds it in the response. " +
+                    "The chart image will display in the conversation alongside the data. " +
+                    "Costs 2 additional credits on top of the base call cost.",
+            },
+            visual_config: {
+                type: "object",
+                description: "Optional rendering preferences (only used when include_visual=true).",
+                properties: {
+                    theme: { type: "string", enum: ["light", "dark"], description: "Color theme. Default: light." },
+                    size: { type: "number", description: "Canvas size in pixels, 200–4000. Default: 800." },
+                },
+                additionalProperties: false,
+            },
         },
         required: ["birth_datetime", "birth_latitude", "birth_longitude", "target_datetime"],
         additionalProperties: false,
@@ -60,6 +75,14 @@ registerTool({
         if (args.include_aspects != null) {
             body.options = { include_aspects: args.include_aspects };
         }
+        if (args.include_visual) {
+            body.include_visual = true;
+            body.visual_config = {
+                format: "svg",
+                theme: args.visual_config?.theme || "light",
+                size: args.visual_config?.size || 800,
+            };
+        }
         return await getActiveClient().post("/ephemeris/progressed", body);
     },
 });

package/dist/tools/specialized/returns.js

@@ -40,6 +40,21 @@ registerTool({
                 type: "number",
                 description: "Location longitude for the return chart (optional).",
             },
+            include_visual: {
+                type: "boolean",
+                description: "When true, renders the solar return chart wheel as an SVG and embeds it in the response. " +
+                    "The chart image will display in the conversation alongside the data. " +
+                    "Costs 2 additional credits on top of the base call cost.",
+            },
+            visual_config: {
+                type: "object",
+                description: "Optional rendering preferences (only used when include_visual=true).",
+                properties: {
+                    theme: { type: "string", enum: ["light", "dark"], description: "Color theme. Default: light." },
+                    size: { type: "number", description: "Canvas size in pixels, 200–4000. Default: 800." },
+                },
+                additionalProperties: false,
+            },
         },
         required: ["birth_datetime"],
         additionalProperties: false,
@@ -64,6 +79,14 @@ registerTool({
                 longitude: { decimal: args.return_longitude },
             };
         }
+        if (args.include_visual) {
+            body.include_visual = true;
+            body.visual_config = {
+                format: "svg",
+                theme: args.visual_config?.theme || "light",
+                size: args.visual_config?.size || 800,
+            };
+        }
         return await getActiveClient().post("/predictive/returns/solar", body);
     },
 });

package/dist/tools/specialized/synastry.js

@@ -28,6 +28,21 @@ registerTool({
                 enum: ["json", "llm"],
                 description: "Output format. 'llm' is compact and token-efficient (available on all tiers).",
             },
+            include_visual: {
+                type: "boolean",
+                description: "When true, renders a bi-wheel SVG comparing both charts and embeds it in the response. " +
+                    "The chart image will display in the conversation alongside the data. " +
+                    "Costs 2 additional credits on top of the base call cost.",
+            },
+            visual_config: {
+                type: "object",
+                description: "Optional rendering preferences (only used when include_visual=true).",
+                properties: {
+                    theme: { type: "string", enum: ["light", "dark"], description: "Color theme. Default: light." },
+                    size: { type: "number", description: "Canvas size in pixels, 200–4000. Default: 800." },
+                },
+                additionalProperties: false,
+            },
         },
         required: [
             "person_a_datetime", "person_a_latitude", "person_a_longitude",
@@ -63,6 +78,14 @@ registerTool({
         const query = {};
         if (args.format)
             query.format = args.format;
+        if (args.include_visual) {
+            body.include_visual = true;
+            body.visual_config = {
+                format: "svg",
+                theme: args.visual_config?.theme || "light",
+                size: args.visual_config?.size || 800,
+            };
+        }
         return await getActiveClient().request("POST", "/comparative/synastry", {
             data: body,
             params: query,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openephemeris/mcp-server",
-  "version": "3.9.2",
+  "version": "3.10.0",
   "description": "Model Context Protocol server for the Open Ephemeris astronomical computation API",
   "type": "module",
   "main": "dist/index.js",
@@ -65,7 +65,8 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.24.3",
+    "@modelcontextprotocol/ext-apps": "^1.7.0",
+    "@modelcontextprotocol/sdk": "1.29.0",
     "axios": "1.13.2",
     "express": "5.1.0",
     "zod": "4.1.13"
@@ -73,8 +74,11 @@
   "devDependencies": {
     "@types/express": "5.0.3",
     "@types/node": "25.0.1",
+    "cross-env": "^10.1.0",
     "tsx": "4.21.0",
     "typescript": "5.9.3",
+    "vite": "^8.0.10",
+    "vite-plugin-singlefile": "^2.3.3",
     "vitest": "4.0.15"
   },
   "packageManager": "pnpm@10.27.0+sha512.72d699da16b1179c14ba9e64dc71c9a40988cbdc65c264cb0e489db7de917f20dcf4d64d8723625f2969ba52d4b7e2a1170682d9ac2a5dcaeaab732b7e16f04a"