@openephemeris/mcp-server 4.11.2 → 4.12.0

package/CHANGELOG.md

@@ -7,6 +7,34 @@ Version numbering follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [4.12.0] — 2026-08-13
+
+### Fixed
+- **Server `instructions` told the model a tool needed no arguments when it
+  did.** The zero-data-entry-point line named `ephemeris_retrograde_status` as
+  needing no arguments; its schema has `required: ["datetime"]`. An agent
+  that took the line literally made a zero-argument call and got a validation
+  error as its first experience of the server. Now names
+  `explore_moon_phase` and `electional_moment_analysis` — both genuinely
+  zero-argument — and both are asserted against the real tool schemas in CI
+  so this cannot silently drift again.
+
+### Added
+- **Connector first-run activation telemetry.** `mcp_tools_listed` (both
+  transports, once per session) and `mcp_session_silent` (HTTP, on teardown
+  when tools were listed but never called) close the gap where "connected but
+  never used it" was only an absence of events — indistinguishable from a
+  session that died mid-handshake. Funnel: `mcp_session_init` →
+  `mcp_tools_listed` → `first_tool_call`.
+
+### Changed
+- **Server `instructions` deduplicated** into `src/instructions.ts`, shared by
+  both transports. They were previously copy-pasted verbatim into each
+  transport file, which is how the argument-count claim above drifted from
+  the schemas undetected.
+
+---
+
 ## [4.11.2] — 2026-08-13
 
 ### Fixed

package/dist/analytics.d.ts

@@ -1,3 +1,13 @@
-/** Stable, non-reversible identity from a credential. */
+/** Stable identity from a credential — the Supabase user id for OAuth, else a hash of the API key. */
 export declare function distinctIdFor(credential: string | undefined): string;
+/**
+ * Fire `first_tool_call` the first time a given identity completes a tool
+ * call, so activation (site visit → connector install → first real use) is a
+ * queryable event instead of "earliest mcp_tool_call per person" math. Never
+ * fires for "anonymous" (no credential at all — nothing to attribute
+ * activation to). Best-effort dedup only: the set is per-process, so a
+ * session that lands on a different Fly machine can refire once — acceptable
+ * for an activation metric read in aggregate.
+ */
+export declare function captureFirstToolCallOnce(distinctId: string, properties?: Record<string, unknown>): void;
 export declare function captureEvent(event: string, distinctId: string, properties?: Record<string, unknown>): void;

package/dist/analytics.js

@@ -6,6 +6,21 @@
  * the 402 paywall. These events close that gap. Everything is best-effort:
  * analytics must never slow down or fail a tool call.
  *
+ * Events, in funnel order:
+ *   mcp_session_init    — handshake completed
+ *   mcp_tools_listed    — host fetched tools/list (once per session)
+ *   first_tool_call     — this identity's first-ever completed tool call
+ *   mcp_tool_call       — every completed call
+ *   mcp_tool_error      — every failed call
+ *   mcp_session_silent  — HTTP only: listed tools, never attempted one. See
+ *                         reportSilentSession() in server-sse.ts for its two
+ *                         reading caveats (late arrival, undercount).
+ *
+ * mcp_session_init → mcp_tools_listed → first_tool_call is the activation
+ * funnel. Before mcp_tools_listed existed, "connected but never used it" was
+ * only an absence of events and could not be told apart from a host that never
+ * listed, or a session that died mid-handshake.
+ *
  * Configuration:
  *   POSTHOG_API_KEY  — project API key (phc_...). On the Fly-hosted remote
  *                      server this comes from a secret. On stdio (the npm
@@ -18,12 +33,18 @@
  *   DO_NOT_TRACK=1                      (de-facto cross-tool standard)
  * Disclosed in README.md under "Telemetry".
  *
- * Identity: we never send raw API keys or JWTs. The distinct_id is a SHA-256
- * prefix of the credential, stable per user across sessions but useless for
- * authentication. No birth data, coordinates, names, or tool arguments are
- * ever sent — only the tool NAME, duration, error status, and client name.
+ * Identity: we never send raw API keys. API-key sessions get a SHA-256
+ * prefix of the key, stable per user across sessions but useless for
+ * authentication. OAuth (Supabase JWT) sessions instead use the JWT's `sub`
+ * claim directly as the distinct_id — that's the same Supabase user id the
+ * web app passes to posthog.identify() at apps/web/contexts/AuthContext.tsx,
+ * so an MCP session and a browser session for the same account land on one
+ * PostHog person instead of two unmergeable ones. No birth data, coordinates,
+ * names, or tool arguments are ever sent — only the tool NAME, duration,
+ * error status, and client name.
  */
 import { createHash } from "node:crypto";
+import { decodeJwtSub } from "./oauth/session-utils.js";
 const POSTHOG_HOST = process.env.POSTHOG_HOST || "https://us.i.posthog.com";
 /**
  * Public, write-only PostHog project ingestion key.
@@ -51,13 +72,45 @@ function apiKey() {
         return configured;
     return DEFAULT_INGEST_KEY.startsWith("phc_") ? DEFAULT_INGEST_KEY : undefined;
 }
-/** Stable, non-reversible identity from a credential. */
+/** Stable identity from a credential — the Supabase user id for OAuth, else a hash of the API key. */
 export function distinctIdFor(credential) {
     if (!credential)
         return "anonymous";
+    if (credential.startsWith("eyJ")) {
+        const sub = decodeJwtSub(credential);
+        if (sub)
+            return sub;
+    }
     return "mcp_" + createHash("sha256").update(credential).digest("hex").slice(0, 24);
 }
+const identitiesWithFirstToolCall = new Set();
+/**
+ * Fire `first_tool_call` the first time a given identity completes a tool
+ * call, so activation (site visit → connector install → first real use) is a
+ * queryable event instead of "earliest mcp_tool_call per person" math. Never
+ * fires for "anonymous" (no credential at all — nothing to attribute
+ * activation to). Best-effort dedup only: the set is per-process, so a
+ * session that lands on a different Fly machine can refire once — acceptable
+ * for an activation metric read in aggregate.
+ */
+export function captureFirstToolCallOnce(distinctId, properties = {}) {
+    if (distinctId === "anonymous" || identitiesWithFirstToolCall.has(distinctId))
+        return;
+    identitiesWithFirstToolCall.add(distinctId);
+    captureEvent("first_tool_call", distinctId, properties);
+}
+// Our own e2e/harness/canary scripts declare an MCP clientInfo.name that ends
+// up in every event's `client_name` property (see transportProps() in
+// server-sse.ts / index.ts) — e.g. "e2e-http-client", "harness-fixture-capture".
+// Their runs were previously indistinguishable from real users in PostHog.
+const INTERNAL_CLIENT_PREFIXES = ["e2e-", "harness-", "test-", "canary-", "deploy-state-check", "local-agent-mode", "verify"];
+/** True if a captured `client_name` identifies one of our own test/harness/canary scripts. */
+function isInternalClientName(name) {
+    return typeof name === "string" && INTERNAL_CLIENT_PREFIXES.some((prefix) => name.startsWith(prefix));
+}
 export function captureEvent(event, distinctId, properties = {}) {
+    if (isInternalClientName(properties.client_name))
+        return;
     const key = apiKey();
     if (!key)
         return;

package/dist/index.js

@@ -6,8 +6,8 @@ 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, formatToolError, modelVisibleTools, parseToolSurface, SERVER_VERSION } from "./tools/index.js";
-import { DATETIME_CONTRACT_INSTRUCTIONS } from "./tools/datetime.js";
-import { captureEvent, distinctIdFor } from "./analytics.js";
+import { SERVER_INSTRUCTIONS } from "./instructions.js";
+import { captureEvent, captureFirstToolCallOnce, distinctIdFor } from "./analytics.js";
 import { listPrompts, getPromptContent } from "./prompts.js";
 // ── MCP App resource imports ────────────────────────────────────────────────
 import { CHART_WHEEL_RESOURCE_URI, CHART_WHEEL_MIME_TYPE, getChartWheelBundle, } from "./tools/apps/chart-wheel-app.js";
@@ -63,15 +63,7 @@ const server = new Server({
             },
         },
     },
-    instructions: "Open Ephemeris computes real astronomy (JPL DE440, sub-arcsecond) — never guess " +
-        "or approximate positions yourself; always call a tool. " +
-        "For anything the user should SEE (natal chart, bi-wheel, bodygraph, moon phase), " +
-        "prefer the explore_* tools — they render interactive visuals inline. " +
-        "ephemeris_* tools return data; use format='llm' on them for compact output. " +
-        "If the user has no birth data handy, start with the sky right now — " +
-        "explore_moon_phase and ephemeris_retrograde_status need none. " +
-        "See the 'welcome_to_open_ephemeris' prompt for orientation.\n\n" +
-        DATETIME_CONTRACT_INSTRUCTIONS,
+    instructions: SERVER_INSTRUCTIONS,
 });
 // Which slice of the registry this process advertises. Tools outside the
 // surface stay callable by name — this only controls what tools/list returns.
@@ -110,34 +102,49 @@ function transportProps() {
         server_version: SERVER_VERSION,
     };
 }
+// One-shot latch for mcp_tools_listed. A stdio process serves exactly one
+// session for its whole lifetime, so process scope IS session scope here.
+//
+// There is deliberately no stdio equivalent of the HTTP transport's
+// `mcp_session_silent`: the only teardown signal is process exit, and
+// captureEvent is a fire-and-forget fetch that would not flush before the
+// process is gone. On stdio, "listed but never called" is a PostHog query
+// (mcp_tools_listed with no following first_tool_call), not an event.
+let toolsListedReported = false;
 // List available tools
 server.setRequestHandler(ListToolsRequestSchema, async () => {
-    return {
-        tools: modelVisibleTools("stdio", STDIO_SURFACE).map((tool) => ({
-            name: tool.name,
-            description: tool.description,
-            inputSchema: tool.inputSchema,
-            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
-            ...(tool._meta?.ui?.resourceUri
-                ? {
-                    _meta: {
-                        "ui/resourceUri": tool._meta.ui.resourceUri,
-                        ui: {
-                            resourceUri: tool._meta.ui.resourceUri,
-                            visibility: tool._meta.ui.visibility ?? ["model", "app"],
-                        },
+    const tools = modelVisibleTools("stdio", STDIO_SURFACE).map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        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
+        ...(tool._meta?.ui?.resourceUri
+            ? {
+                _meta: {
+                    "ui/resourceUri": tool._meta.ui.resourceUri,
+                    ui: {
+                        resourceUri: tool._meta.ui.resourceUri,
+                        visibility: tool._meta.ui.visibility ?? ["model", "app"],
                     },
-                }
-                : {}),
-        })),
-    };
+                },
+            }
+            : {}),
+    }));
+    if (!toolsListedReported) {
+        toolsListedReported = true;
+        captureEvent("mcp_tools_listed", analyticsId(), {
+            tool_count: tools.length,
+            ...transportProps(),
+        });
+    }
+    return { tools };
 });
 // List available prompts
 server.setRequestHandler(ListPromptsRequestSchema, async () => {
@@ -279,11 +286,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     try {
         const result = await tool.handler(request.params.arguments ?? {});
         const durationMs = Date.now() - startTime;
-        captureEvent("mcp_tool_call", analyticsId(), {
+        const id = analyticsId();
+        captureEvent("mcp_tool_call", id, {
             tool: toolName,
             duration_ms: durationMs,
             ...transportProps(),
         });
+        captureFirstToolCallOnce(id, { tool: toolName, ...transportProps() });
         return formatToolResponse(toolName, result, durationMs);
     }
     catch (error) {

package/dist/instructions.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Tools an agent can call with literally no arguments — the entry points for a
+ * user who has not offered birth data.
+ *
+ * Asserted against the real schemas in test/description-cross-references.test.ts:
+ * each name here must be registered, must be on the CORE surface (most hosts
+ * refuse to call a tool absent from tools/list), and must genuinely have no
+ * required fields. Naming a tool here that needs an argument puts the model's
+ * very first call on a path to a validation error, which is the exact failure
+ * this list exists to prevent.
+ *
+ * Order is deliberate: the visual one leads, because a rendered dial is a
+ * better first impression than a score.
+ */
+export declare const ZERO_ARG_ENTRY_TOOLS: readonly ["explore_moon_phase", "electional_moment_analysis"];
+export declare const SERVER_INSTRUCTIONS: string;

package/dist/instructions.js

@@ -0,0 +1,51 @@
+/**
+ * instructions.ts — the server `instructions` string, shared by both transports.
+ *
+ * This is the highest-leverage text in the product. It is the only guidance a
+ * host puts in front of the model before the user's first message, and the
+ * connector funnel is where we lose people: of the MCP connector identities
+ * seen in a 60-day window, ~1 in 8 ever invoked a tool at all.
+ *
+ * It previously lived inline and duplicated verbatim in src/index.ts and
+ * src/server-sse.ts. That duplication is how it came to advertise
+ * `ephemeris_retrograde_status` as needing no arguments when its schema has
+ * `required: ["datetime"]` — an agent that took the line literally made a
+ * zero-argument call and got a validation error as its first experience of the
+ * server. Defining the text once, next to the list it interpolates, lets a test
+ * check the claim against the real schemas (see description-cross-references).
+ *
+ * Kept OUT of the tool surface on purpose: `instructions` is sent once at
+ * initialize and is not counted by the tool-surface token budget (GATE 4, see
+ * test/tool-surface-budget.test.ts), which is at ~19.6k of its 20k ceiling.
+ * First-run routing guidance therefore belongs here rather than in a tool
+ * description that every model pass re-pays for.
+ */
+import { DATETIME_CONTRACT_INSTRUCTIONS } from "./tools/datetime.js";
+/**
+ * Tools an agent can call with literally no arguments — the entry points for a
+ * user who has not offered birth data.
+ *
+ * Asserted against the real schemas in test/description-cross-references.test.ts:
+ * each name here must be registered, must be on the CORE surface (most hosts
+ * refuse to call a tool absent from tools/list), and must genuinely have no
+ * required fields. Naming a tool here that needs an argument puts the model's
+ * very first call on a path to a validation error, which is the exact failure
+ * this list exists to prevent.
+ *
+ * Order is deliberate: the visual one leads, because a rendered dial is a
+ * better first impression than a score.
+ */
+export const ZERO_ARG_ENTRY_TOOLS = [
+    "explore_moon_phase",
+    "electional_moment_analysis",
+];
+export const SERVER_INSTRUCTIONS = "Open Ephemeris computes real astronomy (JPL DE440, sub-arcsecond) — never guess " +
+    "or approximate positions yourself; always call a tool. " +
+    "For anything the user should SEE (natal chart, bi-wheel, bodygraph, moon phase), " +
+    "prefer the explore_* tools — they render interactive visuals inline. " +
+    "ephemeris_* tools return data; use format='llm' on them for compact output. " +
+    "If the user has no birth data handy, open with the sky right now: " +
+    `${ZERO_ARG_ENTRY_TOOLS.join(" and ")} take no arguments at all — ` +
+    "call one rather than asking for a birth date first. " +
+    "See the 'welcome_to_open_ephemeris' prompt for orientation.\n\n" +
+    DATETIME_CONTRACT_INSTRUCTIONS;

package/dist/server-sse.js

@@ -21,10 +21,10 @@ import axios from "axios";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { InMemoryEventStore } from "./event-store.js";
-import { captureEvent, distinctIdFor } from "./analytics.js";
+import { captureEvent, captureFirstToolCallOnce, distinctIdFor } from "./analytics.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, isInitializeRequest, } from "@modelcontextprotocol/sdk/types.js";
 import { initTools, toolRegistry, formatToolResponse, formatToolError, modelVisibleTools, parseToolSurface, describeSurface } from "./tools/index.js";
-import { DATETIME_CONTRACT_INSTRUCTIONS } from "./tools/datetime.js";
+import { SERVER_INSTRUCTIONS } from "./instructions.js";
 import { BackendClient, runWithClient } from "./backend/client.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";
@@ -224,7 +224,36 @@ function transportProps(server, surface) {
         server_version: version,
     };
 }
-function createMcpServer(analyticsId = "anonymous", surface = "core") {
+function newSessionActivity() {
+    return { startedAt: Date.now(), listedTools: false, attemptedTool: false, silenceReported: false };
+}
+/**
+ * Emit `mcp_session_silent` for a session that saw the tool list and never tried
+ * to use it — the measurable form of the connector drop-off.
+ *
+ * Two caveats for whoever reads this in PostHog, because they change the query:
+ *
+ *  1. The event lands when the session TEARS DOWN, not when it went quiet. A
+ *     host that vanishes without a DELETE is only cleaned up by the idle reaper,
+ *     so its event can arrive SESSION_IDLE_TTL_MS + up to one 10-minute sweep
+ *     after the fact. Read it in daily aggregate, not as a live signal, and use
+ *     `session_duration_ms` to separate "closed straight away" from "sat open
+ *     and unused".
+ *  2. It UNDERCOUNTS. A process restart (i.e. every deploy) drops the sessions
+ *     still pending teardown. `mcp_tools_listed` with no following
+ *     `first_tool_call` is the reliable denominator; this event is the richer
+ *     but lossier view.
+ */
+function reportSilentSession(server, analyticsId, surface, activity) {
+    if (!activity.listedTools || activity.attemptedTool || activity.silenceReported)
+        return;
+    activity.silenceReported = true;
+    captureEvent("mcp_session_silent", analyticsId, {
+        session_duration_ms: Date.now() - activity.startedAt,
+        ...transportProps(server, surface),
+    });
+}
+function createMcpServer(analyticsId = "anonymous", surface = "core", activity = newSessionActivity()) {
     const server = new Server({
         name: "openephemeris-mcp",
         title: "Open Ephemeris",
@@ -266,19 +295,11 @@ function createMcpServer(analyticsId = "anonymous", surface = "core") {
                 },
             },
         },
-        instructions: "Open Ephemeris computes real astronomy (JPL DE440, sub-arcsecond) — never guess " +
-            "or approximate positions yourself; always call a tool. " +
-            "For anything the user should SEE (natal chart, bi-wheel, bodygraph, moon phase), " +
-            "prefer the explore_* tools — they render interactive visuals inline. " +
-            "ephemeris_* tools return data; use format='llm' on them for compact output. " +
-            "If the user has no birth data handy, start with the sky right now — " +
-            "explore_moon_phase and ephemeris_retrograde_status need none. " +
-            "See the 'welcome_to_open_ephemeris' prompt for orientation.\n\n" +
-            DATETIME_CONTRACT_INSTRUCTIONS,
+        instructions: SERVER_INSTRUCTIONS,
     });
     // --- Tool handlers ---
-    server.setRequestHandler(ListToolsRequestSchema, async () => ({
-        tools: modelVisibleTools("http", surface).map((tool) => ({
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        const tools = modelVisibleTools("http", surface).map((tool) => ({
             name: tool.name,
             description: tool.description,
             inputSchema: tool.inputSchema,
@@ -295,8 +316,18 @@ function createMcpServer(analyticsId = "anonymous", surface = "core") {
                     },
                 }
                 : {}),
-        })),
-    }));
+        }));
+        // Once per session: the host has fetched the surface. Everything after this
+        // point is the model's choice, so this is the denominator for activation.
+        if (!activity.listedTools) {
+            activity.listedTools = true;
+            captureEvent("mcp_tools_listed", analyticsId, {
+                tool_count: tools.length,
+                ...transportProps(server, surface),
+            });
+        }
+        return { tools };
+    });
     // --- Prompt handlers ---
     server.setRequestHandler(ListPromptsRequestSchema, async () => ({
         prompts: [WELCOME_PROMPT],
@@ -313,6 +344,9 @@ function createMcpServer(analyticsId = "anonymous", surface = "core") {
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const toolName = request.params.name;
         const tool = toolRegistry[toolName];
+        // Marked before the registry check: reaching for a tool that does not exist
+        // is still a session that tried, and must not be counted as silence.
+        activity.attemptedTool = true;
         if (!tool || tool.stdioOnly) {
             // stdioOnly tools (device auth) mutate process-global state and must not
             // be callable on the multi-tenant HTTP transport, even by name.
@@ -331,6 +365,7 @@ function createMcpServer(analyticsId = "anonymous", surface = "core") {
                 duration_ms: durationMs,
                 ...transportProps(server, surface),
             });
+            captureFirstToolCallOnce(analyticsId, { tool: toolName, ...transportProps(server, surface) });
             return formatToolResponse(toolName, result, durationMs);
         }
         catch (error) {
@@ -854,7 +889,8 @@ export async function createSseApp() {
         // A comma list of traditions works the same way — `?profile=hd,bazi` —
         // and advertises just those plus geocoding, account and the escape hatch.
         const surface = parseToolSurface(req.query.profile ?? req.headers["x-oe-tool-surface"]);
-        const server = createMcpServer(analyticsId, surface);
+        const activity = newSessionActivity();
+        const server = createMcpServer(analyticsId, surface, activity);
         // Fire session_init after the handshake so getClientVersion() is populated
         // — without this the connecting host is unknown and we cannot tell which
         // clients the remote server is actually serving.
@@ -869,6 +905,10 @@ export async function createSseApp() {
                 httpSessions.delete(transport.sessionId);
                 console.error(`[HTTP] Session closed: ${transport.sessionId}`);
             }
+            // All three teardown paths (transport close, DELETE /mcp, idle reaper)
+            // converge here — server.close() closes the transport — so this is the one
+            // place the silence verdict has to be made.
+            reportSilentSession(server, analyticsId, surface, activity);
         };
         await server.connect(transport);
         await runWithClient(client, () => transport.handleRequest(req, res, req.body));

package/package.json

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