local-code-agent

Локальный MCP-сервер на базе FastMCP: позволяет внешним 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 ограничены этой папкой (песочница); смена папки заменяет текущий выбор.

• Токен аутентификации: при запуске генерируется случайный токен, можно нажать «Перегенерировать» для замены; этот токен необходимо указать в клиенте AI как Authorization: Bearer ....

• Порт / Режим только для чтения: установите порт прослушивания; при включении режима только для чтения инструменты записи/редактирования/команд отключаются.

• Запуск / Остановка сервиса: запускает server.py как дочерний процесс, остановка завершает процесс.

• Строка состояния: опрашивает /health, отображает версию сервиса, текущую рабочую область, время работы; также поддерживает копирование команды туннеля cloudflared одним нажатием.

• Область логов: отображает вывод дочернего процесса сервера в реальном времени, при превышении 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. Токен считывается только из 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).

• Загрузка: разрешены только http(s) хосты из download_allow_domains; перенаправления запрещены; при превышении 50 МБ загрузка прерывается и частичный файл удаляется.

• Журнал аудита: формат JSON lines, ротация 10 МБ × 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 необходимо вручную нажать «Запустить сервис».