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:

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:

npm run build

Run test suites:

# 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:

# 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