Secure Agent Workspace

🛡️ Agent Workspace MCP 服务

一个统一的模型上下文协议（MCP）服务，为大语言模型（LLM）提供高度安全、容器化的工作区。它是一个隔离的“Agent 游乐场”，Agent 可以在其中自主编写代码、测试和调试，而无需担心危及宿主机。

---

✨ 功能

• 🏗️ 完整的项目生命周期：使用 uv init 初始化项目，使用 uv add 管理依赖项，并通过 uv run 执行。
• 🐚 安全的 Bash 访问：执行 Shell 命令时强制设置超时时间，并合并输出流。
• 🚀 针对令牌优化的输出：集成 RTK（Rust Token Killer），自动过滤并压缩 run_bash 输出（例如 ls、git 和测试运行器的输出），节省 60-90% 的大模型上下文令牌。
• 📂 稳健的文件系统：对工作区中的读取、写入和搜索操作提供路径遍历保护。
• 🛡️ 多层安全防护：以非 root 用户身份运行、移除权限、限制资源，并将根文件系统设为只读。
• ⚡ 精准编辑：高级 search_and_replace 工具支持模糊空白匹配、保留缩进、试运行，以及对 Python、JSON、JSONL、TOML 和 YAML 的语法验证。
• 📊 实时可观测性：直接向 MCP 客户端 UI 写入日志，并持久化滚动审计日志。

---

🏗️ 架构

flowchart TD
    Client["MCP Client (Claude / Cursor)"] -- "stdio (JSON-RPC)" --> FastMCP["FastMCP Server"]

    subgraph Sandbox ["Docker Sandbox Container (mcpuser)"]
        direction TB
        
        FastMCP -. "Intercepts accidental prints" .-> StdioGuard["StdoutRedirector"]
        FastMCP -. "Application Logs" .-> Logger["Dual Logger (stderr & .mcp/server.log)"]
        
        FastMCP -- "Tool Calls" --> SecurityGuard["Security & Path Validator"]
        
        subgraph Toolset ["Tool Modules"]
            direction TB
            SecurityGuard --> FSTools["Filesystem (read, write, list, search)"]
            SecurityGuard --> EditTools["Editing (search_and_replace)"]
            SecurityGuard --> ExecTools["Execution (run_bash)"]
        end

        EditTools -- "AST Verification" --> Validator["Syntax Validations (Python, JSON, JSONL, TOML, YAML)"]
        ExecTools -- "Process Group (Timeout=60s)" --> Shell["/bin/sh Subprocess"]
        Shell -- "Package Mgt & Checks" --> UV["uv Environment / Ruff"]
        
        FSTools -- "Secure I/O" --> Workspace["/workspace Directory"]
        EditTools -- "Atomic Writes" --> Workspace
        Shell -- "Executes within" --> Workspace
    end

    Workspace <--"Volume Mount"--> HostFS["User Host Filesystem"]

---

📦 快速开始

1. 拉取或构建 Docker 镜像

# Pull from GHCR
docker pull ghcr.io/hrrodan/agent-workspace-mcp:latest

# OR: Build locally with your host's UID/GID for optimal permissions
docker build --build-arg UID=$(id -u) --build-arg GID=$(id -g) -t agent-workspace-mcp .

2. 编程方式使用（OpenAI Agents SDK）

以下是一个快速入门示例，演示如何通过标准的 openai-agents SDK 以编程方式使用容器化工作区：

import asyncio
from agents import Agent, Runner
from agents.mcp import MCPServerStdio

async def main():
    # 1. Configure the MCP Server to run via Docker
    server = MCPServerStdio(
        name="Sandboxed Workspace",
        params={
            "command": "docker",
            "args": [
                "run", "-i", "--rm", "--init",
                # "--network", "none", # Network Isolation (optional) - see below
                "--memory=2g", "--cpus=2.0",
                "--pids-limit=256",
                "--cap-drop=ALL", "--security-opt=no-new-privileges:true",
                "--read-only",
                "--tmpfs", "/tmp:size=64m",
                "--tmpfs", "/home/mcpuser/.cache:size=512m",
                "--user", "1000:1000", # Replace with your host UID:GID
                "-v", "/path/to/your/projects:/workspace",
                "ghcr.io/hrrodan/agent-workspace-mcp:latest",
            ],
        },
        client_session_timeout_seconds=60.0,
    )

    # 2. Attach server to the Agent and load the skill instructions (optional)
    with open("skills/agent-workspace-mcp/SKILL.md", "r") as f:
        skill_instructions = f.read()

    agent = Agent(
        name="WorkspaceAgent",
        instructions=f"You are a coding agent with access to a secure workspace.\n\n{skill_instructions}",
        mcp_servers=[server],
    )

    # 3. Execute a workflow
    async with server:
        result = await Runner.run(
            agent, 
            "Create a python script in the workspace to print the first 10 Fibonacci numbers, then run it."
        )
        print(f"Agent's Final Output:\n{result.final_output}")

if __name__ == "__main__":
    asyncio.run(main())

3. 与 MCP 客户端搭配使用（Claude / Cursor）

将以下配置添加到 claude_desktop_config.json 或 Cursor 设置中。

{
  "mcpServers": {
    "agent-workspace-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--init",
        // "--network", "none", // Network Isolation (optional) - see below
        "--memory=2g", "--cpus=2.0",
        "--pids-limit=256",
        "--cap-drop=ALL", "--security-opt=no-new-privileges:true",
        "--read-only",
        "--tmpfs", "/tmp:size=64m",
        "--tmpfs", "/home/mcpuser/.cache:size=512m",
        "--user", "1000:1000",
        "-v", "/path/to/your/projects:/workspace",
        "ghcr.io/hrrodan/agent-workspace-mcp:latest"
      ]
    }
  }
}

重要

Linux 用户： 将 1000:1000 替换为你的实际 UID:GID（运行 id -u 和 id -g 获取）。Claude Desktop 不会展开环境变量。 信号处理： --init 标志对于正确转发信号和回收僵尸进程至关重要。

---

🛠️ 工具参考

工具	描述
read_file	读取文本文件，可选设置 offset 和 limit（默认：100 行）。
write_file	创建文件，并进行语法验证和5MB 大小限制。默认情况下拒绝覆盖现有文件（create_only=True）。
list_directory	列出内容，并使用 [F] 表示文件、[D] 表示目录。
search_workspace	按 glob 模式查找文件，支持 exclude_patterns。
run_bash	在 /workspace 中执行 Shell 命令，超时时间为 60s。通过 RTK 自动优化，以减少令牌用量。
search_and_replace	多处编辑工具，支持模糊空白匹配、保留缩进、试运行模式，以及语法验证（Python、JSON、JSONL、TOML、YAML）。

---

⚙️ 配置

服务支持以下环境变量（通过 Docker --env 传入）：

变量	默认值	描述
COMMAND_TIMEOUT	60	run_bash 终止进程前的默认秒数。
MAX_SEARCH_RESULTS	50	search_workspace 返回的最大结果数。
MAX_READ_SIZE_BYTES	1048576	read_file 可读取的最大文件大小（1MB）。
MAX_WRITE_SIZE_BYTES	5242880	write_file 可写入的最大文件大小（5MB）。
LOG_LEVEL	INFO	Python 日志级别（DEBUG、INFO 等）。

---

🛡️ 安全与架构模型

此服务采用纵深防御策略，明确区分严格的安全边界与开发者体验和运行可靠性功能。

🔒 核心安全功能

这些功能旨在保护宿主系统并强制执行严格的隔离边界。

• 内核加固：丢弃所有 Linux capabilities（--cap-drop=ALL），消除权限提升途径。
• 不可变的服务代码：包含服务源代码及其虚拟环境的 /app 目录归 root 所有，且对 mcpuser 只读。这可防止服务修改自身，或通过 run_bash 篡改自身。
• 权限锁定：强制启用 no-new-privileges:true，防止任何进程获得更高权限。
• 不可变的系统核心：容器的根文件系统整体以只读方式挂载，为防范操作系统层面的篡改提供第二道防线。
• 资源配额：对 CPU、内存和 PID 实施硬性限制，以缓解 fork 炸弹和耗尽宿主资源等拒绝服务（DoS）攻击。
• 严格的边界执行：强大的路径验证器会全面阻止对指定 /workspace 之外路径的遍历攻击。
• 进程与资源控制：强制设置命令超时（默认为 60s），并严格隔离进程组，以确保终止失控或恶意进程。
• 内存过载防护：对文件读取（1MB）和命令输出（50KB）设置硬性限制，以防止内存耗尽。
• 防止信息泄露：抑制并清理工具输出中的内部堆栈跟踪和系统路径。

🛠️ 开发者体验与便利性

专注于无缝集成、易用性以及减少 Agent 工作流阻力的功能。

• 与宿主对齐的非 root 身份：以 mcpuser 身份运行，UID/GID 可在构建时自定义，避免在宿主卷挂载时出现繁琐的文件权限冲突。
• 自动优化令牌用量：通过 run_bash 执行的 Shell 命令会透明地经由 RTK 重写，从而提供超精简、适合大模型的输出，而不改变底层命令的行为。
• 智能搜索排除项：自动忽略高噪声或敏感目录（.git、.venv），让上下文窗口保持精简且相关。
• 临时工作区：容器严格采用临时模式（--rm），确保每个新会话都有干净、可预测的起点，不会在连接之间泄漏状态。
• 标准化发现：遵循 OCI Image Specification，以实现容器生态系统的标准化集成和透明审计。

⚙️ 可靠性与安全机制

确保工作区结构完整性并提供可观测性的功能。

• 写入前语法验证：write_file 和 search_and_replace 在保存更改前，会对 Python、JSON、JSONL、TOML 和 YAML 进行内存中的语法验证，防止代码处于损坏状态。
• 安全写入：默认情况下，write_file 会阻止意外覆盖现有文件，并强制执行 5MB 大小限制，以防工作区被写满。
• 原子文件操作：编辑采用临时文件加移动的逻辑，确保文件完整性，并防止意外中断或崩溃造成损坏。
• 透明可观测性：所有工具调用和状态变更都会实时流式传输到 MCP 客户端 UI，供操作人员立即监督。

🌐 网络隔离（可选）

默认情况下，容器通过 Docker 的 bridge 网络完全访问网络。为实现最大程度的隔离，你可以使用 --network none 完全禁用网络堆栈：

docker run -i --rm --init \
  --network none \
  --memory=2g --cpus=2.0 --pids-limit=256 \
  --cap-drop=ALL --security-opt=no-new-privileges:true \
  --read-only \
  --tmpfs /tmp:size=64m \
  --tmpfs /home/mcpuser/.cache:size=512m \
  --user 1000:1000 \
  -v /path/to/your/projects:/workspace \
  ghcr.io/hrrodan/agent-workspace-mcp:latest

这会创建一个完全断网的沙箱——容器内仅存在环回接口。所有出站连接（curl、DNS、uv add 等）都会立即失败，从而彻底消除数据外泄和横向移动风险。

说明

使用 --network none 时，Agent 无法在运行时安装软件包。所有依赖项都必须预先安装在自定义镜像中，或预先填充到挂载的工作区卷中。

---

🤝 贡献

1. 安装开发依赖项：uv sync
2. 运行代码检查：uv run ruff check .
3. 运行单元测试：uv run pytest tests/ --ignore=tests/integration/
4. 运行集成测试：设置 OPENROUTER_API_KEY 并运行 uv run pytest tests/integration/

---

© 2026 HrRodan。基于 MIT 许可。