# MCP Ops Toolkit

[中文说明](README.zh-CN.md) | English

A self-hosted Model Context Protocol (MCP) operations gateway for Linux control hosts. It provides a compact tool surface for safe filesystem and Git operations, authenticated HTTP transport, ChatGPT attachment upload, native file reading, SSH/SFTP adapters, and optional infrastructure integrations.

> **Security warning:** this project can expose highly privileged operations. The unrestricted root-shell path is disabled by default. Audit the code, keep the service on loopback behind an authenticated reverse proxy or tunnel, use a dedicated Unix account, and allowlist every privileged bridge.

## Highlights

- Compact FastMCP facade designed to keep tool discovery manageable.
- Constant-time Bearer or `X-API-Key` authentication for Streamable HTTP.
- Atomic binary attachment upload with size limits, SHA-256 verification, overwrite protection, and backup support.
- Native MCP text, image, and blob responses for local files.
- Structured filesystem, Git, Python, Node, and npm operations through a root-owned bridge.
- Persistent SSH sessions, argv-based remote execution, terminal I/O, and SFTP-style transfer through an external allowlisted bridge.
- Optional Azure, Cloudflare, control-plane, and encrypted secret-broker adapters.
- Optional full root shell with bounded runtime, bounded output files, output paging, and explicit opt-in.

## Repository layout

- `compact_app.py`: the compact public MCP tool surface.
- `http_server.py`: authenticated Streamable HTTP entrypoint.
- `mcp_main.py`: stdio entrypoint.
- `safe_ops.py` / `safe_ops_bridge.py`: structured local operations.
- `file_content.py`: native MCP file responses.
- `server.py`: control-plane and optional root-shell implementation.
- `azure_tools.py`, `cloudflare_tools.py`, `ssh_tools.py`, `secret_tools.py`: optional bridge adapters.
- `deploy/systemd/`: generic systemd and sudoers examples.

## Quick start

```bash
git clone https://github.com/gaojiefengxswhuhit/mcp-ops-toolkit.git
cd mcp-ops-toolkit
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
export MCP_OPS_ACCESS_TOKEN="$(python3 -c 'import secrets; print(secrets.token_urlsafe(48))')"
python http_server.py
```

The default listener is `127.0.0.1:8792`; `/healthz` is unauthenticated and all MCP routes require the access token. For stdio transport, run `python mcp_main.py`.

## Privileged bridges

The MCP process should run as an unprivileged account. Privileged operations call narrowly named, root-owned executables under `/usr/local/sbin/`. The repository includes the safe-operations bridge and the optional root-shell bridge. Azure, Cloudflare, SSH, and secret-broker adapters define JSON or argv contracts, but their deployment-specific credential and host-resolution implementations are intentionally not included.

Expected bridge paths can be changed in source or wrapped with stable symlinks:

```text
/usr/local/sbin/mcp-ops-toolkit-safe-ops
/usr/local/sbin/mcp-ops-toolkit-root-shell
/usr/local/sbin/mcp-ops-toolkit-azure-cli
/usr/local/sbin/mcp-ops-toolkit-cloudflare
/usr/local/sbin/mcp-ops-toolkit-ssh-bridge
/usr/local/sbin/mcp-ops-toolkit-secret-broker
```

## Security defaults

- The HTTP server binds to loopback by default.
- DNS-rebinding protection is enabled.
- Allowed hosts and origins are configured through environment variables.
- Full root shell is disabled unless `MCP_OPS_ENABLE_FULL_SHELL=1`.
- File reads use allowlisted roots and deny common key and secret locations.
- Uploaded files are copied atomically and verified after the copy.
- Real tokens, host aliases, private domains, account identifiers, and credentials must stay outside Git.

See [SECURITY.md](SECURITY.md) before production use.

## Tests

```bash
python -m compileall -q .
python test_server_contract.py server.py
python test_compact_contract.py .
```

## License

MIT