@openephemeris/mcp-server 3.1.0 → 3.2.0

package/dist/src/tools/dev.js

@@ -0,0 +1,187 @@
+import { registerTool } from "./index.js";
+import { backendClient } from "../backend/client.js";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+function getAllowlistPath() {
+    const envPath = process.env.OPENEPHEMERIS_DEV_ALLOWLIST_PATH || process.env.ASTROMCP_DEV_ALLOWLIST_PATH;
+    if (envPath && envPath.trim())
+        return envPath;
+    // dist lives at mcp-server/dist; src lives at mcp-server/src.
+    // We resolve relative to current file location for both dev+prod.
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    // here: .../dist/tools OR .../src/tools
+    const mcpServerRoot = path.resolve(here, "..", "..");
+    return path.join(mcpServerRoot, "config", "dev-allowlist.json");
+}
+function loadAllowlist() {
+    const allowlistPath = getAllowlistPath();
+    const raw = fs.readFileSync(allowlistPath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || parsed.schema !== "astromcp-dev-allowlist-v1" || !Array.isArray(parsed.allow)) {
+        throw new Error(`Invalid allowlist file at ${allowlistPath}. Expected schema astromcp-dev-allowlist-v1.`);
+    }
+    return parsed;
+}
+function isDeniedByPrefix(pathname, prefixes) {
+    return prefixes.some((p) => pathname.startsWith(p));
+}
+function isAllowedOperation(method, pathname, allow) {
+    return allow.some((e) => e.method === method && e.path === pathname);
+}
+registerTool({
+    name: "dev.call",
+    description: "Call any allowlisted Open Ephemeris API endpoint directly. This is the power-user escape hatch " +
+        "— use the typed tools (ephemeris.natal_chart, ephemeris.transits, etc.) first for common operations. " +
+        "Call dev.list_allowed to see all currently available endpoint paths.\n\n" +
+        "AUTH: Set OPENEPHEMERIS_API_KEY in your environment. See openephemeris.com/dashboard for active plan limits.\n\n" +
+        "CREDIT COSTS:\n" +
+        "  • Standard chart math (natal, progressed, bazi, HD): 1 credit\n" +
+        "  • Visualization rendering (chart-wheel, bi-wheel, charts/*): 2 credits\n" +
+        "  • Comparative math (synastry, composite, overlay): 3 credits\n" +
+        "  • Predictive ops (transits, returns, transit-chart): 5 credits\n" +
+        "  • ACG / astrocartography: 5 credits\n" +
+        "  • Catalog / metadata / health endpoints: 0 credits\n" +
+        "  • format=llm (token-optimized output): available on all tiers\n\n" +
+        "COMMON CALLS:\n" +
+        "  POST /ephemeris/natal-chart            — Full natal chart (body: {datetime, latitude, longitude})\n" +
+        "  POST /ephemeris/natal/batch            — Up to 50 natal charts in one request\n" +
+        "  POST /ephemeris/relocation             — Relocated chart (same natal, new location)\n" +
+        "  POST /predictive/transits/search       — Transit event search over a date range\n" +
+        "  POST /predictive/returns/solar         — Solar return chart\n" +
+        "  POST /predictive/returns/lunar         — Lunar return chart\n" +
+        "  POST /comparative/synastry             — Two-person synastry chart\n" +
+        "  POST /comparative/composite            — Composite (midpoint) chart\n" +
+        "  POST /human-design/chart               — Full HD bodygraph\n" +
+        "  GET  /ephemeris/moon/phase             — Current/queried moon phase\n" +
+        "  GET  /ephemeris/moon/void-of-course    — Next void-of-course period\n" +
+        "  GET  /ephemeris/agro/daily             — Biodynamic farming day quality\n" +
+        "  GET  /ephemeris/agro/calendar          — Multi-day biodynamic calendar\n" +
+        "  GET  /ephemeris/agro/void-of-course    — Biodynamic VoC periods\n" +
+        "  GET  /eclipse/solar/global             — Next global solar eclipse (query: date=YYYY-MM-DD)\n" +
+        "  GET  /eclipse/solar/local              — Local solar eclipse (query: latitude, longitude)\n" +
+        "  GET  /eclipse/next-visible             — Next eclipse visible from a location\n" +
+        "  GET  /tidal/forcing                    — Gravitational tidal forcing index\n" +
+        "  GET  /tidal/forcing/deep-time          — Extended tidal deep-time analysis\n" +
+        "  POST /acg/power-lines                 — Astrocartography power lines (lat/lon GeoJSON)\n" +
+        "  POST /acg/hits                         — ACG power at a specific location\n" +
+        "  GET  /calendar/astrology/moon-phases   — Moon phase calendar for a date range\n" +
+        "  GET  /location/autocomplete            — Geocode a place name (query: q=City Name)\n" +
+        "  POST /timezone/lookup                  — Resolve timezone + UTC offset for a location\n" +
+        "  POST /chinese/bazi                     — Chinese Ba Zi (Four Pillars) chart\n" +
+        "  GET  /chinese/zodiac                   — Chinese zodiac year element/animal\n" +
+        "  POST /vedic/chart                      — Vedic (Jyotish) natal chart\n" +
+        "  GET  /catalogs/bodies                  — List all supported celestial bodies\n\n" +
+        "BINARY RESPONSES:\n" +
+        "  • Binary/image endpoints return {content_type, content_length, encoding, data_base64}\n" +
+        "    so callers can decode bytes deterministically.\n\n" +
+        "ECLIPSE NOTE: Eclipse endpoints accept format=llm via the query param like other endpoints.\n\n" +
+        "format=llm NOTE: Add query: {format: 'llm'} to natal/synastry/composite/HD endpoints for " +
+        "compact columnar output optimized for LLM token budgets (availability depends on your current plan).",
+    inputSchema: {
+        type: "object",
+        properties: {
+            method: {
+                type: "string",
+                enum: ["GET", "POST", "PUT", "PATCH", "DELETE"],
+                description: "HTTP method",
+            },
+            path: {
+                type: "string",
+                description: "Absolute API path (e.g., /ephemeris/natal-chart)",
+            },
+            query: {
+                type: "object",
+                additionalProperties: true,
+                description: "Query params for GET requests (optional)",
+            },
+            body: {
+                description: "JSON body for POST/PUT/PATCH (optional)",
+            },
+            preset: {
+                type: "string",
+                enum: ["full", "simple"],
+                description: "Convenience: if provided, set query.preset (optional).",
+            },
+            format: {
+                type: "string",
+                enum: ["json", "llm", "llm_v2"],
+                description: "Convenience: if provided, set query.format (optional). 'llm' is canonical; 'llm_v2' is accepted as a legacy alias.",
+            },
+            output_mode: {
+                type: "string",
+                enum: ["full", "simple", "llm", "llm_v2"],
+                description: "Legacy convenience (deprecated): if provided, set query.output_mode and also map to query.preset/query.format when possible.",
+            },
+        },
+        required: ["method", "path"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        const method = String(args.method || "").toUpperCase();
+        const pathname = String(args.path || "");
+        if (!pathname.startsWith("/")) {
+            throw new Error("path must start with '/'");
+        }
+        const allowlist = loadAllowlist();
+        const denyPrefixes = allowlist.deny?.path_prefixes ?? [];
+        if (denyPrefixes.length > 0 && isDeniedByPrefix(pathname, denyPrefixes)) {
+            throw new Error(`Endpoint denied by policy: ${pathname}`);
+        }
+        if (!isAllowedOperation(method, pathname, allowlist.allow)) {
+            throw new Error(`Endpoint not allowlisted: ${method} ${pathname}`);
+        }
+        const queryBase = args.query && typeof args.query === "object" ? args.query : {};
+        const query = { ...queryBase };
+        const body = args.body;
+        if (args.preset) {
+            query.preset = args.preset;
+        }
+        if (args.format) {
+            const rawFormat = String(args.format).trim().toLowerCase();
+            // Canonical: "llm". Normalize legacy alias "llm_v2" → "llm".
+            query.format = rawFormat === "llm_v2" ? "llm" : rawFormat;
+        }
+        // Legacy: output_mode used to overload both compute preset and output projection.
+        // Keep forwarding it for older endpoints, but also map it to preset/format for new endpoints.
+        if (args.output_mode) {
+            const rawMode = String(args.output_mode).trim().toLowerCase();
+            query.output_mode = rawMode;
+            if ((rawMode === "full" || rawMode === "simple") && query.preset == null) {
+                query.preset = rawMode;
+            }
+            if ((rawMode === "llm" || rawMode === "llm_v2") && query.format == null) {
+                query.format = "llm";
+            }
+        }
+        return await backendClient.request(method, pathname, {
+            params: query,
+            data: body,
+        });
+    },
+});
+registerTool({
+    name: "dev.list_allowed",
+    description: "List all API operations (method + path) that this MCP instance is authorized to call. " +
+        "Returns endpoint entries grouped by method, plus the active deny rules. " +
+        "Use this to discover what's available before calling dev.call, or to verify an endpoint path. " +
+        "Typed shortcut tools (ephemeris.natal_chart, ephemeris.transits, etc.) cover the most common operations — " +
+        "check those first before reaching for dev.call.",
+    inputSchema: {
+        type: "object",
+        properties: {},
+        additionalProperties: false,
+    },
+    handler: async () => {
+        const allowlist = loadAllowlist();
+        return {
+            schema: allowlist.schema,
+            generated_from: allowlist.generated_from,
+            deny: allowlist.deny ?? null,
+            allow: allowlist.allow,
+            counts: {
+                allow: allowlist.allow.length,
+            },
+        };
+    },
+});

package/dist/src/tools/index.d.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: z.ZodType<any> | Record<string, unknown>;
+    annotations?: {
+        title?: string;
+        readOnlyHint?: boolean;
+        destructiveHint?: boolean;
+        idempotentHint?: boolean;
+        openWorldHint?: boolean;
+    };
+    handler: (args: any) => Promise<any>;
+}
+export declare const toolRegistry: Record<string, ToolDefinition>;
+export declare function registerTool(tool: ToolDefinition): void;
+export type ToolProfile = "dev" | "legacy";
+/**
+ * Initializes tool modules.
+ *
+ * - `dev`: registers the allowlist-gated generic call tools AND all specialized
+ *   domain tools (natal chart, transits, moon phase, eclipse, synastry, HD).
+ * - `legacy`: registers only the generic tools (back-compat).
+ */
+export declare function initTools(profile?: ToolProfile): Promise<void>;

package/dist/src/tools/index.js

@@ -0,0 +1,33 @@
+export const toolRegistry = {};
+export function registerTool(tool) {
+    toolRegistry[tool.name] = tool;
+}
+let toolsInitialized = false;
+/**
+ * Initializes tool modules.
+ *
+ * - `dev`: registers the allowlist-gated generic call tools AND all specialized
+ *   domain tools (natal chart, transits, moon phase, eclipse, synastry, HD).
+ * - `legacy`: registers only the generic tools (back-compat).
+ */
+export async function initTools(profile) {
+    if (toolsInitialized)
+        return;
+    toolsInitialized = true;
+    const resolvedProfile = (profile || process.env.OPENEPHEMERIS_PROFILE || process.env.ASTROMCP_PROFILE || "dev").toLowerCase();
+    // Always register auth tools (available in all profiles).
+    await import("./auth.js");
+    // Always register the generic proxy tools (dev.call + dev.list_allowed).
+    await import("./dev.js");
+    if (resolvedProfile === "dev") {
+        // Register all specialized domain tools.
+        await import("./specialized/natal.js");
+        await import("./specialized/transits.js");
+        await import("./specialized/moon.js");
+        await import("./specialized/eclipse.js");
+        await import("./specialized/human_design.js");
+        await import("./specialized/synastry.js");
+        await import("./specialized/relocation.js");
+        await import("./specialized/electional.js");
+    }
+}

package/dist/src/tools/specialized/eclipse.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/tools/specialized/eclipse.js

@@ -0,0 +1,56 @@
+import { registerTool } from "../index.js";
+import { backendClient } from "../../backend/client.js";
+registerTool({
+    name: "ephemeris.next_eclipse",
+    description: "Find the next solar or lunar eclipse visible from a given location (or globally). " +
+        "Returns the eclipse type, date/time of maximum, magnitude, duration of totality (if any), " +
+        "and local contact times if coordinates are provided.\n\n" +
+        "CREDIT COST: 1 credit per call.\n\n" +
+        "EXAMPLE: Find the next solar eclipse visible from New York:\n" +
+        "  eclipse_type='solar', latitude=40.7128, longitude=-74.006\n\n" +
+        "EXAMPLE: Find the next lunar eclipse globally:\n" +
+        "  eclipse_type='lunar'",
+    inputSchema: {
+        type: "object",
+        properties: {
+            eclipse_type: {
+                type: "string",
+                enum: ["solar", "lunar"],
+                description: "Eclipse type to search for.",
+            },
+            latitude: {
+                type: "number",
+                description: "Observer latitude in decimal degrees. If provided, returns local visibility and contact times.",
+            },
+            longitude: {
+                type: "number",
+                description: "Observer longitude in decimal degrees.",
+            },
+            after_date: {
+                type: "string",
+                description: "ISO 8601 date to search after (e.g. '2026-01-01'). Defaults to today if omitted.",
+            },
+        },
+        required: ["eclipse_type"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        const params = {};
+        if (args.latitude != null)
+            params.latitude = args.latitude;
+        if (args.longitude != null)
+            params.longitude = args.longitude;
+        if (args.after_date)
+            params.date = args.after_date;
+        if (args.eclipse_type === "solar") {
+            // Use local endpoint if coordinates provided, otherwise global
+            if (args.latitude != null && args.longitude != null) {
+                return await backendClient.request("GET", "/eclipse/solar/local", { params, timeoutMs: 60_000 });
+            }
+            return await backendClient.request("GET", "/eclipse/solar/global", { params, timeoutMs: 60_000 });
+        }
+        else {
+            return await backendClient.request("GET", "/eclipse/lunar/global", { params, timeoutMs: 60_000 });
+        }
+    },
+});

package/dist/src/tools/specialized/electional.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/tools/specialized/electional.js

@@ -0,0 +1,79 @@
+import { registerTool } from "../index.js";
+import { backendClient } from "../../backend/client.js";
+registerTool({
+    name: "ephemeris.electional",
+    description: "Find optimal planetary timing windows (electional astrology). Scans a date range to find the " +
+        "best times for an event based on essential dignity, aspect quality, sect, and void-of-course " +
+        "moon penalties. Evaluates every hour and clusters the best continuous windows.\n\n" +
+        "CREDIT COST: 5 credits per call (heavy calculation).\n\n" +
+        "EXAMPLE: Find the best time to launch a business in early March 2026.\n" +
+        "  start_date='2026-03-01', end_date='2026-03-10', latitude=40.7128, longitude=-74.0060,\n" +
+        "  avoid_voc=true, lunar_phase='waxing'",
+    inputSchema: {
+        type: "object",
+        properties: {
+            start_date: {
+                type: "string",
+                description: "ISO 8601 start date or datetime for the search window (e.g., 2026-03-01).",
+            },
+            end_date: {
+                type: "string",
+                description: "ISO 8601 end date or datetime for the search window.",
+            },
+            latitude: {
+                type: "number",
+                description: "Latitude of location in decimal degrees (positive = North).",
+            },
+            longitude: {
+                type: "number",
+                description: "Longitude of location in decimal degrees (positive = East).",
+            },
+            max_results: {
+                type: "number",
+                description: "Maximum number of top windows to return (default 5).",
+            },
+            avoid_retrograde: {
+                type: "string",
+                description: "Comma-separated list of planets to avoid when retrograde (e.g., 'mercury,venus').",
+            },
+            lunar_phase: {
+                type: "string",
+                enum: ["waxing", "waning", "new", "full", "any"],
+                description: "Filter windows by lunar phase. Defaults to 'any'.",
+            },
+            avoid_voc: {
+                type: "boolean",
+                description: "If true, strictly ignores any moments where the Moon is Void of Course.",
+            },
+            format: {
+                type: "string",
+                enum: ["json", "llm"],
+                description: "Output format. 'llm' = compact token-efficient output (available on all tiers).",
+            },
+        },
+        required: ["start_date", "end_date", "latitude", "longitude"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        const query = {
+            start_date: args.start_date,
+            end_date: args.end_date,
+            latitude: args.latitude,
+            longitude: args.longitude,
+        };
+        if (args.max_results !== undefined)
+            query.max_results = args.max_results;
+        if (args.avoid_retrograde)
+            query.avoid_retrograde = args.avoid_retrograde;
+        if (args.lunar_phase)
+            query.lunar_phase = args.lunar_phase;
+        if (args.avoid_voc !== undefined)
+            query.avoid_voc = args.avoid_voc;
+        if (args.format)
+            query.format = args.format;
+        return await backendClient.request("GET", "/electional/find-window", {
+            data: {},
+            params: query,
+        });
+    },
+});

package/dist/src/tools/specialized/human_design.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/tools/specialized/human_design.js

@@ -0,0 +1,53 @@
+import { registerTool } from "../index.js";
+import { backendClient } from "../../backend/client.js";
+registerTool({
+    name: "human_design.chart",
+    description: "Calculate a full Human Design bodygraph chart from birth data. Returns the person's Type " +
+        "(Generator, Manifesting Generator, Projector, Manifestor, Reflector), Strategy, Authority, " +
+        "Profile (e.g. 1/3, 2/4), defined and undefined Centers, activated Gates and Channels, " +
+        "Incarnation Cross, and both Personality (conscious) and Design (unconscious) planetary positions.\n\n" +
+        "CREDIT COST: 1 credit per call.\n\n" +
+        "Human Design uses two calculation moments: the birth time (Personality) and ~88° of Sun motion " +
+        "before birth (~3 months prior, the Design calculation). The API handles this automatically.\n\n" +
+        "EXAMPLE: Get the Human Design chart for someone born April 15, 1990 at 2:30 PM in Chicago:\n" +
+        "  datetime='1990-04-15T14:30:00', latitude=41.8781, longitude=-87.6298",
+    inputSchema: {
+        type: "object",
+        properties: {
+            datetime: {
+                type: "string",
+                description: "ISO 8601 birth datetime (local time at birth location), e.g. '1990-04-15T14:30:00'.",
+            },
+            latitude: {
+                type: "number",
+                description: "Latitude of birth location in decimal degrees (positive = North).",
+            },
+            longitude: {
+                type: "number",
+                description: "Longitude of birth location in decimal degrees (positive = East).",
+            },
+            format: {
+                type: "string",
+                enum: ["json", "llm"],
+                description: "Output format. 'llm' returns compact array projection for token efficiency (available on all tiers). " +
+                    "'json' returns verbose full output.",
+            },
+        },
+        required: ["datetime", "latitude", "longitude"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        const body = {
+            datetime: args.datetime,
+            latitude: args.latitude,
+            longitude: args.longitude,
+        };
+        const query = {};
+        if (args.format)
+            query.format = args.format;
+        return await backendClient.request("POST", "/human-design/chart", {
+            data: body,
+            params: query,
+        });
+    },
+});

package/dist/src/tools/specialized/moon.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/tools/specialized/moon.js

@@ -0,0 +1,50 @@
+import { registerTool } from "../index.js";
+import { backendClient } from "../../backend/client.js";
+registerTool({
+    name: "ephemeris.moon_phase",
+    description: "Get the current Moon phase and void-of-course status. Returns the Moon's sign, phase name " +
+        "(New, Waxing Crescent, First Quarter, Waxing Gibbous, Full, Waning Gibbous, Last Quarter, " +
+        "Waning Crescent), exact phase angle, illumination percentage, and the next void-of-course period.\n\n" +
+        "CREDIT COST: 1 credit per call.\n\n" +
+        "If no datetime is provided, returns the current (live) moon phase.\n\n" +
+        "EXAMPLE: Get moon phase for a specific date/time:\n" +
+        "  datetime='2026-03-20T12:00:00Z'\n\n" +
+        "EXAMPLE: Get the current moon phase right now:\n" +
+        "  (call with no arguments)",
+    inputSchema: {
+        type: "object",
+        properties: {
+            datetime: {
+                type: "string",
+                description: "ISO 8601 datetime to query. If omitted, returns the current live moon phase (UTC now).",
+            },
+            latitude: {
+                type: "number",
+                description: "Observer latitude (optional, used for local void-of-course calculations).",
+            },
+            longitude: {
+                type: "number",
+                description: "Observer longitude (optional, used for local void-of-course calculations).",
+            },
+        },
+        required: [],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        const params = {};
+        if (args.datetime)
+            params.datetime = args.datetime;
+        if (args.latitude != null)
+            params.latitude = args.latitude;
+        if (args.longitude != null)
+            params.longitude = args.longitude;
+        const [phase, voc] = await Promise.allSettled([
+            backendClient.request("GET", "/ephemeris/moon/phase", { params }),
+            backendClient.request("GET", "/ephemeris/moon/void-of-course", { params }),
+        ]);
+        return {
+            phase: phase.status === "fulfilled" ? phase.value : { error: phase.reason?.message },
+            void_of_course: voc.status === "fulfilled" ? voc.value : { error: voc.reason?.message },
+        };
+    },
+});

package/dist/src/tools/specialized/natal.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/tools/specialized/natal.js

@@ -0,0 +1,71 @@
+import { registerTool } from "../index.js";
+import { backendClient } from "../../backend/client.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'.";
+registerTool({
+    name: "ephemeris.natal_chart",
+    description: "Calculate a full natal (birth) chart for a person. Returns planetary positions, house cusps, " +
+        "aspects, and chart patterns. Use format='llm' for a compact, token-efficient output ideal for " +
+        "interpretation (available on all tiers). The result includes all major planets, angles (ASC/MC/DSC/IC), " +
+        "essential dignities, retrograde status, house system data, and major aspect grid.\n\n" +
+        "CREDIT COST: 1 credit per call.\n\n" +
+        "EXAMPLE: Calculate the natal chart for someone born April 15, 1990 at 2:30 PM in Chicago:\n" +
+        "  datetime='1990-04-15T14:30:00', latitude=41.8781, longitude=-87.6298",
+    inputSchema: {
+        type: "object",
+        properties: {
+            datetime: {
+                type: "string",
+                description: DATETIME_DESC,
+            },
+            latitude: {
+                type: "number",
+                description: "Geographic latitude of birth location in decimal degrees (positive = North).",
+            },
+            longitude: {
+                type: "number",
+                description: "Geographic longitude of birth location in decimal degrees (positive = East).",
+            },
+            house_system: {
+                type: "string",
+                enum: ["placidus", "whole_sign", "equal", "koch", "campanus", "regiomontanus", "porphyry", "alcabitius", "morinus"],
+                description: "House system to use. Defaults to 'placidus' if omitted.",
+            },
+            format: {
+                type: "string",
+                enum: ["json", "llm"],
+                description: "Output format. 'llm' returns a compact array-based projection optimized for LLM token efficiency (available on all tiers). 'json' returns full verbose JSON.",
+            },
+            include_arabic_parts: {
+                type: "boolean",
+                description: "If true, include Hermetic Lots (Arabic Parts) in the response.",
+            },
+            include_fixed_stars: {
+                type: "boolean",
+                description: "If true, include fixed star conjunctions in the response.",
+            },
+        },
+        required: ["datetime", "latitude", "longitude"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        const body = {
+            datetime: args.datetime,
+            latitude: args.latitude,
+            longitude: args.longitude,
+        };
+        if (args.house_system)
+            body.house_system = args.house_system;
+        if (args.include_arabic_parts)
+            body.include_arabic_parts = args.include_arabic_parts;
+        if (args.include_fixed_stars)
+            body.include_fixed_stars = args.include_fixed_stars;
+        const query = {};
+        if (args.format)
+            query.format = args.format;
+        return await backendClient.request("POST", "/ephemeris/natal-chart", {
+            data: body,
+            params: query,
+        });
+    },
+});

package/dist/src/tools/specialized/relocation.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/tools/specialized/relocation.js

@@ -0,0 +1,71 @@
+import { registerTool } from "../index.js";
+import { backendClient } from "../../backend/client.js";
+registerTool({
+    name: "ephemeris.relocation",
+    description: "Calculate a relocation chart — the same natal planetary positions re-cast for a different " +
+        "geographic location. Used to understand how living in a different city shifts house placements " +
+        "and angles, without changing the planetary longitudes in the chart.\n\n" +
+        "CREDIT COST: 1 credit per call.\n\n" +
+        "EXAMPLE: How does moving from Chicago to London change someone's chart?\n" +
+        "  natal_datetime='1990-04-15T14:30:00', natal_latitude=41.8781, natal_longitude=-87.6298,\n" +
+        "  relocation_latitude=51.5074, relocation_longitude=-0.1278",
+    inputSchema: {
+        type: "object",
+        properties: {
+            natal_datetime: {
+                type: "string",
+                description: "ISO 8601 birth datetime (local time at birth location).",
+            },
+            natal_latitude: {
+                type: "number",
+                description: "Latitude of birth location in decimal degrees.",
+            },
+            natal_longitude: {
+                type: "number",
+                description: "Longitude of birth location in decimal degrees.",
+            },
+            relocation_latitude: {
+                type: "number",
+                description: "Latitude of the relocation city in decimal degrees (positive = North).",
+            },
+            relocation_longitude: {
+                type: "number",
+                description: "Longitude of the relocation city in decimal degrees (positive = East).",
+            },
+            house_system: {
+                type: "string",
+                enum: ["placidus", "whole_sign", "equal", "koch", "campanus", "regiomontanus", "porphyry"],
+                description: "House system to use. Defaults to 'placidus'.",
+            },
+            format: {
+                type: "string",
+                enum: ["json", "llm"],
+                description: "Output format. 'llm' = compact token-efficient output (available on all tiers).",
+            },
+        },
+        required: ["natal_datetime", "natal_latitude", "natal_longitude", "relocation_latitude", "relocation_longitude"],
+        additionalProperties: false,
+    },
+    handler: async (args) => {
+        const body = {
+            natal: {
+                datetime: args.natal_datetime,
+                latitude: args.natal_latitude,
+                longitude: args.natal_longitude,
+            },
+            relocation: {
+                latitude: args.relocation_latitude,
+                longitude: args.relocation_longitude,
+            },
+        };
+        if (args.house_system)
+            body.house_system = args.house_system;
+        const query = {};
+        if (args.format)
+            query.format = args.format;
+        return await backendClient.request("POST", "/ephemeris/relocation", {
+            data: body,
+            params: query,
+        });
+    },
+});

package/dist/src/tools/specialized/synastry.d.ts

@@ -0,0 +1 @@
+export {};