内容
<p align="center">
<a href="https://three.ws"><img src="https://three.ws/three-ws-mcp-icon.svg" alt="three.ws" width="88" height="88"></a>
</p>
<h1 align="center">@three-ws/clash-mcp</h1>
<p align="center"><strong>在任意AI代理上玩转three.ws的社区派系战争——后者由真实资产和pump.fun数据支持——并查看实时战况，招募你的钱包，并为你的派系聚集力量。</strong></p>
<p align="center">
<a href="https://www.npmjs.com/package/@three-ws/clash-mcp"><img alt="npm" src="https://img.shields.io/npm/v/@three-ws/clash-mcp?logo=npm&color=cb3837"></a>
<img alt="license" src="https://img.shields.io/npm/l/@three-ws/clash-mcp?color=3b82f6">
<img alt="node" src="https://img.shields.io/node/v/@three-ws/clash-mcp?color=339933&logo=node.js">
<a href="https://registry.modelcontextprotocol.io/?q=io.github.nirholas"><img alt="MCP Registry" src="https://img.shields.io/badge/MCP%20Registry-io.github.nirholas-0ea5e9"></a>
<a href="https://three.ws"><img alt="three.ws" src="https://img.shields.io/badge/built%20by-three.ws-000"></a>
</p>
---
> 一个 [模型上下文协议](https://modelcontextprotocol.io) 服务器，将 **Coin Clash** —— three.ws 的社区派系战争 —— 扩展到任意AI代理，通过stdio接口。每个社区都是一个派系，其持有者是其军队；每轮两个派系匹配，哪个军队的力量更大，时钟耗尽前聚集更多力量，哪一方就赢。查看实时排行榜和领导者榜，然后 **招募** （证明你持有该币）和 **聚集** 你所在派系的力量。
读取是公开的——指向 `THREE_WS_BASE` 并启动。写入是钱包范围的：招募需要使用Solana密钥签名挑战，后端确认 **链上持有** 派系币后颁发战争通行证。派系、成员和动力来自CoinCommunities + pump.fun；聚集力量在服务器端持久化和排名。没有任何内容是模拟的。
## 安装
```bash
npm install @three-ws/clash-mcp
```
或使用 `npx` 运行（无需安装）：
```bash
npx @three-ws/clash-mcp
```
## 快速开始
**Claude 代码**，一行：
```bash
claude mcp add clash -- npx -y @three-ws/clash-mcp
```
**Claude Desktop / Cursor** (`claude_desktop_config.json` 或 `mcp.json`）：
```json
{
"mcpServers": {
"clash": {
"command": "npx",
"args": ["-y", "@three-ws/clash-mcp"],
"env": {
"SOLANA_SECRET_KEY": "<base58 密钥的招募钱包——仅写入时需要>"
}
}
}
}
```
使用MCP检查器检查界面：
```bash
npx -y @modelcontextprotocol/inspector npx @three-ws/clash-mcp
```
## 工具
| 工具 | 类型 | 功能 |
| --- | --- | --- |
| `get_clash_state` | 只读 | 实时战场：对阵、每个军队的力量 + 动量、回合时钟、拔河份额、谁领先。 |
| `get_clash_leaderboard` | 只读 | 所有派系战争记录（胜/负/平、胜率、力量），可选单个派系本轮的顶级士兵。 |
| `enlist_faction` | 写入 | 证明签名者的钱包持有派系币（Solana签名）并获得战争通行证。 |
| `rally_faction` | 写入 | 将战斗力作为派系的力量——传递战争通行证，或令牌自动招募并聚集在一个调用中。 |
读取返回实时数据——力量和 standings 在调用之间移动，因此两者都不是幂等的。写入是钱包范围的：没有资金移动（战争通行证是签名证明，不是交易），因此两者都不是破坏性的。`enlist_faction` 是幂等的（重新招募等效的通行证）；`rally_faction` 不是（每个调用追加力量）。
### 输入参数
**`get_clash_state`** — 无。
**`get_clash_leaderboard`** — `faction` （可选铸造；还返回该派系本轮的顶级士兵）。
**`enlist_faction`** — `token` （必填派系铸造），`secret` （可选base58 Solana密钥；默认为 `SOLANA_SECRET_KEY`）。
**`rally_faction`** — `taps` （必填，1–50），和 `pass` （来自 `enlist_faction` 的战争通行证） **或** `token` （+ 可选 `secret` ）自动招募。
## 战斗如何进行
1. **侦察。** `get_clash_state` 显示当前轮次：谁匹配，每个军队的力量、动量和 `msLeft`。
2. **招募。** `enlist_faction` 发出挑战，绑定到您的钱包 + 派系，用Solana密钥签名，后端验证签名 **和** 链上持有该币。你会收到一个 `warPass`。（无持有 → `eligible:false`，`reason:"not_a_holder"`。）
3. **聚集。** `rally_faction` 从通行证中花费 `taps` （每次调用1–50）作为战斗力——乘以派系的实时动量，按钱包每轮上限。反复调用，直到 `msLeft > 0`。
4. **胜利。** 当回合时钟归零时，军队力量更大的赢得战斗，结果写入每个派系的永久战争记录（`get_clash_leaderboard`）。
## 示例
```jsonc
// get_clash_state
> {}
{
"ok": true,
"epoch": 486231,
"msLeft": 1843000,
"factionCount": 16,
"arena": [
{
"id": "486231:…",
"a": { "token": "…", "symbol": "ALPHA", "members": 8200, "momentum": 1.31, "power": 940, "record": { "w": 12, "l": 4, "d": 1 } },
"b": { "token": "…", "symbol": "BETA", "members": 5100, "momentum": 1.12, "power": 610, "record": { "w": 7, "l": 9, "d": 0 } },
"aShare": 0.61,
"leader": "…ALPHA mint…"
}
],
"bye": null
}
```
```jsonc
// rally_faction — 自动招募 + 聚集在一个调用中（钱包必须持有该币）
> { "token": "…faction mint…", "taps": 50 }
{
"ok": true,
"enlisted": { "wallet": "…", "amount": 1250000, "usd": 84.20 },
"epoch": 486231,
"mint": "…faction mint…",
"added": 65,
"momentum": 1.31,
"walletPower": 65,
"walletCap": 5000,
"capped": false,
"factionPower": 1005,
"msLeft": 1841000
}
```
## 要求
- **Node.js >= 20.**
- 可以访问 `https://three.ws` 的网络（或您自己的 `THREE_WS_BASE`）。
- 仅写入：一个base58 Solana密钥，其钱包 **持有** 它招募的派系币，通过 `SOLANA_SECRET_KEY` 或每个调用的 `secret` 参数。
### 环境变量
| 变量 | 必需 | 默认 | 备注 |
| --- | --- | --- | --- |
| `THREE_WS_BASE` | 否 | `https://three.ws` | API部署地址。 |
| `THREE_WS_TIMEOUT_MS` | 否 | `20000` | 每个请求的超时时间。 |
| `SOLANA_SECRET_KEY` | 仅写入 | — | 招募钱包的base58密钥。每个调用的 `secret` 参数覆盖它。 **像现金一样保护。** |
> `secret` 仅用于本地签名招募挑战——一个分离的ed25519签名，覆盖挑战文本。它从不签署交易，也不会移动资金。尽管如此，它控制了一个钱包：更倾向于每个调用的 `secret` 参数或一个专用环境变量在一台你信任的机器上。
## 链接
- 首页：https://three.ws
- 更新日志：https://three.ws/changelog
- 问题：https://github.com/nirholas/three.ws/issues
- 许可证：Apache-2.0 — 见 [LICENSE](./LICENSE)
---
<p align="center">
<sub>
three.ws SDK 套件的一部分 — 3D AI 代理、链上身份和代理支付。<br/>
<a href="https://three.ws">网站</a> · <a href="https://three.ws/changelog">更新日志</a> · <a href="https://github.com/nirholas/three.ws">GitHub</a>
</sub>
</p>
## 许可证
Copyright © 2026 nirholas. All rights reserved.
本软件是专有软件 — 见 [LICENSE](./LICENSE)。未经版权所有者明确书面许可，不得授予任何权利。
