Skip to main content
Glama
unified-mcp-server

unified-mcp-server

by waxz
README.md
# unified-mcp-server

A self-contained MCP server with file editing and shell execution in one
process, one endpoint and one config file. It has 58 tools:

| Family | Tools |
|---|---|
| Files | read/write/create/copy/move/delete, search & replace, `patch_file`, `apply_patch` with preview → confirm → apply (plus a browser review page over HTTP), `get_file_info` |
| Git | status, init, clone, add, commit, push, pull, log, branch, checkout, diff, remote |
| Code analysis | tree-sitter `list_functions`, `get_function_at_line`, `get_code_structure`, `search_functions` |
| Linting | `detect_linters`, `run_linter`, `lint_file`, `run_type_checker`, `type_check_file`, `format_file` |
| Remote | `ssh_upload`, `ssh_download`, `ssh_sync`, SSH project directories |
| Project | `set_project_directory`, `get_project_directory` |
| Shell | `execute_command` (streamed output), `list_trusted_commands`, process list/terminate, tmux sessions |

The code started as two separate servers,
[mcp-file-edit](https://github.com/waxz/mcp-file-edit) and
[shell-mcp-server](https://github.com/waxz/shell-mcp-server). It is copied
into this package and maintained here; neither project is a dependency.

**New here? See [docs/USAGE.md](docs/USAGE.md)** for recommended setup, how to
run and approve shell commands, keeping secrets away from the model, and
upgrading/restarting safely.

## Install

One line installs [uv](https://docs.astral.sh/uv/) (which fetches Python 3.12
if needed) and then the `unified-mcp-server` command. Git is not required.

**Ubuntu / Linux / macOS**

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh && ~/.local/bin/uv tool install --python 3.12 "unified-mcp-server @ https://github.com/waxz/unified-mcp-server/archive/refs/heads/main.zip"
```

**Windows (PowerShell)**

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"; & "$env:USERPROFILE\.local\bin\uv.exe" tool install --python 3.12 "unified-mcp-server @ https://github.com/waxz/unified-mcp-server/archive/refs/heads/main.zip"
```

The command is installed in `~/.local/bin` (`%USERPROFILE%\.local\bin` on
Windows). If `unified-mcp-server` isn't found afterwards, open a new terminal or
run `uv tool update-shell`.

**Update** (reinstalls from `main`, then restarts your running HTTP servers in
place: same process, terminal and arguments, new code):

```bash
unified-mcp-server --update
```

`--update <branch|tag|commit>` installs another version, `--no-restart` only
reinstalls, `--version` prints the installed version. You can also restart a
running server in place with `kill -HUP <pid>`. Remove with
`uv tool uninstall unified-mcp-server`.

On Windows the shell tools run commands through PowerShell (`bash` maps to
`powershell.exe`) and the tmux tools are unavailable. CI runs on Ubuntu only.

From a checkout, for development:

```bash
uv venv && uv pip install -e ".[dev]"
```

## Run

stdio (Claude Desktop, Claude Code):

```bash
unified-mcp-server -w /path/to/project
```

```bash
claude mcp add unified -- unified-mcp-server -w /path/to/project
```

HTTP:

```bash
unified-mcp-server -c config.toml -t http -H 127.0.0.1 -P 8000 -p /mcp
```

### CLI

| Flag | Meaning |
|---|---|
| `-c/--config` | TOML config. Optional (see below) |
| `--init-config [PATH]` | write a commented config template to PATH (default `config.toml`, `-` prints it) and exit; `--force` overwrites |
| `-t/--transport` | `stdio` or `http` |
| `-H/--host`, `-P/--port`, `-p/--path` | HTTP bind settings |
| `-w/--workdir` | project directory |
| `-d/--directories` | allowed root directories |
| `--shell NAME PATH` | shell mapping for shell tools (repeatable) |
| `--namespaced` | prefix tools with `fs_` / `shell_` |
| `--no-files` / `--no-shell` | disable one family |
| `--api-key KEY` | API key for HTTP clients (repeatable; replaces `API_KEYS`) |
| `--command-timeout SECONDS` | shell command timeout (`COMMAND_TIMEOUT`) |
| `--safety-mode strict\|relax` | shell safety mode (`SAFETY_MODE`) |
| `--public-url URL` | base URL for patch-preview links (`PUBLIC_URL`) |
| `--in-docker` | server runs in a container; run commands directly (`IS_IN_DOCKER`) |
| `--no-approval` | refuse untrusted commands instead of asking you (`APPROVE_UNTRUSTED = false`) |
| `PROTECTED_PATHS` (config only) | files/folders the file tools must never touch; the loaded config file is always protected |
| `COMMAND_TIMEOUT_MAX` (config only) | largest per-call `timeout` for `execute_command` (default 600) |
| `--approval-timeout SECONDS` | how long an approval request stays open (`APPROVAL_TIMEOUT`, default 600) |
| `--approval-wait SECONDS` | how long one tool call waits before returning "pending" (`APPROVAL_WAIT`, default 25) |
| `--dashboard-token TOKEN` | fixed approvals-dashboard token so its link is stable across restarts (`APPROVALS_DASHBOARD_TOKEN`) |
| `--sandbox MODE` | how untrusted commands are sandboxed: `none`/`bubblewrap`/`docker` (`SANDBOX`) |
| `--sandbox-network allow\|none` | whether a sandboxed command has network (`SANDBOX_NETWORK`) |
| `--update [REF]` | reinstall from GitHub (default `main`), restart running HTTP servers in place, exit; `--no-restart` to skip the restart |
| `--version` | print the installed version |
| `--allow-host-tmux-input` | let `tmux_send_keys` type into host sessions (`ALLOW_HOST_TMUX_INPUT`; runs arbitrary commands) |

Precedence: installed default config → your config file → CLI flags.
Environment variables are not read.

A config file is optional. Which one is used:

- `-c FILE` that exists: that file.
- `-c FILE` that doesn't exist: a warning names the missing file, and the
  installed default config is used.
- no `-c`: `./config.toml` if it exists, otherwise the installed default config.

So a quick HTTP server with a key needs no file at all:

```bash
unified-mcp-server -t http -H 127.0.0.1 -P 8000 -p /mcp --api-key change-me
```

Arguments are visible to other users on the same machine (for example in
`ps`), so on shared machines put `API_KEYS` in a config file instead of using
`--api-key`. Trusted shell commands can only be defined in a config file.

## Configuration

Generate a starting config with every option documented:

```bash
unified-mcp-server --init-config            # writes ./config.toml
unified-mcp-server -c config.toml -t http
```

The template fills in a freshly generated API key, so the file is created
readable by you only (mode 600). It won't overwrite an existing file unless
you pass `--force`. `--init-config -` prints the template instead.

Config files written for either original project use the same format and load
as they are, as long as the directories they name exist on this machine. Keys
this server doesn't know are logged and ignored.

- **Project directory.** `[CONFIG.<os>] work_dir` / `-w` sets the root for
  file tools. Unless `[DOCKER_CONFIG.<os>] host_root` is set, shell commands
  with `cwd="."` run there too, and follow `set_project_directory`. Allowed
  roots are shared the same way.
- **Auth.** `API_KEYS = "k1,k2"` protects every tool call over HTTP. Send
  `Authorization: Bearer <key>` or `x-api-key: <key>`. Keys are compared in
  constant time and never echoed back. stdio has no headers, so keys are
  ignored there.

### Shell execution model

- `TRUSTED_COMMANDS` run directly on the host, by name:
  `execute_command(command="t_test", cwd=".")`.
- Any other command, when no sandbox is configured, needs **your approval**
  (`APPROVE_UNTRUSTED = true`, the default). Answer wherever is handiest:
  - **Approvals dashboard** (HTTP): the server prints its link once at
    startup. Keep the tab open: it lists every waiting request, updates by
    itself, shows the count in the tab title, and lets you revoke commands
    you allowed earlier. The link changes on every restart.
  - **Your MCP client's prompt**, if it supports MCP elicitation: *Submit*
    allows the command once (tick the checkbox to allow it until restart),
    *Decline* denies it. The client draws those buttons; the server only adds
    the checkbox.
  - **A per-request link** printed in the server log with each request.

  Answers: **Allow once**, **Allow until restart** (the same command, shell
  and working directory then run without asking until the server restarts),
  or **Deny**. Nothing is written to `config.toml`.

  A request stays open for `APPROVAL_TIMEOUT` seconds (default 600). A tool
  call waits up to `APPROVAL_WAIT` seconds (default 25) for your answer; if
  you haven't answered yet it returns "approval pending" without running
  anything, and the model calls again with the same arguments once you have.
  While your client is showing its own prompt, the call waits for that answer
  instead.

  Links carry random tokens and appear only in the server's log, never in what
  the model sees, so the model can't approve its own requests. Keep that log
  outside the folders the file tools can read. The working directory must
  still be inside the allowed roots. `--no-approval` refuses untrusted
  commands instead. Over stdio with a client that can't show prompts there is
  no way to approve, so the command is refused; use `TRUSTED_COMMANDS` there.
- With a **sandbox** configured (`SANDBOX`), untrusted commands run in it
  instead of asking for approval. The server builds the sandbox itself, and
  there is **one filesystem path space**: the sandbox binds the project
  directory at the *same* path, so a command sees the same paths inside and
  out (no host/container mapping).
  - `SANDBOX = "bubblewrap"` (Linux; needs the `bubblewrap` package): the
    whole filesystem read-only except the project directory, a private
    `/tmp`, and its own user/pid/ipc/net namespaces. No Docker, no daemon,
    no helper script.
  - `SANDBOX = "docker"`: a throwaway `docker run --rm` container with only
    the project directory mounted, as the current user, optionally with
    `DOCKER_SANDBOX_CPUS` / `DOCKER_SANDBOX_MEMORY` caps.
  - `SANDBOX_NETWORK = "none"` cuts network inside the sandbox (default
    `"allow"`).
  The command is passed to `bwrap`/`docker` as a single argument, never
  interpolated into a shell, so there is no outer-shell injection. If the
  chosen sandbox's tool is missing the server refuses to start (fail closed).
  Unset, `SANDBOX` is `"none"` (approval).
- Set `IS_IN_DOCKER = true` when the server itself runs inside a container:
  every command then runs directly in it.
- On Windows there is no built-in sandbox (`bubblewrap` and `docker` need a
  Linux host), so an untrusted command is gated by the **same approve/decline
  flow as on Linux**: it runs only after you allow it (in your client's prompt
  or on the approvals dashboard), and is refused if approvals are off
  (`--no-approval`). Add it to `TRUSTED_COMMANDS` to skip the prompt. Setting
  `SANDBOX = "docker"` on Windows is rejected at startup so a command can't slip
  past both the sandbox and the approval gate.
- `SAFETY_MODE = "strict"` forces `bash` for untrusted commands.
- tmux: `tmux_execute` creates host sessions named `native_mcp_<name>`, and
  the other tmux tools act on those directly. Any other session name is
  treated as a sandbox session, so without a sandbox configured those calls
  return an error. Your own tmux sessions aren't reachable.
- `tmux_send_keys` can't type into host (`native_mcp_*`) sessions unless
  `ALLOW_HOST_TMUX_INPUT = true` (or `--allow-host-tmux-input`). Typing into a
  host shell runs any command, which would bypass `TRUSTED_COMMANDS`, so it is
  off by default.

## Changes from the original projects

**Structure**

- `files/` holds the file tools and `shell/` the shell tools. Code both
  projects duplicated lives once in `common/`.
- Both tool families share one `Settings` model, one loader and one FastMCP
  app. Tools are registered directly; there is no proxying or mounting.
- Settings is a plain pydantic model, not `BaseSettings`, so the system
  `PATH`/`HOST` environment variables can't leak into the server's
  `PATH`/`HOST` fields.
- The unused `fuzzy_patch.py` (it needed an uninstalled library) and a
  debugging tmux helper that printed to stdout were not copied.

**Bugs fixed**

- `tmux_execute` sent `C-c` to a new pane before its shell had started,
  killing the shell and the tmux server. This failed every time on GitHub
  runners. The bootstrap now waits for the pane's prompt and the reset no
  longer sends `C-c`. *(shell/tmux_commands.py)*
- `tmux_get_output`, `tmux_send_keys` and `tmux_kill_session` crashed
  (`cwd=None`) or failed with "Directory not allowed" on any session not
  named `native_mcp_*` when no sandbox was configured. They now return an
  error that explains why. *(shell/tool_handlers.py)*
- `tmux_list_session` crashed with `cwd=None` when no sandbox work dir was
  configured, and raised when no tmux server was running. It now checks the
  sandbox only when one exists, returns `[]` with no server, and drops blank
  names. *(shell/tool_handlers.py)*
- The Windows shell adapter crashed (`'NoneType' has no attribute 'replace'`)
  when no sandbox root was configured, and in relaxed mode ran an untrusted
  `cmd`/`powershell` command straight on the host with no sandbox. It now
  guards the crash and refuses those untrusted commands. The untrusted
  sandbox is also a real, server-built bubblewrap/docker jail rather than an
  undefined external `drun`, and a misconfigured sandbox fails the server at
  startup instead of running commands unsandboxed. *(shell/sandbox.py,
  shell/platform_adapters/windows.py)*
- The inherited shell sandbox had **two filesystem path spaces** -- a host
  space and a separate docker-container space (`DOCKER_SANDBOX_WORKDIR`,
  `ALLOWED_DIRECTORIES_DOCKER`, host->container cwd mapping, `drun` override
  env) -- so a command ran partly on host paths and partly on mapped
  container paths. That mixture (and its mapping bugs) is removed: there is
  now one host path space, sandboxes bind the project dir at the same path,
  and a config that still sets the old `work_dir`/`drun` fails at startup
  with a migration message. *(shell/execution_policy.py, shell/sandbox.py)*
- **`--update` on Windows no longer fails with "Access is denied".** The
  running `unified-mcp-server.exe` / `python.exe` live inside the uv tool env
  that `uv tool install --reinstall` wipes, and Windows won't delete in-use
  files (`os error 5` removing `...\Scripts`). When the updater is running from
  inside the env it's replacing, the reinstall is now handed to a detached step
  that waits for this process to exit (unlocking the files) and then installs;
  restart the server afterwards. *(update.py)*
- **CI security-guards gate.** A dedicated suite (run as its own CI step)
  asserts the server *refuses* dangerous tool calls and that the side effect
  never happens: file access outside the working directory (`..` traversal, an
  absolute path, a symlink pointing out of the project, a protected file) and
  dangerous/untrusted shell commands (refused with no sandbox and no approval,
  and never executed). *(tests/test_security_guards.py, .github/workflows/ci.yml)*
- **`apply_patch` preview/confirm no longer corrupts file content.** The
  dry-run diff was built from `splitlines(keepends=True)` joined with `"\n"`
  (with `lineterm=""`), doubling every newline -- so the shown diff, and the
  content the confirm/apply path rebuilt *from that diff*, gained a blank line
  after every line. Worse, rebuilding from a unified diff dropped every line
  outside a hunk, so confirming a patch on any non-trivial file truncated it.
  The dry-run now carries the exact full post-patch content, and the preview
  writes that verbatim on confirm (never reconstructs it from the diff); the
  diff itself is generated correctly. *(files/file_patch_tools.py)*
- **`get_file_info().absolute_path` is now absolute.** It was built relative to
  the project dir, so it equalled `relative_path` and contradicted its name.
  *(files/utils.py)*
- **`patch_file` no longer leaves an orphan `.backup_*`** when no patch matched:
  the file isn't modified, so the pre-emptive backup is removed. *(files/file_tools.py)*
- **`read_file` with an out-of-range line window** now returns `total_lines`,
  the resolved range, and a `warning`, instead of silently looking like an empty
  file. *(files/file_tools.py)*
- **cmd output no longer gets a stray trailing quote.** A `shell="cmd"` command
  was invoked as `cmd.exe /c "<command>"`, whose `/c` quote heuristic leaks a
  trailing quote on a nested/quoted command line (e.g. `cmd /c echo hi` printed
  `hi"`). cmd is now invoked as `cmd.exe /d /s /c "<command>"`: `/s` strips
  exactly the outer quote pair and runs the rest verbatim, avoiding the
  heuristic. *(shell/platform_adapters/windows.py)*
- **Windows commands no longer break with "`&&` is not a valid statement
  separator".** The shell adapter prepended `( cd '<cwd>' && <command> )` --
  bash syntax -- to every command, but on Windows `shell="bash"` maps to
  PowerShell (and strict mode coerced untrusted commands to it), where `&&`
  isn't a statement separator, so `execute_command`/`tmux_execute` failed even
  with `cwd`/`shell` given. The working directory is set by the spawn, so the
  adapter no longer chains `cd` at all: each shell (cmd / PowerShell / pwsh /
  wsl / real bash, dispatched by the actual program) just receives the command.
  Strict mode also no longer forces `bash` on Windows, so an explicit
  `shell="cmd"` is honored end-to-end. *(shell/platform_adapters/windows.py,
  shell/approvals.py)*
- **Windows now uses the same approve/decline gate as Linux.** An untrusted
  command on Windows (no OS sandbox) goes through the approval flow and runs
  once allowed -- it is no longer dead-refused with "run on a Linux host". The
  fail-closed refusal (approvals off, no sandbox) is now one shared message on
  both OSes. `SANDBOX = "docker"` on a Windows host is rejected at startup
  rather than silently skipping approval and then failing to run (it can't bind
  host paths 1:1 into a Linux container), so an untrusted command can never slip
  past both gates. *(shell/executor.py, shell/sandbox.py,
  shell/platform_adapters/windows.py)*
- `read_file`, `patch_file` and `apply_patch` misread text files with an
  unrecognised extension (`.mjs`, `.cjs`, `.mts`, `.lock`, ...) as binary,
  because the fallback trusted the host mime database and treated every
  `application/*` type as binary. File type is now decided from the bytes
  (NUL byte / UTF-8), which doesn't vary by machine.
  *(files/utils.py)*
- Failed commands came back as a Python list repr
  (`['…', '[exit code: 1]']`) with the timeout note twice; they are now plain
  text. A client disconnect raised a validation error instead of returning.
  *(common/mcp_types_utils.py, shell/tool_handlers.py)*
- `remove_directory` and recursive `delete_file` used
  `shutil.rmtree(onexc=...)`, which needs Python 3.12. They now work on 3.11.
  *(files/file_operations.py)*
- Code analysis skipped every `async def` (no `visit_AsyncFunctionDef`).
  *(files/code_analyzer.py)*
- A timed-out command crashed while formatting its result (`config` was never
  imported). *(common/mcp_types_utils.py)*
- Auth: Bearer tokens never worked, because the `Authorization` header was
  stripped. A failed check also echoed the key and all request headers back to
  the caller. *(server.py)*
- fastmcp 4.x removed `fastmcp.server.tasks`; the dependency is pinned `<4`.

## Tests & CI

```bash
uv pip install -e ".[dev]"
pytest -q
```

- `tests/test_tools.py` calls every tool family through a real MCP client. It
  also checks the exact set of 58 registered tools.
- `tests/test_unified.py` covers config, namespacing, the shared project
  directory, the installed console script over stdio, and API-key auth over
  real HTTP.
- `tests/test_fixes.py` holds a regression test for each fixed bug, including
  a reproduction of the tmux race using a shell that is slow to start.

CI (`.github/workflows/ci.yml`) runs the suite on Ubuntu with
Python 3.11, 3.12 and 3.13.

## License

The code comes from an MIT-licensed project (mcp-file-edit) and an
Apache-2.0-licensed project (shell-mcp-server), so the package is
`MIT AND Apache-2.0`. See `NOTICE`, `LICENSE-MIT` and `LICENSE-APACHE`. Each
copied file says which project it came from.