Local Coder MCP Agent

이 프로젝트는 로컬 코딩 에이전트 워크플로를 패키지로 묶습니다:

1. Qwen 코딩 모델이 OpenAI 호환 /v1/chat/completions API를 통해 로컬에서 실행됩니다.

2. Python 워커가 OpenAI SDK로 해당 로컬 API와 통신합니다.

3. local-coder MCP 서버가 Codex에 delegate_to_local_coder를 노출합니다.

4. Codex는 구현 작업을 로컬 워커에게 위임한 다음, 테스트와 diff를 스스로 검토합니다.

모델 가중치는 포함되어 있지 않습니다. 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 실행, 소규모 허용 목록(allowlist)에 속한 명령 실행, 텍스트 검색, 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_ROOT는 워커가 편집할 수 있는 디렉터리 트리입니다. 여러 루트를 사용하려면 macOS/Linux에서 :로 구분된 ALLOWED_WORKSPACE_ROOTS를 사용하세요.

모델 서버 시작

Apple Silicon에서 MLX 모델을 사용하는 경우:

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는 config.toml에서 MCP 서버를 자동으로 시작합니다.

Codex MCP 구성

config.example.toml의 local-coder 블록을 Codex config.toml로 복사한 다음, 자리 표시자를 로컬 값으로 바꾸세요:

[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 프로젝트입니다.

일반적인 오류

워크스페이스가 허용된 루트 안에 없는 경우

요청한 워크스페이스가 승인된 디렉터리 안에 있도록 ALLOWED_WORKSPACE_ROOT 또는 ALLOWED_WORKSPACE_ROOTS를 설정하세요. 이는 의도된 동작입니다. 워커가 임의의 로컬 파일을 편집할 수 없어야 합니다.

워커가 최대 단계 수를 초과함

더 큰 작업에는 max_steps를 늘리거나 작업을 더 작은 단계로 나누세요. 좋은 로컬 워커 작업은 구체적이고 검증 가능합니다.

모델이 사용 가능한 텍스트를 반환하지 않음

로컬 모델 서버가 사용 가능한 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 서버를 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