Agentexecmcp

🚀 AgentExecMCP

AgentExecMCPは、AIエージェントにコア実行機能を提供するFastMCPサーバーです。Dockerによるパッケージングが行われており、安全かつ簡単にデプロイできます。

🚀 クイックスタート

2分で起動して実行するには、QUICKSTART.mdを参照してください。

📋 目次

• クイックスタート
• 主な機能
• Makeコマンド
  • クイックスタートコマンド
  • コアコマンド
  • 管理コマンド
  • メンテナンスコマンド
  • サンプルワークフロー
• Claude Desktop統合
  • Makeによる簡単なセットアップ（推奨）
  • 手動セットアップ（好みに応じて）
  • 統合のテスト
  • トラブルシューティング
• Cursor統合
  • Cursorの手動セットアップ
• MCPツール
  • シェルツール
  • コード実行ツール
  • パッケージインストールツール
• クライアント接続サンプル
• セキュリティ機能
• 環境
• MCPプロトコルサポート
• 開発
• テスト
• 要件
• ユースケース
• ライセンス

✨ 主な機能

• シェル実行：タイムアウトと安全制御付きでbashコマンドを実行します。
• 多言語コード実行：Python、Node.js、Goを最適化して実行することができます。
• パッケージ管理：pip、npm、Goモジュールを介してパッケージをインストールします。
• 複数のトランスポート：stdioとSSEをサポートします。
• Dockerデプロイメント：コンテナ化されており、一貫した実行環境を提供します。
• MCPプロトコル：標準準拠のModel Context Protocolをサポートします。
• 安全制御：非root実行、タイムアウト、同時実行数制限などの安全制御があります。
• Claude Desktop統合：SSEトランスポートを介してClaude Desktopとシームレスに動作します。
• Go最適化：CGO_ENABLED=0でGoコードを実行し、互換性を向上させます。

🛠️ Makeコマンド

AgentExecMCPには包括的なMakefileが含まれており、セットアップと管理を非常に簡単にします。すべてのコマンドは、技術者でも非技術者でも使いやすいように設計されています。

クイックスタートコマンド

make help                # すべての利用可能なコマンドと説明を表示
make quick-start         # SSEトランスポートでビルドして実行（推奨）

コアコマンド

make build              # Dockerコンテナをビルド
make run                # STDIOトランスポートで実行（対話型）
make run-sse            # SSEトランスポートで実行（Claude Desktop用）

管理コマンド

make status             # コンテナの状態を表示
make logs               # コンテナのログを表示（ログ出力を追跡）
make health             # サーバーが応答しているか確認
make stop               # すべての実行中のコンテナを停止
make shell              # 実行中のコンテナでシェルを開く

開発コマンド

make lint               # ruffリンターとフォーマッターを実行

メンテナンスコマンド

make test               # 基本機能をテスト
make clean              # コンテナとイメージを削除
make workspace          # ワークスペースディレクトリを作成

サンプルワークフロー

# 初回セットアップ
make quick-start                    # すべてをビルドして起動
make install-claude-config          # Claude Desktopをセットアップ

# 日常の使用
make status                         # 実行中か確認
make logs                          # 出力を表示
make stop                          # 終了時に停止

# トラブルシューティング
make clean                         # すべてをクリーンアップ
make quick-start                   # 新しく起動

🖥️ Claude Desktop統合

AgentExecMCPは、SSEトランスポートを使用してClaude Desktopとシームレスに動作します。これは、ローカル開発とテストに最適です。

Makeによる簡単なセットアップ（推奨）

超簡単な3ステップセットアップ：

1. AgentExecMCPを起動：

   make quick-start
   

2. Claude Desktopの設定をインストール：

   make install-claude-config
   

3. Claude Desktopを再起動して、MCPツールのアイコンを探します！🎉

手動セットアップ（好みに応じて）

1. SSEサーバーを起動：

   docker run -d --name AgentExecMCP-claude -p 8000:8000 -e MCP_TRANSPORT=sse AgentExecMCP
   

2. Claude Desktopを設定： Claude Desktopの設定ファイルを開きます。
   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json 以下の設定を追加します。

   {
     "mcpServers": {
       "AgentExecMCP": {
         "command": "npx",
         "args": [
           "mcp-remote",
           "http://localhost:8000/sse"
         ]
       }
     }
   }
   

3. Claude Desktopを再起動して、MCPツールのアイコンを探します。

統合のテスト

Claude Desktopで以下のコマンドを試してみてください。

• "ファイルをリストするシェルコマンドを実行"
• "2 + 2を計算するPythonコードを実行"
• "pipを使用してrequestsパッケージをインストール"

トラブルシューティング

• サーバーの状態を確認：make status
• ログを表示：make logs
• サーバーを再起動：make stop && make quick-start

Claude Desktopの前提条件

• システムにNode.jsとnpmがインストールされていること
• AgentExecMCPコンテナが実行されているDocker
• 最新バージョンのClaude Desktop

mcp-remoteパッケージは、初回使用時にnpxによって自動的にインストールされます。

🖥️ Cursor統合

AgentExecMCPは、Claude Desktopと同じSSEトランスポートと設定を使用して、Cursor IDEとシームレスに動作します。

Cursorの手動セットアップ

1. SSEサーバーを起動：

   make quick-start
   

2. Cursorを設定： Cursorのmcp設定ファイル（例：~/.cursor/mcp.json）を開き、以下を追加します。

   {
     "mcpServers": {
       "AgentExecMCP": {
         "command": "npx",
         "args": [
           "mcp-remote",
           "http://localhost:8000/sse"
         ]
       }
     }
   }
   

🔧 MCPツール

1. シェルツール

安全制御付きでシェルコマンドを実行します。

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "shell",
    "arguments": {
      "request": {
        "command": "echo 'Hello World!'",
        "timeout": 60,
        "cwd": "/workspace"
      }
    }
  }
}

2. コード実行ツール

Python、Node.js、またはGoのコードスニペットを最適化して実行します。

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "execute_code",
    "arguments": {
      "request": {
        "language": "python",
        "code": "print('Hello from Python!')\nprint(2 + 2)",
        "timeout": 60
      }
    }
  }
}

Goコードの例：

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "execute_code",
    "arguments": {
      "request": {
        "language": "go",
        "code": "package main\nimport \"fmt\"\nfunc main() {\n    fmt.Println(\"Hello from Go!\")\n}",
        "timeout": 60
      }
    }
  }
}

機能：

• Python：標準ライブラリ付きの完全なPython 3.x環境
• Node.js：npmパッケージ付きのNode.jsランタイム
• Go：CGO_ENABLED=0で最適化された実行で、互換性が向上します。
• 自動クリーンアップ：一時ファイルが自動的に作成され、クリーンアップされます。
• エラーハンドリング：コンパイルエラーとランタイムエラーが適切に捕捉されます。

3. パッケージインストールツール

さまざまなパッケージマネージャーを使用してパッケージをインストールします。

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "install_package",
    "arguments": {
      "request": {
        "package_manager": "pip",
        "package": "requests",
        "version": "2.32.0"
      }
    }
  }
}

🌐 クライアント接続サンプル

FastMCPクライアント（Python）

from fastmcp import Client
import asyncio

async def main():
    # stdioを介してローカルコンテナに接続
    async with Client("docker run -i --rm AgentExecMCP") as client:
        result = await client.call_tool("shell", {"request": {"command": "echo 'Hello!'"}})
        print(result[0].text)
    
    # SSEを介してHTTPサーバーに接続
    async with Client("http://localhost:8000/sse") as client:
        tools = await client.list_tools()
        print(f"利用可能なツール: {[tool.name for tool in tools]}")

asyncio.run(main())

🔒 セキュリティ機能

• 非root実行：agentユーザー（UID 10001）として実行されます。
• サンドボックス化されたワークスペース：すべての操作は/workspaceディレクトリで行われます。
• タイムアウト制御：設定可能なタイムアウト（デフォルト60秒、最大300秒）
• 同時実行数制限：最大4つの同時プロセス
• 入力検証：サイズ制限とパラメーター検証
• プロセスクリーンアップ：実行中のプロセスが自動的にクリーンアップされます。

🌍 環境

コンテナには以下が含まれています。

• Ubuntu 22.04ベースイメージ
• pipパッケージマネージャー付きのPython 3.13.3
• npm付きのNode.js 20.19.2
• モジュール付きのGo 1.23.4
• 開発ツール：git、curl、wget、build-essential
• ユーティリティ：jq、ripgrep、fd-find、htop

📡 MCPプロトコルサポート

サーバーは、Model Context Protocol (MCP) 2024 - 11 - 05仕様を複数のトランスポートオプションで実装しています。

• STDIO：ローカルツールとコマンドライン使用のデフォルトトランスポート
• SSE：HTTPデプロイメントとClaude Desktop用のServer - Sent Eventsトランスポート

🛠️ 開発

ローカル開発

# 依存関係をインストール
uv sync

# ローカルでサーバーを実行（stdio）
uv run python -m app.main

# SSEトランスポートでサーバーを実行
MCP_TRANSPORT=sse uv run python -m app.main

テスト

サーバーは以下のテストを行っています。

• ✅ すべてのトランスポートでのMCPプロトコル準拠
• ✅ すべての3つのツール（シェル、コード実行、パッケージインストール）
• ✅ パッケージインポート付きの多言語コード実行
• ✅ パッケージのインストールと検証
• ✅ Dockerコンテナのデプロイメント
• ✅ SSEトランスポートを介したClaude Desktop統合
• ✅ 安全とタイムアウト制御

📋 要件

• コンテナ化されたデプロイメント用のDocker
• ローカル開発用のPython 3.12+
• 依存関係管理用のUVパッケージマネージャー
• Claude Desktop統合用のNode.jsとnpm

🎯 ユースケース

• Claude Desktop統合：Claude Desktop内で直接実行機能を提供します。
• AIエージェント実行：AIエージェントに安全な実行環境を提供します。
• コードサンドボックス化：分離されたコンテナで信頼できないコードを実行します。
• 多言語開発：Python、Node.js、Goのワークフローをサポートします。
• パッケージ管理：エコシステム全体でパッケージをインストールしてテストします。
• シェル自動化：適切な制御付きでシステムコマンドを実行します。
• Kubernetesデプロイメント：クラウド環境で実行機能をスケールさせます。

📄 ライセンス

このプロジェクトは、Apache License 2.0の下でライセンスされています。詳細については、LICENSEファイルを参照してください。

このプロジェクトは、高速なビルド、再現性、デフォルトでの安全性、拡張性を基本原則としています。