agent-env-mcp

재사용 가능한 Linux 개발 런타임을 소유하고 코딩 에이전트에게 좁은 프로젝트 범위의 작업공간/도구 경계를 노출하는 호스트 측 MCP 컨트롤러입니다.

신뢰 경계

• MCP 프로세스는 Docker를 제어해야 하므로 호스트에서 실행됩니다.

• 모델에는 호스트 파일시스템 도구나 임의의 호스트 명령 도구가 절대 제공되지 않습니다.

• VS Code는 MCP 시작 시 현재 열려 있는 작업공간을 AGENT_HOST_WORKSPACE를 통해 한 번 전달합니다.

• 해당 작업공간은 /agent-env/environment/<project-slug>에 있는 에이전트가 소유한 런타임에 바인드 마운트됩니다.

• 파일 읽기, 검색, 편집, 로컬 Git, 빌드, 테스트 및 기타 명령 실행은 Linux agent 컨테이너 내부에서 이루어집니다.

• 런타임에는 Docker 소켓도 GitHub 자격 증명 마운트도 없습니다.

• Compose와 Dockerfile은 애플리케이션 저장소가 아닌 이 저장소가 소유합니다.

노출된 도구

• ensure_environment

• list_directory

• read_file

• search_workspace

• workspace_edit

• run_command

• git_command

run_command는 셸 없이 구조화된 program + args 실행을 사용하며 직접 Git을 거부합니다. git_command는 GitHub Operator를 위한 것으로, 저장소 훅/서명을 비활성화하고 로컬 Git 하위 명령 허용 목록만 허용합니다. 네트워크 Git 작업은 의도적으로 제외됩니다.

설치

cd D:\mcp\agent-env-mcp
npm install

mcp.json.example를 사용하여 VS Code 사용자 MCP 구성에 서버를 추가합니다.

중요한 설정은 다음과 같습니다.

"env": {
  "AGENT_HOST_WORKSPACE": "${workspaceFolder}"
}

MCP 서버가 시작된 후에는 모델이 다른 호스트 작업공간을 선택할 수 없습니다.

검증

MCP 서버를 재시작한 후:

1. ensure_environment

2. list_directory를 path: "."로 실행

3. read_file을 알려진 프로젝트 파일에 대해 실행

4. search_workspace로 알려진 기호/텍스트를 검색

5. run_command를 program: "pwd"로 실행

6. git_command를 args: ["status", "--short"]로 실행

예상되는 경계 실패:

• read_file("../../anything")

• 절대 경로

• Windows 경로

• 직접 .git 읽기

• run_command를 bash로 실행

• run_command를 docker로 실행

• run_command를 git으로 실행

마이그레이션

새 런타임이 검증된 후:

1. 프로젝트 소유의 .devcontainer를 제거합니다.

2. Software Engineer에서 일반적인 VS Code execute, read, edit, search를 제거합니다.

3. 엄격한 컨테이너 전용 읽기 경계를 위해 agent-env 외부의 소스를 검사하는 VS Code C/C++ 시맨틱 도구도 제거합니다.

4. GitHub Operator에게 로컬 Git용 agent-env/git_command를 제공합니다.

5. 원격 GitHub 작업은 GitHub MCP에 유지합니다.

런타임 기본 구성

포함된 Dockerfile은 Node 24 LTS, C/C++ 빌드 도구, Python, PlatformIO 6.1.19, Git 및 ripgrep을 사용합니다. 런타임 프로필은 신뢰 모델을 변경하지 않고 나중에 분리할 수 있습니다.