集装箱-MCP

模型上下文协议 (MCP) 的安全、基于容器的实现，用于代表大型语言模型执行工具。

概述

Container-MCP 提供了一个沙盒环境，用于安全地执行代码、运行命令、访问文件以及执行大型语言模型请求的 Web 操作。它实现了 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 （布尔值）：命令是否成功完成

{
  "stdout": "file1.txt\nfile2.txt\n",
  "stderr": "",
  "exit_code": 0,
  "success": true
}

`system_run_python`

在安全的沙盒环境中执行 Python 代码。

参数：
- code （字符串，必需）：要执行的 Python 代码
- working_dir （字符串，可选）：工作目录（在沙箱中忽略）
返回：
- output （字符串）：打印代码的输出
- error （字符串）：代码的错误输出
- result （任意）：可选返回值（如果代码设置了_变量则可用）
- 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 （浮点数）：上次修改的时间戳
- 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 操作

`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
}

执行环境

Container-MCP 为不同类型的操作提供隔离的执行环境，每种操作都有自己的安全措施和资源限制。

容器环境

主要的 Container-MCP 服务在容器内运行（使用 Podman 或 Docker），提供第一层隔离：

基础镜像：Ubuntu 24.04
用户：非 root ubuntu 用户
Python ：3.12
网络：仅限于本地主机绑定
文件系统：配置、数据和日志的卷挂载
安全性：AppArmor、Seccomp 和功能限制

Bash 执行环境

Bash 执行环境配置了多个隔离层：

允许的命令：仅限于BASH_ALLOWED_COMMANDS中配置的安全命令
Firejail Sandbox ：通过限制文件系统访问进行进程隔离
AppArmor 配置文件：细粒度访问控制
资源限制：
- 执行超时（默认值：30秒，最大值：120秒）
- 仅限沙盒的目录访问
网络：无网络访问
文件系统：只读访问数据，读写沙箱

允许的命令示例：

ls, cat, grep, find, echo, pwd, mkdir, touch

Python执行环境

Python 执行环境是为安全代码执行而设计的：

Python版本：3.12
内存限制：可配置内存上限（默认值：256MB）
执行超时：可配置的时间限制（默认值：30 秒，最大值：120 秒）
AppArmor 配置文件：限制对系统资源的访问
Firejail Sandbox ：进程隔离
能力：所有能力均被放弃
网络：无网络访问
可用库：仅标准库
输出捕获：stdout/stderr 重定向和清理
资源控制：强制执行 CPU 和内存限制

文件系统环境

文件系统环境控制对沙箱内文件的访问：

基目录：所有操作都限制在沙盒根目录下
路径验证：所有路径均已规范化并检查遍历尝试
大小限制：强制执行最大文件大小（默认值：10MB）
扩展控制：仅允许允许的扩展（默认值：txt，md，csv，json，py）
权限控制：强制适当的读/写权限
隔离：无法访问主机文件系统

Web 环境

Web 环境提供对外部资源的受控访问：

域控制：可选的允许域白名单
超时控制：可配置操作超时
浏览器控制：通过 Playwright 的无头浏览器进行完整渲染
抓取控制：通过请求/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()类方法用于基于环境的初始化
非阻塞操作的异步执行方法
强大的输入验证和错误处理
所有操作均采用安全第一的方法

安全措施

Container-MCP 实现了多层安全性：

容器隔离：使用 Podman/Docker 进行容器隔离
AppArmor 配置文件：针对 bash 和 Python 执行的细粒度访问控制
Firejail 沙盒：额外的进程隔离
资源限制：内存、CPU 和执行时间限制
路径遍历预防：验证并规范所有文件路径
允许的扩展限制：控制可以访问的文件类型
网络限制：控制可以访问哪些域
最小权限：组件以最少的必要权限运行

安装

先决条件

带有 Podman 或 Docker 的 Linux 系统
Python 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 或您配置的端口）。/ /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管理器配置

# 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