From c811c0cb51246ea92bd74d44e60d6d0c25943542 Mon Sep 17 00:00:00 2001 From: Aiden Cline <63023139+rekram1-node@users.noreply.github.com> Date: Fri, 30 Oct 2026 22:50:33 -0500 Subject: [PATCH] fix(core): wait briefly for starting MCP servers before a model call (#60490) --- packages/core/src/mcp/index.ts | 51 +++++++++++++- packages/core/src/tool/mcp.ts | 16 ++++- packages/core/test/fixture/mcp.ts | 1 + packages/core/test/mcp.test.ts | 106 ++++++++++++++++++++++++++---- 4 files changed, 158 insertions(+), 16 deletions(-) diff --git a/packages/core/src/mcp/index.ts b/packages/core/src/mcp/index.ts index 285af0a9fc9..f9951531529 100644 --- a/packages/core/src/mcp/index.ts +++ b/packages/core/src/mcp/index.ts @@ -7,7 +7,21 @@ import type { Session } from "@opencode/schema/session" import type { Transport } from "@modelcontextprotocol/client" import { createHash } from "node:crypto" import { isDeepStrictEqual } from "node:util" -import { Cause, Context, Effect, Exit, FiberSet, Latch, Layer, Schema, Scope, Semaphore, Stream, Types } from "effect" +import { + Cause, + Clock, + Context, + Effect, + Exit, + FiberSet, + Latch, + Layer, + Schema, + Scope, + Semaphore, + Stream, + Types, +} from "effect" import { makeLocationNode } from "@opencode/util/effect/app-node" import { Credential } from "../credential.js" import { Bus } from "../bus.js" @@ -80,6 +94,8 @@ type ServerEntry = { readonly config: Mcp.ServerConfig status: Status readonly startup: Latch.Latch + // The connection attempt in flight: when it began and a latch that opens once it settles. + attempt?: { readonly started: number; readonly settled: Latch.Latch } scope?: Scope.Closeable client?: McpClient.Connection tools?: ReadonlyArray @@ -98,6 +114,9 @@ type AttachedEntry = { tools: ReadonlyArray } +// How long a model call may wait for a server that is still connecting, counted from when it began. +const STARTUP_GRACE_MS = 2_000 + // Bounds re-listing the tools of an attached connection that takes over the top of its stack. const FALLBACK_LIST_TIMEOUT = "5 seconds" @@ -136,6 +155,11 @@ export interface Interface extends State.Transformable { */ readonly attach: (name: string, transport: Transport) => Effect.Effect readonly tools: () => Effect.Effect + /** + * Waits for servers that are still connecting, each until it settles or until its startup grace + * window ends. Servers past their window never wait. + */ + readonly awaitStartup: () => Effect.Effect readonly callTool: (input: { readonly server: ServerName | string readonly name: string @@ -455,6 +479,9 @@ export const layer = (options?: Options) => const startServer = (name: ServerName, entry: ServerEntry) => Effect.gen(function* () { + // A server still pending from creation keeps the window that started with its entry. + if (!entry.attempt || entry.status.status !== "pending") + entry.attempt = { started: yield* Clock.currentTimeMillis, settled: Latch.makeUnsafe() } // Announce the handshake so connect() and credential reconnects don't show a stale // disabled/failed status for the duration of the connection attempt. entry.status = { status: "pending" } @@ -505,6 +532,14 @@ export const layer = (options?: Options) => yield* Effect.logWarning("mcp connect failed", { server: name, status: entry.status }) yield* bus.publish(McpEvent.StatusChanged, { server: name }) }).pipe( + // Every caller holds the server lock, so the attempt read here is the one this call began. + Effect.ensuring( + Effect.suspend(() => { + const attempt = entry.attempt + entry.attempt = undefined + return attempt ? attempt.settled.open : Effect.void + }), + ), Effect.ensuring(entry.startup.open), Effect.annotateLogs({ server: name, directory: location.directory, connectionID: crypto.randomUUID() }), ) @@ -535,6 +570,7 @@ export const layer = (options?: Options) => config: serverConfig, status: { status: "pending" }, startup: Latch.makeUnsafe(), + attempt: { started: yield* Clock.currentTimeMillis, settled: Latch.makeUnsafe() }, } entries.set(name, entry) yield* Effect.gen(function* () { @@ -665,11 +701,13 @@ export const layer = (options?: Options) => const reconcile = Effect.fnUntraced(function* () { const servers = state.get().servers if (!applied && entries.size === 0) { + const started = yield* Clock.currentTimeMillis for (const [name, server] of servers) { entries.set(name, { config: server, status: { status: "pending" }, startup: Latch.makeUnsafe(), + attempt: { started, settled: Latch.makeUnsafe() }, }) } yield* Effect.forEach(entries, ([name, entry]) => register(name, entry), { discard: true }) @@ -816,6 +854,17 @@ export const layer = (options?: Options) => ...clients, ].toSorted((a, b) => a.server.localeCompare(b.server) || a.name.localeCompare(b.name)) }), + awaitStartup: Effect.fn("MCP.awaitStartup")(function* () { + const now = yield* Clock.currentTimeMillis + yield* Effect.all( + Array.from(entries.values()).flatMap((entry) => { + if (entry.status.status !== "pending" || !entry.attempt) return [] + const remaining = entry.attempt.started + STARTUP_GRACE_MS - now + return remaining > 0 ? [entry.attempt.settled.await.pipe(Effect.raceFirst(Effect.sleep(remaining)))] : [] + }), + { concurrency: "unbounded", discard: true }, + ) + }), callTool: Effect.fn("MCP.callTool")(function* (input) { const server = ServerName.make(input.server) // An attached client owns the tools it lists, even when a configured server shares its name, and diff --git a/packages/core/src/tool/mcp.ts b/packages/core/src/tool/mcp.ts index 7fbce8a31da..7391ba9e860 100644 --- a/packages/core/src/tool/mcp.ts +++ b/packages/core/src/tool/mcp.ts @@ -23,7 +23,10 @@ export const namespace = (server: string) => server.replace(/[^a-zA-Z0-9_-]/g, " export const name = (server: string, tool: string) => `${namespace(server)}_${tool.replace(/[^a-zA-Z0-9_-]/g, "_")}` export interface Interface { - /** Wait for the initial MCP tool registration to settle. */ + /** + * Wait for the initial MCP tool registration, give servers still connecting a bounded chance to + * finish, then bring the registry up to date without waiting for the debounced reload. + */ readonly flush: Effect.Effect } @@ -140,7 +143,16 @@ export const layer = Layer.effect( Stream.runForEach(() => reconcile), Effect.forkScoped({ startImmediately: true }), ) - return Service.of({ flush: Effect.asVoid(Fiber.await(initial)) }) + return Service.of({ + flush: Effect.gen(function* () { + yield* Fiber.await(initial) + yield* mcp.awaitStartup() + // Each catalog refresh creates new tool objects, so identity shows whether the registry is behind. + const current = yield* mcp.tools() + if (current.length !== discovered.length || current.some((tool, index) => tool !== discovered[index])) + yield* reconcile + }), + }) }), ) diff --git a/packages/core/test/fixture/mcp.ts b/packages/core/test/fixture/mcp.ts index 97a1c91551e..e6c31d3b0e7 100644 --- a/packages/core/test/fixture/mcp.ts +++ b/packages/core/test/fixture/mcp.ts @@ -16,6 +16,7 @@ export const emptyMcp = Mcp.Service.of({ remove: () => Effect.die("unused mcp.remove"), attach: () => Effect.die("unused mcp.attach"), tools: () => Effect.succeed([]), + awaitStartup: () => Effect.void, callTool: () => Effect.die("unused mcp.callTool"), instructions: () => Effect.succeed([]), prompts: () => Effect.succeed([]), diff --git a/packages/core/test/mcp.test.ts b/packages/core/test/mcp.test.ts index ad5c0f0c696..7846591d025 100644 --- a/packages/core/test/mcp.test.ts +++ b/packages/core/test/mcp.test.ts @@ -436,6 +436,7 @@ const settled = (service: Mcp.Interface, name = "resources") => }).pipe(Effect.retry({ times: 200, schedule: Schedule.spaced("10 millis") })) const mcp = Layer.mock(Mcp.Service, { + awaitStartup: () => Effect.void, tools: () => Effect.succeed([ { @@ -2520,6 +2521,7 @@ testEffect(Layer.empty).live("preserves plugin transforms through MCP catalog up AppNodeBuilder.build(LayerNode.group([Tool.node, McpTool.node, Bus.node]), [ Mcp.node.replace( Layer.mock(Mcp.Service, { + awaitStartup: () => Effect.void, tools: () => Ref.get(catalog), callTool: (input) => Effect.succeed({ @@ -2540,37 +2542,45 @@ testEffect(Layer.empty).live("preserves plugin transforms through MCP catalog up ) testEffect(Layer.empty).effect("coalesces queued MCP tool notifications after initial registration", () => { + const tool = (name: string) => + ({ + server: Mcp.ServerName.make("demo"), + name, + codemode: false, + inputSchema: { type: "object", properties: {} }, + }) satisfies Mcp.Tool let reads = 0 + let catalog = [tool("read_1")] return Effect.gen(function* () { const registry = yield* Tool.Service const registration = yield* McpTool.Service const bus = yield* Bus.Service yield* registration.flush - expect(reads).toBe(1) + // Initial registration plus the flush's check that the registry is current. + expect(reads).toBe(2) expect((yield* toolDefinitions(registry)).map((tool) => tool.name)).toEqual(["demo_read_1", "execute"]) + catalog = [tool("read_2")] yield* bus.publish(McpEvent.ToolsChanged, { server: "demo" }) - yield* advance(() => reads >= 2) - expect(reads).toBe(2) - yield* Effect.forEach(Array.from({ length: 20 }), () => bus.publish(McpEvent.ToolsChanged, { server: "demo" })) yield* advance(() => reads >= 3) - yield* drain expect(reads).toBe(3) + catalog = [tool("read_3")] + yield* Effect.forEach(Array.from({ length: 20 }), () => bus.publish(McpEvent.ToolsChanged, { server: "demo" })) + yield* advance(() => reads >= 4) + yield* drain + expect(reads).toBe(4) expect((yield* toolDefinitions(registry)).map((tool) => tool.name)).toEqual(["demo_read_3", "execute"]) }).pipe( Effect.provide( AppNodeBuilder.build(LayerNode.group([Tool.node, McpTool.node, Bus.node]), [ Mcp.node.replace( Layer.mock(Mcp.Service, { + awaitStartup: () => Effect.void, tools: () => - Effect.sync(() => [ - { - server: Mcp.ServerName.make("demo"), - name: `read_${++reads}`, - codemode: false, - inputSchema: { type: "object", properties: {} }, - } satisfies Mcp.Tool, - ]), + Effect.sync(() => { + reads++ + return catalog + }), }), ), Permission.node.replace(Layer.mock(Permission.Service, { assert: () => Effect.void })), @@ -2580,6 +2590,76 @@ testEffect(Layer.empty).effect("coalesces queued MCP tool notifications after in ) }) +// Holds every MCP POST, including the handshake, until the test releases it. +const gatedServer = Effect.gen(function* () { + const started = yield* Deferred.make() + const release = yield* Deferred.make() + const server = yield* resourceServer({ + respond: (request) => + request.method !== "POST" + ? undefined + : Effect.runPromise( + Deferred.succeed(started, undefined).pipe(Effect.andThen(Deferred.await(release)), Effect.as(undefined)), + ), + }) + return { server, started, release } +}) + +// The real Mcp layer behind the tool registry; the bus never delivers, so only flush can register tools. +const startupRegistry = (url: string) => + AppNodeBuilder.build(LayerNode.group([Mcp.node, Tool.node, McpTool.node]), [ + Mcp.node.replace(resourceMcpLayer(new ConfigMCP.Remote({ type: "remote", url, oauth: false, codemode: false }))), + Permission.node.replace(permissions), + Bus.node.replace(events), + Image.node.replace(imagePassthrough), + Global.node.replace(Global.layerWith({ data: outputData })), + ]) + +testEffect(Layer.empty).effect("flush waits for a server that connects within its startup window", () => + Effect.gen(function* () { + const gated = yield* gatedServer + yield* Effect.gen(function* () { + const registry = yield* Tool.Service + const registration = yield* McpTool.Service + yield* Deferred.await(gated.started) + const flush = yield* registration.flush.pipe(Effect.forkChild({ startImmediately: true })) + yield* Effect.yieldNow + expect(flush.pollUnsafe()).toBeUndefined() + + yield* Deferred.succeed(gated.release, undefined) + yield* Fiber.join(flush) + expect((yield* toolDefinitions(registry)).map((tool) => tool.name)).toContain("resources_echo") + }).pipe( + Effect.ensuring(Deferred.succeed(gated.release, undefined)), + Effect.provide(startupRegistry(gated.server.url)), + ) + }), +) + +testEffect(Layer.empty).effect("flush stops waiting for a hung server when its startup window ends", () => + Effect.gen(function* () { + const gated = yield* gatedServer + yield* Effect.gen(function* () { + const mcp = yield* Mcp.Service + const registration = yield* McpTool.Service + yield* Deferred.await(gated.started) + const flush = yield* registration.flush.pipe(Effect.forkChild({ startImmediately: true })) + yield* TestClock.adjust("1999 millis") + expect(flush.pollUnsafe()).toBeUndefined() + + yield* TestClock.adjust("1 millis") + yield* Fiber.join(flush) + // Past its window, the still-pending server no longer holds up a model call. + yield* registration.flush + expect((yield* mcp.servers())[0]?.status).toEqual({ status: "pending" }) + }).pipe( + // Shutting down mid-handshake would wait on the held request. + Effect.ensuring(Deferred.succeed(gated.release, undefined)), + Effect.provide(startupRegistry(gated.server.url)), + ) + }), +) + it.effect("advertises MCP output schemas to Code Mode", () => Effect.gen(function* () { const registry = yield* Tool.Service