@openephemeris/mcp-server 3.13.6 → 3.13.8

package/README.md

@@ -355,8 +355,8 @@ Generated by `npm run sync:readme` from `config/dev-allowlist.json` and the live
 
 - Allowlisted operations: **28**
 - Methods: `GET=4`, `POST=24`, `PUT=0`, `PATCH=0`, `DELETE=0`
-- Registered tools (`OPENEPHEMERIS_PROFILE=dev`): **64**
-- Typed tools: `acg_hits`, `acg_power_lines`, `auth_login`, `auth_logout`, `auth_status`, `bi_wheel_on_cross_aspect_click`, `bi_wheel_on_planet_click`, `chart_wheel_on_aspect_click`, `chart_wheel_on_house_click`, `chart_wheel_on_planet_click`, `chart_wheel_recalculate`, `chinese_bazi`, `dev_call`, `dev_list_allowed`, `electional_aspect_search`, `electional_moment_analysis`, `electional_station_tracker`, `ephemeris_angles_points`, `ephemeris_aspect_check`, `ephemeris_bi_wheel`, `ephemeris_chart_wheel`, `ephemeris_composite`, `ephemeris_composite_midpoint`, `ephemeris_dignities`, `ephemeris_electional`, `ephemeris_fixed_stars`, `ephemeris_hermetic_lots`, `ephemeris_house_cusps`, `ephemeris_lunar_return`, `ephemeris_midpoints`, `ephemeris_moon_phase`, `ephemeris_natal_batch`, `ephemeris_natal_chart`, `ephemeris_natal_transits`, `ephemeris_next_eclipse`, `ephemeris_next_lunar_phase`, `ephemeris_overlay`, `ephemeris_planet_position`, `ephemeris_planetary_return`, `ephemeris_progressed_chart`, `ephemeris_relocation`, `ephemeris_retrograde_status`, `ephemeris_solar_return`, `ephemeris_synastry`, `ephemeris_transits`, `explore_bi_wheel`, `explore_human_design`, `explore_natal_chart`, `hd_on_center_click`, `hd_on_channel_click`, `hd_on_gate_click`, `hd_opposition`, `hd_planetary_return`, `human_design_bodygraph`, `human_design_chart`, `human_design_composite`, `human_design_penta`, `vedic_chart`, `venus_eight_year_star`, `venus_elongations`, `venus_phase`, `venus_star_points`, `venus_star_points_conjunctions`, `venus_stations`
+- Registered tools (`OPENEPHEMERIS_PROFILE=dev`): **72**
+- Typed tools: `acg_hits`, `acg_power_lines`, `auth_login`, `auth_logout`, `auth_status`, `bi_wheel_on_cross_aspect_click`, `bi_wheel_on_house_click`, `bi_wheel_on_planet_click`, `bi_wheel_recalculate`, `bi_wheel_synopsis`, `bodygraph_recalculate`, `chart_wheel_on_aspect_click`, `chart_wheel_on_house_click`, `chart_wheel_on_planet_click`, `chart_wheel_recalculate`, `chinese_bazi`, `dev_call`, `dev_list_allowed`, `electional_aspect_search`, `electional_moment_analysis`, `electional_station_tracker`, `ephemeris_angles_points`, `ephemeris_aspect_check`, `ephemeris_bi_wheel`, `ephemeris_chart_wheel`, `ephemeris_composite`, `ephemeris_composite_midpoint`, `ephemeris_dignities`, `ephemeris_electional`, `ephemeris_fixed_stars`, `ephemeris_hermetic_lots`, `ephemeris_house_cusps`, `ephemeris_lunar_return`, `ephemeris_midpoints`, `ephemeris_moon_phase`, `ephemeris_natal_batch`, `ephemeris_natal_chart`, `ephemeris_natal_transits`, `ephemeris_next_eclipse`, `ephemeris_next_lunar_phase`, `ephemeris_overlay`, `ephemeris_planet_position`, `ephemeris_planetary_return`, `ephemeris_progressed_chart`, `ephemeris_relocation`, `ephemeris_retrograde_status`, `ephemeris_solar_return`, `ephemeris_synastry`, `ephemeris_transits`, `explore_bi_wheel`, `explore_human_design`, `explore_natal_chart`, `hd_on_center_click`, `hd_on_channel_click`, `hd_on_gate_click`, `hd_on_planet_click`, `hd_on_variable_click`, `hd_opposition`, `hd_planetary_return`, `human_design_bodygraph`, `human_design_chart`, `human_design_composite`, `human_design_penta`, `location_search`, `timezone_resolve`, `vedic_chart`, `venus_eight_year_star`, `venus_elongations`, `venus_phase`, `venus_star_points`, `venus_star_points_conjunctions`, `venus_stations`
 - Generic tools: 
 
 ### Allowlist Families

package/dist/backend/client.js

@@ -15,7 +15,7 @@ const BINARY_ENDPOINT_PREFIXES = [
 ];
 const DASHBOARD_ACCOUNT_URL = "https://openephemeris.com/dashboard?tab=account";
 const LOGIN_SIGNUP_URL = "https://openephemeris.com/login?signup=true&redirect=%2Fdashboard%3Ftab%3Daccount";
-const UPGRADE_URL = "https://openephemeris.com/pay";
+const UPGRADE_URL = "https://openephemeris.com/pricing";
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -251,18 +251,36 @@ export class BackendClient {
                     `or set OPENEPHEMERIS_API_KEY in your MCP server config.`, 401, "auth_required", false, LOGIN_SIGNUP_URL);
             }
             if (status === 402) {
+                const dataObj = data && typeof data === "object" ? data : {};
+                const walletUrl = dataObj.upgrade?.wallets_url || "https://openephemeris.com/wallet";
+                const currentTier = dataObj.upgrade?.current_tier || dataObj.tier || "explorer";
+                const isPro = currentTier === "developer" || currentTier === "pro" || currentTier === "startup" || currentTier === "scale";
+                let upsellMsg = "";
+                if (currentTier === 'explorer') {
+                    upsellMsg =
+                        `Let the user know warmly: Their 150 free discovery credits are used up. ` +
+                            `They can top up their wallet starting at $5 for 150 credits at ` +
+                            `${walletUrl} — or upgrade to Pro ($29/mo) ` +
+                            `for 75,000 credits/month at ${UPGRADE_URL}`;
+                }
+                else if (currentTier === 'payg') {
+                    upsellMsg =
+                        `Let the user know warmly: Their wallet balance is empty. They can top up at ` +
+                            `${walletUrl} — $5 for 150 credits, ` +
+                            `$10 for 350, or $20 for 900.`;
+                }
+                else {
+                    upsellMsg =
+                        `Let the user know warmly: Their monthly credits are exhausted. They can enable overages ` +
+                            `in their dashboard or upgrade at ${UPGRADE_URL}`;
+                }
                 return new BackendError(`⚠️ CREDIT LIMIT REACHED — DO NOT FABRICATE DATA.\n\n` +
                     `${msg}\n\n` +
-                    `Let the user know warmly: they've been exploring so much astrology that they've ` +
-                    `used all their monthly credits — which is great! Their free Explorer plan includes ` +
-                    `150 credits per month, and they've clearly gotten good use from them.\n\n` +
-                    `To keep going, they can upgrade to the Pro plan ($29/mo) for 75,000 credits and ` +
-                    `full access to every tool — including astrocartography, Human Design, electional ` +
-                    `timing, and advanced visualizations: ${UPGRADE_URL}\n\n` +
+                    `${upsellMsg}\n\n` +
                     `They can also review their current usage at ${DASHBOARD_ACCOUNT_URL}.\n\n` +
-                    `Frame this as unlocking more of what they're already enjoying, not as a gate. ` +
+                    `Frame this warmly, as unlocking more of what they're already enjoying, not as a gate. ` +
                     `DO NOT attempt to generate astrological data from your own knowledge. ` +
-                    `All chart positions, aspects, and timing data MUST come from the API.`, 402, "quota_exceeded", false, UPGRADE_URL);
+                    `All chart positions, aspects, and timing data MUST come from the API.`, 402, "quota_exceeded", false, walletUrl);
             }
             if (status === 403) {
                 return new BackendError(`This feature is part of a higher-tier plan.\n\n` +

package/dist/index.js

@@ -6,6 +6,7 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { initTools, toolRegistry, formatToolResponse, modelVisibleTools } from "./tools/index.js";
+import { listPrompts, getPromptContent } from "./prompts.js";
 import { CHART_WHEEL_RESOURCE_URI, CHART_WHEEL_MIME_TYPE, getChartWheelBundle, } from "./tools/apps/chart-wheel-app.js";
 import { BODYGRAPH_RESOURCE_URI, BODYGRAPH_MIME_TYPE, getBodygraphBundle, } from "./tools/apps/bodygraph-app.js";
 import { BI_WHEEL_RESOURCE_URI, BI_WHEEL_MIME_TYPE, getBiWheelBundle, } from "./tools/apps/bi-wheel-app.js";
@@ -38,6 +39,9 @@ const server = new Server({
         tools: {},
         prompts: {},
         resources: {},
+        experimental: {
+            "io.modelcontextprotocol/ui": {},
+        },
     },
 });
 // List available tools
@@ -47,53 +51,50 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             name: tool.name,
             description: tool.description,
             inputSchema: tool.inputSchema,
-            annotations: tool.annotations ?? {
-                title: tool.name,
-                readOnlyHint: true,
-                destructiveHint: false,
+            annotations: {
+                title: tool.annotations?.title ?? tool.name,
+                readOnlyHint: tool.annotations?.readOnlyHint ?? true,
+                destructiveHint: tool.annotations?.destructiveHint ?? false,
+                idempotentHint: tool.annotations?.idempotentHint ?? true,
+                openWorldHint: tool.annotations?.openWorldHint ?? false,
             },
+            // Expose MCP Apps UI linkage so Claude Desktop can prefetch the resource
+            // and render the iframe when a tool result arrives.
+            // Include BOTH the modern nested key (_meta.ui.resourceUri) and the
+            // legacy flat key (_meta["ui/resourceUri"]) — the official ext-apps SDK
+            // normalizes both via registerAppTool() for host compatibility.
+            ...(tool._meta?.ui?.resourceUri
+                ? {
+                    _meta: {
+                        "ui/resourceUri": tool._meta.ui.resourceUri,
+                        ui: {
+                            resourceUri: tool._meta.ui.resourceUri,
+                            visibility: tool._meta.ui.visibility ?? ["model", "app"],
+                        },
+                    },
+                }
+                : {}),
         })),
     };
 });
 // List available prompts
 server.setRequestHandler(ListPromptsRequestSchema, async () => {
-    return {
-        prompts: [
-            {
-                name: "welcome_to_open_ephemeris",
-                description: "Getting started guide for the Open Ephemeris MCP. Use this to orient yourself to available tools, astrology terminology, and usage.",
-            }
-        ]
-    };
+    return { prompts: listPrompts() };
 });
 // Get prompt content
 server.setRequestHandler(GetPromptRequestSchema, async (request) => {
-    if (request.params.name !== "welcome_to_open_ephemeris") {
+    const prompt = getPromptContent(request.params.name);
+    if (!prompt) {
         throw new Error(`Unknown prompt: ${request.params.name}`);
     }
     return {
-        description: "Open Ephemeris Agent Orientation",
+        description: prompt.description,
         messages: [
             {
                 role: "user",
-                content: {
-                    type: "text",
-                    text: "Welcome to the **Open Ephemeris MCP Server**!\n\n" +
-                        "You are now connected to an enterprise-grade astrological and astronomical computation engine powered by NASA JPL DE440 ephemeris data (1550–2650 CE). As a generative guide, here is how you can best utilize these tools to help the user:\n\n" +
-                        "### Core Capabilities\n" +
-                        "- **Birth Charts:** Use `ephemeris_natal_chart` for full planetary positions, houses, dignities, and aspects.\n" +
-                        "- **Predictive Timing:** `ephemeris_transits` searches for exact dates when transiting planets hit natal points.\n" +
-                        "- **Location Astrology:** `ephemeris_relocation` projects a natal chart to a new geographic location (Astrocartography).\n" +
-                        "- **Specialized Modalities:** Dedicated tools for `vedic_chart`, `chinese_bazi`, and `human_design_chart`.\n" +
-                        "- **Eclipse Hunter:** `ephemeris_next_eclipse` dynamically scans 20 years for the next total or partial hit at the user's location.\n\n" +
-                        "### Best Practices for AI Agents\n" +
-                        "1. **Coordinate Formatting:** Always convert addresses/city names into `latitude` and `longitude` decimals *before* calling the tools (e.g., Chicago is `41.8781, -87.6298`).\n" +
-                        "2. **Datetime Handling:** Most endpoints accept ISO 8601 strings. If you have a local birth time but the endpoint asks for UTC, explicitly append a `Z` or timezone offset (e.g., `1990-04-15T19:30:00Z`).\n" +
-                        "3. **Token Efficiency:** Our responses are hyper-condensed to save you context space. You don't need to struggle with raw JSON arrays; interpret the condensed strings directly (e.g., `Su 15°Pi30 H10`).\n\n" +
-                        "You're equipped with professional-grade math. Start by asking the user if they'd like to calculate a natal chart, check recent transits, or explore another modality!"
-                }
-            }
-        ]
+                content: { type: "text", text: prompt.text },
+            },
+        ],
     };
 });
 // List available resources

package/dist/prompts.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Open Ephemeris MCP — Preloaded Prompt Library
+ *
+ * Each prompt is a complete agent workflow that:
+ *   1. Coaches the agent to collect all required data from the user
+ *   2. Handles timezone, coordinate, and house-system nuances correctly
+ *   3. Specifies which tools to call and in what order
+ *   4. Provides a structured interpretation framework
+ */
+export interface McpPrompt {
+    name: string;
+    description: string;
+    text: string;
+}
+export declare const PROMPTS: McpPrompt[];
+/**
+ * Returns the list of all prompts (name + description only, for ListPrompts).
+ */
+export declare function listPrompts(): Array<{
+    name: string;
+    description: string;
+}>;
+/**
+ * Returns the full prompt content for a given prompt name, or null if not found.
+ */
+export declare function getPromptContent(name: string): McpPrompt | null;