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。