FACEIT-MCP

FACEIT CS2 辅导 MCP 服务器 一个远程 **MCP 服务器**（Python + [FastMCP](https://github.com/jlowin/fastmcp)），读取玩家的公共 **FACEIT CS2** 数据，诊断优势和劣势，并生成个性化的、基于数据的改进路径。它部署到 **Render.com**，并在第一次尝试时作为aude 中的远程连接器**。 服务器是 **只读 — 它只读取公共 FACEIT 数据。MCP 端点故意没有身份验证墙参见 [稍后启用真正的 OAuth](#稍后启用真正的-oauth-高级-需要持久存储)）；您的 FACEIT API 密钥保留在服务器端，永远不会暴露给连接的客户端。 --- ## 它公开的内容 **工具** | 工具 | 功能 | | --- | --- | | `search_faceit_player(query)` | 解析昵称/个人资料网址/ `player_id`ID64 → 身 等级 + E昵称不明确返回 `候选人`。 | | `_overview(query)`资料 + 生命周期统计 + 活跃封禁。 | | `formance(query)` | 按地图划分的胜率 / K佳和最差地图（少于 10 场比赛的地图将被忽略）。 | | `get_recent_form(query, limit)` | 最近的比赛 + 每场比赛的统计数据，趋势，连续胜利，稳定性。 | | `benchmark_player(query)` |判**，适用于 K/D，K/R，HS胜率，与同地区的同行相比（例如“8 级的底部四分位数 ADR”）。实时同样，带有标记的静态基线备用。 | | `get_stats(query)` | **ify** 高级公开 — 开斗 %，交易 %伤害，预瞄，反应时间，瞄准/实用评级。如果玩家没有 Leetify 个人资料，则会干净地降级。需要署名。 | | `analyze_player | **头条工具 完整的诊断，结合 FACE统计数据 + 同行基准 + Leetify 信号：优势，劣势（带有严重性），地图/表格洞察，整体评估。在获取数据时报告 | | `get_improvement_plan(query, focus=None)` | → 优先排序的训练/资源，与玩家和百分比相关联focus` 可以是 `aim`，`opening`，`trading`，`utility`，`positioning`，`maps`，`teamplay`，`tilt`。 | set_my_profile(query)`whoami()` / `_profile()` | 轻量级每用户身份：说 `<nick>`”一次，后续工具默认使用你。尽力而为的内存存储；每个工具仍然接受显式 `。 | **提示** — `coach_me(query)`pre_match_prep(query, map=None)`，`post_loss_review(query)`，`weekly)`。 **资源**it://player/{query}/analysis` 公开最新的（从内存 TTL 缓存中提供，按需重新计算状态安全）。 ` 在每个工具中接受称**，**个人**（`faceit/players/<nick>`），原始 **`player_id`**（UUID），或 **SteamID64**。确切的昵称，备用 FACEIT 不明确的昵称最佳匹配，并返回替代方案，以便 Claude 可以确认。 ###功能的工作原理 -行基准测试（无数据库）。** 对于目标区域 + 技能等级，服务器从 FACEIT 排名中抽样约 40 名同行， 并并发获取他们的生命周期统计数据（限速），计算目标的每个指标的百分比。分布在内存中6 小时， 按 `(region, level)` 缓抽样受到速率薄，它会近似静态基 表（在 `benchmark` 中），并明确标记输出 `source: "baseline"`。 - **Leetify 桥接。** FACEIT 玩家的 `game_player_id是他们的 SteamID64**，而 Leetify 的公共端点（3/profile?steam64_id=`）由 Steam 键控。因此条是昵称 → FACEIT 玩家 → Steam64 → Leetify 个人资料。许多玩家ify 上；分析地降级为IT，并注明连接 Leet加深报告。 - **Leetify 署名（必需）。** 任何包含 导出数据的输出都"数据由 Leetify 提供"** 和 **在 Leetify** 链接（://leetify.com/app/profile/{steam64}`）。该项目与 Leetify 无关 Leetify 赞助## 1. 获取 FACEIT 服务器端 API 密钥. 前往 **FACEIT 开发者门户 /室**：<https.faceit.com/> 2应用并生成 **服务器 API 密钥（不是客户端密钥）。 3. — 它仅作为服务器环境变量（`FACEIT_API_KEY`）存在，永远不会在面向客户端的代码中使用。 游戏分支是 `cs2`（旧的` 分支在此处已弃用且未使用）。 --- ## 2. 在本地运行 ```bash python -m venv venv # Windows: venv\Scripts\activateOS/Linux: source/activate pip install requirements.txt cp . .env #env 并设置 FACE=... python server``` 服务器启动在 `0.0.:8000`，MCP 端点位于 **`localhost:8000/mcp`**. **测试：** 检查：`curllocalhost:8000/health `{"status":"ok"}` - MCP 检查器： `http://localhost:/mcp`（式传输的 HTTP 传输）并调用 `analyze_player使用类似 `donk` 或 `ZywOo` 的昵称。 > 注意：`PORT` 在本地覆盖默认 8000，如果设置，则在 Render 上自动注入。 --- ## 3. 部署此存储库附带了一个 Render **蓝图**（`render.yaml`）： 1. 将此存储库推送到 GitHub。 2. 在 Render 中：**新建 → 蓝图**，选择存储库。Render 读取 `render.yaml` 并创建一个名为 `faceit-cs2-mcp` 的免费网络服务。 3. 在服务的 **环境** 设置中，设置 **`FACEIT_API_KEY`** 为您的服务器（标记为 `sync`，因此 Render 不文件中读取它 — 手动设置）。 可选设置 **`LEETIFY`** 以获得更高的 速率限制（服务器它的情况下工作）。 `ENABLE_FACEIT_O `ENABLE_ELICITATION` 默认值为 `" — 留下它们。 部署。Render 的健康探测会命中 `/health一旦变为绿色，服务就会在 `https://<your-service>.onrender.com` 上启动。 **部署的工作原理（以及为什么它在第一次尝试）：** - **可流式传输的 HTTP — `mcp.run(transport="http", ...)`，而不是 stdio/SSE。 - **绑定 `0.0.0`** 并从 Render 注入的 env 变量中读取 **`PORT本地备用 8000）。没有硬编码端口，没有 `127.0.0.1`。 - **无状态 HTTP**（`stateless_http=True`），因此 Render 的代理层冷启动不会破坏内存会话，Claude 的连接器会干净地。 - **TLS 由终止。** 应用在 `$PORT` 上提供纯 HTTPonrender.com` 免费提供 HTTPS。Python 中**没有证书/SSL 代码** — 这是经典错误 **`/health`** **GET**（200 `{"status":"ok"}` Render 的 `healthCheckPath`；`/m 端点不是普通的 GET健康目标。 - 每个工具 **捕获自己的错误**（404/401/超时）并返回结构化消息，而不是抛出，因此错误的查找永远不会在对话中出现 500 错误。 --- ## 4. 将其添加到 Claude 作为连接器 在 **Claude → 设置 → 连接器 → 添加自定义连接器**此确切网址： ``` https://<your-service>.onrender.com/mcp（用您的 Render 服务名称替换 `<your-service>`。路径为 `/mcp` — 服务器也接受 `/mcp/`。） > **Render 免费层冷启动：** 在空闲约 15 分钟后，服务会休眠，第一次请求可能需要约 50 秒才能。如果第一次连接尝试超时，只需重试 — 一旦，连接将立即恢复。 --- ## 每用户个性化 两层，均无需基础设施： - **现在（默认，无身份验证，无数据库）：** `set_my_profile("<nick>")` 记住您是谁，以便会话使用，因此 `analyze_player()` 等默认使用您。它存储在内存中，按 MCP 会话键控，是 **尽力而为** — 在 `stateless_http=True` 下，没有稳定的会话 ID，因此每个工具也接受显式的 `query`。该显式参数是真正的保证：没有任何内容在冷启动。FACEIT 的公共 API + Leetify 的公共 API 已经涵盖了完整的辅导范围，因此这提供了个性化的体验，无需身份验证。 - **稍后（真正的 OAuth，禁用）：** 参见下一节。 ## 稍后启用真正的 OAuth（高级 - 需要持久存储） 一个完整的 FACEIT OAuth 提供程序在 [`auth_faceit.py`](auth_faceit.py) 中使用 FastMCP 的 `OAuthProxy` 搭建，针对 FACEIT 的真实 OIDC 端点，位于 `ENABLE_FACEIT_OAUTH默认为 `false`）后面。当为假时，服务器运行开放，并首次连接 Claude。**在正常部署时不要启用它。** 两个注意事项您必须首先了解： 1. **Claude.ai DCR 问题。** Claude.ai 远程连接器有一个报告的动态客户端注册（DCR）`400` 失败针对 FastMCP 的 `OAuthProxy`。启用 OAuth 可能会破坏连接 — 首先在 **MCP 检查器** 中测试，而不是直接在 Claude 中。 **内存令牌存储不可用于生产。** 框架将 `client_storage=None` 留空，因此 OAuth 客户端注册和令牌存储在内存中，**且在重启/冷启动后不存活**。使其适用于生产需要 **持久的、加密的存储**（一个 DB/Redis 实现 `AsyncKeyValue`），这故意超出了此无需基础设施构建的范围。注入点在 `auth_faceit.py` 中标记。 要实验：设置 `ENABLE_FACEIT_OAUTH=true`，`MCP_J，`FACEIT_OAUTH_CLIENT_ID`，`FACEIT_OAUTH_CLIENT_SECRET`，并将 `https://<service>.onrender.com/auth/callback` 注册为 FACEIT OAuth 应用中的重定向 URI。 > 类似地，`ENABLE_ELICITATION`（默认为 `false`）开启协议级 `ctx.elicit` 提示。它关闭，因为在 `stateless_http` 下，该请求往返不可靠，并且可能会挂起一个工具。关闭后，不明确的昵称解析为最佳匹配，并返回 `candidates` 列表，供 Claude 在对话中消歧义。 --- ## 做出的假设 - FastMCP 3.x 独立包（`from fastmcp import FastMCP`）；MCP 端点安装在 `/mcp`。 - FACEIT 统计字段被视为字符串，并防御性地解析（容忍缺少字段）。 - 技能等级 ELO 波段遵循 FACEIT 公布的 CS2 表；地图需要 ≥10 场比赛才能计入最佳/最差；≥3 场比赛的活跃连败标志倾斜风险。**同行基准测试** 抽样40 名同缓存分布 时；静态表是近似的。这些阈值/ [`analysis.py`](analysis.py) 和 [`.py`](benchmarks.py) 中，易于调整。 - Leetify 字段名称/路径在编译时已针对实时 OpenAPI 规范进行了确认。 --- ## 测试 ```bash pip install pytest python -m pytest tests/ -v ``` 单元测试（无网络）涵分析引擎（解析，等级波段，杀伤/瞄准/，地图排名，表格斜，端到端诊断），**基准数学** + 静态，和 **Leetify合**（检测，署名，失）。