Terminal Controller

🚀 终端控制器 MCP 服务器

终端控制器 MCP 服务器是一个基于 Model Context Protocol (MCP) 的服务器，它借助标准化接口，实现了安全的终端命令执行、目录导航以及文件系统操作，为用户提供了便捷且安全的终端控制体验。

🚀 快速开始

终端控制器 MCP 服务器能帮助你通过标准化接口安全地执行终端命令、进行目录导航和文件系统操作。以下是使用前的系统要求和安装步骤。

系统要求

• 操作系统：Linux 或 macOS
• Python 版本：3.11 或更高版本

安装步骤

1. 使用以下命令安装依赖项：

   pip install terminal_controller
   

2. 启动终端控制器服务器：

   python -m terminal_controller
   

✨ 主要特性

• 命令执行：支持终端命令的执行，包括文件管理和系统操作。
• 目录导航：提供目录浏览和导航功能。
• 文件操作：包括文件读取、写入、插入、删除和更新等操作。
• 安全性：内置安全机制，防止危险命令的执行。

📦 安装指南

系统要求

• 操作系统：Linux 或 macOS
• Python 版本：3.11 或更高版本

安装步骤

1. 使用以下命令安装依赖项：

   pip install terminal_controller
   

2. 启动终端控制器服务器：

   python -m terminal_controller
   

💻 使用示例

基本用法

# 执行命令
mcp exec "ls -l"

# 导航目录
mcp cd /path/to/directory

# 读取文件
mcp read_file example.txt

高级用法

# 插入内容
mcp insert_file_content example.txt "new content" 5

# 删除内容
mcp delete_file_content example.txt 3

📚 详细文档

客户端配置

支持的客户端

• Claude Desktop
• 其他 MCP 兼容客户端

配置示例

在 config.json 文件中添加以下内容：

{
  "server_address": "localhost:8000",
  "timeout": 3600
}

API 参考

命令执行

def execute_command(command: str, timeout: int = 3600) -> dict:
    """
    执行终端命令。
    
    参数：
        command (str): 要执行的命令
        timeout (int): 超时时间（秒，默认为 3600）
        
    返回值：
        dict：包含结果或错误信息的字典
    """

文件读取

def read_file(path: str, start_row: int = None, end_row: int = None) -> str:
    """
    从文件中读取内容。
    
    参数：
        path (str): 文件路径
        start_row (int, 可选): 开始行（0 基础）
        end_row (int, 可选): 结束行（0 基础，包含）
        
    返回值：
        str：文件内容或指定范围的内容
    """

🔧 技术细节

安全考虑

• 超时控制：防止长时间运行的命令。
• 黑名单危险命令：阻止如 rm -rf / 等危险操作。
• 错误处理：隔离命令执行环境，确保安全性。

限制

• 默认情况下，服务器具有与运行它的用户相同的文件系统权限。
• 部分交互式命令可能无法正常工作，因为终端是非交互式的。

故障排除

1. 检查 Python 版本是否为 3.11 或更高。
2. 确保客户端配置正确。
3. 直接运行终端控制器以检查错误：

   python -m terminal_controller
   

4. 对于 UVX 相关问题，尝试：

   uvx terminal_controller
   

📄 许可证

本项目采用 MIT 许可证。

贡献

欢迎贡献！请随意提交 Pull Request。