pi-mcp-adapter 2.3.5 → 2.4.1

package/CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.4.1] - 2026-04-22
+
+### Added
+- Added standard-MCP-first config discovery: `~/.config/mcp/mcp.json` and project `.mcp.json` now load automatically, with Pi-owned files preserved as override layers.
+- Added `pi-mcp-adapter init` as a native post-install helper that detects host-specific MCP configs and scaffolds Pi compatibility imports without using the old raw GitHub downloader flow.
+- Added first-run onboarding inside the extension: `/mcp` now shows shared-config hints or actionable empty states, and `/mcp setup` opens a guided setup flow for compatibility imports, minimal `.mcp.json` scaffolding, detected config paths, RepoPrompt quick-add, and exact before/after write previews.
+- Added automatic Pi-core reload after setup or direct-tool config changes, using the same flow as `/reload` so freshly configured direct tools can appear without a manual restart.
+- Added a dedicated Pi-owned onboarding state file so shared-config hints behave as one-time guidance instead of repeating every session.
+
+### Changed
+- Updated config precedence to prefer shared MCP files first, then Pi overrides, with `.pi/mcp.json` acting as the final Pi-specific project override.
+- Updated Claude Code compatibility probing to prefer modern Claude MCP config locations before legacy paths.
+- Updated project scaffolding so generated `.mcp.json` files are safe minimal shells instead of fake placeholder servers that fail on first reload.
+- Updated the setup panel and README for clearer first-run guidance, improved spacing, and a more digestible shared-MCP-first setup story.
+
+## [2.4.0] - 2026-04-13
+
+### Added
+- `settings.disableProxyTool` to hide the `mcp` proxy tool once configured direct tools are fully available from cache. Thanks @tanavamsikrishna for PR #41.
+- Per-server `excludeTools` to hide specific MCP tools/resources by original or prefixed name across direct tools, proxy discovery, and the `/mcp` panel. Thanks @ahmadaccino for issue #36.
+- `settings.autoAuth` to optionally trigger OAuth automatically from proxy/direct tool usage, then rerun the original blocked connect/tool operation once after authentication succeeds. Thanks @unimonkiez for issue #34.
+
+### Fixed
+- Regenerated `package-lock.json` so the root lockfile metadata matches `package.json` again, including the declared `open`, `@types/bun`, `@types/open`, and `tsx` entries.
+- Kept the `mcp` proxy tool available as a first-session fallback when configured direct tools are still missing cache metadata, avoiding no-tool startup gaps.
+
 ## [2.3.5] - 2026-04-13
 
 ### Fixed

package/README.md

@@ -24,9 +24,21 @@ pi install npm:pi-mcp-adapter
 
 Restart Pi after installation.
 
+## What happens on first run
+
+The adapter reads standard MCP files automatically. No extra setup needed if you already have them.
+
+| You already have... | What happens |
+|---------------------|--------------|
+| `.mcp.json` or `~/.config/mcp/mcp.json` | Pi uses it immediately. The first time you open `/mcp`, you'll see a short heads-up explaining which file Pi detected and that Pi only writes adapter-specific overrides to its own files. |
+| Host-specific configs (Cursor, Claude Code, Codex, etc.) but no standard MCP files | Run `/mcp setup` to adopt those host configs into Pi. The setup flow shows exactly what it found, lets you pick which ones to import, and previews the exact file changes before writing. |
+| Nothing configured yet | Run `/mcp setup` to scaffold a minimal `.mcp.json`, quick-add RepoPrompt, or inspect what the adapter discovered on your machine. |
+
+If you prefer the terminal, you can also run `pi-mcp-adapter init` after install to scan for host-specific configs and add missing compatibility imports to `~/.pi/agent/mcp.json`.
+
 ## Quick Start
 
-Create `~/.pi/agent/mcp.json`:
+Preferred project config: `.mcp.json`
 
 ```json
 {
@@ -39,6 +51,20 @@ Create `~/.pi/agent/mcp.json`:
 }
 ```
 
+Preferred user-global shared config: `~/.config/mcp/mcp.json`
+
+Pi also reads Pi-owned override files for settings and host-specific compatibility:
+
+- `~/.pi/agent/mcp.json` — Pi global override
+- `.pi/mcp.json` — Pi project override
+
+Precedence is:
+
+1. `~/.config/mcp/mcp.json`
+2. `~/.pi/agent/mcp.json`
+3. `.mcp.json`
+4. `.pi/mcp.json`
+
 Servers are **lazy by default** — they won't connect until you actually call one of their tools. The adapter caches tool metadata so search and describe work without live connections.
 
 ```
@@ -62,6 +88,19 @@ Two calls instead of 26 tools cluttering the context.
 
 ## Config
 
+### File Layout
+
+Use the shared MCP files when you want one setup to work across hosts, and Pi-owned files when you need Pi-specific overrides or settings.
+
+| File | Purpose |
+|------|---------|
+| `~/.config/mcp/mcp.json` | User-global shared MCP config |
+| `.mcp.json` | Project-local shared MCP config |
+| `~/.pi/agent/mcp.json` | Pi global override and compatibility imports |
+| `.pi/mcp.json` | Pi project override |
+
+Pi-specific files are the write targets for imported or shared global servers when Pi needs to persist adapter-only settings such as `directTools`.
+
 ### Server Options
 
 ```json
@@ -91,6 +130,7 @@ Two calls instead of 26 tools cluttering the context.
 | `idleTimeout` | Minutes before idle disconnect (overrides global) |
 | `exposeResources` | Expose MCP resources as tools (default: true) |
 | `directTools` | `true`, `string[]`, or `false` — register tools individually instead of through proxy |
+| `excludeTools` | `string[]` of tool names to hide (matches original names like `get_screenshot` and prefixed names like `figma_get_screenshot`) |
 | `debug` | Show server stderr (default: false) |
 
 ### Lifecycle Modes
@@ -116,6 +156,8 @@ Two calls instead of 26 tools cluttering the context.
 | `toolPrefix` | `"server"` (default), `"short"` (strips `-mcp` suffix), or `"none"` |
 | `idleTimeout` | Global idle timeout in minutes (default: 10, 0 to disable) |
 | `directTools` | Global default for all servers (default: false). Per-server overrides this. |
+| `disableProxyTool` | Hide the `mcp` proxy tool once configured direct tools are fully available from cache. |
+| `autoAuth` | Auto-run OAuth on `connect`/tool calls when a server needs auth, then retry once (default: false). |
 
 Per-server `idleTimeout` overrides the global setting.
 
@@ -169,11 +211,31 @@ To set a global default for all servers:
 
 Per-server `directTools` overrides the global setting. The example above registers direct tools for every server except `huge-server`.
 
+To exclude specific tools while still using `directTools: true`, add `excludeTools` on the server:
+
+```json
+{
+  "mcpServers": {
+    "figma": {
+      "url": "http://localhost:3845/mcp",
+      "directTools": true,
+      "excludeTools": ["get_figjam", "figma_get_code_connect_map"]
+    }
+  }
+}
+```
+
+`excludeTools` filters direct tools, proxy search/list/describe, and the `/mcp` panel view.
+
 Each direct tool costs ~150-300 tokens in the system prompt (name + description + schema). Good for targeted sets of 5-20 tools. For servers with 75+ tools, stick with the proxy or pick specific tools with a `string[]`.
 
-Direct tools register from the metadata cache (`~/.pi/agent/mcp-cache.json`), so no server connections are needed at startup. On the first session after adding `directTools` to a new server, the cache won't exist yet — tools fall back to proxy-only and the cache populates in the background. Restart Pi and they'll be available. To force it: `/mcp reconnect <server>` then restart.
+Direct tools register from the metadata cache (`~/.pi/agent/mcp-cache.json`), so no server connections are needed at startup. On the first session after adding `directTools` to a new server, the cache won't exist yet — tools fall back to proxy-only and the cache populates in the background. To force it: `/mcp reconnect <server>`.
+
+When you change direct-tool toggles in `/mcp` or write new config through `/mcp setup`, the extension triggers Pi's normal reload flow automatically. That refreshes extensions, prompts, skills, and MCP tool registration in one shot, so newly configured direct tools can appear without a manual restart.
 
-**Interactive configuration:** Run `/mcp` to open an interactive panel showing all servers with connection status, tools, and direct/proxy toggles. You can reconnect servers, initiate OAuth, and toggle tools between direct and proxy — all from one overlay. Changes are written to your config file; restart Pi to apply.
+**Interactive configuration:** Run `/mcp` to open an interactive panel showing all servers with connection status, tools, and direct/proxy toggles. You can reconnect servers, initiate OAuth, and toggle tools between direct and proxy — all from one overlay.
+
+**Guided first-run setup:** Run `/mcp setup` to inspect detected shared MCP files, adopt compatibility imports from other hosts, open discovered config paths, preview exact before/after file diffs for writes, scaffold a minimal project `.mcp.json`, or quick-add RepoPrompt into a standard/shared MCP file.
 
 **Subagent integration:** If you use the subagent extension, agents can request direct MCP tools in their frontmatter with `mcp:server-name` syntax. See the subagent README for details.
 
@@ -238,7 +300,7 @@ Restart pi, then ask the agent to show a chart — it calls `show_chart` and ope
 
 ### Import Existing Configs
 
-Already have MCP set up elsewhere? Import it:
+Shared MCP files are loaded automatically. Use `imports` only for host-specific config formats that are not already covered by `.mcp.json` or `~/.config/mcp/mcp.json`.
 
 ```json
 {
@@ -247,11 +309,13 @@ Already have MCP set up elsewhere? Import it:
 }
 ```
 
-Supported: `cursor`, `claude-code`, `claude-desktop`, `vscode`, `windsurf`, `codex`
+Supported compatibility imports: `cursor`, `claude-code`, `claude-desktop`, `vscode`, `windsurf`, `codex`
+
+`pi-mcp-adapter init` detects these host-specific configs and adds missing imports to `~/.pi/agent/mcp.json` for you.
 
 ### Project Config
 
-Add `.pi/mcp.json` in a project root for project-specific servers. Project config overrides global and imported servers.
+Prefer `.mcp.json` for project-local shared MCP config. Use `.pi/mcp.json` only when you need a Pi-specific project override. Project files override both user-global shared MCP config and Pi global overrides.
 
 ## Usage
 
@@ -273,12 +337,15 @@ Tool names are fuzzy-matched on hyphens and underscores — `context7_resolve_li
 
 | Command | What it does |
 |---------|--------------|
-| `/mcp` | Interactive panel (server status, tool toggles, reconnect) |
+| `/mcp` | Interactive panel and first-run onboarding surface |
+| `/mcp setup` | Guided setup for imports, a minimal `.mcp.json`, RepoPrompt quick-add, and config-path inspection |
 | `/mcp tools` | List all tools |
 | `/mcp reconnect` | Reconnect all servers |
 | `/mcp reconnect <server>` | Connect or reconnect a single server |
 | `/mcp-auth <server>` | OAuth setup |
 
+If `settings.autoAuth` is `true`, `mcp({ connect: ... })`, `mcp({ tool: ... })`, and direct tool calls will automatically run OAuth when needed and retry once. In non-interactive sessions, browser-based OAuth still requires running `/mcp-auth <server>` manually.
+
 ## How It Works
 
 - One `mcp` tool in context (~200 tokens) instead of hundreds

package/cli.js

@@ -2,107 +2,173 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import https from "node:https";
 import os from "node:os";
-import { execSync } from "node:child_process";
-
-const REPO_URL = "https://raw.githubusercontent.com/nicobailon/pi-mcp-adapter/main";
-const EXT_DIR = path.join(os.homedir(), ".pi", "agent", "extensions", "pi-mcp-adapter");
-const SETTINGS_FILE = path.join(os.homedir(), ".pi", "agent", "settings.json");
-const EXT_PATH = "~/.pi/agent/extensions/pi-mcp-adapter/index.ts";
-
-const FILES = [
-  "index.ts",
-  "types.ts",
-  "config.ts",
-  "server-manager.ts",
-  "tool-registrar.ts",
-  "resource-tools.ts",
-  "lifecycle.ts",
-  "metadata-cache.ts",
-  "npx-resolver.ts",
-  "oauth-handler.ts",
-  "package.json",
-  "tsconfig.json",
-  "README.md",
-  "CHANGELOG.md",
-  "LICENSE",
-];
-
-function download(url) {
-  return new Promise((resolve, reject) => {
-    https.get(url, (res) => {
-      if (res.statusCode === 301 || res.statusCode === 302) {
-        return download(res.headers.location).then(resolve).catch(reject);
-      }
-      if (res.statusCode !== 200) {
-        return reject(new Error(`Failed to download ${url}: ${res.statusCode}`));
-      }
-      let data = "";
-      res.on("data", (chunk) => (data += chunk));
-      res.on("end", () => resolve(data));
-      res.on("error", reject);
-    }).on("error", reject);
-  });
-}
+import { pathToFileURL } from "node:url";
+
+const HOME = os.homedir();
+const PI_CONFIG_PATH = path.join(HOME, ".pi", "agent", "mcp.json");
+const GENERIC_GLOBAL_CONFIG_PATH = path.join(HOME, ".config", "mcp", "mcp.json");
+const PROJECT_CONFIG_PATH = path.resolve(process.cwd(), ".mcp.json");
+const PROJECT_PI_CONFIG_PATH = path.resolve(process.cwd(), ".pi", "mcp.json");
 
-async function main() {
-  console.log("Installing pi-mcp-adapter...\n");
+const IMPORT_PATHS = {
+  cursor: [path.join(HOME, ".cursor", "mcp.json")],
+  "claude-code": [
+    path.join(HOME, ".claude", "mcp.json"),
+    path.join(HOME, ".claude.json"),
+    path.join(HOME, ".claude", "claude_desktop_config.json"),
+  ],
+  "claude-desktop": [path.join(HOME, "Library", "Application Support", "Claude", "claude_desktop_config.json")],
+  codex: [path.join(HOME, ".codex", "config.json")],
+  windsurf: [path.join(HOME, ".windsurf", "mcp.json")],
+  vscode: [path.resolve(process.cwd(), ".vscode", "mcp.json")],
+};
+
+function printHelp(log = console.log) {
+  log("pi-mcp-adapter helper\n");
+  log("Install the package with:");
+  log("  pi install npm:pi-mcp-adapter\n");
+  log("Then optionally run:");
+  log("  pi-mcp-adapter init       Detect host configs and scaffold Pi imports");
+  log("  pi-mcp-adapter init --dry-run");
+}
 
-  fs.mkdirSync(EXT_DIR, { recursive: true });
-  console.log(`Created directory: ${EXT_DIR}`);
+function readJsonFile(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+}
 
-  for (const file of FILES) {
-    console.log(`Downloading ${file}...`);
-    const content = await download(`${REPO_URL}/${file}`);
-    fs.writeFileSync(path.join(EXT_DIR, file), content);
+function loadPiConfig() {
+  if (!fs.existsSync(PI_CONFIG_PATH)) {
+    return { mcpServers: {} };
   }
 
-  console.log("\nInstalling dependencies...");
-  try {
-    execSync("npm install --omit=dev", { cwd: EXT_DIR, stdio: "inherit" });
-  } catch {
-    console.error("Warning: npm install failed. You may need to run it manually.");
+  const raw = readJsonFile(PI_CONFIG_PATH);
+  const mcpServers = raw.mcpServers ?? raw["mcp-servers"] ?? {};
+  if (!mcpServers || typeof mcpServers !== "object" || Array.isArray(mcpServers)) {
+    throw new Error(`Invalid MCP config at ${PI_CONFIG_PATH}: expected \"mcpServers\" to be an object`);
   }
 
-  console.log(`\nUpdating settings: ${SETTINGS_FILE}`);
-  
-  let settings = {};
-  if (fs.existsSync(SETTINGS_FILE)) {
-    try {
-      settings = JSON.parse(fs.readFileSync(SETTINGS_FILE, "utf-8"));
-    } catch (err) {
-      console.error(`Warning: Could not parse existing settings.json: ${err.message}`);
-      console.error("Creating new settings file...");
+  const normalized = { ...raw };
+  delete normalized["mcp-servers"];
+
+  const imports = Array.isArray(raw.imports) ? raw.imports.filter((value) => typeof value === "string") : undefined;
+  return {
+    ...normalized,
+    mcpServers,
+    imports,
+  };
+}
+
+function findAvailableImports() {
+  const found = [];
+
+  for (const [kind, candidates] of Object.entries(IMPORT_PATHS)) {
+    const existing = candidates.find((candidate) => fs.existsSync(candidate));
+    if (existing) {
+      found.push({ kind, path: existing });
     }
   }
 
-  if (!Array.isArray(settings.extensions)) {
-    settings.extensions = [];
+  return found;
+}
+
+function printDiscovery(log, imports) {
+  log("Config discovery:\n");
+
+  const paths = [
+    ["User-global standard MCP", GENERIC_GLOBAL_CONFIG_PATH],
+    ["Pi global override", PI_CONFIG_PATH],
+    ["Project standard MCP", PROJECT_CONFIG_PATH],
+    ["Project Pi override", PROJECT_PI_CONFIG_PATH],
+  ];
+
+  for (const [label, filePath] of paths) {
+    const prefix = fs.existsSync(filePath) ? "✓" : "-";
+    log(`${prefix} ${label}: ${filePath}`);
+  }
+
+  log("\nCompatibility imports:\n");
+  if (imports.length === 0) {
+    log("- No host-specific MCP configs detected");
+    return;
+  }
+
+  for (const entry of imports) {
+    log(`✓ ${entry.kind}: ${entry.path}`);
+  }
+}
+
+function writePiConfig(config) {
+  fs.mkdirSync(path.dirname(PI_CONFIG_PATH), { recursive: true });
+  fs.writeFileSync(PI_CONFIG_PATH, `${JSON.stringify(config, null, 2)}\n`, "utf-8");
+}
+
+async function runInit(argv, log = console.log) {
+  const dryRun = argv.includes("--dry-run");
+  const foundImports = findAvailableImports();
+  const existingConfig = loadPiConfig();
+  const existingImports = new Set(existingConfig.imports ?? []);
+  const importsToAdd = foundImports
+    .map((entry) => entry.kind)
+    .filter((kind) => !existingImports.has(kind));
+
+  printDiscovery(log, foundImports);
+
+  if (importsToAdd.length === 0) {
+    log("\nNo Pi config changes needed.");
+    log("Standard MCP configs are discovered automatically, and host-specific imports are already configured or unavailable.");
+    return 0;
   }
 
-  const hasMcpExt = settings.extensions.some(p => 
-    p === EXT_PATH || 
-    p.includes("/extensions/pi-mcp-adapter/index.ts") || 
-    p.includes("/extensions/pi-mcp-adapter")
-  );
-
-  if (!hasMcpExt) {
-    settings.extensions.push(EXT_PATH);
-    console.log(`Added "${EXT_PATH}" to extensions array`);
-  } else {
-    console.log("Extension already configured in settings.json");
+  const nextConfig = {
+    ...existingConfig,
+    imports: [...existingImports, ...importsToAdd],
+    mcpServers: existingConfig.mcpServers ?? {},
+  };
+
+  log(`\nDetected host configs to import into Pi: ${importsToAdd.join(", ")}`);
+
+  if (dryRun) {
+    log(`Dry run: would update ${PI_CONFIG_PATH}`);
+    return 0;
   }
 
-  fs.mkdirSync(path.dirname(SETTINGS_FILE), { recursive: true });
-  fs.writeFileSync(SETTINGS_FILE, JSON.stringify(settings, null, 2) + "\n");
+  writePiConfig(nextConfig);
+  log(`Updated ${PI_CONFIG_PATH}`);
+  log("Pi will now keep reading standard MCP configs automatically, while these imports cover host-specific config formats.");
+  return 0;
+}
+
+export async function main(argv = process.argv.slice(2), log = console.log, error = console.error) {
+  const [command, ...rest] = argv;
 
-  console.log("\nInstallation complete!");
-  console.log("\nCreate ~/.pi/agent/mcp.json to configure MCP servers.");
-  console.log("Restart pi to load the extension.");
+  if (!command || command === "help" || command === "--help" || command === "-h") {
+    printHelp(log);
+    return 0;
+  }
+
+  if (command === "install") {
+    error("The custom downloader has been retired.");
+    error("Use `pi install npm:pi-mcp-adapter` instead, then optionally run `pi-mcp-adapter init`.");
+    return 1;
+  }
+
+  if (command === "init") {
+    return runInit(rest, log);
+  }
+
+  error(`Unknown command: ${command}`);
+  printHelp(log);
+  return 1;
 }
 
-main().catch((err) => {
-  console.error(`\nInstallation failed: ${err.message}`);
-  process.exit(1);
-});
+const isEntrypoint = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+
+if (isEntrypoint) {
+  main().then((code) => {
+    process.exitCode = code;
+  }).catch((err) => {
+    console.error(`\nHelper failed: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  });
+}

package/commands.ts

@@ -1,12 +1,24 @@
 import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
 import type { McpExtensionState } from "./state.js";
-import type { McpConfig, ServerEntry, McpPanelCallbacks, McpPanelResult } from "./types.js";
-import { getServerProvenance, writeDirectToolsConfig } from "./config.js";
+import type { McpConfig, ServerEntry, McpPanelCallbacks, McpPanelResult, ImportKind } from "./types.js";
+import {
+  ensureCompatibilityImports,
+  getMcpDiscoverySummary,
+  getServerProvenance,
+  previewCompatibilityImports,
+  previewSharedServerEntry,
+  previewStarterProjectConfig,
+  writeDirectToolsConfig,
+  writeSharedServerEntry,
+  writeStarterProjectConfig,
+} from "./config.js";
 import { lazyConnect, updateMetadataCache, updateStatusBar, getFailureAgeSeconds } from "./init.js";
 import { loadMetadataCache } from "./metadata-cache.js";
 import { buildToolMetadata } from "./tool-metadata.js";
 import { supportsOAuth, authenticate } from "./mcp-auth-flow.js";
 import { hasStoredTokens } from "./mcp-auth.js";
+import { loadOnboardingState, markSetupCompleted as persistSetupCompleted, markSharedConfigHintShown } from "./onboarding-state.js";
+import { openPath } from "./utils.js";
 
 export async function showStatus(state: McpExtensionState, ctx: ExtensionContext): Promise<void> {
   if (!ctx.hasUI) return;
@@ -42,6 +54,7 @@ export async function showStatus(state: McpExtensionState, ctx: ExtensionContext
 
   if (Object.keys(state.config.mcpServers).length === 0) {
     lines.push("No MCP servers configured");
+    lines.push("Run /mcp setup to adopt imports or scaffold a starter .mcp.json");
   }
 
   ctx.ui.notify(lines.join("\n"), "info");
@@ -153,11 +166,8 @@ export async function authenticateServer(
     return;
   }
 
-  // Full automatic OAuth flow using SDK
   try {
     ctx.ui.setStatus("mcp-auth", `Authenticating ${serverName}...`);
-
-    // Runs the configured OAuth flow (interactive browser or non-interactive client_credentials)
     const status = await authenticate(serverName, definition.url, definition);
 
     if (status === "authenticated") {
@@ -180,15 +190,104 @@ export async function authenticateServer(
   }
 }
 
+export interface PanelFlowResult {
+  configChanged: boolean;
+}
+
+function buildSharedConfigNoticeLines(configOverridePath?: string): { lines: string[]; fingerprint: string | null } {
+  const discovery = getMcpDiscoverySummary(configOverridePath);
+  const onboardingState = loadOnboardingState();
+  if (!discovery.hasSharedServers || onboardingState.sharedConfigHintShown) {
+    return { lines: [], fingerprint: null };
+  }
+
+  const sharedSources = discovery.sources.filter((source) => source.kind === "shared" && source.serverCount > 0);
+  const sourceList = sharedSources.map((source) => source.path).join(", ");
+  return {
+    lines: [
+      `Using standard MCP config from ${sourceList}.`,
+      "Pi only writes compatibility imports and adapter-specific overrides into Pi-owned files when needed.",
+    ],
+    fingerprint: discovery.fingerprint,
+  };
+}
+
+export async function openMcpSetup(
+  _state: McpExtensionState,
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  configOverridePath?: string,
+  mode: "empty" | "setup" = "setup",
+): Promise<PanelFlowResult> {
+  if (!ctx.hasUI) return { configChanged: false };
+
+  const discovery = getMcpDiscoverySummary(configOverridePath);
+  const onboardingState = loadOnboardingState();
+  const { createMcpSetupPanel } = await import("./mcp-setup-panel.js");
+  let configChanged = false;
+
+  const callbacks = {
+    previewImports: (imports: ImportKind[]) => previewCompatibilityImports(imports, configOverridePath),
+    previewStarterProject: () => previewStarterProjectConfig(),
+    previewRepoPrompt: () => {
+      const repoPrompt = getMcpDiscoverySummary(configOverridePath).repoPrompt;
+      if (!repoPrompt.entry || !repoPrompt.targetPath || !repoPrompt.serverName) return null;
+      return previewSharedServerEntry(repoPrompt.targetPath, repoPrompt.serverName, repoPrompt.entry);
+    },
+    adoptImports: async (imports: ImportKind[]) => {
+      const result = ensureCompatibilityImports(imports, configOverridePath);
+      if (result.added.length > 0) configChanged = true;
+      return result;
+    },
+    scaffoldProjectConfig: async () => {
+      const path = writeStarterProjectConfig();
+      configChanged = true;
+      return { path };
+    },
+    addRepoPrompt: async () => {
+      const repoPrompt = getMcpDiscoverySummary(configOverridePath).repoPrompt;
+      if (!repoPrompt.entry || !repoPrompt.targetPath || !repoPrompt.serverName) {
+        throw new Error("RepoPrompt is not available to add from this setup screen.");
+      }
+      const path = writeSharedServerEntry(repoPrompt.targetPath, repoPrompt.serverName, repoPrompt.entry);
+      configChanged = true;
+      return { path, serverName: repoPrompt.serverName };
+    },
+    openPath: async (targetPath: string) => {
+      await openPath(pi, targetPath);
+    },
+    markSetupCompleted: () => {
+      persistSetupCompleted(discovery.fingerprint);
+    },
+  };
+
+  return new Promise<PanelFlowResult>((resolve) => {
+    ctx.ui.custom(
+      (tui, _theme, _keybindings, done) => {
+        return createMcpSetupPanel(discovery, callbacks, { mode, onboardingState }, tui, () => {
+          done();
+          resolve({ configChanged });
+        });
+      },
+      { overlay: true, overlayOptions: { anchor: "center", width: 92 } },
+    );
+  });
+}
+
 export async function openMcpPanel(
   state: McpExtensionState,
   pi: ExtensionAPI,
   ctx: ExtensionContext,
   configOverridePath?: string,
-): Promise<void> {
+): Promise<PanelFlowResult> {
+  if (Object.keys(state.config.mcpServers).length === 0) {
+    return openMcpSetup(state, pi, ctx, configOverridePath, "empty");
+  }
+
   const config = state.config;
   const cache = loadMetadataCache();
   const provenanceMap = getServerProvenance(pi.getFlag("mcp-config") as string | undefined ?? configOverridePath);
+  const { lines: noticeLines, fingerprint } = buildSharedConfigNoticeLines(pi.getFlag("mcp-config") as string | undefined ?? configOverridePath);
 
   const callbacks: McpPanelCallbacks = {
     reconnect: async (serverName: string) => {
@@ -219,20 +318,28 @@ export async function openMcpPanel(
   };
 
   const { createMcpPanel } = await import("./mcp-panel.js");
+  let configChanged = false;
 
-  return new Promise<void>((resolve) => {
+  await new Promise<void>((resolve) => {
     ctx.ui.custom(
       (tui, _theme, _keybindings, done) => {
         return createMcpPanel(config, cache, provenanceMap, callbacks, tui, (result: McpPanelResult) => {
           if (!result.cancelled && result.changes.size > 0) {
             writeDirectToolsConfig(result.changes, provenanceMap, config);
-            ctx.ui.notify("Direct tools updated. Restart pi to apply.", "info");
+            configChanged = true;
+            ctx.ui.notify("Direct tools updated. Pi will reload after this panel closes.", "info");
           }
           done();
           resolve();
-        });
+        }, { noticeLines });
       },
       { overlay: true, overlayOptions: { anchor: "center", width: 82 } },
     );
   });
+
+  if (noticeLines.length > 0 && fingerprint) {
+    markSharedConfigHintShown(fingerprint);
+  }
+
+  return { configChanged };
 }