Spirit Cards

spirit-cards-mcp

一个只读的 Model Context Protocol（MCP）服务，适用于 Spirit Cards (Proof of Card)——一款在 Robinhood Chain 上通过工作量证明铸造的收藏卡牌游戏——主网 chainId 4663，自 2026-10-05 起运行。

它通过 stdio 运行，因此 Claude Desktop 和 Cursor 可使用 npx 启动它。它从托管的 Web API 获取实时游戏数据，并使用 viem 在本地计算工作量证明——因此 Agent 无需钱包、私钥或发送任何交易，就能检查卡牌收藏、验证 nonce，甚至不断尝试以找到有效 nonce。

只读。 不涉及密钥、机密、签名或发送操作。所有网络调用都是普通的 GET 请求。

---

快速开始

使用 npx 运行（发布后）

npx spirit-cards-mcp

从源代码运行

npm install
node src/index.mjs      # starts the stdio server (logs to stderr)

该服务通过 stdin/stdout 使用 MCP 通信，并且只向 stderr 输出日志——通常由 MCP 客户端启动，而非手动启动。

---

在 Claude Desktop 中使用

将以下内容添加到 claude_desktop_config.json （macOS 上为 ~/Library/Application Support/Claude/，Windows 上为 %APPDATA%\Claude\）：

{
  "mcpServers": {
    "spirit-cards": {
      "command": "npx",
      "args": ["-y", "spirit-cards-mcp"],
      "env": { "SPIRIT_CARDS_API": "https://spiritcards.fun" }
    }
  }
}

在 Cursor 中使用

将以下内容添加到 .cursor/mcp.json（项目级）或 ~/.cursor/mcp.json（全局）：

{
  "mcpServers": {
    "spirit-cards": {
      "command": "npx",
      "args": ["-y", "spirit-cards-mcp"],
      "env": { "SPIRIT_CARDS_API": "https://spiritcards.fun" }
    }
  }
}

---

配置

环境变量	默认值	含义
SPIRIT_CARDS_API	https://spiritcards.fun	托管网站/API 的基础 URL

所有数据端点都只接受只读 GET 请求：

• /.well-known/ai.json — 项目描述信息（链 ID、核心合约、机制、链接）
• /stats/current.json — 实时供应量、价格、所需难度（baseBits）、冷却时间
• /api/meta/{tokenId} — 卡牌元数据
• /api/points — 积分排行榜
• /api/pool — 质押池/排放快照（累计池、分配比例、金库权重）
• /api/recent — 最近的链上活动

---

工具

工具	参数	描述
get_project_info	—	/.well-known/ai.json + 汇总整理的人工可读 summary
get_collection_stats	—	实时统计数据：供应量、价格、baseBits、冷却时间、暂停标志
get_card	tokenId	卡牌元数据（/api/meta/{tokenId}）
get_leaderboard	limit?（默认 25）	积分排行榜，截取至 limit 条
get_pool	—	质押池：累计池、分配比例、金库权重（未分发）
get_recent_activity	limit?（默认 10）	最近事件，截取至 limit 条
verify_nonce	miner、nonce	在本地验证 nonce 的工作量（不发送交易）：{work, leadingZeroBits, valid}
find_nonce	miner、maxAttempts?（≤5M）	从 0 开始不断尝试 nonce，直到有效（墙钟时间上限约 20 秒）
get_mining_guide	—	按步骤说明铸造流程，并提供实时价格/难度/冷却时间

工作量证明

nonce 满足以下条件时有效：

work = keccak256(abi.encodePacked(uint256 chainId, address core, address miner, uint256 nonce))
leadingZeroBits(work) >= baseBits

verify_nonce 和 find_nonce 都会使用 viem 的 keccak256 在本地计算，对 concatHex([chainId, core, miner, nonce]) 求哈希——与 Solidity 的 abi.encodePacked 逐字节完全一致。

提示词

提示词	参数	描述
project_overview	—	向新手介绍这款游戏（调用信息和统计工具）
start_mining	wallet?	逐步讲解如何找到 nonce 以及准确的铸造交易

---

托管的 HTTP MCP

更倾向于使用 HTTP 而非 stdio？同一 MCP 服务也托管在：

https://spiritcards.fun/api/mcp

---

许可证

MIT © 2026 Spirit Cards (Proof of Card)。参见 LICENSE。