Container-MCP

Container-MCP

LLM に代わってツールを実行するための、安全なコンテナベースの Model Context Protocol（MCP）実装です。

概要

Container-MCP は、LLM から要求されたコードの安全な実行、コマンドの実行、ファイルへのアクセス、ウェブ操作の実行を可能にするサンドボックス環境を提供します。MCP プロトコルを実装し、これらの機能をツールとして公開することで、AI システムが安全に検出・呼び出せるようにします。

アーキテクチャには、ドメイン固有のマネージャーパターンと多層セキュリティを採用しています。これにより、適切な制限が適用された分離環境内でツールが実行され、潜在的に有害な操作からホストシステムを保護します。

主な機能

• 多層セキュリティ

  • Podman／Docker によるコンテナ分離
  • アクセス制限のための AppArmor プロファイル
  • さらなる分離のための Firejail サンドボックス化
  • リソース制限（CPU、メモリ、実行時間）
  • パストラバーサルの防止
  • 許可する拡張子の制限

• MCP プロトコルの実装

  • 標準化されたツールの検出と実行
  • リソース管理
  • 非同期実行のサポート

• ドメイン固有のマネージャー

  • BashManager：安全なコマンド実行
  • PythonManager：Python コードのサンドボックス内実行
  • FileManager：安全なファイル操作
  • WebManager：安全なウェブ閲覧とスクレイピング
  • KnowledgeBaseManager：セマンティック検索に対応した構造化ドキュメントの保存
  • ListManager：リストやコレクションの整理・管理
  • MarketManager：Yahoo Finance 経由での株式および暗号通貨データの取得
  • RssManager：RSS および Atom フィードの取得

• 設定可能な環境

  • 環境変数による広範な設定
  • カスタム環境のサポート
  • 開発モードと本番モード

利用可能なツール

システム操作

system_run_command

安全なサンドボックス環境で bash コマンドを実行します。

• パラメーター：
  • command（string、必須）：実行する bash コマンド
  • working_dir（string、省略可）：作業ディレクトリ（サンドボックス内では無視されます）
• 戻り値：
  • stdout（string）：コマンドの標準出力
  • stderr（string）：コマンドの標準エラー出力
  • exit_code（integer）：コマンドの終了コード
  • success（boolean）：コマンドが正常に完了したかどうか

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

system_run_python

安全なサンドボックス環境で Python コードを実行します。

• パラメーター：
  • code（string、必須）：実行する Python コード
  • working_dir（string、省略可）：作業ディレクトリ（サンドボックス内では無視されます）
• 戻り値：
  • output（string）：コードの print 出力
  • error（string）：コードのエラー出力
  • result（any）：任意の戻り値（コードで変数 _ が設定されている場合に利用可能）
  • success（boolean）：コードが正常に実行されたかどうか

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

system_env_var

環境変数の値を取得します。

• パラメーター：
  • var_name（string、省略可）：取得する特定の変数
• 戻り値：
  • variables（object）：環境変数の辞書
  • requested_var（string）：要求された変数の値（var_name が指定された場合）

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

health_check

サーバーのヘルスステータスとシステム情報を取得します。

• パラメーター：なし
• 戻り値：
  • status（string）：サーバーのヘルスステータス
  • timestamp（string）：現在の ISO タイムスタンプ
  • server（object）：サーバーの詳細（name、host、port、platform、python_version）
  • system（object）：システムのメトリクス（cpu_percent、memory_percent、disk_percent）
  • managers（object）：各マネージャーのステータス（有効／無効）

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

ファイル操作

fs_read

ファイルの内容を安全に読み取ります。

• Parameters:
  • path (string, required): ファイルへのパス（サンドボックスのルートからの相対パス）
  • encoding (string, optional): ファイルのエンコーディング（デフォルト: "utf-8"）
• Returns:
  • content (string): ファイルの内容
  • size (integer): ファイルサイズ（バイト単位）
  • modified (float): 最終更新日時のタイムスタンプ
  • success (boolean): 読み取りが成功したかどうか

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

fs_write

ファイルに内容を安全に書き込みます。

• Parameters:
  • path (string, required): ファイルへのパス（サンドボックスのルートからの相対パス）
  • content (string, required): 書き込む内容
  • encoding (string, optional): ファイルのエンコーディング（デフォルト: "utf-8"）
• Returns:
  • success (boolean): 書き込みが成功したかどうか
  • path (string): 書き込んだファイルへのパス

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

fs_list

ディレクトリの内容を安全に一覧表示します。

• Parameters:
  • path (string, optional): ディレクトリへのパス（デフォルト: "/"）
  • pattern (string, optional): ファイルを絞り込む glob パターン
  • recursive (boolean, optional): 再帰的に一覧表示するかどうか（デフォルト: true）
• Returns:
  • entries (array): メタデータを含むディレクトリエントリの一覧
  • path (string): 一覧表示したディレクトリのパス
  • success (boolean): 一覧表示が成功したかどうか

{
  "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): 削除するファイルへのパス
• Returns:
  • success (boolean): 削除が成功したかどうか
  • path (string): 削除したファイルへのパス

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

fs_move

ファイルを安全に移動または名前変更します。

• Parameters:
  • source_path (string, required): 移動元ファイルのパス
  • destination_path (string, required): 移動先ファイルのパス
• Returns:
  • success (boolean): 移動が成功したかどうか
  • source_path (string): 元のファイルパス
  • destination_path (string): 新しいファイルパス

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

fs_apply_diff

サンドボックスのファイルシステム内のファイルに unified diff パッチを適用します。

• Parameters:
  • path (string, required): パッチを適用するファイルへのパス（サンドボックスのルートからの相対パス）
  • diff (string, required): 適用する unified diff の内容
• Returns:
  • success (boolean): パッチが正常に適用されたかどうか
  • path (string): パッチを適用したファイルへのパス
  • lines_applied (integer): 変更された行数
  • new_size (integer): 新しいファイルサイズ（バイト単位）
  • error (string): パッチの適用に失敗した場合のエラーメッセージ

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

Web 操作

web_search

検索エンジンを使ってウェブ上の情報を検索します。

• Parameters:
  • query (string, required): 検索するクエリ
• Returns:
  • results (array): 検索結果の一覧
  • query (string): 元のクエリ

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

web_scrape

指定した URL の内容を取得して返します。

• Parameters:
  • url (string, required): 内容を取得する URL
  • selector (string, optional): 特定のコンテンツを対象にする CSS セレクター
  • output_format (string, optional): Markdown を返すには "markdown" を指定します（リンクを保持します）。デフォルトはプレーンテキストです。
• Returns:
  • content (string): 取得したコンテンツ
  • url (string): 内容を取得した URL
  • title (string): ページのタイトル
  • success (boolean): 内容の取得が成功したかどうか
  • error (string): 取得に失敗した場合のエラーメッセージ

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

Markdown 出力の例：

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

web_browse

Playwright を使ってウェブサイトを対話的に閲覧します。

注: web_browse には Playwright のブラウザバイナリが必要です。コンテナの外部で使用する場合は、python -m playwright install chromium（または playwright install）を実行してインストールしてください。

• Parameters:
  • url (string, required): ブラウジングセッションの開始 URL
• Returns:
  • content (string): ページの HTML コンテンツ
  • url (string): リダイレクト後の最終 URL
  • title (string): ページのタイトル
  • success (boolean): ブラウジングが成功したかどうか
  • error (string): ブラウジングに失敗した場合のエラーメッセージ

{
  "content": "<!DOCTYPE html><html>...</html>",
  "url": "https://example.com/after_redirect",
  "title": "Example Page",
  "success": true,
  "error": null
}

ナレッジベースの操作

ナレッジベースシステムは、セマンティック検索機能、RDF 形式の関連付け、メタデータ管理を備えた構造化ドキュメントストレージを提供します。ドキュメントは階層型の名前空間構造に整理され、プリファレンス（任意の RDF トリプル）と参照（ドキュメント間のリンク）をサポートします。

ドキュメント URI の形式

ナレッジベースのドキュメントでは、構造化 URI 形式を使用します：kb://namespace/collection[/subcollection]*/name

• namespace：最上位の組織単位（例：「projects」、「research」）
• collection：名前空間内の主なカテゴリ（例：「documentation」、「notes」）
• subcollection：任意の下位カテゴリ（例：「api」、「tutorials」）
• name：ドキュメント識別子（例：「getting-started」、「user-guide」）

例：

• kb://projects/docs/api-reference
• kb://research/papers/machine-learning/transformers
• kb://personal/notes/meeting-2024-01-15

kb_create_document

任意のメタデータとコンテンツを指定して、ナレッジベースに新しいドキュメントを作成します。

• パラメーター：
  • uri（string、必須）：形式が "kb://namespace/collection[/subcollection]*/name" のドキュメント URI
  • metadata（object、任意）：ドキュメントのメタデータ（デフォルト：{}）
  • content（string、任意）：ドキュメントのコンテンツ（作成と書き込みを一度に実行できます）
• 戻り値：
  • 作成の詳細を含む完全なドキュメントインデックスオブジェクト
• 注意：content パラメーターを指定すると、コンテンツ付きのドキュメントを一度の操作で作成できます。または、最初にドキュメントを作成し、その後 kb_write_content でコンテンツを追加する2段階の手順も使用できます。

{
  "namespace": "projects",
  "collection": "docs",
  "name": "api-reference",
  "type": "document",
  "subtype": "text",
  "created_at": "2024-01-15T10:30:00.000Z",
  "updated_at": "2024-01-15T10:30:00.000Z",
  "content_type": "text/plain",
  "chunked": false,
  "fragments": {},
  "preferences": [],
  "references": [],
  "referenced_by": [],
  "indices": [],
  "metadata": {"author": "John Doe", "version": "1.0"}
}

kb_write_content

ナレッジベース内の既存ドキュメントにコンテンツを書き込みます。

• パラメーター：
  • uri（string、必須）：ドキュメント URI
  • content（string、必須）：ドキュメントのコンテンツ
  • force（boolean、任意）：既存のコンテンツを上書きするかどうか（デフォルト：false）
• 戻り値：
  • 更新後の完全なドキュメントインデックスオブジェクト
• 注意：ドキュメントは、先に kb_create_document を使用して作成する必要があります。

{
  "namespace": "projects",
  "collection": "docs", 
  "name": "api-reference",
  "type": "document",
  "subtype": "text",
  "created_at": "2024-01-15T10:30:00.000Z",
  "updated_at": "2024-01-15T10:35:00.000Z",
  "content_type": "text/plain",
  "chunked": false,
  "fragments": {},
  "preferences": [],
  "references": [],
  "referenced_by": [],
  "indices": [],
  "metadata": {"author": "John Doe", "version": "1.0"}
}

kb_read

ナレッジベースからドキュメントデータを読み込みます。uri を指定せずに呼び出すと、すべてのドキュメントを一覧表示します（個別の一覧表示操作は不要です）。

• パラメーター：
  • uri（string、任意）：ドキュメント URI。省略すると、すべてのドキュメントを一覧表示します。
  • recursive（boolean、任意）：再帰的に一覧表示するかどうか（デフォルト：true）
  • include_content（boolean、任意）：ドキュメントのコンテンツを含めるかどうか（デフォルト：false）
  • include_index（boolean、任意）：ドキュメントのメタデータを含めるかどうか（デフォルト：false）
• 戻り値：
  • 要求された構成要素に基づくドキュメントデータ。次の3つのモードで動作します：
    • list mode：uri が省略された場合、ドキュメント URI の一覧を返します
    • bulk_read mode：uri が部分パス（namespace または collection）の場合、複数のドキュメントを返します
    • read mode：uri が完全なドキュメントパスの場合、単一のドキュメントを返します

単一のドキュメントを読み込む：

{
  "status": "success",
  "uri": "kb://projects/docs/api-reference",
  "content": "This is the API reference content...",
  "index": {
    "namespace": "projects",
    "collection": "docs",
    "name": "api-reference",
    "created_at": "2024-01-15T10:30:00Z",
    "metadata": {"author": "John Doe"}
  }
}

すべてのドキュメントを一覧表示する（uri なし）：

{
  "mode": "list",
  "documents": [
    "kb://projects/docs/api-reference",
    "kb://projects/docs/user-guide",
    "kb://research/papers/transformers"
  ],
  "count": 3
}

kb_update_triples

ドキュメントの RDF トリプル（プリファレンス、参照、メタデータ）を管理します。このツールは triple_type="metadata" によるメタデータの更新にも対応しているため、個別のメタデータ更新操作は不要です。

• パラメーター：
  • action（string、必須）：実行する操作（"add" または "remove"）
  • triple_type（string、必須）：トリプルの種類（"preference"、"reference"、または "metadata"）
  • uri（string、必須）：ソースドキュメントの URI
  • predicate（string、必須）：トリプルの述語
  • object（string、任意）：トリプルのオブジェクト（プリファレンスとメタデータの場合）
  • ref_uri（string、任意）：参照先ドキュメントの URI（参照の場合のみ）
• 戻り値：
  • 操作のステータスと更新後の件数

プリファレンス（任意の RDF トリプル）を追加する：

{
  "status": "updated",
  "preference_count": 3,
  "action": "add",
  "triple_type": "preference"
}

参照（別のドキュメントへのリンク）を追加する：

{
  "status": "success",
  "message": "Reference added",
  "added": true,
  "action": "add",
  "triple_type": "reference"
}

メタデータを更新する：

{
  "status": "updated",
  "action": "add",
  "triple_type": "metadata"
}

参照を削除する：

{
  "status": "updated",
  "reference_count": 2,
  "action": "remove",
  "triple_type": "reference"
}

kb_search

テキストクエリおよび／またはグラフ拡張を使用して、ナレッジベースを検索します。

• パラメーター：
  • query（string、任意）：セマンティック検索および再ランキング用のテキストクエリ
  • seed_uris（array、任意）：グラフ拡張の開始点となる完全な URI（kb://namespace/collection/name）
  • root_uri（string、任意）：検索範囲を指定する部分 URI（kb://namespace または kb://namespace/collection）
  • expand_hops（integer、任意）：拡張する関係のホップ数（デフォルト：0）
  • filter_uris（array、任意）：結果から除外する URI
  • relation_predicates（array、任意）：グラフ探索中にたどる述語（デフォルト：["references"]）
  • top_k_sparse（integer、任意）：取得するスパース検索結果の数（デフォルト：50）
  • top_k_rerank（integer、任意）：再ランキング後の最終結果数（デフォルト：10）
  • include_content（boolean、任意）：ドキュメントの内容を含めるかどうか（デフォルト：false）
  • include_index（boolean、任意）：ドキュメントのメタデータを含めるかどうか（デフォルト：false）
  • use_reranker（boolean、任意）：セマンティック再ランキングを使用するかどうか（デフォルト：true）
• 戻り値：
  • ランク付けされた検索結果のリスト

{
  "results": [
    {
      "urn": "kb://projects/docs/api-reference",
      "sparse_score": 1.95,
      "content": "API reference content...",
      "index": {
        "namespace": "projects",
        "collection": "docs",
        "name": "api-reference",
        "type": "document",
        "subtype": "text",
        "created_at": "2025-07-02T23:13:17.362283Z",
        "updated_at": "2025-07-02T23:18:23.396660Z",
        "content_type": "text/plain",
        "chunked": false,
        "fragments": {},
        "preferences": [],
        "references": [
          [
            "references",
            "kb://project/docs/api-dto"
          ]
        ],
        "referenced_by": [],
        "indices": [],
        "metadata": {
          "purpose": "testing_collection_organization",
          "created_for": "kb_exercise",
          "type": "test_document",
          "created_date": "2025-07-02",
          "topic": "search_performance",
          "related_to": "rebuild_test"
        }
      },
      "rerank_score": 0.84,
    }
  ],
  "count": 1
}

kb_manage

ドキュメントの移動や検索インデックスの再構築など、ナレッジベースの操作を管理します。

• パラメーター：
  • action（string、必須）：実行する管理操作
    • "move_document"：ドキュメントを移動します
    • "delete"：ドキュメントをアーカイブします
    • "rebuild_search_index"：検索インデックスを再構築します
  • options（object、必須）：操作固有のオプション
    • "move_document"の場合：{"uri": "...", "new_uri": "..."}
    • "delete"の場合：{"uri": "..."}
    • "rebuild_search_index"の場合：{"rebuild_all": true}（任意）
• 戻り値：
  • 操作のステータスと結果

ドキュメントの移動：

{
  "action": "move_document",
  "status": "success",
  "old_path": "projects/docs/old-name",
  "new_path": "projects/docs/new-name",
  "result": {
    "namespace": "projects",
    "collection": "docs",
    "name": "new-name",
    "type": "document",
    "subtype": "text",
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-01-15T10:50:00.000Z",
    "content_type": "text/plain",
    "chunked": false,
    "fragments": {},
    "preferences": [],
    "references": [],
    "referenced_by": [],
    "indices": [],
    "metadata": {}
  }
}

ドキュメントのアーカイブ：

{
  "action": "delete",
  "status": "success", 
  "path": "projects/docs/obsolete",
  "result": {
    "status": "archived",
    "message": "Document archived: kb://projects/docs/obsolete",
    "original_path": "projects/docs/obsolete",
    "archive_path": "archive/projects/docs/obsolete",
    "archive_urn": "kb://archive/projects/docs/obsolete"
  }
}

リスト操作

リストシステムは、タスク、メモ、買い物、一般的な項目の管理に、org-mode ベースのリスト管理機能を提供します。リストではさまざまな項目ステータスを使用でき、整理のためにタグを付けられます。

項目のステータス

リスト内の項目には、次のステータスを設定できます：TODO、DONE、WAITING、CANCELLED、NEXT、SOMEDAY

リストの種類

リストの種類は次のいずれかです：todo、shopping、notes、checklist、project、reading、ideas

list_create

タスク、メモ、買い物、その他の項目をまとめる、新しい整理済みリストを作成します。

• パラメーター：
  • name（string、必須）：リストの内部名（ファイル名に使用）
  • title（string、任意）：リストの表示タイトル
  • list_type（string、任意）：リストの種類（デフォルト："todo"）
  • description（string、任意）：任意の説明
  • tags（array、任意）：整理用のタグ
  • properties（object、任意）：ユーザー定義のカスタムプロパティ
• 戻り値：
  • success（boolean）：作成に成功したかどうか
  • name（string）：リスト名
  • metadata（object）：タイトル、種類、作成日時、プロパティ
  • path（string）：ファイルパス

{
  "success": true,
  "name": "grocery-list",
  "metadata": {
    "title": "Weekly Groceries",
    "type": "shopping",
    "created": "2024-01-15T10:30:00.000Z",
    "properties": {}
  },
  "path": "/app/lists/grocery-list.org"
}

list_get

柔軟なフィルターオプションを使用して、リストを取得・閲覧します。

• パラメーター：
  • name（string、任意）：取得する特定のリスト名。省略すると、利用可能なすべてのリストが一覧表示されます。
  • include_items（boolean、任意）：応答に項目を含めるかどうか（デフォルト：true）
  • summary_only（boolean、任意）：項目を含めず、概要統計のみを返すかどうか（デフォルト：false）
  • status_filter（string、任意）：ステータス（TODO、DONE、WAITING、CANCELLED、NEXT、SOMEDAY）で項目を絞り込みます
  • tag_filter（array、任意）：タグで項目を絞り込みます（項目には指定されたすべてのタグが付いている必要があります）
• 戻り値：
  • nameを省略した場合：lists（概要の配列）、count
  • nameを指定した場合：name、metadata、items、statistics

すべてのリストの一覧表示：

{
  "success": true,
  "lists": [
    {"name": "grocery-list", "title": "Weekly Groceries", "type": "shopping"},
    {"name": "project-tasks", "title": "Q1 Tasks", "type": "todo"}
  ],
  "count": 2
}

特定のリストの取得：

{
  "success": true,
  "name": "project-tasks",
  "metadata": {"title": "Q1 Tasks", "type": "todo"},
  "items": [
    {
      "text": "Complete API integration",
      "status": "TODO",
      "index": 0,
      "tags": ["backend"],
      "created": "2024-01-15T10:30:00.000Z",
      "completed": null,
      "properties": {}
    }
  ],
  "statistics": {
    "total_items": 5,
    "status_counts": {"TODO": 3, "DONE": 2},
    "completion_percentage": 40.0
  }
}

list_modify

リスト項目を追加、更新、削除して変更します。

• パラメーター：
  • list_name（文字列、必須）：リスト名
  • action（文字列、必須）：実行する操作（"add"、"update"、"remove"）
  • item_text（文字列、任意）：項目のテキスト（"add"では必須、"update"では任意）
  • item_index（整数、任意）：項目のインデックス（"update"と"remove"では必須）
  • status（文字列、任意）：項目のステータス（TODO、DONE、WAITING、CANCELLED、NEXT、SOMEDAY）
  • tags（配列、任意）：項目のタグ
  • properties（オブジェクト、任意）：カスタムプロパティ
• 戻り値：
  • success（ブール値）：操作が成功したかどうか
  • action（文字列）：実行されたアクション
  • item（オブジェクト）：影響を受けた項目の詳細

項目の追加：

{
  "success": true,
  "action": "add",
  "item": {
    "text": "Buy milk",
    "status": "TODO",
    "index": 3,
    "tags": ["dairy"]
  },
  "total_items": 4
}

項目の更新：

{
  "success": true,
  "action": "update",
  "item_index": 0,
  "item": {"text": "Buy milk", "status": "DONE"},
  "old_item": {"text": "Buy milk", "status": "TODO"}
}

項目の削除：

{
  "success": true,
  "action": "remove",
  "removed_item": {"text": "Buy milk", "status": "DONE", "index": 0},
  "remaining_items": 3
}

list_update

リストのプロパティとメタデータを更新します。プロパティはマージ方式で処理されます。指定されたキーのみが更新され、既存のキーは保持されます。

• パラメーター：
  • name（文字列、必須）：リスト名
  • title（文字列、任意）：新しいタイトル
  • list_type（文字列、任意）：新しいリストの種類
  • description（文字列、任意）：新しい説明
  • tags（配列、任意）：新しいタグ（既存のタグを置き換えます）
  • author（文字列、任意）：新しい作成者
  • properties（オブジェクト、任意）：カスタムプロパティ（既存のプロパティとマージされます）
• 戻り値：
  • success（ブール値）：更新が成功したかどうか
  • name（文字列）：リスト名
  • metadata（オブジェクト）：更新されたメタデータ

{
  "success": true,
  "name": "project-tasks",
  "metadata": {
    "title": "Q1 Tasks - Updated",
    "type": "project",
    "tags": ["work", "q1"],
    "description": "Updated project task list"
  }
}

list_delete

リスト全体とそのすべての項目を完全に削除します。安全のためリストファイルはアーカイブされますが、通常の操作ではリストにアクセスできなくなります。

• パラメーター：
  • name（文字列、必須）：削除するリスト名
• 戻り値：
  • success（ブール値）：削除が成功したかどうか
  • name（文字列）：削除されたリスト名
  • items_count（整数）：リストに含まれていた項目数
  • archived_to（文字列）：アーカイブファイルのパス

{
  "success": true,
  "name": "old-grocery-list",
  "items_count": 12,
  "archived_to": "/app/lists/.archive/old-grocery-list.org"
}

list_search

テキストまたはタグを使って、複数のリストにまたがる項目を検索します。

• パラメーター：
  • query（文字列、必須）：検索クエリ文字列
  • list_names（配列、任意）：検索対象の特定のリスト（省略した場合はすべてのリストを検索）
  • search_in（配列、任意）：検索対象："text"、"tags"、または両方（デフォルト：["text"]）
  • case_sensitive（ブール値、任意）：大文字と小文字を区別するかどうか（デフォルト：false）
• 戻り値：
  • matches（配列）：リストの情報を含む、一致した項目の一覧
  • total_matches（整数）：一致した項目の総数
  • lists_searched（整数）：検索したリストの数
  • search_options（オブジェクト）：適用された検索パラメーター

{
  "success": true,
  "query": "milk",
  "matches": [
    {
      "list_name": "grocery-list",
      "list_title": "Weekly Groceries",
      "item_index": 2,
      "item_text": "Buy milk",
      "item_status": "TODO",
      "item_tags": ["dairy"],
      "match_type": "text"
    }
  ],
  "total_matches": 1,
  "lists_searched": 3,
  "search_options": {
    "search_in": ["text"],
    "case_sensitive": false
  }
}

マーケット操作

マーケットシステムでは、株式と暗号資産の金融データを Yahoo Finance を使用して検索できます。

market_query

株式または暗号資産の価格を、ファンダメンタルズ、ニュース、トレンド分析とともに照会します。

• パラメーター：
  • symbol（string、必須）：株式／暗号資産のシンボル（例：「AAPL」、「BTC-USD」、「TSLA」）
  • period（string、任意）：トレンド指標の対象となる過去の期間（デフォルト：「1y」）
  • interval（string、任意）：過去データの間隔（デフォルト：「1d」）
  • news_count（integer、任意）：返す最新ニュース項目の数（デフォルト：5）
• 戻り値：
  • symbol（string）：照会したシンボル
  • name（string）：企業／資産名
  • price（float）：現在の価格
  • change（float）：価格変動
  • change_percent（float）：変動率
  • volume（integer）：取引量
  • market_cap（integer）：時価総額
  • currency（string）：通貨コード
  • timestamp（string）：ISO 形式のタイムスタンプ
  • fundamentals（object）：収益、株価収益率、配当、利益率
  • news（array）：最新ニュース項目
  • trend（object）：移動平均、RSI、ボラティリティ、過去のリターン
  • success（boolean）：照会が成功したかどうか
  • error（string）：照会に失敗した場合のエラーメッセージ

{
  "symbol": "AAPL",
  "name": "Apple Inc.",
  "price": 185.92,
  "change": 2.35,
  "change_percent": 1.28,
  "volume": 54321000,
  "market_cap": 2890000000000,
  "currency": "USD",
  "timestamp": "2024-01-15T16:00:00Z",
  "fundamentals": {
    "trailing_pe": 29.5,
    "forward_pe": 27.8,
    "dividend_yield": 0.0054,
    "profit_margin": 0.256,
    "earnings_quarterly_growth": 0.13
  },
  "news": [
    {
      "title": "Apple Reports Strong Q4 Earnings",
      "link": "https://example.com/article",
      "publisher": "Reuters",
      "published": "2024-01-15T12:00:00Z",
      "type": "STORY"
    }
  ],
  "trend": {
    "as_of": "2024-01-15T16:00:00Z",
    "close": 185.92,
    "return_1w": 0.023,
    "return_1m": 0.045,
    "return_3m": 0.12,
    "ma20": 183.50,
    "ma50": 180.25,
    "ma200": 175.80,
    "rsi14": 58.3,
    "volatility_20d": 0.18,
    "range_52w_low": 164.08,
    "range_52w_high": 199.62,
    "data_points": 252
  },
  "success": true,
  "error": null
}

RSS 操作

RSS システムは RSS フィードと Atom フィードを取得して解析します。

rss_fetch

RSS フィードまたは Atom フィードを取得して解析し、構造化された項目を返します。

• パラメーター：
  • url（string、必須）：RSS フィードの URL
  • limit（integer、任意）：返す項目の最大数（デフォルト：10）
• 戻り値：
  • feed_title（string）：フィードのタイトル
  • feed_link（string）：フィードのウェブサイトへのリンク
  • items（array）：フィード項目。各項目には以下が含まれます：
    • title（string）：項目のタイトル
    • link（string）：項目の URL
    • published（string）：公開日
    • summary（string）：項目の要約／説明
  • item_count（integer）：返された項目の数
  • success（boolean）：取得に成功したかどうか
  • error（string）：取得に失敗した場合のエラーメッセージ

{
  "feed_title": "Hacker News",
  "feed_link": "https://news.ycombinator.com",
  "items": [
    {
      "title": "Show HN: A new open-source project",
      "link": "https://example.com/project",
      "published": "2024-01-15T14:30:00Z",
      "summary": "An innovative approach to solving..."
    }
  ],
  "item_count": 10,
  "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 プロファイル：きめ細かなアクセス制御
• リソース制限：
  • 実行タイムアウト（デフォルト：30s、最大：120s）
  • サンドボックス内のディレクトリへのアクセスに制限
• ネットワーク：ネットワークアクセスなし
• ファイルシステム：データへの読み取り専用アクセス、サンドボックスへの読み書きアクセス

許可されるコマンドの例：

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

Python 実行環境

Python 実行環境は、安全なコード実行を目的として設計されています。

• Python バージョン：3.12
• メモリ制限：設定可能なメモリ上限（デフォルト：256MB）
• 実行タイムアウト：設定可能な時間制限（デフォルト：30s、最大：120s）
• AppArmor プロファイル：システムリソースへのアクセスを制限
• Firejail サンドボックス：プロセス分離
• ケイパビリティ：すべてのケイパビリティを削除
• ネットワーク：ネットワークアクセスなし
• 利用可能なライブラリ：標準ライブラリのみ
• 出力のキャプチャ：stdout／stderr をリダイレクトしてサニタイズ
• リソース制御：CPU とメモリの制限を適用

ファイルシステム環境

ファイルシステム環境は、サンドボックス内のファイルへのアクセスを制御します。

• ベースディレクトリ：すべての操作をサンドボックスのルートに制限します
• パスの検証：すべてのパスを正規化し、パストラバーサルの試みがないか確認します
• サイズ制限：最大ファイルサイズを適用します（デフォルト：10MB）
• 拡張子の制御：許可された拡張子のみを許可します（デフォルト：txt, md, csv, json, py）
• 権限の制御：適切な読み取り／書き込み権限を適用します
• 分離：ホストファイルシステムにはアクセスできません

Web 環境

Web 環境は、外部リソースへの制御されたアクセスを提供します。

• ドメインの制御：許可するドメインを任意でホワイトリストに登録できます
• タイムアウトの制御：操作のタイムアウトを設定できます
• ブラウザーの制御：Playwright によるヘッドレスブラウザーで完全にレンダリングします
• スクレイピングの制御：requests/BeautifulSoup によるシンプルなスクレイピングを利用できます
• コンテンツのサニタイズ：すべてのコンテンツを解析してサニタイズします
• ネットワークの分離：コンテナーを介して独立したネットワーク名前空間を使用します

ナレッジベース環境

ナレッジベース環境は、構造化されたドキュメントの保存とセマンティック検索を提供します。

• 階層的な整理：ドキュメントを namespace/collection/name の構造で整理します
• メタデータ管理：RDF 形式のトリプルによるリッチなメタデータをサポートします
• セマンティック検索：スパースインデックスとセマンティックな再ランキングによる全文検索を行います
• グラフの関連付け：ドキュメント間の参照を関連性に沿ってたどれます
• パスの検証：パスを厳密に検証し、正規化します
• 検索インデックス：最適なパフォーマンスを実現するため、スパースインデックスとグラフインデックスを分けています
• タイムアウトの制御：操作のタイムアウトを設定できます（デフォルト：30s、最大：120s）
• 分離：ナレッジベースの操作を、設定済みのストレージパスに制限します

リスト環境

リスト環境は、整理されたコレクション管理を提供します。

• Org-mode 形式：移植性のため、リストを Org-mode ファイルとして保存します
• ステータスの追跡：項目は複数のステータス（TODO、DONE、WAITING、CANCELLED、NEXT、SOMEDAY）に対応します
• タグ付け：柔軟に整理できるよう、項目とリストにタグを付けられます
• アーカイブ：安全のため、削除されたリストをアーカイブします
• 検索：テキストとタグで複数のリストを横断して検索できます
• 分離：リストの操作を、設定済みのストレージパスに制限します

マーケット環境

マーケット環境は、金融データへの制御されたアクセスを提供します。

• データソース：株式と暗号資産には Yahoo Finance を使用します
• タイムアウトの制御：タイムアウトを設定できます（デフォルト：30s、最大：60s）
• データの種類：価格相場、ファンダメンタルズ、ニュース、トレンド分析

RSS 環境

RSS 環境は、フィードの取得機能を提供します。

• フィードの種類：RSS フィードと Atom フィードの両方をサポートします
• タイムアウトの制御：タイムアウトを設定できます（デフォルト：15s、最大：30s）
• ユーザーエージェント：ユーザーエージェント文字列を設定できます
• 項目数の制限：取得ごとの最大項目数を設定できます

アーキテクチャ

このプロジェクトはモジュール型アーキテクチャを採用しています。

container-mcp/
├── cmcp/                     # Main application code
│   ├── managers/             # Domain-specific managers
│   │   ├── bash_manager.py   # Secure bash execution
│   │   ├── file_manager.py   # Secure file operations
│   │   ├── knowledge_base_manager.py # Knowledge base operations
│   │   ├── list_manager.py   # List/collection operations
│   │   ├── market_manager.py # Market data operations
│   │   ├── python_manager.py # Secure python execution
│   │   ├── rss_manager.py    # RSS feed operations
│   │   └── web_manager.py    # Secure web operations
│   ├── kb/                   # Knowledge base components
│   │   ├── document_store.py # Document storage and retrieval
│   │   ├── models.py         # Data models and schemas
│   │   ├── path.py           # Path parsing and validation
│   │   └── search.py         # Search indices and ranking
│   ├── tools/                # MCP tool implementations
│   │   ├── file.py           # File operation tools
│   │   ├── kb.py             # Knowledge base tools
│   │   ├── list.py           # List operation tools
│   │   ├── market.py         # Market data tools
│   │   ├── rss.py            # RSS feed tools
│   │   ├── system.py         # System operation tools
│   │   └── web.py            # Web operation tools
│   ├── utils/                # Utility functions
│   │   ├── diff.py           # Diff/patch utilities
│   │   ├── io.py             # I/O helpers
│   │   └── logging.py        # Logging utilities
│   ├── __init__.py
│   ├── config.py             # Configuration system
│   └── main.py               # MCP server setup
├── apparmor/                 # AppArmor profiles
│   ├── mcp-bash              # Bash execution profile
│   └── mcp-python            # Python execution profile
├── bin/                      # Build/run scripts
│   ├── 00-all-in-one.sh      # Complete setup script
│   ├── 01-init.sh            # Project initialization
│   ├── 02-build-container.sh # Container build script
│   ├── 03-setup-environment.sh # Environment setup
│   ├── 04-run-container.sh   # Container run script
│   ├── 05-check-container.sh # Container health check
│   ├── 06-run-tests.sh       # Test execution
│   ├── 07-attach-container.sh # Container shell access
│   ├── 08-testnetwork.sh     # Network testing
│   ├── 09-view-logs.sh       # Log viewing
│   ├── zy-shutdown.sh        # Container shutdown
│   └── zz-teardown.sh        # Complete teardown
├── tests/                    # Test suites
│   ├── integration/          # Integration tests
│   ├── unit/                 # Unit tests
│   └── conftest.py           # Test configuration
├── volume/                   # Persistent storage
│   ├── config/               # Configuration files
│   ├── data/                 # Data directory
│   ├── kb/                   # Knowledge base storage
│   │   ├── search/           # Search indices
│   │   │   ├── sparse_idx/   # Sparse search index
│   │   │   └── graph_idx/    # Graph search index
│   │   ├── archive/          # Archived documents
│   ├── logs/                 # Log files
│   ├── sandbox/              # Sandboxed execution space
│   │   ├── bash/             # Bash sandbox
│   │   ├── browser/          # Web browser sandbox
│   │   ├── files/            # File operation sandbox
│   │   └── python/           # Python sandbox
│   └── temp/                 # Temporary storage
├── Containerfile            # Container definition
├── podman-compose.yml       # Container orchestration
├── pyproject.toml           # Python project configuration
├── uv.lock                  # Dependency lock file
├── pytest.ini               # Test configuration
└── README.md                # Project documentation

各マネージャーは、一貫した設計パターンに従います。

• 環境変数に基づいて初期化するための .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/54rt1n/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 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=*

ナレッジベースマネージャーの設定

# Knowledge Base Manager Configuration
CMCP_KB_STORAGE_PATH=/app/kb
KB_TIMEOUT_DEFAULT=30
KB_TIMEOUT_MAX=120

# Search Configuration
CMCP_KB_SEARCH_ENABLED=true
CMCP_KB_SPARSE_INDEX_PATH=/app/kb/search/sparse_idx
CMCP_KB_GRAPH_INDEX_PATH=/app/kb/search/graph_idx
CMCP_KB_RERANKER_MODEL=mixedbread-ai/mxbai-rerank-base-v1
CMCP_KB_SEARCH_RELATION_PREDICATES=references
CMCP_KB_SEARCH_GRAPH_NEIGHBOR_LIMIT=1000

# Tool Enable/Disable
TOOLS_ENABLE_KB=true

リストマネージャーの設定

# List Manager Configuration
CMCP_LIST_STORAGE_PATH=/app/lists
TOOLS_ENABLE_LIST=true

マーケットマネージャーの設定

# Market Manager Configuration
MARKET_TIMEOUT_DEFAULT=30
MARKET_TIMEOUT_MAX=60
TOOLS_ENABLE_MARKET=true

RSS マネージャーの設定

# RSS Manager Configuration
RSS_TIMEOUT_DEFAULT=15
RSS_TIMEOUT_MAX=30
RSS_USER_AGENT=container-mcp/1.0
TOOLS_ENABLE_RSS=true

開発

開発環境のセットアップ

1. Python 仮想環境を作成します：

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

2. 依存関係をインストールします：

   pip install -r requirements-dev.txt
   

3. 開発モードでパッケージをインストールします：

   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 の下でライセンスされています。

作者

Martin Bukowski