@pharaoh-so/mcp 0.2.12 → 0.3.1

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.1",
   "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/audit-tests/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: audit-tests
+prompt-name: audit-tests
 description: "Classify tests by real value: ceremony versus protection. Mutation score over line coverage — tests that can't detect mutations are theater. Identify tests that prove nothing, tests that duplicate coverage, and gaps where real protection is missing. Produce an actionable audit with keep, rewrite, and delete verdicts."
 version: 0.2.0
 homepage: https://pharaoh.so

package/skills/brainstorm/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: brainstorm
+prompt-name: brainstorm
 description: "Explore intent, requirements, and design before implementation. Collaborative dialogue to turn ideas into specs. Ask clarifying questions one at a time, propose 2-3 approaches with trade-offs, get approval before writing any code. Prevents wasted work from unexamined assumptions."
 version: 0.2.0
 homepage: https://pharaoh.so

package/skills/debt/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: debt
+prompt-name: find-tech-debt
 description: "Categorized technical debt report using Pharaoh knowledge graph. Four-step pro-tier workflow: dead code detection, duplicate logic discovery, undocumented complex functions via spec gaps, and volatile high-complexity module identification. Categorizes findings as DELETE, CONSOLIDATE, DOCUMENT, STABILIZE, or TEST — each with the specific function or file, effort estimate, and risk of ignoring."
 version: 0.2.0
 homepage: https://pharaoh.so

package/skills/debug/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: debug
+prompt-name: systematic-debugging
 description: "Systematic 4-phase debugging methodology. Root cause investigation before any fixes. Read errors carefully, reproduce consistently, trace data flow, form hypotheses, test minimally. If 3+ fixes fail, question the architecture. No guessing, no quick patches, no symptom fixes."
 version: 0.2.0
 homepage: https://pharaoh.so

package/skills/execute/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: execute
+prompt-name: execute-plan
 description: "Execute a written implementation plan with review checkpoints. Load plan, review critically, execute tasks sequentially with verification at each step. Stop and ask when blocked — never guess through ambiguity. Finish with branch completion workflow."
 version: 0.2.0
 homepage: https://pharaoh.so

package/skills/explore/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: explore
+prompt-name: explore-module
 description: "Deep-dive into a single codebase module using Pharaoh knowledge graph. Four-step free-tier workflow: full structure with functions, exports, and complexity scores; blast radius of what depends on it; upstream and downstream dependency mapping; and related function discovery. Produces a module briefing with purpose, key functions, dependencies, risk areas, and external API surface."
 version: 0.2.0
 homepage: https://pharaoh.so

package/skills/finish/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: finish
+prompt-name: finish-branch
 description: "Complete a development branch after implementation. Verify all tests pass, present structured options (merge locally, create PR, keep branch, or discard), execute the chosen workflow, and clean up worktrees. Never merge broken code or delete work without confirmation."
 version: 0.2.0
 homepage: https://pharaoh.so

package/skills/health/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: health
+prompt-name: health-check
 description: "Full codebase health sweep using Pharaoh knowledge graph. Six-step pro-tier workflow: module map with metrics, dead code detection, test coverage gaps, duplicate logic, regression risk scoring, and spec drift analysis. Produces an A-F grade, top 5 risks, tech debt hotspots (high-complexity + low-coverage + high-volatility intersections), spec drift summary, and prioritized actions with effort estimates."
 version: 0.2.0
 homepage: https://pharaoh.so

package/skills/investigate/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: investigate
+prompt-name: investigate-change
 description: "Full architectural context gathering before modifying a function, file, or module using Pharaoh knowledge graph. Four-step free-tier workflow: module structure, blast radius of downstream callers, related function discovery, and dependency mapping. Blocks code suggestions until all context is gathered. Produces an investigation report with structure, blast radius, related functions, dependency context, and risk assessment."
 version: 0.2.0
 homepage: https://pharaoh.so

package/skills/onboard/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: onboard
+prompt-name: onboard-to-codebase
 description: "Quick codebase orientation using Pharaoh knowledge graph. Five-step workflow using only free-tier tools: full module map, deep-dive into the three largest modules, entry point discovery, critical path blast radius, and core data flow mapping. Produces an onboarding summary with module descriptions, entry points, data flow, and key functions to read first."
 version: 0.2.0
 homepage: https://pharaoh.so

package/skills/orchestrate/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: orchestrate
+prompt-name: orchestrate-plan
 description: "Execute implementation plans by dispatching one subagent per task with two-stage review (spec compliance then code quality). Sequential task execution with quality gates. Controller stays in session, constructs focused context for each agent, never shares session history. Handles DONE/DONE_WITH_CONCERNS/NEEDS_CONTEXT/BLOCKED status protocol."
 version: 0.2.5
 homepage: https://pharaoh.so

package/skills/parallel/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: parallel
+prompt-name: parallel-agents
 description: "Dispatch 2+ independent subagent tasks that run concurrently. Each agent gets focused scope, clear goal, constraints, and expected output. No shared state between agents. Review and integrate results after all complete."
 version: 0.2.0
 homepage: https://pharaoh.so

package/skills/pharaoh/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: pharaoh
+prompt-name: pharaoh-core
 description: "Codebase knowledge graph — gives AI agents full architectural awareness. Query architecture, dependencies, blast radius, module context, and function search instead of reading files one at a time. Code intelligence via MCP: understand any codebase in seconds."
 version: 0.3.0
 homepage: https://pharaoh.so
@@ -70,12 +71,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
 ```

package/skills/plan/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: plan
+prompt-name: plan-with-pharaoh
 description: "Full-cycle architecture-aware planning: Pharaoh reconnaissance, structured plan writing with bite-sized TDD steps and zero placeholders, then deep adversarial review with wiring verification and interactive issue resolution. Replaces both writing-plans and plan-review."
 version: 0.3.0
 homepage: https://pharaoh.so

package/skills/pr/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: pr
+prompt-name: pre-pr-review
 description: "Pre-pull-request architectural review checklist using Pharaoh codebase knowledge graph. Covers module context, blast radius per touched module, hidden coupling between modules, duplicate logic detection, regression risk scoring, and vision spec alignment. Produces a structured review summary before opening a PR."
 version: 0.2.0
 homepage: https://pharaoh.so

package/skills/refactor/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: refactor
+prompt-name: safe-refactor
 description: "Safe refactoring workflow using Pharaoh codebase knowledge graph. Six-step process: module context, blast radius of downstream callers, reachability verification, dependency mapping, naming conflict detection, and test coverage assessment. Produces a refactoring plan with every caller listed, test files identified, unreachable code flagged, and high-risk paths warned."
 version: 0.2.0
 homepage: https://pharaoh.so

package/skills/review/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: review
+prompt-name: review-with-pharaoh
 description: "Architecture-aware pre-PR code review using Pharaoh codebase knowledge graph. Four-phase workflow: context gathering with module structure and blast radius, risk assessment with regression scoring and wiring checks, spec alignment against vision docs, and a final verdict of SHIP / SHIP WITH CHANGES / BLOCK. Auto-block rules for unreachable exports, circular dependencies, high regression risk, and spec violations."
 version: 0.2.0
 homepage: https://pharaoh.so

package/skills/review-codex/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: review-codex
+prompt-name: cross-model-review
 description: "Cross-model security review. Dispatch code to a different AI model or subagent for independent second-opinion review. Evaluator applies AGREE, DISAGREE, or CONTEXT verdicts to each finding. Catches blind spots from single-model reasoning. Use for security-sensitive code, auth flows, data access, and architectural decisions."
 version: 0.2.0
 homepage: https://pharaoh.so

package/skills/review-receive/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: review-receive
+prompt-name: receive-code-review
 description: "Receive code review feedback with technical rigor. No performative agreement — verify suggestions against codebase reality before implementing. Push back with evidence when feedback is wrong. Clarify all unclear items before implementing any. External feedback is suggestions to evaluate, not orders to follow."
 version: 0.2.0
 homepage: https://pharaoh.so

package/skills/sessions/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: sessions
+prompt-name: session-decomposition
 description: "Decompose work into parallel, isolated sessions using git worktrees. Each session gets fresh context, a narrow scope, and produces atomic commits. Prevents context window pollution from large tasks. Coordinate across sessions without shared state."
 version: 0.2.0
 homepage: https://pharaoh.so

package/skills/tdd/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: tdd
+prompt-name: test-driven-development
 description: "Test-driven development discipline. Write the failing test first, watch it fail, write minimal code to pass, refactor. No production code without a failing test. No exceptions without explicit permission. Covers red-green-refactor cycle, common rationalizations, and when to start over."
 version: 0.2.0
 homepage: https://pharaoh.so

package/skills/verify/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: verify
+prompt-name: verification
 description: "Evidence before assertions. Run verification commands and confirm output before claiming work is complete, fixed, or passing. No 'should work now' — run the command, read the output, then claim the result. Covers tests, builds, linting, agent delegation, and requirement checklists."
 version: 0.2.0
 homepage: https://pharaoh.so

package/skills/wiring/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: wiring
+prompt-name: validate-wiring
 description: "Wiring validation for a codebase module using Pharaoh knowledge graph. Four-step pro-tier workflow: entry point reachability, caller verification via blast radius, test coverage per function, and dead code detection. Categorizes functions as CONNECTED, UNREACHABLE, DEAD, or UNTESTED. Produces a PASS or FAIL verdict with specific issues listed. Iron law: zero callers on a non-entry-point export means the code is not wired."
 version: 0.2.0
 homepage: https://pharaoh.so

package/skills/worktree/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: worktree
+prompt-name: git-worktree
 description: "Set up isolated git worktrees for feature work. Smart directory selection with safety verification — checks for existing worktree directories, verifies gitignore, auto-detects project setup, and confirms clean test baseline before starting. Prevents accidentally committing worktree contents."
 version: 0.2.0
 homepage: https://pharaoh.so