HostGate MCP

一个面向 Windows 优先的本地能力控制平面，用于 MCP 客户端。

HostGate MCP 让 MCP 客户端获得明确授权的访问权限，可访问选定的本地文件和受信任的命令行程序，并提供桌面控制中心，用于策略、审计、回滚、诊断和服务生命周期管理。

执行模型刻意比通用终端更窄：不将顶层 cmd.exe、Windows PowerShell 和 pwsh 暴露为受信任的执行工具。 允许的可执行文件会被解析为固定路径并直接启动。

HostGate 存在的原因

通过 MCP 读取本地文件很简单。但向远程 AI 客户端安全地暴露写入和进程执行能力则更难。

HostGate 专注于这一控制平面：

• 显式的读 / 写 / 拒绝根目录；

• 事务性策略编辑，支持差异审查和回滚；

• 权限热重载，无需重启 MCP 服务；

• 受信任可执行文件允许列表，支持精确路径解析；

• 有审计的直接进程执行，不经过通用 shell；

• 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 控制中心提供六个页面：

• 服务 — 状态、PID、Scheduled Task 启动/停止/重启。

• 权限 — 浏览和管理读/写/拒绝根目录。

• 执行 — 管理受信任的 CLI 程序。

• 策略 — 模拟有效权限并恢复配置修订。

• 诊断 — 验证服务/配置/审计/修订状态并导出脱敏报告。

• 审计 — 查看最近的文件变更和进程执行事件。

策略更改使用事务流程，而不是直接编辑 TOML：

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

安全的公共默认值

仓库初始状态为默认拒绝：

• 无读根目录；

• 无写根目录；

• 无用户定义的拒绝路径（控制平面路径自动被拒绝）；

• 最初仅信任 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 Scheduled Task：

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 服务器的其余部分仍然可用。

这使默认安装专注于 RWX/控制平面用例，而不是强制每个用户安装大型科学依赖项（如 PyTorch）。

项目状态

当前公共准备版本：1.4.0rc1。

公共仓库是从经过测试的私有开发线的干净、无历史导出中创建的。私有 Git 历史、生产策略、OAuth 状态、日志、机密和构建输出被有意排除。

非目标

HostGate 不打算成为：

• 完整的终端模拟器；

• shell 编排框架；

• 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。