MCP Widget Usage Guide

starred/electerm

Fork 0

mirror of https://github.com/electerm/electerm.git synced 2026-04-25 05:25:50 +03:00

Table of Contents

MCP Widget Usage Guide

English

Overview
Features
Configuration
Architecture
How to Use
Available Tools

Terminal Management (Always Enabled)
Bookmark Management (if enabled)
Bookmark Groups (if enabled)
Quick Commands (if enabled)
History (if enabled)
SFTP APIs (if enabled)
Settings (if enabled)

Complete Example
Error Handling
CORS Configuration
Security Notes
Testing

中文

概述
功能特性
配置选项
架构
使用方法
可用工具

终端管理（始终启用）
书签管理（如果启用）
书签组（如果启用）
快捷命令（如果启用）
历史记录（如果启用）
SFTP API（如果启用）
设置（如果启用）

完整示例
错误处理
CORS 配置
安全注意事项
测试

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

English | 中文

English

Overview

⚠️ Development Notice: The MCP widget is currently under active development. APIs and interfaces may change without notice. Please check for updates regularly.

The MCP (Model Context Protocol) widget is a built-in Electerm widget that exposes Electerm's APIs via the Model Context Protocol. This allows AI assistants and external tools to interact with Electerm programmatically, enabling automation of terminal operations, bookmark management, and other features.

Features

HTTP Server: Runs a local HTTP server (default: http://127.0.0.1:30837/mcp)
Server-Sent Events (SSE): Uses SSE for real-time communication
Session Management: Supports multiple concurrent sessions with unique session IDs
CORS Support: Allows cross-origin requests for web-based integrations
IPC Communication: Uses Electron's IPC to communicate with the main Electerm application
Configurable APIs: Enable/disable different API groups based on needs
SFTP Support: Full SFTP operations (list, stat, read, delete, upload, download)
Zmodem Support: File transfer via trzsz/rzsz protocols

Configuration

The MCP widget can be configured with the following options:

Host: IP address to bind the server to (default: 127.0.0.1)
Port: Port number to listen on (default: 30837)
Enable Bookmarks: Enable bookmark management APIs (default: true)
Enable Bookmark Groups: Enable bookmark group APIs (default: true)
Enable SFTP: Enable SFTP APIs (list, stat, read, delete, upload, download, trzsz) (default: true)
Enable Settings: Enable settings APIs (default: false)

Architecture

The MCP widget consists of several key components:

Express Server: Handles HTTP requests and CORS
MCP Server: Implements the Model Context Protocol
Streamable HTTP Transport: Manages SSE communication
IPC Bridge: Communicates with Electerm's renderer process
Tool Registry: Registers available tools based on configuration

How to Use

Start the Widget:
- Open Electerm
- Go to Widgets panel
- Select "MCP Server" widget
- Configure options as needed
- Click "Run"
Connect to the Server:
- The server will be available at http://127.0.0.1:30837/mcp (or configured host/port)
- Use HTTP POST requests with JSON-RPC 2.0 protocol
- Include mcp-session-id header for session management
- Responses are sent via Server-Sent Events (SSE)

Initialize Session:

POST /mcp
Content-Type: application/json
Accept: application/json, text/event-stream

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "your-client",
      "version": "1.0.0"
    }
  }
}

Response (SSE):

event: message
data: {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","serverInfo":{"name":"electerm-mcp-server","version":"1.0.0"},"capabilities":{}}}

Available Tools

Terminal Management (Always Enabled)

list_electerm_tabs: List all open terminal tabs

{
  "name": "list_electerm_tabs",
  "description": "List all open electerm terminal tabs",
  "inputSchema": {"type": "object", "properties": {}}
}

get_electerm_active_tab: Get the currently active tab

{
  "name": "get_electerm_active_tab",
  "description": "Get the currently active electerm tab",
  "inputSchema": {"type": "object", "properties": {}}
}

switch_electerm_tab: Switch to a specific tab

{
  "name": "switch_electerm_tab",
  "description": "Switch to a specific electerm tab",
  "inputSchema": {
    "type": "object",
    "properties": {
      "tabId": {"type": "string", "description": "Tab ID to switch to"}
    },
    "required": ["tabId"]
  }
}

close_electerm_tab: Close a specific tab

{
  "name": "close_electerm_tab",
  "description": "Close a specific electerm tab",
  "inputSchema": {
    "type": "object",
    "properties": {
      "tabId": {"type": "string", "description": "Tab ID to close"}
    },
    "required": ["tabId"]
  }
}

reload_electerm_tab: Reload/reconnect a tab

{
  "name": "reload_electerm_tab",
  "description": "Reload/reconnect an electerm tab",
  "inputSchema": {
    "type": "object",
    "properties": {
      "tabId": {"type": "string", "description": "Tab ID to reload (default: active tab)"}
    }
  }
}

duplicate_electerm_tab: Duplicate a tab

{
  "name": "duplicate_electerm_tab",
  "description": "Duplicate an electerm tab",
  "inputSchema": {
    "type": "object",
    "properties": {
      "tabId": {"type": "string", "description": "Tab ID to duplicate"}
    },
    "required": ["tabId"]
  }
}

open_electerm_local_terminal: Open a new local terminal tab

{
  "name": "open_electerm_local_terminal",
  "description": "Open a new electerm local terminal tab",
  "inputSchema": {"type": "object", "properties": {}}
}

send_electerm_terminal_command: Send a command to the active terminal

{
  "name": "send_electerm_terminal_command",
  "description": "Send a command to the active electerm terminal",
  "inputSchema": {
    "type": "object",
    "properties": {
      "command": {"type": "string", "description": "Command to send"},
      "tabId": {"type": "string", "description": "Optional: specific tab ID"},
      "inputOnly": {"type": "boolean", "description": "Input only mode (no enter key)"}
    },
    "required": ["command"]
  }
}

get_electerm_terminal_selection: Get current text selection in terminal

{
  "name": "get_electerm_terminal_selection",
  "description": "Get the current text selection in electerm terminal",
  "inputSchema": {
    "type": "object",
    "properties": {
      "tabId": {"type": "string", "description": "Optional: specific tab ID"}
    }
  }
}

get_electerm_terminal_output: Get recent terminal output

{
  "name": "get_electerm_terminal_output",
  "description": "Get recent electerm terminal output/buffer content",
  "inputSchema": {
    "type": "object",
    "properties": {
      "tabId": {"type": "string", "description": "Optional: specific tab ID"},
      "lines": {"type": "number", "description": "Number of lines to return (default: 50)"}
    }
  }
}

Bookmark Management (if enabled)

list_electerm_bookmarks: List all bookmarks

{
  "name": "list_electerm_bookmarks",
  "description": "List all electerm SSH/terminal bookmarks",
  "inputSchema": {"type": "object", "properties": {}}
}

get_electerm_bookmark: Get a specific bookmark

{
  "name": "get_electerm_bookmark",
  "description": "Get a specific electerm bookmark by ID",
  "inputSchema": {
    "type": "object",
    "properties": {
      "id": {"type": "string", "description": "Bookmark ID"}
    },
    "required": ["id"]
  }
}

add_electerm_bookmark_ssh: Add a new SSH bookmark

{
  "name": "add_electerm_bookmark_ssh",
  "description": "Add a new SSH bookmark to electerm",
  "inputSchema": {
    "type": "object",
    "properties": {
      "title": {"type": "string", "description": "Bookmark title"},
      "host": {"type": "string", "description": "SSH host address"},
      "port": {"type": "number", "description": "SSH port (default 22)"},
      "username": {"type": "string", "description": "SSH username"},
      "password": {"type": "string", "description": "SSH password (optional)"}
    },
    "required": ["title", "host", "username"]
  }
}

add_electerm_bookmark_telnet: Add a new Telnet bookmark

{
  "name": "add_electerm_bookmark_telnet",
  "description": "Add a new Telnet bookmark to electerm",
  "inputSchema": {
    "type": "object",
    "properties": {
      "title": {"type": "string", "description": "Bookmark title"},
      "host": {"type": "string", "description": "Telnet host address"},
      "port": {"type": "number", "description": "Telnet port"}
    },
    "required": ["title", "host", "port"]
  }
}

add_electerm_bookmark_serial: Add a new Serial bookmark

{
  "name": "add_electerm_bookmark_serial",
  "description": "Add a new Serial bookmark to electerm",
  "inputSchema": {
    "type": "object",
    "properties": {
      "title": {"type": "string", "description": "Bookmark title"},
      "port": {"type": "string", "description": "Serial port path"},
      "baudRate": {"type": "number", "description": "Baud rate"}
    },
    "required": ["title", "port"]
  }
}

add_electerm_bookmark_local: Add a new Local terminal bookmark

{
  "name": "add_electerm_bookmark_local",
  "description": "Add a new Local terminal bookmark to electerm",
  "inputSchema": {
    "type": "object",
    "properties": {
      "title": {"type": "string", "description": "Bookmark title"}
    },
    "required": ["title"]
  }
}

edit_electerm_bookmark: Edit an existing bookmark

{
  "name": "edit_electerm_bookmark",
  "description": "Edit an existing electerm bookmark",
  "inputSchema": {
    "type": "object",
    "properties": {
      "id": {"type": "string", "description": "Bookmark ID to edit"},
      "updates": {"type": "object", "description": "Fields to update"}
    },
    "required": ["id", "updates"]
  }
}

delete_electerm_bookmark: Delete a bookmark

{
  "name": "delete_electerm_bookmark",
  "description": "Delete an electerm bookmark",
  "inputSchema": {
    "type": "object",
    "properties": {
      "id": {"type": "string", "description": "Bookmark ID to delete"}
    },
    "required": ["id"]
  }
}

open_electerm_bookmark: Open a bookmark in a new tab

{
  "name": "open_electerm_bookmark",
  "description": "Open an electerm bookmark in a new tab",
  "inputSchema": {
    "type": "object",
    "properties": {
      "id": {"type": "string", "description": "Bookmark ID to open"}
    },
    "required": ["id"]
  }
}

Bookmark Groups (if enabled)

list_electerm_bookmark_groups: List bookmark groups

{
  "name": "list_electerm_bookmark_groups",
  "description": "List all electerm bookmark groups/folders",
  "inputSchema": {"type": "object", "properties": {}}
}

add_electerm_bookmark_group: Add a bookmark group

{
  "name": "add_electerm_bookmark_group",
  "description": "Add a new electerm bookmark group",
  "inputSchema": {
    "type": "object",
    "properties": {
      "title": {"type": "string", "description": "Group title"},
      "parentId": {"type": "string", "description": "Optional parent group ID"}
    },
    "required": ["title"]
  }
}

Quick Commands (if enabled)

list_electerm_quick_commands: List quick commands

{
  "name": "list_electerm_quick_commands",
  "description": "List all electerm quick commands",
  "inputSchema": {"type": "object", "properties": {}}
}

add_electerm_quick_command: Add a quick command

{
  "name": "add_electerm_quick_command",
  "description": "Add a new electerm quick command",
  "inputSchema": {
    "type": "object",
    "properties": {
      "name": {"type": "string", "description": "Quick command name"},
      "command": {"type": "string", "description": "Single command to execute"},
      "commands": {"type": "array", "items": {"type": "object"}, "description": "Multiple commands with delays"},
      "labels": {"type": "array", "items": {"type": "string"}, "description": "Tags/labels for the command"}
    },
    "required": ["name"]
  }
}

run_electerm_quick_command: Run a quick command

{
  "name": "run_electerm_quick_command",
  "description": "Run an electerm quick command in the active terminal",
  "inputSchema": {
    "type": "object",
    "properties": {
      "id": {"type": "string", "description": "Quick command ID to run"}
    },
    "required": ["id"]
  }
}

delete_electerm_quick_command: Delete a quick command

{
  "name": "delete_electerm_quick_command",
  "description": "Delete an electerm quick command",
  "inputSchema": {
    "type": "object",
    "properties": {
      "id": {"type": "string", "description": "Quick command ID to delete"}
    },
    "required": ["id"]
  }
}

History (if enabled)

list_electerm_history: List connection history

{
  "name": "list_electerm_history",
  "description": "List electerm connection history",
  "inputSchema": {
    "type": "object",
    "properties": {
      "limit": {"type": "number", "description": "Max number of entries (default 50)"}
    }
  }
}

clear_electerm_history: Clear connection history

{
  "name": "clear_electerm_history",
  "description": "Clear electerm connection history",
  "inputSchema": {"type": "object", "properties": {}}
}

SFTP APIs (if enabled)

electerm_sftp_list: List remote directory contents

{
  "name": "electerm_sftp_list",
  "description": "List files and folders in a remote directory on the SSH-connected tab",
  "inputSchema": {
    "type": "object",
    "properties": {
      "tabId": {"type": "string", "description": "SSH tab ID (default: active tab)"},
      "remotePath": {"type": "string", "description": "Remote directory path to list"}
    },
    "required": ["remotePath"]
  }
}

electerm_sftp_stat: Get remote file/directory info

{
  "name": "electerm_sftp_stat",
  "description": "Get file or directory stat/info on the remote SSH server",
  "inputSchema": {
    "type": "object",
    "properties": {
      "tabId": {"type": "string", "description": "SSH tab ID (default: active tab)"},
      "remotePath": {"type": "string", "description": "Remote file or directory path"}
    },
    "required": ["remotePath"]
  }
}

electerm_sftp_read_file: Read remote file content

{
  "name": "electerm_sftp_read_file",
  "description": "Read the content of a remote file on the SSH server",
  "inputSchema": {
    "type": "object",
    "properties": {
      "tabId": {"type": "string", "description": "SSH tab ID (default: active tab)"},
      "remotePath": {"type": "string", "description": "Remote file path to read"}
    },
    "required": ["remotePath"]
  }
}

electerm_sftp_del_file_or_folder: Delete remote file or folder

{
  "name": "electerm_sftp_del_file_or_folder",
  "description": "Delete a file or folder on the remote SSH server",
  "inputSchema": {
    "type": "object",
    "properties": {
      "tabId": {"type": "string", "description": "SSH tab ID (default: active tab)"},
      "remotePath": {"type": "string", "description": "Remote file or directory path to delete"}
    },
    "required": ["remotePath"]
  }
}

electerm_sftp_upload: Upload file via SFTP

{
  "name": "electerm_sftp_upload",
  "description": "Upload a local file or folder to the remote SSH server using the SFTP transfer panel",
  "inputSchema": {
    "type": "object",
    "properties": {
      "tabId": {"type": "string", "description": "SSH tab ID (default: active tab)"},
      "localPath": {"type": "string", "description": "Local file or folder path to upload"},
      "remotePath": {"type": "string", "description": "Remote destination path"},
      "conflictPolicy": {"type": "string", "enum": ["overwrite", "rename"], "description": "Conflict policy: overwrite or rename (default: overwrite)"}
    },
    "required": ["localPath", "remotePath"]
  }
}

electerm_sftp_download: Download file via SFTP

{
  "name": "electerm_sftp_download",
  "description": "Download a remote file or folder from the SSH server to a local path using the SFTP transfer panel",
  "inputSchema": {
    "type": "object",
    "properties": {
      "tabId": {"type": "string", "description": "SSH tab ID (default: active tab)"},
      "remotePath": {"type": "string", "description": "Remote file or directory path to download"},
      "localPath": {"type": "string", "description": "Local destination path"},
      "conflictPolicy": {"type": "string", "enum": ["overwrite", "rename"], "description": "Conflict policy: overwrite or rename (default: overwrite)"}
    },
    "required": ["remotePath", "localPath"]
  }
}

electerm_zmodem_upload: Upload files via trzsz/rzsz

{
  "name": "electerm_zmodem_upload",
  "description": "Upload local files to the remote SSH server using trzsz (trz) or rzsz (rz). The SSH tab must have the chosen protocol installed.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "tabId": {"type": "string", "description": "SSH tab ID (default: active tab)"},
      "files": {"type": "array", "items": {"type": "string"}, "description": "List of local file paths to upload"},
      "protocol": {"type": "string", "enum": ["trzsz", "rzsz"], "description": "Transfer protocol: trzsz (trz) or rzsz (rz) (default: rzsz)"}
    },
    "required": ["files"]
  }
}

electerm_zmodem_download: Download files via trzsz/rzsz

{
  "name": "electerm_zmodem_download",
  "description": "Download remote files from the SSH server using trzsz (tsz) or rzsz (sz). The SSH tab must have the chosen protocol installed.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "tabId": {"type": "string", "description": "SSH tab ID (default: active tab)"},
      "remoteFiles": {"type": "array", "items": {"type": "string"}, "description": "List of remote file paths to download"},
      "saveFolder": {"type": "string", "description": "Local folder path to save downloaded files"},
      "protocol": {"type": "string", "enum": ["trzsz", "rzsz"], "description": "Transfer protocol: trzsz (tsz) or rzsz (sz) (default: rzsz)"}
    },
    "required": ["remoteFiles", "saveFolder"]
  }
}

Settings (if enabled)

get_electerm_settings: Get application settings

{
  "name": "get_electerm_settings",
  "description": "Get current electerm application settings",
  "inputSchema": {"type": "object", "properties": {}}
}

Complete Example

Here's a complete example showing how to initialize a session and perform operations:

const axios = require('axios');

async function example() {
  const serverUrl = 'http://127.0.0.1:30837/mcp';

  try {
    // 1. Initialize session
    const initResponse = await axios.post(serverUrl, {
      jsonrpc: '2.0',
      id: 1,
      method: 'initialize',
      params: {
        protocolVersion: '2024-11-05',
        capabilities: {},
        clientInfo: { name: 'example-client', version: '1.0.0' }
      }
    }, {
      headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json, text/event-stream'
      }
    });

    const sessionId = initResponse.headers['mcp-session-id'];
    console.log('Session ID:', sessionId);

    // 2. List available tools
    const toolsResponse = await axios.post(serverUrl, {
      jsonrpc: '2.0',
      id: 2,
      method: 'tools/list',
      params: {}
    }, {
      headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json, text/event-stream',
        'mcp-session-id': sessionId
      }
    });

    // Parse SSE response
    const toolsData = JSON.parse(toolsResponse.data.split('\n')
      .find(line => line.startsWith('data: '))
      .substring(6));

    console.log('Available tools:', toolsData.result.tools.map(t => t.name));

    // 3. Open a local terminal
    const terminalResponse = await axios.post(serverUrl, {
      jsonrpc: '2.0',
      id: 3,
      method: 'tools/call',
      params: {
        name: 'open_electerm_local_terminal',
        arguments: {}
      }
    }, {
      headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json, text/event-stream',
        'mcp-session-id': sessionId
      }
    });

    // 4. Send a command
    const commandResponse = await axios.post(serverUrl, {
      jsonrpc: '2.0',
      id: 4,
      method: 'tools/call',
      params: {
        name: 'send_electerm_terminal_command',
        arguments: { command: 'echo "Hello from MCP!"' }
      }
    }, {
      headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json, text/event-stream',
        'mcp-session-id': sessionId
      }
    });

    // 5. Get terminal output
    const outputResponse = await axios.post(serverUrl, {
      jsonrpc: '2.0',
      id: 5,
      method: 'tools/call',
      params: {
        name: 'get_electerm_terminal_output',
        arguments: { lines: 10 }
      }
    }, {
      headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json, text/event-stream',
        'mcp-session-id': sessionId
      }
    });

  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

example();

Error Handling

The MCP server provides detailed error responses:

{
  "jsonrpc": "2.0",
  "id": 123,
  "error": {
    "code": -32603,
    "message": "Internal server error",
    "data": "Additional error details"
  }
}

Common error codes:

-32603: Internal server error (e.g., no active window)
-32602: Invalid params
-32601: Method not found

CORS Configuration

The server is configured with permissive CORS headers:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, mcp-session-id

Security Notes

The server runs locally by default
CORS is enabled for cross-origin access
No authentication is implemented - use at your own risk
Consider firewall rules if exposing to network
Session IDs are generated server-side for each new session
Requests timeout after 30 seconds by default

Testing

The widget includes comprehensive tests that verify:

Server accessibility and CORS configuration
MCP protocol initialization
Tool listing and calling
Session management
SFTP operations (list, stat, read, delete)
File transfer operations (upload, download)
Zmodem operations (trzsz/rzsz upload/download)
Error handling in various scenarios

Run tests with: npm run test2 (includes MCP widget tests)

中文

概述

⚠️ 开发提醒：MCP 组件目前正在积极开发中。API 和接口可能会在没有通知的情况下发生变化。请定期检查更新。

MCP (Model Context Protocol) 组件是 Electerm 的内置组件，通过模型上下文协议暴露 Electerm 的 API。这允许 AI 助手和外部工具以编程方式与 Electerm 交互，实现终端操作、书签管理等功能的自动化。

功能特性

HTTP 服务器：运行本地 HTTP 服务器（默认：http://127.0.0.1:30837/mcp）
服务器发送事件 (SSE)：使用 SSE 进行实时通信
会话管理：支持多个并发会话，具有唯一的会话 ID
CORS 支持：允许跨域请求，支持网页集成
IPC 通信：使用 Electron 的 IPC 与主 Electerm 应用程序通信
可配置 API：根据需要启用/禁用不同的 API 组
SFTP 支持：完整的 SFTP 操作（列表、stat、读取、删除、上传、下载）
Zmodem 支持：通过 trzsz/rzsz 协议进行文件传输

配置选项

MCP 组件可以配置以下选项：

主机：服务器绑定 IP 地址（默认：127.0.0.1）
端口：监听端口号（默认：30837）
启用书签：启用书签管理 API（默认：true）
启用书签组：启用书签组 API（默认：true）
启用 SFTP：启用 SFTP API（列表、stat、读取、删除、上传、下载、trzsz）（默认：true）
启用设置：启用设置 API（默认：false）

架构

MCP 组件由几个关键组件组成：

Express 服务器：处理 HTTP 请求和 CORS
MCP 服务器：实现模型上下文协议
可流式 HTTP 传输：管理 SSE 通信
IPC 桥接：与 Electerm 的渲染进程通信
工具注册表：根据配置注册可用工具

使用方法

启动组件：
- 打开 Electerm
- 进入组件面板
- 选择 "MCP Server" 组件
- 根据需要配置选项
- 点击 "运行"
连接服务器：
- 服务器将在 http://127.0.0.1:30837/mcp 可用（或配置的主机/端口）
- 使用 HTTP POST 请求，JSON-RPC 2.0 协议
- 包含 mcp-session-id 头部进行会话管理
- 响应通过服务器发送事件 (SSE) 发送

初始化会话：

POST /mcp
Content-Type: application/json
Accept: application/json, text/event-stream

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "your-client",
      "version": "1.0.0"
    }
  }
}

响应 (SSE)：

event: message
data: {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","serverInfo":{"name":"electerm-mcp-server","version":"1.0.0"},"capabilities":{}}}

可用工具

终端管理（始终启用）

list_electerm_tabs：列出所有打开的终端标签页

{
  "name": "list_electerm_tabs",
  "description": "List all open electerm terminal tabs",
  "inputSchema": {"type": "object", "properties": {}}
}

get_electerm_active_tab：获取当前活动标签页

{
  "name": "get_electerm_active_tab",
  "description": "Get the currently active electerm tab",
  "inputSchema": {"type": "object", "properties": {}}
}

switch_electerm_tab：切换到指定标签页

{
  "name": "switch_electerm_tab",
  "description": "Switch to a specific electerm tab",
  "inputSchema": {
    "type": "object",
    "properties": {
      "tabId": {"type": "string", "description": "Tab ID to switch to"}
    },
    "required": ["tabId"]
  }
}

close_electerm_tab：关闭指定标签页

{
  "name": "close_electerm_tab",
  "description": "Close a specific electerm tab",
  "inputSchema": {
    "type": "object",
    "properties": {
      "tabId": {"type": "string", "description": "Tab ID to close"}
    },
    "required": ["tabId"]
  }
}

reload_electerm_tab：重新加载/重连标签页

{
  "name": "reload_electerm_tab",
  "description": "Reload/reconnect an electerm tab",
  "inputSchema": {
    "type": "object",
    "properties": {
      "tabId": {"type": "string", "description": "Tab ID to reload (default: active tab)"}
    }
  }
}

duplicate_electerm_tab：复制标签页

{
  "name": "duplicate_electerm_tab",
  "description": "Duplicate an electerm tab",
  "inputSchema": {
    "type": "object",
    "properties": {
      "tabId": {"type": "string", "description": "Tab ID to duplicate"}
    },
    "required": ["tabId"]
  }
}

open_electerm_local_terminal：打开新的本地终端标签页

{
  "name": "open_electerm_local_terminal",
  "description": "Open a new electerm local terminal tab",
  "inputSchema": {"type": "object", "properties": {}}
}

send_electerm_terminal_command：向活动终端发送命令

{
  "name": "send_electerm_terminal_command",
  "description": "Send a command to the active electerm terminal",
  "inputSchema": {
    "type": "object",
    "properties": {
      "command": {"type": "string", "description": "Command to send"},
      "tabId": {"type": "string", "description": "Optional: specific tab ID"},
      "inputOnly": {"type": "boolean", "description": "Input only mode (no enter key)"}
    },
    "required": ["command"]
  }
}

get_electerm_terminal_selection：获取终端中的当前文本选择

{
  "name": "get_electerm_terminal_selection",
  "description": "Get the current text selection in electerm terminal",
  "inputSchema": {
    "type": "object",
    "properties": {
      "tabId": {"type": "string", "description": "Optional: specific tab ID"}
    }
  }
}

get_electerm_terminal_output：获取最近的终端输出

{
  "name": "get_electerm_terminal_output",
  "description": "Get recent electerm terminal output/buffer content",
  "inputSchema": {
    "type": "object",
    "properties": {
      "tabId": {"type": "string", "description": "Optional: specific tab ID"},
      "lines": {"type": "number", "description": "Number of lines to return (default: 50)"}
    }
  }
}

书签管理（如果启用）

list_electerm_bookmarks：列出所有书签

{
  "name": "list_electerm_bookmarks",
  "description": "List all electerm SSH/terminal bookmarks",
  "inputSchema": {"type": "object", "properties": {}}
}

get_electerm_bookmark：获取指定书签

{
  "name": "get_electerm_bookmark",
  "description": "Get a specific electerm bookmark by ID",
  "inputSchema": {
    "type": "object",
    "properties": {
      "id": {"type": "string", "description": "Bookmark ID"}
    },
    "required": ["id"]
  }
}

add_electerm_bookmark_ssh：添加 SSH 书签

{
  "name": "add_electerm_bookmark_ssh",
  "description": "Add a new SSH bookmark to electerm",
  "inputSchema": {
    "type": "object",
    "properties": {
      "title": {"type": "string", "description": "Bookmark title"},
      "host": {"type": "string", "description": "SSH host address"},
      "port": {"type": "number", "description": "SSH port (default 22)"},
      "username": {"type": "string", "description": "SSH username"},
      "password": {"type": "string", "description": "SSH password (optional)"}
    },
    "required": ["title", "host", "username"]
  }
}

add_electerm_bookmark_telnet：添加 Telnet 书签

{
  "name": "add_electerm_bookmark_telnet",
  "description": "Add a new Telnet bookmark to electerm",
  "inputSchema": {
    "type": "object",
    "properties": {
      "title": {"type": "string", "description": "Bookmark title"},
      "host": {"type": "string", "description": "Telnet host address"},
      "port": {"type": "number", "description": "Telnet port"}
    },
    "required": ["title", "host", "port"]
  }
}

add_electerm_bookmark_serial：添加 Serial 书签

{
  "name": "add_electerm_bookmark_serial",
  "description": "Add a new Serial bookmark to electerm",
  "inputSchema": {
    "type": "object",
    "properties": {
      "title": {"type": "string", "description": "Bookmark title"},
      "port": {"type": "string", "description": "Serial port path"},
      "baudRate": {"type": "number", "description": "Baud rate"}
    },
    "required": ["title", "port"]
  }
}

add_electerm_bookmark_local：添加本地终端书签

{
  "name": "add_electerm_bookmark_local",
  "description": "Add a new Local terminal bookmark to electerm",
  "inputSchema": {
    "type": "object",
    "properties": {
      "title": {"type": "string", "description": "Bookmark title"}
    },
    "required": ["title"]
  }
}

edit_electerm_bookmark：编辑现有书签

{
  "name": "edit_electerm_bookmark",
  "description": "Edit an existing electerm bookmark",
  "inputSchema": {
    "type": "object",
    "properties": {
      "id": {"type": "string", "description": "Bookmark ID to edit"},
      "updates": {"type": "object", "description": "Fields to update"}
    },
    "required": ["id", "updates"]
  }
}

delete_electerm_bookmark：删除书签

{
  "name": "delete_electerm_bookmark",
  "description": "Delete an electerm bookmark",
  "inputSchema": {
    "type": "object",
    "properties": {
      "id": {"type": "string", "description": "Bookmark ID to delete"}
    },
    "required": ["id"]
  }
}

open_electerm_bookmark：在新标签页中打开书签

{
  "name": "open_electerm_bookmark",
  "description": "Open an electerm bookmark in a new tab",
  "inputSchema": {
    "type": "object",
    "properties": {
      "id": {"type": "string", "description": "Bookmark ID to open"}
    },
    "required": ["id"]
  }
}

书签组（如果启用）

list_electerm_bookmark_groups：列出书签组

{
  "name": "list_electerm_bookmark_groups",
  "description": "List all electerm bookmark groups/folders",
  "inputSchema": {"type": "object", "properties": {}}
}

add_electerm_bookmark_group：添加书签组

{
  "name": "add_electerm_bookmark_group",
  "description": "Add a new electerm bookmark group",
  "inputSchema": {
    "type": "object",
    "properties": {
      "title": {"type": "string", "description": "Group title"},
      "parentId": {"type": "string", "description": "Optional parent group ID"}
    },
    "required": ["title"]
  }
}

快捷命令（如果启用）

list_electerm_quick_commands：列出快捷命令

{
  "name": "list_electerm_quick_commands",
  "description": "List all electerm quick commands",
  "inputSchema": {"type": "object", "properties": {}}
}

add_electerm_quick_command：添加快捷命令

{
  "name": "add_electerm_quick_command",
  "description": "Add a new electerm quick command",
  "inputSchema": {
    "type": "object",
    "properties": {
      "name": {"type": "string", "description": "Quick command name"},
      "command": {"type": "string", "description": "Single command to execute"},
      "commands": {"type": "array", "items": {"type": "object"}, "description": "Multiple commands with delays"},
      "labels": {"type": "array", "items": {"type": "string"}, "description": "Tags/labels for the command"}
    },
    "required": ["name"]
  }
}

run_electerm_quick_command：运行快捷命令

{
  "name": "run_electerm_quick_command",
  "description": "Run an electerm quick command in the active terminal",
  "inputSchema": {
    "type": "object",
    "properties": {
      "id": {"type": "string", "description": "Quick command ID to run"}
    },
    "required": ["id"]
  }
}

delete_electerm_quick_command：删除快捷命令

{
  "name": "delete_electerm_quick_command",
  "description": "Delete an electerm quick command",
  "inputSchema": {
    "type": "object",
    "properties": {
      "id": {"type": "string", "description": "Quick command ID to delete"}
    },
    "required": ["id"]
  }
}

历史记录（如果启用）

list_electerm_history：列出连接历史记录

{
  "name": "list_electerm_history",
  "description": "List electerm connection history",
  "inputSchema": {
    "type": "object",
    "properties": {
      "limit": {"type": "number", "description": "Max number of entries (default 50)"}
    }
  }
}

clear_electerm_history：清除连接历史记录

{
  "name": "clear_electerm_history",
  "description": "Clear electerm connection history",
  "inputSchema": {"type": "object", "properties": {}}
}

SFTP API（如果启用）

electerm_sftp_list：列出远程目录内容

{
  "name": "electerm_sftp_list",
  "description": "List files and folders in a remote directory on the SSH-connected tab",
  "inputSchema": {
    "type": "object",
    "properties": {
      "tabId": {"type": "string", "description": "SSH tab ID (default: active tab)"},
      "remotePath": {"type": "string", "description": "Remote directory path to list"}
    },
    "required": ["remotePath"]
  }
}

electerm_sftp_stat：获取远程文件/目录信息

{
  "name": "electerm_sftp_stat",
  "description": "Get file or directory stat/info on the remote SSH server",
  "inputSchema": {
    "type": "object",
    "properties": {
      "tabId": {"type": "string", "description": "SSH tab ID (default: active tab)"},
      "remotePath": {"type": "string", "description": "Remote file or directory path"}
    },
    "required": ["remotePath"]
  }
}

electerm_sftp_read_file：读取远程文件内容

{
  "name": "electerm_sftp_read_file",
  "description": "Read the content of a remote file on the SSH server",
  "inputSchema": {
    "type": "object",
    "properties": {
      "tabId": {"type": "string", "description": "SSH tab ID (default: active tab)"},
      "remotePath": {"type": "string", "description": "Remote file path to read"}
    },
    "required": ["remotePath"]
  }
}

electerm_sftp_del_file_or_folder：删除远程文件或文件夹

{
  "name": "electerm_sftp_del_file_or_folder",
  "description": "Delete a file or folder on the remote SSH server",
  "inputSchema": {
    "type": "object",
    "properties": {
      "tabId": {"type": "string", "description": "SSH tab ID (default: active tab)"},
      "remotePath": {"type": "string", "description": "Remote file or directory path to delete"}
    },
    "required": ["remotePath"]
  }
}

electerm_sftp_upload：通过 SFTP 上传文件

{
  "name": "electerm_sftp_upload",
  "description": "Upload a local file or folder to the remote SSH server using the SFTP transfer panel",
  "inputSchema": {
    "type": "object",
    "properties": {
      "tabId": {"type": "string", "description": "SSH tab ID (default: active tab)"},
      "localPath": {"type": "string", "description": "Local file or folder path to upload"},
      "remotePath": {"type": "string", "description": "Remote destination path"},
      "conflictPolicy": {"type": "string", "enum": ["overwrite", "rename"], "description": "Conflict policy: overwrite or rename (default: overwrite)"}
    },
    "required": ["localPath", "remotePath"]
  }
}

electerm_sftp_download：通过 SFTP 下载文件

{
  "name": "electerm_sftp_download",
  "description": "Download a remote file or folder from the SSH server to a local path using the SFTP transfer panel",
  "inputSchema": {
    "type": "object",
    "properties": {
      "tabId": {"type": "string", "description": "SSH tab ID (default: active tab)"},
      "remotePath": {"type": "string", "description": "Remote file or directory path to download"},
      "localPath": {"type": "string", "description": "Local destination path"},
      "conflictPolicy": {"type": "string", "enum": ["overwrite", "rename"], "description": "Conflict policy: overwrite or rename (default: overwrite)"}
    },
    "required": ["remotePath", "localPath"]
  }
}

electerm_zmodem_upload：通过 trzsz/rzsz 上传文件

{
  "name": "electerm_zmodem_upload",
  "description": "Upload local files to the remote SSH server using trzsz (trz) or rzsz (rz). The SSH tab must have the chosen protocol installed.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "tabId": {"type": "string", "description": "SSH tab ID (default: active tab)"},
      "files": {"type": "array", "items": {"type": "string"}, "description": "List of local file paths to upload"},
      "protocol": {"type": "string", "enum": ["trzsz", "rzsz"], "description": "Transfer protocol: trzsz (trz) or rzsz (rz) (default: rzsz)"}
    },
    "required": ["files"]
  }
}

electerm_zmodem_download：通过 trzsz/rzsz 下载文件

{
  "name": "electerm_zmodem_download",
  "description": "Download remote files from the SSH server using trzsz (tsz) or rzsz (sz). The SSH tab must have the chosen protocol installed.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "tabId": {"type": "string", "description": "SSH tab ID (default: active tab)"},
      "remoteFiles": {"type": "array", "items": {"type": "string"}, "description": "List of remote file paths to download"},
      "saveFolder": {"type": "string", "description": "Local folder path to save downloaded files"},
      "protocol": {"type": "string", "enum": ["trzsz", "rzsz"], "description": "Transfer protocol: trzsz (tsz) or rzsz (sz) (default: rzsz)"}
    },
    "required": ["remoteFiles", "saveFolder"]
  }
}

设置（如果启用）

get_electerm_settings：获取应用程序设置

{
  "name": "get_electerm_settings",
  "description": "Get current electerm application settings",
  "inputSchema": {"type": "object", "properties": {}}
}

完整示例

以下是一个完整的示例，展示如何初始化会话并执行操作：

const axios = require('axios');

async function example() {
  const serverUrl = 'http://127.0.0.1:30837/mcp';

  try {
    // 1. 初始化会话
    const initResponse = await axios.post(serverUrl, {
      jsonrpc: '2.0',
      id: 1,
      method: 'initialize',
      params: {
        protocolVersion: '2024-11-05',
        capabilities: {},
        clientInfo: { name: 'example-client', version: '1.0.0' }
      }
    }, {
      headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json, text/event-stream'
      }
    });

    const sessionId = initResponse.headers['mcp-session-id'];
    console.log('Session ID:', sessionId);

    // 2. 列出可用工具
    const toolsResponse = await axios.post(serverUrl, {
      jsonrpc: '2.0',
      id: 2,
      method: 'tools/list',
      params: {}
    }, {
      headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json, text/event-stream',
        'mcp-session-id': sessionId
      }
    });

    // 解析 SSE 响应
    const toolsData = JSON.parse(toolsResponse.data.split('\n')
      .find(line => line.startsWith('data: '))
      .substring(6));

    console.log('Available tools:', toolsData.result.tools.map(t => t.name));

    // 3. 打开本地终端
    const terminalResponse = await axios.post(serverUrl, {
      jsonrpc: '2.0',
      id: 3,
      method: 'tools/call',
      params: {
        name: 'open_electerm_local_terminal',
        arguments: {}
      }
    }, {
      headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json, text/event-stream',
        'mcp-session-id': sessionId
      }
    });

    // 4. 发送命令
    const commandResponse = await axios.post(serverUrl, {
      jsonrpc: '2.0',
      id: 4,
      method: 'tools/call',
      params: {
        name: 'send_electerm_terminal_command',
        arguments: { command: 'echo "Hello from MCP!"' }
      }
    }, {
      headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json, text/event-stream',
        'mcp-session-id': sessionId
      }
    });

    // 5. 获取终端输出
    const outputResponse = await axios.post(serverUrl, {
      jsonrpc: '2.0',
      id: 5,
      method: 'tools/call',
      params: {
        name: 'get_electerm_terminal_output',
        arguments: { lines: 10 }
      }
    }, {
      headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json, text/event-stream',
        'mcp-session-id': sessionId
      }
    });

  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

example();

错误处理

MCP 服务器提供详细的错误响应：

{
  "jsonrpc": "2.0",
  "id": 123,
  "error": {
    "code": -32603,
    "message": "Internal server error",
    "data": "Additional error details"
  }
}

常见错误代码：

-32603：内部服务器错误（例如，没有活动窗口）
-32602：无效参数
-32601：方法未找到

CORS 配置

服务器配置了宽松的 CORS 头部：

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, mcp-session-id

安全注意事项

服务器默认在本地运行
已启用 CORS 以允许跨域访问
未实现身份验证 - 使用时请自行承担风险
如果暴露到网络，请考虑防火墙规则
会话 ID 由服务器端为每个新会话生成
请求默认在 30 秒后超时

测试

该组件包含全面的测试，用于验证：

服务器可访问性和 CORS 配置
MCP 协议初始化
工具列出和调用
会话管理
SFTP 操作（列表、stat、读取、删除）
文件传输操作（上传、下载）
Zmodem 操作（trzsz/rzsz 上传/下载）
各种场景下的错误处理