@pharaoh-so/mcp 0.2.12 → 0.3.0

package/README.md

@@ -26,7 +26,7 @@ This displays a device code and a URL. Open the URL on **any device** (phone, la
 ### Step 2 — Add to Claude Code
 
 ```bash
-claude mcp add pharaoh -- npx @pharaoh-so/mcp
+npx @pharaoh-so/mcp --setup
 ```
 
 Verify the connection:
@@ -43,19 +43,9 @@ If you previously added Pharaoh as an SSE server, remove it first:
 
 ```bash
 claude mcp remove pharaoh
-claude mcp add pharaoh -- npx @pharaoh-so/mcp
+npx @pharaoh-so/mcp --setup
 ```
 
-### Desktop with Browser (Alternative)
-
-If you have a browser available (desktop, laptop), you can connect directly via SSE instead:
-
-```bash
-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.
-
 ## How It Works
 
 ```
@@ -156,10 +146,10 @@ npx @pharaoh-so/mcp --logout
 
 ### Custom Server
 
-For self-hosted Pharaoh instances or development:
+For self-hosted Pharaoh instances or development, register manually:
 
 ```bash
-claude mcp add pharaoh -- npx @pharaoh-so/mcp --server https://your-pharaoh-instance.com
+claude mcp add --scope user pharaoh -- npx @pharaoh-so/mcp --server https://your-pharaoh-instance.com
 ```
 
 ### Environment Variables
@@ -213,7 +203,7 @@ npx @pharaoh-so/mcp
 Make sure you added it with the correct command:
 
 ```bash
-claude mcp add pharaoh -- npx @pharaoh-so/mcp
+npx @pharaoh-so/mcp --setup
 ```
 
 Note the `--` separator between `pharaoh` and `npx`.
@@ -230,7 +220,7 @@ The first run after installation may take a moment as npm downloads the package.
 
 ```bash
 npm install -g @pharaoh-so/mcp
-claude mcp add pharaoh -- pharaoh-mcp
+claude mcp add --scope user pharaoh -- pharaoh-mcp
 ```
 
 ## How Pharaoh Works

package/dist/helpers.d.ts

@@ -10,6 +10,7 @@ export declare function printLines(...lines: string[]): void;
 export declare function parseArgs(argv?: string[]): {
     server: string;
     logout: boolean;
+    setup: boolean;
 };
 export declare function printUsage(): void;
 /**

package/dist/helpers.js

@@ -8,6 +8,7 @@ export function printLines(...lines) {
 export function parseArgs(argv = process.argv.slice(2)) {
     let server = DEFAULT_SERVER;
     let logout = false;
+    let setup = false;
     for (let i = 0; i < argv.length; i++) {
         if (argv[i] === "--server" && argv[i + 1]) {
             server = argv[i + 1];
@@ -16,6 +17,9 @@ export function parseArgs(argv = process.argv.slice(2)) {
         else if (argv[i] === "--logout") {
             logout = true;
         }
+        else if (argv[i] === "--setup") {
+            setup = true;
+        }
     }
     // Strip trailing slash
     server = server.replace(/\/+$/, "");
@@ -37,10 +41,10 @@ export function parseArgs(argv = process.argv.slice(2)) {
         printLines(`Pharaoh: --server is not a valid URL: ${server}`);
         process.exit(1);
     }
-    return { server, logout };
+    return { server, logout, setup };
 }
 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", "  --install-skills  Force reinstall Pharaoh skills (Claude Code + OpenClaw)", "  --help, -h        Show this help", "", "Add to Claude Code:", "  claude mcp add pharaoh -- npx @pharaoh-so/mcp", "");
+    printLines("Usage: pharaoh-mcp [options]", "", "Options:", "  --setup           Full install: auth, register MCP, install skills (start here)", "  --server <url>    Pharaoh server URL (default: https://mcp.pharaoh.so)", "  --logout          Clear stored credentials and exit", "  --install-skills  Force reinstall Pharaoh skills (Claude Code + OpenClaw)", "  --help, -h        Show this help", "", "Get started:", "  npx @pharaoh-so/mcp --setup", "");
 }
 /**
  * Validate that a server-supplied SSE URL shares the same origin as the configured server.
@@ -96,7 +100,7 @@ export function formatTtl(expiresAt) {
  * 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                                    │", "└───────────────────────────────────────────────────────┘", "");
+    printLines("", "┌───────────────────────────────────────────────────────┐", "│  To register Pharaoh in Claude Code, run:             │", "│    npx @pharaoh-so/mcp --setup                       │", "│                                                       │", "│  This removes stale entries, registers the MCP        │", "│  server globally, and installs all skills.            │", "└───────────────────────────────────────────────────────┘", "");
 }
 /** Format a credential identity string (e.g. "alice (my-org)"). */
 export function formatIdentity(creds) {

package/dist/index.js

@@ -33,7 +33,7 @@ async function main() {
         runInstallSkills();
         return;
     }
-    const { server, logout } = parseArgs(args);
+    const { server, logout, setup } = parseArgs(args);
     if (logout) {
         deleteCredentials();
         printLines("Pharaoh: credentials cleared");
@@ -41,6 +41,36 @@ async function main() {
     }
     const creds = readCredentials();
     const isInteractive = Boolean(process.stdin.isTTY);
+    // ── Setup mode (--setup): full automated install ──
+    // Auth → remove stale → register MCP → install skills → done.
+    if (setup) {
+        // Authenticate if needed
+        let activeCreds = creds && !isExpired(creds) ? creds : null;
+        if (activeCreds) {
+            printLines(`Pharaoh: authenticated as ${formatIdentity(activeCreds)} — token valid for ${formatTtl(activeCreds.expires_at)}`);
+        }
+        else {
+            printLines("Pharaoh: 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) {
+                printLines(`Pharaoh: provisional access — install the GitHub App to map your repos: ${token.install_url ?? ""}`);
+            }
+            const sseUrl = resolveSseUrl(token.sse_url, server);
+            const newCreds = tokenToCredentials(token, sseUrl);
+            writeCredentials(newCreds);
+            activeCreds = newCreds;
+            printAuthSuccess(token.github_login ?? null, token.tenant_name ?? null, token.repos?.length ?? 0);
+        }
+        // Register MCP server in Claude Code
+        const { runSetup } = await import("./setup.js");
+        runSetup();
+        // Install skills
+        runInstallSkills();
+        printLines("", "Pharaoh is ready. Start a new Claude Code conversation and ask:", '  "What modules does this codebase have?"', "");
+        process.exit(0);
+    }
     // ── 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.

package/dist/setup.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Full automated setup: remove stale entries, register MCP server globally,
+ * install skills. Requires valid credentials (caller handles auth first).
+ *
+ * @returns true if setup succeeded, false if Claude CLI not found.
+ */
+export declare function runSetup(): boolean;

package/dist/setup.js

@@ -0,0 +1,76 @@
+/**
+ * --setup implementation for the Pharaoh MCP proxy CLI.
+ *
+ * Full automated install: authenticates via device flow, removes stale MCP
+ * entries, registers Pharaoh as a global stdio MCP server, and installs skills.
+ * One command does everything: `npx @pharaoh-so/mcp --setup`
+ */
+import { execFileSync } from "node:child_process";
+import { printLines } from "./helpers.js";
+/** Check if `claude` CLI is available in PATH. */
+function hasClaude() {
+    try {
+        const which = process.platform === "win32" ? "where" : "which";
+        execFileSync(which, ["claude"], {
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Run a claude CLI command, returning true on success. Surfaces stderr on failure. */
+function runClaude(args) {
+    try {
+        execFileSync("claude", args, {
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
+            timeout: 30_000,
+        });
+        return true;
+    }
+    catch (err) {
+        if (err && typeof err === "object" && "stderr" in err) {
+            const stderr = err.stderr?.toString().trim();
+            if (stderr)
+                printLines(`  claude ${args.slice(0, 3).join(" ")}: ${stderr}`);
+        }
+        return false;
+    }
+}
+/**
+ * Full automated setup: remove stale entries, register MCP server globally,
+ * install skills. Requires valid credentials (caller handles auth first).
+ *
+ * @returns true if setup succeeded, false if Claude CLI not found.
+ */
+export function runSetup() {
+    if (!hasClaude()) {
+        printLines("Pharaoh: Claude Code CLI not found.", "", "Install Claude Code first: https://claude.ai/download", "Then re-run: npx @pharaoh-so/mcp --setup", "");
+        return false;
+    }
+    printLines("Pharaoh: setting up...");
+    // Step 1: Remove any stale entry (ignore failures — may not exist)
+    runClaude(["mcp", "remove", "pharaoh"]);
+    // Step 2: Register as global stdio MCP server
+    const added = runClaude([
+        "mcp",
+        "add",
+        "--scope",
+        "user",
+        "pharaoh",
+        "--",
+        "npx",
+        "@pharaoh-so/mcp",
+    ]);
+    if (!added) {
+        printLines("Pharaoh: failed to register MCP server.", "Try manually: npx @pharaoh-so/mcp --setup", "");
+        return false;
+    }
+    printLines("Pharaoh: registered as global MCP server (scope: user)");
+    // Step 3: Install skills (handled by caller via runInstallSkills)
+    // We just report the MCP registration success here.
+    return true;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pharaoh-so/mcp",
   "mcpName": "so.pharaoh/pharaoh",
-  "version": "0.2.12",
+  "version": "0.3.0",
   "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

@@ -70,12 +70,12 @@ Full docs at [pharaoh.so/docs](https://pharaoh.so/docs).
 
 ## Connection options
 
-**Direct SSE** (desktop with browser, uses OAuth):
+**CLI** (Claude Code, OpenClaw — works everywhere):
 ```
-claude mcp add --transport sse --scope user pharaoh https://mcp.pharaoh.so/sse
+npx @pharaoh-so/mcp --setup
 ```
 
-**Headless** (VPS/SSH/containers, uses device flow — authorize on any device):
+**URL** (Claude.ai, Cursor, ChatGPT — paste in settings):
 ```
-claude mcp add pharaoh -- npx @pharaoh-so/mcp
+https://mcp.pharaoh.so/sse
 ```