opencode-raven 2.1.0 → 2.1.2

package/README.md

@@ -2,27 +2,27 @@
 
 <table>
 <tr>
-<td><img src="Raven.png" alt="Raven" width="768" /></td>
+<td width="40%"><img src="Raven.png" alt="Raven" width="100%" /></td>
 <td>
-<strong>Context firewall for <a href="https://opencode.ai">OpenCode</a></strong><br/>
-Raven routes noisy search, docs, web, GitHub, and MCP calls through a free focused agent before they hit your main model, saving cost and context.
+Raven gives OpenCode useful search tools by default and optional on-demand MCPs for any remote or local MCP you want to add. It keeps noisy tool work behind a focused Raven agent, so your main model gets compact answers instead of raw search results, docs pages, GitHub examples, MCP output, or large MCP schemas.
+
+## Why Use Raven?
+
+* Routed search, fetch, and bash discovery work through Raven.
+* Context7, Exa, and Grep.app are bundled as on-demand MCP defaults.
+* Any extra MCP can be added under `onDemandMcpServers` when you want it.
+* Configured noisy tools and MCPs are blocked for non-Raven agents and forced through `raven_seek`.
 </td>
 </tr>
 </table>
 
-## What Raven Does
-
-Tool-heavy work floods context. Search, docs, web, GitHub examples, and verbose MCP calls can dump raw results into your expensive main model. Raven is a hard blocker-rerouter: configured tools fail closed for non-Raven agents and must be delegated through `raven_seek`, where a focused Raven agent performs the work and returns a compact answer.
-
-Raven fixes three problems:
-
-1. **Context flooding** - Keep noisy tool results out of the main session. Raven summarizes tool/MCP output before returning it.
-2. **Cost** - Use a cheaper model like `opencode/deepseek-v4-flash-free` for tool-heavy work while saving your main model's context for decisions and edits.
-3. **Enforcement** - This is not soft nudging. Raven blocks configured tools/MCP prefixes for non-Raven agents and gives them the exact `raven_seek` retry path.
+## Example
 
-Raven defaults to routing noisy search/fetch tools and bundles Context7, Exa, and Grep.app as on-demand MCPs that are always handled behind Raven.
+<p align="center">
+  <img src="example.gif" alt="Raven example: searching today's top 30 AI news items while saving 71K context" />
+</p>
 
-Important limitation: MCPs enabled directly in OpenCode config still load their tool schemas into the main session. Raven saves context from tool calls and raw results for those global MCPs, but schema hiding requires putting the MCP in Raven's `onDemandMcpServers`. **Strongly recommended:** configure noisy/search/docs/web MCPs as on-demand MCPs unless you need direct main-agent access.
+In this example, the main model asks for the top 30 AI news items from today. Raven handles the noisy search/web work in a focused agent and returns the compact result, saving about 71K context that would otherwise have landed in the main session.
 
 ## Install
 
@@ -36,6 +36,8 @@ Add Raven to your `opencode.jsonc` plugins:
 
 Restart opencode. It will resolve Raven from npm and cache the plugin automatically.
 
+That is enough to start using Raven. The default config already includes routed search/fetch tools and bundled on-demand MCPs for Context7, Exa, and Grep.app. Add any other MCP under `onDemandMcpServers` only if you want more capabilities.
+
 Raven checks for package updates and notifies you when a newer version is available. Run `/raven update`, then restart opencode.
 
 ## Quick Use
@@ -78,17 +80,11 @@ The main agent does not see Raven's internal tool calls or raw tool output, just
 
 Config persists across restarts in `~/.config/opencode/opencode-raven/raven-config.json`. It is global and shared across all projects.
 
-## Example
-
-<p align="center">
-  <img src="example.gif" alt="Raven example: searching today's top 30 AI news items while saving 71K context" />
-</p>
-
-In this example, the main model asks for the top 30 AI news items from today. Raven handles the noisy search/web work in a focused agent and returns the compact result, saving about 71K context that would otherwise have landed in the main session.
-
 ## Recommended MCP Setup
 
-Raven's bundled Context7, Exa, and Grep.app MCPs are on-demand by default. They live in `onDemandMcpServers`, so Raven connects to them internally through `raven_mcp` instead of registering their full tool schemas in OpenCode's global MCP config.
+You do not need to configure MCPs just to try Raven. Raven gives you the search tools up front, supports any MCP as an on-demand MCP, and bundles Context7, Exa, and Grep.app as defaults. Add more MCPs only when you want extra capabilities.
+
+On-demand MCPs live in `onDemandMcpServers`, so Raven connects to them internally through `raven_mcp` only when needed instead of registering their full tool schemas in OpenCode's global MCP config. Context7, Exa, and Grep.app are included there by default, but the same setup works for any remote or local MCP you want to add.
 
 On-demand MCPs are always behind Raven and do not need routing entries.
 
@@ -96,6 +92,8 @@ Raven checks configured on-demand MCPs after startup. `/raven` and `/raven mcp`
 
 Raven also warns if the same MCP server name is configured both globally in OpenCode and in Raven's `onDemandMcpServers`. Prefer one location: on-demand for schema hiding, or global only when direct main-agent access is required.
 
+Important limitation: MCPs enabled directly in OpenCode config still load their tool schemas into the main session. Raven saves context from tool calls and raw results for those global MCPs, but schema hiding requires putting the MCP in Raven's `onDemandMcpServers`. **Strongly recommended:** configure noisy/search/docs/web MCPs as on-demand MCPs unless you need direct main-agent access.
+
 All three bundled MCPs work without API keys. Add keys for higher rate limits:
 
 | MCP | URL | API key |
@@ -119,23 +117,36 @@ To add an API key to an on-demand MCP, edit Raven config:
 }
 ```
 
-To add a local stdio MCP:
+### Add Your Own On-Demand MCP
+
+To add another MCP, put it under `onDemandMcpServers`. Raven will connect to it only when needed, discover its tools, and generate guidance automatically. Your main model does not need to load that MCP's full schema up front.
+
+Use `remote` for hosted MCPs and `local` for command-based MCPs.
+
+To add an OpenCode-style local MCP:
 
 ```jsonc
 {
   "onDemandMcpServers": {
-    "localServer": {
-      "type": "stdio",
-      "command": "bunx",
-      "args": ["some-mcp-server"],
-      "env": { "API_KEY": "{env:API_KEY}" },
-      "cwd": "/optional/path",
-      "description": "Local MCP server."
+    "unityMCP": {
+      "type": "local",
+      "command": [
+        "C:\\Users\\evila\\.local\\bin\\uvx.exe",
+        "--offline",
+        "--from",
+        "mcpforunityserver==9.7.1",
+        "mcp-for-unity",
+        "--transport",
+        "stdio"
+      ],
+      "enabled": true
     }
   }
 }
 ```
 
+This matches OpenCode's local MCP shape: `type: "local"`, `command` as an array, optional `environment`, optional `timeout`, and optional `enabled`. Raven also supports `cwd` and `description`. `enabled` defaults to `true`; set it to `false` to keep a server in config without loading it.
+
 `description` is user-authored and never overwritten. Raven fills missing generated metadata after startup or when you run `/raven mcp refresh [server]`, storing tool summaries, MCP health, and avoided schema-load estimates separately in `~/.config/opencode/opencode-raven/autogenerated-on-demand-mcp-metadata.json`.
 
 Raven also writes generated main-model guidance to `~/.config/opencode/opencode-raven/autogenerated-on-demand-guidance.md` and injects that file into OpenCode instructions at startup.
@@ -157,16 +168,19 @@ Edit config manually or use `/raven` commands:
   "onDemandMcpDescriptionDetail": "full",
   "onDemandMcpServers": {
     "context7": {
+      "enabled": true,
       "type": "remote",
       "url": "https://mcp.context7.com/mcp",
       "description": "Library/framework documentation lookup."
     },
     "exa": {
+      "enabled": true,
       "type": "remote",
       "url": "https://mcp.exa.ai/mcp",
       "description": "Live web search and webpage fetching."
     },
     "grep_app": {
+      "enabled": true,
       "type": "remote",
       "url": "https://mcp.grep.app",
       "description": "Public GitHub code search and real-world examples."
@@ -187,7 +201,7 @@ Edit config manually or use `/raven` commands:
 | `routeTools` | built-in search/fetch tools plus `bash` | Exact tool names hard-routed through Raven. `bash` routes only search-like bash commands, not every bash call. |
 | `routeToolKeywords` | `[]` | Case-insensitive substrings hard-routed through Raven for globally registered tools with non-standard names. Catches suffix-style names like `web_search_exa`. |
 | `onDemandMcpDescriptionDetail` | `"full"` | On-demand MCP guidance detail. `full` includes tool names/descriptions; `minimized` uses compact capability summaries. |
-| `onDemandMcpServers` | Context7, Exa, Grep.app | MCPs Raven connects to internally on demand, without registering full schemas in OpenCode global MCP config. Supports `remote` and `stdio`. |
+| `onDemandMcpServers` | Context7, Exa, Grep.app | MCPs Raven connects to internally on demand, without registering full schemas in OpenCode global MCP config. Supports OpenCode-style `remote` and `local` entries. Each server supports `enabled`, defaulting to `true`. |
 | `excludeAgents` | `[]` | Agents that bypass Raven routing, case-insensitive. |
 | `excludeTools` | `[]` | Exact tools that never get blocked, even if matched by auto-routed global MCP prefixes. |
 | `timeout` | `180` | Max seconds for a `raven_seek` call. On timeout the session is kept for inspection. |
@@ -285,7 +299,7 @@ Raven itself has access to these tools, blocked for other agents when configured
 | `read`, `glob`, `grep`, `list` | Local codebase inspection |
 | `bash` | Full local shell access, including `rg`, `grep`, `dir`, `ls`, `Get-ChildItem`, and `find` |
 | `external_directory` | Allowed, with no permission prompts when accessing paths outside the workspace |
-| `raven_mcp` | Raven-only bridge to on-demand remote/stdio MCP servers |
+| `raven_mcp` | Raven-only bridge to on-demand remote/local MCP servers |
 | Context7 | On-demand library/framework/SDK/API docs |
 | Exa AI | On-demand web search, news, pages, products |
 | Grep.app | On-demand public GitHub examples |

package/index.ts

@@ -31,16 +31,19 @@ const DEFAULT_ROUTE_TOOL_KEYWORDS: string[] = []
 
 const DEFAULT_ON_DEMAND_MCP_SERVERS: Record<string, OnDemandMcpServer> = {
   context7: {
+    enabled: true,
     type: "remote",
     url: "https://mcp.context7.com/mcp",
     description: "Library/framework documentation lookup.",
   },
   exa: {
+    enabled: true,
     type: "remote",
     url: "https://mcp.exa.ai/mcp",
     description: "Live web search and webpage fetching.",
   },
   grep_app: {
+    enabled: true,
     type: "remote",
     url: "https://mcp.grep.app",
     description: "Public GitHub code search and real-world examples.",
@@ -138,6 +141,8 @@ interface OnDemandMcpToolInfo {
 }
 
 interface BaseOnDemandMcpServer {
+  enabled?: boolean
+  timeout?: number
   description?: string
 }
 
@@ -154,17 +159,17 @@ interface RemoteOnDemandMcpServer extends BaseOnDemandMcpServer {
   type: "remote"
   url: string
   headers?: Record<string, string>
+  oauth?: Record<string, unknown> | false
 }
 
-interface StdioOnDemandMcpServer extends BaseOnDemandMcpServer {
-  type: "stdio"
-  command: string
-  args?: string[]
-  env?: Record<string, string>
+interface LocalOnDemandMcpServer extends BaseOnDemandMcpServer {
+  type: "local"
+  command: string[]
+  environment?: Record<string, string>
   cwd?: string
 }
 
-type OnDemandMcpServer = RemoteOnDemandMcpServer | StdioOnDemandMcpServer
+type OnDemandMcpServer = RemoteOnDemandMcpServer | LocalOnDemandMcpServer
 type OnDemandMcpDescriptionDetail = "full" | "minimized"
 type RavenMcpOperation = "list_tools" | "call_tool" | "list_resources" | "read_resource" | "list_prompts" | "get_prompt"
 
@@ -303,32 +308,45 @@ function normalizeToolInfo(value: unknown): OnDemandMcpToolInfo[] | undefined {
   return tools.length ? tools : undefined
 }
 
+function normalizeStringRecord(value: unknown): Record<string, string> | undefined {
+  if (!value || typeof value !== "object") return undefined
+  const entries = Object.entries(value).filter((entry): entry is [string, string] => typeof entry[1] === "string")
+  return entries.length ? Object.fromEntries(entries) : undefined
+}
+
 function normalizeOnDemandMcpServer(value: unknown): OnDemandMcpServer | undefined {
   if (!value || typeof value !== "object") return undefined
   const source = value as Record<string, any>
   const base = {
+    enabled: source.enabled !== false,
+    ...(typeof source.timeout === "number" && source.timeout > 0 ? { timeout: Math.floor(source.timeout) } : {}),
     ...(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
+  if (source.type === "local") {
+    const commandParts = Array.isArray(source.command)
+      ? source.command.filter((arg: unknown): arg is string => typeof arg === "string" && arg.trim())
+      : []
+    if (!commandParts.length) return undefined
+    const environment = normalizeStringRecord(source.environment)
     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")) } : {}),
+      type: "local",
+      command: commandParts,
+      ...(environment ? { environment } : {}),
       ...(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
+    const headers = normalizeStringRecord(source.headers)
     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")) } : {}),
+      ...(headers ? { headers } : {}),
+      ...(source.oauth === false ? { oauth: false } : source.oauth && typeof source.oauth === "object" ? { oauth: source.oauth } : {}),
     }
   }
 
@@ -491,7 +509,7 @@ export default ((input: PluginInput) => {
 
   function resetOnDemandMcpRuntimeStatuses() {
     let changed = false
-    for (const name of Object.keys(config.onDemandMcpServers ?? {})) {
+    for (const [name] of activeOnDemandMcpEntries()) {
       const metadata = mcpMetadata[name] ?? {}
       if (metadata.status !== "pending" || metadata.lastError || metadata.lastCheckedAt) {
         mcpMetadata[name] = { ...metadata, status: "pending" }
@@ -591,8 +609,11 @@ export default ((input: PluginInput) => {
 
   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 activeEntries = activeOnDemandMcpEntries()
+    const entries = activeEntries.filter(([name]) => onDemandMcpRuntimeStatus(name) === "ready")
+    if (!Object.keys(servers).length) return "No on-demand MCPs are configured."
+    if (!activeEntries.length) return "No enabled on-demand MCPs are configured."
+    if (!entries.length) return "No loaded on-demand MCPs are available."
 
     const detail = config.onDemandMcpDescriptionDetail ?? "full"
     const lines = entries.map(([name, server]) => {
@@ -693,22 +714,29 @@ export default ((input: PluginInput) => {
   }
 
   function getOnDemandMcpServer(serverName: string): [string, OnDemandMcpServer] | undefined {
-    const entries = Object.entries(config.onDemandMcpServers ?? {})
+    const entries = activeOnDemandMcpEntries()
     return entries.find(([name]) => name.toLowerCase() === serverName.toLowerCase())
   }
 
+  function activeOnDemandMcpEntries(): [string, OnDemandMcpServer][] {
+    return Object.entries(config.onDemandMcpServers ?? {}).filter(([, server]) => server.enabled !== false)
+  }
+
   async function connectOnDemandMcp(serverName: string, server: OnDemandMcpServer): Promise<McpConnection> {
-    const timeout = (config.timeout ?? 180) * 1000
+    const timeout = server.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) }
+    if (server.type === "local") {
+      const env = { ...cleanProcessEnv(), ...resolveStringRecord(server.environment) }
       const transport = new StdioClientTransport({
-        command: resolveEnvPlaceholders(server.command),
-        args: server.args?.map((arg) => resolveEnvPlaceholders(arg)),
+        command: resolveEnvPlaceholders(server.command[0]),
+        args: server.command.slice(1).map((arg) => resolveEnvPlaceholders(arg)),
         env,
+        stderr: "pipe",
         cwd: server.cwd ? resolveEnvPlaceholders(server.cwd) : undefined,
       })
+      transport.stderr?.on("data", () => {})
+      transport.stderr?.on("error", () => {})
       await withTimeout(client.connect(transport), timeout, `Connecting to ${serverName}`)
       return { client, transport, serverName, lastUsed: Date.now() }
     }
@@ -799,7 +827,7 @@ export default ((input: PluginInput) => {
   }
 
   async function refreshOnDemandMcpDescriptions(force = false, serverName?: string): Promise<{ refreshed: string[]; failed: string[] }> {
-    const entries = Object.entries(config.onDemandMcpServers ?? {})
+    const entries = activeOnDemandMcpEntries()
       .filter(([name]) => !serverName || name.toLowerCase() === serverName.toLowerCase())
       .filter(([name]) => {
         const metadata = mcpMetadata[name]
@@ -869,7 +897,7 @@ export default ((input: PluginInput) => {
 
   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 ?? {})) {
+    for (const [name] of activeOnDemandMcpEntries()) {
       const status = onDemandMcpRuntimeStatus(name)
       if (status === "ready") buckets.loaded.push(name)
       else if (status === "failed") buckets.failed.push(name)
@@ -879,7 +907,7 @@ export default ((input: PluginInput) => {
   }
 
   function failedOnDemandMcpNames(names?: string[]): string[] {
-    const configured = Object.keys(config.onDemandMcpServers ?? {})
+    const configured = activeOnDemandMcpEntries().map(([name]) => name)
     const wanted = names?.length ? names : configured
     return wanted.filter((name) => configured.includes(name) && onDemandMcpRuntimeStatus(name) === "failed")
   }
@@ -897,12 +925,14 @@ export default ((input: PluginInput) => {
     else delete next.lastError
     mcpMetadata[name] = next
     saveMcpMetadata(mcpMetadata)
+    saveDynamicGuidance()
     return name
   }
 
   function onDemandMcpStatus(): string {
-    const entries = Object.entries(config.onDemandMcpServers ?? {})
-    if (!entries.length) return "Raven on-demand MCPs: none configured."
+    const entries = activeOnDemandMcpEntries()
+    if (!Object.keys(config.onDemandMcpServers ?? {}).length) return "Raven on-demand MCPs: none configured."
+    if (!entries.length) return "Raven on-demand MCPs: none enabled."
     const buckets = onDemandMcpStatusBuckets()
     const lines = entries.map(([name, server]) => {
       const metadata = mcpMetadata[name]
@@ -918,7 +948,7 @@ export default ((input: PluginInput) => {
   }
 
   function avoidedMcpSchemaBytes(): number {
-    return Object.keys(config.onDemandMcpServers ?? {}).reduce((sum, name) => {
+    return activeOnDemandMcpEntries().reduce((sum, [name]) => {
       const metadata = mcpMetadata[name]
       if (onDemandMcpRuntimeStatus(name) !== "ready") return sum
       return sum + Math.max(0, metadata?.avoidedSchemaBytes ?? 0)
@@ -994,7 +1024,9 @@ export default ((input: PluginInput) => {
 
   function formatTokens(bytes: number): string {
     const tokens = Math.round(bytes / 4)
-    return tokens >= 1000 ? `${(tokens / 1000).toFixed(1)}K` : `${tokens}`
+    return tokens >= 1_000_000 ? `${(tokens / 1_000_000).toFixed(1)}M`
+      : tokens >= 1000 ? `${(tokens / 1000).toFixed(1)}K`
+      : `${tokens}`
   }
 
   function compareVersions(a: string, b: string): number {
@@ -1153,11 +1185,11 @@ export default ((input: PluginInput) => {
       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()))
+      const onDemandNames = new Set(activeOnDemandMcpEntries().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()
+      // Inject MCP guidance as a startup instruction file (absolute path for npm compat).
+      // The file is regenerated after MCP health checks, not during the startup pending reset.
       cleanupOldRootFiles()
       configInput.instructions = configInput.instructions || []
       if (!configInput.instructions.includes(MCP_GUIDANCE_MD)) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opencode-raven",
-  "version": "2.1.0",
-  "description": "Raven is a context firewall for OpenCode. It routes noisy search, docs, web, GitHub, and MCP calls through a free focused agent before they hit your main model, saving cost and context!",
+  "version": "2.1.2",
+  "description": "Ready-to-use search tools and optional on-demand MCPs for OpenCode, routed through Raven to save your main model's context and cost.",
   "main": "./index.ts",
   "exports": {
     ".": "./index.ts"