Skip to content

Commit 383a094

Browse files
fix(server): Copilot threads load optional T3 tools on demand
The T3 MCP server listed all 68 tools to every client. Copilot over ACP has no tool search of its own, so every request carried every schema (about 25k tokens on a fresh thread). Copilot sessions now send `t3-tool-exposure: deferred` with their MCP credential. For such a session, tools/list returns orchestrator_capabilities, delegate_task, task_status and a new tool_search. tool_search matches tools by name and description, lists the matches to that provider session from then on, and sends notifications/tools/list_changed, which Copilot re-lists on within the same turn. Calls are never gated. Other clients list exactly what they did before, without tool_search. Fixes #34233 AI-assisted; verified with the tests and tools listed above.
1 parent 6e21f81 commit 383a094

9 files changed

Lines changed: 324 additions & 5 deletions

File tree

‎apps/server/src/mcp/McpHttpServer.test.ts‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1539,3 +1539,129 @@ it.effect(
15391539
}),
15401540
).pipe(Effect.provide(NodeHttpServer.layerTest)),
15411541
);
1542+
1543+
it.effect("lists optional tools to a deferring client only after tool_search loads them", () =>
1544+
Effect.scoped(
1545+
Effect.gen(function* () {
1546+
const scopeFor = (token: string): McpInvocationContext.McpThreadInvocationScope => ({
1547+
environmentId,
1548+
requestNamespace: token,
1549+
thread: {
1550+
threadId: ThreadId.make(`thread-${token}`),
1551+
providerSessionId: token,
1552+
providerInstanceId: ProviderInstanceId.make("copilot"),
1553+
},
1554+
client: undefined,
1555+
capabilities: new Set(["orchestration"]),
1556+
issuedAt: 1,
1557+
});
1558+
const scopes = new Map([
1559+
["deferringToken", scopeFor("deferringToken")],
1560+
["otherToken", scopeFor("otherToken")],
1561+
]);
1562+
const tool = (name: string, description: string) =>
1563+
Tool.make(name, {
1564+
description,
1565+
success: Schema.Struct({}),
1566+
failure: OrchestratorMcpFailure,
1567+
failureMode: "return",
1568+
});
1569+
const OptionalToolkit = Toolkit.make(
1570+
tool("delegate_task", "Delegates a task."),
1571+
tool("preview_open", "Opens a browser preview."),
1572+
tool("schedule_task", "Schedules a task."),
1573+
);
1574+
const reads = McpToolAccess.reads(() => Effect.succeed({}));
1575+
const serverLayer = McpHttpServer.layerMcpTransport(
1576+
Layer.mergeAll(
1577+
McpHttpServer.toolkitRegistration(
1578+
OptionalToolkit,
1579+
McpToolAccess.toLayer(OptionalToolkit, {
1580+
delegate_task: reads,
1581+
preview_open: reads,
1582+
schedule_task: reads,
1583+
}),
1584+
),
1585+
McpHttpServer.layerToolSearch,
1586+
),
1587+
).pipe(
1588+
Layer.provide(ServerSettings.layerTest()),
1589+
Layer.provide(McpToolAccessTestkit.liveThreadsLayer),
1590+
Layer.provide(
1591+
Layer.mock(McpSessionRegistry.McpSessionRegistry)({
1592+
resolve: (token) => Effect.succeed(scopes.get(token)),
1593+
}),
1594+
),
1595+
);
1596+
yield* HttpRouter.serve(serverLayer, { disableListenLog: true, disableLogger: true }).pipe(
1597+
Layer.build,
1598+
);
1599+
const httpClient = yield* HttpClient.HttpClient;
1600+
const session = (token: string, deferred: boolean) =>
1601+
Effect.gen(function* () {
1602+
const headers = {
1603+
accept: "application/json, text/event-stream",
1604+
authorization: `Bearer ${token}`,
1605+
...(deferred ? { "t3-tool-exposure": "deferred" } : {}),
1606+
};
1607+
const initialize = yield* httpClient.post("/mcp", {
1608+
headers,
1609+
body: HttpBody.text(
1610+
`{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"1.0.0"}}}`,
1611+
"application/json",
1612+
),
1613+
});
1614+
const rpc = (method: string, params: object) =>
1615+
httpClient
1616+
.post("/mcp", {
1617+
headers: {
1618+
...headers,
1619+
"mcp-session-id": initialize.headers["mcp-session-id"]!,
1620+
"mcp-protocol-version": "2025-06-18",
1621+
},
1622+
body: HttpBody.text(
1623+
JSON.stringify({ jsonrpc: "2.0", id: 2, method, params }),
1624+
"application/json",
1625+
),
1626+
})
1627+
.pipe(
1628+
Effect.flatMap((response) => response.text),
1629+
// tool_search answers over SSE, after its list_changed notification.
1630+
Effect.map((text): unknown =>
1631+
text
1632+
.split("\n")
1633+
.filter((line) => line.startsWith("data: ") || line.startsWith("{"))
1634+
.map((line) => JSON.parse(line.replace(/^data: /u, "")) as { id?: number })
1635+
.find((message) => message.id === 2),
1636+
),
1637+
);
1638+
return {
1639+
listed: rpc("tools/list", {}).pipe(
1640+
Effect.map((body) =>
1641+
(body as { result: { tools: ReadonlyArray<{ name: string }> } }).result.tools
1642+
.map((listed) => listed.name)
1643+
.sort(),
1644+
),
1645+
),
1646+
call: (name: string, args: object) =>
1647+
rpc("tools/call", { name, arguments: args }).pipe(
1648+
Effect.map((body) => (body as { result: { structuredContent?: unknown } }).result),
1649+
),
1650+
};
1651+
});
1652+
1653+
const deferring = yield* session("deferringToken", true);
1654+
const other = yield* session("otherToken", false);
1655+
expect(yield* deferring.listed).toEqual(["delegate_task", "tool_search"]);
1656+
expect(yield* other.listed).toEqual(["delegate_task", "preview_open", "schedule_task"]);
1657+
// Unlisted tools stay callable.
1658+
expect((yield* deferring.call("schedule_task", {})).structuredContent).toEqual({});
1659+
1660+
expect(
1661+
(yield* deferring.call("tool_search", { query: "browser" })).structuredContent,
1662+
).toEqual({ tools: [{ name: "preview_open", description: "Opens a browser preview." }] });
1663+
expect(yield* deferring.listed).toEqual(["delegate_task", "preview_open", "tool_search"]);
1664+
expect(yield* other.listed).toEqual(["delegate_task", "preview_open", "schedule_task"]);
1665+
}),
1666+
).pipe(Effect.provide(NodeHttpServer.layerTest)),
1667+
);

‎apps/server/src/mcp/McpHttpServer.ts‎

Lines changed: 45 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,8 @@ import {
4343
import { advertisedJsonSchema } from "./advertisedJsonSchema.ts";
4444
import * as McpInvocationContext from "./McpInvocationContext.ts";
4545
import * as McpToolAccess from "./McpToolAccess.ts";
46+
import * as McpToolExposure from "./McpToolExposure.ts";
47+
import { MCP_TOOL_EXPOSURE_HEADER } from "@t3tools/provider-core/server/mcpSession";
4648
import * as OrchestratorMcpService from "./OrchestratorMcpService.ts";
4749
import { PreviewControlsToolkit } from "./toolkits/previewControls/tools.ts";
4850
import * as PreviewControlsHandlers from "./toolkits/previewControls/handlers.ts";
@@ -69,6 +71,8 @@ import * as WorktreeHandlers from "./toolkits/worktree/handlers.ts";
6971
import { WorktreeToolkit } from "./toolkits/worktree/tools.ts";
7072
import * as WorktreeMcpService from "./WorktreeMcpService.ts";
7173
import * as PullRequestsHandlers from "./toolkits/pullRequests/handlers.ts";
74+
import * as ToolSearchHandlers from "./toolkits/toolSearch/handlers.ts";
75+
import { ToolSearchToolkit } from "./toolkits/toolSearch/tools.ts";
7276
import { PullRequestsToolkit } from "./toolkits/pullRequests/tools.ts";
7377
import * as DeviceHandlers from "./toolkits/device/handlers.ts";
7478
import {
@@ -1262,4 +1266,44 @@ export const layerTools = Layer.mergeAll(
12621266
layerHtmlToolkit,
12631267
);
12641268

1265-
export const layer = layerMcpTransport(layerTools);
1269+
const layerToolExposure = Layer.effect(
1270+
McpToolExposure.McpToolExposure,
1271+
Effect.gen(function* () {
1272+
const server = yield* McpServer.McpServer;
1273+
return McpToolExposure.make(
1274+
() =>
1275+
server.tools.map(({ tool }) => ({ name: tool.name, description: tool.description ?? "" })),
1276+
() => server.notifications["notifications/tools/list_changed"]({}),
1277+
);
1278+
}),
1279+
);
1280+
1281+
/**
1282+
* A provider session that sends `MCP_TOOL_EXPOSURE_HEADER: deferred` lists only
1283+
* the direct tools and what its `tool_search` calls loaded. Calls are never
1284+
* gated, and every other client lists everything but `tool_search`.
1285+
*/
1286+
const layerDeferredListing = McpServer.visibility(
1287+
Effect.gen(function* () {
1288+
const exposure = yield* McpToolExposure.McpToolExposure;
1289+
// Untraced: it runs once per tool on every list request.
1290+
return Effect.fnUntraced(function* ({ method, target, headers }: McpServer.MiddlewareOptions) {
1291+
if (method !== "tools/list") return true;
1292+
const scope = yield* Effect.serviceOption(McpInvocationContext.McpInvocationContext);
1293+
const providerSessionId = Option.getOrUndefined(scope)?.thread?.providerSessionId;
1294+
if (headers[MCP_TOOL_EXPOSURE_HEADER] !== "deferred" || providerSessionId === undefined) {
1295+
return target !== McpToolExposure.TOOL_SEARCH;
1296+
}
1297+
return exposure.isListed(providerSessionId, target);
1298+
});
1299+
}),
1300+
{ global: true },
1301+
);
1302+
1303+
/** Outside layerTools: the clients its budget measures never list `tool_search`. */
1304+
export const layerToolSearch = Layer.mergeAll(
1305+
toolkitRegistration(ToolSearchToolkit, ToolSearchHandlers.layer),
1306+
layerDeferredListing,
1307+
).pipe(Layer.provide(layerToolExposure));
1308+
1309+
export const layer = layerMcpTransport(Layer.mergeAll(layerTools, layerToolSearch));
Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
import * as Context from "effect/Context";
2+
import * as Effect from "effect/Effect";
3+
4+
export const TOOL_SEARCH = "tool_search";
5+
6+
/** What a deferring client lists before it searches. Pi's extension declares the same three. */
7+
const DIRECT_TOOLS: ReadonlySet<string> = new Set([
8+
"orchestrator_capabilities",
9+
"delegate_task",
10+
"task_status",
11+
TOOL_SEARCH,
12+
]);
13+
14+
const MAX_RESULTS = 10;
15+
// Sessions that ended are never reported here, so keep only the newest.
16+
const MAX_SESSIONS = 256;
17+
18+
export interface ListedTool {
19+
readonly name: string;
20+
readonly description: string;
21+
}
22+
23+
export class McpToolExposure extends Context.Service<
24+
McpToolExposure,
25+
{
26+
/** Finds tools for the query and lists them to the session from now on. */
27+
readonly search: (
28+
providerSessionId: string,
29+
query: string,
30+
) => Effect.Effect<ReadonlyArray<ListedTool>>;
31+
readonly isListed: (providerSessionId: string, tool: string) => boolean;
32+
}
33+
>()("t3/mcp/McpToolExposure") {}
34+
35+
const score = (tool: ListedTool, terms: ReadonlyArray<string>) => {
36+
const name = tool.name.toLowerCase();
37+
const description = tool.description.toLowerCase();
38+
let total = 0;
39+
for (const term of terms) {
40+
if (term === name) total += 100;
41+
else if (name.includes(term)) total += 3;
42+
else if (description.includes(term)) total += 1;
43+
}
44+
return total;
45+
};
46+
47+
export const make = (
48+
tools: () => ReadonlyArray<ListedTool>,
49+
announceListChanged: () => Effect.Effect<void>,
50+
) => {
51+
const loaded = new Map<string, Set<string>>();
52+
const load = (providerSessionId: string, names: ReadonlyArray<string>) => {
53+
const listed = loaded.get(providerSessionId) ?? new Set<string>();
54+
loaded.delete(providerSessionId);
55+
loaded.set(providerSessionId, listed);
56+
for (const name of names) listed.add(name);
57+
for (const oldest of loaded.keys()) {
58+
if (loaded.size <= MAX_SESSIONS) break;
59+
loaded.delete(oldest);
60+
}
61+
};
62+
return McpToolExposure.of({
63+
search: Effect.fn("McpToolExposure.search")(function* (providerSessionId, query) {
64+
const terms = query
65+
.toLowerCase()
66+
.split(/[^a-z0-9_]+/u)
67+
.filter(Boolean);
68+
const found = tools()
69+
.filter((tool) => tool.name !== TOOL_SEARCH)
70+
.map((tool) => ({ tool, score: score(tool, terms) }))
71+
.filter((match) => match.score > 0)
72+
.sort((a, b) => b.score - a.score)
73+
.slice(0, MAX_RESULTS)
74+
.map((match) => match.tool);
75+
if (found.length > 0) {
76+
load(
77+
providerSessionId,
78+
found.map((tool) => tool.name),
79+
);
80+
yield* announceListChanged();
81+
}
82+
return found;
83+
}),
84+
isListed: (providerSessionId, tool) =>
85+
DIRECT_TOOLS.has(tool) || loaded.get(providerSessionId)?.has(tool) === true,
86+
});
87+
};
Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
import * as Effect from "effect/Effect";
2+
3+
import * as McpInvocationContext from "../../McpInvocationContext.ts";
4+
import * as McpToolAccess from "../../McpToolAccess.ts";
5+
import * as McpToolExposure from "../../McpToolExposure.ts";
6+
import { ToolSearchToolkit } from "./tools.ts";
7+
8+
export const layer = McpToolAccess.toLayer(ToolSearchToolkit, {
9+
tool_search: McpToolAccess.readsAsCaller(({ query }) =>
10+
Effect.gen(function* () {
11+
const { thread } = yield* McpInvocationContext.McpInvocationContext.pipe(
12+
Effect.flatMap((scope) => McpInvocationContext.requireThreadScope(scope, "tool_search")),
13+
);
14+
const exposure = yield* McpToolExposure.McpToolExposure;
15+
return { tools: yield* exposure.search(thread.providerSessionId, query) };
16+
}),
17+
),
18+
});
Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
import { OrchestratorMcpFailure } from "@t3tools/contracts";
2+
import * as Schema from "effect/Schema";
3+
import { Tool, Toolkit } from "effect/ai";
4+
5+
import * as McpInvocationContext from "../../McpInvocationContext.ts";
6+
import * as McpToolExposure from "../../McpToolExposure.ts";
7+
8+
const ToolSearchTool = Tool.make(McpToolExposure.TOOL_SEARCH, {
9+
description:
10+
"Load T3 Code tools you do not have yet, then call them by name. Search by name or purpose: threads (t3_thread_*), projects (t3_project_*), worktrees, preview_* browser, device_*, html_preview/html_render, schedule_task, pull requests and guides, attachments, request_secret, environment links. Exact names work too.",
11+
parameters: Schema.Struct({ query: Schema.String.check(Schema.isMaxLength(500)) }),
12+
success: Schema.Struct({
13+
tools: Schema.Array(Schema.Struct({ name: Schema.String, description: Schema.String })),
14+
}),
15+
failure: OrchestratorMcpFailure,
16+
failureMode: "return",
17+
dependencies: [McpInvocationContext.McpInvocationContext, McpToolExposure.McpToolExposure],
18+
})
19+
.annotate(Tool.Readonly, true)
20+
.annotate(Tool.Destructive, false);
21+
22+
export const ToolSearchToolkit = Toolkit.make(ToolSearchTool);

‎apps/server/src/orchestration-v2/Adapters/AcpRegistryAdapterV2.test.ts‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1210,7 +1210,10 @@ describe("AcpRegistryAdapterV2", () => {
12101210
type: "http",
12111211
name: "t3-code",
12121212
url: endpoint,
1213-
headers: [{ name: "Authorization", value: authorization }],
1213+
headers: [
1214+
{ name: "Authorization", value: authorization },
1215+
{ name: "t3-tool-exposure", value: "deferred" },
1216+
],
12141217
},
12151218
];
12161219
const stdio = (authorization: string) => [

‎packages/provider-acp-registry/src/server/adapter.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -253,6 +253,7 @@ export const makeAcpRegistryAdapterV2 = Effect.fn("makeAcpRegistryAdapterV2")(fu
253253
clientCapabilitiesMeta: copilotClientCapabilitiesMeta,
254254
// Copilot CLI 1.0.105 rejects stdio MCP servers from the client.
255255
mcpOverHttp: true,
256+
deferMcpTools: true,
256257
registerExtensions: copilotRouting.registerExtensions,
257258
normalizeSessionUpdate: copilotRouting.normalizeSessionUpdate,
258259
extractSubagentUpdate: extractCopilotSubagentUpdate,

‎packages/provider-acp/src/server/adapter.ts‎

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -333,6 +333,8 @@ export interface AcpAdapterV2Flavor {
333333
EffectAcpSchema.InitializeRequest["clientCapabilities"]
334334
>["_meta"];
335335
readonly mcpOverHttp?: boolean;
336+
/** The agent has no tool search of its own, so T3 lists optional tools on demand. */
337+
readonly deferMcpTools?: boolean;
336338
readonly normalizeSessionUpdate?: (
337339
notification: EffectAcpSchema.SessionNotification,
338340
) => EffectAcpSchema.SessionNotification;
@@ -838,6 +840,7 @@ function acpMcpContext(
838840
session: McpProviderSession.McpProviderSessionConfig | undefined,
839841
self: SelfInvocation,
840842
mcpOverHttp: boolean | undefined,
843+
deferMcpTools: boolean | undefined,
841844
): AcpMcpContext {
842845
if (session === undefined) {
843846
return { servers: [], acpServers: [], httpServers: [] };
@@ -864,7 +867,12 @@ function acpMcpContext(
864867
type: "http",
865868
name: "t3-code",
866869
url: session.endpoint,
867-
headers: [{ name: "Authorization", value: session.authorizationHeader }],
870+
headers: [
871+
{ name: "Authorization", value: session.authorizationHeader },
872+
...(deferMcpTools === true
873+
? [{ name: McpProviderSession.MCP_TOOL_EXPOSURE_HEADER, value: "deferred" }]
874+
: []),
875+
],
868876
},
869877
]
870878
: [],
@@ -1687,10 +1695,14 @@ export const makeAcpAdapterV2 = Effect.fn("makeAcpAdapterV2")(function* (
16871695
const { flavor, selfInvocation: self } = options;
16881696
const readMcpContext = (threadId: ThreadId | null) =>
16891697
threadId === null
1690-
? Effect.succeed(acpMcpContext(undefined, self, flavor.mcpOverHttp))
1698+
? Effect.succeed(acpMcpContext(undefined, self, flavor.mcpOverHttp, flavor.deferMcpTools))
16911699
: mcpSessions
16921700
.read(threadId)
1693-
.pipe(Effect.map((session) => acpMcpContext(session, self, flavor.mcpOverHttp)));
1701+
.pipe(
1702+
Effect.map((session) =>
1703+
acpMcpContext(session, self, flavor.mcpOverHttp, flavor.deferMcpTools),
1704+
),
1705+
);
16941706
const driver = flavor.driver;
16951707
const continuationRequests = options.continuationRequests;
16961708
const postSettleContinuationEnabled =

0 commit comments

Comments
 (0)