Zero-Context Discovery
Relevant source files
The following files were used as context for generating this wiki page:
Zero-Context Discovery is a mechanism designed to optimize Large Language Model (LLM) performance by drastically reducing initial context window usage. Instead of pre-loading hundreds of tool schemas from multiple Model Context Protocol (MCP) servers, which can consume upwards of 30,000 tokens, this bridge implementation maintains a constant 200-token overhead. It achieves this by exposing only a single tool, run_python, and requiring the LLM to discover and hydrate specific tool schemas on demand during code execution.
Sources: README.md:14-17, README.md:79-92, ARCHITECTURE.md:88-92
This "discovery-first" architecture shifts the responsibility of tool management from the initial prompt to the runtime execution phase. The LLM uses specialized sandbox helpers within its generated Python code to list available servers, search for specific capabilities, and query full documentation only for the tools it intends to use.
Sources: README.md:46-75, mcp_server_code_execution_mode.py:118-124
Architecture and Data Flow
The discovery process involves a multi-stage communication flow between the host bridge and the sandboxed container. The host maintains a persistent pool of MCP clients and a cache of server metadata, which it serves to the sandbox via a JSON-framed stdio bridge.
Sources: ARCHITECTURE.md:18-42, mcp_server_code_execution_mode.py:1022-1065
Discovery Pipeline
The following diagram illustrates the lifecycle of a discovery request from the LLM through the sandbox to the host bridge:
Key Discovery Components
Sandbox Discovery Helpers
The mcp.runtime module, injected into the container sandbox at startup, provides synchronous and asynchronous functions for interacting with the discovery system.
Sources: mcp_server_code_execution_mode.py:649-808, GUIDE.md:214-250
| Helper Function | Type | Description |
|---|---|---|
discovered_servers(detailed=False) | Sync | Returns a tuple of server names or a list of server/description dicts. |
list_servers() | Async | Performs an RPC call to the host to list all selectable servers. |
query_tool_docs(server, tool=None, detail="summary") | Async | Fetches tool documentation. detail can be "summary" or "full". |
search_tool_docs(query, limit=5, detail="summary") | Async | Performs a fuzzy search across loaded servers for specific capabilities. |
describe_server(name) | Sync | Returns cached metadata for a specific server, including its cwd. |
capability_summary() | Sync | Returns a high-level summary of the sandbox and its discovery capabilities. |
| Sources: mcp_server_code_execution_mode.py:734-808, GUIDE.md:395-442 |
Host-Side Metadata Management
The MCPBridge class manages the lifecycle of metadata. It automatically discovers server configurations from various system paths (e.g., ~/.config/mcp/servers/, ~/.claude.json) and caches their tool definitions upon the first request.
Sources: mcp_server_code_execution_mode.py:1171-1250, ARCHITECTURE.md:77-80
Implementation Details
Metadata Schema
When the host queries an MCP server for discovery, it sanitizes tool names into Python-compatible identifiers and stores them in a structured cache.
Sources: mcp_server_code_execution_mode.py:1330-1380
# mcp_server_code_execution_mode.py:1372-1377
metadata = {
"name": server_name,
"alias": alias,
"tools": tools,
"cwd": cwd_value,
}
Search Logic
The discovery system supports keyword-based fuzzy searching across all loaded servers. The search logic tokenizes the user query and matches it against a pre-built index of server names, aliases, tool names, and tool descriptions.
Sources: mcp_server_code_execution_mode.py:1463-1490, tests/test_entrypoint.py:236-248
Workflow Example: Two-Stage Discovery
- Enumeration: The LLM calls
mcp.runtime.discovered_servers()to see what resources are available. - Targeting: Based on descriptions, the LLM selects a server (e.g., "filesystem").
- Hydration: The LLM calls
mcp.runtime.query_tool_docs("filesystem", detail="full")to get the exact JSON schema for its arguments. - Execution: The LLM writes Python code using the
mcp_filesystemproxy to perform tasks.
Sources: README.md:94-100, GUIDE.md:200-212
Summary
Zero-Context Discovery allows the project to scale to hundreds of MCP servers without impacting LLM context window efficiency. By utilizing a "discovery-first" approach mediated by the mcp.runtime helper module and host-side metadata caching, the system ensures that complex tool schemas are only transferred to the LLM when strictly necessary.
Sources: README.md:86-92, STATUS.md:14-25