local-code-agent

MCP-сервер на базе FastMCP: позволяет внешним ИИ (ChatGPT, Claude и др.) удалённо управлять локальной рабочей областью через HTTP — чтение/запись/редактирование файлов, поиск, shell-команды, Git-операции — с песочницей, защитой конфиденциальных файлов и журналом аудита.

Этот проект не содержит логики ИИ/LLM, только инструментальный слой и средства безопасности.

Требования к окружению

• Python 3.10+ (строгое требование FastMCP)

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

Related MCP server: OpenAI Secure MCP Tunnel

Быстрый старт

Способ 1: Графический интерфейс (рекомендуется)

python start.py

Порядок действий в окне консоли:

1. Папка рабочей области: нажмите «Выбрать…» и укажите папку. Все действия ИИ ограничены этой папкой (песочница); смена папки переключает корень песочницы.

2. Подсказка для подключения: в центре окна есть карточка «Подсказка для подключения». Скопируйте текст из неё и отправьте веб-версии ИИ — ИИ настроит подключение к этому MCP-серверу (токен не требуется).

3. Порт: по умолчанию 8000; если занят, можно изменить.

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

5. Нажмите «Запустить службу» → в строке состояния отобразятся версия, статус только для чтения, рабочая область, время работы; в области журнала в реальном времени выводятся логи службы.

6. Остановка: нажмите «Остановить службу» или просто закройте окно (будет запрос подтверждения).

Способ 2: Командная строка

# 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.

Проверка работоспособности и health check

После запуска службы перейдите по адресу: 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

Функции консоли:

• Папка рабочей области: нажмите «Выбрать…», чтобы открыть диалог выбора папки. Можно выбрать только одну папку; все действия ИИ ограничены этой папкой (песочница); смена папки заменяет текущий выбор.

• Подсказка для подключения: встроенный редактируемый текст подсказки; нажмите «Копировать подсказку», чтобы скопировать её одним нажатием, и отправьте веб-версии ИИ для завершения привязки MCP. Токен не требуется.

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

• Запуск / Остановка службы: запускает FastMCP в процессе GUI (фоновый поток + uvicorn) с отдельным обработчиком журналов; остановка ожидает завершения потока службы.

• Переключение во время работы: смена рабочей области или включение режима только для чтения вступают в силу немедленно, без перезапуска. Изменение порта требует перезапуска службы.

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

• Область журнала: в реальном времени показывает вывод службы, автоматически очищает ANSI-escape-последовательности; можно скопировать правой кнопкой мыши; при превышении 600 строк автоматически усекается.

GUI и командная строка используют одни и те же механизмы песочницы и аудита; способ подключения одинаков.

Подключение клиента

Локальный клиент: URL http://127.0.0.1:8000/mcp; клиент по локальной сети: http://<локальный IP этой машины>:8000/mcp (сервер должен быть запущен с --host 0.0.0.0). Аутентификация не требуется.

claude_desktop_config.json для Claude Desktop:

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

Список инструментов

Модель безопасности

• Песочница: все пути разрешаются через realpath и должны находиться внутри корня рабочей области (перехватывает побеги через символические ссылки). ../ и абсолютные пути не могут выйти за границы.

• Аутентификация: аутентификация по токену отсутствует. Служба по умолчанию слушает только локальный 127.0.0.1; для внешнего доступа добавьте аутентификацию на уровне обратного прокси самостоятельно.

• Подтверждение опасных операций: для Git-коммита требуется заголовок запроса x-confirm: true.

• Конфиденциальные файлы: .env, .env.*, *.pem, *.key, id_rsa, .ssh/, .aws/, credentials блокируются на любом уровне пути. Возвращается единый ответ «access denied», не раскрывающий существование файла.

• Загрузка: поддерживаются любые HTTP(S) хосты; перенаправления запрещены; при превышении 50 МБ загрузка прерывается, частичный файл удаляется.

• Журнал аудита: формат JSON lines, ротация 10 МБ × 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).