opencode-raven 2.0.1 → 2.1.0

package/index.ts

@@ -1,5 +1,9 @@
 import type { Plugin, PluginInput } from "@opencode-ai/plugin"
 import { tool } from "@opencode-ai/plugin"
+import { Client } from "@modelcontextprotocol/sdk/client/index.js"
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js"
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js"
 import { readFileSync, writeFileSync, existsSync, mkdirSync, appendFileSync, readdirSync, rmSync } from "node:fs"
 import { join } from "node:path"
 import { homedir, tmpdir } from "node:os"
@@ -19,29 +23,43 @@ const DEFAULT_ROUTE_TOOLS = [
   "glob",
   "webfetch",
   "fetch",
+  "websearch",
   "bash",
 ]
 
-const DEFAULT_ROUTE_MCP_SERVERS = [
-  "context7",
-  "exa",
-  "grep_app",
-]
-
-const DEFAULT_ROUTE_TOOL_KEYWORDS = [
-  "search",
-  "context7",
-  "exa",
-  "grep_app",
-]
-
-const DEFAULT_MCP_SERVERS: Record<string, string> = {
-  context7: "https://mcp.context7.com/mcp",
-  exa: "https://mcp.exa.ai/mcp",
-  grep_app: "https://mcp.grep.app",
+const DEFAULT_ROUTE_TOOL_KEYWORDS: string[] = []
+
+const DEFAULT_ON_DEMAND_MCP_SERVERS: Record<string, OnDemandMcpServer> = {
+  context7: {
+    type: "remote",
+    url: "https://mcp.context7.com/mcp",
+    description: "Library/framework documentation lookup.",
+  },
+  exa: {
+    type: "remote",
+    url: "https://mcp.exa.ai/mcp",
+    description: "Live web search and webpage fetching.",
+  },
+  grep_app: {
+    type: "remote",
+    url: "https://mcp.grep.app",
+    description: "Public GitHub code search and real-world examples.",
+  },
 }
 
-const NEVER_ROUTE_TOOLS = new Set(["raven_seek", "task", "subtask"])
+const DEFAULT_ON_DEMAND_MCP_METADATA: Record<string, OnDemandMcpMetadata> = {
+  context7: {
+    autoGeneratedDescription: "Finds current library, framework, SDK, package, and API documentation; useful for implementation, configuration, and debugging with version-specific docs.",
+  },
+  exa: {
+    autoGeneratedDescription: "Searches the live web, fetches webpages, researches companies/products, and gathers current information from online sources.",
+  },
+  grep_app: {
+    autoGeneratedDescription: "Searches public GitHub repositories for real-world code examples, usage patterns, configuration snippets, and implementation references.",
+  },
+}
+
+const NEVER_ROUTE_TOOLS = new Set(["raven_seek", "raven_mcp", "task", "subtask"])
 
 // ── Bash commands that look like search workarounds ──
 const SEARCH_BASH_RE = /\b(?:rg|ripgrep|grep|egrep|fgrep|git\s+grep|ack|ag\b|findstr|Select-String)\b|\b(?:Get-ChildItem|gci)\b(?=[^|;&\n]*(?:-Recurse|-Filter|-Include|\s-[A-Za-z]*r[A-Za-z]*\b))|\bdir\b(?=[^|;&\n]*(?:[/-][sS]\b|-Recurse|-Filter|-Include))|\bls\b(?=[^|;&\n]*(?:\s-[A-Za-z]*R[A-Za-z]*\b|--recursive\b))|\bfind\b\s+.*(?:-name|-type)\b/i
@@ -114,15 +132,51 @@ function isSearchBash(tool: string, args: any): boolean {
 }
 
 // ── Config file shape ──
+interface OnDemandMcpToolInfo {
+  name: string
+  description?: string
+}
+
+interface BaseOnDemandMcpServer {
+  description?: string
+}
+
+interface OnDemandMcpMetadata {
+  autoGeneratedDescription?: string
+  autoGeneratedTools?: OnDemandMcpToolInfo[]
+  avoidedSchemaBytes?: number
+  status?: "pending" | "ready" | "failed"
+  lastError?: string
+  lastCheckedAt?: string
+}
+
+interface RemoteOnDemandMcpServer extends BaseOnDemandMcpServer {
+  type: "remote"
+  url: string
+  headers?: Record<string, string>
+}
+
+interface StdioOnDemandMcpServer extends BaseOnDemandMcpServer {
+  type: "stdio"
+  command: string
+  args?: string[]
+  env?: Record<string, string>
+  cwd?: string
+}
+
+type OnDemandMcpServer = RemoteOnDemandMcpServer | StdioOnDemandMcpServer
+type OnDemandMcpDescriptionDetail = "full" | "minimized"
+type RavenMcpOperation = "list_tools" | "call_tool" | "list_resources" | "read_resource" | "list_prompts" | "get_prompt"
+
 interface RavenConfig {
   enabled: boolean
   model?: string
   reasoning_effort?: string
-  ravenInstructions?: string
-  routeTools?: string[]
-  routeMcpServers?: string[]
-  routeToolKeywords?: string[]
-  allowBundledMCPServers?: boolean
+  ravenInstructions?: string
+  routeTools?: string[]
+  routeToolKeywords?: string[]
+  onDemandMcpDescriptionDetail?: OnDemandMcpDescriptionDetail
+  onDemandMcpServers?: Record<string, OnDemandMcpServer>
   excludeAgents?: string[]
   excludeTools?: string[]
   timeout?: number
@@ -137,11 +191,11 @@ const DEFAULT_CONFIG: RavenConfig = {
   enabled: true,
   model: fm.model,
   reasoning_effort: fm.reasoning_effort,
-  ravenInstructions: "",
-  routeTools: DEFAULT_ROUTE_TOOLS,
-  routeMcpServers: DEFAULT_ROUTE_MCP_SERVERS,
-  routeToolKeywords: DEFAULT_ROUTE_TOOL_KEYWORDS,
-  allowBundledMCPServers: true,
+  ravenInstructions: "",
+  routeTools: DEFAULT_ROUTE_TOOLS,
+  routeToolKeywords: DEFAULT_ROUTE_TOOL_KEYWORDS,
+  onDemandMcpDescriptionDetail: "full",
+  onDemandMcpServers: DEFAULT_ON_DEMAND_MCP_SERVERS,
   excludeAgents: [],
   excludeTools: [],
   timeout: 180,
@@ -230,25 +284,123 @@ function uniqueStrings(value: unknown, fallback: string[] = []): string[] {
   return [...new Set(source.filter((item) => typeof item === "string" && item.trim()).map((item) => item.trim()))]
 }
 
+function cloneOnDemandMcpServers(value: Record<string, OnDemandMcpServer>): Record<string, OnDemandMcpServer> {
+  return JSON.parse(JSON.stringify(value))
+}
+
+function cloneOnDemandMcpMetadata(value: Record<string, OnDemandMcpMetadata>): Record<string, OnDemandMcpMetadata> {
+  return JSON.parse(JSON.stringify(value))
+}
+
+function normalizeToolInfo(value: unknown): OnDemandMcpToolInfo[] | undefined {
+  if (!Array.isArray(value)) return undefined
+  const tools = value
+    .filter((item) => item && typeof item === "object" && typeof item.name === "string" && item.name.trim())
+    .map((item) => ({
+      name: item.name.trim(),
+      ...(typeof item.description === "string" && item.description.trim() ? { description: item.description.trim() } : {}),
+    }))
+  return tools.length ? tools : undefined
+}
+
+function normalizeOnDemandMcpServer(value: unknown): OnDemandMcpServer | undefined {
+  if (!value || typeof value !== "object") return undefined
+  const source = value as Record<string, any>
+  const base = {
+    ...(typeof source.description === "string" && source.description.trim() ? { description: source.description.trim() } : {}),
+  }
+
+  if (source.type === "stdio") {
+    if (typeof source.command !== "string" || !source.command.trim()) return undefined
+    return {
+      ...base,
+      type: "stdio",
+      command: source.command.trim(),
+      ...(Array.isArray(source.args) ? { args: source.args.filter((arg: unknown) => typeof arg === "string") } : {}),
+      ...(source.env && typeof source.env === "object" ? { env: Object.fromEntries(Object.entries(source.env).filter((entry): entry is [string, string] => typeof entry[1] === "string")) } : {}),
+      ...(typeof source.cwd === "string" && source.cwd.trim() ? { cwd: source.cwd.trim() } : {}),
+    }
+  }
+
+  if (source.type === "remote" || typeof source.url === "string") {
+    if (typeof source.url !== "string" || !source.url.trim()) return undefined
+    return {
+      ...base,
+      type: "remote",
+      url: source.url.trim(),
+      ...(source.headers && typeof source.headers === "object" ? { headers: Object.fromEntries(Object.entries(source.headers).filter((entry): entry is [string, string] => typeof entry[1] === "string")) } : {}),
+    }
+  }
+
+  return undefined
+}
+
+function normalizeOnDemandMcpMetadata(value: unknown, fallback: Record<string, OnDemandMcpMetadata> = {}): Record<string, OnDemandMcpMetadata> {
+  const source = value && typeof value === "object" ? value as Record<string, any> : fallback
+  const result: Record<string, OnDemandMcpMetadata> = {}
+  for (const [key, raw] of Object.entries(source)) {
+    if (!key.trim() || !raw || typeof raw !== "object") continue
+    const item = raw as Record<string, unknown>
+    const metadata: OnDemandMcpMetadata = {}
+    if (typeof item.autoGeneratedDescription === "string" && item.autoGeneratedDescription.trim()) {
+      metadata.autoGeneratedDescription = item.autoGeneratedDescription.trim()
+    }
+    const tools = normalizeToolInfo(item.autoGeneratedTools)
+    if (tools) metadata.autoGeneratedTools = tools
+    if (typeof item.avoidedSchemaBytes === "number" && Number.isFinite(item.avoidedSchemaBytes) && item.avoidedSchemaBytes >= 0) {
+      metadata.avoidedSchemaBytes = Math.round(item.avoidedSchemaBytes)
+    }
+    if (item.status === "pending" || item.status === "ready" || item.status === "failed") metadata.status = item.status
+    if (typeof item.lastError === "string" && item.lastError.trim()) metadata.lastError = item.lastError.trim()
+    if (typeof item.lastCheckedAt === "string" && item.lastCheckedAt.trim()) metadata.lastCheckedAt = item.lastCheckedAt.trim()
+    if (metadata.autoGeneratedDescription || metadata.autoGeneratedTools?.length || metadata.avoidedSchemaBytes || metadata.status || metadata.lastError || metadata.lastCheckedAt) result[key.trim()] = metadata
+  }
+  return result
+}
+
+function extractOnDemandMcpMetadata(value: unknown): Record<string, OnDemandMcpMetadata> {
+  return normalizeOnDemandMcpMetadata(value)
+}
+
+function normalizeOnDemandMcpServers(value: unknown, fallback: Record<string, OnDemandMcpServer> = {}): Record<string, OnDemandMcpServer> {
+  const source = value && typeof value === "object" ? value as Record<string, unknown> : fallback
+  const result: Record<string, OnDemandMcpServer> = {}
+  for (const [key, raw] of Object.entries(source)) {
+    if (!key.trim()) continue
+    const server = normalizeOnDemandMcpServer(raw)
+    if (server) result[key.trim()] = server
+  }
+  return result
+}
+
 // ── Plugin ──
 export default ((input: PluginInput) => {
   const client = input.client
 
-  // Config file lives in the global opencode config directory
-  const configFile = join(homedir(), ".config", "opencode", "raven-config.json")
+  // Raven state lives under the global opencode config directory.
+  const opencodeConfigDir = join(homedir(), ".config", "opencode")
+  const ravenConfigDir = join(opencodeConfigDir, "opencode-raven")
+  const oldConfigFile = join(opencodeConfigDir, "raven-config.json")
+  const configFile = join(ravenConfigDir, "raven-config.json")
+  const mcpMetadataFile = join(ravenConfigDir, "autogenerated-on-demand-mcp-metadata.json")
+  const dynamicGuidanceFile = join(ravenConfigDir, "autogenerated-on-demand-guidance.md")
+  let migratedFromOldConfig = false
+  let initialMcpMetadata: Record<string, OnDemandMcpMetadata> = {}
 
   function normalizeConfig(raw: any): RavenConfig {
     const source = raw && typeof raw === "object" ? raw : {}
-    const normalized: RavenConfig = { ...DEFAULT_CONFIG, ...source }
+    const normalized: RavenConfig = { ...DEFAULT_CONFIG }
 
     normalized.enabled = source.enabled !== false
     normalized.model = typeof source.model === "string" ? source.model : DEFAULT_CONFIG.model
     normalized.reasoning_effort = typeof source.reasoning_effort === "string" ? source.reasoning_effort : DEFAULT_CONFIG.reasoning_effort
-    normalized.ravenInstructions = typeof source.ravenInstructions === "string" ? source.ravenInstructions : DEFAULT_CONFIG.ravenInstructions
-    normalized.routeTools = uniqueStrings(source.routeTools, DEFAULT_ROUTE_TOOLS)
-    normalized.routeMcpServers = uniqueStrings(source.routeMcpServers, DEFAULT_ROUTE_MCP_SERVERS)
-    normalized.routeToolKeywords = uniqueStrings(source.routeToolKeywords, DEFAULT_ROUTE_TOOL_KEYWORDS)
-    normalized.allowBundledMCPServers = source.allowBundledMCPServers !== false
+    normalized.ravenInstructions = typeof source.ravenInstructions === "string" ? source.ravenInstructions : DEFAULT_CONFIG.ravenInstructions
+    normalized.routeTools = uniqueStrings(source.routeTools, DEFAULT_ROUTE_TOOLS)
+    normalized.routeToolKeywords = uniqueStrings(source.routeToolKeywords, DEFAULT_ROUTE_TOOL_KEYWORDS)
+    normalized.onDemandMcpDescriptionDetail = source.onDemandMcpDescriptionDetail === "minimized" ? "minimized" : "full"
+    normalized.onDemandMcpServers = source.onDemandMcpServers === undefined
+      ? cloneOnDemandMcpServers(DEFAULT_ON_DEMAND_MCP_SERVERS)
+      : normalizeOnDemandMcpServers(source.onDemandMcpServers)
     normalized.excludeAgents = uniqueStrings(source.excludeAgents)
     normalized.excludeTools = uniqueStrings(source.excludeTools)
     normalized.timeout = typeof source.timeout === "number" ? source.timeout : DEFAULT_CONFIG.timeout
@@ -259,12 +411,18 @@ export default ((input: PluginInput) => {
 
   function loadConfig(): RavenConfig {
     try {
-      if (existsSync(configFile)) {
-        const raw = JSON.parse(readFileSync(configFile, "utf-8"))
+      const sourceFile = existsSync(configFile) ? configFile : existsSync(oldConfigFile) ? oldConfigFile : undefined
+      if (sourceFile) {
+        const raw = JSON.parse(readFileSync(sourceFile, "utf-8"))
+        migratedFromOldConfig = sourceFile === oldConfigFile
+        initialMcpMetadata = extractOnDemandMcpMetadata(raw.onDemandMcpServers)
         const normalized = normalizeConfig(raw)
-        if (JSON.stringify(raw) !== JSON.stringify(normalized)) {
+        if (migratedFromOldConfig || JSON.stringify(raw) !== JSON.stringify(normalized)) {
           saveConfig(normalized)
         }
+        if (migratedFromOldConfig) {
+          try { rmSync(oldConfigFile, { force: true }) } catch { /* best-effort */ }
+        }
         return normalized
       }
     } catch { /* ignore corruption, use defaults */ }
@@ -275,19 +433,75 @@ export default ((input: PluginInput) => {
 
   function saveConfig(config: RavenConfig) {
     try {
-      mkdirSync(join(homedir(), ".config", "opencode"), { recursive: true })
+      mkdirSync(ravenConfigDir, { recursive: true })
       writeFileSync(configFile, JSON.stringify(config, null, 2) + "\n")
     } catch { /* non-fatal: config won't persist but toggle still works in-session */ }
   }
 
+  function loadMcpMetadata(seed: Record<string, OnDemandMcpMetadata>): Record<string, OnDemandMcpMetadata> {
+    const defaults = cloneOnDemandMcpMetadata(DEFAULT_ON_DEMAND_MCP_METADATA)
+    try {
+      if (existsSync(mcpMetadataFile)) {
+        return { ...defaults, ...normalizeOnDemandMcpMetadata(JSON.parse(readFileSync(mcpMetadataFile, "utf-8"))) }
+      }
+    } catch { /* ignore corruption, use defaults + seed */ }
+    const metadata = { ...defaults, ...seed }
+    saveMcpMetadata(metadata)
+    return metadata
+  }
+
+  function saveMcpMetadata(metadata: Record<string, OnDemandMcpMetadata>) {
+    try {
+      mkdirSync(ravenConfigDir, { recursive: true })
+      writeFileSync(mcpMetadataFile, JSON.stringify(metadata, null, 2) + "\n")
+    } catch { /* non-fatal: generated metadata can be refreshed */ }
+  }
+
+  function saveDynamicGuidance() {
+    try {
+      mkdirSync(ravenConfigDir, { recursive: true })
+      writeFileSync(dynamicGuidanceFile, `## Raven on-demand MCP capabilities\n\n${onDemandMcpGuidance("delegate")}\n`, "utf-8")
+    } catch { /* non-fatal: guidance still exists in tool/subagent paths */ }
+  }
+
+  function cleanupOldRootFiles() {
+    try {
+      if (existsSync(configFile)) rmSync(oldConfigFile, { force: true })
+    } catch { /* best-effort migration cleanup */ }
+  }
+
   let config = loadConfig()
+  let mcpMetadata = loadMcpMetadata(initialMcpMetadata)
   const ravenSessions = new Set<string>()
   const ravenTaskCalls = new Set<string>()
   const sessionAgents = new Map<string, string>()
   const ravenSessionParents = new Map<string, string>()
+  let globalMcpServers: string[] = []
+  let duplicateMcpServers: string[] = []
   let updateInfo: { current: string; latest?: string; available: boolean } | undefined
   let updateCheckPromise: Promise<{ current: string; latest?: string; available: boolean }> | undefined
   let updateToastPending = false
+  let mcpFailureToastPending = false
+  let duplicateMcpToastPending = false
+  let mcpRefreshScheduled = false
+  let mcpRefreshPromise: Promise<{ refreshed: string[]; failed: string[] }> | undefined
+  let lastNotifiedMcpFailureKey = ""
+
+  resetOnDemandMcpRuntimeStatuses()
+
+  function resetOnDemandMcpRuntimeStatuses() {
+    let changed = false
+    for (const name of Object.keys(config.onDemandMcpServers ?? {})) {
+      const metadata = mcpMetadata[name] ?? {}
+      if (metadata.status !== "pending" || metadata.lastError || metadata.lastCheckedAt) {
+        mcpMetadata[name] = { ...metadata, status: "pending" }
+        delete mcpMetadata[name].lastError
+        delete mcpMetadata[name].lastCheckedAt
+        changed = true
+      }
+    }
+    if (changed) saveMcpMetadata(mcpMetadata)
+  }
 
   // ── Check if an agent is excluded from Raven enforcement (case-insensitive) ──
   function isExcluded(agent: string | undefined): boolean {
@@ -297,19 +511,19 @@ export default ((input: PluginInput) => {
   }
 
   function ravenGuidance(): string {
-    const tools = config.routeTools?.length ? config.routeTools.join(", ") : "none"
-    const mcps = config.routeMcpServers?.length ? config.routeMcpServers.map((server) => `${server}_*`).join(", ") : "none"
-    const keywords = config.routeToolKeywords?.length ? config.routeToolKeywords.join(", ") : "none"
-    return `Some tools/MCPs are routed through Raven to save context. Routed tools: ${tools}. Routed MCP prefixes: ${mcps}. Routed tool-name keywords: ${keywords}. If one is blocked, your next tool call should be raven_seek(query="<same request>"). Include the original tool/MCP name and relevant arguments.`
-  }
+    const tools = config.routeTools?.length ? config.routeTools.join(", ") : "none"
+    const mcps = globalMcpServers.length ? globalMcpServers.map((server) => `${server}_*`).join(", ") : "none"
+    const keywords = config.routeToolKeywords?.length ? config.routeToolKeywords.join(", ") : "none"
+    return `Some tools/MCPs are routed through Raven to save context. Routed tools: ${tools}. Auto-routed global MCP prefixes: ${mcps}. Routed tool-name keywords: ${keywords}. ${onDemandMcpGuidance("delegate")} If one is blocked, your next tool call should be raven_seek(query="<same request>"). Include the original tool/MCP name and relevant arguments.`
+  }
 
   function isRouteConfigured(toolName: string): boolean {
     const tool = toolName.toLowerCase()
-    if (NEVER_ROUTE_TOOLS.has(tool)) return false
-    if (config.routeTools?.some((name) => name.toLowerCase() === tool)) return true
-    if (config.routeToolKeywords?.some((keyword) => tool.includes(keyword.toLowerCase()))) return true
-    return config.routeMcpServers?.some((server) => tool.startsWith(`${server.toLowerCase()}_`)) ?? false
-  }
+    if (NEVER_ROUTE_TOOLS.has(tool)) return false
+    if (config.routeTools?.some((name) => name.toLowerCase() === tool)) return true
+    if (config.routeToolKeywords?.some((keyword) => tool.includes(keyword.toLowerCase()))) return true
+    return globalMcpServers.some((server) => tool.startsWith(`${server.toLowerCase()}_`))
+  }
 
   function compactArgs(value: any): any {
     if (Array.isArray(value)) {
@@ -342,19 +556,423 @@ export default ((input: PluginInput) => {
   }
 
   function routeSummary(): string {
-    const tools = config.routeTools?.length ? config.routeTools.join(", ") : "(none)"
-    const mcps = config.routeMcpServers?.length ? config.routeMcpServers.join(", ") : "(none)"
-    const keywords = config.routeToolKeywords?.length ? config.routeToolKeywords.join(", ") : "(none)"
-    return `Raven routed tools/MCPs:\n  Tools: ${tools}\n  MCP servers: ${mcps}\n  Tool keywords: ${keywords}`
-  }
+    const tools = config.routeTools?.length ? config.routeTools.join(", ") : "(none)"
+    const mcps = globalMcpServers.length ? `${globalMcpServers.join(", ")} (auto-detected)` : "none detected"
+    const keywords = config.routeToolKeywords?.length ? config.routeToolKeywords.join(", ") : "(none)"
+    const duplicates = duplicateMcpServers.length ? `\n  Duplicate MCP config: ${duplicateMcpServers.join(", ")} (configured globally and on-demand)` : ""
+    return `Raven routing:\n  Routed tools: ${tools}\n  Routed global MCPs: ${mcps}\n  Routed tool keywords: ${keywords}${duplicates}`
+  }
 
   function mcpSummary(): string {
-    return `Raven bundled MCPs: ${config.allowBundledMCPServers === false ? "disabled" : Object.keys(DEFAULT_MCP_SERVERS).join(", ")}`
+    const buckets = onDemandMcpStatusBuckets()
+    const total = buckets.loaded.length + buckets.failed.length + buckets.pending.length
+    if (!total) return `Raven on-demand MCPs (always behind Raven): none configured.\n  Guidance detail: ${config.onDemandMcpDescriptionDetail ?? "full"}`
+    const lines = [
+      "Raven on-demand MCPs (always behind Raven):",
+      `  Loaded: ${buckets.loaded.length ? buckets.loaded.join(", ") : "none"}`,
+      `  Failed: ${buckets.failed.length ? buckets.failed.join(", ") : "none"}`,
+      `  Pending: ${buckets.pending.length ? buckets.pending.join(", ") : "none"}`,
+      `  Guidance detail: ${config.onDemandMcpDescriptionDetail ?? "full"}`,
+    ]
+    return lines.join("\n")
   }
 
   function ravenAgentPrompt(): string {
     const extra = config.ravenInstructions?.trim()
-    return extra ? `${ravenPrompt}\n\nAdditional user instructions:\n${extra}` : ravenPrompt
+    const onDemand = onDemandMcpGuidance("raven")
+    const prompt = `${ravenPrompt}\n\nOn-demand MCP guidance:\n${onDemand}\nUse direct MCP tools when they are available globally. Use raven_mcp for on-demand MCPs listed above. If you do not know the exact tool name for an on-demand MCP, call raven_mcp with operation list_tools first, then call the selected tool with operation call_tool. For call_tool and get_prompt, pass arguments as a JSON object string in argumentsJson.`
+    return extra ? `${prompt}\n\nAdditional user instructions:\n${extra}` : prompt
+  }
+
+  function truncateText(value: unknown, max = 240): string {
+    const text = String(value ?? "").replace(/\s+/g, " ").trim()
+    return text.length > max ? `${text.slice(0, Math.max(0, max - 3))}...` : text
+  }
+
+  function onDemandMcpGuidance(target: "delegate" | "raven" = "delegate"): string {
+    const servers = config.onDemandMcpServers ?? {}
+    const entries = Object.entries(servers)
+    if (!entries.length) return "No on-demand MCPs are configured."
+
+    const detail = config.onDemandMcpDescriptionDetail ?? "full"
+    const lines = entries.map(([name, server]) => {
+      const metadata = mcpMetadata[name] ?? {}
+      const userDescription = truncateText(server.description, 220)
+      const generated = truncateText(metadata.autoGeneratedDescription, 260)
+      const parts = [userDescription, generated ? `Discovered capabilities: ${generated}` : ""].filter(Boolean)
+      const summary = parts.length ? parts.join(" ") : "Description discovery pending."
+      if (detail === "minimized" || !metadata.autoGeneratedTools?.length) return `- ${name}: ${summary}`
+      const tools = metadata.autoGeneratedTools
+        .map((item) => `${item.name}${item.description ? ` - ${truncateText(item.description, 140)}` : ""}`)
+        .join("; ")
+      return `- ${name}: ${summary} Tools: ${tools}`
+    })
+    if (target === "raven") {
+      return `Raven can handle these on-demand MCP capabilities through raven_mcp:\n${lines.join("\n")}`
+    }
+    return `Raven can handle these on-demand MCP capabilities. Delegate matching requests with raven_seek; include the target MCP server and likely tool name when obvious, but do not call raven_mcp directly:\n${lines.join("\n")}`
+  }
+
+  function resolveEnvPlaceholders(value: string): string {
+    return value.replace(/\{env:([A-Za-z_][A-Za-z0-9_]*)\}/g, (_match, name) => {
+      const envValue = process.env[name]
+      if (envValue === undefined) throw new Error(`Missing environment variable ${name}`)
+      return envValue
+    })
+  }
+
+  function resolveStringRecord(value: Record<string, string> | undefined): Record<string, string> | undefined {
+    if (!value) return undefined
+    const result: Record<string, string> = {}
+    for (const [key, raw] of Object.entries(value)) {
+      result[key] = resolveEnvPlaceholders(raw)
+    }
+    return result
+  }
+
+  function cleanProcessEnv(): Record<string, string> {
+    const result: Record<string, string> = {}
+    for (const [key, value] of Object.entries(process.env)) {
+      if (typeof value === "string") result[key] = value
+    }
+    return result
+  }
+
+  async function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T> {
+    let timer: ReturnType<typeof setTimeout> | undefined
+    try {
+      return await Promise.race([
+        promise,
+        new Promise<never>((_, reject) => {
+          timer = setTimeout(() => reject(new Error(`${label} timed out after ${Math.round(ms / 1000)}s`)), ms)
+        }),
+      ])
+    } finally {
+      if (timer) clearTimeout(timer)
+    }
+  }
+
+  type McpConnection = {
+    client: Client
+    transport: any
+    serverName: string
+    lastUsed: number
+  }
+
+  const mcpConnections = new Map<string, McpConnection>()
+
+  async function closeMcpConnection(connection: McpConnection) {
+    try {
+      if (typeof connection.transport?.terminateSession === "function") {
+        await connection.transport.terminateSession()
+      }
+    } catch { /* best-effort */ }
+    try {
+      await connection.client.close()
+    } catch { /* best-effort */ }
+  }
+
+  async function closeMcpConnectionKey(key: string) {
+    const existing = mcpConnections.get(key)
+    if (!existing) return
+    mcpConnections.delete(key)
+    await closeMcpConnection(existing)
+  }
+
+  function closeIdleMcpConnections(maxAgeMs = 10 * 60 * 1000) {
+    const now = Date.now()
+    for (const [key, connection] of mcpConnections) {
+      if (now - connection.lastUsed > maxAgeMs) {
+        void closeMcpConnectionKey(key)
+      }
+    }
+  }
+
+  function mcpConnectionKey(sessionId: string, serverName: string): string {
+    return `${sessionId}:${serverName.toLowerCase()}`
+  }
+
+  function getOnDemandMcpServer(serverName: string): [string, OnDemandMcpServer] | undefined {
+    const entries = Object.entries(config.onDemandMcpServers ?? {})
+    return entries.find(([name]) => name.toLowerCase() === serverName.toLowerCase())
+  }
+
+  async function connectOnDemandMcp(serverName: string, server: OnDemandMcpServer): Promise<McpConnection> {
+    const timeout = (config.timeout ?? 180) * 1000
+    const client = new Client({ name: PACKAGE_NAME, version: PACKAGE_VERSION })
+
+    if (server.type === "stdio") {
+      const env = { ...cleanProcessEnv(), ...resolveStringRecord(server.env) }
+      const transport = new StdioClientTransport({
+        command: resolveEnvPlaceholders(server.command),
+        args: server.args?.map((arg) => resolveEnvPlaceholders(arg)),
+        env,
+        cwd: server.cwd ? resolveEnvPlaceholders(server.cwd) : undefined,
+      })
+      await withTimeout(client.connect(transport), timeout, `Connecting to ${serverName}`)
+      return { client, transport, serverName, lastUsed: Date.now() }
+    }
+
+    const url = new URL(resolveEnvPlaceholders(server.url))
+    const headers = resolveStringRecord(server.headers)
+    try {
+      const transport = new StreamableHTTPClientTransport(url, headers ? { requestInit: { headers } } : undefined)
+      await withTimeout(client.connect(transport), timeout, `Connecting to ${serverName}`)
+      return { client, transport, serverName, lastUsed: Date.now() }
+    } catch (err) {
+      try { await client.close() } catch { /* best-effort */ }
+      const fallbackClient = new Client({ name: PACKAGE_NAME, version: PACKAGE_VERSION })
+      const fallback = new SSEClientTransport(url, headers ? { requestInit: { headers } } : undefined)
+      await withTimeout(fallbackClient.connect(fallback), timeout, `Connecting to ${serverName} via SSE`)
+      return { client: fallbackClient, transport: fallback, serverName, lastUsed: Date.now() }
+    }
+  }
+
+  async function getMcpConnection(sessionId: string, serverName: string): Promise<McpConnection> {
+    closeIdleMcpConnections()
+    const match = getOnDemandMcpServer(serverName)
+    if (!match) throw new Error(`Unknown on-demand MCP server: ${serverName}`)
+    const [canonicalName, server] = match
+    const key = mcpConnectionKey(sessionId, canonicalName)
+    const existing = mcpConnections.get(key)
+    if (existing) {
+      existing.lastUsed = Date.now()
+      return existing
+    }
+    const connection = await connectOnDemandMcp(canonicalName, server)
+    mcpConnections.set(key, connection)
+    return connection
+  }
+
+  async function listAllMcpTools(client: Client): Promise<any[]> {
+    const tools: any[] = []
+    let cursor: string | undefined
+    do {
+      const result: any = await client.listTools(cursor ? { cursor } : undefined as any)
+      tools.push(...(result.tools ?? []))
+      cursor = result.nextCursor
+    } while (cursor)
+    return tools
+  }
+
+  async function listAllMcpResources(client: Client): Promise<any[]> {
+    const resources: any[] = []
+    let cursor: string | undefined
+    do {
+      const result: any = await client.listResources(cursor ? { cursor } : undefined as any)
+      resources.push(...(result.resources ?? []))
+      cursor = result.nextCursor
+    } while (cursor)
+    return resources
+  }
+
+  async function listAllMcpPrompts(client: Client): Promise<any[]> {
+    const prompts: any[] = []
+    let cursor: string | undefined
+    do {
+      const result: any = await client.listPrompts(cursor ? { cursor } : undefined as any)
+      prompts.push(...(result.prompts ?? []))
+      cursor = result.nextCursor
+    } while (cursor)
+    return prompts
+  }
+
+  function generatedToolsFromMcpTools(tools: any[]): OnDemandMcpToolInfo[] {
+    return tools
+      .filter((item) => item?.name)
+      .map((item) => ({
+        name: String(item.name),
+        ...(item.description ? { description: truncateText(item.description, 500) } : {}),
+      }))
+  }
+
+  function estimateAvoidedMcpSchemaBytes(tools: any[]): number {
+    if (!tools.length) return 0
+    return JSON.stringify(tools).length
+  }
+
+  function synthesizeMcpDescription(serverName: string, tools: OnDemandMcpToolInfo[]): string {
+    if (!tools.length) return `${serverName} exposes on-demand MCP capabilities. Use list_tools for available operations.`
+    const descriptions = tools.map((item) => item.description || item.name).filter(Boolean)
+    const joined = descriptions.slice(0, 6).join("; ")
+    return truncateText(`${serverName} provides on-demand MCP tools for ${joined}.`, 300)
+  }
+
+  async function refreshOnDemandMcpDescriptions(force = false, serverName?: string): Promise<{ refreshed: string[]; failed: string[] }> {
+    const entries = Object.entries(config.onDemandMcpServers ?? {})
+      .filter(([name]) => !serverName || name.toLowerCase() === serverName.toLowerCase())
+      .filter(([name]) => {
+        const metadata = mcpMetadata[name]
+        return force || metadata?.status === "pending" || metadata?.status === "failed" || !metadata?.autoGeneratedDescription || !metadata.autoGeneratedTools?.length || metadata.avoidedSchemaBytes === undefined
+      })
+    const refreshed: string[] = []
+    const failed: string[] = []
+    if (!entries.length) return { refreshed, failed }
+    let changed = false
+    for (const [name, server] of entries) {
+      let connection: McpConnection | undefined
+      const checkedAt = new Date().toISOString()
+      try {
+        connection = await connectOnDemandMcp(name, server)
+        const rawTools = await listAllMcpTools(connection.client)
+        const tools = generatedToolsFromMcpTools(rawTools)
+        mcpMetadata[name] = {
+          autoGeneratedTools: tools,
+          autoGeneratedDescription: synthesizeMcpDescription(name, tools),
+          avoidedSchemaBytes: estimateAvoidedMcpSchemaBytes(rawTools),
+          status: "ready",
+          lastCheckedAt: checkedAt,
+        }
+        changed = true
+        refreshed.push(name)
+      } catch (err: any) {
+        mcpMetadata[name] = {
+          ...(mcpMetadata[name] ?? {}),
+          status: "failed",
+          lastError: truncateText(err?.message ?? err, 500),
+          lastCheckedAt: checkedAt,
+        }
+        changed = true
+        failed.push(name)
+        // Keep startup/discovery best-effort; /raven mcp exposes failures.
+      } finally {
+        if (connection) await closeMcpConnection(connection)
+      }
+    }
+    if (changed) {
+      saveMcpMetadata(mcpMetadata)
+      saveDynamicGuidance()
+    }
+    return { refreshed, failed }
+  }
+
+  function scheduleOnDemandMcpRefresh(): Promise<{ refreshed: string[]; failed: string[] }> {
+    if (mcpRefreshScheduled && mcpRefreshPromise) return mcpRefreshPromise
+    mcpRefreshScheduled = true
+    mcpRefreshPromise = new Promise((resolve) => {
+      setTimeout(() => {
+        void refreshOnDemandMcpDescriptions().then(resolve)
+      }, 1000)
+    })
+    return mcpRefreshPromise
+  }
+
+  function onDemandMcpRuntimeStatus(name: string): "pending" | "ready" | "failed" {
+    const metadata = mcpMetadata[name]
+    if (metadata?.status) return metadata.status
+    return "pending"
+  }
+
+  function displayMcpStatus(status: "pending" | "ready" | "failed"): "pending" | "loaded" | "failed" {
+    return status === "ready" ? "loaded" : status
+  }
+
+  function onDemandMcpStatusBuckets(): { loaded: string[]; failed: string[]; pending: string[] } {
+    const buckets = { loaded: [] as string[], failed: [] as string[], pending: [] as string[] }
+    for (const name of Object.keys(config.onDemandMcpServers ?? {})) {
+      const status = onDemandMcpRuntimeStatus(name)
+      if (status === "ready") buckets.loaded.push(name)
+      else if (status === "failed") buckets.failed.push(name)
+      else buckets.pending.push(name)
+    }
+    return buckets
+  }
+
+  function failedOnDemandMcpNames(names?: string[]): string[] {
+    const configured = Object.keys(config.onDemandMcpServers ?? {})
+    const wanted = names?.length ? names : configured
+    return wanted.filter((name) => configured.includes(name) && onDemandMcpRuntimeStatus(name) === "failed")
+  }
+
+  function setOnDemandMcpHealth(serverName: string, status: "ready" | "failed", error?: unknown) {
+    const match = getOnDemandMcpServer(serverName)
+    if (!match) return undefined
+    const [name] = match
+    const next: OnDemandMcpMetadata = {
+      ...(mcpMetadata[name] ?? {}),
+      status,
+      lastCheckedAt: new Date().toISOString(),
+    }
+    if (status === "failed") next.lastError = truncateText(error, 500)
+    else delete next.lastError
+    mcpMetadata[name] = next
+    saveMcpMetadata(mcpMetadata)
+    return name
+  }
+
+  function onDemandMcpStatus(): string {
+    const entries = Object.entries(config.onDemandMcpServers ?? {})
+    if (!entries.length) return "Raven on-demand MCPs: none configured."
+    const buckets = onDemandMcpStatusBuckets()
+    const lines = entries.map(([name, server]) => {
+      const metadata = mcpMetadata[name]
+      const source = server.description ? "user description" : "no user description"
+      const generated = metadata?.autoGeneratedDescription ? "generated" : "missing generated description"
+      const tools = metadata?.autoGeneratedTools?.length ? `${metadata.autoGeneratedTools.length} tools` : "tools pending"
+      const status = onDemandMcpRuntimeStatus(name)
+      const avoided = status === "ready" && metadata?.avoidedSchemaBytes ? `, ${formatBytes(metadata.avoidedSchemaBytes)} avoided schema` : ""
+      const error = status === "failed" && metadata?.lastError ? `, error: ${metadata.lastError}` : ""
+      return `- ${name} (${server.type}): ${displayMcpStatus(status)}, ${source}, ${generated}, ${tools}${avoided}${error}`
+    })
+    return `Raven on-demand MCPs (${config.onDemandMcpDescriptionDetail ?? "full"} guidance):\n  Loaded: ${buckets.loaded.length ? buckets.loaded.join(", ") : "none"}\n  Failed: ${buckets.failed.length ? buckets.failed.join(", ") : "none"}\n  Pending: ${buckets.pending.length ? buckets.pending.join(", ") : "none"}\n${lines.join("\n")}`
+  }
+
+  function avoidedMcpSchemaBytes(): number {
+    return Object.keys(config.onDemandMcpServers ?? {}).reduce((sum, name) => {
+      const metadata = mcpMetadata[name]
+      if (onDemandMcpRuntimeStatus(name) !== "ready") return sum
+      return sum + Math.max(0, metadata?.avoidedSchemaBytes ?? 0)
+    }, 0)
+  }
+
+  function statsText(): string {
+    const avoided = avoidedMcpSchemaBytes()
+    return `Raven context saved:\n  Avoided MCP schema load: ${formatBytes(avoided)} (~${formatTokens(avoided)} context)\n  This session: ${formatBytes(sessionBytes)} (~${formatTokens(sessionBytes)} context)\n  All time: ${formatBytes(totalBytes)} (~${formatTokens(totalBytes)} context)`
+  }
+
+  function helpText(): string {
+    return `Raven commands:\n  /raven help   — show this help\n  /raven on     — enable tool/MCP routing\n  /raven off    — disable tool/MCP routing\n  /raven route  — show or edit routed tools/keywords\n  /raven mcp    — show or refresh on-demand MCP metadata\n  /raven update — check npm, clear plugin cache if newer, then restart opencode\n  /raven model <name> — change Raven's model (requires restart)\n  /raven effort <value> — change Raven's reasoning effort (requires restart)\n  /raven timeout <seconds> — change raven_seek timeout\n  /raven stats  — show context saved`
+  }
+
+  function formatMcpList(title: string, items: any[], fields: string[] = ["name", "description"]): string {
+    if (!items.length) return `${title}: none found.`
+    const lines = items.map((item) => {
+      const primary = fields.map((field) => item?.[field]).find(Boolean) ?? JSON.stringify(item)
+      const description = item?.description && primary !== item.description ? ` - ${truncateText(item.description, 300)}` : ""
+      return `- ${truncateText(primary, 180)}${description}`
+    })
+    return `${title}:\n${lines.join("\n")}`
+  }
+
+  function formatMcpToolsForRaven(serverName: string, tools: any[]): string {
+    if (!tools.length) return `Tools for ${serverName}: none found.`
+    const lines = tools.map((item) => {
+      const description = item?.description ? `\n  Description: ${truncateText(item.description, 600)}` : ""
+      const schema = item?.inputSchema ? `\n  Input schema: ${truncateText(JSON.stringify(item.inputSchema), 3000)}` : ""
+      return `- ${item?.name ?? "(unnamed)"}${description}${schema}`
+    })
+    return `Tools for ${serverName}:\n${lines.join("\n")}`
+  }
+
+  function formatMcpResult(result: any): string {
+    if (!result) return "No result."
+    if (Array.isArray(result.content)) {
+      const parts = result.content.map((part: any) => {
+        if (part?.type === "text") return part.text
+        return JSON.stringify(part)
+      })
+      return parts.join("\n") || JSON.stringify(result)
+    }
+    return typeof result === "string" ? result : JSON.stringify(result, null, 2)
+  }
+
+  function parseMcpArguments(raw: string | undefined): Record<string, any> {
+    if (!raw?.trim()) return {}
+    const parsed = JSON.parse(raw)
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error("argumentsJson must be a JSON object")
+    }
+    return parsed
   }
 
   // ── Context saved by Raven delegation ──
@@ -496,34 +1114,58 @@ export default ((input: PluginInput) => {
     } catch { /* update checks are best-effort */ }
   }
 
-  function ensureRemoteMcp(configInput: any, key: string, url: string) {
-    const existing = configInput.mcp?.[key] && typeof configInput.mcp[key] === "object"
-      ? configInput.mcp[key]
-      : {}
-    const type = existing.type ?? "remote"
-    configInput.mcp[key] = {
-      ...existing,
-      type,
-      ...(type === "local" ? {} : { url: existing.url ?? url }),
-      enabled: existing.enabled ?? true,
-    }
+  async function notifyIfMcpFailures(names?: string[]) {
+    try {
+      const failed = failedOnDemandMcpNames(names)
+      if (!failed.length) return
+      const key = failed.sort().join("|")
+      if (key === lastNotifiedMcpFailureKey) return
+      lastNotifiedMcpFailureKey = key
+      const label = failed.length === 1 ? failed[0] : `${failed.length} on-demand MCPs`
+      await (client as any).tui?.showToast?.({
+        body: {
+          title: "Raven MCP warning",
+          message: `${label} failed to load. Run /raven mcp for details.`,
+          variant: "warning",
+          duration: 12000,
+        },
+      })
+    } catch { /* MCP failure notifications are best-effort */ }
+  }
+
+  async function notifyIfDuplicateMcps() {
+    try {
+      if (!duplicateMcpServers.length) return
+      const label = duplicateMcpServers.length === 1 ? duplicateMcpServers[0] : `${duplicateMcpServers.length} MCPs`
+      await (client as any).tui?.showToast?.({
+        body: {
+          title: "Raven MCP duplicate config",
+          message: `${label} configured both globally and on-demand. Prefer one location to avoid duplicate schema/connection behavior.`,
+          variant: "warning",
+          duration: 12000,
+        },
+      })
+    } catch { /* duplicate MCP notifications are best-effort */ }
   }
 
   return {
     config(configInput: any) {
-      // Bundled MCP defaults. Existing opencode.jsonc entries are merged, not overwritten.
-      if (config.allowBundledMCPServers !== false) {
-        configInput.mcp = configInput.mcp || {}
-        for (const [key, url] of Object.entries(DEFAULT_MCP_SERVERS)) {
-          ensureRemoteMcp(configInput, key, url)
-        }
-      }
+      globalMcpServers = uniqueStrings(Object.entries(configInput.mcp ?? {})
+        .filter(([, value]) => !value || typeof value !== "object" || (value as any).enabled !== false)
+        .map(([name]) => name))
+      const onDemandNames = new Set(Object.keys(config.onDemandMcpServers ?? {}).map((name) => name.toLowerCase()))
+      duplicateMcpServers = globalMcpServers.filter((name) => onDemandNames.has(name.toLowerCase()))
 
       // Inject MCP guidance as a startup instruction file (absolute path for npm compat)
+      saveDynamicGuidance()
+      cleanupOldRootFiles()
       configInput.instructions = configInput.instructions || []
       if (!configInput.instructions.includes(MCP_GUIDANCE_MD)) {
         configInput.instructions.push(MCP_GUIDANCE_MD)
       }
+      if (!configInput.instructions.includes(dynamicGuidanceFile)) {
+        configInput.instructions.push(dynamicGuidanceFile)
+      }
 
       // Register Raven from Raven.md, with config file overrides
       configInput.agent = configInput.agent || {}
@@ -544,18 +1186,21 @@ export default ((input: PluginInput) => {
       configInput.command = configInput.command || {}
       if (!configInput.command.raven) {
         configInput.command.raven = {
-          template: "Manage Raven: /raven on|off|route|update|model <name>|status",
-          description: "Toggle Raven routing, manage routed tools/MCPs, or change Raven's model",
+          template: "Manage Raven: /raven on|off|route|mcp|update|model <name>|status",
+          description: "Toggle Raven routing, manage routed/on-demand MCPs, or change Raven's model",
         }
       }
 
+      scheduleOnDemandMcpRefresh()
       updateToastPending = true
+      mcpFailureToastPending = true
+      duplicateMcpToastPending = duplicateMcpServers.length > 0
     },
 
     // Register raven_seek tool — lets agents with task:false still delegate through Raven
     tool: {
       "raven_seek": tool({
-        description: "Unified Raven delegation tool. Use this whenever a tool/MCP is blocked by Raven, or when grep, glob, WebFetch/fetch, websearch, docs lookup, GitHub search, or search-like bash would be used. Handles routed MCP requests, local codebase search, filesystem discovery, specific URL/page reads, web/docs research, GitHub examples, and command-output/system inspection via Raven.",
+        description: "Unified Raven delegation tool. Use this whenever a tool/MCP is blocked by Raven, or when grep, glob, WebFetch/fetch, websearch, docs lookup, GitHub search, on-demand MCP capabilities, or search-like bash would be used. Handles routed MCP requests, on-demand MCPs, local codebase search, filesystem discovery, specific URL/page reads, web/docs research, GitHub examples, and command-output/system inspection via Raven.",
         args: {
           query: tool.schema.string().describe("What Raven should do. Include the original blocked tool/MCP request and relevant args, exact URLs when replacing WebFetch, and commands/output checks when replacing grep/rg/head over command output."),
         },
@@ -641,6 +1286,85 @@ export default ((input: PluginInput) => {
           }
         },
       }),
+      "raven_mcp": tool({
+        description: "Raven-only bridge for on-demand MCP servers. Non-Raven agents must not call this directly; use raven_seek instead. Raven uses this to list and call tools/resources/prompts from MCPs configured in Raven's onDemandMcpServers without exposing their full schemas to the main model.",
+        args: {
+          server: tool.schema.string().describe("On-demand MCP server name from Raven config, e.g. context7, exa, grep_app, unityMCP."),
+          operation: tool.schema.enum(["list_tools", "call_tool", "list_resources", "read_resource", "list_prompts", "get_prompt"]).describe("MCP operation to perform."),
+          name: tool.schema.string().optional().describe("Tool name for call_tool, resource URI for read_resource, or prompt name for get_prompt."),
+          argumentsJson: tool.schema.string().optional().describe("JSON object string with arguments for call_tool or get_prompt, e.g. {\"query\":\"latest AI news\"}. Omit for no arguments."),
+        },
+        async execute(args, context) {
+          if (!ravenSessions.has(context.sessionID) && sessionAgents.get(context.sessionID) !== "raven") {
+            return { title: "Raven MCP", output: "raven_mcp is only available inside Raven. Use raven_seek for MCP requests." }
+          }
+
+          const operation = args.operation as RavenMcpOperation
+          const timeout = (config.timeout ?? 180) * 1000
+          let connected = false
+          try {
+            const connection = await getMcpConnection(context.sessionID, args.server)
+            connected = true
+            setOnDemandMcpHealth(args.server, "ready")
+            connection.lastUsed = Date.now()
+            const client = connection.client
+
+            if (operation === "list_tools") {
+              const tools = await withTimeout(listAllMcpTools(client), timeout, `Listing ${args.server} tools`)
+              const match = getOnDemandMcpServer(args.server)
+              if (match) {
+                const [name] = match
+                const generatedTools = generatedToolsFromMcpTools(tools)
+                mcpMetadata[name] = {
+                  autoGeneratedTools: generatedTools,
+                  autoGeneratedDescription: mcpMetadata[name]?.autoGeneratedDescription || synthesizeMcpDescription(name, generatedTools),
+                  avoidedSchemaBytes: estimateAvoidedMcpSchemaBytes(tools),
+                  status: "ready",
+                  lastCheckedAt: new Date().toISOString(),
+                }
+                saveMcpMetadata(mcpMetadata)
+              }
+              return { title: `Raven MCP: ${args.server}`, output: formatMcpToolsForRaven(args.server, tools) }
+            }
+
+            if (operation === "call_tool") {
+              if (!args.name) return { title: `Raven MCP: ${args.server}`, output: "call_tool requires name." }
+              const result = await withTimeout(client.callTool({ name: args.name, arguments: parseMcpArguments(args.argumentsJson) }), timeout, `Calling ${args.server}.${args.name}`)
+              return { title: `Raven MCP: ${args.server}.${args.name}`, output: formatMcpResult(result) }
+            }
+
+            if (operation === "list_resources") {
+              const resources = await withTimeout(listAllMcpResources(client), timeout, `Listing ${args.server} resources`)
+              return { title: `Raven MCP: ${args.server}`, output: formatMcpList(`Resources for ${args.server}`, resources, ["uri", "name", "description"]) }
+            }
+
+            if (operation === "read_resource") {
+              if (!args.name) return { title: `Raven MCP: ${args.server}`, output: "read_resource requires name as the resource URI." }
+              const result = await withTimeout(client.readResource({ uri: args.name }), timeout, `Reading ${args.server} resource`)
+              return { title: `Raven MCP: ${args.server}`, output: formatMcpResult(result) }
+            }
+
+            if (operation === "list_prompts") {
+              const prompts = await withTimeout(listAllMcpPrompts(client), timeout, `Listing ${args.server} prompts`)
+              return { title: `Raven MCP: ${args.server}`, output: formatMcpList(`Prompts for ${args.server}`, prompts) }
+            }
+
+            if (operation === "get_prompt") {
+              if (!args.name) return { title: `Raven MCP: ${args.server}`, output: "get_prompt requires name." }
+              const result = await withTimeout(client.getPrompt({ name: args.name, arguments: parseMcpArguments(args.argumentsJson) }), timeout, `Getting ${args.server} prompt`)
+              return { title: `Raven MCP: ${args.server}.${args.name}`, output: formatMcpResult(result) }
+            }
+
+            return { title: `Raven MCP: ${args.server}`, output: `Unsupported operation: ${operation}` }
+          } catch (err: any) {
+            if (!connected) {
+              const name = setOnDemandMcpHealth(args.server, "failed", err?.message ?? err)
+              if (name) await notifyIfMcpFailures([name])
+            }
+            return { title: `Raven MCP: ${args.server}`, output: `MCP call failed: ${err?.message ?? err}` }
+          }
+        },
+      }),
     },
 
     // Track agent ↔ session mapping for allowlist + Raven exclusion
@@ -660,12 +1384,21 @@ export default ((input: PluginInput) => {
         ravenSessionParents.set(evt.properties.parentID, evt.properties.id)
       }
 
-      if (!updateToastPending) return
-      updateToastPending = false
-      setTimeout(() => void notifyIfUpdateAvailable(), 500)
+      if (updateToastPending) {
+        updateToastPending = false
+        setTimeout(() => void notifyIfUpdateAvailable(), 500)
+      }
+      if (mcpFailureToastPending) {
+        mcpFailureToastPending = false
+        void scheduleOnDemandMcpRefresh().then((result) => notifyIfMcpFailures(result.failed))
+      }
+      if (duplicateMcpToastPending) {
+        duplicateMcpToastPending = false
+        setTimeout(() => void notifyIfDuplicateMcps(), 700)
+      }
     },
 
-    // /raven on|off|route|model <name>|effort <value>|timeout <seconds>|stats|status
+    // /raven help|on|off|route|mcp|model <name>|effort <value>|timeout <seconds>|stats|status
     async "command.execute.before"(input: any, output: any) {
       if (input.command !== "raven") return
       output.parts.length = 0
@@ -676,23 +1409,25 @@ export default ((input: PluginInput) => {
         config.enabled = true
         saveConfig(config)
         output.parts.push({ type: "text", text: "Raven tool/MCP routing enabled. Non-Raven agents will be redirected to raven_seek for configured tools." })
+      } else if (arg === "help") {
+        output.parts.push({ type: "text", text: helpText() })
       } else if (arg === "off") {
         config.enabled = false
         saveConfig(config)
         output.parts.push({ type: "text", text: "Raven tool/MCP routing disabled. All agents can use tools directly." })
       } else if (arg === "stats") {
-        output.parts.push({ type: "text", text: `Raven context saved:\n  This session: ${formatBytes(sessionBytes)} (~${formatTokens(sessionBytes)} context)\n  All time: ${formatBytes(totalBytes)} (~${formatTokens(totalBytes)} context)` })
+        output.parts.push({ type: "text", text: statsText() })
       } else if (arg === "route") {
-        output.parts.push({ type: "text", text: `${routeSummary()}\n\nUsage:\n  /raven route tool add <tool_name>\n  /raven route tool remove <tool_name>\n  /raven route mcp add <server_name>\n  /raven route mcp remove <server_name>\n  /raven route keyword add <keyword>\n  /raven route keyword remove <keyword>` })
-      } else if (arg.startsWith("route ")) {
-        const parts = raw.split(/\s+/)
-        const kind = parts[1]?.toLowerCase()
-        const action = parts[2]?.toLowerCase()
-        const name = parts.slice(3).join(" ").trim()
-        const key = kind === "tool" ? "routeTools" : kind === "mcp" || kind === "server" ? "routeMcpServers" : kind === "keyword" ? "routeToolKeywords" : undefined
-
-        if (!key || !["add", "remove", "rm"].includes(action) || !name) {
-          output.parts.push({ type: "text", text: "Usage:\n  /raven route tool add <tool_name>\n  /raven route tool remove <tool_name>\n  /raven route mcp add <server_name>\n  /raven route mcp remove <server_name>\n  /raven route keyword add <keyword>\n  /raven route keyword remove <keyword>" })
+        output.parts.push({ type: "text", text: `${routeSummary()}\n\nUsage:\n  /raven route tool add <tool_name>\n  /raven route tool remove <tool_name>\n  /raven route keyword add <keyword>\n  /raven route keyword remove <keyword>\n\nGlobal MCPs are auto-routed by detected OpenCode MCP server name.` })
+      } else if (arg.startsWith("route ")) {
+        const parts = raw.split(/\s+/)
+        const kind = parts[1]?.toLowerCase()
+        const action = parts[2]?.toLowerCase()
+        const name = parts.slice(3).join(" ").trim()
+        const key = kind === "tool" ? "routeTools" : kind === "keyword" ? "routeToolKeywords" : undefined
+
+        if (!key || !["add", "remove", "rm"].includes(action) || !name) {
+          output.parts.push({ type: "text", text: "Usage:\n  /raven route tool add <tool_name>\n  /raven route tool remove <tool_name>\n  /raven route keyword add <keyword>\n  /raven route keyword remove <keyword>\n\nGlobal MCPs are auto-routed by detected OpenCode MCP server name." })
         } else {
           const values = uniqueStrings(config[key])
           const exists = values.some((value) => value.toLowerCase() === name.toLowerCase())
@@ -702,6 +1437,31 @@ export default ((input: PluginInput) => {
           saveConfig(config)
           output.parts.push({ type: "text", text: routeSummary() })
         }
+      } else if (arg === "mcp") {
+        output.parts.push({ type: "text", text: `${onDemandMcpStatus()}\n\nUsage:\n  /raven mcp refresh [server_name]\n  /raven mcp detail full\n  /raven mcp detail minimized` })
+      } else if (arg.startsWith("mcp ")) {
+        const parts = raw.split(/\s+/)
+        const action = parts[1]?.toLowerCase()
+        if (action === "refresh") {
+          const serverName = parts.slice(2).join(" ").trim() || undefined
+          const result = await refreshOnDemandMcpDescriptions(true, serverName)
+          await notifyIfMcpFailures(result.failed)
+          output.parts.push({
+            type: "text",
+            text: `On-demand MCP refresh complete.\n  Refreshed: ${result.refreshed.length ? result.refreshed.join(", ") : "none"}\n  Failed: ${result.failed.length ? result.failed.join(", ") : "none"}`,
+          })
+        } else if (action === "detail") {
+          const detail = parts[2]?.toLowerCase()
+          if (detail !== "full" && detail !== "minimized") {
+            output.parts.push({ type: "text", text: `Usage: /raven mcp detail full|minimized\nCurrent: ${config.onDemandMcpDescriptionDetail ?? "full"}` })
+          } else {
+            config.onDemandMcpDescriptionDetail = detail
+            saveConfig(config)
+            output.parts.push({ type: "text", text: `On-demand MCP guidance detail set to: ${detail}\nRestart opencode for startup instructions/tool descriptions to fully refresh.` })
+          }
+        } else {
+          output.parts.push({ type: "text", text: "Usage:\n  /raven mcp\n  /raven mcp refresh [server_name]\n  /raven mcp detail full\n  /raven mcp detail minimized" })
+        }
       } else if (arg === "update") {
         try {
           const info = await refreshUpdateInfo()
@@ -755,7 +1515,7 @@ export default ((input: PluginInput) => {
             ? `Update: ${info.latest} available. Run /raven update, then restart opencode.`
             : `Update: up to date${info.latest ? ` (latest ${info.latest})` : ""}.`
         } catch { /* keep fallback */ }
-        output.parts.push({ type: "text", text: `Raven is ${enabled}. Version: ${PACKAGE_VERSION}. Model: ${model}. Reasoning: ${effort}. Timeout: ${timeout}s\n${update}\n\n${routeSummary()}\n\n${mcpSummary()}\n\nRaven context saved:\n  This session: ${formatBytes(sessionBytes)} (~${formatTokens(sessionBytes)} context)\n  All time: ${formatBytes(totalBytes)} (~${formatTokens(totalBytes)} context)\n\nCommands:\n  /raven on      — enable tool/MCP routing\n  /raven off     — disable tool/MCP routing\n  /raven route   — show or edit routed tools/MCP servers/keywords\n  /raven update  — check npm, clear plugin cache if newer, then restart opencode\n  /raven model <name> — change Raven's model (requires restart)\n  /raven effort <value> — change Raven's reasoning effort (requires restart)\n  /raven timeout <seconds> — change raven_seek timeout\n  /raven stats   — show context saved` })
+        output.parts.push({ type: "text", text: `Raven is ${enabled}. Version: ${PACKAGE_VERSION}. Model: ${model}. Reasoning: ${effort}. Timeout: ${timeout}s\n${update}\n\n${routeSummary()}\n\n${mcpSummary()}\n\n${statsText()}\n\nRun /raven help for commands.` })
       }
     },
 
@@ -764,6 +1524,10 @@ export default ((input: PluginInput) => {
         throw new Error("raven_seek is disabled inside Raven. Use Raven's direct search/fetch tools instead.")
       }
 
+      if (input.tool === "raven_mcp" && !ravenSessions.has(input.sessionID) && sessionAgents.get(input.sessionID) !== "raven") {
+        throw new Error("raven_mcp is only available inside Raven. Use raven_seek(query=\"Use the relevant on-demand MCP to handle this request\") instead.")
+      }
+
       if (!config.enabled) return
       if (ravenSessions.has(input.sessionID)) return
       if (isExcluded(sessionAgents.get(input.sessionID))) return