슈퍼 윈도우 CLI MCP 서버

명령줄 인터페이스(MCP)를 통해 Windows 환경에 대한 제한 없는 시스템 액세스를 제공하는 Windows CLI MCP 서버의 향상된 포크입니다.

⚠️ 중요 보안 경고 ⚠️

이 서버는 Windows에서 SYSTEM 수준 권한 으로 실행되도록 설계되었습니다. 이를 통해 모든 파일, 프로세스 및 구성 설정을 포함하여 전체 운영 체제에 대한 완전하고 제한 없는 접근 권한이 부여됩니다.

SYSTEM 수준 액세스 권한 부여의 의미를 완전히 이해하지 못하면 이 서버를 설치하거나 실행 하지 마세요 .
네트워크 접근에 대한 완전한 제어권이 있는 매우 신뢰할 수 있는 환경 에서만 이 서버를 사용하세요.
네트워크 보안이 가장 중요합니다. 애플리케이션 수준의 제한은 설계상 최소화되어 있으므로 방화벽, 네트워크 분할, 엄격한 액세스 제어 목록(ACL)을 적극적으로 활용하여 이 서버를 실행하는 컴퓨터를 보호하세요.
구성을 주의 깊게 검토하세요. config.json 의 allowedPaths , blockedCommands 및 기타 보안 설정을 주의 깊게 살펴보세요. 잘못된 구성은 시스템을 쉽게 노출시킬 수 있습니다.

이 소프트웨어는 책임감 있게 사용하시고, 사용에 따른 모든 책임은 사용자에게 있습니다. 관리자는 소프트웨어 사용으로 인해 발생하는 오용이나 보안 침해에 대해 어떠한 책임도 지지 않습니다.

특징

Windows 셸 환경(PowerShell, CMD, Git Bash - 구성 가능)에 대한 완전한 액세스.
제한 없는 명령 실행( config.json 을 통해 구성 가능).
전체 파일 시스템 액세스( config.json 을 통해 구성 가능).
지속성 및 자동 복구를 위해 NSSM을 통한 SYSTEM 수준 서비스 설치.
NSSM이 제공하는 자동 서비스 복구 기능.
네트워크 바인딩 제어(네트워크/방화벽 수준에서 의도되었지만 주로 관리됨).
개인 정보 보호 강화를 위해 PowerShell 원격 측정 기능을 비활성화했습니다.
성능을 위한 프로세스 재사용(셸의 경우).
장기 실행 작업에 대한 시간 제한을 연장합니다(구성 가능).

필수 조건

시작하기 전에 다음 사항이 설치되어 있는지 확인하세요.

Node.js: 버전 18.0.0 이상. nodejs.org 에서 다운로드하세요. (npm 포함).
NSSM(Non-Sucking Service Manager): 안정적인 서비스 설치에 필요합니다. nssm.cc 에서 최신 버전을 다운로드하세요.

설치(NSSM 사용 - 권장)

이 방법을 사용하면 서버가 SYSTEM 권한으로 실행되고 자동으로 시작되는 영구 Windows 서비스로 설치됩니다.

복제 또는 다운로드:
- 이 저장소를 복제하세요: git clone <repository-url>
- 또는 소스 코드 .zip 파일을 다운로드하여 적절한 위치(예: C:\Servers\SuperWinCLIServer )에 압축을 풉니다. 사용자 프로필 폴더는 피하세요.
NSSM 위치:
- nssm.cc 에서 NSSM을 다운로드하세요.
- zip 파일을 추출합니다.
- 적절한 아키텍처 폴더( win32 또는 win64 )에서 nssm.exe 파일을 이 프로젝트의 루트 디렉토리 ( install-service.ps1 과 같은 폴더)로 복사합니다.
종속성 설치 및 빌드:
- 프로젝트의 루트 디렉토리에서 터미널(PowerShell 또는 CMD)을 엽니다.
- 실행: npm install
- 이 명령은 필요한 Node.js 패키지를 설치하고 npm run build 자동으로 실행하여 TypeScript 코드를 dist 폴더로 컴파일합니다.
config.json 구성합니다:
- 복사: config.sample.json 의 복사본을 만들고 프로젝트의 루트 디렉토리에 config.json 이름을 지정합니다.
- 편집: config.json 열고 설정을 주의 깊게 검토하고 수정합니다 .
  - security.allowedPaths : 중요! 샘플 경로 대신 서버가 액세스해야 하는 실제 디렉터리로 변경하세요. 보안을 위해 최대한 구체적으로 작성하세요. 확실하지 않으면 프로젝트 디렉터리부터 시작하세요(예: "C:\\Servers\\SuperWinCLIServer" - 백슬래시 두 개 \\ 를 기억하세요). 서비스는 SYSTEM 계정으로 실행되므로 해당 계정의 경로는 유효해야 합니다.
  - security.blockedCommands / blockedArguments : 기본 목록을 검토합니다. 보안 정책에 따라 명령/인수를 추가하거나 제거합니다.
  - shells : shells(PowerShell, CMD, Git Bash)를 활성화/비활성화하고 command 경로를 확인합니다(특히 Git Bash의 경우).
  - ssh : SSH 실행 기능을 사용할지 여부를 구성합니다(기본적으로 비활성화됨).
- config.json 파일을 저장합니다 .
설치 스크립트 실행:
- 관리자 권한으로 PowerShell을 엽니다.
- 프로젝트의 루트 디렉토리로 이동합니다( cd C:\Servers\SuperWinCLIServer ).
- 설치 스크립트를 실행합니다: .\install-service.ps1
- 이 스크립트는 NSSM을 사용하여 MCPServer 서비스를 설치하고 구성하여 LocalSystem 으로 node.exe dist/index.js 실행하고 자동으로 시작합니다.
서비스 상태 확인:
- 동일한 관리 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이면 명령에서 셸 연산자(셸별로 정의된 & , | , ; 등)를 차단하려고 시도합니다.
shells : 사용 가능한 로컬 셸(powershell, cmd, gitbash)을 구성합니다.
- enabled : 부울 값. 이 셸 사용을 허용합니다.
- command : 셸 실행 파일의 경로.
- args : 사용자 명령 전에 셸에 전달되는 기본 인수 배열입니다.
- blockedOperators : 이 특정 셸의 명령 내에서 차단할 문자열/문자 배열( enableInjectionProtection 이 true인 경우 사용됨).
ssh : SSH를 통해 원격 명령 실행을 구성합니다.
- enabled : 부울 값. ssh_execute 및 ssh_disconnect 도구를 활성화합니다.
- connections : 명명된 연결 구성(호스트, 포트, 사용자 이름, 비밀번호/privateKeyPath)을 포함하는 개체입니다.
구성 병합: config.json 파일이 로드될 때 security 또는 shells 섹션이 포함된 경우, 해당 섹션 전체가 해당 섹션의 기본 구성을 대체합니다 . security 또는 shells 섹션 내의 개별 필드는 병합되지 않습니다 . ssh 섹션은 더 세부적으로 병합됩니다. 이러한 섹션을 사용자 정의하는 경우 config.json 파일에 해당 섹션에 필요한 모든 필드가 포함되어 있는지 확인하십시오.

서비스 관리(NSSM)

install-service.ps1 통해 설치한 후에는 프로젝트 디렉토리의 관리 PowerShell/CMD 에서 표준 Windows 도구나 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)

관리자 권한으로 PowerShell을 엽니다.
프로젝트의 루트 디렉토리로 이동합니다.
설치 제거 스크립트를 실행합니다: .\uninstall-service.ps1
NSSM을 사용하여 MCPServer 서비스를 중지하고 제거합니다.

대체 실행(수동/디버그)

테스트나 디버깅 목적으로 서비스로 설치하지 않고도 서버를 직접 실행할 수 있습니다.

npm install 실행했는지 확인하세요.
config.json 존재하고 구성되어 있는지 확인하세요.
프로젝트 루트에서 일반 터미널(PowerShell/CMD)을 엽니다.
실행: npm run start
서버가 포그라운드에서 실행됩니다. 중지하려면 Ctrl + C 누르세요.

특허

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.