opencode-mcp-triage 0.7.0

package/src/index.ts

@@ -0,0 +1,425 @@
+/*
+ * opencode-mcp-triage — Subagent Router Plugin
+ * ==============================================
+ * Version: 0.6.1
+ * License: MIT
+ *
+ * Routes MCP work to scoped subagents. On first run, automatically
+ * disables all MCP tools globally in opencode.jsonc so they don't
+ * consume tokens in the main agent. Subagents re-enable specific
+ * servers via tool scoping.
+ *
+ * How it works:
+ * 1. Plugin init: reads MCP servers + subagents from config
+ * 2. Writes "servername_*": false to project config (disables MCP tools in main session)
+ * 3. Exposes triage_mcp tool: scores user query against subagent names/descriptions/MCP names
+ * 4. Returns best-matching subagent — user invokes it via @name or Task tool
+ *
+ * Token savings: MCP tools have large descriptions. Disabling them in the
+ * main session saves ~80% of MCP-related tokens. Subagents only carry
+ * their scoped servers' tools.
+ *
+ * Install:  { "plugin": ["opencode-mcp-triage"] }  in opencode.jsonc
+ * Docs:     https://github.com/cascharly/opencode-mcp-triage
+ */
+
+import type { Plugin } from "@opencode-ai/plugin"
+import { tool } from "@opencode-ai/plugin"
+import type { McpServer, Subagent } from "./types.js"
+import { readMcpConfig, readSubagentConfig } from "./config.js"
+import { scoreSubagents, THRESHOLD } from "./triage.js"
+import { ensureToolsDisabled, ensureSubagentsCreated } from "./writer.js"
+
+/** Cache TTL: 5 seconds — balances freshness with performance */
+const CACHE_TTL_MS = 5000
+
+/** Reload debounce: 1 second cooldown to prevent spam */
+const RELOAD_COOLDOWN_MS = 1000
+
+/**
+ * Mutable plugin state — updated on init and reload.
+ *
+ * mcpServers: all MCP servers from config (name + description)
+ * subagents: agents with MCP tool scoping
+ * mcpNames: flat list of MCP server names (for display)
+ * assignedMcps: set of MCP names that have at least one subagent
+ */
+interface State {
+  mcpServers: McpServer[]
+  subagents: Subagent[]
+  mcpNames: string[]
+  assignedMcps: Set<string>
+}
+
+/**
+ * Generic cache with TTL.
+ * Stores a value with an expiry timestamp. Returns null if expired.
+ */
+interface CacheEntry<T> {
+  value: T
+  expiresAt: number
+}
+
+interface Cache<T> {
+  get(): T | null
+  set(value: T): void
+  invalidate(): void
+}
+
+function createCache<T>(ttlMs: number): Cache<T> {
+  let entry: CacheEntry<T> | null = null
+
+  return {
+    get(): T | null {
+      if (entry && Date.now() < entry.expiresAt) {
+        return entry.value
+      }
+      return null
+    },
+    set(value: T) {
+      entry = { value, expiresAt: Date.now() + ttlMs }
+    },
+    invalidate() {
+      entry = null
+    },
+  }
+}
+
+/**
+ * Builds state from raw config data.
+ *
+ * assignedMcps tracks which MCP servers are covered by subagents.
+ * Used to report unassigned servers (no subagent handles them).
+ */
+function buildState(mcpServers: McpServer[], subagents: Subagent[]): State {
+  const assignedMcps = new Set<string>()
+  for (const sa of subagents) {
+    for (const m of sa.mcpServers) {
+      assignedMcps.add(m)
+    }
+  }
+  return {
+    mcpServers,
+    subagents,
+    mcpNames: mcpServers.map((s) => s.name),
+    assignedMcps,
+  }
+}
+
+/**
+ * Sends a TUI toast notification via OpenCode client.
+ * Gracefully handles missing client.tui (older OpenCode versions).
+ */
+function showToast(
+  client: unknown,
+  message: string,
+  variant: "success" | "info" | "error" = "info"
+) {
+  try {
+    const c = client as { tui?: { showToast?: (...args: unknown[]) => unknown } }
+    c.tui?.showToast?.({ message, variant })
+  } catch {
+    // TUI not available — silently skip
+  }
+}
+
+/**
+ * OpenCode plugin entry point.
+ *
+ * Runs once when OpenCode starts. Must complete before returning —
+ * ensureToolsDisabled writes to config file and must finish before
+ * the main agent starts using tools.
+ *
+ * Returns two tools:
+ * - triage_mcp: routes queries to the best subagent
+ * - mcp_stats: shows routing status and token savings
+ */
+export const server: Plugin = async ({ directory, client }) => {
+  // Config caches with 5s TTL — picks up CLI toggles without restart
+  const mcpCache = createCache<McpServer[]>(CACHE_TTL_MS)
+  const subagentCache = createCache<Subagent[]>(CACHE_TTL_MS)
+
+  // Reload debounce: track last reload time to prevent spam
+  let lastReloadAt = 0
+
+  async function getCachedMcpServers(): Promise<McpServer[]> {
+    const cached = mcpCache.get()
+    if (cached) return cached
+    const result = await readMcpConfig(directory)
+    mcpCache.set(result)
+    return result
+  }
+
+  async function getCachedSubagents(): Promise<Subagent[]> {
+    const cached = subagentCache.get()
+    if (cached) return cached
+    const result = await readSubagentConfig(directory)
+    subagentCache.set(result)
+    return result
+  }
+
+  const mcpServers = await getCachedMcpServers()
+  const mcpNames = mcpServers.map((s) => s.name)
+
+  // Phase 1: disable all MCP tools in main agent
+  // This MUST complete before returning — otherwise main session
+  // could use MCP tools before they're disabled
+  await ensureToolsDisabled(directory, mcpNames)
+
+  // Phase 2: read current subagents, then auto-create for unassigned MCPs
+  let subagents = await getCachedSubagents()
+  const created = await ensureSubagentsCreated(directory, mcpServers, subagents)
+  if (created > 0) {
+    // Re-read after auto-create so state is accurate
+    subagentCache.invalidate()
+    subagents = await getCachedSubagents()
+  }
+
+  const state = buildState(mcpServers, subagents)
+
+  return {
+    tool: {
+      /**
+       * Triage Tool: matches a user query to the best subagent.
+       *
+       * Scoring uses keyword matching against subagent name, description,
+       * and assigned MCP server names. Returns the top match if the score
+       * gap exceeds THRESHOLD, otherwise shows multiple options.
+       *
+       * Special queries:
+       * - "reload": re-reads config without restarting OpenCode
+       * - "": lists all available subagents
+       */
+      triage_mcp: tool({
+        description:
+          "Discover and route to the right MCP subagent. " +
+          "Call this before any non-trivial MCP task. " +
+          "Pass a short description of what you need. " +
+          "Returns the best matching subagent and its available MCP tools. " +
+          "Use query 'reload' to re-read MCP config without restarting.",
+        args: {
+          query: tool.schema
+            .string()
+            .describe(
+              "What you want to do — e.g. 'search library docs', " +
+                "'manage GitHub issues', 'database operations', " +
+                "or 'reload' to refresh MCP config"
+            ),
+        },
+        async execute(args, context) {
+          // Abort signal handling — check if request was cancelled
+          if (context?.abort?.aborted) {
+            return "Triage cancelled."
+          }
+
+          const query = args.query.trim()
+
+          // "reload" — re-read config files without restarting
+          if (query.toLowerCase() === "reload") {
+            // Debounce: prevent spam reloads
+            const now = Date.now()
+            if (now - lastReloadAt < RELOAD_COOLDOWN_MS) {
+              return "Reload cooldown active. Try again in a moment."
+            }
+            lastReloadAt = now
+
+            mcpCache.invalidate()
+            subagentCache.invalidate()
+            state.mcpServers = await getCachedMcpServers()
+            let sa = await getCachedSubagents()
+            const created = await ensureSubagentsCreated(
+              directory,
+              state.mcpServers,
+              sa
+            )
+            if (created > 0) {
+              subagentCache.invalidate()
+              sa = await getCachedSubagents()
+            }
+            state.subagents = sa
+            const fresh = buildState(state.mcpServers, state.subagents)
+            Object.assign(state, fresh)
+            const lines = ["MCP config reloaded."]
+            if (created > 0) {
+              lines.push(`Auto-created ${created} subagent(s) for new MCP(s).`)
+            }
+            lines.push(
+              `Subagents: ${state.subagents.map((s) => s.name).join(", ") || "none"}`
+            )
+            lines.push(
+              `MCP servers: ${state.mcpServers.map((s) => s.name).join(", ") || "none"}`
+            )
+            showToast(client, "MCP config reloaded", "success")
+            return lines.join("\n")
+          }
+
+          // Empty query — list all subagents
+          if (!query) {
+            if (state.subagents.length === 0) {
+              return [
+                "No MCP subagents configured.",
+                "",
+                "Add subagents in opencode.jsonc under 'agent' section with tool scoping.",
+              ].join("\n")
+            }
+            const lines = ["Available subagents:"]
+            for (const sa of state.subagents) {
+              const mcps = sa.mcpServers.join(", ")
+              lines.push(
+                `  @${sa.name} — ${sa.description || "no description"}${mcps ? ` [${mcps}]` : ""}`
+              )
+            }
+            lines.push("")
+            lines.push("Use @agent-name in your message to invoke a subagent.")
+            return lines.join("\n")
+          }
+
+          // No subagents configured — show setup instructions
+          if (state.subagents.length === 0) {
+            return [
+              "No MCP subagents configured.",
+              "",
+              "Add subagents in opencode.jsonc:",
+              `  "agent": { "myserver": { "mode": "subagent", "description": "...", "tools": { "myserver_*": true } } }`,
+            ].join("\n")
+          }
+
+          // Score and rank subagents
+          const scored = scoreSubagents(query, state.subagents)
+            .filter((s) => s.score > 0)
+            .sort((a, b) => b.score - a.score)
+
+          // No matches — show available options
+          if (scored.length === 0) {
+            const names = state.subagents.map((s) => s.name).join(", ")
+            showToast(client, `No match for "${query}"`, "error")
+            return [
+              `No subagent matches "${query}".`,
+              `Available: ${names}`,
+              "",
+              "Try broader keywords or call triage_mcp with empty query to list all.",
+            ].join("\n")
+          }
+
+          // Check if top match is clearly better than runner-up
+          const gap = scored[0].score - (scored[1]?.score ?? 0)
+
+          if (gap >= THRESHOLD || scored.length === 1) {
+            // Clear winner — route to it
+            const match = scored[0]
+            const mcps = match.subagent.mcpServers.join(", ")
+            const lines = [
+              `ROUTED: @${match.subagent.name}`,
+              match.subagent.description
+                ? `  ${match.subagent.description}`
+                : "",
+              mcps ? `  MCP: ${mcps}` : "",
+              `  Matched by: ${match.matchedBy}`,
+              "",
+              `Invoke with @${match.subagent.name} in your message, or use the Task tool:`,
+              `  task({ subagent_type: "${match.subagent.name}", prompt: "..." })`,
+            ]
+            showToast(client, `Routed to @${match.subagent.name}`, "success")
+            return lines.join("\n")
+          }
+
+          // Too close to call — show top 5 options
+          const top = scored.slice(0, 5)
+          const lines = [`Multiple subagents match "${query}":`, ""]
+          top.forEach((s, i) => {
+            const mcps = s.subagent.mcpServers.join(", ")
+            lines.push(
+              `  ${i + 1}. @${s.subagent.name}${s.subagent.description ? ` — ${s.subagent.description}` : ""}${mcps ? ` [${mcps}]` : ""}`
+            )
+          })
+          lines.push("")
+          lines.push(
+            `Be more specific, or name the subagent directly: @${top[0].subagent.name}`
+          )
+          showToast(client, `${scored.length} subagents match`, "info")
+          return lines.join("\n")
+        },
+      }),
+
+      /**
+       * Stats tool: displays routing status and token savings.
+       *
+       * Shows:
+       * - Subagent routing map (which subagent handles which MCP servers)
+       * - Unassigned servers (no subagent covers them)
+       * - Token savings confirmation (0 MCP tokens in main session)
+       * - Coverage percentage
+       */
+      mcp_stats: tool({
+        description:
+          "Show MCP subagent routing status and token savings. " +
+          "Displays which MCP servers are routed to which subagents. " +
+          "MCP tools in main session are disabled — only subagents carry them.",
+        args: {},
+        async execute() {
+          const lines: string[] = []
+          const { subagents: sa, mcpNames, assignedMcps } = state
+
+          lines.push("MCP Subagent Routing Status")
+          lines.push("")
+
+          if (sa.length === 0) {
+            lines.push("  No subagents configured.")
+            lines.push("")
+            lines.push(
+              "  Configure subagents with MCP tool scoping for token savings."
+            )
+            return lines.join("\n")
+          }
+
+          lines.push(
+            `  Strategy: Global disable → Subagent enable via tool scoping`
+          )
+          lines.push(
+            `  Subagents: ${sa.length}  |  MCP servers: ${mcpNames.length}`
+          )
+          lines.push("")
+          lines.push("  Subagent routing map:")
+          lines.push("  ─".repeat(30))
+
+          for (const s of sa) {
+            const mcps = s.mcpServers.join(", ")
+            lines.push(
+              `  @${s.name.padEnd(18)} → ${mcps || "no MCP servers"}`
+            )
+            if (s.description) {
+              lines.push(`  ${" ".repeat(19)}${s.description}`)
+            }
+          }
+
+          // Find MCP servers not assigned to any subagent
+          const unassigned = mcpNames.filter(
+            (n) => !sa.some((s) => s.mcpServers.includes(n))
+          )
+          if (unassigned.length > 0) {
+            lines.push("")
+            lines.push(
+              `  Unassigned: ${unassigned.join(", ")} (no subagent)`
+            )
+          }
+
+          const assigned = assignedMcps.size
+          const pct = mcpNames.length > 0
+            ? Math.round((assigned / mcpNames.length) * 100)
+            : 0
+
+          lines.push("")
+          lines.push("  ─".repeat(30))
+          lines.push(
+            `  MCP tools in main session: 0 tokens (globally disabled)`
+          )
+          lines.push(
+            `  MCP coverage: ${assigned}/${mcpNames.length} servers routed (${pct}%)`
+          )
+
+          return lines.join("\n")
+        },
+      }),
+    },
+  }
+}

package/src/lock.ts

@@ -0,0 +1,42 @@
+import { readFile, writeFile, mkdir, stat, rename } from "node:fs/promises"
+import { join, dirname } from "node:path"
+
+const LOCK_FILENAME = "mcp-triage.json"
+
+/** Max lock file size: 64KB — prevents memory exhaustion */
+const MAX_LOCK_SIZE = 64 * 1024
+
+export interface LockFile {
+  version: 1
+  autoCreated: Record<string, string>
+}
+
+export async function readLock(directory: string): Promise<LockFile | null> {
+  const path = join(directory, ".opencode", LOCK_FILENAME)
+  try {
+    const stats = await stat(path)
+    if (stats.size > MAX_LOCK_SIZE) return null
+    const raw = await readFile(path, "utf-8")
+    return JSON.parse(raw) as LockFile
+  } catch {
+    return null
+  }
+}
+
+export async function writeLock(
+  directory: string,
+  lock: LockFile
+): Promise<void> {
+  const path = join(directory, ".opencode", LOCK_FILENAME)
+  await mkdir(dirname(path), { recursive: true })
+
+  // Atomic write: write to temp file then rename
+  const tmpPath = path + ".tmp"
+  await writeFile(tmpPath, JSON.stringify(lock, null, 2) + "\n", "utf-8")
+  try {
+    await rename(tmpPath, path)
+  } catch {
+    // Rename failed (cross-device) — fallback to direct write
+    await writeFile(path, JSON.stringify(lock, null, 2) + "\n", "utf-8")
+  }
+}

package/src/triage.ts

@@ -0,0 +1,121 @@
+/**
+ * Keyword-based subagent scoring engine.
+ *
+ * Scoring strategy (no LLM, pure text matching):
+ * 1. Split query into words (min 3 chars, strip punctuation)
+ * 2. For each subagent, score against name, description, and MCP server names
+ * 3. Word boundary match > substring match (15 vs 10 base points)
+ * 4. Name and MCP matches weighted 3x, description weighted 1x
+ *
+ * Threshold (30): minimum score gap between 1st and 2nd place for auto-routing.
+ * If gap < threshold, we show multiple options instead of picking one.
+ *
+ * Why these weights:
+ * - NAME_WEIGHT=3: subagent name is the strongest signal ("github" in query → github agent)
+ * - DESC_WEIGHT=1: description is broader, more false positives
+ * - MCP names use NAME_WEIGHT: server name matches are as strong as agent name matches
+ */
+
+import type { Subagent, ScoredSubagent } from "./types.js"
+
+/** Minimum score gap between top two candidates for confident routing */
+export const THRESHOLD = 30
+/** Words shorter than this are ignored (too generic) */
+const MIN_WORD_LENGTH = 3
+/** Multiplier for name and MCP server matches */
+const NAME_WEIGHT = 3
+/** Multiplier for description matches (lower — more noise) */
+const DESC_WEIGHT = 1
+
+/**
+ * Escapes regex special characters in a string.
+ * Used when building dynamic regex patterns from user input or config values.
+ */
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\-]/g, "\\$&")
+}
+
+/**
+ * Scores a single word against a target string.
+ *
+ * Returns:
+ * - 15 if word matches as a whole word (boundary match)
+ * - 10 if word is a substring of target
+ * - 0 if no match
+ *
+ * Case-insensitive. Boundary match uses \b word boundaries.
+ */
+function getWordBonus(word: string, target: string): number {
+  const re = new RegExp(`\\b${escapeRegex(word)}\\b`, "i")
+  if (re.test(target)) return 15
+  if (target.includes(word)) return 10
+  return 0
+}
+
+/**
+ * Scores all subagents against a triage query.
+ *
+ * Scoring happens in three passes:
+ * 1. Query words vs subagent name (highest weight)
+ * 2. Query words vs subagent description (lower weight)
+ * 3. Query words vs MCP server names assigned to the subagent (highest weight)
+ *
+ * Uses a Set for matchedBy to avoid duplicate entries when multiple
+ * query words match the same MCP server.
+ *
+ * Returns all subagents with their scores — caller filters by score > 0.
+ */
+export function scoreSubagents(
+  query: string,
+  subagents: Subagent[]
+): ScoredSubagent[] {
+  // Normalize query: lowercase, split on whitespace, strip punctuation, filter short words
+  const words = query
+    .toLowerCase()
+    .split(/\s+/)
+    .map((w) => w.replace(/[^\p{L}\p{N}]/gu, ""))
+    .filter((w) => w.length >= MIN_WORD_LENGTH)
+
+  if (words.length === 0) return []
+
+  return subagents.map((subagent) => {
+    const nameLower = subagent.name.toLowerCase()
+    const descLower = subagent.description.toLowerCase()
+    const mcpNames = subagent.mcpServers.map((s) => s.toLowerCase())
+    let score = 0
+    // Use Set to deduplicate — multiple query words can match the same MCP server
+    const matched = new Set<string>()
+
+    // Pass 1: score against subagent name (strongest signal)
+    for (const word of words) {
+      const bonus = getWordBonus(word, nameLower)
+      if (bonus > 0) {
+        score += NAME_WEIGHT * bonus
+        matched.add(`name:${word}`)
+      }
+    }
+
+    // Pass 2: score against description (broader, more noise)
+    for (const word of words) {
+      const bonus = getWordBonus(word, descLower)
+      if (bonus > 0) {
+        score += DESC_WEIGHT * bonus
+        matched.add(`desc:${word}`)
+      }
+    }
+
+    // Pass 3: score against MCP server names assigned to this subagent
+    // Treats MCP name matches as strong as name matches
+    for (const mcpName of mcpNames) {
+      for (const word of words) {
+        const bonus = getWordBonus(word, mcpName)
+        if (bonus > 0) {
+          score += NAME_WEIGHT * bonus
+          matched.add(`mcp:${mcpName}`)
+        }
+      }
+    }
+
+    return { subagent, score, matchedBy: Array.from(matched).join(", ") }
+  })
+}

package/src/types.ts

@@ -0,0 +1,63 @@
+/**
+ * Shared type definitions for opencode-mcp-triage.
+ *
+ * Key distinction:
+ * - McpConfigEntry: raw config from opencode.jsonc (has type, command, url, etc.)
+ * - McpServer: simplified name + description for display
+ * - Subagent: agent with MCP tool scoping, extracted from agent config
+ * - ScoredSubagent: subagent + relevance score from keyword matching
+ */
+
+/**
+ * MCP server config entry from opencode.jsonc.
+ *
+ * OpenCode supports both "env" and "environment" keys for env vars.
+ * "enabled" defaults to true when omitted — we only filter out explicit false.
+ */
+export interface McpConfigEntry {
+  type: "local" | "remote"
+  command?: string[]
+  args?: string[]
+  url?: string
+  env?: Record<string, string>
+  environment?: Record<string, string>
+  headers?: Record<string, string>
+  enabled?: boolean
+  description?: string
+}
+
+/**
+ * Simplified MCP server representation.
+ * Used for routing state and display — stripped of connection details.
+ */
+export interface McpServer {
+  name: string
+  description: string
+}
+
+/**
+ * Subagent extracted from opencode.jsonc agent config.
+ *
+ * A subagent is any agent entry with:
+ * - mode !== "primary"
+ * - tools object containing at least one "servername_*": true entry
+ *
+ * The mcpServers array holds the server name prefixes (without _* suffix).
+ */
+export interface Subagent {
+  name: string
+  description: string
+  mcpServers: string[]
+}
+
+/**
+ * Subagent enriched with a relevance score from triage matching.
+ *
+ * score: cumulative points from keyword matches across name, description, and MCP names
+ * matchedBy: human-readable explanation of which fields matched which keywords
+ */
+export interface ScoredSubagent {
+  subagent: Subagent
+  score: number
+  matchedBy: string
+}