Secure Agent Workspace

🛡️ エージェントワークスペース MCP サーバー

LLM 向けに、高度にセキュアなコンテナ化ワークスペースを提供する、統合型の Model Context Protocol（MCP）サーバーです。隔離された「エージェント向けの実験環境」として機能し、エージェントはホストマシンに危険を及ぼすことなく、自律的にコーディング、テスト、デバッグを行えます。

---

✨ 特長

• 🏗️ プロジェクトのライフサイクル全体に対応：uv init でプロジェクトを作成し、uv add で依存関係を管理して、uv run で実行できます。
• 🐚 セキュアな Bash アクセス：必須のタイムアウトを設定し、出力ストリームを統合してシェルコマンドを実行します。
• 🚀 トークンを最適化した出力：RTK（Rust Token Killer） を統合し、run_bash の出力（ls、git、テストランナーなど）を自動的にフィルタリングして圧縮します。これにより、LLM のコンテキストトークンを 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	exclude_patterns による除外に対応し、glob パターンでファイルを検索します。
run_bash	60 秒のタイムアウトで、/workspace 内のシェルコマンドを実行します。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 ケイパビリティを削除し（--cap-drop=ALL）、権限昇格につながる経路を無効化します。
• 不変のサーバーコード：サーバーのソースコードと仮想環境を含む /app ディレクトリは root が所有し、mcpuser に対して読み取り専用です。これにより、サーバーによる自身の変更や、run_bash を介した改ざんを防止します。
• 権限のロックダウン：no-new-privileges:true を適用し、プロセスが昇格した権限を取得できないようにします。
• 不変のシステムコア：コンテナのルートファイルシステム全体を読み取り専用でマウントし、OS レベルの改ざんに対する二重の防御層を設けます。
• リソース割り当て上限：CPU、メモリ、PID に厳格な上限を設け、フォークボムやホストリソースの枯渇などのサービス拒否（DoS）攻撃を緩和します。
• 厳格な境界の適用：堅牢なパス検証機能により、指定された /workspace の外部に対するパストラバーサル攻撃を包括的にブロックします。
• プロセスとリソースの制御：コマンドに必須のタイムアウト（デフォルトは 60 秒）を設け、プロセスグループを厳格に隔離することで、暴走または悪意のあるプロセスを確実に終了させます。
• メモリ過負荷の防止：ファイルの読み取り（1MB）とコマンド出力（50KB）に厳格な上限を設け、メモリの枯渇を防ぎます。
• 情報漏えいの防止：内部のスタックトレースとシステムパスをツール出力から抑制し、サニタイズします。

🛠️ 開発者エクスペリエンスと利便性

シームレスな統合、使いやすさ、エージェントワークフローでの摩擦軽減を重視した機能です。

• ホストに合わせた非 root ID：mcpuser として実行し、UID/GID はビルド時にカスタマイズできます。これにより、ホストのボリュームマウントで発生する面倒なファイル権限の競合を解消します。
• トークンの自動最適化：run_bash で実行されるシェルコマンドは、基盤となるコマンドの動作を変えることなく、RTK を通じて透過的に書き換えられます。これにより、LLM に適した非常にコンパクトな出力を生成します。
• インテリジェントな検索除外：ノイズの多いディレクトリや機密性の高いディレクトリ（.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 を指定すると、エージェントは実行時にパッケージをインストールできません。すべての依存関係は、カスタムイメージに事前インストールするか、マウントされたワークスペースボリュームに事前配置する必要があります。

---

🤝 コントリビュート

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 ライセンス。