# Proxy Pool MCP Server

面向**已授权**安全测试的出口代理调度服务。它不抓取、不分发公共代理；每个节点都必须由管理员显式登记，随后由服务按健康度和评分选择。服务同时提供：

- FastAPI HTTP API，供 Burp Extension 调用；
- stdio MCP Server，供 WordBuddy 等 MCP Client 调用；
- 30 秒后台 TCP + 代理 HTTP 健康检查；
- SQLite（本地）或 PostgreSQL（容器）持久化；
- Redis 用于短期的调用方分配记录缓存；Redis 故障不会停止代理调度；
- Token 鉴权、调用方标识、追加式审计记录和响应式 Web Dashboard；
- Windows 可视化管理台 EXE，可管理代理、规则和审计日志。

## 架构

```text
WordBuddy MCP Client --stdio MCP--> Proxy Pool MCP Server ---+--> PostgreSQL / SQLite
                                                              +--> Redis (optional)
Burp Extension -----HTTP + X-API-Token--> FastAPI -----------+
                                                              |
                                             Health scheduler -+--> Authorized proxy nodes
```

数据库是节点真实状态的唯一来源；Redis 不可用时会降级并记录告警，而不会让安全测试任务停摆。

## 目录与职责

```text
proxy-mcp-server/
├── main.py                     # HTTP 服务入口；--mcp 切换为 stdio MCP 入口
├── mcp_server/
│   ├── api.py                  # Burp / 管理后台使用的 HTTP API
│   ├── auth.py                 # API Token 与 MCP Tool Token 校验
│   ├── tools.py                # 五个 MCP Tools
│   ├── proxy_manager.py        # 节点状态机、评分、选择和审计
│   ├── health_checker.py       # TCP 和经代理 HTTP 探测
│   ├── scheduler.py            # 30 秒后台任务生命周期
│   ├── schemas.py              # HTTP 请求约束
│   └── settings.py             # YAML + 环境变量配置加载
├── database/
│   ├── models.py               # ProxyNode 与 append-only AuditLog
│   └── session.py              # SQLAlchemy 连接和会话
├── config/config.yaml          # 非机密默认配置
├── templates/dashboard.html    # 浏览器管理后台
├── desktop-console/            # Windows 桌面管理台（Electron）
│   ├── main.cjs                # 安全 IPC 与受限 HTTP API 调用
│   ├── preload.cjs             # 不暴露 Node 的最小化桥接层
│   ├── renderer/               # 代理、规则、日志的桌面界面
│   └── build.cmd               # Windows EXE 构建脚本
├── tests/test_proxy_manager.py # 调度关键行为测试
├── Dockerfile
├── docker-compose.yml
├── .env.example
└── requirements.txt
```

## 调度与状态规则

每个节点持久化 `host`、`port`、`protocol`、`status`、`latency`、成功/失败次数、连续失败次数、最后检查时间和隔离截止时间。成功率和分数由持久化计数实时计算，避免冗余字段不一致。

```text
score = 成功率(0..100) * 0.50
      + 响应速度分(0..100) * 0.30
      + 稳定性分(0..100) * 0.20
```

同一优先级下依次选分数最高、延迟最低、累计失败数最少的节点。首次登记为 `WARNING`；成功后变为 `ACTIVE`。连续失败达到 3 次时进入 `FAILED`，隔离 30 分钟；隔离到期后会重新被健康检查。管理员禁用后为 `DISABLED`，不会自动恢复。

## 本地启动（Python 3.12）

PowerShell：

```powershell
cd D:\GTP\proxy-mcp-server
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
Copy-Item .env.example .env
# 编辑 .env：至少替换两种 Token；本地 SQLite 可不设置 DATABASE_URL。
$env:PROXY_MCP_API_TOKENS = "your-long-api-token"
$env:PROXY_MCP_MCP_TOKENS = "your-different-mcp-token"
python main.py
```

打开 `http://127.0.0.1:8080/`，输入 API Token 管理节点。Dashboard 会可视化展示节点可用率、健康环、状态分布、健康评分、延迟、成功率与连续失败次数，并每 20 秒刷新一次。OpenAPI 文档在 `http://127.0.0.1:8080/docs`。生产环境请把 Token 放入 Secret 管理系统或容器环境变量，绝不要提交 `.env`。

## Windows 可视化管理台（EXE）

已生成的可直接运行的 64 位便携版：

`D:\GTP\proxy-mcp-server\desktop-console\dist\Proxy-Pool-Console-1.5.0-win-x64.exe`

它是一体化本机程序：启动后会自动运行仅监听 `127.0.0.1:8080` 的本机代理池 HTTP API、后台健康检查和桌面管理界面；无需安装 Python、运行脚本、填写服务地址或 API Token。

1. **代理节点**：添加 IP/域名、端口、协议；查看评分、延迟、成功率和失败次数；支持禁用或带审计原因的永久删除。
2. **调度规则**：添加最小评分、最大延迟、协议与优先级约束；支持启用/停用和带审计原因的删除。所有启用规则都会实际参与节点筛选。
3. **操作日志**：查看最近 200 条代理状态变化、规则变更、添加、禁用和删除的审计记录。

桌面程序将代理、规则和审计记录保存至当前 Windows 用户数据目录。它采用 Electron 的 `contextIsolation`、关闭 `nodeIntegration`，并在主进程中限制为本项目 API 白名单；本机 API 不对局域网开放。

从源码重新构建 EXE（需 Node.js 24+）：

```powershell
cd D:\GTP\proxy-mcp-server\desktop-console
.\build.cmd
```

构建结果在 `desktop-console\dist\Proxy-Pool-Console-<version>-win-x64.exe`。首次构建会下载 Electron 打包依赖；不要提交 `node_modules` 或 `dist`。详细的一体化使用步骤见 [desktop-console/使用说明.md](desktop-console/使用说明.md)。

添加一个已授权节点：

```powershell
$headers = @{ "X-API-Token" = "your-long-api-token"; "X-Caller" = "bootstrap-admin" }
Invoke-RestMethod -Method Post http://127.0.0.1:8080/api/proxies -Headers $headers -ContentType application/json -Body '{"host":"203.0.113.12","port":8080,"protocol":"http"}'
```

> `203.0.113.0/24` 是文档保留地址；替换为你已获授权的测试出口节点。

## Docker 部署

```powershell
cd D:\GTP\proxy-mcp-server
Copy-Item .env.example .env
# 在 .env 中设置：POSTGRES_PASSWORD、PROXY_MCP_API_TOKENS、PROXY_MCP_MCP_TOKENS
docker compose up --build -d
docker compose ps
```

Compose 包含 `proxy-mcp`、`redis`、`database`（PostgreSQL）三个服务。默认仅将 API 发布到宿主机 `8080`；请在防火墙/反向代理层限制调用来源，并使用 HTTPS 终止 TLS。数据库卷和 Redis 卷由 Docker 管理，停止容器不会删除数据。

## HTTP API（Burp 集成）

所有 `/api/*` 端点都需要 `X-API-Token: <API_TOKEN>`（或 `Authorization: Bearer <API_TOKEN>`）。可用 `X-Caller: burp-extension/<version>` 写入审计日志。Token 从不写入日志或响应。

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| `GET` | `/api/proxy/current` | 获取最佳可用节点 |
| `POST` | `/api/proxy/switch` | 排除当前节点，选择替代节点 |
| `POST` | `/api/proxy/status` | 上报成功、告警或失败 |
| `GET` | `/api/pool/status` | 返回总数、状态计数和平均延迟 |
| `GET/POST` | `/api/proxies` | 列出/新增授权节点 |
| `POST` | `/api/proxies/{id}/disable` | 人工禁用，并记入审计 |
| `DELETE` | `/api/proxies/{id}` | 带原因永久删除节点；审计记录保留 |
| `GET/POST/PATCH/DELETE` | `/api/rules` | 查询、新增、修改或删除调度规则 |
| `GET` | `/api/audit-logs` | 获取最近审计日志（最多 500 条） |

Burp Extension 应在任务开始时调用：

```http
GET /api/proxy/current HTTP/1.1
Host: proxy-pool.internal:8080
X-API-Token: <API_TOKEN>
X-Caller: burp-extension/1.0
```

响应示例：

```json
{"proxy":"http://203.0.113.12:8080","status":"ACTIVE","latency":120,"score":96.4}
```

扩展将 `proxy` 解析为 host、port、scheme 后更新 Burp 的项目级上游代理设置。遇到连接/超时失败时，先上报再请求切换：

```json
POST /api/proxy/status
{"proxy":"http://203.0.113.12:8080","status":"failed","reason":"connect_timeout"}

POST /api/proxy/switch
{"current_proxy":"http://203.0.113.12:8080"}
```

切换响应的 `new_proxy` 可直接写回扩展配置。不要让扩展从外部列表下载代理，也不要把测试目标、Cookie、请求正文或 API Token 发送给本服务。

## MCP 配置与 WordBuddy 示例

MCP 使用 stdio，因此应由 MCP Client 在与本服务数据库网络可达的主机上启动。将下面 JSON 合并到 WordBuddy 的 MCP Server 配置；Windows 使用 `python.exe` 的绝对路径：

```json
{
  "mcpServers": {
    "proxy-pool": {
      "command": "D:\\GTP\\proxy-mcp-server\\.venv\\Scripts\\python.exe",
      "args": ["D:\\GTP\\proxy-mcp-server\\main.py", "--mcp"],
      "env": {
        "PROXY_MCP_DATABASE_URL": "sqlite:///./data/proxy_pool.db",
        "PROXY_MCP_MCP_TOKENS": "${PROXY_POOL_MCP_TOKEN}"
      }
    }
  }
}
```

每次 MCP Tool 调用都显式传入 `access_token`（建议由 WordBuddy 的 Secret 变量注入）和 `caller`，例如：

```json
{"access_token":"${PROXY_POOL_MCP_TOKEN}","caller":"wordbuddy-prod","current_proxy":"http://203.0.113.12:8080"}
```

提供的 Tools：

| Tool | 必填入参（除 `access_token`） | 结果 |
| --- | --- | --- |
| `get_available_proxy` | — | 最佳可用代理与健康指标 |
| `report_proxy_status` | `proxy`, `status` | 记录任务侧状态并可能隔离 |
| `switch_proxy` | `current_proxy` | 返回替换节点与 `health_score` 原因 |
| `proxy_pool_status` | — | 代理池汇总 |
| `add_proxy` | `host`, `port`, `protocol` | 登记授权节点 |

推荐的 WordBuddy 编排是：`get_available_proxy` → Burp MCP 执行已授权任务 → 成功时 `report_proxy_status(success)`；异常时 `report_proxy_status(failed)` → `switch_proxy` → 继续可重试的任务。应用层应为非幂等测试请求设置自己的重试边界，代理服务不重放任何 Burp 请求。

## 审计与安全运维

- `audit_logs` 记录时间、调用方、节点、旧/新状态、原因与操作，不记录 Token。
- 对 Dashboard/API 使用独立 Token；对 MCP 使用另一套 Token，最小化泄露影响。
- 健康检查 URL 应指向组织控制的轻量端点；生产中替换 `https://example.com/`。
- 仅向经过授权的测试范围和出口节点发起流量。该服务不判断目标授权状态。
- 建议在部署前做数据库备份、配置 TLS、网络分段、Token 轮换和日志集中化。

## 验证

```powershell
cd D:\GTP\proxy-mcp-server
python -m compileall main.py mcp_server database
pytest -q
```

测试覆盖：高分节点优先、三次连续失败隔离、自动回退到备用节点。运行真实健康检查还需要存在且被授权的代理节点和可访问的 `health_check.target_url`。