Local Coder MCP Agent

Este proyecto empaqueta un flujo de trabajo de agente de programación local:

1. Un modelo de codificación Qwen se ejecuta localmente detrás de una API compatible con OpenAI /v1/chat/completions.

2. Un worker de Python se comunica con esa API local mediante el SDK de OpenAI.

3. Un servidor MCP local-coder expone delegate_to_local_coder a Codex.

4. Codex delega las tareas de implementación al worker local y luego revisa los tests y los diffs por sí mismo.

No se incluyen pesos de modelos. Usa tu propio directorio de modelos local mediante MODEL_DIR.

Arquitectura

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

El worker puede listar archivos, leer archivos, escribir archivos, aplicar parches de texto exacto, ejecutar pytest, ejecutar una pequeña lista de comandos permitidos, buscar texto, inspeccionar el estado de git e inspeccionar el diff de git. Rechaza rutas fuera del espacio de trabajo seleccionado.

Related MCP server: Codex Workspace Bridge

Instalación

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

Edita .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_ROOT es el árbol de directorios que el worker puede editar. Para varias raíces, usa ALLOWED_WORKSPACE_ROOTS separadas por : en macOS/Linux.

Iniciar el servidor del modelo

Para un modelo MLX en Apple Silicon:

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

El script arranca:

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

Cualquier servidor compatible con OpenAI funciona si expone http://127.0.0.1:8080/v1/chat/completions, o si actualizas LOCAL_CODER_BASE_URL.

Iniciar el servidor MCP manualmente

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

Normalmente Codex inicia el servidor MCP por ti desde config.toml.

Configurar Codex

Copia el bloque local-coder de config.example.toml a tu config.toml de Codex y reemplaza los marcadores de posición con valores locales:

[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}"

Usa rutas locales reales solo en tu configuración privada de Codex, nunca en archivos versionados.

Delegar una tarea desde Codex

Ejemplo de prompt para 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.

La carpeta examples/sandbox incluida es un pequeño proyecto pytest para pruebas de humo.

Errores Comunes

El espacio de trabajo no está dentro de un directorio raíz permitido

Configura SALLOWED_WORKSPACE_ROOT o ALLOWED_WORKSPACE_ROOTS para que el espacio de trabajo solicitado quede dentro de un directorio aprobado. Esto es intencional: el worker no debería poder editar archivos locales arbitrarios.

El worker superó el número máximo de pasos

Aumenta max_steps para tareas más grandes, o divide la tarea en pasos más pequeños. Las tareas buenas para el worker local son específicas y verificables.

El modelo no devolvió ningún texto utilizable

El servidor del modelo local devolvió una respuesta sin content, reasoning_content, reasoning ni thinking utilizables. Prueba esto:

• Asegurate de que el servidor implementa chat completions compatibles con OpenAI.

• Establece LOCAL_CODER_ENABLE_THINKING=false.

• Reduce el tamaño de la tarea.

• Prueba el servidor con una solicitud directa a /v1/chat/completions.

La conexión falló

Confirmar que el servidor del modelo se está ejecutando, que el puerto coincide con LOCAL_CODER_BASE_URL y que ningún firewall ni proxy esté interceptando el tráfico de localhost.

Notas de Seguridad

• No hagas commit de .env, archivos de configuración privados de Codex, pesos de modelos, logs, claves ni cachés generadas.

• Mantén ALLOWED_WORKSPACE_ROOT restringido.

• El worker local puede editar y ejecutar comandos limitados dentro de los espacios de trabajo permitidos; revisa cada diff antes de aceptar los cambios.

• Mantén el servidor API enlazado a 127.0.0.1 a menos que tengas un plan de seguridad de red aparte.

• Este repositorio utiliza intencionadamente marcadores de posición como ${HOME}, ${MODEL_DIR}, ${PROJECT_ROOT} y ${ALLOWED_WORKSPACE_ROOT}.

Ejecutar comprobaciones

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