@openephemeris/mcp-server 4.3.1 → 4.4.0

package/CHANGELOG.md

@@ -7,6 +7,45 @@ Version numbering follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [4.4.0] — 2026-07-30
+
+Puts the location resolver on the natural path for the four `explore_*`
+chart tools, and corrects two parameter descriptions that had drifted from
+the code.
+
+### Added
+
+- **`location` on `explore_natal_chart`, `explore_human_design`,
+  `explore_vedic_chart`, and `explore_bi_wheel` now resolves internally.**
+  Supply a plain place name — `location: "Portland, ME"` — and the tool
+  fills in the coordinates and (unless overridden) the timezone via the
+  same `/location/autocomplete` lookup `location_search` uses. Supplied
+  `latitude`/`longitude` always win. Ambiguous names (e.g. bare
+  `"portland"`) throw with a disambiguation hint rather than silently
+  picking the top hit — the same behaviour `location_search` reports as
+  `ambiguous: true`.
+  A prior smoke run measured `location_search` adoption at **1 in 8** when
+  it was documented but off the natural path; every request supplied
+  coordinates from model memory instead. Wiring `location` into the chart
+  tools themselves makes the resolver the minimum-effort call.
+
+### Fixed
+
+- **`explore_human_design` no longer silently computes at 0°N 0°E.**
+  When neither `latitude`/`longitude` nor a resolvable `location` is
+  supplied, the call is now rejected with a clear message. Previously a
+  bare `datetime` produced a plausible-looking bodygraph anchored on the
+  Gulf of Guinea — a location-sensitive system silently defaulting to a
+  wrong location is the failure class the Phase-0 audits keep catching.
+- **`include_fixed_stars` and `include_arabic_parts` descriptions on
+  `ephemeris_natal_chart` no longer say "Reserved for future use".** Both
+  parameters have always been wired to their respective configuration
+  keys (`configuration.fixed_star_options.include: true` and
+  `options.include_hermetic_lots: true`); only the descriptions were
+  stale.
+
+---
+
 ## [4.3.1] — 2026-07-29
 
 Two rendering fixes surfaced by the Phase-0 v4.3 audit, plus a companion

package/dist/tools/apps/_location-resolver.d.ts

@@ -0,0 +1,34 @@
+export interface ResolvedLocation {
+    latitude: number;
+    longitude: number;
+    timezone: string | null;
+    displayName: string;
+    placeId: string | null;
+}
+/**
+ * Resolve a place name to lat/lon/tz. Throws if ambiguous or unresolvable.
+ *
+ * Ambiguity is detected the same way `location_search` reports it — a
+ * count of *rivals* for the top short_name, unless the query itself
+ * qualifies the place (e.g. "portland uk", "dallas texas").
+ */
+export declare function resolveLocationOrThrow(location: string): Promise<ResolvedLocation>;
+/**
+ * Convenience wrapper: fills in missing lat/lon (and optionally timezone)
+ * from `location` when the caller left them unset. Returns the effective
+ * coordinates + a display-safe location string. Coords passed in win —
+ * this only fires when both are unset. If only one of lat/lon is set,
+ * throws (partial input is a user error).
+ */
+export declare function coordsFromArgsOrLocation(args: {
+    latitude?: unknown;
+    longitude?: unknown;
+    timezone?: unknown;
+    location?: unknown;
+}): Promise<{
+    latitude: number | undefined;
+    longitude: number | undefined;
+    timezone: string | undefined;
+    location: string | undefined;
+    resolvedFromLocation: boolean;
+}>;

package/dist/tools/apps/_location-resolver.js

@@ -0,0 +1,100 @@
+// Internal location resolver used by `explore_*` tools when the caller
+// supplies a place name (`location`) but omits `latitude`/`longitude`.
+//
+// The point is to put the resolver ON the model's natural path rather than
+// hoping tool-description prose ("call location_search first") convinces
+// the model to detour when it already has plausible coordinates in memory.
+// A live smoke test measured that path at 1-in-8 adoption vs 8-in-8 for
+// the same guidance when the request-shape *forced* the model's hand
+// (naive datetime → 400).
+//
+// Ambiguity handling MUST mirror `location_search` — if the top hit has
+// rival cities of the same short name and the query didn't already qualify
+// it (e.g. "portland uk"), throw rather than silently pick suggestions[0].
+// A quiet default to Portland, OR when the user meant Portland, ME
+// produces a chart nothing downstream can detect as wrong. Same failure
+// class as the naive-UTC ASC and the unlabelled cusp longitudes.
+import { getActiveClient } from "../../backend/client.js";
+/**
+ * Resolve a place name to lat/lon/tz. Throws if ambiguous or unresolvable.
+ *
+ * Ambiguity is detected the same way `location_search` reports it — a
+ * count of *rivals* for the top short_name, unless the query itself
+ * qualifies the place (e.g. "portland uk", "dallas texas").
+ */
+export async function resolveLocationOrThrow(location) {
+    const query = location.trim();
+    if (query === "") {
+        throw new Error("location is empty");
+    }
+    const raw = (await getActiveClient().request("GET", "/location/autocomplete", {
+        params: { query },
+    }));
+    const list = Array.isArray(raw?.suggestions) ? raw.suggestions : [];
+    if (list.length === 0) {
+        throw new Error(`location "${query}" did not match any known place. Call location_search directly to inspect suggestions, ` +
+            `or supply latitude/longitude explicitly.`);
+    }
+    const norm = (v) => String(v ?? "").trim().toLowerCase();
+    const top = list[0];
+    const rivals = list.filter((s) => norm(s.short_name) === norm(top.short_name));
+    const q = norm(query);
+    const qTokens = new Set(q.split(/[^a-z0-9]+/).filter(Boolean));
+    const qualified = (norm(top.region) !== "" && q.includes(norm(top.region))) ||
+        (norm(top.country_code) !== "" && qTokens.has(norm(top.country_code)));
+    const ambiguous = rivals.length > 1 && !qualified;
+    if (ambiguous) {
+        const options = rivals
+            .slice(0, 4)
+            .map((s) => `${s.display_name ?? s.short_name} (${s.country_code ?? "??"})`)
+            .join("; ");
+        throw new Error(`location "${query}" is ambiguous — matches ${rivals.length} places (${options}${rivals.length > 4 ? ", …" : ""}). Call location_search directly and pass the disambiguated place, or supply latitude/longitude explicitly.`);
+    }
+    if (top.latitude == null || top.longitude == null) {
+        throw new Error(`location "${query}" matched "${top.display_name ?? top.short_name}" but the record is missing coordinates. ` +
+            `Supply latitude/longitude explicitly.`);
+    }
+    return {
+        latitude: Number(top.latitude),
+        longitude: Number(top.longitude),
+        timezone: top.timezone ?? null,
+        displayName: String(top.display_name ?? top.short_name ?? query),
+        placeId: top.place_id ?? null,
+    };
+}
+/**
+ * Convenience wrapper: fills in missing lat/lon (and optionally timezone)
+ * from `location` when the caller left them unset. Returns the effective
+ * coordinates + a display-safe location string. Coords passed in win —
+ * this only fires when both are unset. If only one of lat/lon is set,
+ * throws (partial input is a user error).
+ */
+export async function coordsFromArgsOrLocation(args) {
+    const lat = args.latitude;
+    const lon = args.longitude;
+    const tz = args.timezone;
+    const loc = args.location;
+    const latSet = lat != null;
+    const lonSet = lon != null;
+    if (latSet && lonSet) {
+        return { latitude: lat, longitude: lon, timezone: tz, location: loc, resolvedFromLocation: false };
+    }
+    if (latSet !== lonSet) {
+        throw new Error("latitude and longitude must both be supplied (or both omitted with a `location` name).");
+    }
+    if (!loc || String(loc).trim() === "") {
+        // Neither coords nor location — leave undefined; the tool's own
+        // validation decides whether that's acceptable (some tools, like
+        // explore_human_design, historically defaulted to 0°N 0°E, which
+        // is a silent-wrong we want to end).
+        return { latitude: undefined, longitude: undefined, timezone: tz, location: loc, resolvedFromLocation: false };
+    }
+    const resolved = await resolveLocationOrThrow(String(loc));
+    return {
+        latitude: resolved.latitude,
+        longitude: resolved.longitude,
+        timezone: tz ?? resolved.timezone ?? undefined,
+        location: resolved.displayName,
+        resolvedFromLocation: true,
+    };
+}

package/dist/tools/apps/bi-wheel-app.js

@@ -27,6 +27,7 @@ import { registerTool, SERVER_VERSION } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
 import { DATETIME_DESC, timezoneProperty } from "../datetime.js";
+import { coordsFromArgsOrLocation } from "./_location-resolver.js";
 // ── Constants ─────────────────────────────────────────────────────────────────
 export const BI_WHEEL_RESOURCE_URI = "ui://openephemeris/bi-wheel";
 export const BI_WHEEL_MIME_TYPE = "text/html;profile=mcp-app";
@@ -430,8 +431,8 @@ registerTool({
                 type: "string",
                 description: "Birth datetime for Person 1 / Natal chart. " + DATETIME_DESC,
             },
-            person1_latitude: { type: "number", description: "Birth latitude for Person 1 (decimal degrees, positive = North). Resolve from a place name with location_search; never recall coordinates from memory." },
-            person1_longitude: { type: "number", description: "Birth longitude for Person 1 (decimal degrees, positive = East)." },
+            person1_latitude: { type: "number", description: "Birth latitude for Person 1 (decimal degrees, positive = North). Optional if `location` is a place name — the resolver fills it in. Never recall coordinates from memory." },
+            person1_longitude: { type: "number", description: "Birth longitude for Person 1 (decimal degrees, positive = East). Optional if `location` is a place name." },
             person1_timezone: timezoneProperty("Person 1's birth location", "America/New_York"),
             person1_name: {
                 type: "string",
@@ -452,7 +453,7 @@ registerTool({
             },
             location: {
                 type: "string",
-                description: "Label for Person 1 / Natal location (display only, e.g. 'New York, NY'). This is a caption, NOT a geocoder — it does not set the chart location. Supply latitude/longitude too (resolve them with location_search), or the chart is computed at 0N 0E.",
+                description: "Person 1 / Natal location. Prefer a plain place name like 'New York, NY' — the server resolves it via the same lookup `location_search` uses (unambiguous names → coords + timezone; ambiguous names throw with a disambiguation hint). Supplied person1_latitude/person1_longitude always win.",
             },
             mode: {
                 type: "string",
@@ -460,8 +461,7 @@ registerTool({
                 description: "Chart comparison mode. Defaults to 'synastry'.",
             },
         },
-        required: ["person1_datetime", "person2_datetime",
-            "person1_latitude", "person1_longitude"],
+        required: ["person1_datetime", "person2_datetime"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
     annotations: {
@@ -480,15 +480,24 @@ registerTool({
     handler: async (args) => {
         const client = getActiveClient();
         const mode = args.mode ?? "synastry";
+        const resolved1 = await coordsFromArgsOrLocation({
+            latitude: args.person1_latitude,
+            longitude: args.person1_longitude,
+            timezone: args.person1_timezone,
+            location: args.location,
+        });
+        if (resolved1.latitude == null || resolved1.longitude == null) {
+            throw new Error("explore_bi_wheel requires either `person1_latitude` + `person1_longitude` or a resolvable `location` name.");
+        }
         const dt1 = String(args.person1_datetime);
-        const lat1 = args.person1_latitude;
-        const lon1 = args.person1_longitude;
-        const tz1 = args.person1_timezone;
+        const lat1 = resolved1.latitude;
+        const lon1 = resolved1.longitude;
+        const tz1 = args.person1_timezone ?? resolved1.timezone;
         const dt2 = String(args.person2_datetime);
         const lat2 = args.person2_latitude;
         const lon2 = args.person2_longitude;
         const tz2 = args.person2_timezone;
-        const loc1 = String(args.person1_name ?? args.location ?? `${lat1 ?? "?"},${lon1 ?? "?"}`);
+        const loc1 = String(args.person1_name ?? resolved1.location ?? args.location ?? `${lat1},${lon1}`);
         const loc2 = MODE_META[mode].outerLabel(dt2, args.person2_name);
         // Fetch inner (natal) and outer (mode-dependent) charts in parallel where possible
         const [innerData, outerData] = await Promise.all([

package/dist/tools/apps/bodygraph-app.js

@@ -26,6 +26,7 @@ import { registerTool, SERVER_VERSION } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
 import { localToUtcIso } from "../datetime.js";
+import { coordsFromArgsOrLocation } from "./_location-resolver.js";
 // ── Constants ─────────────────────────────────────────────────────────────
 export const BODYGRAPH_RESOURCE_URI = "ui://openephemeris/bodygraph";
 // Appended to every model-visible HD tool description — trademark hygiene.
@@ -326,15 +327,15 @@ registerTool({
             },
             latitude: {
                 type: "number",
-                description: "Birth latitude in decimal degrees (positive = North). Optional for HD charts. Resolve from a place name with location_search; never recall coordinates from memory.",
+                description: "Birth latitude in decimal degrees (positive = North). Optional if `location` is a place name — the resolver fills it in. Never recall coordinates from memory; either supply a place name or resolve with location_search first.",
             },
             longitude: {
                 type: "number",
-                description: "Birth longitude in decimal degrees (positive = East). Optional for HD charts.",
+                description: "Birth longitude in decimal degrees (positive = East). Optional if `location` is a place name.",
             },
             location: {
                 type: "string",
-                description: "Location name for display only (e.g. 'New York, NY'). This is a caption, NOT a geocoder — it does not set the chart location. Supply latitude/longitude too (resolve them with location_search), or the chart is computed at 0N 0E.",
+                description: "Birth location. Prefer a plain place name like 'New York, NY' — the server resolves it via the same lookup `location_search` uses (unambiguous names → coords + timezone; ambiguous names throw with a disambiguation hint). If neither location nor lat/lon is supplied the call is rejected — no more silent 0°N 0°E charts.",
             },
             timezone: {
                 type: "string",
@@ -361,18 +362,29 @@ registerTool({
     },
     handler: async (args) => {
         const client = getActiveClient();
-        const timezone = args.timezone;
+        // Resolve `location` → lat/lon/tz when the caller left coords unset.
+        // If neither is provided we throw rather than silently computing at
+        // 0°N 0°E (a plausible-looking chart nothing downstream can detect).
+        const resolved = await coordsFromArgsOrLocation({
+            latitude: args.latitude,
+            longitude: args.longitude,
+            timezone: args.timezone,
+            location: args.location,
+        });
+        const timezone = args.timezone ?? resolved.timezone;
         const datetime = localToUtcIso("datetime", String(args.datetime), timezone);
-        const location = String(args.location ?? (args.latitude != null ? `${args.latitude}, ${args.longitude}` : "Unknown")).slice(0, 120);
-        const lat = args.latitude;
-        const lon = args.longitude;
+        const lat = resolved.latitude;
+        const lon = resolved.longitude;
+        if (lat == null || lon == null) {
+            throw new Error("explore_human_design requires either `latitude` + `longitude` or a resolvable `location` name. " +
+                "Human Design is sensitive to birth location; a chart at 0°N 0°E is silently wrong.");
+        }
+        const location = String(resolved.location ?? args.location ?? `${lat}, ${lon}`).slice(0, 120);
         const body = {
             birth_datetime_utc: datetime,
         };
-        if (lat != null)
-            body.latitude = lat;
-        if (lon != null)
-            body.longitude = lon;
+        body.latitude = lat;
+        body.longitude = lon;
         const bundleAvailable = Boolean(getBodygraphBundle());
         // Fetch chart data and Go-rendered SVG in parallel. SVG only fetched when
         // the iframe bundle is available (text-fallback hosts have no use for it,
@@ -390,7 +402,7 @@ registerTool({
         // Build payload once — summary and model data both derive from the same object
         const modelPayload = buildHdModelPayload(chart, {
             datetime,
-            location: args.location ?? null,
+            location: resolved.location ?? args.location ?? null,
             timezone: timezone ?? null,
             latitude: lat ?? null,
             longitude: lon ?? null,

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

@@ -22,6 +22,7 @@ import { registerTool, SERVER_VERSION } from "../index.js";
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
 import { DATETIME_DESC, TIMEZONE_PROPERTY } from "../datetime.js";
+import { coordsFromArgsOrLocation } from "./_location-resolver.js";
 // ── Constants ─────────────────────────────────────────────────────────────
 export const CHART_WHEEL_RESOURCE_URI = "ui://openephemeris/chart-wheel";
 export const CHART_WHEEL_MIME_TYPE = "text/html;profile=mcp-app";
@@ -125,15 +126,15 @@ registerTool({
             timezone: TIMEZONE_PROPERTY,
             latitude: {
                 type: "number",
-                description: "Birth latitude in decimal degrees (positive = North). Resolve from a place name with location_search; never recall coordinates from memory.",
+                description: "Birth latitude in decimal degrees (positive = North). Optional if `location` is a place name — the resolver fills it in. If you supply lat/lon directly, resolve them with location_search first; never recall coordinates from memory.",
             },
             longitude: {
                 type: "number",
-                description: "Birth longitude in decimal degrees (positive = East).",
+                description: "Birth longitude in decimal degrees (positive = East). Optional if `location` is a place name.",
             },
             location: {
                 type: "string",
-                description: "Location name for display only (e.g. 'New York, NY'). This is a caption, NOT a geocoder — it does not set the chart location. Supply latitude/longitude too (resolve them with location_search), or the chart is computed at 0N 0E.",
+                description: "Birth location. Prefer a plain place name like 'New York, NY' — the server resolves it via the same lookup `location_search` uses (unambiguous names → coords + timezone; ambiguous names throw with a disambiguation hint). If you already have coords, either omit this or use it as a display caption; supplied coords always win.",
             },
             house_system: {
                 type: "string",
@@ -149,7 +150,7 @@ registerTool({
                     "Example: ['sun','moon','lilith','vertex'].",
             },
         },
-        required: ["datetime", "latitude", "longitude"],
+        required: ["datetime"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
     annotations: {
@@ -169,9 +170,23 @@ registerTool({
         const client = getActiveClient();
         const houseSystem = args.house_system ?? "placidus";
         const datetime = String(args.datetime);
-        const lat = args.latitude;
-        const lon = args.longitude;
-        const natalBody = buildNatalBody(datetime, lat, lon, houseSystem, args.timezone);
+        const resolved = await coordsFromArgsOrLocation({
+            latitude: args.latitude,
+            longitude: args.longitude,
+            timezone: args.timezone,
+            location: args.location,
+        });
+        const lat = resolved.latitude;
+        const lon = resolved.longitude;
+        if (lat == null || lon == null) {
+            throw new Error("explore_natal_chart requires either `latitude` + `longitude` or a resolvable `location` name. " +
+                "The server tried to compute a chart with no coordinates and refused — a chart at 0°N 0°E is silently wrong.");
+        }
+        // A location resolved from the place name carries its own tz. The
+        // caller's explicit timezone still wins when supplied.
+        const effectiveTimezone = args.timezone ?? resolved.timezone;
+        const effectiveLocation = resolved.location ?? args.location;
+        const natalBody = buildNatalBody(datetime, lat, lon, houseSystem, effectiveTimezone);
         // Determine which bodies are requested
         const requestedBodies = args.bodies;
         const wantsAll = requestedBodies?.some(b => b.toLowerCase() === "all");
@@ -188,14 +203,14 @@ registerTool({
         // source of the ~90 second blocking delay.
         const chartData = await client.post("/ephemeris/natal-chart", natalBody);
         // Build human-readable summary for the LLM context
-        const summary = buildChartSummary(chartData, String(args.location ?? `${lat}, ${lon}`), houseSystem);
+        const summary = buildChartSummary(chartData, String(effectiveLocation ?? `${lat}, ${lon}`), houseSystem);
         // Build the UI payload (planets normalised to array, server aspects mapped)
         const modelPayload = buildModelPayload(chartData, {
             datetime,
-            timezone: args.timezone ?? null,
+            timezone: effectiveTimezone ?? null,
             latitude: lat ?? null,
             longitude: lon ?? null,
-            location: args.location ?? null,
+            location: effectiveLocation ?? null,
         }, houseSystem, undefined, requestedBodies);
         const bundleAvailable = Boolean(getChartWheelBundle());
         if (bundleAvailable) {

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

@@ -24,6 +24,7 @@ import { registerTool, validateRequired, validateCoordinates, SERVER_VERSION } f
 import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
 import { localToUtcIso } from "../datetime.js";
+import { coordsFromArgsOrLocation } from "./_location-resolver.js";
 // ── Constants ─────────────────────────────────────────────────────────────────
 export const VEDIC_CHART_RESOURCE_URI = "ui://openephemeris/vedic-chart";
 export const VEDIC_CHART_MIME_TYPE = "text/html;profile=mcp-app";
@@ -112,15 +113,15 @@ registerTool({
             },
             latitude: {
                 type: "number",
-                description: "Birth latitude in decimal degrees (positive = North). Resolve from a place name with location_search; never recall coordinates from memory.",
+                description: "Birth latitude in decimal degrees (positive = North). Optional if `location` is a place name — the resolver fills it in. Never recall coordinates from memory; either supply a place name or resolve with location_search first.",
             },
             longitude: {
                 type: "number",
-                description: "Birth longitude in decimal degrees (positive = East).",
+                description: "Birth longitude in decimal degrees (positive = East). Optional if `location` is a place name.",
             },
             location: {
                 type: "string",
-                description: "Location name for display only (e.g. 'Mumbai, India'). This is a caption, NOT a geocoder — it does not set the chart location. Supply latitude/longitude too (resolve them with location_search), or the chart is computed at 0N 0E.",
+                description: "Birth location. Prefer a plain place name like 'Mumbai, India' — the server resolves it via the same lookup `location_search` uses (unambiguous names → coords + timezone; ambiguous names throw with a disambiguation hint). Supplied coords always win.",
             },
             timezone: {
                 type: "string",
@@ -133,7 +134,7 @@ registerTool({
                 description: "Ayanamsa system for sidereal conversion. Defaults to 'lahiri'.",
             },
         },
-        required: ["datetime", "latitude", "longitude"],
+        required: ["datetime"],
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
     annotations: {
@@ -150,15 +151,25 @@ registerTool({
         },
     },
     handler: async (args) => {
-        validateRequired(args, ["datetime", "latitude", "longitude"]);
-        validateCoordinates(args, "latitude", "longitude");
+        validateRequired(args, ["datetime"]);
+        const resolved = await coordsFromArgsOrLocation({
+            latitude: args.latitude,
+            longitude: args.longitude,
+            timezone: args.timezone,
+            location: args.location,
+        });
+        if (resolved.latitude == null || resolved.longitude == null) {
+            throw new Error("explore_vedic_chart requires either `latitude` + `longitude` or a resolvable `location` name.");
+        }
+        const argsWithResolved = { ...args, latitude: resolved.latitude, longitude: resolved.longitude };
+        validateCoordinates(argsWithResolved, "latitude", "longitude");
         const client = getActiveClient();
-        const timezone = args.timezone;
+        const timezone = args.timezone ?? resolved.timezone;
         const datetime = localToUtcIso("datetime", String(args.datetime), timezone);
-        const lat = Number(args.latitude);
-        const lon = Number(args.longitude);
+        const lat = Number(resolved.latitude);
+        const lon = Number(resolved.longitude);
         const ayanamsa = args.ayanamsa;
-        const location = String(args.location ?? `${lat}, ${lon}`).slice(0, 120);
+        const location = String(resolved.location ?? args.location ?? `${lat}, ${lon}`).slice(0, 120);
         const bundleAvailable = Boolean(getVedicChartBundle());
         const theme = "dark"; // app shell default; iframe reconciles to host theme on load
         const body = {
@@ -175,7 +186,7 @@ registerTool({
         const chartData = await client.request("POST", "/vedic/chart", { data: body });
         const modelPayload = buildVedicModelPayload(chartData, {
             datetime,
-            location: args.location ?? null,
+            location: resolved.location ?? args.location ?? null,
             timezone: timezone ?? null,
             latitude: lat,
             longitude: lon,

package/dist/tools/specialized/natal.js

@@ -47,11 +47,11 @@ registerTool({
             },
             include_arabic_parts: {
                 type: "boolean",
-                description: "Reserved for future use. Hermetic Lots / Arabic Parts are currently available via the dedicated /ephemeris/hermetic-lots endpoint.",
+                description: "Include Hermetic Lots / Arabic Parts in the natal response (routed as `options.include_hermetic_lots: true`). For a standalone lots-only payload without a full natal chart, use `/ephemeris/hermetic-lots` instead.",
             },
             include_fixed_stars: {
                 type: "boolean",
-                description: "Reserved for future use. Fixed star positions are currently available via the dedicated /ephemeris/fixed-stars endpoint.",
+                description: "Include fixed-star positions in the natal response (routed as `configuration.fixed_star_options.include: true`). For a standalone fixed-stars payload without a full natal chart, use `/ephemeris/fixed-stars` instead.",
             },
             include_visual: {
                 type: "boolean",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openephemeris/mcp-server",
-  "version": "4.3.1",
+  "version": "4.4.0",
   "description": "Model Context Protocol server for the Open Ephemeris astronomical computation API",
   "type": "module",
   "main": "dist/index.js",