pi-mcp-adapter 2.20.0 → 2.21.0

package/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.21.0] - 2026-08-06
+
+### Added
+- Added MCP 2026-07-28 endpoint probing and defaulted curated remote setup presets to automatic protocol negotiation for stateless MCP servers.
+- Added `resolveServerFromToolName` so permission brokers can map prefixed MCP tool names back to their owning server. Thanks @jagaliano for PR #295.
+- Added per-server `oauth.skipIssuerMetadataValidation` for known-misconfigured OAuth servers. Thanks @embik for issue #297.
+- Added a configurable `mcp.panel.save` keybinding for the MCP panel Save action. Thanks @tim-hilde for issue #299.
+- Added `settings.agentPluginPaths` to load MCP servers from Agent Plugins 1.0 packages.
+
+### Changed
+- Refined MCP endpoint probing internals with typed strategies while preserving request order, fallback behavior, and diagnostics.
+
+### Fixed
+- Rejected Agent Plugin command paths that escape the plugin directory and skipped normalized server-name collisions instead of overwriting servers.
+- Stopped `/mcp` from inspecting host-specific config files when host config discovery is disabled. Thanks @rtfmkiesel for issue #292.
+- Stopped optional numeric `mcp` and `mcpScript` tool parameters from leaking TypeBox internal markers into serialized schemas. Thanks @RainbowXie for issue #289 and PR #290.
+- Forwarded RFC 9207 OAuth callback issuers to the MCP SDK during manual authorization completion. Thanks @tkoenig for issue #293 and PR #294, and @ugur-murat-alt for independent live verification.
+- Kept `mcpScript` `tools.describe()` from omitting parameter information when TypeScript shape rendering falls back. Thanks @sheurich for issue #288.
+- Reduced repeated collapsed MCP result rendering allocation after large or truncated tool outputs. Thanks @cp-yu for issue #291.
+
+## [2.20.1] - 2026-08-04
+
+### Fixed
+- Stopped server-side MCP app helper imports from requiring the legacy `@modelcontextprotocol/sdk` peer at extension load time, fixing peerless Pi installs of 2.20.0. Thanks @aryzing for issue #285 and @DevDominic, @Shinkicast, and @marceloid for confirmations.
+
 ## [2.20.0] - 2026-08-04
 
 ### Added

package/README.md

@@ -58,7 +58,7 @@ Pi also reads Pi-owned override files for settings and host-specific compatibili
 - `<Pi agent dir>/mcp.json` — Pi global override (`~/.pi/agent/mcp.json` by default)
 - `.pi/mcp.json` — Pi project override
 
-Host-specific configs are detected and shown by `/mcp setup` and `pi-mcp-adapter init`, but they are not loaded automatically. To explicitly opt in to host-config fallback discovery, set `settings.hostConfigDiscovery` to `"on"` or run `pi-mcp-adapter init --discover-host-configs`. The default is `"off"`; `"prompt"` is available for integrations that want detection without activation. Host configs are lower precedence than every shared and Pi-owned source, and `/mcp setup` continues to offer explicit import adoption. Discovery reports source paths, provenance, and same-name conflicts; it never writes to external host files or silently launches commands from them.
+Host-specific configs are detected and shown by `/mcp setup` and `pi-mcp-adapter init`, but they are not loaded automatically. The normal `/mcp` panel does not scan host-specific files when `settings.hostConfigDiscovery` is `"off"`. To explicitly opt in to host-config fallback discovery, set `settings.hostConfigDiscovery` to `"on"` or run `pi-mcp-adapter init --discover-host-configs`. The default is `"off"`; `"prompt"` is available for integrations that want detection without activation. Host configs are lower precedence than every shared and Pi-owned source, and `/mcp setup` continues to offer explicit import adoption. Discovery reports source paths, provenance, and same-name conflicts; it never writes to external host files or silently launches commands from them.
 
 Precedence is:
 
@@ -109,6 +109,23 @@ Use the shared MCP files when you want one setup to work across hosts, and Pi-ow
 
 Pi-specific files are the write targets for imported or shared global servers when Pi needs to persist adapter-only settings such as `directTools`.
 
+### Agent Plugins
+
+The adapter can load MCP servers from [Agent Plugins](https://agent-plugins.org/) packages when you list plugin directories in `settings.agentPluginPaths`:
+
+```json
+{
+  "settings": {
+    "agentPluginPaths": ["./plugins/acme-tools"]
+  },
+  "mcpServers": {}
+}
+```
+
+Each directory must contain a valid Agent Plugins 1.0 `plugin.json`. If it also has a root `mcp.json`, the adapter loads its `mcpServers` entries and prefixes them as `<plugin>__<server>`. The loader uses the Agent Plugins transport declared by each server `type` and skips invalid entries without blocking other servers. For stdio plugin servers, `${PLUGIN_ROOT}` and `${PLUGIN_DATA}` are expanded only in `args`, `env`, and `cwd`; the adapter sets both variables for the child process and stores plugin data under the Pi agent directory.
+
+Agent Plugins is a portable package format. Native Pi MCP config remains `.mcp.json`, `~/.config/mcp/mcp.json`, and Pi-owned overrides.
+
 ### SDK configuration
 
 Use `createMcpAdapter` when an SDK or server integration already owns its MCP configuration:
@@ -181,12 +198,13 @@ In the configuration examples below, `30000` is illustrative only. If `requestTi
 | `headers` | HTTP headers; supports `${VAR}` and `$env:VAR` interpolation. A value beginning with `!` runs a command when the HTTP server connects or OAuth authenticates; use `!!` for a literal leading `!`. |
 | `auth` | `"bearer"` or `"oauth"` |
 | `oauth.grantType` | `"authorization_code"` (default) or `"client_credentials"` for non-interactive machine auth |
-| `oauth.clientId` | Pre-registered OAuth client ID; dynamic registration is used when omitted |
+| `oauth.clientId` | Pre-registered OAuth client ID. MCP 2026 prefers pre-registered clients or Client ID Metadata Documents; this adapter falls back to Dynamic Client Registration when the ID is omitted and the server supports it. |
 | `oauth.clientSecret` | OAuth client secret for confidential clients; a value beginning with `!` runs a command when OAuth authenticates, while `!!` escapes a literal leading `!` |
 | `oauth.scope` | Requested OAuth scopes |
 | `oauth.redirectUri` | Exact localhost redirect URI for browser OAuth, including port and path, for providers that pre-register callbacks |
-| `oauth.clientName` | Client display name advertised during dynamic registration |
-| `oauth.clientUri` | Client homepage URI advertised during dynamic registration |
+| `oauth.clientName` | Client display name advertised during Dynamic Client Registration fallback |
+| `oauth.clientUri` | Client homepage URI advertised during Dynamic Client Registration fallback |
+| `oauth.skipIssuerMetadataValidation` | `true` disables the OAuth authorization-server metadata issuer check for this server. This weakens OAuth mix-up protection and should only be used for known-misconfigured internal servers while their metadata is being fixed. |
 | `bearerToken` / `bearerTokenEnv` | Token or env var name; `bearerToken` supports `${VAR}` and `$env:VAR` interpolation. A leading `!` in `bearerToken` runs a command when the HTTP server connects; use `!!` for a literal leading `!`. |
 | `lifecycle` | `"lazy"` (default), `"eager"`, `"keep-alive"`, or `"lazy-keep-alive"` |
 | `idleTimeout` | Minutes before idle disconnect (overrides global) |
@@ -205,7 +223,7 @@ In the configuration examples below, `30000` is illustrative only. If `requestTi
 
 The adapter defaults to `protocolVersion: "legacy"`. Omitting the field uses the classic MCP initialize sequence without `server/discover` or 2026 headers, preserving compatibility with deployed 2025-era servers.
 
-Use `"auto"` to probe for MCP 2026-07-28 and conservatively fall back to the classic handshake when the server provides legacy evidence. For stdio servers, the SDK probes with a short-lived sibling process before starting the session process, so each fresh auto connection adds one process spawn and can wait for the configured request timeout. Explicit Unix sockets are custom transports and probe in place. HTTP auto negotiation uses the actual Streamable HTTP connection; the adapter falls back to legacy SSE only when the endpoint definitively rejects Streamable HTTP (for example 404/405/406/415), never for authentication failures, cancellation, timeouts, or server errors.
+Use `"auto"` to probe for MCP 2026-07-28 and conservatively fall back to the classic handshake when the server provides legacy evidence. Set it for Cloudflare Workers `createMcpHandler` and other MCP SDK v2 stateless servers. The adapter keeps `"legacy"` as the global default for compatibility. For stdio servers, the SDK probes with a short-lived sibling process before starting the session process, so each fresh auto connection adds one process spawn and can wait for the configured request timeout. Explicit Unix sockets are custom transports and probe in place. HTTP auto negotiation uses the actual Streamable HTTP connection; the adapter falls back to legacy SSE only when the endpoint definitively rejects Streamable HTTP (for example 404/405/406/415), never for authentication failures, cancellation, timeouts, or server errors.
 
 Use `"2026-07-28"` to pin that revision. Pinning has no legacy or SSE fallback and fails if the server does not offer the requested version.
 
@@ -213,6 +231,8 @@ The stable SDK handles era-specific request envelopes, result decoding, list-cha
 
 For pre-registered browser OAuth clients, set `oauth.redirectUri` to the exact callback registered with the provider, for example `"http://localhost:3118/callback"`. Dynamic clients normally omit it and use a lazy OS-assigned localhost callback port.
 
+If an internal authorization server publishes mismatched OAuth metadata and cannot be fixed immediately, set `oauth.skipIssuerMetadataValidation: true` on that server only. This is security-weakening. It disables the RFC 8414 issuer echo check and should not be used for public or untrusted servers.
+
 Secret values in `headers`, `bearerToken`, `oauth.clientSecret`, and stdio `env` may use a leading `!command` to obtain their value at connection or authentication time. The command runs with stdin and stderr suppressed, stdout is limited to 1 MiB and trimmed, and it must finish within 10 seconds with non-empty output; failures stop the connection or authentication flow. Commands are not run during OAuth discovery or while reading, merging, previewing, hashing, or rendering configuration. Use `!!` to escape a literal leading `!`; ordinary and escaped values retain environment interpolation.
 
 ### Shared MCP processes with rmcp-mux
@@ -294,6 +314,7 @@ When any enabled server uses `eager` or `keep-alive`, initialization also starts
 | `showStatusIcon` | Show the plug icon in MCP status and connection text (default: `true`). Set to `false` for plain `MCP: ...` text. |
 | `mcpFooterStatus` | MCP footer verbosity: `"full"` (default), `"compact"` for `MCP connected/enabled`, or `"off"` to clear the persistent footer status. `/mcp status` remains available. |
 | `hostConfigDiscovery` | Host-specific config policy: `"off"` (default), `"prompt"` (detect/report only), or `"on"` (explicitly load detected host configs as the lowest-precedence fallback) |
+| `agentPluginPaths` | Agent Plugins package directories to load MCP servers from. Relative paths resolve from the active project cwd. |
 | `approveTools` | `true` to require approval before every MCP tool call, or an array of glob patterns such as `["github_delete_*", "notion_update_*"]`. Per-server `approveTools` overrides this. |
 | `oauthDir` | Legacy OAuth `tokens.json` import directory for this MCP config. Relative paths resolve from the active project cwd. `MCP_OAUTH_DIR` still wins when set. Persistent OAuth credentials are stored in the OS credential store, not this directory. |
 | `mcpServers.<name>.oauth.authorizationParams` | Extra authorization URL parameters for provider-specific OAuth extensions. Flow-owned parameters such as `client_id`, `redirect_uri`, `scope`, `state`, `code_challenge`, `response_type`, and `resource` cannot be overridden. |
@@ -509,7 +530,7 @@ If prompt-cache stability matters more than automatic direct-tool hot-loading, s
 
 When you change direct-tool toggles in `/mcp`, the extension updates direct tool registration in the current session. Broader setup writes from `/mcp setup` still use Pi's normal reload flow because they can add or restructure MCP config files.
 
-**Interactive configuration:** Run `/mcp` to open an interactive panel showing all servers with connection status, tools, and direct/proxy toggles. You can reconnect servers and toggle tools between direct and proxy from the same overlay. For OAuth, press Enter on a server that needs auth or `ctrl+a` on any OAuth server.
+**Interactive configuration:** Run `/mcp` to open an interactive panel showing all servers with connection status, tools, and direct/proxy toggles. You can reconnect servers and toggle tools between direct and proxy from the same overlay. For OAuth, press Enter on a server that needs auth or `ctrl+a` on any OAuth server. The Save action defaults to `ctrl+s` and can be remapped with the `mcp.panel.save` keybinding.
 
 **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`, add a curated known server (DeepWiki, Context7, Notion, GitHub, or Chrome DevTools), or quick-add RepoPrompt into a standard/shared MCP file.
 

package/agent-plugin-loader.ts

@@ -0,0 +1,377 @@
+import { existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { getAgentPath } from "./agent-dir.ts";
+import type { McpConfig, ServerEntry } from "./types.ts";
+
+const PLUGIN_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";
+const MCP_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json";
+const PLUGIN_NAME_PATTERN = /^(?!.*(?:--|\.\.))[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/;
+const PLUGIN_MANIFEST_FIELDS = new Set([
+  "$schema",
+  "name",
+  "version",
+  "description",
+  "author",
+  "homepage",
+  "repository",
+  "license",
+  "keywords",
+  "extensions",
+]);
+const MCP_CONFIG_FIELDS = new Set(["$schema", "mcpServers"]);
+const STDIO_FIELDS = new Set(["type", "command", "args", "env", "cwd"]);
+const HTTP_FIELDS = new Set(["type", "url", "headers"]);
+
+interface AgentPluginManifest {
+  name: string;
+}
+
+export interface AgentPluginSummary {
+  path: string;
+  name?: string;
+  serverCount: number;
+}
+
+export function loadAgentPluginConfigs(paths: unknown, cwd = process.cwd()): McpConfig {
+  const mcpServers: Record<string, ServerEntry> = {};
+  for (const pluginPath of getPluginPaths(paths)) {
+    const loaded = loadAgentPluginMcpConfig(pluginPath, cwd);
+    if (!loaded) continue;
+    for (const [serverName, server] of Object.entries(loaded.mcpServers)) {
+      if (mcpServers[serverName]) {
+        console.warn(`Agent Plugin at ${resolvePluginPath(pluginPath, cwd)} skips duplicate normalized MCP server ${serverName}`);
+        continue;
+      }
+      mcpServers[serverName] = server;
+    }
+  }
+  return { mcpServers };
+}
+
+export function getAgentPluginSummaries(paths: unknown, cwd = process.cwd()): AgentPluginSummary[] {
+  return getPluginPaths(paths).map(path => {
+    const pluginRoot = resolvePluginPath(path, cwd);
+    const loaded = loadAgentPluginMcpConfig(path, cwd);
+    const manifest = loaded ? readPluginManifest(pluginRoot, false) : null;
+    return {
+      path: pluginRoot,
+      ...(manifest?.name ? { name: manifest.name } : {}),
+      serverCount: loaded ? Object.keys(loaded.mcpServers).length : 0,
+    };
+  });
+}
+
+function getPluginPaths(paths: unknown): string[] {
+  return Array.isArray(paths) ? paths.filter((path): path is string => typeof path === "string") : [];
+}
+
+function loadAgentPluginMcpConfig(path: string, cwd: string): McpConfig | null {
+  const pluginRoot = resolvePluginPath(path, cwd);
+  const manifest = readPluginManifest(pluginRoot, true);
+  if (!manifest) return null;
+
+  const mcpPath = resolve(pluginRoot, "mcp.json");
+  if (!existsSync(mcpPath)) return { mcpServers: {} };
+  if (!statSync(mcpPath).isFile()) {
+    console.warn(`Agent Plugin ${manifest.name} has invalid MCP config: mcp.json is not a regular file`);
+    return { mcpServers: {} };
+  }
+
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(mcpPath, "utf8"));
+  } catch (error) {
+    console.warn(`Agent Plugin ${manifest.name} has invalid MCP config: failed to parse mcp.json`, error);
+    return { mcpServers: {} };
+  }
+
+  return translateAgentPluginMcpConfig(raw, manifest, pluginRoot);
+}
+
+function readPluginManifest(pluginRoot: string, report: boolean): AgentPluginManifest | null {
+  const manifestPath = resolve(pluginRoot, "plugin.json");
+  if (!existsSync(manifestPath)) {
+    if (report) console.warn(`Agent Plugin at ${pluginRoot} is invalid: missing plugin.json`);
+    return null;
+  }
+  if (!statSync(manifestPath).isFile()) {
+    if (report) console.warn(`Agent Plugin at ${pluginRoot} is invalid: plugin.json is not a regular file`);
+    return null;
+  }
+
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(manifestPath, "utf8"));
+  } catch (error) {
+    if (report) console.warn(`Agent Plugin at ${pluginRoot} is invalid: failed to parse plugin.json`, error);
+    return null;
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    if (report) console.warn(`Agent Plugin at ${pluginRoot} is invalid: plugin.json must be an object`);
+    return null;
+  }
+
+  const manifest = raw as Record<string, unknown>;
+  for (const key of Object.keys(manifest)) {
+    if (!PLUGIN_MANIFEST_FIELDS.has(key) && report) {
+      console.warn(`Agent Plugin at ${pluginRoot} ignores unknown plugin.json field: ${key}`);
+    }
+  }
+  if (manifest.$schema !== PLUGIN_SCHEMA) {
+    if (report) console.warn(`Agent Plugin at ${pluginRoot} is invalid: unsupported plugin.json $schema`);
+    return null;
+  }
+  if (typeof manifest.name !== "string" || manifest.name.length < 1 || manifest.name.length > 64 || !PLUGIN_NAME_PATTERN.test(manifest.name)) {
+    if (report) console.warn(`Agent Plugin at ${pluginRoot} is invalid: plugin.json name is invalid`);
+    return null;
+  }
+  if (manifest.extensions !== undefined && (!manifest.extensions || typeof manifest.extensions !== "object" || Array.isArray(manifest.extensions))) {
+    if (report) console.warn(`Agent Plugin ${manifest.name} ignores non-object plugin.json extensions`);
+  }
+
+  return { name: manifest.name };
+}
+
+function translateAgentPluginMcpConfig(raw: unknown, manifest: AgentPluginManifest, pluginRoot: string): McpConfig {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    console.warn(`Agent Plugin ${manifest.name} has invalid MCP config: mcp.json must be an object`);
+    return { mcpServers: {} };
+  }
+
+  const mcpConfig = raw as Record<string, unknown>;
+  for (const key of Object.keys(mcpConfig)) {
+    if (!MCP_CONFIG_FIELDS.has(key)) {
+      console.warn(`Agent Plugin ${manifest.name} has invalid MCP config: unknown top-level field ${key}`);
+      return { mcpServers: {} };
+    }
+  }
+  if (mcpConfig.$schema !== MCP_SCHEMA) {
+    console.warn(`Agent Plugin ${manifest.name} has invalid MCP config: unsupported mcp.json $schema`);
+    return { mcpServers: {} };
+  }
+  if (!mcpConfig.mcpServers || typeof mcpConfig.mcpServers !== "object" || Array.isArray(mcpConfig.mcpServers)) {
+    console.warn(`Agent Plugin ${manifest.name} has invalid MCP config: mcpServers must be an object`);
+    return { mcpServers: {} };
+  }
+
+  const mcpServers: Record<string, ServerEntry> = {};
+  for (const [serverName, entry] of Object.entries(mcpConfig.mcpServers)) {
+    const translated = translateAgentPluginServer(manifest, pluginRoot, serverName, entry);
+    if (!translated) continue;
+
+    const normalizedName = formatAgentPluginServerName(manifest.name, serverName);
+    if (mcpServers[normalizedName]) {
+      console.warn(`Agent Plugin ${manifest.name} skips invalid MCP server ${serverName}: normalized server name ${normalizedName} already exists`);
+      continue;
+    }
+    mcpServers[normalizedName] = translated;
+  }
+  return { mcpServers };
+}
+
+function translateAgentPluginServer(
+  manifest: AgentPluginManifest,
+  pluginRoot: string,
+  serverName: string,
+  entry: unknown,
+): ServerEntry | null {
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+    console.warn(`Agent Plugin ${manifest.name} skips invalid MCP server ${serverName}: entry must be an object`);
+    return null;
+  }
+
+  const raw = entry as Record<string, unknown>;
+  if (raw.type === "stdio") return translateStdioServer(manifest, pluginRoot, serverName, raw);
+  if (raw.type === "streamable-http" || raw.type === "sse") return translateHttpServer(manifest, serverName, raw, raw.type);
+
+  console.warn(`Agent Plugin ${manifest.name} skips invalid MCP server ${serverName}: unsupported type`);
+  return null;
+}
+
+function translateStdioServer(
+  manifest: AgentPluginManifest,
+  pluginRoot: string,
+  serverName: string,
+  raw: Record<string, unknown>,
+): ServerEntry | null {
+  for (const key of Object.keys(raw)) {
+    if (!STDIO_FIELDS.has(key)) return skipServer(manifest, serverName, `unknown field ${key}`);
+  }
+  if (typeof raw.command !== "string" || raw.command.length === 0) return skipServer(manifest, serverName, "command must be a non-empty string");
+  if (!isBareCommand(raw.command) && !raw.command.startsWith("./")) return skipServer(manifest, serverName, "command must be bare or plugin-relative");
+
+  const args = translateStringArray(raw.args, manifest, serverName, "args");
+  if (args === null) return null;
+  const env = translateEnv(raw.env, manifest, serverName);
+  if (env === null) return null;
+
+  const command = raw.command.startsWith("./") ? resolveContainedPath(pluginRoot, raw.command, pluginRoot) : raw.command;
+  if (command === null) return skipServer(manifest, serverName, "command must stay inside the plugin directory");
+
+  const pluginDataDir = getAgentPath("agent-plugin-data", manifest.name);
+  const cwd = resolvePluginCwd(raw.cwd, pluginRoot, pluginDataDir);
+  if (cwd === null) return skipServer(manifest, serverName, "cwd must be plugin-relative, PLUGIN_ROOT-rooted, or PLUGIN_DATA-rooted");
+
+  return {
+    command,
+    args: args.map(value => expandPluginPlaceholders(value, pluginRoot, pluginDataDir)),
+    env: {
+      ...Object.fromEntries(Object.entries(env).map(([key, value]) => [key, expandPluginPlaceholders(value, pluginRoot, pluginDataDir)])),
+      PLUGIN_ROOT: pluginRoot,
+      PLUGIN_DATA: pluginDataDir,
+    },
+    cwd,
+    pluginDataDir,
+    literalEnv: true,
+  };
+}
+
+function translateHttpServer(
+  manifest: AgentPluginManifest,
+  serverName: string,
+  raw: Record<string, unknown>,
+  type: "streamable-http" | "sse",
+): ServerEntry | null {
+  for (const key of Object.keys(raw)) {
+    if (!HTTP_FIELDS.has(key)) return skipServer(manifest, serverName, `unknown field ${key}`);
+  }
+  if (typeof raw.url !== "string" || raw.url.length === 0) return skipServer(manifest, serverName, "url must be a non-empty string");
+  if (!isValidAgentPluginUrl(raw.url)) return skipServer(manifest, serverName, "url must be an allowed absolute HTTP(S) URL");
+  const headers = translateHeaders(raw.headers, manifest, serverName);
+  if (headers === null) return null;
+
+  return {
+    url: raw.url,
+    httpTransport: type,
+    ...(headers ? { headers } : {}),
+  };
+}
+
+function formatAgentPluginServerName(pluginName: string, serverName: string): string {
+  const pluginPart = pluginName.replace(/[^A-Za-z0-9_-]+/g, "_").replace(/^[_-]+|[_-]+$/g, "") || "plugin";
+  const serverPart = serverName.replace(/[^A-Za-z0-9_-]+/g, "_").replace(/^[_-]+|[_-]+$/g, "") || "server";
+  return `${pluginPart}__${serverPart}`;
+}
+
+function skipServer(manifest: AgentPluginManifest, serverName: string, reason: string): null {
+  console.warn(`Agent Plugin ${manifest.name} skips invalid MCP server ${serverName}: ${reason}`);
+  return null;
+}
+
+function translateStringArray(value: unknown, manifest: AgentPluginManifest, serverName: string, field: string): string[] | null {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.some(item => typeof item !== "string")) {
+    console.warn(`Agent Plugin ${manifest.name} skips invalid MCP server ${serverName}: ${field} must be an array of strings`);
+    return null;
+  }
+  return value;
+}
+
+function translateEnv(value: unknown, manifest: AgentPluginManifest, serverName: string): Record<string, string> | null {
+  if (value === undefined) return {};
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    console.warn(`Agent Plugin ${manifest.name} skips invalid MCP server ${serverName}: env must be an object of strings`);
+    return null;
+  }
+  const env: Record<string, string> = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (key === "PLUGIN_ROOT" || key === "PLUGIN_DATA") {
+      console.warn(`Agent Plugin ${manifest.name} skips invalid MCP server ${serverName}: env must not define ${key}`);
+      return null;
+    }
+    if (typeof entry !== "string") {
+      console.warn(`Agent Plugin ${manifest.name} skips invalid MCP server ${serverName}: env values must be strings`);
+      return null;
+    }
+    env[key] = entry;
+  }
+  return env;
+}
+
+function translateHeaders(value: unknown, manifest: AgentPluginManifest, serverName: string): Record<string, string> | undefined | null {
+  if (value === undefined) return undefined;
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    console.warn(`Agent Plugin ${manifest.name} skips invalid MCP server ${serverName}: headers must be an object of strings`);
+    return null;
+  }
+  const headers: Record<string, string> = {};
+  const seen = new Set<string>();
+  for (const [key, entry] of Object.entries(value)) {
+    if (typeof entry !== "string") {
+      console.warn(`Agent Plugin ${manifest.name} skips invalid MCP server ${serverName}: header values must be strings`);
+      return null;
+    }
+    const normalized = key.toLowerCase();
+    if (seen.has(normalized)) {
+      console.warn(`Agent Plugin ${manifest.name} skips invalid MCP server ${serverName}: duplicate header ${key}`);
+      return null;
+    }
+    seen.add(normalized);
+    headers[key] = entry;
+  }
+  try {
+    new Headers(headers);
+  } catch {
+    console.warn(`Agent Plugin ${manifest.name} skips invalid MCP server ${serverName}: headers are not valid HTTP fields`);
+    return null;
+  }
+  return Object.keys(headers).length > 0 ? headers : undefined;
+}
+
+function resolvePluginPath(path: string, cwd: string): string {
+  if (path === "~") return resolve(process.env.HOME ?? "", ".");
+  if (path.startsWith("~/")) return resolve(process.env.HOME ?? "", path.slice(2));
+  return isAbsolute(path) ? resolve(path) : resolve(cwd, path);
+}
+
+function isBareCommand(command: string): boolean {
+  return !command.includes("/") && !command.includes("\\") && !command.includes("${PLUGIN_ROOT}") && !command.includes("${PLUGIN_DATA}");
+}
+
+function resolvePluginCwd(value: unknown, pluginRoot: string, pluginDataDir: string): string | null {
+  if (value === undefined) return pluginRoot;
+  if (typeof value !== "string") return null;
+  if (value.startsWith("./")) return resolveContainedPath(pluginRoot, value, pluginRoot);
+  if (value === "${PLUGIN_ROOT}" || value.startsWith("${PLUGIN_ROOT}/")) {
+    return resolveContainedPath(pluginRoot, value.replace("${PLUGIN_ROOT}", "."), pluginRoot);
+  }
+  if (value === "${PLUGIN_DATA}" || value.startsWith("${PLUGIN_DATA}/")) {
+    return resolveContainedPath(pluginDataDir, value.replace("${PLUGIN_DATA}", "."), pluginDataDir);
+  }
+  return null;
+}
+
+function resolveContainedPath(root: string, value: string, containmentRoot: string): string | null {
+  const resolved = resolve(root, value);
+  const rel = relative(containmentRoot, resolved);
+  if (rel === "" || (!rel.startsWith("..") && !rel.startsWith(sep) && !isAbsolute(rel))) return resolved;
+  return null;
+}
+
+function expandPluginPlaceholders(value: string, pluginRoot: string, pluginDataDir: string): string {
+  return value
+    .replaceAll("${PLUGIN_ROOT}", pluginRoot)
+    .replaceAll("${PLUGIN_DATA}", pluginDataDir);
+}
+
+function isValidAgentPluginUrl(value: string): boolean {
+  if (value.includes("${") || value.includes("$env:") || value.includes("{env:")) return false;
+
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    return false;
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") return false;
+  if (url.username || url.password || url.hash) return false;
+  if (url.protocol === "https:") return true;
+  return isLoopbackHost(url.hostname);
+}
+
+function isLoopbackHost(hostname: string): boolean {
+  const host = hostname.toLowerCase();
+  if (host === "localhost" || host === "127.0.0.1" || host === "::1" || host === "[::1]") return true;
+  if (/^127(?:\.\d{1,3}){3}$/.test(host)) return true;
+  return false;
+}

package/commands.ts

@@ -4,6 +4,7 @@ import { isServerDisabled, type McpAuthResult, type McpConfig, type McpPanelCall
 import {
   ensureCompatibilityImports,
   getMcpDiscoverySummary,
+  getMcpStandardConfigSummary,
   getProjectConfigPath,
   type KnownServerPreset,
   getServerProvenance,
@@ -354,7 +355,7 @@ export interface PanelFlowResult {
 }
 
 function buildSharedConfigNoticeLines(configOverridePath: string | undefined, cwd: string): { lines: string[]; fingerprint: string | null } {
-  const discovery = getMcpDiscoverySummary(configOverridePath, cwd);
+  const discovery = getMcpStandardConfigSummary(configOverridePath, cwd);
   const onboardingState = loadOnboardingState();
   if (!discovery.hasSharedServers || onboardingState.sharedConfigHintShown) {
     return { lines: [], fingerprint: null };
@@ -377,6 +378,7 @@ export async function openMcpSetup(
   ctx: ExtensionContext,
   configOverridePath?: string,
   mode: "empty" | "setup" = "setup",
+  options: { includeHostConfigs?: boolean } = {},
 ): Promise<PanelFlowResult> {
   if (!ctx.hasUI) return { configChanged: false };
   if (state.programmaticConfig) {
@@ -384,7 +386,7 @@ export async function openMcpSetup(
     return { configChanged: false };
   }
 
-  const discovery = getMcpDiscoverySummary(configOverridePath, ctx.cwd);
+  const discovery = getMcpDiscoverySummary(configOverridePath, ctx.cwd, options);
   const onboardingState = loadOnboardingState();
   const { createMcpSetupPanel } = await import("./mcp-setup-panel.ts");
   let configChanged = false;
@@ -393,7 +395,7 @@ export async function openMcpSetup(
     previewImports: (imports: ImportKind[]) => previewCompatibilityImports(imports, configOverridePath),
     previewStarterProject: () => previewStarterProjectConfig(ctx.cwd),
     previewRepoPrompt: () => {
-      const repoPrompt = getMcpDiscoverySummary(configOverridePath, ctx.cwd).repoPrompt;
+      const repoPrompt = getMcpDiscoverySummary(configOverridePath, ctx.cwd, options).repoPrompt;
       if (!repoPrompt.entry || !repoPrompt.targetPath || !repoPrompt.serverName) return null;
       return previewSharedServerEntry(repoPrompt.targetPath, repoPrompt.serverName, repoPrompt.entry);
     },
@@ -409,7 +411,7 @@ export async function openMcpSetup(
       return { path };
     },
     addRepoPrompt: async () => {
-      const repoPrompt = getMcpDiscoverySummary(configOverridePath, ctx.cwd).repoPrompt;
+      const repoPrompt = getMcpDiscoverySummary(configOverridePath, ctx.cwd, options).repoPrompt;
       if (!repoPrompt.entry || !repoPrompt.targetPath || !repoPrompt.serverName) {
         throw new Error("RepoPrompt is not available to add from this setup screen.");
       }
@@ -514,7 +516,7 @@ export async function openMcpPanel(
     return { configChanged: false };
   }
   if (Object.keys(state.config.mcpServers).length === 0) {
-    return openMcpSetup(state, pi, ctx, configOverridePath, "empty");
+    return openMcpSetup(state, pi, ctx, configOverridePath, "empty", { includeHostConfigs: false });
   }
 
   const config = state.config;