local-code-agent

基于 FastMCP 开发的本地 MCP Server：让外部 AI（ChatGPT、Claude 等）通过 Cloudflare Tunnel 安全穿透，远程操控本地工作区——文件读写/编辑、搜索、shell 命令、Git 操作——并提供 Bearer Token 认证、沙盒隔离与审计日志。

本项目不含 AI/LLM 逻辑，仅包含工具层服务与隧道配置。

环境要求

• Python 3.10+（FastMCP 硬性要求）

• pip install -r requirements.txt（fastmcp、pyyaml）

快速开始

# 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

健康检查：GET http://127.0.0.1:8000/health（默认免认证；其余端点必须携带 Bearer Token）。

图形化界面（可选）

不写命令行也能用。tkinter 为 Python 标准库，无需额外安装。

python -m gui.app

控制台功能：

• 工作区文件夹：点「选择…」打开文件夹选择器。一次只能选一个文件夹，AI 的全部操作被限制在该文件夹（沙盒）内，换文件夹会替换当前选择。

• 认证 Token：启动时自动生成随机 Token，可点「重新生成」更换；此 Token 即需填入 AI 客户端的 Authorization: Bearer ...。

• 端口 / 只读模式：设置监听端口；勾选只读则禁用写入/编辑/命令工具。

• 启动 / 停止服务：以子进程运行 server.py，停止即终止进程。

• 状态栏：轮询 /health，显示服务版本、当前工作区、运行时长；也支持一键复制 cloudflared 隧道命令。

• 日志区：实时显示 server 子进程输出，超 600 行自动裁短。

GUI 只是 server.py 的启动器，沿用同一套认证、沙盒、审计安全机制；公网对接方式与命令行相同。

客户端对接

ChatGPT Custom Connector：URL 填 https://<tunnel-host>/mcp，请求头加 Authorization: Bearer your_long_random_token。

Claude Desktop 的 claude_desktop_config.json：

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

工具清单

安全模型

• 沙盒：所有路径经 realpath 解析，必须落在工作区根目录内（可拦截符号链接逃逸）。../ 及绝对路径无法越界。

• 认证：FastMCP DebugTokenVerifier 校验 Bearer Token。Token 仅从 MCP_AUTH_TOKEN 读取（开发可用 --token）。缺失则拒绝启动。

• 敏感文件：.env、.env.*、*.pem、*.key、id_rsa、.ssh/、.aws/、credentials 在任意路径层级都会被拦截。返回统一「access denied」，不暴露文件是否存在。

• 命令白名单：config.yaml 中 command_allow、command_deny、danger_commands（需 x-confirm: true）。

• 下载：仅允许 download_allow_domains 中的 http(s) 主机；禁止重定向；超过 50MB 中止并删除半成品。

• 审计日志：JSON 行格式，轮转 10MB × 5，记录时间、工具名、脱敏参数、结果、耗时。

• 只读模式：python server.py --readonly 仅注册读/搜索/Git 查看类工具。

配置优先级

工作区：--workspace > 环境变量 MCP_WORKSPACE > config.yaml（默认 .）。其余配置均来自 config.yaml（详见文件内默认值）。

项目结构

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

已知限制

• Python 3.8 无法运行本服务（fastmcp 需 3.10+）；逻辑模块兼容 3.8，可用 python tests/test_core.py 自检。

• Cloudflare Tunnel 默认请求超时约 100 秒。run_command 为 SSE 流式；总超时上限 3600 秒。

• 仅支持单工作区。多工作区切换与会话级上下文暂未实现（YAGNI）。

• 打包：pip install -r requirements-build.txt && pyinstaller start.spec，产物 dist/start/start.exe。GUI 需手动点「启动服务」。