内容
# 安全主机 MCP
<p align="center">
<a href="https://github.com/Razewang/secure-host-mcp/actions/workflows/ci.yml"><img src="https://github.com/Razewang/secure-host-mcp/actions/workflows/ci.yml/badge.svg" alt="持续集成"></a>
<a href="https://github.com/Razewang/secure-host-mcp/releases/latest"><img src="https://img.shields.io/github/v/release/Razewang/secure-host-mcp?label=发布版本" alt="最新发布"></a>
<a href="https://www.npmjs.com/package/secure-host-mcp"><img src="https://img.shields.io/npm/v/secure-host-mcp?logo=npm" alt="npm"></a>
<img src="https://img.shields.io/badge/Windows-x64-0078D4?logo=windows" alt="Windows x64">
<img src="https://img.shields.io/badge/Linux-x64-FCC624?logo=linux&logoColor=000000" alt="Linux x64">
<img src="https://img.shields.io/badge/Node.js-20%2B-339933?logo=nodedotjs&logoColor=white" alt="Node.js 20+">
<img src="https://img.shields.io/badge/MCP-Streamable%20HTTP-5A45FF" alt="MCP Streamable HTTP">
<a href="https://github.com/Razewang/secure-host-mcp/blob/main/LICENSE"><img src="https://img.shields.io/badge/许可证-MIT-blue" alt="MIT 许可证"></a>
</p>
<p align="center">
简体中文 | <a href="README.zh-CN.md">English</a>
</p>
安全主机 MCP 通过 Streamable HTTP 将 Windows 或 Linux 主机终端暴露给远程 MCP 客户端。它旨在功能强大：默认管理员令牌可以执行服务帐户可用的任何命令，检查或启动配置的隧道，并请求特权操作。
## 下载独立版本
从 [GitHub Releases](https://github.com/Razewang/secure-host-mcp/releases/latest) 下载您平台的存档：
- Windows x64：解压 ZIP 并双击 `secure-host-mcp.exe`。首次启动时，控制台向导会询问公网 IP 和 Cloudflare Tunnel 访问，配置管理员令牌，显示连接 URL，并启动两个服务器。
- Linux x64：解压 `tar.gz` 存档并运行 `./secure-host-mcp launch` 以获得相同的首次运行初始化和启动行为。
这些存档不需要单独的 Node.js 安装。Windows 可执行文件尚未签名，因此 Microsoft Defender SmartScreen 可能会显示未知发布者警告。在运行之前，请使用 `SHA256SUMS.txt` 验证下载内容。
```powershell
# Windows PowerShell
(Get-FileHash .\secure-host-mcp-0.1.0-windows-x64.zip -Algorithm SHA256).Hash
```
```bash
# Linux
sha256sum -c SHA256SUMS.txt --ignore-missing
```
## 安装和首次设置
通过 npm 安装时，需要 Node.js 20 或更高版本：
```powershell
npm install -g secure-host-mcp
secure-host-mcp setup --public-url https://mcp.example.com
secure-host-mcp doctor
secure-host-mcp start
```
在新安装的交互式终端中运行 `setup`：
1. 询问设备是否具有直接可达的公网 IP，并通过 Cloudflare 的跟踪端点进行检测（如果可能）。
2. 检查 `cloudflared` 并提供安装经过校验的官方二进制文件（如果丢失）。安装二进制文件不会创建 Cloudflare 账户或隧道配置。
3. 允许您自动生成初始令牌或输入您选择的非空令牌。没有固定的令牌格式；接受字母、数字和组合。
4. 解释相同的初始令牌既是 Web 控制台管理员令牌，也是全访问 MCP Bearer 令牌。
5. 打印具体的公网 IP MCP 和 Web 控制台 URL（如果有可用的公网 IP），以及纯文本 HTTP 警告。
非交互式设置保持自动化兼容性：它在不提示的情况下生成令牌，并且不自动安装 Cloudflare。新安装默认监听所有网络接口，以便远程客户端可以在主机防火墙、路由器和云安全规则允许的情况下连接。
端点默认为：
- MCP 和 OAuth：`http://0.0.0.0:8767/mcp`
- 管理：`http://0.0.0.0:8768/`
`0.0.0.0` 是绑定地址，而不是客户端 URL。请使用服务器的 IP 地址或 DNS 名称。两个服务都启动，即使未配置 HTTPS，但身份验证不加密 bearer 令牌、OAuth 代码或管理流量。ChatGPT 需要远程可达的 HTTPS MCP URL。在端口 8767 前面放置 Caddy、Nginx、Cloudflare Tunnel、frp 或另一个受信任的反向代理，并使用 HTTPS 或受信任的私有网络保护端口 8768 上的远程管理。一个最小的 Caddy 示例位于 `examples/` 下。
管理员 URL 在输入管理员令牌后提供响应式双语仪表板。它显示主机资源和运行时配置，创建和撤销范围连接令牌，并控制配置的 frpc/cloudflared 进程。仪表板创建的连接令牌写入 `setup` 和手动配置使用的相同 `tokens.json` 注册表。
例如，当 `setup` 检测到 `203.0.113.10` 时，它会打印：
```text
公网 MCP URL: http://203.0.113.10:8767/mcp
Web 控制台 URL: http://203.0.113.10:8768/
警告：HTTP 是纯文本...
```
## ChatGPT OAuth 连接
将 `https://mcp.example.com/mcp` 用作服务器 URL 并选择 OAuth。服务器发布其授权和受保护资源元数据。新客户端动态注册，ChatGPT 打开授权页面，主机管理员输入管理员令牌并批准请求的范围。服务器使用授权码 + PKCE 并颁发具有离线访问权限的轮换刷新令牌。
ChatGPT 中的完全可写入 MCP 支持取决于帐户/工作区计划和当前开发者模式可用性。
## 终端和作业
主要的 MCP 工具是 `execute_command`、`start_job`、`job_status`、`read_job_output` 和 `cancel_job`。Windows 使用 PowerShell 7（如果可用）否则使用 Windows PowerShell。Linux 使用 `/bin/bash` 除非配置不同。
命令未沙盒化或允许列表。 除非故意使用完全用户/根访问权限，否则请在专用帐户下运行服务。`execute_elevated` 在进程已经提升或安装了特权帮助程序之前会失败。`set_admin_mode` 记录请求；服务重新配置必须由已安装的服务适配器或本地 CLI 应用。
## cloudflared 和 frpc
```powershell
secure-host-mcp tunnel inspect
secure-host-mcp tunnel install-plan cloudflared
secure-host-mcp tunnel install-plan frpc
secure-host-mcp tunnel install cloudflared --yes
secure-host-mcp tunnel start cloudflared
```
检查器搜索 PATH 和标准 cloudflared 配置目录。 为 frpc 设置 `tunnels.frpcConfig`。 解析后的配置递归掩盖。 在启动前运行 `frpc verify -c`。 `tunnels.proxyUrl` 作为 `HTTP_PROXY`、`HTTPS_PROXY` 和 `ALL_PROXY` 传递，包括所选隧道客户端支持的 `socks5://` URL。
安装命令需要 `--yes`，仅下载匹配的官方 GitHub Release 资产，需要其发布的 SHA-256 摘要，验证它，并安装到应用程序数据目录中。 如果没有确认，它会失败关闭。
## 特权帮助程序
默认使用普通服务帐户执行。 要启用每个命令的提升，请从已经提升的终端单独启动帮助程序：
```powershell
# Windows：以管理员身份运行 PowerShell
secure-host-mcp helper
```
```bash
sudo secure-host-mcp helper
```
帮助程序仅监听 `127.0.0.1:8769`，使用来自受限机密文件的随机密钥进行身份验证，独立验证其是否已提升，并审计完整的命令输入/输出。 `set_admin_mode(enabled=true)` 请求帮助程序保持模式，停止普通实例，并启动新的 root/Administrator 实例。 返回到较低权限帐户需要本地恢复配置的 Windows 服务/systemd 帐户； 配置本身从不被视为提升的证明。
## 安全选择
- 配置的管理员令牌具有所有范围，并被 Web 控制台、OAuth 批准页面和直接 MCP Bearer 身份验证所接受。
- `~/.secure-host-mcp/tokens.json` 是管理员令牌和直接 MCP 连接令牌的唯一注册表。 OAuth 授权和帮助程序机密分别存储在 `secrets.json` 中。 两个文件都必须在 POSIX 上使用模式 `0600`。 备份并保护它们。
- 审计日志故意包含完整的命令和 stdout/stderr 文本。 它们按大小/天轮换，并在数据目录下保留 30 天。
- MCP 和管理默认监听所有接口。 每个管理 API 请求都需要管理员 bearer 令牌， 而变更还需要页面 CSRF 令牌。
- 公共 HTTP 没有加密：身份验证控制访问但无法防止 bearer 令牌、OAuth 代码或管理流量的拦截。 优先使用 HTTPS 或受信任的 VPN。
- 工具注释要求兼容的客户端确认破坏性操作。 主机无法证明客户端实际显示了人类确认。
## 配置
设置 `SECURE_HOST_MCP_HOME` 以更改数据目录。 将字段从 `config.example.json` 复制到生成的 `config.json` 中，然后重新启动。 配置和机密是原子写入的。
生成的 `tokens.json` 有意可编辑：
```json
{
"version": 1,
"adminToken": "my-admin-token",
"connectionTokens": [
{
"id": "second-agent",
"token": "agent-2-token",
"label": "第二个代理",
"scopes": ["system.read", "command.run"]
}
]
}
```
更改 `adminToken` 以轮换管理员令牌，或追加 `connectionTokens` 以创建更多直接 MCP Bearer 令牌。 `id` 对于手动添加的令牌是可选的； 当省略时，服务从令牌值中派生出稳定的标识符。 令牌值没有模式要求，但必须是非空和唯一的。 范围必须来自 `system.read`、`command.run`、`command.elevate`、`tunnel.read`、`tunnel.manage` 和 `admin.manage`。 在手动编辑后重新启动 Secure Host MCP。 有关完全访问示例，请参见 `tokens.example.json`。
对于仅限环回部署，显式将 `mcp.host` 和 `admin.host` 设置为 `127.0.0.1`。 新安装默认启用远程管理。
可以通过 `auth.externalIssuer` 和 `auth.externalAudience` 启用外部 OIDC。 令牌将针对发行者 JWKS 进行验证，并映射到相同的 MCP 范围。
## 开发
```powershell
npm install
npm run lint
npm run typecheck
npm test
npm run build
npm pack --dry-run
```
独立版本构建使用 `npm run package:standalone`。 跨平台工件应在发布 CI 中生成并校验和。
## 发布版本
在将产品更改合并到 `main` 时，使用诸如 `fix:`、`feat:` 和 `feat!: ` 之类的约定提交前缀。 Release Please 自动创建或更新包含下一个 `package.json`/lockfile 版本和 `CHANGELOG.md` 的 Release PR。 在项目低于 `1.0.0` 时，`fix:` 和 `feat:` 都会生成补丁版本； 破坏性更改保留其正常的 SemVer 含义。
合并 Release PR 会创建匹配的 `v<version>` 标签和 GitHub Release。 然后，发布工作流测试和打包两个平台，创建校验和，将 Windows/Linux 资产上传到该 Release，并将相同版本发布到 npm。 Release PR 永远不会自动合并，因此发布保留显式审查门槛。
显式匹配标签和有条件的门控手动工作流运行仍然可用于恢复和预发布版本。 预发布版本使用 npm 的 `next` 分发标签； 稳定版本使用 `latest`。
npm 作业使用 GitHub OIDC 和 Trusted Publishing，不需要存储库机密中的长期 npm 令牌。 手动工作流运行默认为仅验证， 除非显式启用，否则不会发布。
