# Editor MCP — Model Context Protocol Code Agent

A secure, isolated, and feature-complete Model Context Protocol (MCP) server providing full code editor functionality (`read_file`, `write_file`, `list_dir`, `search_files`, `set_workspace`, `run_command`, `git_status`, `git_diff`).

Designed to run inside Docker and be exposed securely via Cloudflare Tunnel for remote AI pair programming from any MCP-compatible LLM client (fully tested and verified working with Claude Desktop, Claude Online, and Google Gemini).

---



## 🏗 Architecture & Security Model

```
[LLM Client / Connector]
           │
           ▼  HTTPS (Streamable HTTP + Bearer Token Auth)
  [Cloudflare Tunnel]
           │
           ▼
 [MCP Server Container]  ──(bind mount)──► Host Workspace Files
           │
           ▼  (Docker Socket / API)
[Workspace Container]   ◄── Isolated CLI execution (`run_command`)
```

### Key Security & Capability Features
- **Path Traversal Guard:** All file operations validate resolved paths against designated `WORKSPACE_ROOT` whitelist. Symlinks pointing outside the workspace root are automatically blocked.
- **Isolated & Flexible CLI Execution:** `run_command` executes arbitrary, complex shell commands (chaining `&&`, `||`, pipes `|`, redirects) inside a dedicated sibling Docker container (`mcp-workspace:latest`).
- **Rich Developer Toolset:** The workspace container includes `bash`, `git`, `node`, `npm`, `python3`, `pip`, `curl`, `wget`, `jq`, `ripgrep`, `build-base` (gcc/g++/make), `tar`, `zip`, `unzip`, and `openssh-client`.
- **Custom Environment Variables:** `run_command` supports passing dynamic key-value environment variables per execution.
- **Audit Logging:** Every tool call is logged with timestamps to `logs/audit.log`.
- **Bearer Token Auth & OAuth 2.0:** Mandated Bearer token authentication on all HTTP/SSE MCP endpoints. Includes built-in standard OAuth 2.0 endpoints for seamless integration with Google Gemini and other strict OAuth clients.

---

## 🛠 Quick Start

### 1. Requirements
- Node.js 20+
- Docker & Docker Compose

### 2. Environment Setup
Copy the sample environment file and adjust your settings:
```bash
cp .env.example .env
```

Key environment variables in `.env`:
- `PORT`: Server HTTP port (default `3000`)
- `AUTH_TOKEN`: Static Bearer token required for clients
- `WORKSPACE_ROOT`: Directory path on host storing target projects (default `./workspaces`)
- `DEFAULT_WORKSPACE`: Subfolder name inside `WORKSPACE_ROOT` (default `default`)
- `WORKSPACE_IMAGE`: Docker image name for execution container (default `mcp-workspace:latest`)
- `TUNNEL_TOKEN`: Cloudflare Tunnel token

### 3. Local Development & Testing

Build TypeScript source files:
```bash
npm run build
```

Run test suites:
```bash
# Security & path traversal tests
node dist/runner-fs.js

# Full End-to-End HTTP & Auth verification
node dist/runner-e2e.js
```

### 4. Docker Compose Deployment

Build all images and run the MCP server and Cloudflare Tunnel:
```bash
# Build both server and workspace execution images
docker compose --profile tools build

# Start MCP server and cloudflared tunnel
docker compose up -d
```

> 📖 **Cloudflare Tunnel Setup Guide:** For detailed step-by-step instructions on creating a tunnel in Cloudflare Zero Trust, obtaining `TUNNEL_TOKEN`, and configuring public domain routing, see [docs/CLOUDFLARE_TUNNEL_SETUP.md](file:///mnt/data/REPO/editor-mcp/docs/CLOUDFLARE_TUNNEL_SETUP.md).

---

## 🧰 Detailed MCP Tools Specification

| Tool Name | Description | Parameters |
|-----------|-------------|------------|
| `ping` | Health check and sanity test tool | `message` *(string, optional)* |
| `set_workspace` | Set or switch the active workspace subfolder | `path` *(string, required)* — relative path within workspace root |
| `read_file` | Read content of a file within active workspace (up to 5MB limit) | `filePath` *(string, required)* |
| `write_file` | Write, overwrite, or append content to a file | `filePath` *(string)*, `content` *(string)*, `mode` *(enum: `create` \| `overwrite` \| `append`, default: `overwrite`)* |
| `replace_file_content` | Precision in-place string replacement within a file | `filePath` *(string)*, `targetContent` *(string)*, `replacementContent` *(string)* |
| `list_dir` | List files and subdirectories in a directory | `dirPath` *(string, optional, default: `.`)* |
| `get_file_tree` | Visual directory tree structure visualization | `dirPath` *(string, optional)*, `maxDepth` *(number, optional)* |
| `search_files` | Search for text/patterns across workspace files using recursive grep | `query` *(string, required)*, `subDir` *(string, optional, default: `.`)* |
| `ripgrep_search` | High-speed regex or literal pattern search via ripgrep | `query` *(string)*, `isRegex` *(boolean)*, `caseInsensitive` *(boolean)*, `subDir` *(string)* |
| `run_command` | Execute arbitrary CLI shell commands inside isolated workspace container | `command` *(string, required)*, `workingDir` *(string, optional, default: `.`)*, `env` *(object/map, optional)*, `timeoutMs` *(number, optional, default: `60000`)* |
| `git_status` | Get git repository status of active workspace | None |
| `git_diff` | Get uncommitted or staged git changes | `staged` *(boolean, optional, default: `false`)* |
| `get_environment_info` | Inspect container tool versions (node, npm, python, git, ripgrep, gcc) | None |
| `fetch_url` | Fetch and extract readable text/JSON from web URLs | `url` *(string)*, `maxBytes` *(number, optional)* |
| `web_search` | Search web queries and return top titles, URLs, and snippets | `query` *(string)* |

---

## 📑 Governance & Guidelines
For LLM agent operational guidelines and behavioral rules, see [AGENT.md](file:///mnt/data/REPO/editor-mcp/AGENT.md).

---

## 📜 License
MIT