Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions docs/architecture/mcp-dynamic-tool-loading.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# MCP dynamic tool loading

Issue #578 adds a task-scoped gate to API tool declarations. When the tools
allowed by the current mode and tool policy exceed `mcp.dynamicLoad.threshold`
(default 50), the task initially attaches up to `mcp.dynamicLoad.initialK`
(default 30) ranked tools. Images-only tasks use the first distinct scoped
tools because there is no initial text to rank.

The selection is stored in task history. Missing or invalid selections are
initialized on demand; a valid empty selection remains initialized. Restored
nonempty selections are checked against scoped definitions before use; selections
with no available names are ranked again. MCP names
already used in conversation history are retained for provider compatibility,
so resumed tasks can require more than `initialK` declarations. This is an
initial selection limit, not a lifetime cap. Historical names accumulate during
a task and are not trimmed, since removing their definitions can cause providers
to reject conversation history. Current server, mode, and tool-policy
restrictions still apply.

If saving fails, the task retains its in-memory selection and continues. Later
normal history saves retry persistence. History writes union attached names under
the disk lock, preserving newer historical names when an older save arrives late.
Storage errors do not trigger API
stream retries.

The gate limits advertised definitions; it does not add an execution permission
boundary. Existing tool authorization still applies to calls by name.

The settings schema and extension-state round trip are implemented. SettingsView
controls and replacement of the legacy catalog-wide warning are deferred to
#581. The legacy warning uses its own catalog advisory threshold; it does not
report the scoped tool count for a running task. The `mcp_load` escape hatch is
deferred to #579.
24 changes: 24 additions & 0 deletions packages/types/src/__tests__/global-settings.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ import {
GLOBAL_SETTINGS_KEYS,
globalSettingsSchema,
} from "../global-settings.js"
import { resolveMcpDynamicLoadSettings } from "../mcp.js"

describe("destructive command guard global setting", () => {
it("is opt-in by default", () => {
Expand Down Expand Up @@ -51,3 +52,26 @@ describe("collapseCommandOutputByDefault global setting", () => {
expect(globalSettingsSchema.safeParse({ collapseCommandOutputByDefault: "true" }).success).toBe(false)
})
})

describe.each(["mcp.dynamicLoad.threshold", "mcp.dynamicLoad.initialK"] as const)("%s", (key) => {
it.each([undefined, 1, 30, 50, 100])("round-trips %s through the settings schema", (value) => {
const settings = globalSettingsSchema.parse({ [key]: value })
expect(globalSettingsSchema.parse(JSON.parse(JSON.stringify(settings)))[key]).toBe(value)
expect(GLOBAL_SETTINGS_KEYS).toContain(key)
})
it.each([-1, 1.5, NaN, Infinity, "30", null])("rejects %s", (value) => {
expect(globalSettingsSchema.safeParse({ [key]: value }).success).toBe(false)
})
it("allows zero only for the threshold", () => {
expect(globalSettingsSchema.safeParse({ [key]: 0 }).success).toBe(key === "mcp.dynamicLoad.threshold")
})
})

describe("runtime MCP routing defaults", () => {
it.each([undefined, null, -1, 1.5, NaN, Infinity, "30", {}])("replaces invalid input %j", (value) => {
expect(resolveMcpDynamicLoadSettings(value, value)).toEqual({ threshold: 50, initialK: 30 })
})
it("preserves a zero threshold and a positive limit", () => {
expect(resolveMcpDynamicLoadSettings(0, 1)).toEqual({ threshold: 0, initialK: 1 })
})
})
21 changes: 21 additions & 0 deletions packages/types/src/__tests__/history.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -63,4 +63,25 @@ describe("historyItemSchema", () => {
it("leaves title unset when absent", () => {
expect(historyItemSchema.parse(baseItem)).not.toHaveProperty("title")
})

it.each([
{ value: undefined, expected: undefined },
{ value: null, expected: undefined },
{ value: "abc", expected: undefined },
{ value: 42, expected: undefined },
{ value: {}, expected: undefined },
{ value: [42], expected: undefined },
{ value: [], expected: [] },
{ value: ["mcp--" + "s".repeat(57) + "--"], expected: ["mcp--" + "s".repeat(57) + "--"] },
{ value: ["mcp--" + "s".repeat(59)], expected: ["mcp--" + "s".repeat(59)] },
{ value: ["mcp--server--"], expected: undefined },
{ value: ["mcp--" + "s".repeat(56) + "--"], expected: undefined },
{ value: ["invalid"], expected: undefined },
{ value: ["mcp__a__b"], expected: undefined },
{ value: ["mcp--a--b", null, 42], expected: ["mcp--a--b"] },
])("normalizes persisted attachments $value without losing the task", ({ value, expected }) => {
const parsed = historyItemSchema.parse({ ...baseItem, attachedMcpToolNames: value })
expect(parsed.id).toBe(baseItem.id)
expect(parsed.attachedMcpToolNames).toEqual(expected)
})
})
3 changes: 3 additions & 0 deletions packages/types/src/global-settings.ts
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ import { toolNamesSchema } from "./tool.js"
import { type Keys } from "./type-fu.js"
import { languagesSchema } from "./vscode.js"
import { providerIdentifiers } from "./provider-identifiers.js"
import { mcpDynamicLoadThresholdSchema, mcpDynamicLoadInitialKSchema } from "./mcp.js"

/**
* Default delay in milliseconds after writes to allow diagnostics to detect potential problems.
Expand Down Expand Up @@ -265,6 +266,8 @@ export const globalSettingsSchema = z.object({
telemetrySetting: telemetrySettingsSchema.optional(),

mcpEnabled: z.boolean().optional(),
"mcp.dynamicLoad.threshold": mcpDynamicLoadThresholdSchema.optional(),
"mcp.dynamicLoad.initialK": mcpDynamicLoadInitialKSchema.optional(),

mode: z.string().optional(),
modeApiConfigs: z.record(z.string(), z.string()).optional(),
Expand Down
12 changes: 12 additions & 0 deletions packages/types/src/history.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
import { z } from "zod"

import { isCanonicalMcpToolName } from "./mcp.js"

import { todoItemSchema } from "./todo.js"

/**
Expand All @@ -26,6 +28,14 @@ export const pendingTaskActionSchema = z.discriminatedUnion("kind", [

export type PendingTaskAction = z.infer<typeof pendingTaskActionSchema>

// Older or hand-edited history can contain an invalid attachment field. Do not
// discard the task record or mark a non-array value as an initialized selection.
export const attachedMcpToolNamesSchema = z.preprocess((value) => {
if (!Array.isArray(value)) return undefined
const names = value.filter((name): name is string => typeof name === "string" && isCanonicalMcpToolName(name))
return value.length > 0 && names.length === 0 ? undefined : names
}, z.array(z.string()).optional())

export const historyItemSchema = z.object({
id: z.string(),
rootTaskId: z.string().optional(),
Expand All @@ -50,6 +60,8 @@ export const historyItemSchema = z.object({
completedByChildId: z.string().optional(), // Child that completed and resumed this parent
completionResultSummary: z.string().optional(), // Summary from completed child
pendingAction: pendingTaskActionSchema.optional(),
// Absent means routing has not run; an empty array is an initialized selection.
attachedMcpToolNames: attachedMcpToolNamesSchema,
})

export type HistoryItem = z.infer<typeof historyItemSchema>
29 changes: 24 additions & 5 deletions packages/types/src/mcp.ts
Original file line number Diff line number Diff line change
@@ -1,11 +1,30 @@
import { z } from "zod"

/**
* Maximum number of MCP tools that can be enabled before showing a warning.
* LLMs tend to perform poorly when given too many tools to choose from.
*/
/** Canonical generated names, including prefixes cut off at the provider's 64-character limit. */
export function isCanonicalMcpToolName(name: string): boolean {
return (
/^mcp--[A-Za-z_][\w-]*--[A-Za-z_][\w-]*$/.test(name) ||
(name.length === 64 && /^mcp--[A-Za-z_][\w-]*$/.test(name))
)
}

export const DEFAULT_MCP_DYNAMIC_LOAD_THRESHOLD = 50
export const DEFAULT_MCP_DYNAMIC_LOAD_INITIAL_K = 30

/** @deprecated Legacy catalog advisory. Runtime routing uses the dynamic-load settings. */
export const MAX_MCP_TOOLS_THRESHOLD = 60

export const mcpDynamicLoadThresholdSchema = z.number().int().min(0)
export const mcpDynamicLoadInitialKSchema = z.number().int().min(1)

/** Apply the same validation to persisted values and direct runtime callers. */
export function resolveMcpDynamicLoadSettings(threshold: unknown, initialK: unknown) {
return {
threshold: mcpDynamicLoadThresholdSchema.safeParse(threshold).data ?? DEFAULT_MCP_DYNAMIC_LOAD_THRESHOLD,
initialK: mcpDynamicLoadInitialKSchema.safeParse(initialK).data ?? DEFAULT_MCP_DYNAMIC_LOAD_INITIAL_K,
}
}

/**
* McpServerUse
*/
Expand Down Expand Up @@ -155,7 +174,7 @@ export interface EnabledMcpToolsCount {
* @example
* const { enabledToolCount, enabledServerCount } = countEnabledMcpTools(mcpServers)
* if (enabledToolCount > MAX_MCP_TOOLS_THRESHOLD) {
* // Show warning
* // Show the legacy catalog advisory, separate from task-scoped routing.
* }
*/
export function countEnabledMcpTools(servers: McpServer[]): EnabledMcpToolsCount {
Expand Down
2 changes: 1 addition & 1 deletion packages/types/src/message.ts
Original file line number Diff line number Diff line change
Expand Up @@ -139,7 +139,7 @@ export function isNonBlockingAsk(ask: ClineAsk): ask is NonBlockingAsk {
* - `condense_context`: Context condensation/summarization has started
* - `condense_context_error`: Error occurred during context condensation
* - `codebase_search_result`: Results from searching the codebase
* - `too_many_tools_warning`: Warning that too many MCP tools are enabled, which may confuse the LLM
* - `too_many_tools_warning`: Legacy warning retained for history rendering; no longer emitted by Task.
* - `ignored_disabled_tools_warning`: Warning that a `disabledTools` entry names a protocol tool, which user settings cannot disable
*/
export const clineSays = [
Expand Down
2 changes: 2 additions & 0 deletions packages/types/src/vscode-extension-host.ts
Original file line number Diff line number Diff line change
Expand Up @@ -377,6 +377,8 @@ export type ExtensionState = Pick<
experiments: Experiments // Map of experiment IDs to their enabled state

mcpEnabled: boolean
"mcp.dynamicLoad.threshold"?: number
"mcp.dynamicLoad.initialK"?: number

mode: string
customModes: ModeConfig[]
Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
// npx vitest src/core/assistant-message/__tests__/presentAssistantMessage-tool-usage-attribution.spec.ts

import { buildMcpToolName } from "../../../utils/mcp-name"
import { NativeToolCallParser } from "../NativeToolCallParser"
import { DispatchState, type PendingWork } from "../../task/dispatchState"
import type { Anthropic } from "@anthropic-ai/sdk"
import { TelemetryEventName } from "@roo-code/types"
Expand Down Expand Up @@ -322,6 +324,40 @@ describe("presentAssistantMessage - tool usage attribution", () => {
})

describe("native mcp_tool_use block", () => {
it.each([55, 57, 58, 59, 70])(
"resolves generated names truncated within a %s-character server",
async (length) => {
const serverName = "s".repeat(length)
const toolName = "original_tool"
const name = buildMcpToolName(serverName, toolName)
mockTask.providerRef = {
deref: () => ({
getState: vi.fn().mockResolvedValue({ mode: "code", customModes: [] }),
getMcpHub: () => ({
findServerNameBySanitizedName: () => undefined,
getAllServers: () => [
{ name: serverName, tools: [{ name: toolName, enabledForPrompt: true }] },
],
}),
}),
}
const parsed = NativeToolCallParser.parseDynamicMcpTool({ id: "truncated", name, arguments: "{}" })
expect(parsed).not.toBeNull()
mockTask.assistantMessageContent = [parsed]
const handle = vi.spyOn(useMcpToolTool, "handle").mockResolvedValue(undefined)
// The structural task double provides the dispatch state, provider, API and callbacks used here.
await presentAssistantMessage(mockTask as unknown as Task, baseSnapshot)
expect(handle).toHaveBeenCalledWith(
expect.anything(),
expect.objectContaining({
params: expect.objectContaining({ server_name: serverName, tool_name: toolName }),
}),
expect.anything(),
)
handle.mockRestore()
},
)

it("records exactly one attempt once the MCP tool's own validation passes", async () => {
mockTask.providerRef = {
deref: () => ({
Expand Down
22 changes: 20 additions & 2 deletions src/core/assistant-message/presentAssistantMessage.ts
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
import { buildMcpToolName, toolNamesMatch } from "../../utils/mcp-name"
import { markToolRejected } from "../task/toolExecutionContext"
import { DispatchState, transitionDispatch } from "../task/dispatchState"
import { serializeError } from "serialize-error"
Expand Down Expand Up @@ -323,13 +324,30 @@ async function presentAssistantMessageBlock(cline: Task, policySnapshot: Request
// We need the original name to find the actual MCP connection
const mcpHub = cline.providerRef.deref()?.getMcpHub()
let resolvedServerName = mcpBlock.serverName
let resolvedToolName = mcpBlock.toolName
if (mcpHub) {
const originalName = mcpHub.findServerNameBySanitizedName(mcpBlock.serverName)
if (originalName) {
resolvedServerName = originalName
}
}

// Truncated generated names cannot be reversed by splitting separators.
// Recover the original pair from the catalog; normal policy checks still apply.
if (mcpHub && mcpBlock.name.length === 64) {
const matches = mcpHub
.getAllServers()

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could this lookup use the enabled, project-priority, mode-scoped, deduplicated catalog that advertised the tool?

.flatMap((server) =>
(server.tools ?? [])
.filter((tool) => toolNamesMatch(buildMcpToolName(server.name, tool.name), mcpBlock.name))
.map((tool) => ({ serverName: server.name, toolName: tool.name })),
)
if (matches.length === 1 && matches[0]) {
resolvedServerName = matches[0].serverName
resolvedToolName = matches[0].toolName
}
}

// Execute the MCP tool using the same handler as use_mcp_tool
// Create a synthetic ToolUse block that the useMcpToolTool can handle
const syntheticToolUse: ToolUse<"use_mcp_tool"> = {
Expand All @@ -338,13 +356,13 @@ async function presentAssistantMessageBlock(cline: Task, policySnapshot: Request
name: "use_mcp_tool",
params: {
server_name: resolvedServerName,
tool_name: mcpBlock.toolName,
tool_name: resolvedToolName,
arguments: JSON.stringify(mcpBlock.arguments),
},
partial: mcpBlock.partial,
nativeArgs: {
server_name: resolvedServerName,
tool_name: mcpBlock.toolName,
tool_name: resolvedToolName,
arguments: mcpBlock.arguments,
},
}
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
import * as fs from "fs/promises"
import * as os from "os"
import * as path from "path"
import { TaskHistoryStore } from "../TaskHistoryStore"
import { taskMetadata } from "../taskMetadata"

describe("MCP attachment history round trip", () => {
it.each([false, true])(
"retains historical names after a delayed stale save (separate store: %s)",
async (separateStore) => {
const directory = await fs.mkdtemp(path.join(os.tmpdir(), "mcp-attachments-race-"))
const store = new TaskHistoryStore(directory)
const peer = new TaskHistoryStore(directory)
const restored = new TaskHistoryStore(directory)
try {
const { historyItem } = await taskMetadata({
taskId: "attachment-task",
taskNumber: 1,
messages: [],
workspace: directory,
globalStoragePath: directory,
attachedMcpToolNames: ["mcp--catalog--initial"],
})
await store.initialize()
await store.upsert(historyItem)
await peer.initialize()
let release = () => {}
const gate = new Promise<void>((resolve) => {
release = resolve
})
const olderSave = gate.then(() =>
(separateStore ? peer : store).upsert({
...historyItem,
attachedMcpToolNames: separateStore ? [] : historyItem.attachedMcpToolNames,
}),
)
await store.upsert({
...historyItem,
attachedMcpToolNames: ["mcp--catalog--initial", "mcp--catalog--historical"],
})
release()
await olderSave
await restored.initialize()
expect(restored.get(historyItem.id)?.attachedMcpToolNames).toEqual([
"mcp--catalog--initial",
"mcp--catalog--historical",
])
} finally {
store.dispose()
peer.dispose()
restored.dispose()
await fs.rm(directory, { recursive: true, force: true })
}
},
)

it.each([{ names: undefined }, { names: [] }, { names: ["mcp--github--issues"] }])(
"preserves $names across a store restart",
async ({ names }) => {
const directory = await fs.mkdtemp(path.join(os.tmpdir(), "mcp-attachments-"))
const store = new TaskHistoryStore(directory)
const restored = new TaskHistoryStore(directory)
try {
const { historyItem } = await taskMetadata({
taskId: "attachment-task",
taskNumber: 1,
messages: [],
workspace: directory,
globalStoragePath: directory,
attachedMcpToolNames: names,
})
await store.initialize()
await store.upsert(historyItem)
store.dispose()
await restored.initialize()
expect(restored.get(historyItem.id)?.attachedMcpToolNames).toEqual(names)
} finally {
store.dispose()
restored.dispose()
await fs.rm(directory, { recursive: true, force: true })
}
},
)
})
Loading
Loading