@openephemeris/mcp-server 3.13.9 → 3.14.0

package/dist/tools/output-schemas.d.ts

@@ -0,0 +1,37 @@
+/**
+ * output-schemas.ts — Shared JSON Schema output schema definitions for MCP tools.
+ *
+ * MCP spec 2025-11-25 supports `outputSchema` on tool definitions. Smithery
+ * uses this field to score the "Output schemas" quality criterion (10.37pt / 57 tools).
+ *
+ * All tools return an MCP content block response. Most return a single JSON text
+ * block; visual tools return an image block or an image + text block.
+ *
+ * Usage:
+ *   import { OUTPUT_SCHEMA_JSON, OUTPUT_SCHEMA_IMAGE } from "../output-schemas.js";
+ *   registerTool({ ..., outputSchema: OUTPUT_SCHEMA_JSON });
+ */
+/**
+ * Standard tool output schema: a single JSON text block.
+ * Used by all data-returning tools (natal chart, transits, synastry, etc.).
+ */
+export declare const OUTPUT_SCHEMA_JSON: Record<string, unknown>;
+/**
+ * Visual tool output schema: a single SVG or PNG image block.
+ * Used by chart wheel (direct image), BaZi chart, Vedic chart, etc.
+ */
+export declare const OUTPUT_SCHEMA_IMAGE: Record<string, unknown>;
+/**
+ * Dual output schema: an image block followed by a JSON text block.
+ * Used by tools with include_visual=true (natal chart SVG + data, bi-wheel, etc.).
+ */
+export declare const OUTPUT_SCHEMA_IMAGE_AND_JSON: Record<string, unknown>;
+/**
+ * Interactive app tool output schema: a text block containing MCP App metadata.
+ * Used by explore_* tools that return an embedded UI resource reference.
+ */
+export declare const OUTPUT_SCHEMA_APP: Record<string, unknown>;
+/**
+ * Auth tool output schema: a JSON text block confirming auth status or credentials.
+ */
+export declare const OUTPUT_SCHEMA_AUTH: Record<string, unknown>;

package/dist/tools/output-schemas.js

@@ -0,0 +1,130 @@
+/**
+ * output-schemas.ts — Shared JSON Schema output schema definitions for MCP tools.
+ *
+ * MCP spec 2025-11-25 supports `outputSchema` on tool definitions. Smithery
+ * uses this field to score the "Output schemas" quality criterion (10.37pt / 57 tools).
+ *
+ * All tools return an MCP content block response. Most return a single JSON text
+ * block; visual tools return an image block or an image + text block.
+ *
+ * Usage:
+ *   import { OUTPUT_SCHEMA_JSON, OUTPUT_SCHEMA_IMAGE } from "../output-schemas.js";
+ *   registerTool({ ..., outputSchema: OUTPUT_SCHEMA_JSON });
+ */
+// ── Base MCP content block shapes ─────────────────────────────────────────────
+/** JSON Schema for a single MCP text content block */
+const TEXT_CONTENT_BLOCK = {
+    type: "object",
+    properties: {
+        type: { type: "string", const: "text" },
+        text: { type: "string" },
+    },
+    required: ["type", "text"],
+    additionalProperties: false,
+};
+/** JSON Schema for a single MCP image content block */
+const IMAGE_CONTENT_BLOCK = {
+    type: "object",
+    properties: {
+        type: { type: "string", const: "image" },
+        data: { type: "string", description: "Base64-encoded image data" },
+        mimeType: { type: "string", enum: ["image/svg+xml", "image/png", "image/jpeg"] },
+    },
+    required: ["type", "data", "mimeType"],
+    additionalProperties: false,
+};
+// ── Exported output schemas ────────────────────────────────────────────────────
+/**
+ * Standard tool output schema: a single JSON text block.
+ * Used by all data-returning tools (natal chart, transits, synastry, etc.).
+ */
+export const OUTPUT_SCHEMA_JSON = {
+    type: "object",
+    properties: {
+        content: {
+            type: "array",
+            items: { oneOf: [TEXT_CONTENT_BLOCK] },
+            minItems: 1,
+        },
+        isError: { type: "boolean" },
+    },
+    required: ["content"],
+};
+/**
+ * Visual tool output schema: a single SVG or PNG image block.
+ * Used by chart wheel (direct image), BaZi chart, Vedic chart, etc.
+ */
+export const OUTPUT_SCHEMA_IMAGE = {
+    type: "object",
+    properties: {
+        content: {
+            type: "array",
+            items: { oneOf: [IMAGE_CONTENT_BLOCK] },
+            minItems: 1,
+        },
+        isError: { type: "boolean" },
+    },
+    required: ["content"],
+};
+/**
+ * Dual output schema: an image block followed by a JSON text block.
+ * Used by tools with include_visual=true (natal chart SVG + data, bi-wheel, etc.).
+ */
+export const OUTPUT_SCHEMA_IMAGE_AND_JSON = {
+    type: "object",
+    properties: {
+        content: {
+            type: "array",
+            items: { oneOf: [TEXT_CONTENT_BLOCK, IMAGE_CONTENT_BLOCK] },
+            minItems: 1,
+        },
+        isError: { type: "boolean" },
+    },
+    required: ["content"],
+};
+/**
+ * Interactive app tool output schema: a text block containing MCP App metadata.
+ * Used by explore_* tools that return an embedded UI resource reference.
+ */
+export const OUTPUT_SCHEMA_APP = {
+    type: "object",
+    properties: {
+        content: {
+            type: "array",
+            items: { oneOf: [TEXT_CONTENT_BLOCK] },
+            minItems: 1,
+        },
+        _meta: {
+            type: "object",
+            description: "MCP Apps UI linkage metadata",
+            properties: {
+                "ui/resourceUri": { type: "string" },
+                ui: {
+                    type: "object",
+                    properties: {
+                        resourceUri: { type: "string" },
+                        visibility: { type: "array", items: { type: "string" } },
+                    },
+                },
+            },
+        },
+        isError: { type: "boolean" },
+    },
+    required: ["content"],
+};
+/**
+ * Auth tool output schema: a JSON text block confirming auth status or credentials.
+ */
+export const OUTPUT_SCHEMA_AUTH = {
+    type: "object",
+    properties: {
+        content: {
+            type: "array",
+            items: { oneOf: [TEXT_CONTENT_BLOCK] },
+            minItems: 1,
+            maxItems: 1,
+        },
+        isError: { type: "boolean" },
+    },
+    required: ["content"],
+};

package/dist/tools/specialized/acg.js

@@ -1,5 +1,6 @@
 import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
+import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
 const ACG_BODY_DESCRIPTION = "List of celestial bodies for line calculation. " +
     "E.g. ['Sun', 'Moon', 'Venus', 'Mars', 'Jupiter', 'Saturn']. " +
     "Aliases: 'NorthNode'/'Node'/'Rahu' → MeanNode, 'SouthNode'/'Ketu' → SouthNode. " +
@@ -54,7 +55,8 @@ registerTool({
         required: ["birth_datetime", "birth_latitude", "birth_longitude"],
         additionalProperties: false,
     },
-    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    outputSchema: OUTPUT_SCHEMA_JSON,
+    annotations: { title: "Astrocartography Lines", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, ["birth_datetime", "birth_latitude", "birth_longitude"]);
         const body = {
@@ -147,7 +149,8 @@ registerTool({
         required: ["birth_datetime", "birth_latitude", "birth_longitude", "query_latitude", "query_longitude"],
         additionalProperties: false,
     },
-    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    outputSchema: OUTPUT_SCHEMA_JSON,
+    annotations: { title: "Astrocartography Location Hits", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, ["birth_datetime", "birth_latitude", "birth_longitude", "query_latitude", "query_longitude"]);
         const body = {

package/dist/tools/specialized/bazi.js

@@ -1,68 +1,399 @@
 import { registerTool } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
+import { OUTPUT_SCHEMA_IMAGE_AND_JSON } from "../output-schemas.js";
+function parseBaziArgs(args) {
+    let { year, month, day, hour } = args;
+    if (args.datetime && (!year || !month || !day)) {
+        const dt = new Date(args.datetime);
+        if (!isNaN(dt.getTime())) {
+            year = dt.getUTCFullYear();
+            month = dt.getUTCMonth() + 1;
+            day = dt.getUTCDate();
+            if (hour == null)
+                hour = dt.getUTCHours();
+        }
+    }
+    if (!year || !month || !day) {
+        throw new Error("Provide year/month/day fields, or a datetime ISO string. " +
+            "Example: year=1987, month=7, day=15 OR datetime='1987-07-15T14:00:00'");
+    }
+    const out = { year, month, day };
+    if (hour != null)
+        out.hour = hour;
+    return out;
+}
+// Shared datetime input schema fragment — used across all BaZiRequest tools.
+const DATETIME_PROPERTIES = {
+    year: {
+        type: "integer",
+        description: "Gregorian birth year, e.g. 1987.",
+    },
+    month: {
+        type: "integer",
+        description: "Birth month (1–12).",
+    },
+    day: {
+        type: "integer",
+        description: "Birth day of month (1–31).",
+    },
+    hour: {
+        type: "integer",
+        description: "Birth hour (0–23). Optional, defaults to 12 (noon). " +
+            "Chinese shí hours are 2-hour blocks — precision within a 2-hour window is sufficient.",
+    },
+    datetime: {
+        type: "string",
+        description: "Alternative to year/month/day: ISO 8601 datetime (e.g. '1987-07-15T14:00:00'). " +
+            "year/month/day/hour are extracted automatically. Use this OR the individual fields.",
+    },
+};
+// Shared visual input schema fragment — mirrors natal.ts pattern.
+const VISUAL_PROPERTIES = {
+    include_visual: {
+        type: "boolean",
+        description: "When true, the response includes a rendered SVG chart of the Four Pillars. " +
+            "Costs an extra 2 credits (total 3 credits). Ideal for delivering a visual alongside text analysis.",
+    },
+    visual_config: {
+        type: "object",
+        description: "Optional rendering preferences. Only relevant when include_visual=true.",
+        properties: {
+            theme: {
+                type: "string",
+                enum: ["light", "dark", "mono"],
+                description: "Chart color theme. Defaults to 'light'.",
+            },
+            size: {
+                type: "integer",
+                description: "Chart width in pixels (400–1600). Defaults to 800.",
+            },
+        },
+        additionalProperties: false,
+    },
+};
+// buildVisualBody appends include_visual and visual_config to a request body
+// when the caller passes include_visual=true.
+function applyVisualConfig(body, args) {
+    if (args.include_visual) {
+        body.include_visual = true;
+        body.visual_config = {
+            format: "svg", // always SVG for MCP — no resvg dependency in prod
+            theme: args.visual_config?.theme ?? "light",
+            size: args.visual_config?.size ?? 800,
+        };
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// chinese_bazi — base Four Pillars chart
+// ─────────────────────────────────────────────────────────────────────────────
 registerTool({
     name: "chinese_bazi",
-    description: "Calculate a Chinese Ba Zi (Four Pillars of Destiny) chart. Returns the Year, Month, Day, " +
-        "and Hour pillars, each containing a Heavenly Stem and Earthly Branch pair. Also includes " +
-        "the Day Master element, Wu Xing element breakdown, and basic interpretation context.\n\n" +
-        "CREDIT COST: 1 credit per call.\n\n" +
-        "You can provide either a datetime string (which will be decomposed automatically) " +
-        "or explicit year/month/day/hour values.\n\n" +
-        "EXAMPLE: Ba Zi for someone born July 15, 1987 at 2:00 PM:\n" +
+    description: "Calculate a Chinese BaZi (四柱命盘 Four Pillars of Destiny) chart. Returns the Year, Month, Day, " +
+        "and Hour pillars, each with a Heavenly Stem (天干) and Earthly Branch (地支) pair. " +
+        "Includes the Day Master element and basic metadata.\n\n" +
+        "CREDIT COST: 1 credit (3 credits when include_visual=true).\n\n" +
+        "Set include_visual=true to receive a rendered SVG chart alongside the text data.\n\n" +
+        "For deep analysis, follow up with:\n" +
+        "  • bazi_ten_gods()         — Ten Gods (十神) per pillar including hidden stems\n" +
+        "  • bazi_element_balance()  — Weighted Wu Xing (五行) element scores + Yong Shen\n" +
+        "  • bazi_luck_pillars()     — 8 Da Yun 10-year luck cycles\n\n" +
+        "EXAMPLE: BaZi chart for someone born July 15, 1987 at 2 PM:\n" +
+        "  year=1987, month=7, day=15, hour=14",
+    inputSchema: {
+        type: "object",
+        properties: {
+            ...DATETIME_PROPERTIES,
+            ...VISUAL_PROPERTIES,
+        },
+        additionalProperties: false,
+    },
+    outputSchema: OUTPUT_SCHEMA_IMAGE_AND_JSON,
+    annotations: { title: "BaZi Four Pillars Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    handler: async (args) => {
+        const body = { ...parseBaziArgs(args) };
+        applyVisualConfig(body, args);
+        return await getActiveClient().request("POST", "/chinese/bazi", { data: body });
+    },
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// bazi_ten_gods — Ten Gods (十神) analysis
+// ─────────────────────────────────────────────────────────────────────────────
+registerTool({
+    name: "bazi_ten_gods",
+    description: "Calculate the Ten Gods (十神 Shí Shén) for a BaZi chart. Each of the 10 gods describes " +
+        "the relationship between the Day Master (日主, the person's core identity element) and " +
+        "every other Heavenly Stem in the chart — including visible stems and the hidden stems " +
+        "stored within each Earthly Branch.\n\n" +
+        "The 10 gods and their categories:\n" +
+        "  COMPANION: Friend (比肩), Rob Wealth (劫财)\n" +
+        "  OUTPUT:    Eating God (食神), Hurting Officer (伤官)\n" +
+        "  WEALTH:    Indirect Wealth (偏财), Direct Wealth (正财)\n" +
+        "  POWER:     Seven Killings (七杀), Direct Officer (正官)\n" +
+        "  RESOURCE:  Indirect Resource (偏印), Direct Resource (正印)\n\n" +
+        "The Day Pillar itself has no Ten God (it IS the Day Master). " +
+        "Hidden stems in the Day Branch still receive Ten God labels.\n\n" +
+        "CREDIT COST: 1 credit (3 credits when include_visual=true).\n\n" +
+        "Set include_visual=true to receive an SVG Four Pillars chart alongside the Ten Gods data.\n\n" +
+        "EXAMPLE: Ten Gods for someone born July 15, 1987 at 2 PM:\n" +
         "  year=1987, month=7, day=15, hour=14",
+    inputSchema: {
+        type: "object",
+        properties: {
+            ...DATETIME_PROPERTIES,
+            ...VISUAL_PROPERTIES,
+        },
+        additionalProperties: false,
+    },
+    outputSchema: OUTPUT_SCHEMA_IMAGE_AND_JSON,
+    annotations: { title: "BaZi Day Master Analysis", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    handler: async (args) => {
+        const body = { ...parseBaziArgs(args) };
+        applyVisualConfig(body, args);
+        return await getActiveClient().request("POST", "/chinese/bazi/ten-gods", { data: body });
+    },
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// bazi_element_balance — Wu Xing (五行) weighted element analysis
+// ─────────────────────────────────────────────────────────────────────────────
+registerTool({
+    name: "bazi_element_balance",
+    description: "Calculate the weighted Wu Xing (五行 Five Elements) distribution for a BaZi chart. " +
+        "Returns percentage scores for Wood, Fire, Earth, Metal, and Water across all chart positions.\n\n" +
+        "Scoring is weighted — hidden stems inside Earthly Branches count toward element totals:\n" +
+        "  • Visible Heavenly Stems: 1.0 weight each (4 positions)\n" +
+        "  • Hidden Stem main (本气):      1.0 weight\n" +
+        "  • Hidden Stem secondary (中气): 0.6 weight\n" +
+        "  • Hidden Stem residual (余气):  0.3 weight\n\n" +
+        "Also returns:\n" +
+        "  • Day Master strength: 'strong' (旺, ≥50% own+resource elements) or 'weak' (弱)\n" +
+        "  • Yong Shen (用神): the favorable element — what the chart needs most\n\n" +
+        "CREDIT COST: 1 credit (3 credits when include_visual=true).\n\n" +
+        "Set include_visual=true to receive an SVG Four Pillars chart alongside the element data.\n\n" +
+        "EXAMPLE: Element balance for 1987-07-15 at 14:00:\n" +
+        "  year=1987, month=7, day=15, hour=14",
+    inputSchema: {
+        type: "object",
+        properties: {
+            ...DATETIME_PROPERTIES,
+            ...VISUAL_PROPERTIES,
+        },
+        additionalProperties: false,
+    },
+    outputSchema: OUTPUT_SCHEMA_IMAGE_AND_JSON,
+    annotations: { title: "BaZi Clash & Combination", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    handler: async (args) => {
+        const body = { ...parseBaziArgs(args) };
+        applyVisualConfig(body, args);
+        return await getActiveClient().request("POST", "/chinese/bazi/element-balance", { data: body });
+    },
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// bazi_luck_pillars — Da Yun (大运) 10-year luck cycles
+// ─────────────────────────────────────────────────────────────────────────────
+registerTool({
+    name: "bazi_luck_pillars",
+    description: "Calculate the 8 Da Yun (大运) 10-year luck pillar cycles for a BaZi chart. " +
+        "Luck pillars sequence through the sexagenary cycle starting from a person's " +
+        "'starting age' (起运岁数), calculated by counting days from birth to the nearest " +
+        "solar term boundary (Jié 节). Each 3 days = 1 year of starting age (Zi Ping rule).\n\n" +
+        "Direction (forward/backward) depends on gender and year polarity:\n" +
+        "  • Male in Yang year → forward\n" +
+        "  • Male in Yin year → backward\n" +
+        "  • Female in Yang year → backward\n" +
+        "  • Female in Yin year → forward\n\n" +
+        "gender is REQUIRED — the direction of luck pillars is gender-dependent.\n\n" +
+        "Returns: starting_age, direction, direction_reason, and 8 pillars each with:\n" +
+        "  stem, branch, Chinese characters, element, start_age, end_age\n\n" +
+        "CREDIT COST: 1 credit per call.\n\n" +
+        "EXAMPLE: Luck pillars for a female born July 15, 1987 at 2 PM:\n" +
+        "  year=1987, month=7, day=15, hour=14, gender='female'",
+    inputSchema: {
+        type: "object",
+        properties: {
+            ...DATETIME_PROPERTIES,
+            gender: {
+                type: "string",
+                enum: ["male", "female"],
+                description: "Required. Determines the direction of Da Yun progression. " +
+                    "Male in Yang year / Female in Yin year → forward. " +
+                    "Male in Yin year / Female in Yang year → backward.",
+            },
+        },
+        required: ["gender"],
+        additionalProperties: false,
+    },
+    outputSchema: OUTPUT_SCHEMA_IMAGE_AND_JSON,
+    annotations: { title: "BaZi Ten Gods", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    handler: async (args) => {
+        if (!args.gender) {
+            throw new Error("gender is required for luck pillar calculation. " +
+                "Provide 'male' or 'female' — the direction of Da Yun depends on gender and year polarity.");
+        }
+        const { year, month, day, hour } = parseBaziArgs(args);
+        const body = { year, month, day, gender: args.gender };
+        if (hour != null)
+            body.hour = hour;
+        return await getActiveClient().request("POST", "/chinese/bazi/luck-pillars", { data: body });
+    },
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// bazi_annual_pillar — sexagenary year pillar + NaYin
+// ─────────────────────────────────────────────────────────────────────────────
+registerTool({
+    name: "bazi_annual_pillar",
+    description: "Look up the sexagenary pillar for any Gregorian year (1–9999). Returns the Heavenly Stem, " +
+        "Earthly Branch, Chinese characters, zodiac animal, element, polarity, and NaYin (纳音) " +
+        "poetic resonance image.\n\n" +
+        "NaYin maps each pair in the 60-cycle sexagenary sequence to one of 30 elemental images " +
+        "(e.g. '海中金 Metal in the Sea', '炉中火 Fire in the Furnace'). It is traditionally " +
+        "applied to the Year and Day pillars to reveal deeper elemental character.\n\n" +
+        "Use this to:\n" +
+        "  • Identify the energetic quality of any given year\n" +
+        "  • Determine a person's birth year pillar for compatibility context\n" +
+        "  • Find the NaYin element for year or day interpretations\n\n" +
+        "CREDIT COST: 1 credit per call.\n\n" +
+        "EXAMPLE: Year pillar for 2025:\n" +
+        "  year=2025",
     inputSchema: {
         type: "object",
         properties: {
             year: {
                 type: "integer",
-                description: "Gregorian birth year, e.g. 1987.",
+                description: "Gregorian year (1–9999). e.g. 2025.",
             },
-            month: {
-                type: "integer",
-                description: "Birth month (1-12).",
+        },
+        required: ["year"],
+        additionalProperties: false,
+    },
+    outputSchema: OUTPUT_SCHEMA_IMAGE_AND_JSON,
+    annotations: { title: "BaZi Luck Pillars", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    handler: async (args) => {
+        if (!args.year) {
+            throw new Error("year is required. Provide a Gregorian year (1–9999), e.g. year=2025.");
+        }
+        return await getActiveClient().request("POST", "/chinese/bazi/annual-pillar", {
+            data: { year: args.year },
+        });
+    },
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// bazi_compatibility — pair chart scoring
+// ─────────────────────────────────────────────────────────────────────────────
+registerTool({
+    name: "bazi_compatibility",
+    description: "Calculate BaZi compatibility between two people by comparing their Four Pillars charts. " +
+        "Returns a score 0–100, an assessment, and a breakdown of the harmony/clash/penalty " +
+        "factors found between the two charts.\n\n" +
+        "Scoring factors include:\n" +
+        "  +5  Six Harmony (六合 Liù Hé) — branch pair bonds\n" +
+        "  +8  Three Harmonies (三合 Sān Hé) — branch trinity formations\n" +
+        "  -8  Six Clash (六冲 Liù Chōng) — opposing branch pairs\n" +
+        "  -5  Six Harm (六害 Liù Hài) — branch interference pairs\n" +
+        "  -6  Three Penalties (三刑 Sān Xíng) — branch penalty formations\n\n" +
+        "Assessment grades:\n" +
+        "  90–100: excellent | 70–89: good | 50–69: moderate | below 50: challenging\n\n" +
+        "CREDIT COST: 2 credits per call.\n\n" +
+        "EXAMPLE: Compatibility between two people:\n" +
+        "  chart_a_year=1987, chart_a_month=7, chart_a_day=15, chart_a_hour=14\n" +
+        "  chart_b_year=1990, chart_b_month=3, chart_b_day=22, chart_b_hour=8",
+    inputSchema: {
+        type: "object",
+        properties: {
+            // Chart A
+            chart_a_year: { type: "integer", description: "Chart A birth year." },
+            chart_a_month: { type: "integer", description: "Chart A birth month (1–12)." },
+            chart_a_day: { type: "integer", description: "Chart A birth day (1–31)." },
+            chart_a_hour: { type: "integer", description: "Chart A birth hour (0–23). Optional." },
+            chart_a_datetime: {
+                type: "string",
+                description: "Chart A alternative: ISO 8601 datetime. Extracts year/month/day/hour automatically.",
             },
-            day: {
-                type: "integer",
-                description: "Birth day of month (1-31).",
+            // Chart B
+            chart_b_year: { type: "integer", description: "Chart B birth year." },
+            chart_b_month: { type: "integer", description: "Chart B birth month (1–12)." },
+            chart_b_day: { type: "integer", description: "Chart B birth day (1–31)." },
+            chart_b_hour: { type: "integer", description: "Chart B birth hour (0–23). Optional." },
+            chart_b_datetime: {
+                type: "string",
+                description: "Chart B alternative: ISO 8601 datetime. Extracts year/month/day/hour automatically.",
             },
-            hour: {
-                type: "integer",
-                description: "Birth hour (0-23). Optional, defaults to 12 (noon). " +
-                    "Chinese hours (shí) are 2-hour blocks, so precision within a 2-hour window is sufficient.",
+        },
+        additionalProperties: false,
+    },
+    outputSchema: OUTPUT_SCHEMA_IMAGE_AND_JSON,
+    annotations: { title: "BaZi Annual Pillars", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    handler: async (args) => {
+        const chartAComponents = parseBaziArgs({
+            year: args.chart_a_year,
+            month: args.chart_a_month,
+            day: args.chart_a_day,
+            hour: args.chart_a_hour,
+            datetime: args.chart_a_datetime,
+        });
+        const chartBComponents = parseBaziArgs({
+            year: args.chart_b_year,
+            month: args.chart_b_month,
+            day: args.chart_b_day,
+            hour: args.chart_b_hour,
+            datetime: args.chart_b_datetime,
+        });
+        return await getActiveClient().request("POST", "/chinese/bazi/compatibility", {
+            data: {
+                chart_a: chartAComponents,
+                chart_b: chartBComponents,
             },
-            datetime: {
+        });
+    },
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// bazi_chart — dedicated Four Pillars SVG chart visual
+// ─────────────────────────────────────────────────────────────────────────────
+registerTool({
+    name: "bazi_chart",
+    description: "Render a self-contained SVG chart of a BaZi Four Pillars chart. " +
+        "Returns a production-quality visualization showing:\n" +
+        "  • All four pillars (Year, Month, Day, Hour) with Heavenly Stems and Earthly Branches\n" +
+        "  • Ten Gods (十神) labels for each non-Day pillar\n" +
+        "  • Wu Xing (五行) element balance bar chart\n" +
+        "  • Day Master identity with element and polarity\n\n" +
+        "The chart is rendered in the Open Ephemeris design system (OKLCH color tokens) " +
+        "and is fully self-contained — suitable for embedding or display without dependencies.\n\n" +
+        "Theme options: 'light' (default), 'dark', 'mono'.\n\n" +
+        "CREDIT COST: 3 credits per call (1 base + 2 visual render).\n\n" +
+        "Use this tool when the user asks to 'show', 'visualize', 'draw', or 'render' " +
+        "a BaZi / Four Pillars chart. For text-only data, use chinese_bazi() instead.\n\n" +
+        "EXAMPLE: Render a chart for someone born July 15, 1987 at 2 PM:\n" +
+        "  year=1987, month=7, day=15, hour=14",
+    inputSchema: {
+        type: "object",
+        properties: {
+            ...DATETIME_PROPERTIES,
+            theme: {
                 type: "string",
-                description: "Alternative: ISO 8601 datetime (e.g. '1987-07-15T14:00:00'). " +
-                    "If provided, year/month/day/hour are extracted automatically. " +
-                    "Use this OR the individual year/month/day fields, not both.",
+                enum: ["light", "dark", "mono"],
+                description: "Chart color theme. Defaults to 'light'.",
+            },
+            size: {
+                type: "integer",
+                description: "Chart width in pixels (400–1600). Defaults to 800.",
             },
         },
         additionalProperties: false,
     },
-    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    outputSchema: OUTPUT_SCHEMA_IMAGE_AND_JSON,
+    annotations: { title: "BaZi Compatibility", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
-        let year = args.year;
-        let month = args.month;
-        let day = args.day;
-        let hour = args.hour;
-        // If datetime provided, extract components
-        if (args.datetime && (!year || !month || !day)) {
-            const dt = new Date(args.datetime);
-            if (!isNaN(dt.getTime())) {
-                year = dt.getUTCFullYear();
-                month = dt.getUTCMonth() + 1;
-                day = dt.getUTCDate();
-                if (hour == null)
-                    hour = dt.getUTCHours();
-            }
-        }
-        if (!year || !month || !day) {
-            throw new Error("Either provide year/month/day fields, or a datetime string. " +
-                "Example: year=1987, month=7, day=15 OR datetime='1987-07-15T14:00:00'");
-        }
-        const body = { year, month, day };
+        const { year, month, day, hour } = parseBaziArgs(args);
+        const body = {
+            year, month, day,
+            visual_config: {
+                format: "svg",
+                theme: args.theme ?? "light",
+                size: args.size ?? 800,
+            },
+        };
         if (hour != null)
             body.hour = hour;
-        return await getActiveClient().request("POST", "/chinese/bazi", { data: body });
+        return await getActiveClient().request("POST", "/chinese/bazi/chart", { data: body });
     },
 });

package/dist/tools/specialized/bi_wheel.js

@@ -1,5 +1,6 @@
 import { registerTool, validateRequired } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
+import { OUTPUT_SCHEMA_IMAGE } from "../output-schemas.js";
 const DATETIME_DESC = "ISO 8601 datetime string, e.g. '1990-04-15T14:30:00' (local time at birth location). " +
     "Include timezone offset if known, e.g. '1990-04-15T14:30:00-05:00'.";
 const HOUSE_SYSTEM_MAP = {
@@ -38,7 +39,8 @@ registerTool({
         required: ["datetime_a", "latitude_a", "longitude_a", "datetime_b", "latitude_b", "longitude_b"],
         additionalProperties: false,
     },
-    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+    outputSchema: OUTPUT_SCHEMA_IMAGE,
+    annotations: { title: "Bi-Wheel Chart", readOnlyHint: true, destructiveHint: false, idempotentHint: true },
     handler: async (args) => {
         validateRequired(args, ["datetime_a", "latitude_a", "longitude_a", "datetime_b", "latitude_b", "longitude_b"]);
         const body = {