Terminal Toolkit MCP

CAMEL终端工具包MCP服务器

这是一个独立的MCP（模型上下文协议）服务器，用于导出CAMEL终端工具包功能。它允许LLM客户端通过MCP协议安全地执行终端命令。

特性

• 壳牌执行：在托管会话中执行shell命令
• 会话管理：创建和管理多个shell会话
• 安全模式：限制危险操作并强制执行工作目录边界
• 交互式支持：支持交互式命令（仅限Linux/macOS）
• 流程管理：控制正在运行的进程（查看、等待、写入输入、终止）
• 人类接管：需要时请求人力援助

安装

选项1：使用uvx（推荐）

使用此MCP服务器的最简单方法是 uvx，它将自动安装并运行它：

uvx terminal-toolkit-mcp

选项2：使用pip

pip install terminal-toolkit-mcp

选项3：开发安装

git clone https://github.com/camel-ai/terminal-toolkit-mcp.git
cd terminal-toolkit-mcp
pip install -e .

用法

作为MCP服务器

使用stdio传输启动服务器：

terminal-toolkit-mcp

命令行选项

• --working-directory PATH：设置操作的工作目录
• --timeout SECONDS：设置操作超时（默认值：20.0）
• --safe-mode / --no-safe-mode：启用/禁用安全模式（默认：启用）
• --interactive：为需要输入的命令启用交互模式
• --transport {stdio}：设置传输类型（目前仅支持stdio）

示例

# Start with custom working directory and increased timeout
terminal-toolkit-mcp --working-directory /tmp/workspace --timeout 60.0

# Start with safe mode disabled (not recommended)
terminal-toolkit-mcp --no-safe-mode

可用工具

服务器通过MCP公开以下工具：

1. shell-exec（id，命令）：在会话中执行shell命令
2. 外壳视图（id）：查看会话的输出历史记录
3. shell_wait（id，秒）：等待正在运行的命令完成
4. shell_write_to_进程（id、输入、按enter）：向正在运行的进程发送输入
5. shell_kill_process（id）：终止正在运行的进程
6. ask_user_for_help（id）：请求人力援助

MCP客户端配置

要将此服务器与MCP客户端一起使用，您需要配置客户端以连接到终端工具包服务器。以下是不同场景的示例：

适用于克劳德桌面

将此配置添加到您的Claude Desktop设置中(~/Library/Application Support/Claude/claude_desktop_config.json 在 macOS 上：

{
  "mcpServers": {
    "terminal-toolkit": {
      "command": "uvx",
      "args": ["terminal-toolkit-mcp"]
    }
  }
}

CAMEL框架

选项1：使用MCPClient（直接连接）

import asyncio
from camel.utils.mcp_client import MCPClient

async def main():
    config = {
        "command": "uvx",
        "args": ["terminal-toolkit-mcp"]
    }
    
    async with MCPClient(config) as client:
        # List available tools
        tools = await client.list_mcp_tools()
        print("Available tools:", [tool.name for tool in tools.tools])
        
        # Execute a shell command
        result = await client.call_tool(
            "shell_exec", 
            {"id": "main", "command": "ls -la"}
        )
        print("Command output:", result.content[0].text)

asyncio.run(main())

选项2：使用MCPToolkit（推荐给代理）

import asyncio
from pathlib import Path
from camel.agents import ChatAgent
from camel.models import ModelFactory
from camel.toolkits import MCPToolkit
from camel.types import ModelPlatformType, ModelType

async def main():
    # Configuration for terminal toolkit
    config = {
        "mcpServers": {
            "terminal-toolkit": {
                "command": "uvx",
                "args": ["terminal-toolkit-mcp"]
            }
        }
    }
    
    # Connect to MCP server
    async with MCPToolkit(config=config) as mcp_toolkit:
        # Create an agent with terminal tools
        model = ModelFactory.create(
            model_platform=ModelPlatformType.DEFAULT,
            model_type=ModelType.DEFAULT,
        )
        
        agent = ChatAgent(
            system_message="You are a helpful assistant with terminal access.",
            model=model,
            tools=[*mcp_toolkit.get_tools()],
        )
        
        # Use the agent
        response = await agent.astep(
            "List the files in the current directory and show their sizes"
        )
        print(response.msgs[0].content)

asyncio.run(main())

配置选项

您可以通过传递其他参数来自定义服务器行为：

{
  "mcpServers": {
    "terminal-toolkit": {
      "command": "uvx",
      "args": [
        "terminal-toolkit-mcp",
        "--working-directory", "/path/to/workspace",
        "--timeout", "30.0",
        "--safe-mode"
      ]
    }
  }
}

可用配置选项：

• --working-directory PATH：设置终端操作的工作目录
• --timeout SECONDS：设置操作超时（默认值：20.0）
• --safe-mode / --no-safe-mode：启用/禁用安全模式（默认：启用）
• --interactive：为需要输入的命令启用交互模式

替代安装方法

如果您在本地安装了该软件包，您还可以使用：

{
  "mcpServers": {
    "terminal-toolkit": {
      "command": "terminal-toolkit-mcp"
    }
  }
}

或者，如果您更喜欢传统的可执行文件名：

{
  "mcpServers": {
    "terminal-toolkit": {
      "command": "uvx",
      "args": ["--from", "terminal-toolkit-mcp", "camel-terminal-mcp"]
    }
  }
}

完整使用示例

示例1：基本终端操作

import asyncio
from camel.utils.mcp_client import MCPClient

async def terminal_example():
    config = {
        "command": "uvx",
        "args": ["terminal-toolkit-mcp"]
    }
    
    async with MCPClient(config) as client:
        # Start a shell session and run commands
        session_id = "demo"
        
        # List directory contents
        result = await client.call_tool(
            "shell_exec", 
            {"id": session_id, "command": "pwd && ls -la"}
        )
        print("Directory listing:")
        print(result.content[0].text)
        
        # Create a file and check it
        await client.call_tool(
            "shell_exec",
            {"id": session_id, "command": "echo 'Hello MCP!' > test.txt"}
        )
        
        result = await client.call_tool(
            "shell_exec",
            {"id": session_id, "command": "cat test.txt"}
        )
        print("File contents:")
        print(result.content[0].text)
        
        # Clean up
        await client.call_tool(
            "shell_exec",
            {"id": session_id, "command": "rm test.txt"}
        )

asyncio.run(terminal_example())

示例2：交互式流程管理

import asyncio
from camel.utils.mcp_client import MCPClient

async def interactive_example():
    config = {
        "command": "uvx",
        "args": ["terminal-toolkit-mcp", "--interactive"]
    }
    
    async with MCPClient(config) as client:
        session_id = "interactive"
        
        # Start an interactive process (e.g., Python REPL)
        await client.call_tool(
            "shell_exec",
            {"id": session_id, "command": "python3"}
        )
        
        # Send input to the running process
        await client.call_tool(
            "shell_write_to_process",
            {
                "id": session_id,
                "input": "print('Hello from Python!')",
                "press_enter": True
            }
        )
        
        # Wait and view output
        await client.call_tool("shell_wait", {"id": session_id, "seconds": 1})
        
        result = await client.call_tool("shell_view", {"id": session_id})
        print("Python output:")
        print(result.content[0].text)
        
        # Exit Python
        await client.call_tool(
            "shell_write_to_process",
            {"id": session_id, "input": "exit()", "press_enter": True}
        )

asyncio.run(interactive_example())

示例3：具有终端访问权限的代理

import asyncio
from camel.agents import ChatAgent
from camel.models import ModelFactory
from camel.toolkits import MCPToolkit
from camel.types import ModelPlatformType, ModelType

async def agent_example():
    config = {
        "mcpServers": {
            "terminal": {
                "command": "uvx",
                "args": ["terminal-toolkit-mcp"]
            }
        }
    }
    
    async with MCPToolkit(config=config) as mcp_toolkit:
        model = ModelFactory.create(
            model_platform=ModelPlatformType.DEFAULT,
            model_type=ModelType.DEFAULT,
        )
        
        agent = ChatAgent(
            system_message="You are a helpful coding assistant with terminal access. "
                         "Use the terminal tools to help users with their tasks.",
            model=model,
            tools=[*mcp_toolkit.get_tools()],
        )
        
        # Example tasks
        tasks = [
            "Create a simple Python script that prints 'Hello World' and run it",
            "Check the current Git status and show me the recent commits",
            "Find all Python files in the current directory and count the lines of code"
        ]
        
        for task in tasks:
            print(f"\n🤖 Task: {task}")
            response = await agent.astep(task)
            print(f"📝 Response: {response.msgs[0].content}")

asyncio.run(agent_example())

安全功能

启用安全模式时（默认）：

• 命令仅限于工作目录
• 危险系统命令被阻止
• 文件操作仅限于工作区
• 禁止网络命令

发展

设置开发环境

uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

运行测试

pytest

代码格式化

ruff check .
ruff format .

故障排除

常见问题

1.“一个名为 terminal-toolkit-mcp 未提供”

如果您看到此错误，则表示软件包安装不正确，或者uvx正在使用缓存版本。尝试：

# Clear uvx cache and reinstall
uvx --from terminal-toolkit-mcp==0.1.2 terminal-toolkit-mcp --help

# Or use the legacy executable name
uvx --from terminal-toolkit-mcp camel-terminal-mcp --help

2.MCP连接失败

确保服务器正确启动：

# Test the server directly
terminal-toolkit-mcp --help

# Check if uvx can run it
uvx terminal-toolkit-mcp --help

3.权限被拒绝错误

在安全模式（默认）下，某些操作可能会受到限制。你可以：

• 使用 --working-directory 设置适当的工作区
• 禁用安全模式 --no-safe-mode （不建议用于生产）

4.刀具参数验证错误

确保提供所有必需的参数：

# Correct usage
await client.call_tool("shell_exec", {"id": "session1", "command": "ls"})

# Missing required 'id' parameter will cause an error
await client.call_tool("shell_exec", {"command": "ls"})  # ❌ Error

调试模式

通过设置环境变量启用详细日志记录：

export PYTHONPATH=.
python -m camel_terminal_toolkit.server --help

许可证

Apache许可证2.0-有关完整的许可证详细信息，请参阅CAMEL-AI项目。

贡献

该项目是CAMEL-AI生态系统的一部分。请参阅CAMEL主存储库以获取贡献指南。

更新日志

v0.1.2

• 完整的MCP配置文档：为Claude Desktop、CAMEL Framework和其他MCP客户端添加了全面的指南
• 工作示例：添加了基本操作、交互流程和代理集成的完整使用示例
• 故障排除指南：添加了详细的故障排除部分，其中包含常见问题和解决方案
• 已验证PyPI集成：确认简单配置 uvx terminal-toolkit-mcp 与PyPI包配合使用
• 增强的客户端示例：更新实例，展示实际工作成果

v0.1.1

• 修复了可执行文件名配置
• 增加了对两者的支持 terminal-toolkit-mcp 和 camel-terminal-mcp 可执行文件
• 更新了包含全面MCP配置示例的文档
• 改进的客户端配置示例

v0.1.0

• 初始版本
• 基本终端工具包功能
• MCP服务器实现
• 安全模式和交互支持