HostGate MCP

MCP 클라이언트를 위한 Windows 우선 로컬 기능 제어 평면(control plane)입니다.

HostGate MCP는 MCP 클라이언트가 선택된 로컬 파일과 신뢰할 수 있는 명령줄 프로그램에 명시적으로 승인된 액세스를 제공하며, 정책, 감사, 롤백, 진단 및 서비스 수명 주기 관리를 위한 데스크톱 제어 센터(Control Center)를 포함합니다.

실행 모델은 의도적으로 범용 터미널보다 좁게 설계되었습니다. 최상위 cmd.exe, Windows PowerShell 및 pwsh는 신뢰할 수 있는 실행 도구로 노출되지 않습니다. 허용된 실행 파일은 고정 경로로 확인된 후 직접 실행됩니다.

HostGate가 존재하는 이유

MCP를 통한 로컬 파일 읽기는 간단합니다. 원격 AI 클라이언트에 쓰기 및 프로세스 실행 기능을 안전하게 노출하는 것은 더 어렵습니다.

HostGate는 해당 제어 평면에 집중합니다:

• 명시적 읽기 / 쓰기 / 거부 루트;

• diff 검토 및 롤백이 포함된 트랜잭션 방식의 정책 편집;

• MCP 서비스를 재시작하지 않는 권한 핫 리로드;

• 정확한 경로 확인이 포함된 신뢰할 수 있는 실행 파일 허용 목록;

• 범용 셸 없이 감사되는 직접 프로세스 실행;

• Windows Job Object 프로세스 트리 격리;

• 로컬 감사 기록, 구성 개정, 정책 시뮬레이션 및 진단;

• 이중 언어 Windows 제어 센터(zh-CN / en-US);

• 예약 작업(Scheduled Task) 수명 주기 관리;

• 로컬 stdio 및 OAuth 보호 Streamable HTTP 모드;

• PyInstaller onedir 및 휴대용 onefile 제어 센터 빌드.

Related MCP server: MCP Local Filesystem Server

보안 모델

MCP client
    |
    | OAuth / stdio
    v
HostGate MCP
    |
    +-- Filesystem policy
    |     read roots
    |     write roots
    |     deny paths
    |
    +-- Direct execution policy
    |     trusted executable allowlist
    |     exact path resolution
    |     no general-purpose shell
    |     stdin disabled / bounded output
    |     Windows Job Object lifetime
    |
    +-- Control plane
          GUI / audit / revisions
          diagnostics / rollback

중요한 경계

HostGate MCP는 운영 체제 파일시스템 샌드박스가 아닙니다.

파일시스템 정책은 HostGate 자체 파일 도구와 exec_command가 허용하는 작업 디렉터리를 제어합니다. 승인된 실행 파일이 시작되면 해당 프로그램과 그 하위 프로세스는 MCP 서비스 계정의 OS 권한으로 실행되며, 해당 계정이 액세스할 수 있는 리소스에 액세스할 수 있습니다.

실행 파일 허용 목록은 최상위 프로세스를 제한합니다. 승인된 프로그램이 생성한 하위 프로세스를 샌드박싱하지 않습니다.

서비스를 localhost 이상으로 노출하기 전에 SECURITY.md 및 docs/THREAT_MODEL.md를 읽으십시오.

제어 센터

Windows 제어 센터는 6개 페이지를 제공합니다:

• 서비스(Service) — 상태, PID, 예약 작업 시작/중지/재시작.

• 권한(Permissions) — 읽기/쓰기/거부 루트 탐색 및 관리.

• 실행(Execution) — 신뢰할 수 있는 CLI 프로그램 관리.

• 정책(Policy) — 유효 권한 시뮬레이션 및 구성 개정 복원.

• 진단(Diagnostics) — 서비스/구성/감사/개정 상태 검증 및 편집된 보고서 내보내기.

• 감사(Audit) — 최근 파일 변경 및 프로세스 실행 이벤트 검토.

정책 변경은 TOML을 직접 편집하는 대신 트랜잭션 흐름을 사용합니다:

candidate
  -> validate
  -> review diff
  -> stale SHA256 check
  -> save previous revision
  -> atomic replace
  -> hot reload or controlled restart
  -> health check / rollback

안전한 공개 기본값

저장소는 기본적으로 실패 시 잠금(fail-closed) 상태로 시작합니다:

• 읽기 루트 없음;

• 쓰기 루트 없음;

• 사용자 정의 거부 경로 없음(제어 평면 경로는 자동으로 거부됨);

• 처음에는 Windows where.exe 유틸리티만 신뢰됨;

• OAuth URL은 127.0.0.1:8000을 가리킴;

• 실제 비밀번호 해시, 토큰 데이터베이스, 감사 데이터 또는 사용자 정책은 포함되지 않음.

제어 센터에서 실제로 필요한 디렉터리와 실행 파일만 승인하십시오.

설치

요구 사항:

• Windows 10/11;

• Python 3.10+;

• uv 권장.

핵심 서버 + GUI 설치:

cd C:\path\to\hostgate-mcp
uv sync --no-dev
Copy-Item config\secrets.example.toml config\secrets.toml

기본 설치에는 파일시스템/텍스트/CSV/변경/실행 도구, OAuth HTTP 지원 및 제어 센터가 포함됩니다. 형식별 리더는 선택 사항입니다:

uv sync --extra excel      # Excel tools
uv sync --extra pdf        # PDF tools
uv sync --extra image      # image tools
uv sync --extra pytorch    # PyTorch checkpoint tools
uv sync --extra all        # all optional tool families

개발 및 전체 테스트 스위트용:

uv sync --all-extras
.venv\Scripts\python.exe -m pytest -q

config\secrets.toml에 실제 Argon2id 소유자 비밀번호 해시를 설정한 다음, HTTP 서비스를 노출하기 전에 루트와 신뢰할 수 있는 실행 파일을 구성하십시오.

제어 센터 실행:

scripts\start_control_center.ps1

로그온 시 HostGate를 실행할 준비가 되면 Windows 예약 작업을 설치하십시오:

scripts\install_server_task.ps1

Windows 제어 센터 빌드

권장 onedir 빌드:

scripts\build_control_center.ps1

휴대용 onefile 빌드:

scripts\build_control_center.ps1 -OneFile

빌드 산출물은 의도적으로 소스 제어에서 제외됩니다.

선택적 도구 패밀리

모든 선택적 확장이 설치되면 HostGate는 비공개 1.4 라인을 위해 개발된 전체 리더 세트(Excel, PDF, 이미지 및 PyTorch 검사 도구 포함)를 노출합니다. 확장이 없으면 해당 도구 패밀리는 단순히 등록되지 않으며, 나머지 MCP 서버는 계속 사용할 수 있습니다.

이를 통해 기본 설치가 모든 사용자에게 PyTorch와 같은 대규모 과학 의존성을 설치하도록 강요하는 대신 RWX/제어 평면 사용 사례에 집중할 수 있습니다.

프로젝트 상태

현재 공개 준비 버전: 1.4.0rc1.

공개 저장소는 테스트된 비공개 개발 라인의 깨끗하고 기록이 없는 내보내기에서 생성되었습니다. 비공개 Git 기록, 프로덕션 정책, OAuth 상태, 로그, 비밀 및 빌드 출력은 의도적으로 제외됩니다.

비목표(Non-goals)

HostGate는 다음이 되려고 하지 않습니다:

• 완전한 터미널 에뮬레이터;

• 셸 오케스트레이션 프레임워크;

• MCP 마켓플레이스 또는 라우터;

• 크로스 플랫폼 코딩 에이전트 대체품;

• 완전한 OS 샌드박스.

새 기능은 입증된 운영 또는 보안 문제를 해결할 때만 추가되어야 합니다.

문서

• SECURITY.md — 보안 경계 및 취약점 보고.

• docs/THREAT_MODEL.md — 가정, 보호 자산 및 범위 외 보증.

• docs/control_center.md — 제어 센터 아키텍처 및 정책 트랜잭션.

• docs/architecture.md — 서버 아키텍처.

• docs/tools.md — MCP 도구 참조.

• CHANGELOG.md — 릴리스 기록.

라이선스

Apache License 2.0에 따라 라이선스가 부여됩니다. 귀속 정보는 NOTICE를 참조하십시오.