Container-MCP

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

概述

Container-MCP 提供了一个沙盒环境，用于安全地执行代码、运行命令、访问文件以及执行大型语言模型请求的 Web 操作。 它实现了 MCP 协议，将这些功能作为工具公开，这些工具可以被 AI 系统以安全的方式发现和调用。

该架构使用具有多层安全性的领域特定管理器模式，以确保工具在具有适当限制的隔离环境中执行，从而保护主机系统免受潜在有害操作的影响。

主要特性

• 多层安全性

  • 使用 Podman/Docker 的容器隔离
  • 用于限制访问的 AppArmor 配置文件
  • 用于额外隔离的 Firejail 沙盒
  • 资源限制（CPU、内存、执行时间）
  • 路径遍历预防
  • 允许的扩展名限制

• MCP 协议实现

  • 标准化的工具发现和执行
  • 资源管理
  • 异步执行支持

• 领域特定管理器

  • BashManager: 安全的命令执行
  • PythonManager: 沙盒化的 Python 代码执行
  • FileManager: 安全的文件操作
  • WebManager: 安全的 Web 浏览和抓取

• 可配置的环境

  • 通过环境变量进行广泛的配置
  • 自定义环境支持
  • 开发和生产模式

可用工具

系统操作

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

使用搜索引擎在 Web 上查找信息。

• 参数:
  • 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
• 网络: 仅限于 localhost 绑定
• 文件系统: 用于配置、数据和日志的卷挂载
• 安全: AppArmor、Seccomp 和功能限制

Bash 执行环境

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

• 允许的命令: 限制为在 BASH_ALLOWED_COMMANDS 中配置的安全命令
• Firejail 沙盒: 进程隔离，具有受限的文件系统访问权限
• AppArmor 配置文件: 细粒度的访问控制
• 资源限制:
  • 执行超时（默认值: 30 秒，最大值: 120 秒）
  • 仅限对沙盒的有限目录访问
• 网络: 没有网络访问权限
• 文件系统: 对数据的只读访问，对沙盒的读写访问

允许的命令示例：

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

Python 执行环境

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

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

文件系统环境

文件系统环境控制对沙盒中文件的访问：

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

Web 环境

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

• 域控制: 可选的允许域白名单
• 超时控制: 可配置的操作超时
• 浏览器控制: 通过 Playwright 的无头浏览器进行完整渲染
• 抓取控制: 通过 requests/BeautifulSoup 进行简单抓取
• 内容清理: 所有内容都经过解析和清理
• 网络隔离: 通过容器的单独网络命名空间

架构

该项目遵循模块化架构：

container-mcp/
├── cmcp/                     # 主要应用程序代码
│   ├── managers/             # 领域特定管理器
│   │   ├── bash_manager.py   # 安全的 bash 执行
│   │   ├── python_manager.py # 安全的 python 执行
│   │   ├── file_manager.py   # 安全的文件操作
│   │   └── web_manager.py    # 安全的 web 操作
│   ├── utils/                # 实用程序函数
│   ├── config.py             # 配置系统
│   └── main.py               # MCP 服务器设置
├── apparmor/                 # AppArmor 配置文件
├── config/                   # 配置文件
├── bin/                      # 构建/运行脚本
├── data/                     # 数据目录
├── logs/                     # 日志目录
├── sandbox/                  # 沙盒化的执行空间
│   ├── bash/                 # Bash 沙盒
│   ├── python/               # Python 沙盒
│   ├── files/                # 文件操作沙盒
│   └── browser/              # Web 浏览器沙盒
├── temp/                     # 临时存储
└── tests/                    # 测试套件

每个管理器都遵循一致的设计模式：

• 用于基于环境初始化的 .from_env() 类方法
• 用于非阻塞操作的异步执行方法
• 强大的输入验证和错误处理
• 所有操作都采用安全第一的方法

安全措施

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

1. 容器隔离: 使用 Podman/Docker 进行容器隔离
2. AppArmor 配置文件: 用于 bash 和 Python 执行的细粒度访问控制
3. Firejail 沙盒: 额外的进程隔离
4. 资源限制: 内存、CPU 和执行时间限制
5. 路径遍历预防: 验证和规范化所有文件路径
6. 允许的扩展名限制: 控制可以访问的文件类型
7. 网络限制: 控制可以访问的域
8. 最小权限: 组件以最小的必要权限运行

安装

前提条件

• 具有 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

分步安装

您也可以单独执行安装步骤：

1. 初始化项目:

   ./bin/01-init.sh
   

2. 构建容器:

   ./bin/02-build-container.sh
   

3. 设置环境:

   ./bin/03-setup-environment.sh
   

4. 运行容器:

   ./bin/04-run-container.sh
   

5. 运行测试 (可选):

   ./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 服务器配置
MCP_HOST=127.0.0.1
MCP_PORT=9001
DEBUG=true
LOG_LEVEL=INFO

Bash 管理器配置

# Bash 管理器配置
BASH_ALLOWED_COMMANDS=ls,cat,grep,find,echo,pwd,mkdir,touch
BASH_TIMEOUT_DEFAULT=30
BASH_TIMEOUT_MAX=120

Python 管理器配置

# Python 管理器配置
PYTHON_MEMORY_LIMIT=256
PYTHON_TIMEOUT_DEFAULT=30
PYTHON_TIMEOUT_MAX=120

文件管理器配置

# 文件管理器配置
FILE_MAX_SIZE_MB=10
FILE_ALLOWED_EXTENSIONS=txt,md,csv,json,py

Web 管理器配置

# Web 管理器配置
WEB_TIMEOUT_DEFAULT=30
WEB_ALLOWED_DOMAINS=*

开发

设置开发环境

1. 创建 Python 虚拟环境：

   python3.12 -m venv .venv
   source .venv/bin/activate
   

2. 安装依赖项：

   pip install -r requirements-dev.txt
   

3. 以开发模式安装软件包：

   pip install -e .
   

运行测试

# 运行所有测试
pytest

# 仅运行单元测试
pytest tests/unit

# 仅运行集成测试
pytest tests/integration

# 运行并生成覆盖率报告
pytest --cov=cmcp --cov-report=term --cov-report=html

开发服务器

要在开发模式下运行 MCP 服务器：

python -m cmcp.main --test-mode

许可证

该项目已获得 Apache License 2.0 许可。

作者

Martin Bukowski