MCP 终端服务器

一个轻量级的 FastAPI 服务器，可以作为 Windows 服务运行，并提供一个执行 shell 命令并实时流式传输其输出的端点。

功能

• 可以作为 Windows 服务运行或在调试模式下运行
• 执行 shell 命令并实时流式传输其输出
• API 密钥认证
• 速率限制
• 通过环境变量或配置文件进行配置
• 强大的错误处理和日志记录
• 在失败时自动重启进程

安装

先决条件

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

安装步骤

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

powershell
.install_service.ps1

这将：

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

安装选项

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

powershell
.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 并进行修改：

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: 服务器的工作目录

服务管理

服务命令

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

powershell

安装服务

python service.py install

启动服务

python service.py start

停止服务

python service.py stop

重启服务

python service.py restart

删除服务

python service.py remove

更新服务配置

python service.py update

以调试模式运行（不作为服务）

python service.py debug

日志

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

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

API 使用

测试客户端

提供了一个强大的测试客户端，用于与服务器交互，具有以下功能：

• 命令行参数以提高可用性
• 支持 API 密钥认证
• 彩色输出以提高可读性
• 支持将输出保存到文件
• 强大的错误处理和日志记录
• 交互模式，支持命令历史
• 服务器健康检查功能

基本用法

powershell

运行命令

python test_client.py -c "dir" -k "your-api-key"

检查服务器健康状况

python test_client.py --health

交互模式

python test_client.py -k "your-api-key"

将输出保存到文件

python test_client.py -c "systeminfo" --save-output output.txt

指定服务器 URL

python test_client.py -s "http://example.com:8000" -c "dir"

启用详细输出

python test_client.py -v -c "dir"

显示版本

python test_client.py --version#### 配置文件

测试客户端可以通过 JSON 配置文件进行配置。根据提供的示例创建一个 client_config.json 文件：

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

然后使用以下命令运行：

powershell
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