Local Coder MCP Agent

Этот проект собирает локальный рабочий процесс кодинг-агента:

1. Кодинг-модель Qwen работает локально через OpenAI-совместимый API /v1/chat/completions.

2. Python-воркер общается с этим локальным API через OpenAI SDK.

3. MCP-сервер local-coder предоставляет Codex функцию delegate_to_local_coder.

4. Codex делегирует задачи по реализации локальному воркеру, а затем сам проверяет тесты и диффы.

Веса моделей не включены. Используйте собственную локальную директорию модели через MODEL_DIR.

Архитектура

Codex
  -> MCP tool: delegate_to_local_coder(task, workspace, max_steps)
    -> mcp_servers.local_coder.server
      -> workers.coding.worker.CodingWorker
        -> OpenAI-compatible local model server
        -> restricted file/test/git tools inside the requested workspace

Воркер умеет выводить список файлов, читать файлы, записывать файлы, вносить точечные правки по точному тексту, запускать pytest, выполнять небольшой список разрешённых команд, искать текст, просматривать git status и git diff. Он отклоняет пути за пределами выбранного рабочего пространства.

Related MCP server: cc-in-codex

Установка

git clone <your-repo-url>
cd local-coder-mcp-agent
python -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -e ".[dev,mlx]"
cp .env.example .env

Отредактируйте .env:

MODEL_DIR=${HOME}/models/Qwen3-Coder-30B-A3B-Instruct-4bit
ALLOWED_WORKSPACE_ROOT=${HOME}/AI/projects
LOCAL_CODER_BASE_URL=http://127.0.0.1:8080/v1
LOCAL_CODER_MODEL=default_model
LOCAL_CODER_API_KEY=local

ALLOWED_WORKSPACE_ROOL — это дерево дирректорий, которое воркер можно редактировать. Длу корневый корнеей используйте ALLOWED_WORKSPACE_ROOOTS, разделзуя их : на macOS/Linux.

Запуск сервера модели

Длуя MLX-модели на Apple Silicone:

source .venv/bin/activate
./scripts/start_qwen3_coder_server.sh

Скрипт запускает:

python -m mlx_lm.server \
  --model "${MODEL_DIR}" \
  --host 127.0.0.1 \
  --port 8080 \
  --max-tokens 4096 \
  --temp 0

Подойдёт любой сервер, совместиый с OpenAI, если он предоставляет http://127.0.0.1:8080/v1/chat/completions, или если вы обновите LOCAL_CODER_BASE_URL.

Запуск MCP-сервера вручную

source .venv/bin/activate
./scripts/start_local_coder_mcp.sh

Обычно Codex сам запускает MCP-сервер из config_toml.

Настройка MCP для Codex

Скопируйте блок local-coder из config.example.toml в свой Codex config.toml, затем замените плейсHoldеры локальными значениями:

[mcp_servers.local-coder]
enabled = true
command = "${PROJECT_ROOT}/.venv/bin/python"
args = ["-m", "mcp_servers.local_coder.server"]
cwd = "${PROJECT_ROOT}"

[mcp_servers.local-coder.env]
LOCAL_CODER_BASE_URL = "http://127.0.0.1:8080/v1"
LOCAL_CODER_MODEL = "default_model"
LOCAL_CODER_API_KEY = "local"
ALLOWED_WORKSPACE_ROOT = "${ALLOWED_WORKSPACE_ROOT}"

Используйте реальные локальные пути только в вашем приватном конфиге Codex, никому не передавайте.

Делегирование задачи из Codex

Пример промпта для Codex:

Use the local-coder MCP server and specifically call delegate_to_local_coder.

Workspace:
${ALLOWED_WORKSPACE_ROOT}/sandbox

Task:
Add multiply(a: int, b: int) -> int to calculator.py.

Requirements:
- Do not change add(), subtract(), or divide().
- Add pytest coverage for multiply().
- Run all tests.
- Inspect git diff before finishing.

After the local worker completes the task, review its changes yourself.
Do not implement the change yourself unless the local worker fails.

В состав включена папка examples/sandbox — небольшой pytest-проект для сmoкевых тестов.

Распространённые ошибки

Рабочее пространство не находится внутри разрешённого корня

Установите ALLOWED_WORKSPACE_ROOT или ALLOWED_WORKSPACE_ROOTS, чтобы запрошенное рабочее пространство находилось внутри разрешённой директории. Это сделано намеренно: воркеру не должно быть разрешено редактировать произвольные локальные файлы.

Воркер превысил лимит количества шагов

Увеличьте max_steps для более крупных задач или разбейте задачу на более мелкие шаги. Хорошие задачи для локального воркера — конкретные и проverяемые.

Модель вернула нет текста

Локальный сервер модели вернул ответ без полезного content, reasoning_content, reasoning или thinking. Попробуйте:

• Убедитесь, что сервер реализует OpenAI-совместимые chat completions.

• Укажите LOCAL_CODER_ENABLE_THINKING=false.

• Уменьшите размер задачи.

• Простестируйте сервер прямым запросом /v1/chat/completions.

Сбой соединения

Убедитесь, что сервер модели запущен, порт совпадает с LOCAL_CODER_BASE_URL и никакой брандмауэр или прокси не перехватывает трафик localhost.

Примечания по безопасности

• Не коммитьте .env, приватный конфиг Codex, веса моделей, логи, ключи или сгенерированные кэши.

• Держите ALLOWED_WORKSPACE_ROOT узким.

• Локальный работник может редактировать и выполнять ограниченные команды внутри разрешённых рабочих пространств; проверяйте каждый diff перед применением изменений.

• Держите API-server привязанным к локальному 127.0.0.1, если у вас нет отдельного плана сетевого обеспечения.

• В этом репозитории намеренно используются плейсхолдеры, такие как ${HOME}, ${MODEL_DIR}, ${PROJECT_ROOT} и ${ALLOWED_WORKSPACE_ROOT}.

Запуск проверок

python -m pytest -q
python -m py_compile \
  mcp_servers/local_coder/server.py \
  workers/coding/client.py \
  workers/coding/parser.py \
  workers/coding/tools.py \
  workers/coding/worker.py