local-code-agent

基于 FastMCP 开发的本地 MCP Server：让外部 AI（ChatGPT、Claude 等）通过 HTTP 远程操控本地工作区——文件读写/编辑、搜索、shell 命令、Git 操作——并提供沙盒隔离、敏感文件保护与审计日志。

本项目不含 AI/LLM 逻辑，仅包含工具层服务与安全控制。

环境要求

• Python 3.10+（FastMCP 硬性要求）
• pip install -r requirements.txt（fastmcp、pyyaml）

快速开始

方式一：图形界面（推荐）

python start.py

控制台窗口操作步骤：

1. 工作区文件夹：点「选择…」指定一个文件夹。AI 的全部操作被限制在该文件夹内（沙盒），换文件夹即切换沙盒根。
2. 连接提示词：窗口中部有「连接提示词」卡片，把里面的文字复制后发给网页端 AI，AI 即按其中配置绑定本 MCP 服务器（无需 Token）。
3. 端口：默认 8000；如被占用可改。
4. 只读模式：勾选后写/编辑/命令类工具全部被拒，运行中切换立即生效。
5. 点「启动服务」→ 状态栏显示版本、只读状态、工作区、运行时长，日志区实时输出服务日志。
6. 停止：点「停止服务」，或直接关闭窗口（会先询问）。

方式二：命令行

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

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

可选参数：--workspace D:\projects\my-project（沙盒根目录）、--host 0.0.0.0（允许局域网访问）、--port 9000。停止用 Ctrl+C。

验证与健康检查

服务启动后访问：GET http://127.0.0.1:8000/health（免认证）。返回：

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

其余端点（含 /mcp）可直接访问，无需认证。

局域网访问

默认只监听 127.0.0.1，仅本机可连。同局域网其他设备访问：

python server.py --host 0.0.0.0

客户端连接地址：http://<本机局域网IP>:8000/mcp（本机 IP 用 ipconfig 查看）。暴露到局域网意味着同网段设备都能访问且无需认证，务必谨慎。

不建议直接暴露公网。如需公网访问，请自备反向代理方案（Nginx + TLS、frp 或其他隧道工具），并在反代层强制 HTTPS 与鉴权。

图形化界面（可选）

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

python start.py

控制台功能：

• 工作区文件夹：点「选择…」打开文件夹选择器。一次只能选一个文件夹，AI 的全部操作被限制在该文件夹（沙盒）内，换文件夹会替换当前选择。
• 连接提示词：内置可编辑的提示词文本，点「复制提示词」一键复制，发给网页端 AI 即可完成 MCP 绑定。无需 Token。
• 端口 / 只读模式：设置监听端口；勾选只读则禁用写入/编辑/命令工具。
• 启动 / 停止服务：在 GUI 进程内启动 FastMCP（后台线程 + uvicorn），使用独立日志处理器，停止会等待服务线程完成。
• 运行中切换：更换工作区或勾选只读会立即生效，无需重启。端口修改需重启服务。
• 状态栏：轮询 /health，显示版本、只读状态、当前工作区、运行时长。
• 日志区：实时显示服务输出，自动清理 ANSI 转义码，右键可复制，超 600 行自动裁短。

GUI 与命令行共用同一套沙盒、审计机制；对接方式相同。

客户端对接

本机客户端：URL 填 http://127.0.0.1:8000/mcp；局域网客户端用 http://<本机局域网IP>:8000/mcp（服务器需 --host 0.0.0.0 启动）。无需认证。

Claude Desktop 的 claude_desktop_config.json：

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

工具清单

工具	参数	说明
read_file	path, offset=0, limit=0	limit 0 表示全部；offset 表示跳过的起始行数
write_file	path, content	自动创建父目录；敏感路径会被拒绝
edit_file	path, old_text, new_text, dry_run=false	文本精确匹配且必须唯一
list_directory	path=".", recursive=false	返回结构化条目；跳过 .git
search_files	pattern, path=".", file_pattern="*"	返回 {path,line,text} 条目；非法正则时退化为子串匹配
file_stat	path	返回结构化大小、mtime、类型
tail_file	path, lines=100	读文件尾部
glob_files	pattern, path="."	返回结构化路径数组；拒绝越界模式
rename_file	source, destination	不覆盖已有目标
copy_file	source, destination	仅复制文件，不覆盖
make_directory	path	自动创建父目录
delete_file	path	仅删文件
download_file	path, url	支持任意 HTTP(S) URL；禁重定向；50MB 上限
run_command	command, timeout=30	工作区内执行任意命令；SSE 流式输出
git_status / git_diff / git_log / git_branch	—	只读
git_commit	message	git add -A + commit；需 x-confirm: true

安全模型

• 沙盒：所有路径经 realpath 解析，必须落在工作区根目录内（可拦截符号链接逃逸）。../ 及绝对路径无法越界。
• 认证：无 Token 认证。服务默认只监听本机 127.0.0.1；如需对外，请在反向代理层自行加鉴权。
• 危险操作确认：Git 提交需请求头 x-confirm: true 才会执行。
• 敏感文件：.env、.env.*、*.pem、*.key、id_rsa、.ssh/、.aws/、credentials 在任意路径层级都会被拦截。返回统一「access denied」，不暴露文件是否存在。
• 下载：支持任意 HTTP(S) 主机；禁止重定向；超过 50MB 中止并删除半成品。
• 审计日志：JSON 行格式，轮转 10MB × 5，记录时间、工具名、脱敏参数、结果、耗时。
• 只读模式：python server.py --readonly 或 GUI 勾选。写/命令工具仍可见，调用时返回 read-only mode。运行中可切换。

配置优先级

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

项目结构

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

已知限制

• Python 3.8 无法运行本服务（fastmcp 需 3.10+）；逻辑模块兼容 3.8，可用 python tests/test_core.py 自检。
• run_command 为 SSE 流式输出，总超时上限 3600 秒。
• 仅支持单工作区。多工作区切换与会话级上下文暂未实现（YAGNI）。