local-code-agent

A local MCP Server built on FastMCP: allows external AI (ChatGPT, Claude, etc.) to remotely control your local workspace through Cloudflare Tunnel — file read/write/edit, search, shell commands, Git operations — with Bearer Token authentication, sandbox isolation, and audit logs.

This project contains no AI/LLM logic, only tool-layer services and tunnel configuration.

Requirements

• Python 3.10+ (hard requirement for FastMCP)

• pip install -r requirements.txt (fastmcp, pyyaml)

Quick Start

# 1. 安装依赖
pip install -r requirements.txt
set MCP_AUTH_TOKEN=your_long_random_token
set MCP_WORKSPACE=D:\projects\my-project

# 2. 启动服务（默认监听 127.0.0.1:8000，路径 /mcp）
python server.py

# 3. 公网穿透（临时域名）
cloudflared tunnel --url http://127.0.0.1:8000

# 固定域名（绑定自有域名）
cloudflared tunnel --url http://127.0.0.1:8000 --hostname mcp.yourdomain.com

Health check: GET http://127.0.0.1:8000/health (no authentication by default; all other endpoints must carry a Bearer Token).

Graphical Interface (Optional)

No need to use the command line. tkinter is part of the Python standard library, no extra installation required.

python -m gui.app

Console features:

• Workspace folder: Click "Select..." to open a folder selector. Only one folder can be selected at a time. All AI operations are restricted to that folder (sandbox). Changing the folder replaces the current selection.

• Auth Token: A random Token is generated automatically on startup; can be regenerated by clicking "Regenerate". This Token is what needs to be entered in the AI client's Authorization: Bearer ....

• Port / Read-only mode: Set the listening port; checking read-only disables write/edit/command tools.

• Start / Stop Service: Runs server.py as a child process; stop terminates the process.

• Status bar: Polls /health to display service version, current workspace, uptime; also supports one-click copy of cloudflared tunnel command.

• Log area: Displays real-time output of the server child process; automatically truncates beyond 600 lines.

The GUI is just a launcher for server.py, using the same authentication, sandbox, and audit security mechanisms; public network integration is the same as the command line.

Client Integration

ChatGPT Custom Connector: URL fill https://<tunnel-host>/mcp, add header Authorization: Bearer your_long_random_token.

Claude Desktop's claude_desktop_config.json:

{
  "mcpServers": {
    "local-code-agent": {
      "url": "https://mcp.yourdomain.com/mcp",
      "headers": { "Authorization": "Bearer your_long_random_token" }
    }
  }
}

Tool List

Security Model

• Sandbox: All paths are resolved via realpath and must fall within the workspace root directory (can intercept symlink escapes). ../ and absolute paths cannot break out.

• Authentication: FastMCP DebugTokenVerifier validates Bearer Token. Token is only read from MCP_AUTH_TOKEN (developer can use --token). Startup is denied if missing.

• Sensitive files: .env, .env.*, *.pem, *.key, id_rsa, .ssh/, .aws/, credentials at any path level are intercepted. Returns a uniform "access denied" without revealing file existence.

• Command Whitelist: command_allow, command_deny, danger_commands (requires x-confirm: true) in config.yaml.

• Download: Only http(s) hosts in download_allowed_domains are allowed; redirects are prohibited; aborts and deletes partial files beyond 50MB.

• Audit Logs: JSON line format, rotated at 10MB × 5, records time, tool name, sanitized parameters, result, duration.

• Read-only mode: python server.py --readonly only registers read/search/Git viewing tools.

Configuration Priority

Workspace: --workspace > environment variable MCP_WORKSPACE > config.yaml (default .). All other configurations come from config.yaml (see defaults inside the file). n

Project Structure

server.py                 # FastMCP 入口：配置、认证、/health
tool_registry.py          # 工具注册（与生命周期分离）
config.py / config.yaml   # 默认值 + YAML
sandbox.py                # 路径沙盒 + 敏感文件过滤
command_whitelist.py      # 命令白名单校验
audit.py                  # 轮转 JSON 审计日志
tools/file_ops.py         # 读/写/编辑/列目录/搜索
tools/file_management.py  # 删/改名/复制/建目录/stat/tail/glob
tools/download.py         # 域名白名单下载
tools/command.py          # 同步 run_command（测试/非流式）
tools/git_ops.py          # status/diff/log/branch/commit
gui/                      # tkinter 启动器
start.py / start.spec     # GUI 入口 + PyInstaller onedir
tests/                    # test_core.py + test_extra.py

Known Limitations

• Python 3.8 cannot run this service (fastmcp requires 3.10+); logic modules are compatible with 3.8, can use python tests/test_core.py for self-check.

• Cloudflare Tunnel default request timeout is about 100 seconds. run_command is SSE streaming; total timeout upper limit 3600 seconds.

• Only single workspace is supported. Multi-workspace switching and session-level context are not yet implemented (YAGNI).

• Packaging: pip install -r requirements-build.txt && pyinstaller start.spec, output dist/start/start.exe. GUI requires manual clicking "Start Service".