@pharaoh-so/mcp 0.3.38 → 0.3.40

package/dist/backend.d.ts

@@ -3,9 +3,9 @@
  *
  * Two concrete implementations:
  *
- * 1. AuthRequiredBackend — advertises a single tool (`get_codebase_map`) that
- *    turns every invocation into a device-flow state step. Used while the
- *    proxy is waiting for the user to authorize.
+ * 1. AuthRequiredBackend — advertises the real tool catalog (bundled at build
+ *    time, see catalog.ts) and turns every invocation into a device-flow state
+ *    step. Used while the proxy is waiting for the user to authorize.
  *
  * 2. SseProxyBackend (returned by createSseBackend) — wraps an MCP Client
  *    connected to the remote Pharaoh SSE server. Forwards list/call requests
@@ -33,17 +33,6 @@ export interface Backend {
      */
     waitForExit?(): Promise<void>;
 }
-/**
- * Minimal pre-auth catalog. Single tool — matches Pharaoh's "call this first"
- * protocol (CLAUDE.md, skills), so the pre-auth surface mirrors the first
- * tool most agents try. Keeping this at 1 means the swap to the real catalog
- * fires a clean visible sendToolListChanged delta.
- *
- * If you add tools here, sync with src/mcp/tool-registry.ts in the main
- * package — descriptions should match so agents get consistent behavior
- * across the pre-auth / authorized transition.
- */
-export declare const AUTH_REQUIRED_TOOLS: Tool[];
 /**
  * Pre-auth backend. Every tool call triggers a device-flow state step via the
  * gateway; returns a structured auth-required response. Once the gateway
@@ -57,6 +46,11 @@ export declare class AuthRequiredBackend implements Backend {
     private readonly onAuthorized?;
     readonly name: "auth-required";
     constructor(gateway: DeviceFlowGateway, onAuthorized?: (() => Promise<void>) | undefined);
+    /**
+     * The real catalog (bundled at build time), so the agent learns every tool
+     * — and Claude Code loads the always-load ones — before sign-in. Each call
+     * returns the sign-in steps until the user authorizes.
+     */
     listTools(): Promise<Tool[]>;
     callTool(_name: string, _args: Record<string, unknown>): Promise<CallToolResult>;
 }

package/dist/backend.js

@@ -3,9 +3,9 @@
  *
  * Two concrete implementations:
  *
- * 1. AuthRequiredBackend — advertises a single tool (`get_codebase_map`) that
- *    turns every invocation into a device-flow state step. Used while the
- *    proxy is waiting for the user to authorize.
+ * 1. AuthRequiredBackend — advertises the real tool catalog (bundled at build
+ *    time, see catalog.ts) and turns every invocation into a device-flow state
+ *    step. Used while the proxy is waiting for the user to authorize.
  *
  * 2. SseProxyBackend (returned by createSseBackend) — wraps an MCP Client
  *    connected to the remote Pharaoh SSE server. Forwards list/call requests
@@ -17,34 +17,9 @@
  */
 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 { getPackageVersion } from "./version.js";
-/**
- * Minimal pre-auth catalog. Single tool — matches Pharaoh's "call this first"
- * protocol (CLAUDE.md, skills), so the pre-auth surface mirrors the first
- * tool most agents try. Keeping this at 1 means the swap to the real catalog
- * fires a clean visible sendToolListChanged delta.
- *
- * If you add tools here, sync with src/mcp/tool-registry.ts in the main
- * package — descriptions should match so agents get consistent behavior
- * across the pre-auth / authorized transition.
- */
-export const AUTH_REQUIRED_TOOLS = [
-    {
-        name: "get_codebase_map",
-        description: "Pharaoh — call this FIRST to understand the codebase structure. " +
-            "Requires authentication; calling this tool will surface the auth URL.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                repo: {
-                    type: "string",
-                    description: "Optional repo slug (owner/name) to map.",
-                },
-            },
-        },
-    },
-];
 /**
  * Pre-auth backend. Every tool call triggers a device-flow state step via the
  * gateway; returns a structured auth-required response. Once the gateway
@@ -61,8 +36,13 @@ export class AuthRequiredBackend {
         this.gateway = gateway;
         this.onAuthorized = onAuthorized;
     }
+    /**
+     * The real catalog (bundled at build time), so the agent learns every tool
+     * — and Claude Code loads the always-load ones — before sign-in. Each call
+     * returns the sign-in steps until the user authorizes.
+     */
     async listTools() {
-        return AUTH_REQUIRED_TOOLS;
+        return loadBundledCatalog().tools;
     }
     async callTool(_name, _args) {
         const response = await this.gateway.handleToolCall();
@@ -106,7 +86,9 @@ export class AuthRequiredBackend {
                 content: [
                     {
                         type: "text",
-                        text: "Pharaoh: authenticated. Call this tool again to get the codebase map.",
+                        // ProxyServer re-runs the call on the new backend; this text
+                        // only reaches the agent if no backend swap happened.
+                        text: "Pharaoh: authenticated. Call the tool again.",
                     },
                 ],
                 isError: false,

package/dist/catalog.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Pharaoh's agent-facing surface as bundled into this package at build time:
+ * the server instructions and the tool catalog in inspect-tools.json, written by
+ * the main repo's scripts/generate-inspect-schemas.ts from the same code the
+ * production server runs.
+ *
+ * The proxy answers Claude Code's `initialize` and first `tools/list` before it
+ * has reached (or signed in to) mcp.pharaoh.so, and the client reads instructions
+ * only once, at connect. So it serves this copy rather than a stub. See VISION.md
+ * § Every connection path delivers the same instructions and tool metadata.
+ */
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+/** Instructions and tools exactly as the Pharaoh server sends them. */
+export interface BundledCatalog {
+    /** Server instructions (getInstructions() in the main repo). */
+    instructions: string;
+    /** Every tool the server lists, with descriptions, schemas and `_meta`. */
+    tools: Tool[];
+}
+/**
+ * Load the bundled instructions and tool catalog (read once per process).
+ *
+ * @returns The catalog shipped in this package's inspect-tools.json.
+ * @throws If the file is missing or lacks instructions or tools — a packaging bug.
+ */
+export declare function loadBundledCatalog(): BundledCatalog;

package/dist/catalog.js

@@ -0,0 +1,33 @@
+/**
+ * Pharaoh's agent-facing surface as bundled into this package at build time:
+ * the server instructions and the tool catalog in inspect-tools.json, written by
+ * the main repo's scripts/generate-inspect-schemas.ts from the same code the
+ * production server runs.
+ *
+ * The proxy answers Claude Code's `initialize` and first `tools/list` before it
+ * has reached (or signed in to) mcp.pharaoh.so, and the client reads instructions
+ * only once, at connect. So it serves this copy rather than a stub. See VISION.md
+ * § Every connection path delivers the same instructions and tool metadata.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+let cached = null;
+/**
+ * Load the bundled instructions and tool catalog (read once per process).
+ *
+ * @returns The catalog shipped in this package's inspect-tools.json.
+ * @throws If the file is missing or lacks instructions or tools — a packaging bug.
+ */
+export function loadBundledCatalog() {
+    if (cached)
+        return cached;
+    // Resolved from the module URL: the package supports Node 18, before the dirname shortcut.
+    const path = join(dirname(fileURLToPath(import.meta.url)), "..", "inspect-tools.json");
+    const parsed = JSON.parse(readFileSync(path, "utf-8"));
+    if (typeof parsed.instructions !== "string" || !Array.isArray(parsed.tools)) {
+        throw new Error(`${path} has no instructions or tools — rebuild the package`);
+    }
+    cached = { instructions: parsed.instructions, tools: parsed.tools };
+    return cached;
+}

package/dist/credentials.d.ts

@@ -22,6 +22,8 @@ export interface Credentials {
     tenant_name: string | null;
     repos: string[];
 }
+/** Default credential file path (route-grep-hook.ts checks the same file to know Pharaoh is signed in). */
+export declare const CREDENTIALS_PATH: string;
 /**
  * Read and parse stored credentials. Returns null if missing, unreadable,
  * malformed, or wrong schema version (v1 credentials will return null here,

package/dist/credentials.js

@@ -26,8 +26,8 @@ const LOCK_POLL_MS = 50;
  * token to upgrade from.
  */
 const SCHEMA_VERSION = 2;
-/** Default credential file path. */
-const CREDENTIALS_PATH = join(homedir(), ".pharaoh", "credentials.json");
+/** Default credential file path (route-grep-hook.ts checks the same file to know Pharaoh is signed in). */
+export const CREDENTIALS_PATH = join(homedir(), ".pharaoh", "credentials.json");
 /**
  * Read and parse stored credentials. Returns null if missing, unreadable,
  * malformed, or wrong schema version (v1 credentials will return null here,

package/dist/helpers.js

@@ -42,7 +42,7 @@ export function parseArgs(argv = process.argv.slice(2)) {
     return { server, logout };
 }
 export function printUsage() {
-    printLines("Usage: pharaoh-mcp [options]", "", "Options:", "  --server <url>    Pharaoh server URL (default: https://mcp.pharaoh.so)", "  --logout          Clear credentials and MCP config, then exit", "  --clean           Remove all Pharaoh MCP entries from Claude Code config", "  --install-skills  Force reinstall Pharaoh skills (Claude Code + OpenClaw)", "  --help, -h        Show this help", "", "Get started:", `  ${NPX_COMMAND}`, "");
+    printLines("Usage: pharaoh-mcp [options]", "", "Options:", "  --server <url>    Pharaoh server URL (default: https://mcp.pharaoh.so)", "  --logout          Clear credentials, MCP config and the Claude Code plugin, then exit", "  --clean           Remove Pharaoh's MCP entries and plugin from Claude Code config", "  --install-skills  Reinstall the Claude Code plugin and OpenClaw skills", "  --help, -h        Show this help", "", "Get started:", `  ${NPX_COMMAND}`, "");
 }
 /**
  * Validate that a server-supplied SSE URL shares the same origin as the configured server.

package/dist/index.js

@@ -52,16 +52,20 @@ async function main() {
     // disabled states, project-scoped configs). Useful for resetting broken installs.
     if (args.includes("--clean")) {
         const { cleanSlate } = await import("./setup.js");
+        const { uninstallClaudePlugin } = await import("./install-skills.js");
         cleanSlate();
-        printLines("Pharaoh: cleaned all MCP entries from Claude Code config");
+        uninstallClaudePlugin();
+        printLines("Pharaoh: cleaned all MCP entries and the plugin from Claude Code config");
         process.exit(0);
     }
     const { server, logout } = parseArgs(args);
     if (logout) {
         const { cleanSlate } = await import("./setup.js");
+        const { uninstallClaudePlugin } = await import("./install-skills.js");
         cleanSlate();
+        uninstallClaudePlugin();
         deleteCredentials();
-        printLines("Pharaoh: credentials and MCP config cleared");
+        printLines("Pharaoh: credentials, MCP config and the Claude Code plugin cleared");
         process.exit(0);
     }
     const isInteractive = Boolean(process.stdin.isTTY);

package/dist/inspect.d.ts

@@ -1,11 +1,11 @@
 /**
- * Inspect mode — serves Pharaoh's tool schemas over stdio for Glama inspection.
+ * Inspect mode — serves Pharaoh's instructions and tool schemas over stdio for
+ * Glama inspection.
  *
- * Reads pre-generated tool schemas from inspect-tools.json (generated at build
- * time by the main repo's `generate-inspect-schemas.ts`). Registers each tool
- * on an MCP server that returns a "connect to mcp.pharaoh.so" message if invoked.
- *
- * Zero-drift: schemas are extracted from the same registerXxx() code that the
- * production server uses, serialized to JSON during build, and shipped in the npm package.
+ * Serves the bundled catalog (catalog.ts — inspect-tools.json, generated at build
+ * time by the main repo's `generate-inspect-schemas.ts`) verbatim: the same
+ * instructions, descriptions, schemas, annotations and `_meta` the production
+ * server sends. Any tool call returns a "connect to mcp.pharaoh.so" message.
  */
+/** Run the inspect server on stdio until the client disconnects. */
 export declare function runInspect(): Promise<void>;

package/dist/inspect.js

@@ -1,46 +1,33 @@
 /**
- * Inspect mode — serves Pharaoh's tool schemas over stdio for Glama inspection.
+ * Inspect mode — serves Pharaoh's instructions and tool schemas over stdio for
+ * Glama inspection.
  *
- * Reads pre-generated tool schemas from inspect-tools.json (generated at build
- * time by the main repo's `generate-inspect-schemas.ts`). Registers each tool
- * on an MCP server that returns a "connect to mcp.pharaoh.so" message if invoked.
- *
- * Zero-drift: schemas are extracted from the same registerXxx() code that the
- * production server uses, serialized to JSON during build, and shipped in the npm package.
+ * Serves the bundled catalog (catalog.ts — inspect-tools.json, generated at build
+ * time by the main repo's `generate-inspect-schemas.ts`) verbatim: the same
+ * instructions, descriptions, schemas, annotations and `_meta` the production
+ * server sends. Any tool call returns a "connect to mcp.pharaoh.so" message.
  */
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+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 { 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.";
+/** Run the inspect server on stdio until the client disconnects. */
 export async function runInspect() {
-    // Load pre-generated schemas (shipped in the npm package)
-    const schemasPath = join(import.meta.dirname, "..", "inspect-tools.json");
-    let schemas;
+    let catalog;
     try {
-        schemas = JSON.parse(readFileSync(schemasPath, "utf-8"));
+        catalog = loadBundledCatalog();
     }
-    catch {
-        process.stderr.write("Pharaoh: inspect-tools.json not found — rebuild the package.\n");
+    catch (err) {
+        process.stderr.write(`Pharaoh: ${err instanceof Error ? err.message : String(err)}\n`);
         process.exit(1);
     }
-    const server = new McpServer({ name: "pharaoh", version: getPackageVersion() }, {
-        instructions: "Pharaoh turns codebases into knowledge graphs that AI agents can think with. " +
-            "Connect at https://mcp.pharaoh.so for full functionality.",
-    });
-    // Register each tool with pre-serialized JSON Schema.
-    // Cast inputSchema to satisfy TypeScript — at runtime registerTool passes it through as-is.
-    for (const tool of schemas.tools) {
-        // biome-ignore lint/suspicious/noExplicitAny: JSON Schema from inspect-tools.json, not Zod
-        const schema = tool.inputSchema;
-        server.registerTool(tool.name, {
-            description: tool.description,
-            inputSchema: schema,
-            annotations: tool.annotations,
-        }, async () => ({ content: [{ type: "text", text: INSPECT_MSG }] }));
-    }
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
+    const server = new Server({ name: "pharaoh", version: getPackageVersion() }, { capabilities: { tools: {} }, instructions: catalog.instructions });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: catalog.tools }));
+    server.setRequestHandler(CallToolRequestSchema, async () => ({
+        content: [{ type: "text", text: INSPECT_MSG }],
+    }));
+    await server.connect(new StdioServerTransport());
 }

package/dist/install-skills.d.ts

@@ -5,6 +5,16 @@
  * @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.
+ *
+ * @param home - Home directory override (defaults to os.homedir()).
+ * @param claude - `claude` CLI runner (defaults to the real CLI for `home`).
+ */
+export declare function uninstallClaudePlugin(home?: string, claude?: ClaudeCli): void;
 /**
  * Install bundled skills to `~/.openclaw/skills/` with the same `pharaoh-`
  * prefix that Claude Code installs use. Keeps naming consistent across both
@@ -33,7 +43,11 @@ export declare function mergeOpenClawConfig(home?: string): boolean;
  * Installs to all detected platforms (a user may use both).
  *
  * @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`).
  */
 export declare function runInstallSkills(home?: string, options?: {
     silent?: boolean;
+    claude?: ClaudeCli;
 }): void;
+export {};