Container-MCP

A secure, container-based implementation of the Model Context Protocol (MCP) for executing tools on behalf of large language models.

Overview

Container-MCP provides a sandboxed environment for safely executing code, running commands, accessing files, and performing web operations requested by large language models. It implements the MCP protocol to expose these capabilities as tools that can be discovered and called by AI systems in a secure manner.

The architecture uses a domain-specific manager pattern with multi-layered security to ensure tools execute in isolated environments with appropriate restrictions, protecting the host system from potentially harmful operations.

Key Features

- Multi-layered Security
- Container isolation using Podman/Docker
- AppArmor profiles for restricting access
- Firejail sandboxing for additional isolation
- Resource limits (CPU, memory, execution time)
- Path traversal prevention
- Allowed extension restrictions

- MCP Protocol Implementation
- Standardized tool discovery and execution
- Resource management
- Async execution support

- Domain-Specific Managers
- BashManager: Secure command execution
- PythonManager: Sandboxed Python code execution
- FileManager: Safe file operations
- WebManager: Secure web browsing and scraping
- KnowledgeBaseManager: Structured document storage with semantic search
- ListManager: Organized list and collection management
- MarketManager: Stock and cryptocurrency data via Yahoo Finance
- RssManager: RSS and Atom feed fetching

- Configurable Environment
- Extensive configuration via environment variables
- Custom environment support
- Development and production modes

Available Tools

System Operations

system_run_command

- Parameters:
- command (string, required): The bash command to execute
- working_dir (string, optional): Working directory (ignored in sandbox)
- Returns:
- stdout (string): Command standard output
- stderr (string): Command standard error
- exit_code (integer): Command exit code
- success (boolean): Whether command completed successfully

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

system_run_python

- Parameters:
- code (string, required): Python code to execute
- working_dir (string, optional): Working directory (ignored in sandbox)
- Returns:
- output (string): Print output from the code
- error (string): Error output from the code
- result (any): Optional return value (available if code sets _ variable)
- success (boolean): Whether code executed successfully

{
  "output": "Hello, world!\n",
  "error": "",
  "result": 42,
  "success": true
}

system_env_var

- Parameters:
- var_name (string, optional): Specific variable to retrieve
- Returns:
- variables (object): Dictionary of environment variables
- requested_var (string): Value of the requested variable (if var_name provided)

{
  "variables": {
    "MCP_PORT": "8000",
    "SANDBOX_ROOT": "/app/sandbox"
  },
  "requested_var": "8000"
}

health_check

- Parameters: None
- Returns:
- status (string): Server health status
- timestamp (string): Current ISO timestamp
- server (object): Server details (name, host, port, platform, python_version)
- system (object): System metrics (cpu_percent, memory_percent, disk_percent)
- managers (object): Status of each manager (enabled/disabled)

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "server": {
    "name": "Container-MCP",
    "host": "127.0.0.1",
    "port": 9001,
    "platform": "linux",
    "python_version": "3.12.0"
  },
  "system": {
    "cpu_percent": 12.5,
    "memory_percent": 45.2,
    "disk_percent": 67.8
  },
  "managers": {
    "bash": "enabled",
    "python": "enabled",
    "file": "enabled",
    "web": "enabled",
    "kb": "enabled",
    "list": "enabled",
    "market": "enabled",
    "rss": "enabled"
  }
}

File Operations

fs_read

- Parameters:
- path (string, required): Path to the file (relative to sandbox root)
- encoding (string, optional): File encoding (default: "utf-8")
- Returns:
- content (string): File content
- size (integer): File size in bytes
- modified (float): Last modified timestamp
- success (boolean): Whether the read was successful

{
  "content": "This is the content of the file.",
  "size": 31,
  "modified": 1673452800.0,
  "success": true
}

fs_write

- Parameters:
- path (string, required): Path to the file (relative to sandbox root)
- content (string, required): Content to write
- encoding (string, optional): File encoding (default: "utf-8")
- Returns:
- success (boolean): Whether the write was successful
- path (string): Path to the written file

{
  "success": true,
  "path": "data/myfile.txt"
}

fs_list

- Parameters:
- path (string, optional): Path to the directory (default: "/")
- pattern (string, optional): Glob pattern to filter files
- recursive (boolean, optional): Whether to list recursively (default: true)
- Returns:
- entries (array): List of directory entries with metadata
- path (string): The listed directory path
- success (boolean): Whether the listing was successful

{
  "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
}

fs_delete

- Parameters:
- path (string, required): Path of the file to delete
- Returns:
- success (boolean): Whether the deletion was successful
- path (string): Path to the deleted file

{
  "success": true,
  "path": "temp/old_file.txt"
}

fs_move

- Parameters:
- source_path (string, required): Source file path
- destination_path (string, required): Destination file path
- Returns:
- success (boolean): Whether the move was successful
- source_path (string): Original file path
- destination_path (string): New file path

{
  "success": true,
  "source_path": "data/old_name.txt",
  "destination_path": "data/new_name.txt"
}

fs_apply_diff

- Parameters:
- path (string, required): Path to the file to patch (relative to sandbox root)
- diff (string, required): Unified diff content to apply
- Returns:
- success (boolean): Whether the patch was applied successfully
- path (string): Path to the patched file
- lines_applied (integer): Number of lines changed
- new_size (integer): New file size in bytes
- error (string): Error message if patch failed

{
  "success": true,
  "path": "src/main.py",
  "lines_applied": 5,
  "new_size": 1248,
  "error": null
}

Web Operations

web_search

- Parameters:
- query (string, required): The query to search for
- Returns:
- results (array): List of search results
- query (string): The original query

{
  "results": [
    {
      "title": "Search Result Title",
      "url": "https://example.com/page1",
      "snippet": "Text snippet from the search result..."
    }
  ],
  "query": "example search query"
}

web_scrape

- Parameters:
- url (string, required): The URL to scrape
- selector (string, optional): CSS selector to target specific content
- output_format (string, optional): Use "markdown" to return Markdown (preserves links). Default is plain text.
- Returns:
- content (string): Scraped content
- url (string): The URL that was scraped
- title (string): Page title
- success (boolean): Whether the scrape was successful
- error (string): Error message if scrape failed

{
  "content": "This is the content of the web page...",
  "url": "https://example.com/page",
  "title": "Example Page",
  "success": true,
  "error": null
}

Markdown output example:

{
  "content": "This is a link in Markdown...",
  "url": "https://example.com/page",
  "title": "Example Page",
  "success": true,
  "error": null
}

web_browse