local-code-agent

A local MCP Server built on FastMCP: allows external AI (ChatGPT, Claude, etc.) to remotely control your local workspace via HTTP—file read/write/edit, search, shell commands, Git operations—with sandbox isolation, sensitive file protection, and audit logging.

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

Requirements

• Python 3.10+ (FastMCP hard requirement)

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

Related MCP server: OpenAI Secure MCP Tunnel

Quick Start

Method 1: GUI (Recommended)

python start.py

Console window steps:

1. Workspace folder: Click "Select…" to choose a folder. All AI operations are confined to this folder (sandbox); changing the folder switches the sandbox root.

2. Connection prompt: The middle of the window has a "Connection Prompt" card. Copy the text inside and send it to the web-based AI. The AI will then bind to this MCP server according to the configuration (no token required).

3. Port: Default 8000; change if occupied.

4. Read-only mode: When checked, all write/edit/command tools are rejected. Toggling takes effect immediately while running.

5. Click "Start Service" → the status bar shows version, read-only status, workspace, and uptime; the log area displays real-time service logs.

6. Stop: Click "Stop Service", or close the window directly (a confirmation prompt will appear first).

Method 2: Command Line

# 1. 安装依赖
pip install -r requirements.txt

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

Optional parameters: --workspace D:\projects\my-project (sandbox root), --host 0.0.0.0 (allow LAN access), --port 9000. Stop with Ctrl+C.

Verification and Health Check

After the service starts, visit: GET http://127.0.0.1:8000/health (no authentication). Returns:

{ "status": "ok", "service": "local-code-agent", "version": "0.1.0",
  "workspace": "D:\\projects\\my-project", "readonly": false,
  "uptime_seconds": 3 }

Other endpoints (including /mcp) are directly accessible without authentication.

LAN Access

By default, it listens only on 127.0.0.1, so only the local machine can connect. For other devices on the same LAN:

python server.py --host 0.0.0.0

Client connection address: http://<local LAN IP>:8000/mcp (use ipconfig to find the local IP). Exposing to the LAN means any device on the same subnet can access it without authentication—proceed with caution.

It is not recommended to expose directly to the public internet. If public access is needed, set up a reverse proxy solution (Nginx + TLS, frp, or other tunneling tools) and enforce HTTPS and authentication at the reverse proxy layer.

Graphical Interface (Optional)

You can use it without writing command lines. tkinter is part of the Python standard library, no extra installation needed.

python start.py

Console features:

• Workspace folder: Click "Select…" to open a folder picker. Only one folder can be selected at a time; all AI operations are confined to that folder (sandbox). Changing the folder replaces the current selection.

• Connection prompt: Built-in editable prompt text. Click "Copy Prompt" to copy it in one click, then send it to the web-based AI to complete the MCP binding. No token required.

• Port / Read-only mode: Set the listening port; check read-only to disable write/edit/command tools.

• Start / Stop service: Start FastMCP within the GUI process (background thread + uvicorn) using a dedicated log handler. Stopping waits for the service thread to finish.

• Switch while running: Changing the workspace or toggling read-only takes effect immediately without restarting. Port changes require a service restart.

• Status bar: Polls /health, displays version, read-only status, current workspace, and uptime.

• Log area: Displays real-time service output, automatically strips ANSI escape codes, right-click to copy, auto-truncates after 600 lines.

The GUI and command line share the same sandbox and audit mechanisms; the integration method is identical.

Client Integration

Local client: fill URL with http://127.0.0.1:8000/mcp; LAN client uses http://<local LAN IP>:8000/mcp (server must be started with --host 0.0.0.0). No authentication required.

Claude Desktop's claude_desktop_config.json:

{
  "mcpServers": {
    "local-code-agent": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Tool List

Security Model

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

• Authentication: No token authentication. The service listens only on 127.0.0.1 by default; if external access is needed, add authentication at the reverse proxy layer.

• Dangerous operation confirmation: Git commits require the request header x-confirm: true to execute.

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

• Downloads: Supports any HTTP(S) host; disables redirects; aborts and deletes partial files if over 50MB.

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

• Read-only mode: python server.py --readonly or GUI checkbox. Write/command tools are still visible but return read-only mode when called. Can be toggled while running.

Configuration Priority

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

Project Structure

server.py                 # FastMCP 入口：配置、认证、/health
tool_registry.py          # 工具注册（与生命周期分离）
config.py / config.yaml   # 默认值 + YAML
sandbox.py                # 路径沙盒 + 敏感文件过滤
audit.py                  # 轮转 JSON 审计日志
tools/file_ops.py         # 读/写/编辑/列目录/搜索
tools/file_management.py  # 删/改名/复制/建目录/stat/tail/glob
tools/download.py         # HTTP(S) 下载（无域名白名单）
tools/command.py          # 同步 run_command（测试/非流式）
tools/git_ops.py          # status/diff/log/branch/commit
runtime.py                # 运行时只读标志
gui/                      # tkinter 控制台（进程内服务）
start.py                  # GUI 入口
tests/                    # test_core.py + test_extra.py

Known Limitations

• Python 3.8 cannot run this service (fastmcp requires 3.10+); the logic modules are compatible with 3.8 and can be tested with python tests/test_core.py.

• run_command uses SSE streaming output with a total timeout of 3600 seconds.

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