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.

Related MCP server: Remote MCP Server Authless

🛠 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.

🧰 Detailed MCP Tools Specification

📑 Governance & Guidelines

For LLM agent operational guidelines and behavioral rules, see AGENT.md.

📜 License

MIT