Agentexecmcp

🚀 AgentExecMCP

AgentExecMCP 是一個 FastMCP 服務器，為 AI 智能體提供核心執行能力。它以 Docker 容器的形式進行封裝，能夠實現安全且便捷的部署。

🚀 快速開始

兩分鐘內即可啟動並運行，請參閱 QUICKSTART.md。

✨ 主要特性

• Shell 執行：運行 bash 命令，具備超時和安全控制機制。
• 多語言代碼執行：支持 Python、Node.js 和 Go 語言，並進行了優化執行。
• 包管理：可通過 pip、npm 和 Go 模塊安裝軟件包。
• 多種傳輸方式：支持標準輸入輸出（stdio）和服務器發送事件（SSE）。
• Docker 部署：採用容器化部署，確保執行環境的一致性。
• MCP 協議：符合標準的模型上下文協議（MCP）。
• 安全控制：以非根用戶身份執行，具備超時和併發限制。
• Claude Desktop 集成：通過 SSE 傳輸方式與 Claude Desktop 無縫集成。
• Go 優化：執行 Go 代碼時，開啟 CGO_ENABLED=0 以提高兼容性。

📦 安裝指南

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              # 在運行的容器中打開 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 輕鬆設置（推薦）

簡單的三步設置：

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 中嘗試以下命令：

• "運行一個 shell 命令來列出文件"
• "執行一些 Python 代碼來計算 2 + 2"
• "使用 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. Shell 工具

使用安全控制執行 shell 命令。

{
  "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():
    # 通過標準輸入輸出連接到本地容器
    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())

📚 詳細文檔

安全特性

• 非根用戶執行：以 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 協議支持

服務器實現了 2024 - 11 - 05 版本的模型上下文協議（MCP），支持多種傳輸選項：

• STDIO：本地工具和命令行使用的默認傳輸方式
• SSE：用於 HTTP 部署和 Claude Desktop 的服務器發送事件傳輸方式

開發

本地開發

# 安裝依賴
uv sync

# 在本地運行服務器（標準輸入輸出）
uv run python -m app.main

# 使用 SSE 傳輸方式運行服務器
MCP_TRANSPORT=sse uv run python -m app.main

測試

服務器已通過以下測試：

• ✅ 所有傳輸方式下的 MCP 協議合規性
• ✅ 所有三種工具（shell、execute_code、install_package）
• ✅ 支持包導入的多語言代碼執行
• ✅ 包安裝和驗證
• ✅ Docker 容器部署
• ✅ 通過 SSE 傳輸方式與 Claude Desktop 集成
• ✅ 安全和超時控制

要求

• Docker（用於容器化部署）
• Python 3.12+（用於本地開發）
• UV 包管理器（用於依賴管理）
• Node.js 和 npm（用於 Claude Desktop 集成）

使用場景

• Claude Desktop 集成：直接在 Claude Desktop 中提供執行能力。
• AI 智能體執行：為 AI 智能體提供安全的執行環境。
• 代碼沙盒：在隔離的容器中運行不可信代碼。
• 多語言開發：支持 Python、Node.js 和 Go 工作流。
• 包管理：跨生態系統安裝和測試軟件包。
• Shell 自動化：使用適當的控制執行系統命令。
• Kubernetes 部署：在雲環境中擴展執行能力。

📄 許可證

本項目採用 Apache 許可證 2.0 版 - 詳情請參閱 LICENSE 文件。

本項目遵循快速構建、可重現、默認安全和可擴展的指導原則。