@miphamai/cli 0.85.4 → 0.85.6

package/src/mcp/client.ts

@@ -26,6 +26,11 @@ const t = createT(bundles['en-US'] || (enUS as TranslationMap), enUS as Translat
 // than block on the per-request 60s timeout. Overridable via env for tests.
 const DEFAULT_CONNECT_TIMEOUT_MS = 15_000
 
+// How often a caller waiting on a handshake re-checks it. A handshake settles in
+// tens of milliseconds when it settles at all; this only bounds how long the wait
+// can overshoot the moment it actually did.
+const CONNECT_POLL_MS = 50
+
 function connectTimeoutMs(): number {
   const env = Number(process.env.MIPHAM_MCP_CONNECT_TIMEOUT_MS)
   return Number.isFinite(env) && env > 0 ? env : DEFAULT_CONNECT_TIMEOUT_MS
@@ -48,6 +53,8 @@ interface ActiveConnection {
   status: ConnectionStatus
   tools: ToolDefinition[]
   serverInfo?: { name: string; version: string }
+  /** initialize 自带的 server 使用说明；见 `mcp/instructions.ts`。 */
+  instructions?: string
   error?: string
   /** Coalescing timer for `tools/list_changed` (see scheduleToolsRefresh). */
   toolsRefreshTimer?: ReturnType<typeof setTimeout>
@@ -72,6 +79,17 @@ interface ActiveConnection {
 export class McpClient {
   private static instance: McpClient | null = null
   private connections = new Map<string, ActiveConnection>()
+  /**
+   * 同名连接**正在握手中**的那一次。
+   *
+   * 两条来源在启动时是并发的：配置里的 server 在 `index.tsx` 一次 `Promise.allSettled`
+   * 里连（同一个同步块里那句没被 await），插件声明的 server 紧接着在 `loadPlugins` 里各
+   * 连一次（`.mcp.json` 走 `plugin-loader`、manifest 内联的 `mcpServers` 走 `claude-plugin`，
+   * 两处也都不 await）。撞上同一个名字时，第二条看到的是 `connecting`，于是**另起一条传输**
+   * 并把它塞回 map —— 而 `closeAll` 只遍历 `connections`，被换掉的那条没人关：stdio 的子
+   * 进程就此不被回收。名字就是身份（URL 怎么拼都不参与判重），所以同名就该是同一个连接。
+   */
+  private connecting = new Map<string, Promise<void>>()
   private _tokenStore: TokenStore | null = null
   private _oauthClient: OAuthClient | null = null
   private eventHandlers = new Map<string, Array<(...args: any[]) => void>>()
@@ -262,6 +280,21 @@ export class McpClient {
     const existing = this.connections.get(config.name)
     if (existing?.status === 'connected') return
 
+    // 名字正在握手中：合并到那一次，别另起一条传输。
+    const inflight = this.connecting.get(config.name)
+    if (inflight) return inflight
+
+    const attempt = this.connectOnce(config)
+    this.connecting.set(config.name, attempt)
+    try {
+      await attempt
+    } finally {
+      // 无论成败都要放开这个名字：失败后用户重连，得能真的重连。
+      this.connecting.delete(config.name)
+    }
+  }
+
+  private async connectOnce(config: McpServerConfig): Promise<void> {
     const transport: StdioTransport | HttpTransport = config.url
       ? new HttpTransport(undefined, config.request_timeout_ms)
       : new StdioTransport(config.request_timeout_ms)
@@ -289,6 +322,7 @@ export class McpClient {
 
         connection.status = 'connected'
         connection.serverInfo = initResult.serverInfo
+        connection.instructions = initResult.instructions
 
         // Wire tools-changed notification (coalesced — see scheduleToolsRefresh)
         protocol.on('tools-changed', () => {
@@ -335,6 +369,31 @@ export class McpClient {
     }
   }
 
+  /**
+   * Wait for a server that is still mid-handshake to settle.
+   *
+   * Startup connects servers without blocking, so a caller that fires alongside
+   * it — a hook, SessionStart work — can arrive while a server is *becoming*
+   * connected. Asked for a tool then, `callTool` answers "not connected", which
+   * is a statement about this moment rather than about the server.
+   *
+   * Bounded by the same timeout the handshake itself is, so a server that never
+   * settles fails the waiting caller instead of hanging it.
+   *
+   * @returns `false` only when the deadline passed with the server still
+   * connecting. A server this client knows nothing about is `true`: there is
+   * nothing to wait for, and `callTool` will say so.
+   */
+  async waitUntilReady(name: string, timeoutMs: number = connectTimeoutMs()): Promise<boolean> {
+    const deadline = Date.now() + timeoutMs
+    for (;;) {
+      const conn = this.connections.get(name)
+      if (!conn || conn.status !== 'connecting') return true
+      if (Date.now() >= deadline) return false
+      await new Promise((resolve) => setTimeout(resolve, CONNECT_POLL_MS))
+    }
+  }
+
   /**
    * Disconnect an MCP server and return the names of its registered tools
    * so the caller can unregister them from the central tool registry.
@@ -386,6 +445,7 @@ export class McpClient {
       tools: conn.tools,
       error: conn.error,
       serverInfo: conn.serverInfo,
+      instructions: conn.instructions,
     }
   }
 
@@ -401,6 +461,7 @@ export class McpClient {
       tools: conn.tools,
       error: conn.error,
       serverInfo: conn.serverInfo,
+      instructions: conn.instructions,
     }))
   }
 

package/src/mcp/instructions.ts

@@ -0,0 +1,49 @@
+import type { ConnectionInfo } from './types'
+
+/**
+ * 单个 server 的 instructions 上限。
+ *
+ * 这是**不受我们控制**的第三方文本，且**每次请求都要重新付一遍前缀** ——
+ * 一个啰嗦的 server 能靠一段自带说明把别人的预算吃光。截断而非拒绝：
+ * 前半段通常正是「这个 server 该怎么用」那部分。
+ */
+export const MCP_INSTRUCTIONS_PER_SERVER_CAP = 2000
+
+const TRUNCATION_MARKER = '… [truncated]'
+
+/**
+ * 把已连接 MCP server 自带的 `instructions` 拼成一段**系统提示用**的文本。
+ *
+ * 依据（MCP 规范）：`initialize` 的返回值里 `instructions` 是 server 运维方写的
+ * 「我该怎么被使用」—— 它**不是**工具描述，没地方能寄生，不收就等于丢掉。
+ *
+ * 三条刻意的约束：
+ *   - 没写 instructions 的 server **整段不出现**（空标题会让模型去猜一个不存在的 server）；
+ *   - 按 server 名**排序**，与连接完成顺序无关 —— 同一组 server 两次拼出的必须是同一段字节，
+ *     否则每次请求前缀都变，提供方的 prefix cache 全部落空；
+ *   - 无话可说时返回**空串**，由调用方据此整段不注入（而不是注入一个空壳标题）。
+ *
+ * **已知边界**：接的是**主会话**的系统提示（`index.tsx` → `ContextManager`）。子代理自己拼
+ * 提示词、且**请求读的是局部变量而非上下文**（见 `agent/sub-agent.ts` 的 `currentSystemPrompt`），
+ * 所以子代理**拿不到**这一段 —— 与权限段那道班是同一个形状，但那道班里子代理是**必须**知道
+ * 自己处在哪一档（不然会拒绝做已被允许的事），MCP instructions 只是「这个 server 怎么用」，
+ * 拿不到不影响正确性。此处如实记下，免得被当成已覆盖。
+ */
+export function buildMcpInstructionsBlock(connections: ConnectionInfo[]): string {
+  const sections = connections
+    .filter((c) => typeof c.instructions === 'string' && c.instructions.trim() !== '')
+    .slice()
+    .sort((a, b) => a.config.name.localeCompare(b.config.name))
+    .map((c) => {
+      const raw = c.instructions!.trim()
+      const body =
+        raw.length > MCP_INSTRUCTIONS_PER_SERVER_CAP
+          ? `${raw.slice(0, MCP_INSTRUCTIONS_PER_SERVER_CAP)}\n${TRUNCATION_MARKER}`
+          : raw
+      return `### ${c.config.name}\n${body}`
+    })
+
+  if (sections.length === 0) return ''
+
+  return ['## MCP server guidance', '', ...sections].join('\n')
+}

package/src/mcp/types.ts

@@ -45,6 +45,11 @@ export interface InitializeResult {
   protocolVersion: string
   capabilities: ServerCapabilities
   serverInfo: { name: string; version: string }
+  /**
+   * MCP 规范里 server 自带的「我该怎么被使用」。它没有工具描述那种可寄生之处，
+   * 不收就一个字节都到不了模型（见 `mcp/instructions.ts`）。
+   */
+  instructions?: string
 }
 
 export interface ServerCapabilities {
@@ -109,4 +114,6 @@ export interface ConnectionInfo {
   tools: ToolDefinition[]
   error?: string
   serverInfo?: { name: string; version: string }
+  /** 见 `InitializeResult.instructions`。 */
+  instructions?: string
 }

package/src/plugin/claude-plugin.ts

@@ -64,8 +64,18 @@ function loadClaudeSkills(dir: string, skillsLoader: SkillsLoader): void {
   }
 }
 
-/** Map a Claude MCP server entry to a Mipham `McpServerConfig`. */
-function toMcpServerConfig(name: string, raw: Record<string, unknown>): McpServerConfig | null {
+/**
+ * Map a Claude MCP server entry to a Mipham `McpServerConfig`, or `null` if the
+ * entry carries no transport.
+ *
+ * Exported so `validatePlugin` can ask *this* function — rather than its own copy
+ * of the rule — whether an entry would survive the load. A second copy is a second
+ * answer, and the one that drifts is the one the operator reads.
+ */
+export function toMcpServerConfig(
+  name: string,
+  raw: Record<string, unknown>,
+): McpServerConfig | null {
   const command = typeof raw.command === 'string' ? raw.command : undefined
   const url = typeof raw.url === 'string' ? raw.url : undefined
   if (!command && !url) return null

package/src/plugin/plugin-loader.ts

@@ -7,7 +7,7 @@ import type { HookEngine } from '../core/hooks'
 import type { McpClient } from '../mcp/client'
 import { registerMcpServerTools } from '../mcp/registry'
 import { executeHook } from '../core/hooks-executor'
-import { detectPluginFormat } from './plugin-validator'
+import { detectPluginFormat, isLoadableMcpConfig } from './plugin-validator'
 import { loadClaudePlugin } from './claude-plugin'
 import type { McpServerConfig, ToolDefinition, HookConfig, HookEvent } from '../shared/types'
 
@@ -50,7 +50,6 @@ export function loadPlugins(
     }
 
     const mcpServers: string[] = []
-    const hookEvents: HookEvent[] = []
 
     // ── Custom agents ──
     const agentsDir = join(plugin.path, 'agents')
@@ -86,7 +85,11 @@ export function loadPlugins(
           try {
             const raw = readFileSync(join(mcpDir, entry), 'utf-8')
             const cfg = JSON.parse(raw) as McpServerConfig
-            if (cfg.name && cfg.command) {
+            // Both transports, not just the local one. Requiring `command` here used
+            // to drop every server declared by `url` — a remote server carries no
+            // command — and dropping it in silence, so the plugin looked installed
+            // and its tools simply never appeared.
+            if (isLoadableMcpConfig(cfg)) {
               mcpServers.push(cfg.name)
               mcpClient
                 .connect(cfg)
@@ -103,9 +106,20 @@ export function loadPlugins(
                     `[plugin] Failed to connect MCP "${cfg.name}" from "${plugin.name}": ${String(err)}\n`,
                   )
                 })
+            } else {
+              // Silent skips are the failure this branch exists to end: the operator
+              // sees a plugin that loaded and tools that are missing, with nothing
+              // connecting the two.
+              const declared =
+                typeof cfg.name === 'string' && cfg.name !== '' ? ` "MCP server ${cfg.name}"` : ''
+              process.stderr.write(
+                `[plugin] "${plugin.name}": mcp-servers/${entry}${declared} declares neither command nor url — skipped\n`,
+              )
             }
-          } catch {
-            // skip unparseable MCP config files
+          } catch (err) {
+            process.stderr.write(
+              `[plugin] "${plugin.name}": mcp-servers/${entry} could not be parsed — skipped: ${String(err)}\n`,
+            )
           }
         }
       } catch (err) {
@@ -126,10 +140,14 @@ export function loadPlugins(
               const event = (hookCfg as unknown as Record<string, unknown>).event as
                 HookEvent | undefined
               if (event) {
-                hookEvents.push(event)
                 hookEngine.register({
                   event,
-                  handler: async (ctx) => executeHook(hookCfg, ctx),
+                  // Whoever is running the session can no longer tell this hook from
+                  // one they wrote themselves: the failure it prints would name only
+                  // its command, its health would be tracked under the bare event
+                  // name, and the cleanup below would have nothing to scope to.
+                  source: plugin.name,
+                  handler: async (ctx) => executeHook(hookCfg, ctx, plugin.name),
                 })
               }
             }
@@ -153,13 +171,13 @@ export function loadPlugins(
           /* best effort */
         }
       }
-      // Unregister hooks
-      for (const event of hookEvents) {
-        try {
-          hookEngine.unregister(event)
-        } catch {
-          /* best effort */
-        }
+      // Unregister hooks — this plugin's, and only this plugin's. Keyed by event,
+      // this removed every hook on those events: the operator's own from settings
+      // and other plugins' alike, silently.
+      try {
+        hookEngine.unregisterSource(plugin.name)
+      } catch {
+        /* best effort */
       }
     })
   }

package/src/plugin/plugin-manager.ts

@@ -15,6 +15,18 @@ import { miphamHome } from '../core/paths.ts'
 
 const PLUGIN_DIR = miphamHome('plugins')
 
+/**
+ * Render validation warnings for the install result.
+ *
+ * A warning the install message drops is a warning nobody reads, and the whole
+ * point of reporting a declaration we would skip is that the operator finds out
+ * here — before wondering why the plugin's tools never appeared.
+ */
+function warningsBlock(warnings: string[]): string {
+  if (warnings.length === 0) return ''
+  return warnings.map((w) => `\n⚠ ${w}`).join('')
+}
+
 export interface InstalledPlugin {
   name: string
   version: string
@@ -68,7 +80,8 @@ export class PluginManager {
       success: true,
       message:
         `Plugin "${validation.manifest.name}" v${validation.manifest.version} installed` +
-        (similarWarning ? `\n⚠ ${similarWarning}` : ''),
+        (similarWarning ? `\n⚠ ${similarWarning}` : '') +
+        warningsBlock(validation.warnings),
     }
   }
 
@@ -169,7 +182,8 @@ export class PluginManager {
         success: true,
         message:
           `Plugin "${manifestName}" installed from npm` +
-          (similarWarning ? `\n⚠ ${similarWarning}` : ''),
+          (similarWarning ? `\n⚠ ${similarWarning}` : '') +
+          warningsBlock(validation.warnings),
       }
     } catch (err: unknown) {
       const msg = err instanceof Error ? err.message : String(err)

package/src/plugin/plugin-validator.ts

@@ -1,5 +1,6 @@
-import { readFileSync, existsSync } from 'node:fs'
+import { readFileSync, existsSync, readdirSync } from 'node:fs'
 import { join } from 'node:path'
+import { toMcpServerConfig } from './claude-plugin'
 
 export interface PluginManifest {
   name: string
@@ -16,12 +17,43 @@ export type PluginFormat = 'mipham' | 'claude'
 export interface PluginValidation {
   valid: boolean
   errors: string[]
+  /**
+   * Findings that do not block installation.
+   *
+   * The split is the point: a declaration we would silently drop is a defect in one
+   * part of one plugin, and refusing to install the whole thing over it would make
+   * the validator an obstacle rather than a report. What it must not do is stay
+   * quiet — a dropped declaration that nothing mentions is indistinguishable from
+   * one that worked.
+   */
+  warnings: string[]
   manifest?: PluginManifest
   format: PluginFormat
   /** Resolved manifest path (empty when no manifest found). */
   manifestPath: string
 }
 
+/**
+ * Whether `loadPlugins` will hand this declaration to the MCP client.
+ *
+ * Lives here so the check and the loader read one rule: `plugin-loader.ts` calls
+ * this at its guard, and the MCP checks below call it to decide what to report. It
+ * requires a `name` because that is the key the client connects under, and one
+ * transport or the other — `McpServerConfig` makes `command` and `url` mutually
+ * exclusive, so demanding a `command` is what used to drop every remote server.
+ */
+export function isLoadableMcpConfig(cfg: {
+  name?: unknown
+  command?: unknown
+  url?: unknown
+}): boolean {
+  return (
+    typeof cfg.name === 'string' &&
+    cfg.name.length > 0 &&
+    (typeof cfg.command === 'string' || typeof cfg.url === 'string')
+  )
+}
+
 /**
  * Resolve a plugin's manifest. Mipham plugins use `plugin.json` at the plugin
  * root; Claude marketplace plugins use `.claude-plugin/plugin.json`.
@@ -39,12 +71,144 @@ export function detectPluginFormat(dir: string): PluginFormat {
   return resolveManifestPath(dir)?.format ?? 'mipham'
 }
 
+/**
+ * `${user_config.*}` is Claude Code's placeholder for a value it prompts the user
+ * for at install time. This loader has no such step: `expandPluginRoot` substitutes
+ * `${CLAUDE_PLUGIN_ROOT}` and nothing else, so the reference reaches the server as
+ * literal text. Every reference is reported — "declared" and "undeclared" are not a
+ * useful split here, because neither one resolves.
+ */
+const USER_CONFIG_RE = /\$\{user_config\.([A-Za-z0-9_.-]+)\}/g
+
+function userConfigKeys(texts: string[]): string[] {
+  const keys: string[] = []
+  const seen = new Set<string>()
+  for (const text of texts) {
+    for (const m of text.matchAll(USER_CONFIG_RE)) {
+      const key = m[1]!
+      if (seen.has(key)) continue
+      seen.add(key)
+      keys.push(key)
+    }
+  }
+  return keys
+}
+
+/** Hosts for which a cleartext URL stays on the machine, so there is nothing in transit. */
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '::1', '[::1]'])
+
+function cleartextWarning(server: string, url: string): string | null {
+  if (!/^http:\/\//i.test(url)) return null
+  let host: string
+  try {
+    host = new URL(url).hostname
+  } catch {
+    return null // an unparseable URL is not the finding this check is for
+  }
+  if (LOOPBACK_HOSTS.has(host)) return null
+  return `MCP server "${server}" uses a cleartext http:// URL (${url}) — it is readable in transit`
+}
+
+const DROPPED = 'declares neither command nor url and would be skipped at load'
+
+function describe(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}
+
+/** Check the Claude-format sources: `.mcp.json` at the root, plus inline `mcpServers`. */
+function checkClaudeMcp(
+  dir: string,
+  manifest: PluginManifest,
+  texts: string[],
+  warnings: string[],
+): void {
+  const inspect = (label: string, servers: unknown): void => {
+    if (!servers || typeof servers !== 'object') return
+    for (const [name, entry] of Object.entries(servers as Record<string, unknown>)) {
+      const raw = (entry ?? {}) as Record<string, unknown>
+      if (toMcpServerConfig(name, raw) === null) {
+        warnings.push(`${label}: MCP server "${name}" ${DROPPED}`)
+        continue
+      }
+      if (typeof raw.url === 'string') {
+        const cleartext = cleartextWarning(name, raw.url)
+        if (cleartext) warnings.push(`${label}: ${cleartext}`)
+      }
+    }
+  }
+
+  const mcpJsonPath = join(dir, '.mcp.json')
+  if (existsSync(mcpJsonPath)) {
+    const text = readFileSync(mcpJsonPath, 'utf-8')
+    texts.push(text)
+    try {
+      inspect('`.mcp.json`', (JSON.parse(text) as { mcpServers?: unknown }).mcpServers)
+    } catch (err) {
+      warnings.push(`\`.mcp.json\` could not be parsed and is skipped at load: ${describe(err)}`)
+    }
+  }
+
+  const inline = manifest.mcpServers
+  if (typeof inline === 'string') {
+    // The manifest type admits a string here, and the loader's `collect` returns
+    // early on anything that is not an object — so this form is declared and read
+    // by nothing.
+    warnings.push('`mcpServers` is a string; this loader only reads an object and ignores it')
+  } else {
+    inspect('manifest `mcpServers`', inline)
+  }
+}
+
+/** Check the Mipham-format source: `mcp-servers/*.json` at the plugin root. */
+function checkMiphamMcp(dir: string, texts: string[], warnings: string[]): void {
+  const mcpDir = join(dir, 'mcp-servers')
+  if (!existsSync(mcpDir)) return
+
+  let entries: string[]
+  try {
+    entries = readdirSync(mcpDir)
+  } catch {
+    return
+  }
+
+  for (const entry of entries) {
+    if (!entry.endsWith('.json')) continue
+    const label = `\`mcp-servers/${entry}\``
+    let text: string
+    try {
+      text = readFileSync(join(mcpDir, entry), 'utf-8')
+    } catch (err) {
+      warnings.push(`${label} could not be read and is skipped at load: ${describe(err)}`)
+      continue
+    }
+    texts.push(text)
+
+    let cfg: Record<string, unknown>
+    try {
+      cfg = JSON.parse(text) as Record<string, unknown>
+    } catch (err) {
+      warnings.push(`${label} could not be parsed and is skipped at load: ${describe(err)}`)
+      continue
+    }
+
+    if (!isLoadableMcpConfig(cfg ?? {})) {
+      warnings.push(`${label}: MCP server "${String(cfg?.name ?? entry)}" ${DROPPED}`)
+      continue
+    }
+    if (typeof cfg.url === 'string') {
+      const cleartext = cleartextWarning(String(cfg.name), cfg.url)
+      if (cleartext) warnings.push(`${label}: ${cleartext}`)
+    }
+  }
+}
+
 export function validatePlugin(dir: string): PluginValidation {
   const resolved = resolveManifestPath(dir)
   if (!resolved) {
     return {
       valid: false,
       errors: ['No plugin manifest found (expected plugin.json or .claude-plugin/plugin.json)'],
+      warnings: [],
       format: 'mipham',
       manifestPath: '',
     }
@@ -69,9 +233,26 @@ export function validatePlugin(dir: string): PluginValidation {
       }
     }
 
+    const warnings: string[] = []
+    // Every text read on the way to a declaration, so a `${user_config.*}` inside an
+    // `args` array or a header value is caught wherever it appears.
+    const texts: string[] = [raw]
+    if (resolved.format === 'claude') {
+      checkClaudeMcp(dir, manifest, texts, warnings)
+    } else {
+      checkMiphamMcp(dir, texts, warnings)
+    }
+    for (const key of userConfigKeys(texts)) {
+      warnings.push(
+        `\`\${user_config.${key}}\` is passed through literally — this loader has no user-config ` +
+          `step, so the server receives the text itself`,
+      )
+    }
+
     return {
       valid: errors.length === 0,
       errors,
+      warnings,
       manifest,
       format: resolved.format,
       manifestPath: resolved.path,
@@ -81,6 +262,7 @@ export function validatePlugin(dir: string): PluginValidation {
     return {
       valid: false,
       errors: [`Failed to read ${label}: ${String(err)}`],
+      warnings: [],
       format: resolved.format,
       manifestPath: resolved.path,
     }