Local Coder MCP Agent

このプロジェクトは、ローカルコーディングエージェントのワークフローをパッケージしたものです:

1. Qwen コーディングモデルが、OpenAI 互換の /v1/chat/completions API の背後でローカルに実行されます。

2. Python ワーカーは、OpenAI SDK を使用してそのローカル API とやり取りします。

3. local-coder MCP サーバーは delegate_to_local_coder を Codex に公開します。

4. Codex は実装タスクをローカルワーカーに委任し、テストと diff は 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_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

http://127.0.0.1:8080/v1/chat/completions を公開する OpenAI 互換サーバーであればどれでも動作します。または 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