super-win-cli-mcp-server

🚀 超级Windows CLI MCP服务器

超级Windows CLI MCP服务器是Windows CLI MCP服务器的增强分支，可通过命令行界面（MCP）为Windows环境提供不受限制的系统访问权限。

🔍 项目基础

本项目基于 win-cli-mcp-server，由SimonB97开发。

⚠️ 重要安全警告 ⚠️

本服务器设计为在Windows上以系统级权限运行，这使其能够完全且不受限制地访问整个操作系统，包括所有文件、进程和配置设置。

• 请勿在未充分了解授予系统级访问权限的影响之前安装或运行此服务器。
• 仅在您能完全控制网络访问的高度可信环境中使用此服务器。
• 网络安全至关重要：由于应用程序级别的限制设计得较少，因此要高度依赖防火墙、网络分段和严格的访问控制列表（ACL）来保护运行此服务器的计算机。
• 仔细审查配置：密切关注 config.json 中的 allowedPaths、blockedCommands 和其他安全设置。配置错误很容易使您的系统暴露风险。

请谨慎使用此软件，并自行承担风险。维护者对因使用此软件而导致的滥用或安全漏洞不承担任何责任。

✨ 主要特性

• 可完全访问Windows shell环境（PowerShell、CMD、Git Bash - 可配置）。
• 可不受限制地执行命令（可通过 config.json 配置）。
• 可完全访问文件系统（可通过 config.json 配置）。
• 可通过NSSM以系统级服务形式安装，实现持久化和自动恢复。
• NSSM提供自动服务恢复功能。
• 具备网络绑定控制（有此设计，但主要在网络/防火墙级别进行管理）。
• 禁用PowerShell遥测功能，增强隐私保护。
• 为提高性能，可重用进程（针对shell）。
• 为长时间运行的操作设置了可配置的延长超时时间。

📦 安装指南

前提条件

在开始之前，请确保已安装以下软件：

1. Node.js：版本18.0.0或更高。可从 nodejs.org 下载（包含npm）。
2. NSSM（Non-Sucking Service Manager）：可靠安装服务所必需。可从 nssm.cc 下载最新版本。

使用NSSM安装（推荐）

此方法会将服务器作为持久的Windows服务安装，该服务以系统权限运行并自动启动。

1. 克隆或下载项目：
   • 克隆此仓库：git clone <repository-url>
   • 或者下载源代码 .zip 文件，并将其解压到合适的位置（例如 C:\Servers\SuperWinCLIServer）。避免使用用户配置文件文件夹。
2. 放置NSSM：
   • 从 nssm.cc 下载NSSM。
   • 解压zip文件。
   • 将 nssm.exe 文件从相应的架构文件夹（win32 或 win64）复制到项目的根目录（与 install-service.ps1 所在的文件夹相同）。
3. 安装依赖并构建：
   • 在项目根目录中打开终端（PowerShell或CMD）。
   • 运行：npm install
   • 此命令将安装必要的Node.js包，并自动运行 npm run build，将TypeScript代码编译到 dist 文件夹中。
4. 配置 config.json：
   • 复制：在项目根目录中复制 config.sample.json 并将其命名为 config.json。
   • 编辑：打开 config.json 并仔细审查和修改设置：
     • security.allowedPaths：至关重要！ 将示例路径更改为服务器实际需要访问的目录。为确保安全，请尽可能具体。如果不确定，请从项目目录本身开始（例如 "C:\\Servers\\SuperWinCLIServer" - 请使用双反斜杠 \\）。由于服务以系统身份运行，因此路径必须对该账户有效。
     • security.blockedCommands / blockedArguments：审查默认列表。根据您的安全策略添加或删除命令/参数。
     • shells：启用/禁用shell（PowerShell、CMD、Git Bash），并验证 command 路径（特别是对于Git Bash）。
     • ssh：如果您打算使用SSH执行功能（默认禁用），请进行配置。
   • 保存 config.json 文件。
5. 运行安装脚本：
   • 以管理员身份打开 PowerShell。
   • 导航到项目根目录（cd C:\Servers\SuperWinCLIServer）。
   • 执行安装脚本：.\install-service.ps1
   • 此脚本使用NSSM安装并配置 MCPServer 服务，使其以 LocalSystem 身份运行 node.exe dist/index.js 并自动启动。
6. 验证服务状态：
   • 在同一个管理员PowerShell窗口中，运行：Get-Service MCPServer
   • 状态应为 Running。如果为 Stopped，请检查NSSM日志或Windows事件查看器（应用程序和系统日志）以查找错误。

📚 详细文档

配置文件 config.json 详情

security 部分

• maxCommandLength：命令字符串允许的最大字符数。
• blockedCommands：要阻止的命令名称数组（不包含扩展名，不区分大小写）。
• blockedArguments：要阻止的精确参数数组（不区分大小写）。
• allowedPaths：关键设置。绝对路径数组。如果 restrictWorkingDirectory 为 true，则仅当命令的工作目录以这些路径之一开头时，才能执行命令。路径在规范化后进行不区分大小写的比较。使用双反斜杠（例如 "C:\\Tools\\Scripts"）。
• restrictWorkingDirectory：布尔值。如果为 true，则对工作目录强制执行 allowedPaths 检查。强烈建议保持为 true。
• logCommands：布尔值。如果为 true，则将执行的命令及其输出（截断）存储在内存中（最多 maxHistorySize 条）。
• maxHistorySize：内存中保留的最大命令数。
• commandTimeout：运行中的命令自动终止前的秒数。
• enableInjectionProtection：布尔值。如果为 true，则尝试阻止命令中的shell运算符（&、|、; 等，按shell定义）。

shells 部分

用于配置可用的本地shell（powershell、cmd、gitbash）。

• enabled：布尔值。允许使用此shell。
• command：shell可执行文件的路径。
• args：在用户命令之前传递给shell的默认参数数组。
• blockedOperators：在 enableInjectionProtection 为 true 时，用于阻止此特定shell命令中的字符串/字符数组。

ssh 部分

用于配置通过SSH进行的远程命令执行。

• enabled：布尔值。启用 ssh_execute 和 ssh_disconnect 工具。
• connections：包含命名连接配置的对象（主机、端口、用户名、密码/私钥路径）。

配置合并规则

当加载 config.json 时，如果它包含 security 或 shells 部分，则该整个部分将替换该部分的默认配置，而不是合并 security 或 shells 中的各个字段。ssh 部分的合并更为细致。如果您自定义这些部分，请确保 config.json 包含这些部分的所有必要字段。

服务管理（NSSM）

通过 install-service.ps1 安装后，您可以使用标准的Windows工具或在项目目录中的管理员PowerShell/CMD中使用NSSM命令来管理服务：

• 启动：Start-Service MCPServer 或 .\nssm.exe start MCPServer
• 停止：Stop-Service MCPServer 或 .\nssm.exe stop MCPServer
• 重启：Restart-Service MCPServer 或 .\nssm.exe restart MCPServer
• 状态：Get-Service MCPServer 或 .\nssm.exe status MCPServer
• 编辑配置（高级）：.\nssm.exe edit MCPServer（打开NSSM GUI编辑器）
• 查看配置：.\nssm.exe dump MCPServer

卸载（NSSM）

1. 以管理员身份打开 PowerShell。
2. 导航到项目根目录。
3. 执行卸载脚本：.\uninstall-service.ps1
4. 此脚本将使用NSSM停止并删除 MCPServer 服务。

替代执行方式（手动/调试）

您可以直接运行服务器，而无需将其作为服务安装，用于测试或调试目的：

1. 确保已运行 npm install。
2. 确保 config.json 存在并已配置。
3. 在项目根目录中打开普通终端（PowerShell/CMD）。
4. 运行：npm run start
5. 服务器将在前台运行。按 Ctrl + C 停止它。

📄 许可证

本项目采用MIT许可证 - 有关详细信息，请参阅 LICENSE 文件。