Debugging Techniques

Relevant source files

The following files were used as context for generating this wiki page:

• src/container_use_mcp.rs
• README.md
• extension.toml
• configuration/installation_instructions.md
• Cargo.toml

The Container Use MCP extension provides a bridge between the Zed editor and containerized environments via the Model Context Protocol (MCP). Debugging this extension primarily involves verifying the presence and accessibility of the cu binary, ensuring correct configuration of path settings, and validating the communication between Zed and the MCP server.

Understanding these techniques is essential for troubleshooting issues where coding agents fail to access containerized environments or when the extension fails to initialize the context server process.
Sources: README.md:1-5, extension.toml:1-13

Binary Resolution and Path Validation

The most common point of failure is the extension's inability to locate the cu (Container Use) binary. The extension employs a specific search order to resolve the binary path. It first checks for a user-defined custom path in the settings, then falls back to searching the system's PATH.

Binary Path Resolution Logic

The following diagram illustrates how the ContainerUseMcpExtension resolves the command to execute the MCP server.

The extension uses the which command to locate the binary if no custom path is provided.
Sources: src/container_use_mcp.rs:26-53, extension.toml:13-16

Key Resolution Components

Component	Description	Source
cached_binary_path	An internal state variable used to store the verified path to the cu binary.	src/container_use_mcp.rs:17-19
context_server_binary_path	Method responsible for the multi-step lookup logic (Settings -> System PATH).	src/container_use_mcp.rs:21-54
zed::process::Command	API used to execute the shell command which cu to find the binary.	src/container_use_mcp.rs:37-40

Configuration-Based Troubleshooting

Debugging often requires inspecting the settings.json within Zed to ensure the extension is correctly configured. If the binary is installed in a non-standard location, the cu_path must be explicitly defined.

Settings Structure

The extension expects settings in a specific JSON format under the container-use-mcp key.

{
  "context_servers": {
    "container-use-mcp": {
      "settings": {
        "cu_path": "/path/to/cu"
      }
    }
  }
}

Sources: README.md:19-27, src/container_use_mcp.rs:11-15

Verifying Extension State

The extension implements context_server_configuration to provide Zed with metadata about how to configure the server.

fn context_server_configuration(
    &mut self,
    _context_server_id: &ContextServerId,
    _project: &Project,
) -> Result<Option<ContextServerConfiguration>> {
    let installation_instructions =
        include_str!("../configuration/installation_instructions.md").to_string();
    let default_settings = include_str!("../configuration/default_settings.jsonc").to_string();
    let settings_schema =
        serde_json::to_string(&schemars::schema_for!(ContainerUseMcpSettings))
            .map_err(|e| e.to_string())?;

    Ok(Some(ContextServerConfiguration {
        installation_instructions,
        default_settings,
        settings_schema,
    }))
}

Sources: src/container_use_mcp.rs:81-98

Process Execution and STDIO

The extension communicates with the cu binary using the stdio transport. Debugging execution issues involves checking if the process can be spawned with the correct arguments.

Execution Sequence

The context_server_command function prepares the execution environment for the MCP server.

Common Execution Issues

• Path Not Found: If cu is not in the PATH and not provided in settings, the extension returns an error: "Failed to find cu path. Follow the instructions in README.md".
• Permission Denied: If the binary is found but not executable, the fs::metadata(path) check may pass, but the process spawn by Zed will fail.
• Missing Agent Rules: Coding agents may fail to behave correctly if the .rules file is missing from the project root. This can be fixed by running: curl -o .rules https://raw.githubusercontent.com/dagger/container-use/main/rules/agent.md.

Sources: src/container_use_mcp.rs:52, README.md:30-34, configuration/installation_instructions.md:1-1

Summary of Debugging Data Structures

The following table summarizes the primary data structures used to manage the extension's execution state, which should be the focus of debugging efforts.

Structure	Usage	Fields
ContainerUseMcpSettings	Deserialized user configuration.	cu_path: Option<String>
ContainerUseMcpExtension	Main state holder for the extension.	cached_binary_path: Option<String>
Command	The output structure defining how to run the server.	command: String, args: Vec<String>, env: Vec<String>

Sources: src/container_use_mcp.rs:11-19, src/container_use_mcp.rs:76-80

Effective debugging of the Container Use MCP extension requires a verified installation of the cu binary and proper path configuration within Zed. By validating the binary resolution logic and ensuring the project contains the necessary agent rules, developers can ensure a stable bridge to containerized environments.