Local Agent MCP

English · 权限说明 · 架构说明

Заставьте ChatGPT Pro работать прямо на вашем локальном компьютере

Вы ставите задачу в ChatGPT, и он вызывает локальные MCP-инструменты: читает проекты, изменяет файлы, запускает тесты, проверяет Git Diff, создаёт Commit.

Сложные задачи можно поручить локальному Codex. ChatGPT продолжает отвечать за разбиение на шаги, просмотр прогресса, уточнение требований и финальную проверку.

ChatGPT Pro
→ Local Agent MCP
→ 本地文件 / 测试 / Git / Codex

Не нужно многократно копировать код и не нужно прогонять каждую задачу через Codex.

Это неофициальный общественный проект. Он не является продуктом OpenAI и не представляет OpenAI.

Related MCP server: chatgpt-codex-tools-mcp

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

Предварительные требования

Подготовьте следующее:

• macOS или Linux

• Python 3.11 и выше

• Git

• uv

• Официальный tunnel-client от OpenAI

• Среда ChatGPT с поддержкой пользовательских MCP-приложений

• Tunnel ID

• Соответствующий Tunnel Runtime Key

На macOS можно сначала установить базовые инструменты:

brew install uv tmux
brew install openai/tools/tunnel-client

Одна фраза для ИИ

Отправьте эту фразу ИИ, который умеет работать с локальным терминалом:

Установи https://github.com/ezra-y/local-agent-mcp на мой компьютер и выполни настройку, запуск и проверку согласно README.

Ручная установка: Установка в ChatGPT.

Ключевые возможности

28 инструментов

Прямой Tool delete_file не предоставлен. apply_patch также отказывается удалять целые файлы.

git_commit по умолчанию отключает Hook репозитория и подпись коммита. При обнаружении Git Filter clean / process коммит отклоняется, чтобы структурированный Commit не запускал неявно программы репозитория. git_diff также отключает внешний Diff и textconv.

Resource прав

Помимо Tool get_permissions, сервис также предоставляет:

local-agent://permissions

Содержимое включает:

当前允许访问哪里
哪些目录和文件被禁止
读写是否开启
有没有直接删除工具
高权限入口有哪些

get_permissions будет сохранён для клиентов, которые ещё не отображают MCP Resources.

Права и их ограничение

Область по умолчанию

Структурированные файловые и Git-инструменты по умолчанию имеют доступ к домашнему каталогу текущего пользователя:

$HOME

Обычно это Desktop, Downloads, Documents и другие проекты в личных каталогах.

Что жёстко запрещено кодом

Структурированные файловые инструменты отклоняют:

.ssh
.aws
.azure
.codex
.docker
.gnupg
.kube
.Trash
Library
.env 和 .env.*
常见凭据文件
.pem / .key / .p12 / .pfx 私钥文件
符号链接路径

Кроме того:

• Нет прямого Tool для удаления файлов.

• apply_patch не может удалить целый файл.

• Нет Git Push Tool.

• git_commit коммитит только явно перечисленные пути.

Сужение структурированной области

Задайте перед запуском:

export LOCAL_AGENT_MCP_ROOT="$HOME/Projects"

Старое имя конфигурации CODEX_MCP_ROOT по-прежнему поддерживается.

После этого эти инструменты смогут обращаться только к $HOME/Projects:

list_files
read_file
write_file
apply_patch
git_status
git_diff
git_commit

Пример запуска на переднем плане:

export LOCAL_AGENT_MCP_ROOT="$HOME/Projects"
./scripts/run_tunnel.sh

Точки входа с повышенными правами

LOCAL_AGENT_MCP_ROOT — это жёсткая граница для структурированных файловых и Git-инструментов, а не системная песочница всего процесса.

Если нужны Hook репозитория, Git LFS или другие Filter, выполняйте коммит вручную или используйте run_command с повышенными правами после явной проверки конфигурации репозитория.

В v0.5.1 пока нет конфигурации для скрытия или отключения отдельных Tool. При необходимости более сильной изоляции используйте отдельного системного пользователя, виртуальную машину, контейнер или поддерживайте версию с сокращённым набором Tool.

Полное описание см. в docs/permissions.md.

Установка в ChatGPT

1. Скачивание и проверка

git clone https://github.com/ezra-y/local-agent-mcp.git
cd local-agent-mcp
uv sync --locked --all-groups
uv run pytest -q

Порядок поиска локального Codex:

1. Путь, указанный в CODEX_BIN.

2. codex из PATH.

3. Codex, встроенный в macOS-приложение ChatGPT.

2. Сохранение Runtime Key

macOS:

./scripts/save_tunnel_key.sh

Linux:

export CONTROL_PLANE_API_KEY="<你的 Runtime Key>"

3. Генерация конфигурации Tunnel

export CONTROL_PLANE_TUNNEL_ID="tunnel_<32位小写十六进制>"
./scripts/configure_tunnel.sh

Локальная конфигурация сохраняется в:

.runtime/profiles/

4. Запуск Tunnel

На переднем плане:

./scripts/run_tunnel.sh

В фоне:

tmux new-session -d \
  -s local-agent-mcp-tunnel \
  -c "$PWD" \
  ./scripts/run_tunnel.sh

Ожидание готовности сервиса:

for i in {1..30}; do
  curl -fsS http://127.0.0.1:8741/readyz && break
  sleep 1
done

При успехе возвращается:

ready

Локальная страница состояния:

http://127.0.0.1:8741/ui

5. Подключение в ChatGPT

1. Откройте Settings → Apps.

2. Включите Developer Mode.

3. Создайте или подключите соответствующее пользовательское MCP-приложение.

4. После запуска Tunnel нажмите Refresh / Scan tools.

5. Откройте новый чат и выберите @Local Agent.

6. Проверка

Отправьте в новом чате:

@Local Agent

调用 get_permissions。
报告当前工具总数、版本和 allowed_root。

Ожидаемый результат для v0.5.1:

工具总数：28
版本：0.5.1
allowed_root：你的 Home，或你设置的 LOCAL_AGENT_MCP_ROOT

Если клиент поддерживает Resources, попробуйте также прочитать:

local-agent://permissions

Запуск только локального stdio MCP

Без использования ChatGPT Tunnel:

./scripts/run_mcp.sh

Также можно установить как глобальную команду:

uv tool install .
local-agent-mcp

Старая команда local-codex-mcp по-прежнему доступна.

Повседневное использование

Параметр project в инструментах обычно заполняется путём относительно $HOME:

Documents/Codex/local-agent-mcp
Downloads/my-project
Desktop/example-project

Абсолютные пути внутри Home также поддерживаются. project="." означает весь структурированный корневой каталог; при настройках по умолчанию это весь Home.

Одна типичная задача

@Local Agent

在 Downloads/my-project 修复登录失败问题。
检查相关代码和 Git 状态，完成修改、测试、Diff 和 Commit。

Обычный процесс:

get_permissions
→ git_status / list_files / read_file
→ write_file / apply_patch
→ run_tests
→ git_diff
→ git_commit

В сложные задачи можно добавить явный Workflow или локальный Codex.

Как работает Workflow

Пять понятий

Порядок выполнения

create_workflow
→ create_step
→ start_step
→ get_job / get_workflow

create_step в настоящее время поддерживает четыре типа выполнения:

Чтение и изменение файлов по-прежнему выполняются напрямую через read_file, write_file, apply_patch.

Пример: создание тестового Step

create_workflow(
  project="Downloads/my-project",
  title="验证登录修复"
)
→ workflow_id

create_step(
  workflow_id=workflow_id,
  position=1,
  name="运行测试",
  executor_kind="tests",
  spec={
    "argv": ["uv", "run", "pytest", "-q"],
    "cwd": ".",
    "timeout_seconds": 900
  },
  write_scope="worktree"
)
→ step_id

start_step(
  workflow_id=workflow_id,
  step_id=step_id,
  attempt=1
)
→ job_id

get_job(job_id)
get_workflow(workflow_id)

Идентификатор выполнения:

workflow_id + step_id + attempt

Повторный запуск с тем же номером вернёт исходный Job и не будет выполнен повторно. Для явного перезапуска используйте новый attempt, например attempt=2.

Правила параллелизма

同一个 Codex Thread：同一时间一个活动 Turn
同一个 Worktree：同一时间一个写入者
同一个仓库：不同 Worktree 可以并行

Если активному Turn нужно добавить требования, используйте steer_codex_turn; для остановки — interrupt_codex_turn.

Локальное состояние и журналы

При запуске из исходников:

.runtime/state.sqlite3
.runtime/artifacts/<job_id>/

Установленная команда по умолчанию использует:

$HOME/.local/state/local-agent-mcp/state.sqlite3

Пользовательское расположение:

export LOCAL_AGENT_MCP_STATE_PATH="/自定义位置/state.sqlite3"

Старое имя конфигурации CODEX_WORKFLOW_STATE_PATH по-прежнему поддерживается. Существующие старые базы состояния также продолжают читаться.

Длинные журналы сохраняются в файлы Artifact. SQLite хранит путь, размер и SHA-256.

Artifact не удаляются автоматически. Когда общий объём записей превышает 1 ГиБ, ping возвращает предупреждение.

Обновление

git pull
uv sync --locked --all-groups
uv run pytest -q

Затем перезапустите Tunnel и нажмите Refresh / Scan tools в ChatGPT.

Структура проекта

src/local_agent_mcp/
├── server.py                 MCP 入口与公共 Tool / Resource
├── adapters/                 本地 Agent Adapter；当前包含 Codex
├── workflow_*.py             Workflow、Step、Job、锁和 SQLite
├── command_jobs.py           后台命令与测试
├── workspace_tools.py        文件读写与 Patch
└── git_tools.py              Git 状态、Diff 和 Commit

tests/                        单元测试与集成测试
docs/                         权限和架构说明
scripts/                      MCP 与 Tunnel 启动脚本

Тестовые файлы остаются в репозитории. Они используются для проверки границ прав, кроссплатформенности, упаковки и совместимости; установленный wheel содержит только рабочий код.

Проверка разработки

uv run pytest -q
uv run python scripts/check_public_release.py
zsh -n scripts/*.sh
uv build

Основная точка входа MCP — src/local_agent_mcp/server.py. src/codex_bridge.py сохранён как совместимый псевдоним для старых импортов и старых способов запуска.

Удаление и локальные данные

Программа удаления не удаляет автоматически SQLite, Artifact, профиль Tunnel или каталог исходников. Сначала проверьте и решите, какие данные нужно сохранить.

License

MIT, см. LICENSE.

⚠️ Конфигурация по умолчанию открывает довольно широкие локальные права: ChatGPT может читать и записывать большинство проектов в домашнем каталоге текущего пользователя, а также запускать тесты, команды и локальных агентов; используйте только на доверенных компьютерах, учётных записях и проектах.