@pharaoh-so/mcp 0.2.8 → 0.2.10

package/README.md

@@ -51,7 +51,7 @@ claude mcp add pharaoh -- npx @pharaoh-so/mcp
 If you have a browser available (desktop, laptop), you can connect directly via SSE instead:
 
 ```bash
-claude mcp add --transport sse pharaoh https://mcp.pharaoh.so/sse
+claude mcp add --transport sse --scope user pharaoh https://mcp.pharaoh.so/sse
 ```
 
 This uses OAuth in the browser and doesn't require this package.

package/dist/proxy.d.ts

@@ -1,3 +1,19 @@
+/**
+ * Stdio ↔ SSE proxy — bridges a local MCP stdio connection to a remote Pharaoh SSE server.
+ * Uses SDK transports on both ends: StdioServerTransport (local) and SSEClientTransport (remote).
+ *
+ * RECONNECTION DESIGN:
+ * The MCP SDK's SSEClientTransport wraps an EventSource, which has built-in auto-reconnect
+ * (every 3 seconds by default). This auto-reconnect is problematic because:
+ *   1. Each reconnect creates a NEW server-side session (new auth, new session ID)
+ *   2. The proxy's reconnect loop doesn't know about the internal reconnect
+ *   3. Tool calls get lost between the stale and new sessions
+ *
+ * Solution: On any non-fatal SSE error, we explicitly close() the transport to kill
+ * the EventSource and its auto-reconnect timer, then let the proxy's own backoff loop
+ * create a fresh SSEClientTransport for the next attempt. This ensures one session
+ * at a time and clean reconnection semantics.
+ */
 /** Thrown when the remote server returns 401 — token is expired or revoked. */
 export declare class TokenExpiredError extends Error {
     constructor();

package/dist/proxy.js

@@ -1,6 +1,18 @@
 /**
  * Stdio ↔ SSE proxy — bridges a local MCP stdio connection to a remote Pharaoh SSE server.
  * Uses SDK transports on both ends: StdioServerTransport (local) and SSEClientTransport (remote).
+ *
+ * RECONNECTION DESIGN:
+ * The MCP SDK's SSEClientTransport wraps an EventSource, which has built-in auto-reconnect
+ * (every 3 seconds by default). This auto-reconnect is problematic because:
+ *   1. Each reconnect creates a NEW server-side session (new auth, new session ID)
+ *   2. The proxy's reconnect loop doesn't know about the internal reconnect
+ *   3. Tool calls get lost between the stale and new sessions
+ *
+ * Solution: On any non-fatal SSE error, we explicitly close() the transport to kill
+ * the EventSource and its auto-reconnect timer, then let the proxy's own backoff loop
+ * create a fresh SSEClientTransport for the next attempt. This ensures one session
+ * at a time and clean reconnection semantics.
  */
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -92,8 +104,6 @@ export async function startProxy(sseUrl, token) {
             });
         };
     }
-    /** Handle SSE errors — delegates to classifySSEError for 401/403 detection. */
-    const handleSSEError = classifySSEError;
     // Connect SSE with reconnect loop — stdio starts AFTER first successful connection
     await connectWithReconnect();
     /** Attempt SSE connection with exponential backoff on failure. */
@@ -116,18 +126,27 @@ export async function startProxy(sseUrl, token) {
                     await stdio.start();
                     stdioStarted = true;
                 }
+                else {
+                    process.stderr.write("Pharaoh: reconnected\n");
+                }
                 // Wait for close — this promise resolves when SSE disconnects
                 await new Promise((resolve, reject) => {
                     sse.onclose = () => resolve();
                     sse.onerror = (err) => {
                         try {
-                            handleSSEError(err);
+                            classifySSEError(err);
                         }
                         catch (typed) {
                             reject(typed);
                             return;
                         }
-                        // Non-fatal error — SSE will auto-close, onclose will fire
+                        // Non-fatal error — explicitly close the transport to kill
+                        // EventSource's built-in auto-reconnect. Without this, EventSource
+                        // reconnects every ~3s, creating ghost sessions on the server
+                        // (100+ auth successes, zero tool calls completing).
+                        // close() fires onclose which resolves this promise, handing
+                        // control back to the proxy's backoff loop.
+                        sse.close().catch(() => { });
                     };
                 });
                 // SSE closed — attempt reconnect

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pharaoh-so/mcp",
   "mcpName": "so.pharaoh/pharaoh",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "description": "MCP proxy for Pharaoh — maps codebases into queryable knowledge graphs for AI agents. Enables Claude Code in headless environments (VPS, SSH, CI) via device flow auth.",
   "type": "module",
   "main": "dist/index.js",

package/skills/pharaoh/SKILL.md

@@ -72,7 +72,7 @@ Full docs at [pharaoh.so/docs](https://pharaoh.so/docs).
 
 **Direct SSE** (desktop with browser, uses OAuth):
 ```
-claude mcp add pharaoh https://mcp.pharaoh.so/sse
+claude mcp add --transport sse --scope user pharaoh https://mcp.pharaoh.so/sse
 ```
 
 **Headless** (VPS/SSH/containers, uses device flow — authorize on any device):