内容
# HTB 应用 MCP 服务器
适用于 **Hack The Box 应用** 服务的本地 MCP 服务器，通过 HTB API（主要是 v4 版本，在 v5 版本上进行机器旗帜提交）访问：
```text
https://labs.hackthebox.com/api/v4
```
本项目 **不使用** `pyhackthebox`：客户端直接通过 `httpx` 与 HTB 进行通信，并使用以下方式进行身份验证：
```http
Authorization: Bearer <HTB 应用令牌>
```
请勿将此服务器与官方 HTB CTF MCP 在 `mcp.hackthebox.ai/v1/ctf/mcp/` 混淆。此服务器仅用于 HTB 应用/实验室内容：机器、挑战、Sherlocks、堡垒、起点、季节性和专业实验室。
## 当前状态
- 推荐传输方式：**本地 Streamable HTTP MCP**，地址为 `http://127.0.0.1:8000/mcp`。
- HTTP 默认情况下是 **无状态的**：重启服务器时，您的 MCP 客户端不会卡在 `会话未找到`。
- 推荐身份验证方式：MCP 头部 `Authorization: Bearer <HTB 应用令牌>`，无需 `.env` 文件。
- 备用方式：stdio + `.env` 文件/环境变量。
- 已暴露工具：**56**。
## 安装配置
前提条件：
- Python 3.11+
- `uv`
- 来自 `app.hackthebox.com` 的 HTB 应用令牌
安装依赖项：
```bash
uv sync
```
## 推荐模式：带有授权头部的 HTTP
启动服务器：
```bash
uv run htb-app-mcp --transport http --host 127.0.0.1 --port 8000
```
配置您的 MCP 客户端：
```json
{
"mcpServers": {
"htb-app-mcp": {
"url": "http://127.0.0.1:8000/mcp",
"type": "http",
"headers": {
"Authorization": "Bearer <HTB 应用令牌>"
}
}
}
}
```
在此模式下，令牌来自 MCP 客户端，仅转发给 HTB。无需 `.env` 文件。
### 重启服务器
HTTP 默认情况下是无状态的，避免了 `会话未找到` 问题。您可以重启：
```bash
uv run htb-app-mcp --transport http --host 127.0.0.1 --port 8000
```
MCP 客户端可以重新连接，无需启动新的聊天。如果客户端仍使用旧连接，请在客户端重新加载 MCP 服务器。
对于协议调试，您可以强制启用有状态模式：
```bash
uv run htb-app-mcp --transport http --stateful-http
```
## 替代模式：stdio
stdio 在 MCP 主机直接启动本地进程时很有用。
配置：
```json
{
"mcpServers": {
"htb-app-mcp": {
"command": "uv",
"args": ["--directory", "D:\\Sources\\htb-app-mcp", "run", "htb-app-mcp"],
"env": {
"HTB_API_TOKEN": "<HTB 应用令牌>"
}
}
}
}
```
您也可以使用 `.env` 文件作为本地备用：
```bash
cp .env.example .env
# 编辑 .env 文件并设置 HTB_API_TOKEN（或 API_TOKEN）
uv run htb-app-mcp
```
`.env` 文件已被 gitignore。
## 工具
| 领域 | 工具 |
|---|---|
| 账户 | `htb_whoami`, `htb_user_profile` |
| VPN | `htb_connection_status`, `htb_vpn_servers`, `htb_switch_vpn_server`, `htb_download_ovpn` |
| 搜索 | `htb_search`, `htb_api_get`, `htb_api_post` |
| 机器 | `htb_list_machines`, `htb_machine_info`, `htb_active_machine`, `htb_recommended_machines`, `htb_machine_tasks` |
| 机器操作 | `htb_spawn_machine`, `htb_stop_machine`, `htb_extend_machine`, `htb_reset_machine`, `htb_submit_machine_flag` |
| 挑战 | `htb_list_challenges`, `htb_challenge_info`, `htb_challenge_categories`, `htb_download_challenge` |
| 挑战操作 | `htb_start_challenge`, `htb_stop_challenge`, `htb_start_container`, `htb_stop_container`, `htb_submit_challenge_flag` |
| Sherlocks | `htb_list_sherlocks`, `htb_sherlock_info`, `htb_sherlock_tasks`, `htb_sherlock_progress`, `htb_sherlock_play`, `htb_download_sherlock`, `htb_submit_sherlock_task_flag` |
| 堡垒 | `htb_list_fortresses`, `htb_fortress_info`, `htb_fortress_flags`, `htb_submit_fortress_flag`, `htb_reset_fortress` |
| 季节性 | `htb_list_seasons`, `htb_active_season_machine`, `htb_season_machines`, `htb_season_rewards`, `htb_season_user_rank`, `htb_season_user_ranks`, `htb_season_leaderboard`, `htb_season_top_leaderboard` |
| 起点 | `htb_starting_point_progress`, `htb_starting_point_tier`, `htb_submit_machine_task` |
| 专业实验室 | `htb_list_prolabs`, `htb_prolab_overview`, `htb_prolab_machines`, `htb_prolab_flags`, `htb_submit_prolab_flag` |
资源：
```text
htb://service-map
```
提示：
```text
htb_target_workflow
```
## 涵盖的 HTB 端点
服务器使用 `labs.hackthebox.com/api/v4`（在 `api/v5` 上进行机器旗帜提交）上的已验证真实端点，包括：
```text
GET /user/info
GET /connection/status
GET /user/connection/status
GET /connections/servers?product=...
POST /connections/servers/switch/{vpnId}
GET /access/ovpnfile/{vpnId}/0
GET /access/ovpnfile/{vpnId}/0/1
GET /search/fetch
GET /machine/paginated
GET /machine/profile/{machineSlug}
GET /machine/active
GET /machine/recommended
GET /machines/{machineId}/tasks
POST /vm/spawn
POST /vm/terminate
POST /vm/extend
POST /vm/reset
POST /vm/reset/vote
POST /vm/reset/vote/accept
POST /api/v5/machine/own
GET /challenges
GET /challenge/info/{challengeSlug}
GET /challenge/categories/list
GET /challenges/{challengeId}/download_link
POST /container/start
POST /container/stop
POST /challenge/own
GET /sherlocks
GET /sherlocks/{sherlockId}/info
GET /sherlocks/{sherlockId}/tasks
GET /sherlocks/{sherlockId}/progress
GET /sherlocks/{sherlockId}/play
GET /sherlocks/{sherlockId}/download_link
POST /sherlocks/{sherlockId}/tasks/{taskId}/flag
GET /fortresses
GET /fortress/{fortressId}
GET /fortress/{fortressId}/flags
POST /fortress/{fortressId}/flag
POST /fortress/{fortressId}/reset
GET /season/list
GET /season/machine/active
GET /season/machines/{seasonId}
GET /season/rewards/{seasonId}
GET /season/user/rank/{seasonId}
GET /season/user/{userId}/ranks
GET /season/{players|teams}/leaderboard
GET /season/{players|teams}/leaderboard/top/{seasonId}
GET /sp/tiers/progress
GET /prolabs
GET /prolab/{prolabId}/overview
GET /prolab/{prolabId}/machines
GET /prolab/{prolabId}/flags
POST /prolab/{prolabId}/flag
```
一些旧端点现在记录在线返回 404（例如 `/machine/list`、`/machines`、`/starting-point/machines`）。
## 下载
支持的下载：
- OVPN：`htb_download_ovpn`
- 挑战 ZIP：`htb_download_challenge`
- Sherlock ZIP：`htb_download_sherlock`
默认值：
- 目录：`downloads`
- ZIP 密码：`hackthebox`
- ZIP 提取：对挑战和 Sherlocks 启用
- ZIP 下载序列化，间隔最小以减少 `429 Too Many Requests`
更改目录：
```bash
export HTB_DOWNLOAD_DIR="D:/Sources/htb-app-mcp/downloads"
```
## 环境变量
| 变量 | 默认值 | 用途 |
|---|---|---:---|
| `HTB_API_TOKEN` | 空 | 用于 stdio 或 HTTP 备用令牌 |
| `API_TOKEN` | 空 | 兼容性支持的别名 |
| `HTB_TOKEN` | 空 | 支持的别名 |
| `HTB_API_BASE_URL` | `https://labs.hackthebox.com/api/v4` | 重写基本 API URL |
| `HTB_DOWNLOAD_DIR` | `downloads` | 下载目录 |
| `HTB_TIMEOUT` | `30` | HTB 的 HTTP 超时（秒） |
| `HTB_LOAD_DOTENV` | `1` | 设置为 `0` 以禁用 `.env` 加载 |
| `HTB_MCP_TRANSPORT` | `stdio` | `stdio`、`http`、`streamable-http` |
| `HTB_MCP_HOST` | `127.0.0.1` | HTTP 绑定地址 |
| `HTB_MCP_PORT` | `8000` | HTTP 端口 |
| `HTB_MCP_PATH` | `/mcp` | MCP HTTP 路径 |
| `HTB_MCP_STATELESS_HTTP` | `1` 在 HTTP 模式下 | 默认情况下 HTTP 无状态 |
| `HTB_MCP_JSON_RESPONSE` | `0` | 在支持的接口中返回 JSON 响应 |
| `HTB_MCP_LOG_LEVEL` | `INFO` | 服务器日志级别 |
| `HTB_MCP_VERBOSE_HTTP` | `0` | 设置为 `1` 以重新启用详细 HTTPX 日志记录 |
| `HTB_DOWNLOAD_MIN_INTERVAL` | `1.0` | ZIP 下载之间的最小秒数 |
| `HTB_MCP_GRACEFUL_SHUTDOWN_TIMEOUT` | `5` | 正常关闭超时（秒） |
| `HTB_MCP_WINDOWS_SELECTOR_EVENT_LOOP` | `1` | 在 Windows 上使用选择器事件循环 |
## 命令行界面
```bash
uv run htb-app-mcp --help
```
主要选项：
```text
--transport {stdio,http,streamable-http}
--host 127.0.0.1
--port 8000
--path /mcp
--stateless-http
--stateful-http
--json-response
--log-level INFO
--graceful-shutdown-timeout 5
```
## 本地验证
使用直接客户端进行烟雾测试：
```bash
uv run python tests/smoke_client.py
```
使用 MCP stdio 进行烟雾测试：
```bash
uv run python tests/smoke_mcp.py
```
使用 MCP HTTP 和授权头部进行烟雾测试：
```bash
uv run python tests/smoke_http.py
```
## 故障排除
### `会话未找到`
更新代码并在默认 HTTP 无状态模式下重启：
```bash
uv run htb-app-mcp --transport http --host 127.0.0.1 --port 8000
```
如果客户端仍然持有旧连接，请在客户端侧重新加载 MCP 服务器。
### `/mcp` 上的 `404 Not Found`
检查：
- 服务器是否使用 `--transport http` 启动
- MCP 配置是否指向 `http://127.0.0.1:8000/mcp`
- `HTB_MCP_PATH` 或 `--path` 是否设置为除 `/mcp` 之外的其他值
### Windows 上的 `ConnectionResetError [WinError 10054]`
HTTP 传输强制在 Windows 上使用选择器事件循环，以避免 MCP 客户端关闭已完成的 HTTP/SSE 连接时出现嘈杂的堆栈跟踪。
### 使用 Ctrl+C 退出时出现回溯或 `ASGI callable returned without completing response`
关闭处理是跨平台的：在 Linux/macOS 上，它使用标准 Uvicorn 信号处理；在 Windows 上，它仅启用选择器事件循环以避免特定于 Proactor 的噪音。在所有情况下，服务器都会过滤 Uvicorn/Starlette 关闭 HTTP MCP 流时产生的良性噪音。对于完整的调试日志，请设置 `HTB_MCP_VERBOSE_HTTP=1`。
### `422 Unprocessable Entity`
HTB 拒绝无效参数。服务器规范常见情况：
- `Easy` -> `easy`
- `Very Easy` -> `very-easy`
- `unsolved` -> `incompleted`
- `solved` -> `complete`
- `sort_by=difficulty` -> `user_difficulty` 用于挑战
- `target_type=challenge` -> `challenges` 用于搜索
如果 HTB 更改架构，请使用 `htb_api_get` 测试只读端点。
### 下载过程中的 `403 Forbidden`
这不一定是错误：HTB 可能会拒绝访问您的帐户计划、层级、状态或权限不可用的挑战或文件。
### `429 Too Many Requests`
您遇到了 HTB 速率限制。服务器序列化 ZIP 下载，但如果代理请求连续下载许多文件，请等待几分钟或增加：
```bash
export HTB_DOWNLOAD_MIN_INTERVAL=2.0
```
### 包含签名 URL 的日志
默认情况下，HTTPX 和 httpcore 日志被静音，以避免打印临时 S3 URL。对于调试：
```bash
export HTB_MCP_VERBOSE_HTTP=1
```
请勿分享详细日志：它们可能包含临时预签名 URL。
## 安全
- 将 HTTP 服务器保持在环回地址（`127.0.0.1`）。
- 不要提交 `.env` 或令牌。
- 不要在日志或 README 中粘贴令牌。
- 在本地调试时避免 `HTB_MCP_VERBOSE_HTTP=1`。
- `spawn`、`stop`、`reset`、`submit flag`、`switch VPN` 等工具有副作用影响您的 HTB 帐户。
## API 注释
HTB 应用 v4 API 不是官方稳定的外部集成接口。大多数公共引用是由社区维护或反向工程的；HTB 可能会在不通知的情况下更改路径、有效载荷或权限。
