@pharaoh-so/mcp 0.3.46 → 0.3.50

package/.mcp.json

@@ -2,7 +2,9 @@
 	"mcpServers": {
 		"pharaoh": {
 			"command": "npx",
-			"args": ["@pharaoh-so/mcp"]
+			"args": [
+				"@pharaoh-so/mcp@0.3.50"
+			]
 		}
 	}
 }

package/CHANGELOG.md

@@ -5,6 +5,35 @@ All notable changes to `@pharaoh-so/mcp` will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.50] - 2026-10-20
+
+### Changed
+- Tighten Trace card spacing without shrinking text or hiding evidence.
+- Stop requesting a duplicate ASCII panel when a usable Trace view is attached. Keep the complete insight available to the agent and preserve text-only output.
+
+## [0.3.49] - 2026-10-20
+
+### Changed
+- Publish from the standalone public source repository with npm provenance, after the reviewed source passes its required checks.
+- Include the test runtime needed to validate the package independently.
+
+## [0.3.48] - 2026-10-20
+
+### Added
+- Compact Trace views for supporting MCP App clients, with expandable evidence, yellow bars and green success markers. Existing text results remain available.
+- The same static Trace resource before and after sign-in. Resource reads do not start device authentication, and view data comes only from authorized tool results.
+
+## [Unreleased]
+
+Security review of 2026-10-17 (findings SC-2, SC-6, SC-7, SC-8, SC-9). See README § Security for what the installer writes.
+
+### Changed
+- The interactive setup allow-lists Pharaoh's six read-only tools and `pharaoh_account` by full name in `~/.claude/settings.json`, only when that file already exists, and says so. It replaces the blanket `mcp__pharaoh` rule earlier versions wrote on every start, which also auto-approved account deletion and `pharaoh_admin`. Proxy starts no longer touch permissions.
+- Slash command files in `~/.claude/commands/` are written only when absent or Pharaoh's own (front-matter marker `# managed-by: pharaoh-mcp`, or the header and `$ARGUMENTS` footer of an earlier install). A user's file with the same name is kept and named in the output; symlinks are never followed.
+- `~/.pharaoh` is created `0700` and set to `0700` on every start, whichever path creates it first.
+- Every registration (`claude mcp add`, OpenClaw, the shipped `.mcp.json`) runs `npx @pharaoh-so/mcp@<the installed version>`. Upgrading is `npx @pharaoh-so/mcp@latest`; the interactive setup prints a hint when the registry has a newer version.
+- `package.json` `repository` names the building repository. The release workflow requests npm provenance when the source repository is public; private-source releases publish without it.
+
 ## [0.1.5] - 2026-03-24
 
 ### Added

package/README.md

@@ -129,10 +129,10 @@ npx @pharaoh-so/mcp --logout
 
 ### Custom Server
 
-For self-hosted Pharaoh instances or development, register manually:
+For self-hosted Pharaoh instances or development, register manually, pinned to a version (`npx @pharaoh-so/mcp --version` prints the one you have):
 
 ```bash
-claude mcp add --scope user pharaoh -- npx @pharaoh-so/mcp --server https://your-pharaoh-instance.com
+claude mcp add --scope user pharaoh -- npx @pharaoh-so/mcp@<version> --server https://your-pharaoh-instance.com
 ```
 
 ### Environment Variables
@@ -155,6 +155,33 @@ claude mcp add --scope user pharaoh -- npx @pharaoh-so/mcp --server https://your
 - The proxy never reads or sends your local files. Pharaoh reads your code from GitHub through its GitHub App, maps it into a knowledge graph of structural metadata (function names, file paths, dependency relationships), and deletes the clone when mapping ends.
 - Tokens expire after 7 days and are refreshed automatically
 - Only use trusted server URLs — the proxy sends your auth token to the configured server
+- No telemetry. The proxy's only network calls are the device flow, token refresh, the MCP connection, and one registry lookup during interactive setup (below).
+
+### What the installer writes on your machine
+
+`npx @pharaoh-so/mcp` in a terminal is the interactive setup. Every later proxy start (Claude Code launching the server) repeats the plugin, skill and command steps so a new version takes effect, and nothing else.
+
+| Path | Mode | When | What |
+|------|------|------|------|
+| `~/.pharaoh/` | `0700`, set again on every start | Always | Credentials and the Claude Code plugin marketplace |
+| `~/.pharaoh/credentials.json` | `0600` | After sign-in | Access token, refresh token, expiry |
+| `~/.pharaoh/claude-marketplace/` | — | `~/.claude/` exists | The one-plugin marketplace Claude Code installs as `pharaoh@pharaoh`: the skills and the Grep routing hook. Rewritten when the package version changes |
+| `~/.claude/commands/plan.md`, `review.md`, `sessions.md` | — | `~/.claude/` exists | Slash commands. A file is written only when it is absent or is Pharaoh's: it carries the front-matter comment `# managed-by: pharaoh-mcp`, or has the exact header and `$ARGUMENTS` footer of a Pharaoh command from 0.3.46 or earlier. Any other file with that name is yours: it is kept, a symlink is never followed, and the setup output names it. Rename your file to keep both |
+| `~/.claude.json` | — | Interactive setup | Removes earlier `pharaoh` entries, then `claude mcp add --scope user pharaoh -- npx @pharaoh-so/mcp@<version>` |
+| `~/.claude/settings.json` | — | Interactive setup, and only if the file already exists | Adds to `permissions.allow`, each by full name: `mcp__pharaoh__get_codebase_map`, `mcp__pharaoh__get_module_context`, `mcp__pharaoh__search_functions`, `mcp__pharaoh__get_blast_radius`, `mcp__pharaoh__get_unused_code`, `mcp__pharaoh__pharaoh_recon`, `mcp__pharaoh__pharaoh_account`. The setup prints a line saying what it did. The proxy never creates this file and never touches it on a start |
+| `~/.openclaw/skills/`, `~/.openclaw/openclaw.json` | — | `~/.openclaw/` exists | Skills prefixed `pharaoh-`, and an `mcpServers.pharaoh` entry running `npx @pharaoh-so/mcp@<version>`. An entry that is not an `npx @pharaoh-so/mcp` command is left alone |
+
+Versions 0.3.46 and earlier wrote one rule, `mcp__pharaoh`, on every proxy start. That prefix auto-approved every Pharaoh tool, including account deletion and `pharaoh_admin`, so a prompt injection could run them without a human prompt. The next interactive setup replaces that rule with the list above; account deletion, `pharaoh_admin` and any tool not listed prompt before they run. To take the blanket rule out by hand, delete `mcp__pharaoh` from `permissions.allow`.
+
+### Pinned version and upgrades
+
+Every registration the setup writes runs the exact version that wrote it (`npx @pharaoh-so/mcp@<version>`). A new release on npm changes nothing on your machine until you upgrade:
+
+```bash
+npx @pharaoh-so/mcp@latest
+```
+
+This signs you in again, rewrites the registration with the new version and refreshes the plugin. The interactive setup asks the npm registry for the newest version and prints a one-line hint when there is one; proxy starts never check.
 
 ### Reporting Vulnerabilities
 

package/dist/backend.d.ts

@@ -15,7 +15,7 @@
  * resolves each tool call's handler at request-arrival time, so in-flight
  * calls complete against whichever backend started them.
  */
-import type { CallToolResult, Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { CallToolResult, ClientCapabilities, Tool } from "@modelcontextprotocol/sdk/types.js";
 import type { DeviceFlowGateway } from "./gateway.js";
 /** The contract ProxyServer uses to delegate tool handling. */
 export interface Backend {
@@ -32,6 +32,8 @@ export interface Backend {
      * act on. Backends without a supervisor loop (AuthRequiredBackend) omit this.
      */
     waitForExit?(): Promise<void>;
+    /** Return an unstarted replacement only if the negotiated UI support changed. */
+    withClientCapabilities?(capabilities: ClientCapabilities): Backend;
 }
 /**
  * Pre-auth backend. Every tool call triggers a device-flow state step via the
@@ -75,7 +77,9 @@ export declare class SseProxyBackend implements Backend {
     private transport;
     private stopped;
     private reconnectPromise;
-    constructor(sseUrl: string, token: string);
+    private readonly clientCapabilities;
+    constructor(sseUrl: string, token: string, capabilities?: ClientCapabilities);
+    withClientCapabilities(capabilities: ClientCapabilities): Backend;
     start(): Promise<void>;
     /**
      * Expose the long-running reconnect loop so a supervisor can await it.

package/dist/backend.js

@@ -19,6 +19,7 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { loadBundledCatalog } from "./catalog.js";
 import { classifySSEError, TenantSuspendedError, TokenExpiredError } from "./proxy.js";
+import { TRACE_MIME_TYPE } from "./trace-resource.js";
 import { getPackageVersion } from "./version.js";
 /**
  * Pre-auth backend. Every tool call triggers a device-flow state step via the
@@ -143,9 +144,23 @@ export class SseProxyBackend {
     transport = null;
     stopped = false;
     reconnectPromise = null;
-    constructor(sseUrl, token) {
+    clientCapabilities;
+    constructor(sseUrl, token, capabilities = {}) {
         this.sseUrl = sseUrl;
         this.token = token;
+        // The proxy can deliver only this static UI extension. Advertising other
+        // capabilities (sampling, elicitation, etc.) would promise unsupported RPCs.
+        const ui = capabilities.extensions?.["io.modelcontextprotocol/ui"];
+        this.clientCapabilities =
+            Array.isArray(ui?.mimeTypes) && ui.mimeTypes.includes(TRACE_MIME_TYPE)
+                ? { extensions: { "io.modelcontextprotocol/ui": { mimeTypes: [TRACE_MIME_TYPE] } } }
+                : {};
+    }
+    withClientCapabilities(capabilities) {
+        const next = new SseProxyBackend(this.sseUrl, this.token, capabilities);
+        return JSON.stringify(next.clientCapabilities) === JSON.stringify(this.clientCapabilities)
+            ? this
+            : next;
     }
     async start() {
         if (this.client)
@@ -169,9 +184,29 @@ export class SseProxyBackend {
         return this.reconnectPromise ?? Promise.resolve();
     }
     async connectOnce() {
-        this.transport = createSSETransport(this.sseUrl, this.token);
-        this.client = new Client({ name: "pharaoh-proxy", version: getPackageVersion() }, { capabilities: {} });
-        await this.client.connect(this.transport);
+        const transport = createSSETransport(this.sseUrl, this.token);
+        const client = new Client({ name: "pharaoh-proxy", version: getPackageVersion() }, { capabilities: this.clientCapabilities });
+        this.transport = transport;
+        this.client = client;
+        try {
+            await client.connect(transport);
+        }
+        catch (error) {
+            // A failed warm capability handshake must not leave EventSource's
+            // automatic retries alive beside the previous backend.
+            await client.close().catch(() => {
+                process.stderr.write("Pharaoh: failed SSE connection cleanup\n");
+            });
+            if (this.transport === transport)
+                this.transport = null;
+            if (this.client === client)
+                this.client = null;
+            // Initial and negotiated connects need the same typed auth recovery
+            // as reconnects. Generic failures still surface to the caller.
+            if (error instanceof Error)
+                classifySSEError(error);
+            throw error;
+        }
     }
     /** Wait for the current transport to close, then decide what to do. */
     waitForClose() {
@@ -204,6 +239,8 @@ export class SseProxyBackend {
         const delay = BACKOFF_MS[attempt - 1];
         process.stderr.write(`Pharaoh: reconnecting in ${delay / 1000}s (attempt ${attempt}/${BACKOFF_MS.length})...\n`);
         await sleep(delay);
+        if (this.stopped)
+            return;
         await this.connectOnce();
         process.stderr.write("Pharaoh: reconnected\n");
     }
@@ -213,6 +250,8 @@ export class SseProxyBackend {
         while (!this.stopped) {
             try {
                 await this.waitForClose();
+                if (this.stopped)
+                    return;
                 attempt++;
                 if (attempt > BACKOFF_MS.length) {
                     process.stderr.write("Pharaoh: max reconnect attempts reached — exiting\n");

package/dist/credentials.d.ts

@@ -46,6 +46,15 @@ export declare function writeCredentials(creds: Credentials, path?: string): voi
  * @throws If the lock stays held for LOCK_WAIT_MS, or a stale lock can't be removed.
  */
 export declare function acquireCredentialsLock(path?: string): Promise<() => void>;
+/**
+ * Create `~/.pharaoh` with mode 0700 and set that mode again if it already
+ * exists. The one place the directory is created, whichever path gets there
+ * first (credentials or the Claude Code plugin marketplace), so it is never
+ * left world-readable (security review SC-8).
+ *
+ * @param dir - The directory (defaults to `~/.pharaoh`).
+ */
+export declare function ensurePharaohHome(dir?: string): void;
 /** Delete the credential file. No-op if it doesn't exist. */
 export declare function deleteCredentials(path?: string): void;
 /**

package/dist/credentials.js

@@ -6,7 +6,7 @@
  * refreshes take a lock (acquireCredentialsLock) and writes are atomic.
  */
 import { randomUUID } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
@@ -147,12 +147,21 @@ function lockAgeMs(lockPath) {
         return 0; // released between our create attempt and this stat — retry immediately
     }
 }
-/** Create the credentials directory (0700) if it doesn't exist. */
+/**
+ * Create `~/.pharaoh` with mode 0700 and set that mode again if it already
+ * exists. The one place the directory is created, whichever path gets there
+ * first (credentials or the Claude Code plugin marketplace), so it is never
+ * left world-readable (security review SC-8).
+ *
+ * @param dir - The directory (defaults to `~/.pharaoh`).
+ */
+export function ensurePharaohHome(dir = join(homedir(), ".pharaoh")) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    chmodSync(dir, 0o700);
+}
+/** Create the directory holding a credentials file (0700). */
 function ensureDir(path) {
-    const dir = dirname(path);
-    if (!existsSync(dir)) {
-        mkdirSync(dir, { recursive: true, mode: 0o700 });
-    }
+    ensurePharaohHome(dirname(path));
 }
 /** Delete the credential file. No-op if it doesn't exist. */
 export function deleteCredentials(path = CREDENTIALS_PATH) {

package/dist/index.js

@@ -17,11 +17,12 @@ import { AuthRequiredBackend, createSseBackend } from "./backend.js";
 import { deleteCredentials, readCredentials, writeCredentials, } from "./credentials.js";
 import { createGateway } from "./gateway.js";
 import { formatTtl, parseArgs, printLines, printUsage, resolveSseUrl, tokenToCredentials, } from "./helpers.js";
-import { runInstallSkills } from "./install-skills.js";
+import { allowReadTools, describeAllowReadTools, formatKeptCommands, runInstallSkills, } from "./install-skills.js";
 import { handleRefreshFailure, tryMidSessionRefresh } from "./lifecycle.js";
 import { TenantSuspendedError, TokenExpiredError } from "./proxy.js";
 import { startInAuthRequiredMode, startInSseMode } from "./proxy-server.js";
 import { loadAndRefresh } from "./refresh.js";
+import { fetchLatestVersion, getPackageVersion, isNewerVersion, UPGRADE_COMMAND, } from "./version.js";
 const BANNER = [
     "",
     "  ___  _  _   _   ___    _    ___  _  _ ",
@@ -90,8 +91,22 @@ async function main() {
         process.stderr.write("  Setting up...");
         const { runSetup } = await import("./setup.js");
         runSetup({ silent: true });
-        runInstallSkills(undefined, { silent: true });
+        const { keptCommands } = runInstallSkills(undefined, { silent: true });
         process.stderr.write(" done.\n");
+        // Two things the user must hear about: their settings.json (the only
+        // place this setup edits permissions, never a silent start) and any
+        // command file of theirs that was left alone.
+        printLines(describeAllowReadTools(allowReadTools()));
+        const kept = formatKeptCommands(keptCommands);
+        if (kept)
+            printLines(kept);
+        // The registration is pinned to this version; upgrading is a deliberate
+        // re-run. Interactive only, and quiet when the registry can't be reached.
+        const latest = await fetchLatestVersion();
+        const running = getPackageVersion();
+        if (latest && isNewerVersion(latest, running)) {
+            printLines(`Pharaoh: ${latest} is available (this is ${running}). Upgrade: ${UPGRADE_COMMAND}`);
+        }
         printLines("", "Pharaoh is ready. Try these in a new Claude Code conversation:", "", '  "What modules does this codebase have?"', '  "Search for functions related to authentication"', '  "What breaks if I change this file?"', "");
         process.exit(0);
     }

package/dist/inspect.js

@@ -11,6 +11,7 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { loadBundledCatalog } from "./catalog.js";
+import { registerTraceResource } from "./trace-resource.js";
 import { getPackageVersion } from "./version.js";
 const INSPECT_MSG = "This is Pharaoh's inspection server for directory listings. " +
     "Connect to https://mcp.pharaoh.so for actual usage.";
@@ -29,5 +30,6 @@ export async function runInspect() {
     server.setRequestHandler(CallToolRequestSchema, async () => ({
         content: [{ type: "text", text: INSPECT_MSG }],
     }));
+    registerTraceResource(server);
     await server.connect(new StdioServerTransport());
 }

package/dist/install-skills.d.ts

@@ -1,3 +1,4 @@
+import { type ClaudeCli } from "./setup.js";
 /**
  * Detect whether OpenClaw is installed by checking for ~/.openclaw/.
  *
@@ -5,8 +6,6 @@
  * @returns True if ~/.openclaw/ exists.
  */
 export declare function detectOpenClaw(home?: string): boolean;
-/** Runs one `claude` CLI command; true on success. */
-type ClaudeCli = (args: string[]) => boolean;
 /**
  * Uninstall Pharaoh's Claude Code plugin: through the CLI, then the local
  * marketplace directory and any pre-marketplace install.
@@ -15,6 +14,22 @@ type ClaudeCli = (args: string[]) => boolean;
  * @param claude - `claude` CLI runner (defaults to the real CLI for `home`).
  */
 export declare function uninstallClaudePlugin(home?: string, claude?: ClaudeCli): void;
+/**
+ * Marker the installer writes into the front-matter of every command file it
+ * installs, as a YAML comment Claude Code ignores. A file in
+ * `~/.claude/commands/` is rewritten only when it is Pharaoh's: it carries
+ * this marker, or the exact header and `$ARGUMENTS` footer every installer
+ * before the marker shipped. Any other file with the same name is the user's
+ * and is left alone (security review SC-7).
+ */
+export declare const PHARAOH_COMMAND_MARKER = "# managed-by: pharaoh-mcp";
+/**
+ * The one-line notice for command files the installer left alone, or null
+ * when there were none.
+ *
+ * @param kept - File names from `runInstallSkills().keptCommands`.
+ */
+export declare function formatKeptCommands(kept: readonly string[]): string | null;
 /**
  * Install bundled skills to `~/.openclaw/skills/` with the same `pharaoh-`
  * prefix that Claude Code installs use. Keeps naming consistent across both
@@ -28,26 +43,64 @@ export declare function uninstallClaudePlugin(home?: string, claude?: ClaudeCli)
  */
 export declare function installSkills(home?: string): number;
 /**
- * Read ~/.openclaw/openclaw.json, add the Pharaoh MCP server under `mcpServers`,
- * and write it back. Creates the file if it does not exist. Does NOT overwrite
- * an existing `pharaoh` entry — skips if already present.
+ * Read ~/.openclaw/openclaw.json, set the Pharaoh MCP server under `mcpServers`
+ * to `npx @pharaoh-so/mcp@<this version>`, and write it back. Creates the file
+ * if it does not exist. An existing `pharaoh` entry is re-pinned when it is an
+ * `npx @pharaoh-so/mcp` command (extra arguments kept) and left alone when it
+ * is anything else.
  *
  * @param home - Home directory override (defaults to os.homedir()).
- * @returns True if the config was written/updated, false if pharaoh was already present.
+ * @returns True if the config was written, false if it was already current or is not ours.
  */
 export declare function mergeOpenClawConfig(home?: string): boolean;
 /**
- * Main entry point for --install-skills.
+ * Rules the interactive setup adds to `permissions.allow` in
+ * ~/.claude/settings.json: the six read-only tools and `pharaoh_account`,
+ * each by full name. Never a prefix rule — `mcp__pharaoh` also auto-approves
+ * account deletion and `pharaoh_admin`, so a prompt injection could run them
+ * with no human in the loop (security review SC-6). Those tools keep prompting.
+ */
+export declare const PHARAOH_ALLOW_RULES: readonly string[];
+/** What `allowReadTools` did to ~/.claude/settings.json. */
+export type AllowReadToolsResult = "added" | "migrated" | "current" | "no-settings" | "error";
+/**
+ * Add `PHARAOH_ALLOW_RULES` to `permissions.allow` in ~/.claude/settings.json,
+ * replacing the blanket `mcp__pharaoh` rule an earlier version wrote. Runs
+ * only from the interactive setup, which prints what happened; never on a
+ * proxy start. Never creates the file: with no settings.json the tools
+ * simply prompt on first use.
+ *
+ * @param home - Home directory override (defaults to os.homedir()).
+ * @returns "added" or "migrated" when the file was written, "current" when
+ *   nothing was missing, "no-settings" when there is no file, "error" when
+ *   the file is not valid JSON (left untouched).
+ */
+export declare function allowReadTools(home?: string): AllowReadToolsResult;
+/**
+ * The line the interactive setup prints for an `allowReadTools` result, so
+ * the user always learns what was done to their settings.
+ *
+ * @param result - What `allowReadTools` returned.
+ */
+export declare function describeAllowReadTools(result: AllowReadToolsResult): string;
+/** What `runInstallSkills` wants the caller to tell the user. */
+export interface InstallResult {
+    /** Files in ~/.claude/commands/ left as they were because they are not Pharaoh's. */
+    keptCommands: string[];
+}
+/**
+ * Main entry point for --install-skills, also run on every proxy start.
  *
  * Detection priority: Claude Code > OpenClaw > manual instructions.
- * Installs to all detected platforms (a user may use both).
+ * Installs to all detected platforms (a user may use both). Never touches
+ * Claude Code permissions: that is `allowReadTools`, interactive setup only.
  *
  * @param home - Home directory override (defaults to os.homedir()).
  * @param options.silent - Print nothing (the interactive setup prints its own summary).
  * @param options.claude - `claude` CLI runner (defaults to the real CLI for `home`).
+ * @returns What was kept, for the caller's own summary.
  */
 export declare function runInstallSkills(home?: string, options?: {
     silent?: boolean;
     claude?: ClaudeCli;
-}): void;
-export {};
+}): InstallResult;