Tool Creator

Implementation guide for Mithril MCP server execution tools.

Overview

Each tool wraps a single command (POSIX, git, etc.) as a structured MCP tool. Tools are never shell strings - they build typed argument vectors validated before execution.

File Placement

Tool lives in crates/tools/src/<category>/<tool_name>.rs where category groups related commands:

PascalCase tool name, snake_case file name: GitStatus -> git/git_status.rs.

Register in crates/tools/src/<category>/mod.rs with pub mod <tool_name>;.

Pre-Implementation Verification

Before writing any code, verify the tool's CLI interface and sandbox compatibility. This section applies only to tools that wrap a CLI command — skip it for general-purpose tools like RunChain that implement execution logic rather than wrapping a binary.

1. CLI interface check

Run <cmd> --help (or <cmd> <subcommand> --help) to get the up-to-date flag reference. Use this output — not memory or documentation — to decide which arguments to expose in the Args struct.

# Examples
grep --help
git diff --help
cargo clippy --help

Cross-check the flag names, short forms, and value types against the help output before writing the parameters() JSON schema. Mismatches between the schema and the real CLI are the most common source of CmdError in tests.

2. Version check

Run <cmd> --version to confirm the developer has a recent version installed:

go version       # → go1.22.0 or newer
cargo --version  # → cargo 1.78.0 or newer

If the installed version is notably old (e.g. Go < 1.21, Cargo < 1.70), inform the developer to upgrade for reliable testing. If the command is not found at all, the tool should declare available() returning false (see ToolDef section below).

Trust --help over documentation or memory. Real CLI interfaces diverge from docs frequently. Common divergences found in this project:

Always run <cmd> <subcommand> --help and build the Args struct from that output.

3. Sandbox compatibility analysis

Read the sandbox implementations in crates/sandbox/src/linux.rs (BubbleWrap) and crates/sandbox/src/darwin.rs (sandbox-exec) to reason about whether the command can execute correctly under each sandbox level:

For each tool, answer:

• Does the command need to write outside cwd? (e.g. cargo check writes to ~/.cargo/registry) → needs rw_binds in SandboxMeta
• Does it need network access? (e.g. pip install, go get) → needs needs_network: true
• Does it need read access to config outside /usr and /etc? (e.g. ~/.cargo/config.toml, ~/.npmrc) → needs ro_binds
• Is the tool read-only? (e.g. cat, ls, git log) → should work at Readonly level
• Is the tool mutating? (e.g. rm, sed, git commit) → Readonly must be rejected; set elicitable() -> true

This analysis informs both the SandboxMeta population in build_context() and the sandbox level used in tests.

Implementation Structure

Every tool file contains exactly three items:

1. Unit struct + Args struct

pub struct ToolName;

#[derive(Debug, Deserialize, Serialize, JsonSchema)]
pub struct ToolNameArgs {
    /// Required arg description.
    pub arg: String,
    /// Optional flag description (-f).
    pub flag: Option<bool>,
}

Argument budget: 5-10 max. Only include args that AI coding agents use frequently or that are essential for regular use. Skip obscure flags.

2. ToolDef implementation

impl ToolDef for ToolName {
    fn name(&self) -> Cow<'static, str> {
        Cow::Borrowed("ToolName")  // PascalCase, matches MCP tool name
    }

    fn description(&self) -> Cow<'static, str> {
        Cow::Borrowed("Short description for LLM context")
    }

    fn parameters(&self) -> Value {
        serde_json::json!({
            "type": "object",
            "properties": {
                "arg": {
                    "type": "string",
                    "description": "Arg description"
                },
                "flag": {
                    "type": "boolean",
                    "description": "Flag description (-f)"
                }
            },
            "required": ["arg"]
        })
    }

    // Override ONLY when needed:

    fn elicitable(&self) -> bool {
        true  // Tools that mutate project state (Rm, Mv, Sed, Patch, Touch, GitCommit...)
    }

    fn available(&self) -> bool {
        which::which("tool_binary").is_ok()  // Third-party or non-guaranteed commands
    }
}

Binary name fallback

Some tools have different binary names across Linux distros. Debian/Ubuntu renames tools to avoid conflicts:

Implement fallback with a helper function:

fn bat_binary() -> &'static str {
    if which::which("bat").is_ok() {
        "bat"
    } else {
        "batcat"
    }
}

impl ToolDef for Bat {
    fn available(&self) -> bool {
        which::which("bat").is_ok() || which::which("batcat").is_ok()
    }
    // ...
}

impl ToolExec for Bat {
    async fn build_context(&self, args: BatArgs, ctx: &mut ExecContext) {
        ctx.cmd.push(OsString::from(bat_binary()));
        // ...
    }
}

For pip, use the shared helper in crates/tools/src/python/mod.rs:

pub(crate) fn pip_bin() -> &'static str {
    if which::which("pip3").is_ok() { "pip3" } else { "pip" }
}

Always check the preferred name first, then fall back to the alternative.

**`parameters()` JSON schema must match `ToolNameArgs` field names and types exactly.** The schema is what the LLM sees; the struct is what gets deserialized.

### 3. `ToolExec` implementation

```rust
#[async_trait]
impl ToolExec for ToolName {
    type Args = ToolNameArgs;

    async fn build_context(&self, args: ToolNameArgs, ctx: &mut ExecContext) {
        // 1. Push binary name
        ctx.cmd.push(OsString::from("tool_binary"));

        // 2. Push flags from bool args
        if args.flag.unwrap_or(false) {
            ctx.cmd.push(OsString::from("-f"));
        }

        // 3. Push valued args
        if let Some(ref val) = args.optional_arg {
            ctx.cmd.push(OsString::from("--option"));
            ctx.cmd.push(OsString::from(val));
        }

        // 4. Push positional args last
        ctx.cmd.push(OsString::from(&args.arg));

        // 5. Populate sandbox metadata (when the tool needs special access)
        //    Set needs_network for commands that fetch from registries.
        //    Add ro_binds / rw_binds for config and cache dirs outside cwd.
        if let Some(home) = std::env::var_os("HOME").map(PathBuf::from) {
            ctx.sandbox.meta.ro_binds.push(home.join(".config/tool"));
            ctx.sandbox.meta.rw_binds.push(home.join(".cache/tool"));
        }
        ctx.sandbox.meta.needs_network = true; // only if the command fetches

        // 6. Register validation rules (CRITICAL - see below)
        ctx.tool.validation_rules.insert(
            "arg",
            ValidationRule::PathConfined {
                pattern: StringPattern::NON_EMPTY | StringPattern::NO_PATH_TRAVERSAL,
                melody: Some(patterns::MELODY_UNIX_PATH),
                allow_git: false,
            },
        );
    }
}

Sandbox Metadata

Tools that need resources beyond what the sandbox level provides must populate ctx.sandbox.meta in build_context(). The sandbox layer reads this metadata to add bind-mounts (Linux/bwrap) or SBPL rules (macOS/sandbox-exec).

Rules:

• rw_binds are only honoured under Dir and Container levels — Readonly ignores them.
• rw_binds outside $HOME are silently rejected by both sandbox backends.
• Read-only tools (e.g. cat, ls, git log) should leave SandboxMeta at its default.
• Guard bind paths with if let Some(home) = std::env::var_os("HOME") — don't assume $HOME exists.
• Include macOS-specific cache paths alongside Linux ones. macOS uses ~/Library/Caches/<tool> instead of ~/.cache/<tool>. Add both in the same helper.

Reference the ecosystem-specific meta helpers in crates/sandbox/src/linux.rs tests (pip_meta(), npm_meta(), cargo_meta(), go_meta()) for canonical bind-mount sets.

Shared sandbox meta helpers

Domain mod.rs files provide reusable meta helpers. Use these instead of inlining bind-mount logic in each tool.

When adding a new tool to an existing domain, call the domain's meta helper:

// In git tool's build_context():
super::apply_git_meta(&mut ctx.sandbox.meta);

// In docker tool's build_context():
super::apply_docker_meta(&mut ctx.sandbox.meta);

// In pip tool's build_context():
super::apply_pip_meta(&mut ctx.sandbox.meta, true /* needs_network */);

When creating a new domain that needs shared sandbox config, add a helper in the domain's mod.rs following this pattern:

pub(crate) fn apply_example_meta(meta: &mut SandboxMeta) {
    if let Some(home) = std::env::var_os("HOME").map(PathBuf::from) {
        meta.ro_binds.push(home.join(".config/example"));
        meta.rw_binds.push(home.join(".cache/example"));
        // macOS cache location
        meta.rw_binds.push(home.join("Library/Caches/example"));
    }
}

Validation Rules - The Critical Part

Every non-bool argument MUST have a validation rule. Only register rules for args present in ctx.args (optional args guard with if ctx.args.contains_key("field")).

Rule selection guide

Injection guard exemption

exempt_injection_guard: false (default, strict) blocks shell metacharacters ($, `, |, ;, etc.).

Set exempt_injection_guard: true ONLY when the argument semantically requires those characters:

• Grep/sed patterns ($, *, ., ^)
• Commit messages (free-form text)
• Awk programs

When in doubt, keep exempt_injection_guard: false.

Melody patterns

• patterns::MELODY_UNIX_PATH - for file/directory path arguments
• patterns::MELODY_CMD_NAME - for command/binary name arguments

Environment Variable Security

The validator blocks dangerous environment variables via ENV_BLOCKLIST in crates/validator/src/constants.rs. Key rules:

• Both LD_* and DYLD_* are blocked unconditionally — never use #[cfg(target_os)] guards on security-relevant blocklists. A cross-compiled binary must still block the other platform's dangerous variables.
• The envs global arg allows tools to inject environment variables, but the validator rejects any that match the blocklist before execution.
• When a tool needs cache/config redirection (e.g. GOPATH, PIP_CACHE_DIR), these are safe to inject via envs because they don't appear in the blocklist.

Path Validation for Non-Existing Files

The validator's path confinement uses resolve_path() which handles files that don't exist yet:

fn resolve_path(path: &OsStr) -> io::Result<PathBuf> {
    match fs::canonicalize(path) {
        Ok(canon) => Ok(canon),
        Err(_) => {
            let parent = p.parent().unwrap_or(p);
            let name = p.file_name().unwrap_or_default();
            Ok(fs::canonicalize(parent)?.join(name))
        }
    }
}

This means path arguments for tools that create files (Touch, Tee, redirected output) will pass validation as long as the parent directory exists and is within the confined path. No special handling needed in build_context().

Router Wiring

After the tool implementation is reviewed, wire it in crates/server/src/router.rs:

1. Add import

use tools::system::tool_name::{ToolName, ToolNameArgs};
// or for a new category:
use tools::git::git_status::{GitStatus, GitStatusArgs};

2. Add endpoint method

#[tool(name = "ToolName", description = "Description matching ToolDef")]
async fn tool_name(
    &self,
    Parameters(tool_args): Parameters<ToolArgs<ToolNameArgs>>,
    req_ctx: RequestContext<RoleServer>,
) -> Result<CallToolResult, McpError> {
    self.exec_tool(&ToolName, tool_args, req_ctx).await
}

The #[tool] macro name must match ToolDef::name(). Description should match or closely mirror ToolDef::description().

Writing Tests

Every tool must have at least two tests in crates/server/tests/tools/<category>.rs. Tests exercise the tool through the full MCP pipeline (validation → proxy → sandbox → runner) using TestClient.

Test infrastructure

use serde_json::json;

use crate::{
    harness::{TempEnv, TextExtractor},
    tools::client_with_root,
};

• TempEnv — creates an isolated temporary directory under /var/tmp/mithril_tests (avoids collision with bwrap's --tmpfs /tmp). Chain .with_file(path, content).await to scaffold files.
• client_with_root(&cwd) — creates a TestClient with the given path as the project root.
• TextExtractor::from_tool_result(&result) — extracts text content from the tool result for assertions.

Availability guard

If the tool wraps a binary that may not be installed, add a guard function and early-return:

fn tool_available() -> bool {
    std::process::Command::new("tool_binary")
        .arg("--version")
        .stdout(Stdio::null())
        .stderr(Stdio::null())
        .status()
        .map(|s| s.success())
        .unwrap_or(false)
}

#[tokio::test]
async fn tool_does_something() {
    if !tool_available() {
        return;
    }
    // ...
}

Sandbox level in tests

The sandbox field in GlobalArgs controls the isolation level per-call. Pass it in the JSON args:

// Read-only tool → test at Readonly level
client.call_tool("Cat", json!({
    "path": path.to_str().unwrap(),
    "sandbox": "readonly",
}), Some(&cwd)).await

// Mutating tool → test at Dir level (default)
client.call_tool("Rm", json!({
    "path": path.to_str().unwrap(),
}), Some(&cwd)).await

// Tool that should work in full isolation → test at Container level
client.call_tool("GoBuild", go_args(&cwd, json!({
    "sandbox": "container",
})), Some(&cwd)).await

Sandbox level selection for tests:

Environment variables for ecosystem tools

Some tools need environment variables pointing caches inside cwd so they work under sandbox. Follow the Go test pattern:

fn tool_args(cwd: &std::path::Path, extra: Value) -> Value {
    let cache = cwd.join(".tool_cache");

    let mut map = match extra {
        Value::Object(m) => m,
        _ => serde_json::Map::new(),
    };

    map.insert(
        String::from("envs"),
        json!({ "TOOL_CACHE": cache.to_string_lossy() }),
    );

    Value::Object(map)
}

What to test

Each tool needs at least two tests. Prefer a mix of:

1. Happy-path execution — call the tool with commonly-used arguments that AI coding agents would use in production. Assert !result.is_error.unwrap_or(false) and check the output contains expected content.
2. Validation rejection — pass an invalid argument (empty string, zero integer, invalid enum value) and assert result.is_err().

Additional tests to consider:

• Different argument combinations that agents use frequently
• Ecosystem detection (tool fails gracefully without the expected project file, e.g. go.mod, Cargo.toml)

Auth-gated tools

Tools that require authentication (like gh, glab) cannot run happy-path tests in CI. For these, test only validation rejections — invalid arguments should be caught by the validation layer before any CLI execution or auth check occurs.

Diagnosing CmdError

When a test returns CmdError(...):

1. Wrong CLI flags — the most common cause. Re-check <cmd> --help output against the args struct. A flag may have been renamed, removed, or may require a different value format.
2. Sandbox resource denial — the command tried to access a path not available at the test sandbox level. Check whether the tool needs additional ro_binds / rw_binds in its SandboxMeta, or whether environment variables should redirect caches inside cwd.
3. Missing environment variables — some tools need HOME, PATH, or tool-specific vars. Use the envs global arg or isolated_env: false (default) to inherit the host environment.
4. Missing project scaffolding — the TempEnv may be missing required files (e.g. go.mod, Cargo.toml, package.json). Add them via .with_file().

Test file registration

Add the test module in crates/server/tests/tools/mod.rs:

pub mod <category>;  // e.g. pub mod docker;

If the tool belongs to an existing category (e.g. a new git tool → git.rs), add tests to the existing file under a new section header comment.

Checklist

Pre-implementation (CLI tools only)

• Ran <cmd> <subcommand> --help to verify up-to-date CLI flags (trust --help, not docs/memory)
• Ran <cmd> --version to confirm a recent version is installed
• Analyzed sandbox levels (Dir/Readonly/Container) for resource compatibility
• Checked if binary has alternative names across distros (bat/batcat, fd/fdfind, pip3/pip)

Implementation

• File at crates/tools/src/<category>/<tool_name>.rs
• Registered in <category>/mod.rs
• Args struct with 5-10 max fields, doc comments on each
• ToolDef: name (PascalCase), description, parameters JSON schema matches args struct
• elicitable() -> true if tool mutates project state
• available() uses which::which() if command isn't guaranteed on PATH; checks all binary name variants with ||
• Binary name fallback helper if distro-specific names exist
• build_context(): cmd vector built in correct order (binary, flags, options, positionals)
• ctx.sandbox.meta populated via domain meta helper (e.g. apply_git_meta, apply_pip_meta) or inline if new domain
• macOS cache paths included alongside Linux ones (~/Library/Caches/<tool> + ~/.cache/<tool>)
• Every non-bool arg has a validation rule with appropriate strictness
• exempt_injection_guard is true only where semantically required
• Path args for mutating tools include NO_GIT_COMPONENT
• Router endpoint added in crates/server/src/router.rs
• #[tool] name matches ToolDef::name()

Tests

• At least 2 tests in crates/server/tests/tools/<category>.rs
• Tests use TempEnv for isolated temp environment with required project files
• Read-only tools tested with "sandbox": "readonly" in args
• Container-compatible tools tested with "sandbox": "container" where feasible
• Ecosystem tools redirect caches inside cwd via envs to avoid sandbox denials
• Auth-gated tools test only validation rejections (no happy-path execution)
• Docker tools use docker info (not --version) in availability guard
• Sandbox test names include ecosystem name with underscores for CI filtering (e.g. _pip_, _cargo_)
• Test module registered in crates/server/tests/tools/mod.rs (if new category)