MCP Terminal Server (Cwmoore AI)

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：日志级别（调试、信息、警告、错误、严重）
• -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：执行命令

- 需要API密钥 X-API-Key 头球 - 请求正文： {"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事件查看器是否存在与服务相关的错误

许可证

麻省理工学院