컨테이너-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`

검색 엔진을 사용하여 웹에서 정보를 찾습니다.

매개변수 :
- query (문자열, 필수): 검색할 쿼리
반품 :
- 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 (문자열, 필수): 스크래핑할 URL
- selector (문자열, 선택 사항): 특정 콘텐츠를 타겟으로 하는 CSS 선택기
반품 :
- content (문자열): 스크래핑된 콘텐츠
- url (문자열): 스크래핑된 URL
- title (문자열): 페이지 제목
- 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 (문자열): 리디렉션 후 최종 URL
- title (문자열): 페이지 제목
- 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/container-mcp/container-mcp.git
cd container-mcp
chmod +x bin/00-all-in-one.sh
./bin/00-all-in-one.sh

단계별 설치

설치 단계를 개별적으로 수행할 수도 있습니다.

프로젝트 초기화 :
./bin/01-init.sh
컨테이너를 빌드하세요 :
./bin/02-build-container.sh
환경 설정 :
./bin/03-setup-environment.sh
컨테이너를 실행합니다 .
./bin/04-run-container.sh
테스트 실행 (선택 사항):
./bin/05-run-tests.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
개발 모드에서 패키지를 설치하세요:
pip install -e .

테스트 실행

# 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에 따라 라이선스가 부여되었습니다.

작가

마틴 부코스키

Integrations