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 文件。

本项目遵循快速构建、可重现、默认安全和可扩展的指导原则。