内容
# 部落冲突MCP服务器
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://modelcontextprotocol.io)
一个[模型上下文协议](https://modelcontextprotocol.io)（MCP）服务器，允许Claude（或任何MCP客户端）从**官方部落冲突API**读取您的部落数据，并应用您部落的规则进行战争评分、长老晋升筛选和CWL延续决策。
为希望使用**AI辅助部落分析**的部落领导者构建，具有可复制和可配置的规则。
**关键词**：部落冲突，MCP，模型上下文协议，Claude，Claude Desktop，部落战争，CWL，部落战争联赛，部落管理，长老晋升，战争分析， Supercell API。
---
## 您可以用它做什么
一旦连接到Claude Desktop（或另一个MCP客户端），您可以询问以下问题：
> "我们的上一次战争怎么样？谁没有遵守规则？"
> "我应该将ankit176晋升为长老吗？我们的政策标准是什么？"
> "为下赛季准备一个CWL延续推荐。"
> "部落中谁的捐赠比例最高？"
> "提取过去5个周末的资本突袭战利品。"
MCP将每个问题转换为正确的API调用，应用您的**可配置规则**（以JSON格式，自由编辑），并返回一个准备好的答案。
---
## 示例输出
在完成战争后运行它，您会得到类似的结果：
```markdown
# 战争报告 — vs clash serious (失败)
使用的总攻击次数：26 · 未使用攻击次数：4 · 平均 ⭐/攻击：2.27 · 平均摧毁率：83%
## 1. 攻击参与度（预期2/2）
- 使用了两次攻击（12次）：Justin (#1), Slayer7 (#2), TURBO (#3), ...
- 只使用1次攻击（2次）：M@NJ!T (#4), Laeo_Lol XD (#11)
- 🚨 未攻击（1次）：Punjabi Pete (#15)
## 2. 规则遵守情况
- 清洁（3次）：Justin (#1), aNkiT (#6), joe (#10)
- 违规（12次）：
- Slayer7 (#2, TH18)：第二次攻击没有3⭐ 且只造成了80%的破坏
- M@NJ!T (#4, TH18)：第一次攻击击中了 #10（偏移 +6）；规则 = 镜像或向下偏移
- ankit176 (#8, TH17)：第二次攻击目标偏移 -3（应该击中更低的基数以获得智能3⭐）
- ...
## 3. 性能排行榜
| 排名 | 名称 | 位置 | 部落等级 | 获得的⭐ | 平均破坏率 | 分数 | 等级 |
| 1 | Justin | #1 | TH18 | 6 | 100% | 23 | A |
| 2 | Corrupt | #5 | TH17 | 6 | 100% | 20 | A |
...
## 4. 智能攻击荣誉榜（清洁3⭐较低基数）
- Justin (#1) → 击中 #2 基数获得 3⭐ 100%
- Corrupt (#5) → 击中 #9 基数获得 3⭐ 100%
```
---
## MCP公开的工具
**API包装器（只读）：**
| 工具 | 用途 |
|---|---|
| `clash_get_clan` | 部落级详细信息（名称、等级、战争联赛、成员数量） |
| `clash_get_clan_members` | 名单包括角色、捐赠、战争星级、奖杯 |
| `clash_get_warlog` | 过去的战争（仅摘要 — 见限制） |
| `clash_get_current_war` | 当前常规战争，**完整每攻击数据** |
| `clash_get_cwl_group` | 当前CWL小组 + 每轮战争标签 |
| `clash_get_cwl_war` | 单个CWL战争按标签 |
| `clash_get_player` | 玩家资料（英雄、部队、战争星级、当前部落） |
| `clash_api_get` | **通用GET直通**任意未包装的端点（金色通行证、资本突袭、联赛、位置、部落搜索等） |
**工作流工具（杠杆）：**
| 工具 | 用途 |
|---|---|
| `clash_grade_war` | 将您的规则应用于战争的攻击 → 每玩家等级、分数、规则违规 |
| `clash_war_report` | Markdown事后分析：谁攻击了，谁遵守了规则，性能排行榜，智能攻击荣誉榜和错失的机会 |
| `clash_missed_opportunities` | 对于每次攻击，检查当时是否有较弱的未被击败的基地。更深层次的智能攻击规则版本。 |
| `clash_carry_forward_recommendation` | 分析所有CWL轮次 → 保留/审查/替补名单用于下赛季 |
| `clash_promotion_candidates` | 根据长老标准（捐赠比例、英雄进度、战争贡献）筛选成员 |
| `clash_snapshot_war` | 将当前战争（常规 + CWL轮次）保存到本地磁盘。幂等。设计用于按计划运行。 |
| `clash_snapshot_status` | 显示快照存储中的内容 + 识别与战争日志的差距 |
| `clash_player_war_history` | 拉取玩家在存储的快照中每攻击的历史记录（出勤率、平均星级、趋势） |
---
## 入门指南
### 1. 获取免费的部落冲突API令牌
此MCP封装了**官方Supercell API**，该API免费但需要与您的IP地址绑定的令牌。
1. 打开 [developer.clashofclans.com](https://developer.clashofclans.com)。
2. 点击 **登录** 并使用您的 **Supercell ID**（与您的游戏账户绑定的同一个账户 — 您将收到一个电子邮件代码）。
3. 登录后，进入 **我的账户** → **创建新密钥**。
4. 查找您的当前公共IP地址 — 最简单的方法：
```bash
curl ifconfig.me
```
5. 填写表格：
- **密钥名称**：任意（例如 `coc-mcp`）
- **描述**：任意（例如 `MCP服务器用于部落分析`）
- **允许的IP地址**：粘贴您从 `curl ifconfig.me` 获得的IP地址
6. 点击 **创建密钥**。复制出现的长 **JWT令牌**（以 `eyJ...` 开头）。
> 🛡️ **令牌与IP地址绑定**。如果您的IP地址更改（新的ISP、VPN、咖啡店），请重新生成密钥并使用新的IP地址，或者从具有固定IP地址的主机运行MCP（小型VPS、家庭服务器等）。
### 2. 找到您的部落标签
在游戏中，点击您的部落名称 → 查找类似 `#YV9JRULU` 的标签。注意：**部落标签仅使用大写字母和数字**（无 `O`，仅 `0`）。
### 3. 克隆和安装
```bash
git clone https://github.com/justinritchie/clash-of-clans-mcp.git
cd clash-of-clans-mcp
pip install -r requirements.txt
```
### 4. 配置您的令牌
```bash
cp .env.example .env
```
编辑 `.env`:
```bash
COC_API_TOKEN=eyJ0eXAiOiJKV1Q... # <-- 粘贴您的令牌
COC_DEFAULT_CLAN_TAG=#YV9JRULU # <-- 您的部落标签
```
`.env` 文件被 `.gitignore`，因此您的令牌不会被意外提交。
### 5. 烟雾测试
```bash
python coc_test.py
```
您应该看到每个端点都有绿色勾选：
```
✅ GET /clans/<tag>
部落： Broken Arrow (等级 27) — 44 名成员，793W
✅ GET /clans/<tag>/members
✅ GET /clans/<tag>/warlog
✅ GET /clans/<tag>/currentwar/leaguegroup
✅ GET /clans/<tag>/currentwar
```
如果您遇到 **❌ HTTP 403**，则您的IP地址与令牌的白名单IP地址不匹配。请使用当前IP地址重新生成令牌（`curl ifconfig.me`）。
如果CWL联赛小组返回404，这是可以的 — CWL仅在每个月的头~10天运行。
### 6. 运行单元测试
```bash
pip install pytest
pytest tests/ -v
```
八个测试应该通过。它们运行在fixture JSON上，无需进行API调用。
### 7. 尝试战争报告CLI
```bash
python run_war_report.py
```
这将为您最近的战争（无论状态如何）导出完整的Markdown报告。
---
## 将其连接到Claude Desktop
### 选项A — 使用附带的安装程序（推荐）
```bash
python install_to_claude_desktop.py
```
这：
- 备份现有的 `claude_desktop_config.json`（带有时间戳）
- 在不触及任何其他MCP的情况下，添加一个 `coc` 条目
- 从您的 `.env` 中提取令牌
- 幂等 — 重新运行只会更新条目
然后 **重启Claude Desktop**。
### B选项 — 手动编辑
将以下内容添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`（Mac）或 `%APPDATA%/Claude/claude_desktop_config.json`（Windows）：
```json
{
"mcpServers": {
"coc": {
"command": "python3",
"args": ["/absolute/path/to/coc-mcp/coc_mcp_server.py"],
"env": {
"COC_API_TOKEN": "eyJ0eXAi...",
"COC_DEFAULT_CLAN_TAG": "#YOURTAG"
}
}
}
}
```
重启Claude Desktop。`coc_*` 工具将出现。
### 合作或其他MCP客户端
MCP通过stdio运行。任何支持stdio MCP服务器的客户端都可以使用 — 将其指向 `coc_mcp_server.py` 并设置环境变量。
---
## 自定义评分标准
默认规则位于 `config/rubric.default.json`:
```json
{
"war_attack_rubric": {
"first_attack": {
"acceptable_offsets": [0, 1], // 镜像或向下偏移
"min_stars_for_pass": 2
},
"second_attack": {
"preferred_offsets_min": 1, // 必须攻击低于您的排名
"must_3_star": true // 智能3星预期
},
"missed_attack_penalty": -10
},
"elder_promotion_rubric": {
"min_donation_ratio": 0.4,
"min_hero_progress_pct": 80,
"min_war_score_last_n": 50
},
"carry_forward_rubric": {
"min_attacks_used_pct": 100,
"min_avg_stars": 2.0,
"min_avg_destruction": 75
}
}
```
**自定义方式：**
1. **永久** — 复制到 `config/rubric.local.json`（gitignored），编辑，然后指向它：
```bash
COC_RUBRIC_PATH=./config/rubric.local.json
```
2. **每次调用** — 调用 `clash_grade_war` 或 `clash_war_report` 时，传递 `rubric_overrides` 并更改您要修改的字段。它们会深度合并到加载的评分标准中。
示例：放松智能3⭐规则进行一次分析：
```json
{ "war_attack_rubric": { "second_attack": { "must_3_star": false } } }
```
---
## 限制（开始前请了解）
- **每次攻击的数据仅适用于**当前战争（状态 `inWar` 或 `warEnded`）。`/warlog` 端点仅返回摘要（结果，总数 — 无每次攻击的数据）。要随时间分析过去的战争，请将 `/currentwar` 快照到磁盘，状态为 `warEnded`。（未来增强：`clash_snapshot_war` 工具。）
- **API是只读的。** 您无法晋升、踢出、接受加入请求、编辑部落设置、发送消息或更改战争状态。Supercell故意不公开写入端点。这是诊断/咨询工具 — 它告诉您谁值得采取行动；您在游戏中采取行动。
- **无部落聊天访问权限。** Supercell不公开聊天。如果您需要基于聊天的流程，请使用Discord桥接机器人。
- **API令牌与IP地址绑定。** 如果您的IP地址更改，令牌就会失效。请重新生成或使用固定IP地址的主机。
- **任职期限 / “在部落中的天数” 不在官方API中。** 该数据存在于第三方网站，如clashofstats.com。未来的增强功能可能会从中抓取；目前，老人评分标准使用战争贡献和捐赠比例作为替代。
---
## 项目布局
```
coc-mcp/
├── coc_mcp_server.py # FastMCP入口 — 工具注册
├── coc_mcp/
│ ├── client.py # 异步COC API客户端
│ ├── grading.py # 评分标准引擎
│ ├── reporting.py # Markdown生成器
│ └── config.py # 令牌 + 评分标准加载
├── config/
│ └── rubric.default.json # 默认评分标准（自由编辑）
├── tests/
│ ├── fixtures/ # 测试样本JSON
│ └── test_grading.py # 单元测试
├── coc_test.py # 现场烟雾测试脚本
├── run_war_report.py # CLI：导出当前战争报告
├── install_to_claude_desktop.py # 安全安装程序（先备份）
└── mcp_config_example.json # claude_desktop_config.json的下拉项
```
---
## 贡献
欢迎PR，尤其是：
- **更多工作流工具**用于常见的领导任务（战争后期趋势、捐赠监控、英雄进度警报）
- **从clashofstats.com或类似站点抓取任期**（其自身的MCP）
- **快照存储**用于历史战争分析（sqlite或jsonl）
- **战争预测**（给定阵容+对手，预计结果？）
- **更多语言SDK**（这是Python；TypeScript端口将有所帮助）
如果您在此基础上构建项目，请发送链接 — 很乐意看到其他部落正在做什么。
---
## 许可证
MIT — 见 [LICENSE](./LICENSE).
---
## 致谢
该产品使用来自 [部落冲突API](https://developer.clashofclans.com) 的数据，但与Supercell无关、未获得Supercell的认可、赞助或特别批准。Supercell对此不承担任何责任。有关更多信息，请参阅Supercell的粉丝内容政策： [supercell.com/fan-content-policy](https://www.supercell.com/fan-content-policy).
使用 [FastMCP](https://github.com/modelcontextprotocol/python-sdk) 和 [MCP规范](https://modelcontextprotocol.io) 构建。
