MCP Terminal Server

MCP 终端服务

一个轻量级 FastAPI 服务，可作为 Windows 服务运行，并提供一个用于执行 shell 命令和流式传输命令输出的端点。

功能

• 作为 Windows 服务运行或在调试模式下运行
• 执行 shell 命令并实时流式传输命令输出
• API 密钥身份验证
• 速率限制
• 可通过环境变量或配置文件配置
• 完善的错误处理和日志记录
• 发生故障时自动重启进程

安装

先决条件

• Windows 操作系统
• Python 3.7 或更高版本
• 管理员权限（用于安装服务）

安装步骤

1. 克隆此仓库或下载源代码
2. 以管理员身份打开 PowerShell
3. 导航至项目目录
4. 运行安装脚本：

.\install_service.ps1

此脚本将：

• 安装所需的 Python 依赖项
• 生成随机 API 密钥（或使用你提供的密钥）
• 创建配置文件
• 安装并启动 Windows 服务

安装选项

你可以使用以下参数自定义安装：

.\install_service.ps1 -ApiKey "your-api-key" -Port 8080 -Host "127.0.0.1" -LogLevel "debug"

可用参数：

• -ApiKey：用于身份验证的自定义 API 密钥
• -Port：服务的端口号（默认值：8000）
• -Host：要绑定的主机地址（默认值：0.0.0.0）
• -LogLevel：日志级别（debug、info、warning、error、critical）
• -ConfigFile：自定义配置文件的路径

配置

服务可通过以下方式配置：

1. 环境变量
2. 配置文件（config.json）
3. 安装期间使用的命令行参数

配置文件

项目提供了一个示例配置文件（config.json.sample）。你可以将其复制为 config.json 并进行修改：

{
    "host": "0.0.0.0",
    "port": 8000,
    "log_level": "info",
    "log_file": "mcp_terminal_server.log",
    "max_log_size_mb": 10,
    "log_backup_count": 5,
    "restart_on_failure": true,
    "max_restart_attempts": 5,
    "restart_delay_seconds": 10,
    "shutdown_timeout_seconds": 30,
    "working_directory": null
}

环境变量

你也可以使用环境变量配置服务：

• MCP_TERMINAL_API_KEY：用于身份验证的 API 密钥
• MCP_HOST：要绑定的主机地址
• MCP_PORT：服务的端口号
• MCP_LOG_LEVEL：日志级别
• MCP_LOG_FILE：日志文件的路径
• MCP_MAX_LOG_SIZE_MB：日志文件的最大大小（MB）
• MCP_LOG_BACKUP_COUNT：要保留的日志备份文件数量
• MCP_RESTART_ON_FAILURE：是否在服务发生故障时重启
• MCP_MAX_RESTART_ATTEMPTS：最大重启尝试次数
• MCP_RESTART_DELAY_SECONDS：重启尝试之间的延迟时间
• MCP_SHUTDOWN_TIMEOUT_SECONDS：正常关闭的超时时间
• MCP_WORKING_DIRECTORY：服务的工作目录

服务管理

服务命令

可以使用以下命令管理服务：

# Install the service
python service.py install

# Start the service
python service.py start

# Stop the service
python service.py stop

# Restart the service
python service.py restart

# Remove the service
python service.py remove

# Update the service configuration
python service.py update

# Run in debug mode (not as a service)
python service.py debug

日志

日志存储在配置的日志文件中（默认值：mcp_terminal_server.log）。日志包括：

• 服务启动／停止事件
• 命令执行记录
• 错误和警告
• 健康检查结果

API 用法

测试客户端

项目提供了一个功能完善的测试客户端，可用于与服务交互，具备以下功能：

• 命令行参数，便于使用
• 支持 API 密钥身份验证
• 彩色输出，便于阅读
• 支持将输出保存到文件
• 完善的错误处理和日志记录
• 支持命令历史的交互模式
• 服务健康检查功能

基本用法

# Run a command
python test_client.py -c "dir" -k "your-api-key"

# Check server health
python test_client.py --health

# Interactive mode
python test_client.py -k "your-api-key"

# Save output to a file
python test_client.py -c "systeminfo" --save-output output.txt

# Specify server URL
python test_client.py -s "http://example.com:8000" -c "dir"

# Enable verbose output
python test_client.py -v -c "dir"

# Show version
python test_client.py --version

配置文件

测试客户端可使用 JSON 配置文件进行配置。请根据提供的示例创建 client_config.json 文件：

{
    "server_url": "http://localhost:8000",
    "api_key": "your-api-key-here",
    "timeout": 60,
    "verbose": false
}

然后使用以下命令：

python test_client.py --config client_config.json

环境变量

测试客户端也支持通过环境变量进行配置：

• MCP_TERMINAL_API_KEY：用于身份验证的 API 密钥
• MCP_TERMINAL_SERVER_URL：服务 URL

API 端点

• POST /run：执行命令

  • 需要在 X-API-Key 标头中提供 API 密钥
  • 请求正文：{"command": "your command"}
  • 返回包含命令输出的流式响应

• GET /health：检查服务健康状态

  • 返回 {"status": "healthy", "active_sessions": 0}

安全注意事项

• 在生产环境中务必更改默认 API 密钥
• 如果服务只应允许本地访问，请将主机限制为 127.0.0.1
• 考虑在生产环境中使用 HTTPS
• 服务会阻止可能存在危险的命令，但可能还需要采取其他安全措施

故障排除

• 检查日志文件中的错误
• 在调试模式下运行以查看控制台输出：python service.py debug
• 验证服务是否正在运行：Get-Service -Name "MCP_Terminal_Server"
• 在 Windows 事件查看器中检查与服务相关的错误

许可证

MIT