컨테이너-MCP
대규모 언어 모델을 대신하여 도구를 실행하기 위한 모델 컨텍스트 프로토콜(MCP)의 안전한 컨테이너 기반 구현입니다.
개요
컨테이너-MCP는 코드 실행, 명령 실행, 파일 접근, 그리고 대규모 언어 모델에서 요청한 웹 작업을 안전하게 수행할 수 있는 샌드박스 환경을 제공합니다. MCP 프로토콜을 구현하여 이러한 기능을 AI 시스템이 안전하게 검색하고 호출할 수 있는 도구로 제공합니다.
이 아키텍처는 적절한 제한 사항이 있는 격리된 환경에서 도구가 실행되도록 보장하고 호스트 시스템을 잠재적으로 유해한 작업으로부터 보호하기 위해 다중 계층 보안을 갖춘 도메인별 관리자 패턴을 사용합니다.
주요 특징
- 다층 보안
- Podman/Docker를 사용한 컨테이너 격리
- 액세스 제한을 위한 AppArmor 프로필
- 추가 격리를 위한 Firejail 샌드박싱
- 리소스 제한(CPU, 메모리, 실행 시간)
- 경로 탐색 방지
- 허용된 확장 제한
- MCP 프로토콜 구현
- 표준화된 도구 발견 및 실행
- 자원 관리
- 비동기 실행 지원
- 도메인별 관리자
BashManager : 안전한 명령 실행PythonManager : 샌드박스 Python 코드 실행FileManager : 안전한 파일 작업WebManager : 안전한 웹 브라우징 및 스크래핑
- 구성 가능한 환경
- 환경 변수를 통한 광범위한 구성
- 사용자 정의 환경 지원
- 개발 및 생산 모드
사용 가능한 도구
시스템 운영
system_run_command
안전한 샌드박스 환경에서 bash 명령을 실행합니다.
- 매개변수 :
command (문자열, 필수): 실행할 bash 명령working_dir (문자열, 선택 사항): 작업 디렉토리(샌드박스에서는 무시됨)
- 반품 :
stdout (문자열): 명령 표준 출력stderr (문자열): 명령 표준 오류exit_code (정수): 명령 종료 코드success (부울): 명령이 성공적으로 완료되었는지 여부
지엑스피1
system_run_python
안전한 샌드박스 환경에서 Python 코드를 실행합니다.
- 매개변수 :
code (문자열, 필수): 실행할 Python 코드working_dir (문자열, 선택 사항): 작업 디렉토리(샌드박스에서는 무시됨)
- 반품 :
output (문자열): 코드에서 출력을 인쇄합니다.error (문자열): 코드에서 출력된 오류result (any): 선택적 반환 값(코드가 _ 변수를 설정하는 경우 사용 가능)success (부울): 코드가 성공적으로 실행되었는지 여부
{
"output": "Hello, world!\n",
"error": "",
"result": 42,
"success": true
}
system_env_var
환경 변수 값을 가져옵니다.
- 매개변수 :
var_name (문자열, 선택 사항): 검색할 특정 변수
- 반품 :
variables (객체): 환경 변수 사전requested_var (문자열): 요청된 변수의 값(var_name이 제공된 경우)
{
"variables": {
"MCP_PORT": "8000",
"SANDBOX_ROOT": "/app/sandbox"
},
"requested_var": "8000"
}
파일 작업
file_read
파일 내용을 안전하게 읽습니다.
- 매개변수 :
path (문자열, 필수): 파일 경로(샌드박스 루트를 기준으로 함)encoding (문자열, 선택 사항): 파일 인코딩(기본값: "utf-8")
- 반품 :
content (문자열): 파일 내용size (정수): 파일 크기(바이트)modified (float): 마지막 수정 타임스탬프success (부울): 읽기가 성공했는지 여부
{
"content": "This is the content of the file.",
"size": 31,
"modified": 1673452800.0,
"success": true
}
file_write
내용을 안전하게 파일에 씁니다.
- 매개변수 :
path (문자열, 필수): 파일 경로(샌드박스 루트를 기준으로 함)content (문자열, 필수): 작성할 콘텐츠encoding (문자열, 선택 사항): 파일 인코딩(기본값: "utf-8")
- 반품 :
success (부울): 쓰기가 성공했는지 여부path (문자열): 작성된 파일의 경로
{
"success": true,
"path": "data/myfile.txt"
}
file_list
디렉토리의 내용을 안전하게 나열합니다.
- 매개변수 :
path (문자열, 선택 사항): 디렉토리 경로(기본값: "/")pattern (문자열, 선택 사항): 파일을 필터링할 Glob 패턴
- 반품 :
entries (배열): 메타데이터가 포함된 디렉토리 항목 목록path (문자열): 나열된 디렉토리 경로success (부울): 목록이 성공했는지 여부
{
"entries": [
{
"name": "file1.txt",
"path": "file1.txt",
"is_directory": false,
"size": 1024,
"modified": 1673452800.0
},
{
"name": "data",
"path": "data",
"is_directory": true,
"size": null,
"modified": 1673452500.0
}
],
"path": "/",
"success": true
}
file_delete
파일을 안전하게 삭제합니다.
- 매개변수 :
path (문자열, 필수): 삭제할 파일의 경로
- 반품 :
success (부울): 삭제가 성공했는지 여부path (문자열): 삭제된 파일의 경로
{
"success": true,
"path": "temp/old_file.txt"
}
file_move
파일을 안전하게 이동하거나 이름을 변경합니다.
- 매개변수 :
source (문자열, 필수): 소스 파일 경로destination (문자열, 필수): 대상 파일 경로
- 반품 :
success (부울): 이동이 성공했는지 여부source (문자열): 원본 파일 경로destination (문자열): 새 파일 경로
{
"success": true,
"source": "data/old_name.txt",
"destination": "data/new_name.txt"
}
웹 운영
web_search
검색 엔진을 사용하여 웹에서 정보를 찾습니다.
- 매개변수 :
- 반품 :
results (배열): 검색 결과 목록query (문자열): 원래 쿼리
{
"results": [
{
"title": "Search Result Title",
"url": "https://example.com/page1",
"snippet": "Text snippet from the search result..."
}
],
"query": "example search query"
}
web_scrape
특정 URL을 스크래핑하여 콘텐츠를 반환합니다.
- 매개변수 :
url (문자열, 필수): 스크래핑할 URLselector (문자열, 선택 사항): 특정 콘텐츠를 타겟으로 하는 CSS 선택기
- 반품 :
content (문자열): 스크래핑된 콘텐츠url (문자열): 스크래핑된 URLtitle (문자열): 페이지 제목success (부울): 스크래핑이 성공했는지 여부error (문자열): 스크래핑에 실패하면 발생하는 오류 메시지
{
"content": "This is the content of the web page...",
"url": "https://example.com/page",
"title": "Example Page",
"success": true,
"error": null
}
web_browse
Playwright를 사용하여 웹사이트를 대화형으로 탐색합니다.
- 매개변수 :
url (문자열, 필수): 탐색 세션의 시작 URL
- 반품 :
content (문자열): 페이지 HTML 콘텐츠url (문자열): 리디렉션 후 최종 URLtitle (문자열): 페이지 제목success (부울): 검색이 성공했는지 여부error (문자열): 검색에 실패한 경우 오류 메시지
{
"content": "<!DOCTYPE html><html>...</html>",
"url": "https://example.com/after_redirect",
"title": "Example Page",
"success": true,
"error": null
}
실행 환경
컨테이너-MCP는 다양한 유형의 작업에 대해 격리된 실행 환경을 제공하며, 각 작업마다 고유한 보안 조치와 리소스 제약이 있습니다.
컨테이너 환경
주요 컨테이너-MCP 서비스는 컨테이너 내부에서 실행되며(Podman 또는 Docker 사용) 첫 번째 격리 계층을 제공합니다.
- 기본 이미지 : Ubuntu 24.04
- 사용자 : 루트가 아닌 ubuntu 사용자
- 파이썬 : 3.12
- 네트워크 : 로컬호스트 바인딩으로만 제한됨
- 파일 시스템 : 구성, 데이터 및 로그에 대한 볼륨 마운트
- 보안 : AppArmor, Seccomp 및 기능 제한
Bash 실행 환경
Bash 실행 환경은 여러 개의 격리 계층으로 구성됩니다.
- 허용된 명령 :
BASH_ALLOWED_COMMANDS 에 구성된 안전한 명령으로 제한됨 - Firejail Sandbox : 제한된 파일 시스템 액세스를 통한 프로세스 격리
- AppArmor 프로필 : 세분화된 액세스 제어
- 리소스 제한 :
- 실행 시간 초과(기본값: 30초, 최대값: 120초)
- 샌드박스에만 제한된 디렉토리 액세스
- 네트워크 : 네트워크 접속 불가
- 파일 시스템 : 데이터에 대한 읽기 전용 액세스, 샌드박스에 대한 읽기-쓰기
허용되는 명령의 예:
ls, cat, grep, find, echo, pwd, mkdir, touch
Python 실행 환경
Python 실행 환경은 안전한 코드 실행을 위해 설계되었습니다.
- 파이썬 버전 : 3.12
- 메모리 제한 : 구성 가능한 메모리 상한(기본값: 256MB)
- 실행 시간 제한 : 설정 가능한 시간 제한(기본값: 30초, 최대값: 120초)
- AppArmor 프로필 : 시스템 리소스에 대한 액세스를 제한합니다.
- Firejail Sandbox : 프로세스 격리
- 기능 : 모든 기능이 삭제되었습니다.
- 네트워크 : 네트워크 접속 불가
- 사용 가능한 라이브러리 : 표준 라이브러리만
- 출력 캡처 : stdout/stderr 리디렉션 및 정리
- 리소스 제어 : CPU 및 메모리 제한 적용
파일 시스템 환경
파일 시스템 환경은 샌드박스 내의 파일에 대한 액세스를 제어합니다.
- 기본 디렉토리 : 모든 작업은 샌드박스 루트로 제한됨
- 경로 검증 : 모든 경로가 정규화되고 횡단 시도가 확인됨
- 크기 제한 : 최대 파일 크기 적용(기본값: 10MB)
- 확장자 제어 : 허용된 확장자만 허용(기본값: txt, md, csv, json, py)
- 권한 제어 : 적절한 읽기/쓰기 권한 적용
- 격리 : 호스트 파일 시스템에 액세스할 수 없음
웹 환경
웹 환경은 외부 리소스에 대한 통제된 액세스를 제공합니다.
- 도메인 제어 : 허용된 도메인의 선택적 화이트리스트
- 시간 초과 제어 : 작업에 대한 구성 가능한 시간 초과
- 브라우저 제어 : Playwright를 통한 헤드리스 브라우저로 전체 렌더링 가능
- 스크래핑 제어 : requests/BeautifulSoup를 통한 간단한 스크래핑
- 콘텐츠 정리 : 모든 콘텐츠가 구문 분석되고 정리됨
- 네트워크 격리 : 컨테이너를 통해 네트워크 네임스페이스 분리
건축학
이 프로젝트는 모듈식 아키텍처를 따릅니다.
container-mcp/
├── cmcp/ # Main application code
│ ├── managers/ # Domain-specific managers
│ │ ├── bash_manager.py # Secure bash execution
│ │ ├── python_manager.py # Secure python execution
│ │ ├── file_manager.py # Secure file operations
│ │ └── web_manager.py # Secure web operations
│ ├── utils/ # Utility functions
│ ├── config.py # Configuration system
│ └── main.py # MCP server setup
├── apparmor/ # AppArmor profiles
├── config/ # Configuration files
├── bin/ # Build/run scripts
├── data/ # Data directory
├── logs/ # Log directory
├── sandbox/ # Sandboxed execution space
│ ├── bash/ # Bash sandbox
│ ├── python/ # Python sandbox
│ ├── files/ # File operation sandbox
│ └── browser/ # Web browser sandbox
├── temp/ # Temporary storage
└── tests/ # Test suites
각 관리자는 일관된 디자인 패턴을 따릅니다.
- 환경 기반 초기화를 위한
.from_env() 클래스 메서드 - 비차단 작업을 위한 비동기 실행 방법
- 강력한 입력 검증 및 오류 처리
- 모든 작업에 대한 보안 우선 접근 방식
보안 조치
컨테이너-MCP는 여러 계층의 보안을 구현합니다.
- 컨테이너 격리 : 컨테이너 격리를 위해 Podman/Docker 사용
- AppArmor 프로필 : bash 및 Python 실행을 위한 세분화된 액세스 제어
- Firejail 샌드박싱 : 추가 프로세스 격리
- 리소스 제한 : 메모리, CPU 및 실행 시간 제한
- 경로 탐색 방지 : 모든 파일 경로를 검증하고 정규화합니다.
- 허용된 확장자 제한 : 액세스할 수 있는 파일 유형을 제어합니다.
- 네트워크 제한 : 액세스할 수 있는 도메인을 제어합니다.
- 최소 권한 : 구성 요소는 최소한의 필수 권한으로 실행됩니다.
설치
필수 조건
- Podman 또는 Docker를 사용한 Linux 시스템
- 파이썬 3.12+
- Firejail (
apt install firejail 또는 dnf install firejail ) - AppArmor(
apt install apparmor apparmor-utils 또는 dnf install apparmor apparmor-utils )
빠른 시작
가장 빠르게 시작하는 방법은 올인원 스크립트를 사용하는 것입니다.
git clone https://github.com/54rt1n/container-mcp.git
cd container-mcp
chmod +x bin/00-all-in-one.sh
./bin/00-all-in-one.sh
단계별 설치
설치 단계를 개별적으로 수행할 수도 있습니다.
- 프로젝트 초기화 :
- 컨테이너를 빌드하세요 :
./bin/02-build-container.sh
- 환경 설정 :
./bin/03-setup-environment.sh
- 컨테이너를 실행합니다 .
./bin/04-run-container.sh
- 테스트 실행 (선택 사항):
용법
컨테이너가 실행되면 MCP 클라이언트 구현을 사용하여 연결할 수 있습니다. 서버는 http://localhost:8000 또는 구성에 지정된 포트에서 사용할 수 있습니다.
중요: MCP 클라이언트를 구성할 때 엔드포인트 URL을 http://127.0.0.1:<port>/sse 로 설정해야 합니다( <port> 는 기본적으로 8000이거나 사용자가 설정한 포트입니다). 서버에서 전송된 이벤트(SES)의 원활한 통신을 위해서는 /sse 경로가 필요합니다.
Python 클라이언트 예제
from mcp.client.sse import sse_client
from mcp import ClientSession
import asyncio
async def main():
# Connect to the Container-MCP server
# Note the /sse endpoint suffix required for SSE communication
sse_url = "http://127.0.0.1:8000/sse" # Or your configured port
# Connect to the SSE endpoint
async with sse_client(sse_url) as (read, write):
async with ClientSession(read, write) as session:
# Initialize the connection
await session.initialize()
# Discover available tools
result = await session.list_tools()
print(f"Available tools: {[tool.name for tool in result.tools]}")
# Execute a Python script
python_result = await session.execute_tool(
"system_run_python",
{"code": "print('Hello, world!')\nresult = 42\n_ = result"}
)
print(f"Python result: {python_result}")
# Execute a bash command
bash_result = await session.execute_tool(
"system_run_command",
{"command": "ls -la"}
)
print(f"Command output: {bash_result['stdout']}")
if __name__ == "__main__":
asyncio.run(main())
구성
Container-MCP는 환경 변수를 통해 구성할 수 있으며, 이 환경 변수는 volume/config/custom.env 에서 설정할 수 있습니다.
서버 구성
# MCP Server Configuration
MCP_HOST=127.0.0.1
MCP_PORT=9001
DEBUG=true
LOG_LEVEL=INFO
Bash 관리자 구성
# Bash Manager Configuration
BASH_ALLOWED_COMMANDS=ls,cat,grep,find,echo,pwd,mkdir,touch
BASH_TIMEOUT_DEFAULT=30
BASH_TIMEOUT_MAX=120
Python 관리자 구성
# Python Manager Configuration
PYTHON_MEMORY_LIMIT=256
PYTHON_TIMEOUT_DEFAULT=30
PYTHON_TIMEOUT_MAX=120
파일 관리자 구성
# File Manager Configuration
FILE_MAX_SIZE_MB=10
FILE_ALLOWED_EXTENSIONS=txt,md,csv,json,py
웹 관리자 구성
# Web Manager Configuration
WEB_TIMEOUT_DEFAULT=30
WEB_ALLOWED_DOMAINS=*
개발
개발 환경 설정
- Python 가상 환경을 만듭니다.
python3.12 -m venv .venv
source .venv/bin/activate
- 종속성 설치:
pip install -r requirements-dev.txt
- 개발 모드에서 패키지를 설치하세요:
테스트 실행
# Run all tests
pytest
# Run only unit tests
pytest tests/unit
# Run only integration tests
pytest tests/integration
# Run with coverage report
pytest --cov=cmcp --cov-report=term --cov-report=html
개발 서버
개발 모드에서 MCP 서버를 실행하려면:
python -m cmcp.main --test-mode
특허
이 프로젝트는 Apache License 2.0에 따라 라이선스가 부여되었습니다.
작가
마틴 부코스키