@openephemeris/mcp-server 4.18.0 → 4.20.0

package/dist/tools/apps/ui-resource.js

@@ -0,0 +1,66 @@
+/**
+ * ui-resource.ts — identity and `_meta` of the seven MCP App `ui://` resources.
+ *
+ * Imported by every `*-app.ts` (for its resource URI) and by ui-resources.ts
+ * (the list/read registry both transports serve). Kept free of app imports so
+ * the app modules can depend on it without a cycle.
+ */
+import { SERVER_VERSION } from "../index.js";
+export const UI_RESOURCE_MIME_TYPE = "text/html;profile=mcp-app";
+/**
+ * Versioned resource URI: `ui://openephemeris/<slug>?v=<server version>`.
+ *
+ * ChatGPT caches a `ui://` resource per connector and never re-reads it for a
+ * URI it has seen — a deploy alone does not refresh the widget. Stamping the
+ * package version into the URI makes every release a new URI, so hosts fetch
+ * the new bundle on their own. Caveat: a widget change must ship with a
+ * version bump to bust the cache (same version ⇒ same URI).
+ *
+ * The SAME string is used in the tool `_meta` (ui.resourceUri and its aliases),
+ * in resources/list and in resources/read, on both transports.
+ */
+export function uiResourceUri(slug) {
+    return `ui://openephemeris/${slug}?v=${SERVER_VERSION}`;
+}
+/** The URI without its `?v=` query — what resources/read matches on. */
+export function uiResourceBase(uri) {
+    const q = uri.indexOf("?");
+    return q === -1 ? uri : uri.slice(0, q);
+}
+/**
+ * CSP the bundles actually need: none. Every bundle is a single self-contained
+ * HTML file (JS/CSS inlined, images and icons as data: URIs), and the apps talk
+ * to the host over postMessage only — no fetch, no remote script, style, image
+ * or font. Empty lists are the spec's secure default; declaring them explicitly
+ * documents that this is deliberate, not forgotten.
+ */
+export const UI_RESOURCE_CSP = {
+    connectDomains: [],
+    resourceDomains: [],
+};
+/**
+ * `_meta` for a `ui://` resource (resources/list entry and resources/read
+ * content item). Two wire forms, same values:
+ *
+ *   ui.*       — MCP Apps (SEP-1865) McpUiResourceMeta.
+ *   openai/*   — ChatGPT's aliases for the same fields.
+ *
+ * prefersBorder: true — the host draws the card border and background; the apps
+ * therefore paint no card, border or glow of their own (shared/tokens.css).
+ *
+ * ui.domain / openai/widgetDomain are deliberately NOT set: their format is
+ * host-specific (a hash subdomain on Claude, a derived *.oaiusercontent.com on
+ * ChatGPT) and a wrong value can stop the widget rendering. Omitted = the
+ * host's default sandbox origin, which is what every live render uses today.
+ */
+export function uiResourceMeta(widgetDescription) {
+    return {
+        ui: {
+            prefersBorder: true,
+            csp: UI_RESOURCE_CSP,
+        },
+        "openai/widgetPrefersBorder": true,
+        "openai/widgetCSP": { connect_domains: [], resource_domains: [] },
+        "openai/widgetDescription": widgetDescription,
+    };
+}

package/dist/tools/apps/ui-resources.d.ts

@@ -0,0 +1,22 @@
+export interface UiResourceEntry {
+    uri: string;
+    /** Short name used in the "bundle not found" error. */
+    label: string;
+    name: string;
+    description: string;
+    /** Tells the model what the widget already shows (ChatGPT openai/widgetDescription). */
+    widgetDescription: string;
+    getBundle: () => string | null;
+}
+export declare const UI_RESOURCES: UiResourceEntry[];
+/** resources/list — only bundles that are actually built. */
+export declare function listUiResources(): Array<Record<string, unknown>>;
+/**
+ * resources/read. Matches on the URI WITHOUT its `?v=` so a host holding an
+ * older (or unversioned) URI from a cached tools/list still gets the current
+ * bundle; the content item echoes the URI that was asked for. Returns null for
+ * a URI that is not one of ours.
+ */
+export declare function readUiResource(uri: string): {
+    contents: Array<Record<string, unknown>>;
+} | null;

package/dist/tools/apps/ui-resources.js

@@ -0,0 +1,105 @@
+/**
+ * ui-resources.ts — the resources/list + resources/read registry for the seven
+ * MCP App bundles, shared by BOTH transports (src/index.ts stdio and
+ * src/server-sse.ts HTTP). They used to carry copy-paste twins of the same
+ * seven if-blocks; one table keeps URI, name, description and `_meta` in step.
+ */
+import { UI_RESOURCE_MIME_TYPE, uiResourceBase, uiResourceMeta } from "./ui-resource.js";
+import { CHART_WHEEL_RESOURCE_URI, getChartWheelBundle } from "./chart-wheel-app.js";
+import { BODYGRAPH_RESOURCE_URI, getBodygraphBundle } from "./bodygraph-app.js";
+import { BI_WHEEL_RESOURCE_URI, getBiWheelBundle } from "./bi-wheel-app.js";
+import { MOON_PHASE_RESOURCE_URI, getMoonPhaseBundle } from "./moon-phase-app.js";
+import { TRANSIT_TIMELINE_RESOURCE_URI, getTransitTimelineBundle } from "./transit-timeline-app.js";
+import { VEDIC_CHART_RESOURCE_URI, getVedicChartBundle } from "./vedic-chart-app.js";
+import { BAZI_RESOURCE_URI, getBaziBundle } from "./bazi-app.js";
+export const UI_RESOURCES = [
+    {
+        uri: CHART_WHEEL_RESOURCE_URI,
+        label: "Chart Wheel",
+        name: "Chart Wheel Explorer",
+        description: "Interactive natal chart wheel with clickable planets, houses, and aspects.",
+        widgetDescription: "Shows the full natal chart wheel — every planet, house cusp and aspect line — and lets the user click any of them for a reading. Don't repeat the placements as a list; highlight what stands out and invite them to explore the wheel.",
+        getBundle: getChartWheelBundle,
+    },
+    {
+        uri: BODYGRAPH_RESOURCE_URI,
+        label: "Bodygraph",
+        name: "Human Design Bodygraph Explorer",
+        description: "Interactive Human Design Bodygraph with clickable centers, gates, and channels.",
+        widgetDescription: "Shows the Human Design bodygraph with type, profile and authority, and lets the user click centers, channels and gates for their meaning. Don't redraw or list the whole chart; interpret the key points and point them to the graph.",
+        getBundle: getBodygraphBundle,
+    },
+    {
+        uri: BI_WHEEL_RESOURCE_URI,
+        label: "Bi-Wheel",
+        name: "Bi-Wheel Explorer",
+        description: "Interactive synastry or transit bi-wheel with cross-aspect lines and clickable planets.",
+        widgetDescription: "Shows two charts as a bi-wheel (natal inside, transits or a second person outside) with the cross-aspects drawn, each clickable. Don't list every cross-aspect; summarize the strongest contacts.",
+        getBundle: getBiWheelBundle,
+    },
+    {
+        uri: MOON_PHASE_RESOURCE_URI,
+        label: "Moon Phase",
+        name: "Moon Phase Explorer",
+        description: "Interactive lunar phase dial showing illumination, sign, and void-of-course status.",
+        widgetDescription: "Shows the current moon: phase, illumination, sign, void-of-course status, speed and the next new and full moon. Don't restate those numbers; add meaning or answer the user's question.",
+        getBundle: getMoonPhaseBundle,
+    },
+    {
+        uri: TRANSIT_TIMELINE_RESOURCE_URI,
+        label: "Transit Timeline",
+        name: "Transit Timeline Explorer",
+        description: "Interactive vertical timeline of upcoming transit hits grouped by month, with clickable events.",
+        widgetDescription: "Shows a dated timeline of upcoming transits to the natal chart, grouped by month, each clickable. Don't re-list the dates; call out the few that matter most.",
+        getBundle: getTransitTimelineBundle,
+    },
+    {
+        uri: VEDIC_CHART_RESOURCE_URI,
+        label: "Vedic Chart",
+        name: "Vedic Chart Explorer",
+        description: "Interactive Vedic (Jyotish) South Indian Rashi grid with clickable sign placements.",
+        widgetDescription: "Shows the sidereal South Indian Rashi chart with every graha in its sign, each clickable. Don't re-list placements; interpret the notable ones.",
+        getBundle: getVedicChartBundle,
+    },
+    {
+        uri: BAZI_RESOURCE_URI,
+        label: "BaZi",
+        name: "BaZi Four Pillars Explorer",
+        description: "Interactive BaZi (Four Pillars of Destiny) chart with clickable Year/Month/Day/Hour pillars.",
+        widgetDescription: "Shows the Four Pillars (year, month, day, hour stems and branches) with the Day Master, each pillar clickable. Don't re-list the pillars; interpret the balance.",
+        getBundle: getBaziBundle,
+    },
+];
+/** resources/list — only bundles that are actually built. */
+export function listUiResources() {
+    return UI_RESOURCES.filter((r) => r.getBundle()).map((r) => ({
+        uri: r.uri,
+        name: r.name,
+        description: r.description,
+        mimeType: UI_RESOURCE_MIME_TYPE,
+        _meta: uiResourceMeta(r.widgetDescription),
+    }));
+}
+/**
+ * resources/read. Matches on the URI WITHOUT its `?v=` so a host holding an
+ * older (or unversioned) URI from a cached tools/list still gets the current
+ * bundle; the content item echoes the URI that was asked for. Returns null for
+ * a URI that is not one of ours.
+ */
+export function readUiResource(uri) {
+    const base = uiResourceBase(uri);
+    const entry = UI_RESOURCES.find((r) => uiResourceBase(r.uri) === base);
+    if (!entry)
+        return null;
+    const bundle = entry.getBundle();
+    if (!bundle)
+        throw new Error(`${entry.label} UI bundle not found. Run \`npm run build:ui\` to build it.`);
+    return {
+        contents: [{
+                uri,
+                mimeType: UI_RESOURCE_MIME_TYPE,
+                text: bundle,
+                _meta: uiResourceMeta(entry.widgetDescription),
+            }],
+    };
+}

package/dist/tools/apps/vedic-chart-app.d.ts

@@ -17,7 +17,7 @@
  * Also exports resource helpers (getVedicChartBundle, etc.) for use in
  * index.ts and server-sse.ts.
  */
-export declare const VEDIC_CHART_RESOURCE_URI = "ui://openephemeris/vedic-chart";
+export declare const VEDIC_CHART_RESOURCE_URI: string;
 export declare const VEDIC_CHART_MIME_TYPE = "text/html;profile=mcp-app";
 /** Read the pre-built HTML bundle. Returns null if not yet built. */
 export declare function getVedicChartBundle(): string | null;

package/dist/tools/apps/vedic-chart-app.js

@@ -21,14 +21,15 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { registerTool, validateRequired, validateCoordinates, SERVER_VERSION } from "../index.js";
+import { UI_RESOURCE_MIME_TYPE, uiResourceUri } from "./ui-resource.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
 import { localToUtcIsoHistorical } from "../datetime-historical.js";
 import { coordsFromArgsOrLocation } from "./_location-resolver.js";
 import { RENDER_TOKEN_PROPERTY, renderTokenFromVisual, renderTokenHeaders } from "./_render-token.js";
 // ── Constants ─────────────────────────────────────────────────────────────────
-export const VEDIC_CHART_RESOURCE_URI = "ui://openephemeris/vedic-chart";
-export const VEDIC_CHART_MIME_TYPE = "text/html;profile=mcp-app";
+export const VEDIC_CHART_RESOURCE_URI = uiResourceUri("vedic-chart");
+export const VEDIC_CHART_MIME_TYPE = UI_RESOURCE_MIME_TYPE;
 const here = path.dirname(fileURLToPath(import.meta.url));
 const BUNDLE_PATHS = [
     path.resolve(here, "..", "..", "..", "dist", "ui", "vedic-chart.html"),

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 };
+}