@openephemeris/mcp-server 3.14.0 → 3.16.0

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

@@ -1,11 +1,15 @@
 /**
  * bodygraph-app.ts — MCP App tool registration for the Human Design Bodygraph Explorer.
  *
- * Registers 4 tools:
- *   • explore_human_design      — primary entry point, returns data + UI resource [model]
- *   • hd_on_center_click        — center click handler [app-only]
- *   • hd_on_gate_click          — gate click handler [app-only]
- *   • hd_on_channel_click       — channel click handler [app-only]
+ * Entry tools [model + app]:
+ *   • explore_human_design             — natal bodygraph, data + UI resource
+ *   • explore_human_design_transit     — natal + transit overlay (premium)
+ *   • explore_human_design_connection  — two-person connection/synastry overlay (premium)
+ * Click handlers [app-only]: hd_on_center_click, hd_on_gate_click,
+ *   hd_on_channel_click, hd_on_planet_click, hd_on_variable_click.
+ * The transit + connection tools reuse this bodygraph iframe resource; their
+ * overlay SVG is returned inline by /human-design/transit-chart and
+ * /human-design/composite (include_visual) rather than a separate render call.
  *
  * The bodygraph is rendered client-side from structured JSON — no SVG endpoint
  * is called, keeping latency at zero and the architecture consistent with
@@ -78,13 +82,18 @@ function ensureTimezone(dt) {
  * renderer in bodygraph-renderer.ts. Non-fatal: a missing SVG should never
  * block the tool result.
  */
-async function fetchGoBodygraphSVG(body) {
+async function fetchGoBodygraphSVG(body, theme = "dark") {
     try {
         const client = getActiveClient();
         // /visualization/bodygraph is registered as binary in BINARY_ENDPOINT_PREFIXES.
         // The client wraps it as { content_type, encoding: "base64", data_base64 } —
         // we decode back to UTF-8 SVG text for inlining.
-        const resp = await client.post("/visualization/bodygraph?format=svg&size=800", body);
+        //
+        // style=light|dark drives the Go renderer's palette. The endpoint defaults
+        // to "light" when style is omitted, which mismatches dark MCP hosts — so we
+        // always pass an explicit theme (default "dark" to match the app shell; the
+        // iframe re-fetches with the host-detected theme on load / theme change).
+        const resp = await client.post(`/visualization/bodygraph?format=svg&size=800&style=${theme}`, body);
         if (typeof resp === "string")
             return resp;
         if (resp && typeof resp === "object") {
@@ -438,11 +447,16 @@ registerTool({
             modelPayload._svg = svg;
         const summary = buildHdSummary(modelPayload, location);
         if (bundleAvailable) {
+            // MCP Apps wire format: the UI is declared via `_meta.ui.resourceUri` and
+            // delivered through resources/read — NOT as a content block. A URI-only
+            // `type: "resource"` block lacks the inline text/blob the base MCP schema
+            // requires and fails strict client validation. structuredContent carries
+            // the data for non-rendering hosts.
             return {
                 content: [
                     { type: "text", text: summary },
-                    { type: "text", text: JSON.stringify({ ...modelPayload, server_version: SERVER_VERSION }) },
                 ],
+                structuredContent: { ...modelPayload, server_version: SERVER_VERSION },
                 _meta: {
                     "ui/resourceUri": BODYGRAPH_RESOURCE_URI,
                     ui: { resourceUri: BODYGRAPH_RESOURCE_URI },
@@ -468,6 +482,11 @@ registerTool({
                 type: "string",
                 description: "IANA timezone name (e.g. 'America/New_York') for accurate UTC conversion.",
             },
+            theme: {
+                type: "string",
+                enum: ["light", "dark"],
+                description: "Render palette for the bodygraph SVG. Mirrors the MCP host's light/dark color scheme.",
+            },
         },
         required: ["datetime"],
     },
@@ -481,6 +500,7 @@ registerTool({
         const datetime = localToUtcIso(String(args.datetime), timezone);
         const lat = args.latitude;
         const lon = args.longitude;
+        const theme = args.theme === "light" ? "light" : "dark";
         const body = {
             birth_datetime_utc: datetime,
         };
@@ -493,7 +513,7 @@ registerTool({
             client.request("POST", "/human-design/chart", {
                 data: body,
             }),
-            fetchGoBodygraphSVG(body),
+            fetchGoBodygraphSVG(body, theme),
         ]);
         const chart = chartData.chart ?? chartData;
         const modelPayload = buildHdModelPayload(chart, {
@@ -1157,3 +1177,181 @@ registerTool({
         };
     },
 });
+// ── Tool: explore_human_design_transit ───────────────────────────────────────
+// Personalized Human Design transit overlay (natal chart + a transiting moment).
+// Premium (Developer tier). Calls POST /human-design/transit-chart.
+registerTool({
+    name: "explore_human_design_transit",
+    description: "Overlay the current (or a chosen) planetary transit on a person's natal Human Design bodygraph. " +
+        "Highlights the channels a transit temporarily COMPLETES with the natal chart and any centers it " +
+        "newly defines — the core of a Human Design transit reading. " +
+        "Returns an interactive overlay bodygraph in MCP Apps-capable hosts (Claude Desktop), with a text " +
+        "summary fallback elsewhere. Premium (Developer tier). Calculated with NASA JPL DE440 ephemerides.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            datetime: {
+                type: "string",
+                description: "Natal birth datetime, ISO 8601 (e.g. '1990-04-15T19:30:00Z'). Include 'Z' or an offset, " +
+                    "or supply timezone for local time. HD is time-sensitive to the minute.",
+            },
+            latitude: { type: "number", description: "Natal birth latitude (decimal degrees, +N). Optional." },
+            longitude: { type: "number", description: "Natal birth longitude (decimal degrees, +E). Optional." },
+            location: { type: "string", description: "Natal location name, display only." },
+            timezone: { type: "string", description: "IANA timezone for the birth location (e.g. 'America/New_York')." },
+            transit_datetime: {
+                type: "string",
+                description: "Transit moment, ISO 8601. Defaults to now (UTC) when omitted.",
+            },
+        },
+        required: ["datetime"],
+    },
+    outputSchema: OUTPUT_SCHEMA_JSON,
+    annotations: {
+        title: "Human Design Transit Overlay",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+    },
+    _meta: { ui: { resourceUri: BODYGRAPH_RESOURCE_URI, visibility: ["model", "app"] } },
+    handler: async (args) => {
+        const client = getActiveClient();
+        const timezone = args.timezone;
+        const natalIso = localToUtcIso(String(args.datetime), timezone);
+        const lat = args.latitude ?? 0;
+        const lon = args.longitude ?? 0;
+        // SubjectRequest wire shape: name (required), birth_datetime.iso, and
+        // birth_location with struct-typed coordinate/timezone inputs (matches the
+        // live bi-wheel/transit-timeline tools — bare scalars are rejected).
+        const body = {
+            subject: {
+                name: args.location ?? "Subject",
+                birth_datetime: { iso: natalIso },
+                birth_location: {
+                    latitude: { decimal: lat },
+                    longitude: { decimal: lon },
+                    ...(timezone ? { timezone: { iana_name: timezone } } : {}),
+                },
+            },
+        };
+        if (args.transit_datetime) {
+            body.transit_datetime = { iso: ensureTimezone(String(args.transit_datetime)) };
+        }
+        const bundleAvailable = Boolean(getBodygraphBundle());
+        if (bundleAvailable)
+            body.include_visual = true;
+        const resp = await client.request("POST", "/human-design/transit-chart", { data: body });
+        const transit = (resp?.transit ?? {});
+        const completed = Array.isArray(transit.completed_channels) ? transit.completed_channels : [];
+        const newCenters = Array.isArray(transit.newly_defined_centers) ? transit.newly_defined_centers : [];
+        const natal = (resp?.natal ?? {});
+        const svg = resp?.visual?.data;
+        const summary = `**Human Design Transit Overlay**\n\n` +
+            `Natal: ${natal.type ?? "—"} ${natal.profile ?? ""} · ${natal.authority ?? ""} authority.\n\n` +
+            (completed.length
+                ? `The transit **completes ${completed.length} channel${completed.length === 1 ? "" : "s"}**: ${completed.join(", ")}.`
+                : `The transit completes no channels right now.`) +
+            (newCenters.length
+                ? `\n\nNewly-defined center${newCenters.length === 1 ? "" : "s"}: **${newCenters.join(", ")}** — a temporary shift while the transit holds.`
+                : "");
+        const payload = { ...resp, _svg: svg, server_version: SERVER_VERSION };
+        if (bundleAvailable && svg) {
+            return {
+                content: [{ type: "text", text: summary }],
+                structuredContent: payload,
+                _meta: { "ui/resourceUri": BODYGRAPH_RESOURCE_URI, ui: { resourceUri: BODYGRAPH_RESOURCE_URI } },
+            };
+        }
+        return { content: [{ type: "text", text: summary }], structuredContent: payload };
+    },
+});
+// ── Tool: explore_human_design_connection ────────────────────────────────────
+// Two-person Human Design connection (synastry) overlay. Premium (Developer tier).
+// Calls POST /human-design/composite.
+registerTool({
+    name: "explore_human_design_connection",
+    description: "Compare two people's Human Design charts and classify every connected channel by HD connection " +
+        "theory — electromagnetic (attraction), companionship (sameness), dominance (one defines), and " +
+        "compromise (friction). Returns an interactive two-person overlay bodygraph in MCP Apps-capable " +
+        "hosts, with a text summary fallback elsewhere. Premium (Developer tier). NASA JPL DE440 ephemerides.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            person_a: {
+                type: "object",
+                description: "First person's birth data.",
+                properties: {
+                    datetime: { type: "string", description: "Birth datetime, ISO 8601 (Z/offset, or local with timezone)." },
+                    latitude: { type: "number", description: "Birth latitude (decimal degrees, +N). Optional." },
+                    longitude: { type: "number", description: "Birth longitude (decimal degrees, +E). Optional." },
+                    timezone: { type: "string", description: "IANA timezone (e.g. 'America/New_York')." },
+                },
+                required: ["datetime"],
+            },
+            person_b: {
+                type: "object",
+                description: "Second person's birth data.",
+                properties: {
+                    datetime: { type: "string", description: "Birth datetime, ISO 8601 (Z/offset, or local with timezone)." },
+                    latitude: { type: "number", description: "Birth latitude (decimal degrees, +N). Optional." },
+                    longitude: { type: "number", description: "Birth longitude (decimal degrees, +E). Optional." },
+                    timezone: { type: "string", description: "IANA timezone (e.g. 'America/New_York')." },
+                },
+                required: ["datetime"],
+            },
+        },
+        required: ["person_a", "person_b"],
+    },
+    outputSchema: OUTPUT_SCHEMA_JSON,
+    annotations: {
+        title: "Human Design Connection (Synastry)",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+    _meta: { ui: { resourceUri: BODYGRAPH_RESOURCE_URI, visibility: ["model", "app"] } },
+    handler: async (args) => {
+        const client = getActiveClient();
+        const toSubject = (p) => {
+            const tz = p?.timezone;
+            return {
+                birth_datetime_utc: localToUtcIso(String(p?.datetime), tz),
+                latitude: p?.latitude ?? 0,
+                longitude: p?.longitude ?? 0,
+            };
+        };
+        const body = {
+            subject_1: toSubject(args.person_a),
+            subject_2: toSubject(args.person_b),
+        };
+        const bundleAvailable = Boolean(getBodygraphBundle());
+        if (bundleAvailable)
+            body.include_visual = true;
+        const resp = await client.request("POST", "/human-design/composite", { data: body });
+        const connections = Array.isArray(resp?.connections) ? resp.connections : [];
+        const svg = resp?.visual?.data;
+        const byType = (t) => connections.filter((c) => c?.type === t).map((c) => c.id);
+        const line = (label, t) => {
+            const ids = byType(t);
+            return ids.length ? `\n- **${label}** (${ids.length}): ${ids.join(", ")}` : "";
+        };
+        const summary = `**Human Design Connection**\n\n` +
+            `${connections.length} connected channel${connections.length === 1 ? "" : "s"}:` +
+            line("Electromagnetic — attraction", "electromagnetic") +
+            line("Companionship — sameness", "companionship") +
+            line("Dominance — one defines", "dominance") +
+            line("Compromise — friction", "compromise") +
+            (connections.length ? "" : " none.");
+        const payload = { ...resp, _svg: svg, server_version: SERVER_VERSION };
+        if (bundleAvailable && svg) {
+            return {
+                content: [{ type: "text", text: summary }],
+                structuredContent: payload,
+                _meta: { "ui/resourceUri": BODYGRAPH_RESOURCE_URI, ui: { resourceUri: BODYGRAPH_RESOURCE_URI } },
+            };
+        }
+        return { content: [{ type: "text", text: summary }], structuredContent: payload };
+    },
+});

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

@@ -199,11 +199,17 @@ registerTool({
         }, houseSystem, undefined, requestedBodies);
         const bundleAvailable = Boolean(getChartWheelBundle());
         if (bundleAvailable) {
+            // MCP Apps wire format: the UI is declared via `_meta.ui.resourceUri` and
+            // delivered through resources/read — NOT as a content block. A URI-only
+            // `type: "resource"` block lacks the inline text/blob the base MCP schema
+            // requires and fails strict client validation. Keep `structuredContent`
+            // so non-rendering hosts still get the data, and a text summary so chat
+            // transcripts read coherently.
             return {
                 content: [
                     { type: "text", text: summary },
-                    { type: "text", text: JSON.stringify({ ...modelPayload, server_version: SERVER_VERSION }) },
                 ],
+                structuredContent: { ...modelPayload, server_version: SERVER_VERSION },
                 _meta: {
                     "ui/resourceUri": CHART_WHEEL_RESOURCE_URI,
                     ui: { resourceUri: CHART_WHEEL_RESOURCE_URI },
@@ -414,8 +420,26 @@ function zodSignFromLon(lon) {
 const CLASSICAL_PLANETS = new Set([
     "sun", "moon", "mercury", "venus", "mars",
     "jupiter", "saturn", "uranus", "neptune", "pluto",
-    "chiron", "north_node", "south_node", "true_node", "asc", "mc",
+    // Nodes use space form to match the renderer's glyph table (chart-renderer.ts).
+    "chiron", "north node", "south node", "true node", "asc", "mc",
 ]);
+/**
+ * Canonicalise the Go backend's verbose node keys ("North Node (Mean)" /
+ * "North Node (True)") to the space-form names the renderer expects, keeping
+ * mean vs true DISTINCT. Without this the natal wheel dropped the nodes entirely
+ * (the raw key never matched the classical-planet set). All other body names are
+ * returned lowercased and otherwise unchanged.
+ */
+function canonicalizeBodyName(raw) {
+    const lower = raw.toLowerCase().trim();
+    if (lower === "north node (true)" || lower === "true node")
+        return "true node";
+    if (lower === "north node (mean)" || lower === "mean node" || lower === "north node")
+        return "north node";
+    if (lower === "south node (mean)" || lower === "south node (true)" || lower === "south node")
+        return "south node";
+    return lower;
+}
 const EXTENDED_BODIES = new Set([
     "mean_lilith", "lilith", "true_lilith",
     "ceres", "juno", "vesta", "pallas", "pholus",
@@ -487,19 +511,19 @@ function buildModelPayload(chartData, birthParams, houseSystem, svgBase, bodyFil
     if (rawPlanets && typeof rawPlanets === "object" && !Array.isArray(rawPlanets)) {
         planetsArray = Object.entries(rawPlanets)
             .filter(([k]) => {
-            const key = k.toLowerCase();
+            const key = canonicalizeBodyName(k);
             // If specific bodies were requested, use that filter
             if (bodyFilter) {
                 const wantsAll = bodyFilter.some(b => b.toLowerCase() === "all");
                 if (wantsAll)
                     return ALL_KNOWN_BODIES.has(key);
-                return bodyFilter.some(b => b.toLowerCase() === key);
+                return bodyFilter.some(b => canonicalizeBodyName(b) === key);
             }
             // Default: classical planets only
             return CLASSICAL_PLANETS.has(key);
         })
             .map(([name, p]) => ({
-            name: name.toLowerCase(),
+            name: canonicalizeBodyName(name),
             longitude: (p.longitude ?? p.lon ?? 0),
             latitude: (p.latitude ?? p.lat),
             speed: (p.longitude_speed ?? p.speed),

package/dist/tools/apps/location-tools.js

@@ -3,13 +3,29 @@ import { getActiveClient } from "../../backend/client.js";
 import { OUTPUT_SCHEMA_JSON } from "../output-schemas.js";
 registerTool({
     name: "location_search",
-    description: "App-only tool for getting location autocomplete suggestions. Returns latitude, longitude, and IANA timezone.",
+    description: "App-only tool for getting location autocomplete suggestions. Returns display name, region (state/province), latitude, longitude, and IANA timezone. Optional bias params (country/region/near) improve ranking; a trailing \"City, ST\" qualifier in the query is also honored.",
     inputSchema: {
         type: "object",
         properties: {
             query: {
                 type: "string",
-                description: "Search query for location, e.g. 'Los Angeles'",
+                description: "Search query for location, e.g. 'Los Angeles' or 'Wakefield, MI'",
+            },
+            country: {
+                type: "string",
+                description: "Optional ISO 3166-1 alpha-2 country code (e.g. 'US') to bias ranking. Boost, not filter.",
+            },
+            region: {
+                type: "string",
+                description: "Optional admin1 (state/province) qualifier to bias ranking — full name ('Michigan'), ASCII name, or code ('MI'). Boost, not filter.",
+            },
+            admin1: {
+                type: "string",
+                description: "Alias for region (region wins if both supplied).",
+            },
+            near: {
+                type: "string",
+                description: "Optional 'lat,lon' proximity hint (e.g. '37.77,-122.42') to bias ranking toward nearby places.",
             },
         },
         required: ["query"],
@@ -23,9 +39,26 @@ registerTool({
     },
     handler: async (args) => {
         validateRequired(args, ["query"]);
-        return await getActiveClient().request("GET", "/location/autocomplete", {
-            params: { q: args.query },
-        });
+        // NB: the endpoint param is `query` (only /geocode/search reads `q`).
+        const params = { query: args.query };
+        for (const k of ["country", "region", "admin1", "near"]) {
+            if (args[k] != null && String(args[k]).trim() !== "")
+                params[k] = String(args[k]);
+        }
+        const raw = (await getActiveClient().request("GET", "/location/autocomplete", { params }));
+        // Map the API's snake_case response to the camelCase shape the app UI consumes.
+        const list = Array.isArray(raw?.suggestions) ? raw.suggestions : [];
+        const suggestions = list.map((s) => ({
+            displayName: s.display_name,
+            shortName: s.short_name,
+            region: s.region,
+            countryCode: s.country_code,
+            placeId: s.place_id,
+            latitude: s.latitude,
+            longitude: s.longitude,
+            timezone: s.timezone,
+        }));
+        return { suggestions };
     },
 });
 registerTool({

package/dist/tools/apps/moon-phase-app.js

@@ -227,11 +227,17 @@ registerTool({
         const summary = buildMoonSummary(mergedData);
         const bundleAvailable = Boolean(getMoonPhaseBundle());
         if (bundleAvailable) {
+            // MCP Apps wire format: the UI is declared via `_meta.ui.resourceUri` and
+            // delivered through resources/read — NOT as a content block. An embedded
+            // `type: "resource"` block must carry inline text/blob per the base MCP
+            // schema, so a URI-only reference fails strict client validation; the
+            // _meta keys below are what the host uses to render the iframe.
+            // structuredContent carries the data payload for non-rendering hosts.
             return {
                 content: [
                     { type: "text", text: summary },
-                    { type: "text", text: JSON.stringify(uiPayload) },
                 ],
+                structuredContent: uiPayload,
                 _meta: {
                     "ui/resourceUri": MOON_PHASE_RESOURCE_URI,
                     ui: { resourceUri: MOON_PHASE_RESOURCE_URI },

package/dist/tools/dev.js

@@ -32,66 +32,72 @@ function isDeniedByPrefix(pathname, prefixes) {
 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, vedic, iching): 1 credit\n" +
-        "  • Human Design: 2 credits\n" +
-        "  • Visualization rendering (chart-wheel, bi-wheel, charts/*): 2 credits\n" +
-        "  • Comparative math (synastry, composite, overlay): 3 credits\n" +
-        "  • Predictive ops (transits/search, returns): 5 credits\n" +
-        "  • Predictive transit-chart: 1 credit\n" +
-        "  • ACG / astrocartography: 10 credits (acg/hits: 15 credits)\n" +
-        "  • Calendar endpoints: 10 credits\n" +
-        "  • Catalog / metadata / health endpoints: 0 credits\n" +
-        "  • Compute surcharge: requests > 30s add 1 credit per 30s (predictive, acg, calendar, electional)\n" +
-        "  • format=llm (token-optimized output): available on all tiers\n\n" +
-        "COMMON CALLS:\n" +
-        "  POST /ephemeris/natal-chart            — Full natal chart (body: {subject: {name: 'Name', birth_datetime: {iso: '1990-04-15T14:30:00-05:00'}, birth_location: {latitude: {decimal: 40.0}, longitude: {decimal: -70.0}, timezone: {}}}})\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 chart (body: {birth_datetime_utc: '1990-04-15T19:30:00Z'}) — lat/lon optional\n" +
-        "  POST /time/julian-day                  — Convert date to JD (body: {year: 1987, month: 7, day: 15, hour: 14, minute: 1})\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/next-visible             — Next eclipse visible from a location (query: lat, lon, type=solar|lunar)\n" +
-        "  GET  /eclipse/solar/global             — Next global solar eclipse (query: date=YYYY-MM-DD)\n" +
-        "  GET  /eclipse/solar/local              — Local solar eclipse (query: lat, lon)\n" +
-        "  GET  /tidal/forcing                    — Gravitational tidal forcing index\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 (body: {year, month, day, hour})\n" +
-        "  GET  /chinese/zodiac                   — Chinese zodiac year element/animal\n" +
-        "  POST /vedic/chart                      — Vedic (Jyotish) natal chart (body: {datetime_utc, latitude, longitude})\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: {
+// Shared reference block appended to both read/write proxy tools. Names the
+// target API (Open Ephemeris) explicitly — required by the directory for
+// freeform-path tools — plus credit costs and common calls.
+const DEV_API_REFERENCE = "Target API: Open Ephemeris REST API (https://api.openephemeris.com). " +
+    "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, vedic, iching): 1 credit\n" +
+    "  • Human Design: 2 credits\n" +
+    "  • Visualization rendering (chart-wheel, bi-wheel, charts/*): 2 credits\n" +
+    "  • Comparative math (synastry, composite, overlay): 3 credits\n" +
+    "  • Predictive ops (transits/search, returns): 5 credits\n" +
+    "  • Predictive transit-chart: 1 credit\n" +
+    "  • ACG / astrocartography: 10 credits (acg/hits: 15 credits)\n" +
+    "  • Calendar endpoints: 10 credits\n" +
+    "  • Catalog / metadata / health endpoints: 0 credits\n" +
+    "  • Compute surcharge: requests > 30s add 1 credit per 30s (predictive, acg, calendar, electional)\n" +
+    "  • format=llm (token-optimized output): available on all tiers\n\n" +
+    "COMMON CALLS:\n" +
+    "  POST /ephemeris/natal-chart            — Full natal chart (body: {subject: {name: 'Name', birth_datetime: {iso: '1990-04-15T14:30:00-05:00'}, birth_location: {latitude: {decimal: 40.0}, longitude: {decimal: -70.0}, timezone: {}}}})\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 chart (body: {birth_datetime_utc: '1990-04-15T19:30:00Z'}) — lat/lon optional\n" +
+    "  POST /time/julian-day                  — Convert date to JD (body: {year: 1987, month: 7, day: 15, hour: 14, minute: 1})\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/next-visible             — Next eclipse visible from a location (query: lat, lon, type=solar|lunar)\n" +
+    "  GET  /eclipse/solar/global             — Next global solar eclipse (query: date=YYYY-MM-DD)\n" +
+    "  GET  /eclipse/solar/local              — Local solar eclipse (query: lat, lon)\n" +
+    "  GET  /tidal/forcing                    — Gravitational tidal forcing index\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 (body: {year, month, day, hour})\n" +
+    "  GET  /chinese/zodiac                   — Chinese zodiac year element/animal\n" +
+    "  POST /vedic/chart                      — Vedic (Jyotish) natal chart (body: {datetime_utc, latitude, longitude})\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).";
+// The read and write proxies are kept as separate tools (not one method-switching
+// tool) so that safe GET reads never share a surface with state-changing writes —
+// a hard requirement of the Anthropic connector directory.
+const READ_METHODS = ["GET"];
+const WRITE_METHODS = ["POST", "PUT", "PATCH", "DELETE"];
+function makeProxyInputSchema(methods) {
+    return {
         type: "object",
         properties: {
             method: {
                 type: "string",
-                enum: ["GET", "POST", "PUT", "PATCH", "DELETE"],
-                description: "HTTP method",
+                enum: methods,
+                description: methods.length === 1 ? `HTTP method (always ${methods[0]})` : "HTTP method",
             },
             path: {
                 type: "string",
@@ -100,10 +106,10 @@ registerTool({
             query: {
                 type: "object",
                 additionalProperties: true,
-                description: "Query params for GET requests (optional)",
+                description: "Query params (optional)",
             },
             body: {
-                description: "JSON body for POST/PUT/PATCH (optional)",
+                description: "JSON request body (optional)",
             },
             preset: {
                 type: "string",
@@ -121,15 +127,16 @@ registerTool({
                 description: "Legacy convenience (deprecated): if provided, set query.output_mode and also map to query.preset/query.format when possible.",
             },
         },
-        required: ["method", "path"],
+        required: ["path"],
         additionalProperties: false,
-    },
-    outputSchema: OUTPUT_SCHEMA_JSON,
-    handler: async (args) => {
+    };
+}
+function makeProxyHandler(allowedMethods, defaultMethod) {
+    return async (args) => {
         validateRequired(args, ["path"]);
-        const methodStr = String(args.method || "GET").toUpperCase();
-        if (!["GET", "POST", "PUT", "PATCH", "DELETE"].includes(methodStr)) {
-            throw new Error(`Invalid HTTP method: ${methodStr}`);
+        const methodStr = String(args.method || defaultMethod).toUpperCase();
+        if (!allowedMethods.includes(methodStr)) {
+            throw new Error(`Method ${methodStr} not permitted by this tool. Allowed: ${allowedMethods.join(", ")}.`);
         }
         const method = methodStr;
         const pathname = String(args.path);
@@ -177,21 +184,48 @@ registerTool({
             params: query,
             data: body,
         });
-    },
+    };
+}
+registerTool({
+    name: "dev_read_api",
+    description: "Read from any allowlisted Open Ephemeris API endpoint via HTTP GET. This is the read-only " +
+        "power-user escape hatch — use the typed tools (ephemeris_natal_chart, ephemeris_transits, etc.) " +
+        "first for common operations. For endpoints that compute via POST (natal-chart, synastry, etc.), " +
+        "use dev_write_api.\n\n" +
+        DEV_API_REFERENCE,
+    inputSchema: makeProxyInputSchema(READ_METHODS),
+    outputSchema: OUTPUT_SCHEMA_JSON,
+    // GET-only: never mutates server state.
+    annotations: { title: "API Read", readOnlyHint: true, openWorldHint: true },
+    handler: makeProxyHandler(READ_METHODS, "GET"),
+});
+registerTool({
+    name: "dev_write_api",
+    description: "Send a request to any allowlisted Open Ephemeris API endpoint via POST/PUT/PATCH/DELETE. " +
+        "Most chart computations (natal-chart, synastry, composite, transits/search, returns, ACG) are " +
+        "POST endpoints and use this tool. Use the typed tools first for common operations; use dev_read_api " +
+        "for GET endpoints.\n\n" +
+        DEV_API_REFERENCE,
+    inputSchema: makeProxyInputSchema(WRITE_METHODS),
+    outputSchema: OUTPUT_SCHEMA_JSON,
+    // Issues POST/PUT/PATCH/DELETE — must not be advertised as read-only.
+    annotations: { title: "API Write", readOnlyHint: false, openWorldHint: true },
+    handler: makeProxyHandler(WRITE_METHODS, "POST"),
 });
 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. " +
+        "Use this to discover what's available before calling dev_read_api / dev_write_api, 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.",
+        "check those first before reaching for the generic proxies.",
     inputSchema: {
         type: "object",
         properties: {},
         additionalProperties: false,
     },
     outputSchema: OUTPUT_SCHEMA_JSON,
+    annotations: { title: "List Allowed API Operations", readOnlyHint: true, openWorldHint: false },
     handler: async () => {
         const allowlist = loadAllowlist();
         return {