fix(core): wait briefly for starting MCP servers before a model call (#60490)

This commit is contained in:
Aiden Cline
2026-10-30 22:50:33 -05:00
committed by GitHub
Unverified
parent 2d800e4742
commit c811c0cb51
4 changed files with 158 additions and 16 deletions
+50 -1
View File
@@ -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<Tool>
@@ -98,6 +114,9 @@ type AttachedEntry = {
tools: ReadonlyArray<Tool>
}
// 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<Editor> {
*/
readonly attach: (name: string, transport: Transport) => Effect.Effect<void, McpClient.ConnectError, Scope.Scope>
readonly tools: () => Effect.Effect<Tool[]>
/**
* 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<void>
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
+14 -2
View File
@@ -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<void>
}
@@ -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
}),
})
}),
)
+1
View File
@@ -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([]),
+93 -13
View File
@@ -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<void>()
const release = yield* Deferred.make<void>()
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