{"id":"0e222975-9210-4153-9f97-06bf68c885c4","slug":"clash-mcp","kind":"mcp","name":"clash-mcp","summary":"Play three.ws Coin Clash — the community faction war backed by real holdings + pump.fun data — from any AI agent. Read the live battle board and leaderboard (public), or enlist your wallet and rally p","owner":"nirholas","repoUrl":"https://github.com/nirholas/clash-mcp","license":"Apache-2.0","licenseTier":"permissive","trust":"community","stars":9,"match":null,"fewStars":false,"format":"mcp","createdAt":"2026-06-30T23:20:54.000Z","addedAt":"2026-10-21T04:44:53.172Z","logoUrl":"https://avatars.githubusercontent.com/u/22895867?u=56ece328987410ef7987e2e9b2c9247f735bf751&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["cloud-infra","data-analytics","memory-knowledge"],"tags":["ai-agents","solana","faction","game","nodejs","pump-fun","siws","three-ws"],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-28T07:31:34.875Z","sample":false,"url":"https://conduits.dev/tools/clash-mcp","language":"JavaScript","transports":["stdio"],"install":{"npm":"@three-ws/clash-mcp"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"<p align=\"center\">\n  <a href=\"https://three.ws\"><img src=\"https://three.ws/three-ws-mcp-icon.svg\" alt=\"three.ws\" width=\"88\" height=\"88\"></a>\n</p>\n\n<h1 align=\"center\">@three-ws/clash-mcp</h1>\n\n<p align=\"center\"><strong>Play three.ws Coin Clash — the community faction war backed by real holdings + pump.fun data — from any AI agent. Read the live battle board, enlist your wallet, and rally power for a faction.</strong></p>\n\n<p align=\"center\">\n  <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>\n  <img alt=\"license\" src=\"https://img.shields.io/npm/l/@three-ws/clash-mcp?color=3b82f6\">\n  <img alt=\"node\" src=\"https://img.shields.io/node/v/@three-ws/clash-mcp?color=339933&logo=node.js\">\n  <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>\n  <a href=\"https://three.ws\"><img alt=\"three.ws\" src=\"https://img.shields.io/badge/built%20by-three.ws-000\"></a>\n</p>\n\n---\n\n> A [Model Context Protocol](https://modelcontextprotocol.io) server that puts **Coin Clash** — three.ws's community faction war — in reach of any AI agent over stdio. Every community is a faction, its holders are its army; two factions are matched each round, and whichever army rallies more power before the clock runs out wins. Read the live board and leaderboard, then **enlist** (prove you hold the coin) and **rally** for your side.\n\nReads are public — point `THREE_WS_BASE` at a deployment and go. Writes are wallet-scoped: enlisting signs a challenge with your Solana key and the backend confirms a **live on-chain holding** of the faction coin before issuing a war pass. Factions, members, and momentum come from CoinCommunities + pump.fun; rally power is persisted and ranked server-side. Nothing is mocked.\n\n## Install\n\n```bash\nnpm install @three-ws/clash-mcp\n```\n\nOr run with `npx` (no install):\n\n```bash\nnpx @three-ws/clash-mcp\n```\n\n## Quick start\n\n**Claude Code**, one line:\n\n```bash\nclaude mcp add clash -- npx -y @three-ws/clash-mcp\n```\n\n**Claude Desktop / Cursor** (`claude_desktop_config.json` or `mcp.json`):\n\n```json\n{\n\t\"mcpServers\": {\n\t\t\"clash\": {\n\t\t\t\"command\": \"npx\",\n\t\t\t\"args\": [\"-y\", \"@three-ws/clash-mcp\"],\n\t\t\t\"env\": {\n\t\t\t\t\"SOLANA_SECRET_KEY\": \"<base58 secret of your enlisting wallet — only needed for writes>\"\n\t\t\t}\n\t\t}\n\t}\n}\n```\n\nInspect the surface with the MCP Inspector:\n\n```bash\nnpx -y @modelcontextprotocol/inspector npx @three-ws/clash-mcp\n```\n\n## Tools\n\n| Tool                    | Type      | What it does                                                                                                       |\n| ----------------------- | --------- | ----------------------------------------------------------------------------------------------------------------- |\n| `get_clash_state`       | read-only | The live battle board: matchups, each army's power + momentum, the round clock, the tug-of-war share, who's leading. |\n| `get_clash_leaderboard` | read-only | All-time faction war records (W/L/D, win rate, power), optionally a single faction's top soldiers this round.       |\n| `enlist_faction`        | write     | Prove the signer's wallet holds a faction coin (Solana-signed) and get a war pass.                                  |\n| `rally_faction`         | write     | Spend taps as battle power for your faction — pass a war pass, or a token to auto-enlist and rally in one call.      |\n\nThe reads return live data — power and standings move between calls, so neither is idempotent. The writes are wallet-scoped: no funds ever move (a war pass is a signed proof, not a transaction), so neither is destructive. `enlist_faction` is idempotent (re-enlisting mints an equivalent pass); `rally_faction` is not (each call appends power).\n\n### Input parameters\n\n**`get_clash_state`** — none.\n\n**`get_clash_leaderboard`** — `faction` (optional mint; also returns that faction's top soldiers this round).\n\n**`enlist_faction`** — `token` (required faction mint), `secret` (optional base58 Solana secret; falls back to `SOLANA_SECRET_KEY`).\n\n**`rally_faction`** — `taps` (required, 1–50), and either `pass` (a war pass from `enlist_faction`) **or** `token` (+ optional `secret`) to auto-enlist first.\n\n## How a battle works\n\n1. **Scout.** `get_clash_state` shows the current round: who's matched, each army's power, momentum, and `msLeft`.\n2. **Enlist.** `enlist_faction` issues a challenge bound to your wallet + faction, signs it with your Solana key, and the backend verifies the signature **and** a live on-chain holding of the coin. You get back a `warPass`. (No holding → `eligible:false`, `reason:\"not_a_holder\"`.)\n3. **Rally.** `rally_faction` spends `taps` (1–50 per call) from the pass as battle power — multiplied by the faction's live momentum, capped per wallet per round. Call it repeatedly while `msLeft > 0`.\n4. **Win.** When the round clock hits zero, the army with more power takes the battle and the result is written to each faction's all-time war record (`get_clash_leaderboard`).\n\n## Example\n\n```jsonc\n// get_clash_state\n> {}\n{\n  \"ok\": true,\n  \"epoch\": 486231,\n  \"epochMs\": 3600000,\n  \"endsAt\": 1750000000000,\n  \"msLeft\": 1843000,\n  \"factionCount\": 16,\n  \"arena\": [\n    {\n      \"id\": \"486231:…\",\n      // each side also carries image, posts, and priceUsd (elided here)\n      \"a\": { \"token\": \"…\", \"symbol\": \"ALPHA\", \"members\": 8200, \"momentum\": 1.31, \"power\": 940, \"record\": { \"w\": 12, \"l\": 4, \"d\": 1, \"battles\": 17, \"power\": 8100 } },\n      \"b\": { \"token\": \"…\", \"symbol\": \"BETA\",  \"members\": 5100, \"momentum\": 1.12, \"power\": 610, \"record\": { \"w\": 7,  \"l\": 9, \"d\": 0, \"battles\": 16, \"power\": 5400 } },\n      \"aShare\": 0.61,\n      \"leader\": \"…ALPHA mint…\"\n    }\n  ],\n  \"bye\": null\n}\n```\n\n```jsonc\n// rally_faction — auto-enlist + rally in one call (wallet must hold the coin)\n> { \"token\": \"…faction mint…\", \"taps\": 50 }\n{\n  \"ok\": true,\n  \"enlisted\": { \"wallet\": \"…\", \"amount\": 1250000, \"usd\": 84.20 },\n  \"epoch\": 486231,\n  \"mint\": \"…faction mint…\",\n  \"added\": 66,\n  \"momentum\": 1.31,\n  \"walletPower\": 66,\n  \"walletCap\": 5000,\n  \"capped\": false,\n  \"factionPower\": 1005,\n  \"msLeft\": 1841000\n}\n```\n\n## Requirements\n\n- **Node.js >= 20.**\n- Network access to `https://three.ws` (or your own `THREE_WS_BASE`).\n- For writes only: a base58 Solana secret whose wallet **holds the faction coin** it enlists for, via `SOLANA_SECRET_KEY` or the per-call `secret` arg.\n\n### Environment variables\n\n| Variable              | Required           | Default            | Notes                                                                 |\n| --------------------- | ------------------ | ------------------ | --------------------------------------------------------------------- |\n| `THREE_WS_BASE`       | no                 | `https://three.ws` | API deployment to talk to.                                            |\n| `THREE_WS_TIMEOUT_MS` | no                 | `20000`            | Per-request timeout.                                                  |\n| `SOLANA_SECRET_KEY`   | writes only        | —                  | Base58 secret of the enlisting wallet. Per-call `secret` overrides it. **Treat like cash.** |\n| `CLASH_SOLANA_SECRET` | no                 | —                  | Fallback signer read when `SOLANA_SECRET_KEY` is unset, for hosts that scope env vars per server. Same format and the same care. |\n\n> The `secret` is only ever used to sign the enlist challenge locally — a detached ed25519 signature over the challenge text. It never signs a transaction and no funds move. Still, it controls a wallet: prefer a per-call `secret` or a dedicated env on a machine you trust.\n\n## Errors\n\nA failed tool call returns an MCP error result (`isError: true`) whose text is a single JSON object: `{ \"ok\": false, \"error\": \"<code>\", \"message\": \"…\" }`, plus `status` on upstream rejections and `detail` where the failure carries context (e.g. which wallet was not a holder):\n\n| `error` | Meaning | Recovery |\n| ------- | ------- | -------- |\n| `validation_error` | Bad arguments: a missing faction `token`, or `rally_faction` called with neither a `pass` nor a `token`. | Fix the call. |\n| `no_signer` / `invalid_secret` | A write tool had no Solana key, or the key was not a base58 64-byte secret. | Pass `secret` or set `SOLANA_SECRET_KEY`. |\n| `not_eligible` | The auto-enlisting wallet does not hold the faction coin, so no pass was issued. `detail` carries `wallet`, `faction`, and `reason`. | Hold the coin, then retry. |\n| `upstream_error` | The API rejected the request. `status` carries the HTTP code; notable bodies include `bad_challenge`, `bad_signature`, `pass_invalid` (expired or foreign war pass), `balance_unavailable` (RPC could not read the holding), and `cc_unconfigured` (the deployment has no CoinCommunities config). | Act on the code; re-enlist on `pass_invalid`. |\n| `timeout` | No response within `THREE_WS_TIMEOUT_MS`. | Retry or raise the timeout. |\n| `network_error` | The request never reached the API (DNS, offline, TLS). | Check connectivity / `THREE_WS_BASE`. |\n| `bad_config` | `THREE_WS_TIMEOUT_MS` is not a positive number (thrown at startup). | Fix the env var. |\n\n## Links\n\n- Homepage: https://three.ws\n- Changelog: https://three.ws/changelog\n- Issues: https://github.com/nirholas/three.ws/issues\n- License: Apache-2.0, see [LICENSE](./LICENSE)\n\n---\n\n<p align=\"center\">\n  <sub>\n    Part of the <a href=\"https://three.ws\">three.ws</a> SDK suite — 3D AI agents, on-chain identity, and agent payments.<br/>\n    <a href=\"https://three.ws\">Website</a> · <a href=\"https://three.ws/changelog\">Changelog</a> · <a href=\"https://github.com/nirholas/three.ws\">GitHub</a>\n  </sub>\n</p>\n\n<!-- three.ws:growth -->\n## Support the project\n\nIf clash-mcp saves you time, **[star it on GitHub](https://github.com/nirholas/clash-mcp)**. Stars are how other developers and AI agents find the repositories worth trusting, and they cost you one click.\n\nKnow someone who would use it? [Post on X](https://twitter.com/intent/tweet?text=clash-mcp%3A%20Play%20three.ws%20Coin%20Clash%3A%20the%20community%20faction%20war%20backed%20by%20real%20holdings%20%2B%20pump.fun%20data%3A%20from&url=https%3A%2F%2Fgithub.com%2Fnirholas%2Fclash-mcp) · [Share on Bluesky](https://bsky.app/intent/compose?text=clash-mcp%3A%20Play%20three.ws%20Coin%20Clash%3A%20the%20community%20faction%20war%20backed%20by%20real%20holdings%20%2B%20pump.fun%20data%3A%20from%20https%3A%2F%2Fgithub.com%2Fnirholas%2Fclash-mcp) · [Share on LinkedIn](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fgithub.com%2Fnirholas%2Fclash-mcp) · [Submit to Hacker News](https://news.ycombinator.com/submitlink?u=https%3A%2F%2Fgithub.com%2Fnirholas%2Fclash-mcp&t=clash-mcp%3A%20Play%20three.ws%20Coin%20Clash%3A%20the%20community%20faction%20war%20backed%20by%20real%20holdings%20%2B%20pump.fun%20data%3A%20from) · [Share on Reddit](https://www.reddit.com/submit?url=https%3A%2F%2Fgithub.com%2Fnirholas%2Fclash-mcp&title=clash-mcp%3A%20Play%20three.ws%20Coin%20Clash%3A%20the%20community%20faction%20war%20backed%20by%20real%20holdings%20%2B%20pump.fun%20data%3A%20from)\n\n## Built for AI agents too\n\nCoding agents and LLM tooling can read this repo directly: [AGENTS.md](./AGENTS.md), [llms.txt](./llms.txt), [llms-full.txt](./llms-full.txt). Point an agent at `https://github.com/nirholas/clash-mcp` and it has the context it needs.\n\n## More from the same author\n\n- [All repositories by nirholas](https://github.com/nirholas/nirholas#readme): the full catalog, grouped by topic\n- [three.ws](https://three.ws): the platform for 3D AI agents with Solana wallets, a skill marketplace and x402 payments\n- Questions or ideas: [open an issue](https://github.com/nirholas/clash-mcp/issues) or [start a discussion](https://github.com/nirholas/clash-mcp/discussions)\n\n## Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=nirholas/clash-mcp)](https://github.com/nirholas/clash-mcp/graphs/contributors)\n\n## Star history\n\n[![Star History Chart](https://api.star-history.com/svg?repos=nirholas/clash-mcp&type=Date)](https://www.star-history.com/#nirholas/clash-mcp&Date)\n\n<!-- /three.ws:growth -->\n\n<!-- three.ws:ecosystem -->\n## Part of three.ws\n\n[three.ws](https://three.ws) is a platform for 3D AI agents with Solana wallets: avatars, a skill marketplace, x402 payments and more than seventy MCP servers. `@three-ws/clash-mcp` is one package from it.\n\n- Documentation site: https://nirholas.github.io/clash-mcp/\n- npm: https://www.npmjs.com/package/@three-ws/clash-mcp\n- Canonical source: https://github.com/nirholas/three.ws (this repository is a generated mirror of `packages/clash-mcp`)\n- Agent-readable summary: [llms.txt](./llms.txt) and [AGENTS.md](./AGENTS.md)\n- Issues and ideas: https://github.com/nirholas/clash-mcp/issues\n<!-- /three.ws:ecosystem -->\n"}