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，可管理代理、规则和审计日志。

架构

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 不可用时会降级并记录告警，而不会让安全测试任务停摆。

目录与职责

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、成功/失败次数、连续失败次数、最后检查时间和隔离截止时间。成功率和分数由持久化计数实时计算，避免冗余字段不一致。

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

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

本地启动（Python 3.12）

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+）：

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。

添加一个已授权节点：

$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 部署

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 应在任务开始时调用：

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

响应示例：

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

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

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 的绝对路径：

{
  "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，例如：

{"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 轮换和日志集中化。

验证

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

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