@pharaoh-so/mcp 0.1.2 → 0.1.3

package/README.md

@@ -4,11 +4,28 @@ Stdio-to-SSE proxy for [Pharaoh](https://pharaoh.so) — enables Claude Code in
 
 ## Quick Start
 
+**Step 1 — Authenticate** (run in your terminal):
+
+```bash
+npx @pharaoh-so/mcp
+```
+
+This shows a device code and URL. Open the URL on any device (phone, laptop) to authorize. Credentials are saved to `~/.pharaoh/credentials.json` (valid for 7 days).
+
+**Step 2 — Add to Claude Code:**
+
+```bash
+claude mcp add pharaoh -- npx @pharaoh-so/mcp
+```
+
+If you previously added pharaoh as SSE, remove it first:
+
 ```bash
+claude mcp remove pharaoh
 claude mcp add pharaoh -- npx @pharaoh-so/mcp
 ```
 
-On first run, the proxy shows a device code and URL. Open the URL on any device (phone, laptop) to authorize. The proxy stores credentials at `~/.pharaoh/credentials.json` and reuses them until they expire (7 days).
+Verify with `claude mcp list` — it should show `pharaoh` as a **stdio** server, not SSE.
 
 ## How It Works
 

package/dist/helpers.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Pure helper functions for the mcp-proxy CLI — no side effects on import.
+ * Separated from index.ts so tests can import without triggering main().
+ */
+import type { TokenResponse } from "./auth.js";
+import type { Credentials } from "./credentials.js";
+/** Write one or more lines to stderr. */
+export declare function printLines(...lines: string[]): void;
+/** Parse CLI arguments. */
+export declare function parseArgs(argv?: string[]): {
+    server: string;
+    logout: boolean;
+};
+export declare function printUsage(): void;
+/**
+ * Validate that a server-supplied SSE URL shares the same origin as the configured server.
+ * Prevents a compromised auth response from redirecting the Bearer token to an attacker's host.
+ * Falls back to `${server}/sse` if the URL is missing, malformed, or cross-origin.
+ */
+export declare function resolveSseUrl(tokenSseUrl: string | undefined, server: string): string;
+/** Convert a token response to storable credentials. */
+export declare function tokenToCredentials(token: TokenResponse, sseUrl: string): Credentials;
+/** Format remaining TTL as human-readable string (e.g. "5d 12h"). */
+export declare function formatTtl(expiresAt: string): string;
+/**
+ * Print setup instructions for Claude Code. Called in interactive mode
+ * after auth completes (or when credentials already exist).
+ */
+export declare function printSetupInstructions(): void;
+/** Format a credential identity string (e.g. "alice (my-org)"). */
+export declare function formatIdentity(creds: Credentials): string;
+/**
+ * Determine if credentials are valid for proxy use.
+ * Returns a diagnostic message if not, null if valid.
+ */
+export declare function validateCredentials(creds: Credentials | null): string | null;

package/dist/helpers.js

@@ -0,0 +1,124 @@
+import { isExpired } from "./credentials.js";
+const DEFAULT_SERVER = "https://mcp.pharaoh.so";
+/** Write one or more lines to stderr. */
+export function printLines(...lines) {
+    process.stderr.write(lines.join("\n") + "\n");
+}
+/** Parse CLI arguments. */
+export function parseArgs(argv = process.argv.slice(2)) {
+    let server = DEFAULT_SERVER;
+    let logout = false;
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === "--server" && argv[i + 1]) {
+            server = argv[i + 1];
+            i++;
+        }
+        else if (argv[i] === "--logout") {
+            logout = true;
+        }
+    }
+    // Strip trailing slash
+    server = server.replace(/\/+$/, "");
+    // Reject non-HTTPS servers (allow loopback addresses for local dev)
+    try {
+        const parsed = new URL(server);
+        const isLoopback = parsed.hostname === "localhost" ||
+            parsed.hostname === "127.0.0.1" ||
+            parsed.hostname === "[::1]";
+        if (parsed.protocol !== "https:" && !isLoopback) {
+            printLines(`Pharaoh: --server must use HTTPS (got ${parsed.protocol}//…). Use https:// or http://localhost for local dev.`);
+            process.exit(1);
+        }
+        if (parsed.protocol !== "https:" && isLoopback) {
+            printLines("⚠ Warning: using insecure HTTP over loopback — do not use in production.");
+        }
+    }
+    catch {
+        printLines(`Pharaoh: --server is not a valid URL: ${server}`);
+        process.exit(1);
+    }
+    return { server, logout };
+}
+export function printUsage() {
+    printLines("Usage: pharaoh-mcp [options]", "", "Options:", "  --server <url>  Pharaoh server URL (default: https://mcp.pharaoh.so)", "  --logout        Clear stored credentials and exit", "  --help, -h      Show this help", "", "Add to Claude Code:", "  claude mcp add pharaoh -- npx @pharaoh-so/mcp", "");
+}
+/**
+ * Validate that a server-supplied SSE URL shares the same origin as the configured server.
+ * Prevents a compromised auth response from redirecting the Bearer token to an attacker's host.
+ * Falls back to `${server}/sse` if the URL is missing, malformed, or cross-origin.
+ */
+export function resolveSseUrl(tokenSseUrl, server) {
+    const fallback = `${server}/sse`;
+    if (!tokenSseUrl)
+        return fallback;
+    try {
+        const sseOrigin = new URL(tokenSseUrl).origin;
+        const serverOrigin = new URL(server).origin;
+        if (sseOrigin !== serverOrigin) {
+            printLines(`Pharaoh: ignoring cross-origin sse_url (${sseOrigin} ≠ ${serverOrigin})`);
+            return fallback;
+        }
+        return tokenSseUrl;
+    }
+    catch {
+        return fallback;
+    }
+}
+/** Convert a token response to storable credentials. */
+export function tokenToCredentials(token, sseUrl) {
+    return {
+        version: 1,
+        access_token: token.access_token,
+        expires_at: new Date(Date.now() + token.expires_in * 1000).toISOString(),
+        expires_in: token.expires_in,
+        sse_url: sseUrl,
+        github_login: token.github_login ?? null,
+        tenant_name: token.tenant_name ?? null,
+        repos: token.repos ?? [],
+    };
+}
+/** Format remaining TTL as human-readable string (e.g. "5d 12h"). */
+export function formatTtl(expiresAt) {
+    const remainingMs = new Date(expiresAt).getTime() - Date.now();
+    if (remainingMs <= 0)
+        return "expired";
+    const hours = Math.floor(remainingMs / 3_600_000);
+    const days = Math.floor(hours / 24);
+    const remHours = hours % 24;
+    if (days > 0)
+        return `${days}d ${remHours}h`;
+    if (hours > 0)
+        return `${hours}h`;
+    return `${Math.floor(remainingMs / 60_000)}m`;
+}
+/**
+ * Print setup instructions for Claude Code. Called in interactive mode
+ * after auth completes (or when credentials already exist).
+ */
+export function printSetupInstructions() {
+    printLines("", "┌───────────────────────────────────────────────────────┐", "│  Next step: add Pharaoh to Claude Code                │", "│                                                       │", "│  If pharaoh is already registered (e.g. as SSE):      │", "│    claude mcp remove pharaoh                          │", "│                                                       │", "│  Then add as stdio proxy:                             │", "│    claude mcp add pharaoh -- npx @pharaoh-so/mcp     │", "│                                                       │", "│  Verify with:                                         │", "│    claude mcp list                                    │", "└───────────────────────────────────────────────────────┘", "");
+}
+/** Format a credential identity string (e.g. "alice (my-org)"). */
+export function formatIdentity(creds) {
+    return [
+        creds.github_login ?? "unknown",
+        creds.tenant_name ? `(${creds.tenant_name})` : null,
+    ]
+        .filter(Boolean)
+        .join(" ");
+}
+/**
+ * Determine if credentials are valid for proxy use.
+ * Returns a diagnostic message if not, null if valid.
+ */
+export function validateCredentials(creds) {
+    if (!creds || isExpired(creds)) {
+        return [
+            "Pharaoh: no valid credentials — cannot start proxy.",
+            "Run this command first to authenticate:",
+            "  npx @pharaoh-so/mcp",
+            "",
+        ].join("\n");
+    }
+    return null;
+}

package/dist/index.js

@@ -5,170 +5,92 @@
  * Presents as an MCP server on stdio (for Claude Code) and relays messages
  * to a remote Pharaoh SSE server. Authenticates via RFC 8628 device flow
  * so the user can authorize on any device with a browser.
+ *
+ * Two modes determined by whether stdin is a TTY:
+ * - Interactive (TTY): authenticate, print setup instructions, exit.
+ * - Proxy (pipe):      require pre-existing credentials, bridge stdio ↔ SSE.
  */
 import { printActivationPrompt, printAuthSuccess, pollForToken, requestDeviceCode, } from "./auth.js";
-import { deleteCredentials, isExpired, readCredentials, writeCredentials, } from "./credentials.js";
+import { deleteCredentials, isExpired, readCredentials, writeCredentials } from "./credentials.js";
+import { formatIdentity, formatTtl, parseArgs, printLines, printSetupInstructions, printUsage, resolveSseUrl, tokenToCredentials, } from "./helpers.js";
 import { TokenExpiredError, TenantSuspendedError, startProxy } from "./proxy.js";
-const DEFAULT_SERVER = "https://mcp.pharaoh.so";
-/** Parse CLI arguments. */
-function parseArgs() {
+async function main() {
     const args = process.argv.slice(2);
-    let server = DEFAULT_SERVER;
-    let logout = false;
-    for (let i = 0; i < args.length; i++) {
-        if (args[i] === "--server" && args[i + 1]) {
-            server = args[i + 1];
-            i++;
-        }
-        else if (args[i] === "--logout") {
-            logout = true;
-        }
-        else if (args[i] === "--help" || args[i] === "-h") {
-            printUsage();
-            process.exit(0);
-        }
-    }
-    // Strip trailing slash
-    server = server.replace(/\/+$/, "");
-    return { server, logout };
-}
-function printUsage() {
-    process.stderr.write([
-        "Usage: pharaoh-mcp [options]",
-        "",
-        "Options:",
-        "  --server <url>  Pharaoh server URL (default: https://mcp.pharaoh.so)",
-        "  --logout        Clear stored credentials and exit",
-        "  --help, -h      Show this help",
-        "",
-        "Add to Claude Code:",
-        "  claude mcp add pharaoh -- npx @pharaoh-so/mcp",
-        "",
-    ].join("\n") + "\n");
-}
-/** Run the device flow and return a token response. */
-async function authenticate(server) {
-    const deviceCode = await requestDeviceCode(server);
-    printActivationPrompt(deviceCode.user_code, deviceCode.verification_uri);
-    return pollForToken(server, deviceCode.device_code, deviceCode.interval);
-}
-/**
- * Validate that a server-supplied SSE URL shares the same origin as the configured server.
- * Prevents a compromised auth response from redirecting the Bearer token to an attacker's host.
- * Falls back to `${server}/sse` if the URL is missing, malformed, or cross-origin.
- */
-function resolveSseUrl(tokenSseUrl, server) {
-    const fallback = `${server}/sse`;
-    if (!tokenSseUrl)
-        return fallback;
-    try {
-        const sseOrigin = new URL(tokenSseUrl).origin;
-        const serverOrigin = new URL(server).origin;
-        if (sseOrigin !== serverOrigin) {
-            process.stderr.write(`Pharaoh: ignoring cross-origin sse_url (${sseOrigin} ≠ ${serverOrigin})\n`);
-            return fallback;
-        }
-        return tokenSseUrl;
-    }
-    catch {
-        return fallback;
+    if (args.includes("--help") || args.includes("-h")) {
+        printUsage();
+        process.exit(0);
     }
-}
-/** Convert a token response to storable credentials. */
-function tokenToCredentials(token, sseUrl) {
-    return {
-        version: 1,
-        access_token: token.access_token,
-        expires_at: new Date(Date.now() + token.expires_in * 1000).toISOString(),
-        expires_in: token.expires_in,
-        sse_url: sseUrl,
-        github_login: token.github_login ?? null,
-        tenant_name: token.tenant_name ?? null,
-        repos: token.repos ?? [],
-    };
-}
-/** Format remaining TTL as human-readable string (e.g. "5d 12h"). */
-function formatTtl(expiresAt) {
-    const remainingMs = new Date(expiresAt).getTime() - Date.now();
-    if (remainingMs <= 0)
-        return "expired";
-    const hours = Math.floor(remainingMs / 3_600_000);
-    const days = Math.floor(hours / 24);
-    const remHours = hours % 24;
-    if (days > 0)
-        return `${days}d ${remHours}h`;
-    if (hours > 0)
-        return `${hours}h`;
-    return `${Math.floor(remainingMs / 60_000)}m`;
-}
-async function main() {
-    const { server, logout } = parseArgs();
-    // --logout: clear credentials and exit
+    const { server, logout } = parseArgs(args);
     if (logout) {
         deleteCredentials();
-        process.stderr.write("Pharaoh: credentials cleared\n");
+        printLines("Pharaoh: credentials cleared");
         process.exit(0);
     }
-    let creds = readCredentials();
-    // If we have valid credentials, try to connect directly
-    if (creds && !isExpired(creds)) {
-        process.stderr.write(`Pharaoh: token valid for ${formatTtl(creds.expires_at)} — connecting\n`);
-        try {
-            await startProxy(creds.sse_url, creds.access_token);
-            return;
-        }
-        catch (err) {
-            if (err instanceof TokenExpiredError) {
-                process.stderr.write("Pharaoh: token rejected by server — re-authenticating\n");
-                deleteCredentials();
-                creds = null;
-            }
-            else if (err instanceof TenantSuspendedError) {
-                process.stderr.write(`Pharaoh: ${err.message}\n`);
-                process.exit(1);
-            }
-            else {
-                throw err;
-            }
+    const creds = readCredentials();
+    const isInteractive = Boolean(process.stdin.isTTY);
+    // ── Interactive mode (user running in a terminal) ──
+    // Authenticate if needed, print setup instructions, and exit.
+    // The proxy is useless without Claude Code on the other end of stdin.
+    if (isInteractive) {
+        if (creds && !isExpired(creds)) {
+            printLines(`Pharaoh: authenticated as ${formatIdentity(creds)} — token valid for ${formatTtl(creds.expires_at)}, ${creds.repos.length} repo${creds.repos.length === 1 ? "" : "s"} connected`);
+            printSetupInstructions();
+            process.exit(0);
         }
-    }
-    // No valid credentials — run device flow
-    if (!creds || isExpired(creds)) {
-        process.stderr.write("Pharaoh: no valid credentials — starting device authorization\n");
-        const token = await authenticate(server);
+        // No valid credentials — run device flow
+        printLines("Pharaoh: no valid credentials — starting device authorization");
+        const deviceCode = await requestDeviceCode(server);
+        printActivationPrompt(deviceCode.user_code, deviceCode.verification_uri);
+        const token = await pollForToken(server, deviceCode.device_code, deviceCode.interval);
         if (token.provisional) {
-            process.stderr.write(`Pharaoh: provisional access — install the GitHub App to map your repos: ${token.install_url ?? ""}\n`);
+            printLines(`Pharaoh: provisional access — install the GitHub App to map your repos: ${token.install_url ?? ""}`);
         }
         const sseUrl = resolveSseUrl(token.sse_url, server);
-        creds = tokenToCredentials(token, sseUrl);
-        writeCredentials(creds);
+        const newCreds = tokenToCredentials(token, sseUrl);
+        writeCredentials(newCreds);
         printAuthSuccess(token.github_login ?? null, token.tenant_name ?? null, token.repos?.length ?? 0);
+        printSetupInstructions();
+        process.exit(0);
+    }
+    // ── Proxy mode (Claude Code spawned us as a stdio MCP server) ──
+    // If no credentials, we can't run the device flow (no TTY for user interaction).
+    if (!creds || isExpired(creds)) {
+        printLines("Pharaoh: no valid credentials — cannot start proxy.", "Run this command first to authenticate:", "  npx @pharaoh-so/mcp", "");
+        process.exit(1);
     }
-    // Start proxy with fresh credentials
+    // Valid credentials — start the proxy
+    printLines(`Pharaoh: token valid for ${formatTtl(creds.expires_at)} — connecting`);
     try {
         await startProxy(creds.sse_url, creds.access_token);
     }
     catch (err) {
         if (err instanceof TokenExpiredError) {
-            // Token expired during session — delete creds and re-auth
-            process.stderr.write("Pharaoh: session expired — re-authenticating\n");
+            printLines("Pharaoh: token expired or revoked.", "Run this command to re-authenticate:", "  npx @pharaoh-so/mcp", "");
             deleteCredentials();
-            const token = await authenticate(server);
-            const sseUrl = resolveSseUrl(token.sse_url, server);
-            creds = tokenToCredentials(token, sseUrl);
-            writeCredentials(creds);
-            await startProxy(creds.sse_url, creds.access_token);
-        }
-        else if (err instanceof TenantSuspendedError) {
-            process.stderr.write(`Pharaoh: ${err.message}\n`);
             process.exit(1);
         }
-        else {
-            throw err;
+        if (err instanceof TenantSuspendedError) {
+            printLines(`Pharaoh: ${err.message}`);
+            process.exit(1);
         }
+        throw err;
     }
 }
 main().catch((err) => {
-    process.stderr.write(`Pharaoh: fatal — ${err instanceof Error ? err.message : String(err)}\n`);
+    // Default: print only error name/code to avoid leaking tokens, internal URLs,
+    // or stack fragments that persist in CI logs. Full message behind PHARAOH_DEBUG.
+    if (process.env.PHARAOH_DEBUG === "1" && err instanceof Error) {
+        // Use main's comprehensive redaction patterns when showing the full message
+        const safeMsg = err.message
+            .replace(/Bearer\s+\S+/gi, "Bearer [REDACTED]")
+            .replace(/(?:phat|phrt|ghp|gho|ghs|ghu)_\S+/gi, "[REDACTED_TOKEN]")
+            .replace(/[?&](?:code|token|key|secret|password|state)=[^&\s]+/gi, "?[REDACTED_PARAM]")
+            .replace(/\b[0-9a-f]{32,}\b/gi, "[REDACTED_HEX]");
+        printLines(`Pharaoh: fatal — ${safeMsg}`);
+    }
+    else {
+        const label = err instanceof Error ? err.name : "Error";
+        printLines(`Pharaoh: fatal — ${label}. Set PHARAOH_DEBUG=1 for details.`);
+    }
     process.exit(1);
 });

package/dist/proxy.d.ts

@@ -18,6 +18,10 @@ export declare function classifySSEError(err: Error): void;
  *   Claude Code → stdin → StdioServerTransport.onmessage → SSEClientTransport.send → POST /message
  *   Pharaoh → SSE stream → SSEClientTransport.onmessage → StdioServerTransport.send → stdout
  *
+ * CRITICAL ordering: SSE must be connected BEFORE stdio starts reading stdin.
+ * Otherwise the MCP `initialize` message arrives before the remote transport is ready,
+ * gets permanently lost ("send error — Not connected"), and the client times out.
+ *
  * On SSE disconnect, attempts reconnect with exponential backoff (5 retries, ~62s total).
  * Throws TokenExpiredError on 401, TenantSuspendedError on 403.
  */

package/dist/proxy.js

@@ -67,6 +67,10 @@ function createSSETransport(sseUrl, token) {
  *   Claude Code → stdin → StdioServerTransport.onmessage → SSEClientTransport.send → POST /message
  *   Pharaoh → SSE stream → SSEClientTransport.onmessage → StdioServerTransport.send → stdout
  *
+ * CRITICAL ordering: SSE must be connected BEFORE stdio starts reading stdin.
+ * Otherwise the MCP `initialize` message arrives before the remote transport is ready,
+ * gets permanently lost ("send error — Not connected"), and the client times out.
+ *
  * On SSE disconnect, attempts reconnect with exponential backoff (5 retries, ~62s total).
  * Throws TokenExpiredError on 401, TenantSuspendedError on 403.
  */
@@ -74,6 +78,7 @@ export async function startProxy(sseUrl, token) {
     const stdio = new StdioServerTransport();
     let sse = createSSETransport(sseUrl, token);
     let reconnectAttempt = 0;
+    let stdioStarted = false;
     /** Wire up bidirectional message relay between the two transports. */
     function bridge(sseTransport) {
         stdio.onmessage = (msg) => {
@@ -89,22 +94,7 @@ export async function startProxy(sseUrl, token) {
     }
     /** Handle SSE errors — delegates to classifySSEError for 401/403 detection. */
     const handleSSEError = classifySSEError;
-    // Wire up initial bridge
-    bridge(sse);
-    // Handle SSE connection drops with reconnect
-    sse.onerror = (err) => {
-        try {
-            handleSSEError(err);
-        }
-        catch (typed) {
-            // TokenExpiredError or TenantSuspendedError — propagate via close
-            sse.close().catch(() => { });
-            throw typed;
-        }
-    };
-    // Start both transports
-    await stdio.start();
-    // Connect SSE with reconnect loop
+    // Connect SSE with reconnect loop — stdio starts AFTER first successful connection
     await connectWithReconnect();
     /** Attempt SSE connection with exponential backoff on failure. */
     async function connectWithReconnect() {
@@ -115,10 +105,17 @@ export async function startProxy(sseUrl, token) {
                     process.stderr.write(`Pharaoh: reconnecting in ${delay / 1000}s (attempt ${reconnectAttempt}/${BACKOFF_MS.length})...\n`);
                     await sleep(delay);
                     sse = createSSETransport(sseUrl, token);
-                    bridge(sse);
                 }
                 await sse.start();
                 reconnectAttempt = 0; // Reset on successful connection
+                // Bridge AFTER SSE is connected — messages can now be forwarded
+                bridge(sse);
+                // Start stdio AFTER first SSE connection — prevents initialize race
+                if (!stdioStarted) {
+                    process.stderr.write("Pharaoh: connected\n");
+                    await stdio.start();
+                    stdioStarted = true;
+                }
                 // Wait for close — this promise resolves when SSE disconnects
                 await new Promise((resolve, reject) => {
                     sse.onclose = () => resolve();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pharaoh-so/mcp",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Stdio-to-SSE proxy for Pharaoh MCP — enables headless environments (VPS, SSH, CI) via device flow auth",
   "type": "module",
   "main": "dist/index.js",