@swarmclawai/swarmclaw 1.5.63 → 1.5.64

package/src/lib/server/mcp-gateway-runtime.ts

@@ -0,0 +1,138 @@
+import type { McpServerConfig } from '@/types'
+import { hmrSingleton } from '@/lib/shared-utils'
+
+/**
+ * Gateway-style runtime for SwarmClaw's MCP integration. Mirrors the behavior
+ * of `@swarmclawai/mcp-gateway`'s router (alwaysExpose filter + mcp_tool_search
+ * meta-tool) but stays inside SwarmClaw — no external dep on mcp-core (yet).
+ *
+ * Once `@swarmclawai/mcp-core` is published to npm, the plan is:
+ *   1. Add `@swarmclawai/mcp-core` to SwarmClaw's dependencies.
+ *   2. Replace `SessionToolPromoter`, `searchDiscoveredTools`, and
+ *      `shouldExposeMcpTool` with imports from mcp-core. The field names on
+ *      `DownstreamTool` differ from `DiscoveredTool` (`prefixedName` vs
+ *      `langChainName`) — add a thin adapter during migration.
+ *   3. Keep the hmrSingleton `state` here; mcp-core provides primitives, but
+ *      SwarmClaw still owns process-wide session-scoped storage.
+ *
+ * Contains two pieces of shared state, both HMR-safe:
+ *   - `SessionToolPromoter` instances keyed by sessionId. The agent calls
+ *     `mcp_tool_search` to promote a lazy tool by name; the next turn's tool
+ *     bind picks up the promoted name via `isPromoted`.
+ *   - A discovery cache keyed by MCP server id, so even lazy servers have
+ *     their tool schemas known in-process for `mcp_tool_search` to match
+ *     against without a cold connect.
+ */
+
+export interface DiscoveredTool {
+  name: string // bare tool name as the downstream reported it
+  langChainName: string // the `mcp_<server>_<tool>` name SwarmClaw binds it under
+  description?: string
+  inputSchema?: unknown
+  serverId: string
+  serverName: string
+}
+
+export class SessionToolPromoter {
+  private readonly exposed = new Set<string>()
+  allow(langChainName: string): boolean { return this.exposed.has(langChainName) }
+  promote(langChainName: string): void { this.exposed.add(langChainName) }
+  promoteMany(names: readonly string[]): void { for (const n of names) this.exposed.add(n) }
+  promoted(): string[] { return Array.from(this.exposed) }
+  clear(): void { this.exposed.clear() }
+}
+
+interface RuntimeState {
+  promoters: Map<string, SessionToolPromoter>
+  // serverId -> discovered tools (updated opportunistically when we connect)
+  discovered: Map<string, DiscoveredTool[]>
+}
+
+const state = hmrSingleton<RuntimeState>('mcpGatewayRuntime', () => ({
+  promoters: new Map<string, SessionToolPromoter>(),
+  discovered: new Map<string, DiscoveredTool[]>(),
+}))
+
+export function getPromoter(sessionId: string): SessionToolPromoter {
+  let p = state.promoters.get(sessionId)
+  if (!p) {
+    p = new SessionToolPromoter()
+    state.promoters.set(sessionId, p)
+  }
+  return p
+}
+
+export function clearPromoter(sessionId: string): void {
+  state.promoters.delete(sessionId)
+}
+
+export function recordDiscoveredTools(serverId: string, tools: DiscoveredTool[]): void {
+  state.discovered.set(serverId, tools)
+}
+
+export function allDiscoveredTools(): DiscoveredTool[] {
+  const out: DiscoveredTool[] = []
+  for (const arr of state.discovered.values()) {
+    for (const t of arr) out.push(t)
+  }
+  return out
+}
+
+/**
+ * Decide whether a given tool, from a given server, should be bound on this
+ * turn. Order of precedence:
+ *   1. Per-agent eager allowlist (`mcpEagerTools`) — agent-scoped override
+ *   2. Server-level `alwaysExpose`
+ *      - true (default)  → bind
+ *      - false           → skip unless promoted
+ *      - string[]        → bind only if tool name is on the list
+ *   3. Session promoter — if the agent has called `mcp_tool_search` this
+ *      session and promoted this tool, bind it regardless of (2).
+ */
+export function shouldExposeMcpTool(opts: {
+  server: McpServerConfig
+  toolName: string
+  langChainName: string
+  agentEagerTools?: readonly string[] | null
+  promoter?: SessionToolPromoter | null
+}): boolean {
+  const { server, toolName, langChainName, agentEagerTools, promoter } = opts
+  if (agentEagerTools && agentEagerTools.includes(toolName)) return true
+  if (agentEagerTools && agentEagerTools.includes(langChainName)) return true
+  if (promoter?.allow(langChainName)) return true
+  const mode = server.alwaysExpose
+  if (mode === undefined || mode === true) return true
+  if (mode === false) return false
+  if (Array.isArray(mode)) return mode.includes(toolName)
+  return true
+}
+
+export interface ToolSearchMatch {
+  name: string // langChainName
+  server: string
+  description?: string
+  score: number
+}
+
+export function searchDiscoveredTools(query: string, limit = 8): ToolSearchMatch[] {
+  const q = query.trim().toLowerCase()
+  if (!q) return []
+  const terms = q.split(/\s+/).filter((t) => t.length >= 2)
+  const clamped = Math.max(1, Math.min(limit, 50))
+  const scored = allDiscoveredTools().map((t): ToolSearchMatch => {
+    const haystack = `${t.langChainName} ${t.description ?? ''}`.toLowerCase()
+    let score = 0
+    if (haystack.includes(q)) score += 0.6
+    let termHits = 0
+    for (const term of terms) if (haystack.includes(term)) termHits += 1
+    if (terms.length) score += 0.4 * (termHits / terms.length)
+    return {
+      name: t.langChainName,
+      server: t.serverName,
+      description: t.description,
+      score: Math.min(1, score),
+    }
+  })
+  scored.sort((a, b) => b.score - a.score)
+  return scored.filter((m) => m.score > 0).slice(0, clamped)
+}

package/src/lib/server/session-tools/index.ts

@@ -54,7 +54,15 @@ import { enforceFileAccessPolicy } from './file-access-policy'
 
 import { getExtensionManager } from '../extensions'
 import { runCapabilityBeforeToolCall, runCapabilityHook } from '../native-capabilities'
-import { jsonSchemaToZod } from '../mcp-client'
+import { jsonSchemaToZod, sanitizeName } from '../mcp-client'
+import {
+  getPromoter,
+  recordDiscoveredTools,
+  searchDiscoveredTools,
+  shouldExposeMcpTool,
+  type DiscoveredTool,
+} from '../mcp-gateway-runtime'
+import { getOrConnectMcpClient } from '../mcp-connection-pool'
 import {
   getEnabledCapabilitySelection,
   isExternalExtensionId,
@@ -81,6 +89,11 @@ const DELEGATION_TOOL_NAMES = new Set([
   'delegate_to_qwen_code_cli',
 ])
 
+function inferBareName(langChainName: string, serverName: string): string {
+  const prefix = `mcp_${sanitizeName(serverName)}_`
+  return langChainName.startsWith(prefix) ? langChainName.slice(prefix.length) : langChainName
+}
+
 export async function buildSessionTools(cwd: string, enabledExtensions: string[], ctx?: ToolContext): Promise<SessionToolsResult> {
   const tools: StructuredToolInterface[] = []
   const cleanupFns: (() => Promise<void>)[] = []
@@ -305,33 +318,88 @@ export async function buildSessionTools(cwd: string, enabledExtensions: string[]
 
     // 3. MCP server tools
     const disabledMcpToolNames = new Set<string>(ctx?.mcpDisabledTools ?? [])
+    const agentEagerTools = Array.isArray(agentRecord?.mcpEagerTools) ? agentRecord.mcpEagerTools : null
+    const sessionPromoter = ctx?.sessionId ? getPromoter(ctx.sessionId) : null
+    let exposedAnyLazyCandidate = false
     if (ctx?.mcpServerIds?.length) {
-      const mcpConnections: Array<{ client: any; transport: any }> = []
       const allMcpServers = loadMcpServers()
       for (const serverId of ctx.mcpServerIds) {
         const config = allMcpServers[serverId]
         if (!config) continue
         try {
-          const { connectMcpServer, mcpToolsToLangChain } = await import('../mcp-client')
-          const conn = await connectMcpServer(config)
-          mcpConnections.push(conn)
+          const { mcpToolsToLangChain } = await import('../mcp-client')
+          const conn = await getOrConnectMcpClient(config)
           const mcpLcTools = await mcpToolsToLangChain(conn.client, config.name)
+          // Discovery cache — so mcp_tool_search can match even on lazy servers
+          // whose tools we don't bind. Populated each turn we connect.
+          const discovered: DiscoveredTool[] = mcpLcTools.map((t) => ({
+            name: inferBareName(t.name, config.name),
+            langChainName: t.name,
+            description: typeof t.description === 'string' ? t.description : undefined,
+            serverId,
+            serverName: config.name,
+          }))
+          recordDiscoveredTools(serverId, discovered)
           for (const t of mcpLcTools) {
-            if (!disabledMcpToolNames.has(t.name)) {
-              toolToExtensionMap[t.name] = `mcp:${serverId}`
-              tools.push(t)
-            }
+            if (disabledMcpToolNames.has(t.name)) continue
+            const bareName = inferBareName(t.name, config.name)
+            const effectiveMode = config.alwaysExpose === undefined ? true : config.alwaysExpose
+            if (effectiveMode !== true) exposedAnyLazyCandidate = true
+            const shouldBind = shouldExposeMcpTool({
+              server: config,
+              toolName: bareName,
+              langChainName: t.name,
+              agentEagerTools,
+              promoter: sessionPromoter,
+            })
+            if (!shouldBind) continue
+            toolToExtensionMap[t.name] = `mcp:${serverId}`
+            tools.push(t)
           }
         } catch (err: unknown) {
           log.warn('session-tools', `Failed to connect MCP server "${config.name}"`, { serverId, error: errorMessage(err) })
         }
       }
-      cleanupFns.push(async () => {
-        const { disconnectMcpServer } = await import('../mcp-client')
-        for (const conn of mcpConnections) {
-          await disconnectMcpServer(conn.client, conn.transport)
-        }
-      })
+      // Connection lifetimes are owned by the pool (hmrSingleton) — no per-turn
+      // cleanup here. Evictions happen on server edit/delete via the mcp-servers
+      // API routes or via the /test endpoint.
+    }
+
+    // 3a. mcp_tool_search meta-tool — bound when any configured MCP server has
+    // a non-eager exposure mode so the agent has a path to discover lazy tools.
+    if (exposedAnyLazyCandidate && sessionPromoter) {
+      const promoter = sessionPromoter
+      toolToExtensionMap['mcp_tool_search'] = '_mcp_gateway'
+      tools.push(
+        tool(
+          async (args) => {
+            const normalized = normalizeToolInputArgs((args ?? {}) as Record<string, unknown>)
+            const query = typeof normalized.query === 'string' ? normalized.query : ''
+            const limit = typeof normalized.limit === 'number' ? normalized.limit : undefined
+            const matches = searchDiscoveredTools(query, limit)
+            for (const m of matches) promoter.promote(m.name)
+            return JSON.stringify({
+              query,
+              matches,
+              note: matches.length
+                ? 'Promoted tools will appear in the tool list on subsequent turns; call them by the listed name.'
+                : 'No matches — tighten your query or check enabled MCP servers.',
+            })
+          },
+          {
+            name: 'mcp_tool_search',
+            description: [
+              'Search for tools provided by configured MCP servers that are not currently bound.',
+              'Use this when you suspect a tool exists but do not see it in your available tools.',
+              'Returns matching tool names and descriptions, and promotes the matches so they show up in subsequent turns.',
+            ].join(' '),
+            schema: z.object({
+              query: z.string().min(1).describe('Keywords to search tool names and descriptions'),
+              limit: z.number().int().min(1).max(50).optional().describe('Max results (default 8)'),
+            }),
+          },
+        ),
+      )
     }
 
     // 4. Always available: request_tool_access

package/src/lib/server/storage-normalization.ts

@@ -700,6 +700,16 @@ function normalizeStoredRecordInner(
     return task
   }
 
+  if (table === 'mcp_servers') {
+    const server = value as StoredObject
+    // Back-compat: existing servers had no alwaysExpose; match historical behavior
+    // where every tool was eagerly bound on every turn.
+    if (server.alwaysExpose === undefined) {
+      server.alwaysExpose = true
+    }
+    return server
+  }
+
   if (table === 'provider_configs') {
     const provider = value as StoredObject
     provider.type = provider.type === 'builtin' ? 'builtin' : 'custom'
@@ -801,6 +811,7 @@ function normalizeStoredRecordInner(
   if (session.geminiSessionId === undefined) session.geminiSessionId = null
   // Default copilotSessionId for new field
   if (session.copilotSessionId === undefined) session.copilotSessionId = null
+  if (session.opencodeWebSessionId === undefined) session.opencodeWebSessionId = null
   if (session.droidSessionId === undefined) session.droidSessionId = null
   if (session.cursorSessionId === undefined) session.cursorSessionId = null
   if (session.qwenSessionId === undefined) session.qwenSessionId = null

package/src/types/agent.ts

@@ -86,6 +86,7 @@ export interface Agent {
   skillIds?: string[]           // IDs of pinned managed skills to keep always-on for this agent
   mcpServerIds?: string[]       // IDs of configured MCP servers to inject tools from
   mcpDisabledTools?: string[]   // MCP tool names disabled for this agent (denylist)
+  mcpEagerTools?: string[]      // Per-agent allowlist of MCP tool names to bind eagerly even when the server's alwaysExpose is false
   orgChart?: AgentOrgChart | null
   capabilities?: string[]       // e.g. ['frontend', 'screenshots', 'research', 'devops']
   threadSessionId?: string | null  // persistent shortcut chat session for agent-centric UI

package/src/types/misc.ts

@@ -629,6 +629,13 @@ export interface McpServerConfig {
   url?: string                 // for sse/streamable-http transport
   env?: Record<string, string> // environment variables
   headers?: Record<string, string> // HTTP headers for sse/streamable-http
+  // Tool-exposure policy — lets users cut token spend from chatty MCP servers.
+  // - true (default, back-compat)   → every tool is bound on every turn
+  // - false                         → no tools bound; agent uses mcp_tool_search to promote them
+  // - string[] (allow-list)         → only tools whose names appear here are bound eagerly
+  // Regardless of this setting, tools the agent has promoted via mcp_tool_search in the
+  // current session are bound too. And per-agent mcpEagerTools provide an explicit override.
+  alwaysExpose?: boolean | string[]
   createdAt: number
   updatedAt: number
 }