@zenonft/mcp v1.2.0

ZenoNFT MCP Server — JSON-RPC 2.0 standard, Agent-ready NFT marketplace operations.

双模式鉴权：① API Key（无钱包 agent，服务端 executor 钱包签名）② SIWE 会话（带钱包 agent，per-call signerKey 签名）。

鉴权概览

| 模式 | 适用 agent | 鉴权头 | 链上签名 | 身份归属 | |------|-----------|--------|---------|---------| | API Key | 无钱包（Codex 等） | Authorization: Bearer znf_... | 服务端绑定的 executor 钱包 | 用户钱包地址（Key 与钱包绑定） | | SIWE 会话 | 带钱包 | Authorization: Bearer zns_... | per-call signerKey（地址必须与会话一致） | agent 自身钱包 | | Legacy | 存量客户端 | Authorization: Bearer <BRIDGE_MCP_TOKEN> | SIGNER_KEY 或 per-call | 平台 |

• 读接口：匿名可调（限流内）。
• 写接口：必须有上述任一鉴权；API Key 模式下调用方传的 signerKey 会被忽略（防越权）。

安装与启动

npm install @zenonft/mcp

# 配置环境变量
export BRIDGE_MCP_PORT=3300           # 监听端口（默认 3300）
export BRIDGE_MCP_TOKEN=your-token    # legacy 静态 token（可选）
export ZENONFT_MASTER_KEY=0x...       # API Key 主密钥（必填，用于加密 executor 私钥）
export ALLOWED_ORIGINS=https://your-domain

# 启动
npx @zenonft/mcp
# 或
node node_modules/@zenonft/mcp/src/server.js

配置 AI 客户端

无钱包 agent（API Key 模式）

1. 在 ZenoNFT 前端「API Keys」页连接钱包 → 生成 API Key。
2. 将 Key 配置到 agent：

{
  "mcpServers": {
    "zenonft": {
      "url": "http://43.156.99.215:3300",
      "headers": { "Authorization": "Bearer znf_你的APIKey" }
    }
  }
}

带钱包 agent（SIWE 会话模式）

agent 先调用以下 REST 接口完成登录，拿会话 token 后调用写工具时附上自己的 signerKey：

# 1. 获取签名消息
curl -X POST http://127.0.0.1:3300/auth/challenge \
  -H "Content-Type: application/json" \
  -d '{"address":"0x你的钱包地址"}'
# → { "message": "...EIP-4361 消息...", "nonce": "..." }

# 2. 用钱包对 message 做 personal_sign，验签换会话
curl -X POST http://127.0.0.1:3300/auth/verify \
  -H "Content-Type: application/json" \
  -d '{"message":"...", "signature":"0x..."}'
# → { "token": "zns_...", "address": "0x...", "expiresAt": 1234567890 }

之后调用 MCP 工具时带 Authorization: Bearer zns_...，写操作参数中传入 signerKey（其地址必须等于会话钱包地址）。

前端 API Key 管理（REST）

| 接口 | 鉴权 | 说明 | |------|------|------| | POST /auth/challenge | 公开 | 生成 EIP-4361 签名消息 | | POST /auth/verify | 公开 | 验签并签发会话 token | | GET /auth/session | 会话 | 当前会话信息 | | POST /keys | 会话 | 生成 API Key + 独立 executor 钱包 | | GET /keys | 会话 | 列出我的 Key | | DELETE /keys/:id | 会话 | 吊销 Key | | POST /ipfs/pin-file | 公开(限流) | 文件上传代理（multipart file）→ Pinata pinFileToIPFS，JWT 仅存服务端 | | POST /ipfs/pin-json | 公开(限流) | JSON 元数据上传代理 → Pinata pinJSONToIPFS，JWT 仅存服务端 | | GET /health | 公开 | 健康检查 |

23 个 MCP Tools

写操作（需鉴权，见上表）

| # | Tool | 参数 | 说明 | |---|---|---|---| | 1 | nft_listItem | nftContract, tokenId, priceWei | 定价挂单 | | 2 | nft_createAuction | nftContract, tokenId, startingPriceWei, durationSeconds | 创建英式拍卖 | | 3 | nft_buy | listingId, priceWei | 定价购买 NFT | | 4 | nft_bid | listingId, bidWei | 拍卖出价 | | 5 | nft_deployCollection | name, symbol, maxSupply, mintPrice?, royaltyBps?, soulbound? | 部署合集 | | 6 | nft_mint | collectionAddress, tokenURI, quantity? | 铸造 NFT（1-50） | | 7 | nft_cancelListing | listingId | 取消挂单 | | 8 | nft_endAuction | listingId | 结算拍卖 | | 9 | nft_makeOffer | listingId, offerWei | 对定价挂单报价 | | 10 | nft_acceptOffer | listingId | 卖家接受报价 | | 11 | nft_deployAndBatchMint | name, symbol, maxSupply, mintPrice?, royaltyBps?, baseURI?, soulbound?, maxMintsPerAddress?, tokenURIs | 一键部署 + 批量铸造 | | 12 | nft_ownerBatchMint | collectionAddress, tokenURIs | Owner 批量空投 | | 13 | nft_manageCollection | collectionAddress, mintPrice?, royaltyBps?, baseURI?, soulbound?, mintingEnabled? | 合集管理 | | 14 | nft_updateWhitelist | collectionAddress, action, addresses | 白名单增删 | | 15 | nft_withdraw | collectionAddress | Owner 提取资金 |

仅 SIWE 会话模式支持 per-call signerKey；API Key 模式由服务端 executor 钱包签名，不可覆盖。

只读查询（匿名可调）

| # | Tool | 参数 | 说明 | |---|---|---|---| | 16 | nft_getListing | listingId | 挂单详情 | | 17 | nft_getActiveListings | offset?, limit? | 活跃挂单（分页） | | 18 | nft_getOffer | listingId | 最佳报价 | | 19 | nft_getCollections | offset?, limit? | 全部合集 | | 20 | nft_getCollectionInfo | collectionAddress | 合集信息 | | 21 | nft_getTokenInfo | collectionAddress, tokenId | NFT 详情 | | 22 | nft_getBalance | collectionAddress, address | NFT 余额 | | 23 | nft_getStatus | address? | 链状态 + 市场统计 |

JSON-RPC 2.0 API

initialize

{ "jsonrpc": "2.0", "method": "initialize", "id": 1 }

tools/list

{ "jsonrpc": "2.0", "method": "tools/list", "id": 2 }

tools/call

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": { "name": "nft_getStatus", "arguments": { "address": "0x..." } },
  "id": 3
}

写工具示例（SIWE 会话模式带 signerKey）：

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "nft_listItem",
    "arguments": { "signerKey": "0x...", "nftContract": "0x...", "tokenId": "42", "priceWei": "1000000000000000000" }
  },
  "id": 4
}

GET /health

curl http://127.0.0.1:3300/health
# { "ok": true, "port": 3300, "tools": 23 }

环境变量

| 变量 | 必需 | 默认值 | 说明 | |---|---|---|---| | BRIDGE_MCP_PORT | 否 | 3300 | 监听端口 | | BRIDGE_MCP_TOKEN | 否 | "" | legacy 静态 Bearer token（存量客户端兼容） | | SIGNER_KEY | 否 | "" | legacy 模式默认签名私钥 | | ZENONFT_MASTER_KEY | 是* | "" | API Key 主密钥（加密 executor 私钥）；未设置时用 sha256(BRIDGE_MCP_TOKEN) 派生 | | ALLOWED_ADDRESSES | 否 | "" | 写接口地址白名单（逗号分隔；空 = 不限） | | ALLOWED_ORIGINS | 否 | * | 浏览器 CORS 来源（逗号分隔） | | SESSION_TTL_SECONDS | 否 | 86400 | SIWE 会话有效期（秒） | | CHALLENGE_TTL_SECONDS | 否 | 300 | challenge 有效期（秒） | | RATE_LIMIT_WRITE_MAX | 否 | 10 | 写操作每分钟上限 | | RATE_LIMIT_READ_MAX | 否 | 120 | 读操作每分钟上限 | | RATE_LIMIT_WINDOW_MS | 否 | 60000 | 限流窗口 | | ZENONFT_DATA_DIR | 否 | ./data | 数据目录（keys/sessions/challenges/audit.log） | | PINATA_JWT | 否 | 空 | Pinata JWT，用于 /ipfs/pin-file、/ipfs/pin-json 上传代理（仅存服务端） | | PINATA_API_URL | 否 | https://api.pinata.cloud | Pinata API 地址（默认即可） | | RATE_LIMIT_IPFS_MAX | 否 | 20 | IPFS 上传每分钟上限（按 IP） |

* 要使用 API Key 模式则必填；只跑 legacy 模式可不设。

安全说明

• executor 私钥以 AES-256-GCM 加密落盘（主密钥 ZENONFT_MASTER_KEY）。
• API Key 明文只返回一次（POST /keys），服务端仅存 sha256 哈希。
• 会话 token 服务端存储，吊销/过期即失效。
• 写操作按身份限流（默认 10/min）并写入 audit.log。

架构

┌──────────────┐     JSON-RPC 2.0 / REST     ┌──────────────────────────┐
│ Claude/Cursor│ ◄──────── HTTP ──────────► │  @zenonft/mcp (Express)   │
│ (AI Agent)    │                            │  ├─ Auth: APIKey/SIWE/legacy│
└──────────────┘                            │  ├─ 23 Tools              │
┌──────────────┐                            │  └─ @zenonft/sdk ──► RPC  │
│ 前端 API Keys│──── /auth /keys ──────────►│  data/ (keys/sessions)    │
└──────────────┘                            └──────────────────────────┘

本地开发

cd mcp
npm install --install-links
BRIDGE_MCP_PORT=3300 ZENONFT_MASTER_KEY=dev-secret npm start