Pull Request Description

Where did you find this issue?

Code mode has two executors (local VM and E2B) and a documented discovery helper, search_tools(). The VM executor and the searchTools() API return a ToolSearchResponse:

{ meta: { total_tools: number; namespaces: string[]; result_count: number }, results: ToolSearchResult[] }

The E2B executor's shim returned a bare array, and the exported CODE_MODE_AGENT_PROMPT iterates it as an array:

// VM
const tools = await search_tools("github");   // { meta: {...}, results: [...] }
for (const tool of tools) { … }               // TypeError: tools is not iterable

// E2B
const tools = await search_tools("github");   // [ { name, server, description, input_schema }, … ]
for (const tool of tools) { … }               // works

So a snippet written the way the prompt (and the docs) show runs on E2B and fails on the VM, and meta is unavailable on E2B. The E2B shim also only matched the query against a tool's name and description, while the VM path also matches the server name.

Reproduced on main (8d8034e) with the tests in this PR (all three fail before the change).

Language / Project Scope

• TypeScript

Changes

• E2BCodeExecutor.generateShim() now emits a search_tools() that returns the same { meta, results } envelope as BaseCodeExecutor.createSearchToolsFunction() and searchTools() — for every detail level, with total_tools, sorted namespaces and result_count, and server-name matching in the query.
• The shim keeps searching the full tool records before projecting to the requested detail level (its existing order). fix(client): preserve description matches in names-only tool search #2728 applies the same order to the VM executor; on main today the VM still projects first, so a description-only match at the names level is currently found on E2B but not on the VM — that gap closes when fix(client): preserve description matches in names-only tool search #2728 lands, and this PR deliberately keeps E2B's behavior instead of copying the bug.
• CODE_MODE_AGENT_PROMPT examples read results (and destructure it) instead of iterating the return value.
• docs/typescript/api-reference/client/code-mode.mdx states that the in-sandbox helper returns the same { meta, results } envelope on both executors, and that which tools a query matches can still differ until fix(client): preserve description matches in names-only tool search #2728 lands.
• Four parity tests in packages/client/tests/unit/client/code-mode-search-tools-parity.test.ts: three compare the shim's output with the VM implementation directly, and one asserts the search-then-project order that fix(client): preserve description matches in names-only tool search #2728 gives the VM.
• Changeset: @mcp-use/client minor — the E2B helper's return shape changes for anyone who used the old array form.

Implementation Details

• meta.total_tools counts all tools in the catalog (not the filtered list), meta.namespaces is the sorted list of servers that have tools, and meta.result_count is the filtered length — copied from createSearchToolsFunction() so the two implementations stay comparable. The code_mode self-server is already excluded by getToolNamespaces(), which feeds both paths.
• The detail levels keep their per-entry shape (names → {name, server}, descriptions → {name, server, description}, full → the full record with input_schema); only the envelope is added.
• No API or type change for searchTools(); the shim now matches the type it already documented.
• This complements fix(client): expose the sanitized server alias in the VM code executor #2964 (server-name alias parity on the VM executor): both make a code-mode snippet behave the same on either executor.

Coordination with other open PRs

• fix(client): preserve description matches in names-only tool search #2728 (preserve description matches in names-only tool search) changes the VM to search full records before projecting. This PR keeps E2B on that same order, so the two agree once fix(client): preserve description matches in names-only tool search #2728 merges; today the VM still projects first, which is the single intentional difference between the executors (a description-only match at the names level). No change is needed here after fix(client): preserve description matches in names-only tool search #2728.
• feat(client): add Jev tool routing and MCP firewall #2581 touches the same global.search_tools shim (its hunk does not apply on this commit). Its Jev early-return emits response.results (a bare array); it should return the same { meta, results } envelope to avoid reintroducing the inconsistency this PR removes.
• Small behavior change worth calling out: search_tools(null) now throws (like the VM), where the old shim returned every tool because it only tested !query inside the filter. undefined/omitted still returns everything.

TypeScript Checklist

Packages Modified

• docs
• tests
• cli
• create-mcp-use-app
• mcp-use (server)
• mcp-use (client)
• inspector

Pre-commit Checklist

• Ran pnpm lint:fix / eslint on the changed files
• Ran pnpm format (Prettier)
• Ran pnpm build and it succeeds (@mcp-use/client)
• Ran pnpm changeset
• Added tests
• Updated documentation

Example Usage (Before)

// E2B executor
const tools = await search_tools("github");
console.log(tools.map(t => t.name));      // works — array
console.log(tools.meta.result_count);     // undefined

// VM executor
const tools = await search_tools("github");
for (const tool of tools) { … }           // TypeError: tools is not iterable

Example Usage (After)

// both executors
const { results, meta } = await search_tools("github");
for (const tool of results) { … }
console.log(meta.result_count);

Testing

• New: packages/client/tests/unit/client/code-mode-search-tools-parity.test.ts — 4 tests on the evaluated E2B shim: default query, server-name match and all three detail levels compared with VMCodeExecutor.createSearchToolsFunction(), plus the search-then-project order (found at the names level; not compared with today's VM, see fix(client): preserve description matches in names-only tool search #2728). All four fail on 8d8034e and pass with the change.
• Full client unit suite: 423 passed, 1 skipped.
• tsc --noEmit, eslint, prettier: clean. pnpm --filter @mcp-use/client build: success.

Backwards Compatibility

The E2B search_tools() helper's return value changes from an array to the { meta, results } object that the VM executor, searchTools() and the API docs already describe. A snippet that iterated the array directly must read .results; snippets written against the prompt examples already do after this change. The changeset is marked minor for that reason.

Related Issues

No existing issue covers this. Related open PRs: #2964 (the same executor-parity class of bug for server namespaces) and #2728 (VM side of the search-then-project order).