three.ws Coin Clash

@three-ws/clash-mcp

通过任意 AI Agent，参与 three.ws Coin Clash——由真实持仓数据和 pump.fun 数据支持的社区阵营之战。查看实时战况板，使用钱包加入，并为所属阵营集结力量。

---

一个基于 stdio 的 Model Context Protocol 服务，让任意 AI Agent 都能参与 Coin Clash——three.ws 的社区阵营之战。每个社区都是一个阵营，其持有者就是军队；每轮匹配两个阵营，倒计时结束前集结力量更多的军队获胜。查看实时战况板和排行榜，然后加入（证明你持有该代币）并为己方集结。

读取数据公开——将 THREE_WS_BASE 指向一个部署实例即可。写入操作与钱包绑定：加入时需使用 Solana 密钥签署挑战，后端会确认你当前在链上持有该阵营代币，然后发放参战凭证。阵营、成员和势头数据来自 CoinCommunities + pump.fun；集结力量会在服务端持久保存并排名。所有数据均为真实数据。

安装

npm install @three-ws/clash-mcp

也可以使用 npx 运行（无需安装）：

npx @three-ws/clash-mcp

快速开始

Claude Code，一行命令：

claude mcp add clash -- npx -y @three-ws/clash-mcp

Claude Desktop / Cursor（claude_desktop_config.json 或 mcp.json）：

{
	"mcpServers": {
		"clash": {
			"command": "npx",
			"args": ["-y", "@three-ws/clash-mcp"],
			"env": {
				"SOLANA_SECRET_KEY": "<base58 secret of your enlisting wallet — only needed for writes>"
			}
		}
	}
}

使用 MCP Inspector 检查工具列表：

npx -y @modelcontextprotocol/inspector npx @three-ws/clash-mcp

工具

工具	类型	功能
get_clash_state	只读	实时战况板：对阵情况、各军队的力量与势头、回合倒计时、拉锯战的力量占比，以及当前领先方。
get_clash_leaderboard	只读	阵营战的历史记录（胜/负/平、胜率、力量），也可选择查看单个阵营本轮的顶尖战士。
enlist_faction	写入	证明签署者的钱包持有某个阵营代币（由 Solana 签名），并获取参战凭证。
rally_faction	写入	为所属阵营消耗 taps 来增加战斗力量——传入参战凭证，或传入代币以在一次调用中自动加入并集结。

读取操作会返回实时数据——不同调用之间力量和排名会变化，因此不具备幂等性。写入操作与钱包绑定：不会转移任何资金（参战凭证是签名证明，并非交易），因此不会造成破坏。enlist_faction 具备幂等性（重复加入会签发等效凭证）；rally_faction 不具备幂等性（每次调用都会增加力量）。

输入参数

get_clash_state——无。

get_clash_leaderboard——faction（可选的 mint；也会返回该阵营本轮的顶尖战士）。

enlist_faction——token（必填的阵营 mint）、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）。

示例

// get_clash_state
> {}
{
  "ok": true,
  "epoch": 486231,
  "epochMs": 3600000,
  "endsAt": 1750000000000,
  "msLeft": 1843000,
  "factionCount": 16,
  "arena": [
    {
      "id": "486231:…",
      // each side also carries image, posts, and priceUsd (elided here)
      "a": { "token": "…", "symbol": "ALPHA", "members": 8200, "momentum": 1.31, "power": 940, "record": { "w": 12, "l": 4, "d": 1, "battles": 17, "power": 8100 } },
      "b": { "token": "…", "symbol": "BETA",  "members": 5100, "momentum": 1.12, "power": 610, "record": { "w": 7,  "l": 9, "d": 0, "battles": 16, "power": 5400 } },
      "aShare": 0.61,
      "leader": "…ALPHA mint…"
    }
  ],
  "bye": null
}

// rally_faction — auto-enlist + rally in one call (wallet must hold the coin)
> { "token": "…faction mint…", "taps": 50 }
{
  "ok": true,
  "enlisted": { "wallet": "…", "amount": 1250000, "usd": 84.20 },
  "epoch": 486231,
  "mint": "…faction mint…",
  "added": 66,
  "momentum": 1.31,
  "walletPower": 66,
  "walletCap": 5000,
  "capped": false,
  "factionPower": 1005,
  "msLeft": 1841000
}

要求

• Node.js >= 20。
• 可访问网络 https://three.ws（或你自己的 THREE_WS_BASE）。
• 仅写入操作需要：使用 SOLANA_SECRET_KEY 或每次调用时传入的 secret，提供一个 base58 格式的 Solana 私钥，其对应的钱包持有所应征阵营的代币。

环境变量

变量	是否必需	默认值	说明
THREE_WS_BASE	否	https://three.ws	要连接的 API 部署地址。
THREE_WS_TIMEOUT_MS	否	20000	每次请求的超时时间。
SOLANA_SECRET_KEY	仅写入操作需要	—	应征钱包的 base58 私钥。每次调用传入的 secret 会覆盖此值。请像现金一样妥善保管。
CLASH_SOLANA_SECRET	否	—	当未设置 SOLANA_SECRET_KEY 时读取的备用签名密钥，供按服务隔离环境变量的主机使用。格式相同，也要同样谨慎保管。

secret 仅用于在本地为应征挑战签名——对挑战文本生成分离式 ed25519 签名。它不会用于签署交易，也不会发生资金转移。但它仍能控制一个钱包：建议使用每次调用时传入的 secret，或在可信机器上设置专用环境变量。

错误

工具调用失败时会返回 MCP 错误结果（isError: true），其文本为单个 JSON 对象：{ "ok": false, "error": "<code>", "message": "…" }；上游拒绝请求时还会包含 status，而失败原因附带上下文时（例如哪个钱包未持有代币）会包含 detail：

error	含义	处理方法
validation_error	参数错误：缺少阵营 token，或调用 rally_faction 时既未提供 pass 也未提供 token。	修正调用。
no_signer / invalid_secret	写入工具没有 Solana 密钥，或密钥不是 base58 格式的 64 字节私钥。	传入 secret 或设置 SOLANA_SECRET_KEY。
not_eligible	自动应征的钱包未持有该阵营的代币，因此没有签发通行证。detail 中包含 wallet、faction 和 reason。	持有该代币后重试。
upstream_error	API 拒绝了请求。status 中包含 HTTP 状态码；值得注意的响应内容包括 bad_challenge、bad_signature、pass_invalid（战争通行证已过期或属于其他用户）、balance_unavailable（RPC 无法读取持有情况）和 cc_unconfigured（该部署未配置 CoinCommunities）。	根据错误码处理；遇到 pass_invalid 时重新应征。
timeout	在 THREE_WS_TIMEOUT_MS 指定的时间内未收到响应。	重试或延长超时时间。
network_error	请求未能到达 API（DNS、网络离线或 TLS 问题）。	检查网络连接和 THREE_WS_BASE。
bad_config	THREE_WS_TIMEOUT_MS 不是正数（启动时抛出）。	修正环境变量。

链接

• 主页：https://three.ws
• 更新日志：https://three.ws/changelog
• 问题反馈：https://github.com/nirholas/three.ws/issues
• 许可证：Apache-2.0，详见 LICENSE

---

_{属于 three.ws SDK 套件的一部分 — 3D AI Agent、链上身份和 Agent 支付。
网站 · 更新日志 · GitHub}