国家MCP
为AI代理提供结构化工具，以与Algorand兼容网络上的ARC200令牌、ARC72 NFT、DEX掉期和NFT市场进行交互。
设置
npm install用法
Stdio（本地MCP客户端）
node index.jsHTTP（带x402支付门控的远程托管）
X402_AVM_PAY_TO=IR7EOSEN5S3L2HWHW6OXQW6CBG2I2N73VEGI3NXZLYPKZXAP3EUXG4EINU \
X402_AVM_PRICE=1000000 \
node serve.jsHTTP服务器在Streamable HTTP上公开MCP协议 /mcp （默认端口3000）。当 X402_AVM_PAY_TO 和 X402_AVM_PRICE 如果已设置，工具调用需要x402支付头。初始化和会话管理请求无需付款即可通过。
集 MCP_PORT 更改侦听端口。
HTTP与WAD计量计费
cp .env.example .env
# Edit .env with your treasury address and mnemonic
node serve-billed.js计费服务器使用WAD（Whale Asset Dollar，ARC-200代币）添加计量使用计费 47138068).代理通过钱包进行身份验证，内部跟踪使用情况，当累计使用量达到结算阈值时，在链上结算费用。
计费模式：
| 参数 | 默认值 | 说明 |
|---|---|---|
MIN_REQUIRED_BALANCE | 10 WAD | 要激活的最小WAD余额 |
MIN_REQUIRED_ALLOWANCE | 10 WAD | 财政部最低WAD津贴 |
SETTLEMENT_THRESHOLD | 1 WAD | 触发链上结算 |
MAX_UNPAID_USAGE | 2 WAD | 如果未支付，暂停代理 |
代理入职流程：
POST /auth/challenge随着{ "address": "" }→ 接收{ nonce, message }- 使用钱包的私钥对消息字节进行签名
POST /auth/verify随着{ "address", "nonce", "signature" }→ 接收{ token }- 连接到MCP
POST /mcp随着Authorization: Bearer
服务器在验证过程中检查WAD余额和容差。代理人必须通过ARC-200批准至少10 WAD的国库地址 approve.
终点：
| 端点 | 描述 |
|---|---|
POST /auth/challenge | 获取认证挑战随机数 |
POST /auth/verify | 验证钱包签名，激活代理 |
GET /agent/:address/status | 代理计费状态 |
GET /pricing | WAD中的工具定价 |
POST /mcp | MCP协议（流式HTTP） |
结算： 当累计使用量达到1WAD时，服务器调用 arc200_transferFrom 从代理人的钱包向国库收款。后台工作人员重试失败的结算，并在恢复余额/配额后取消暂停代理。
添加到客户端
添加到MCP客户端配置中（例如。 claude_desktop_config.json):
{
"mcpServers": {
"ulu-mcp": {
"command": "node",
"args": ["/absolute/path/to/UluMCP/index.js"]
}
}
}工具
ARC200令牌工具
| 工具 | 说明 |
|---|---|
arc200_list_tokens | 列出网络上的ARC200令牌（Mimir） |
arc200_balance_of | 返回地址的ARC200令牌余额 |
arc200_allowance | 将所有者授予消费者的支出津贴退还给消费者 |
arc200_transfers | 使用可选用户筛选器获取令牌传输历史记录 |
arc200_holders | 按余额（Mimir）排序的ARC200代币持有者列表 |
arc200_approvals | 获取令牌审批历史记录 |
ARC72 NFT工具
| 工具 | 说明 |
|---|---|
arc72_tokens | 按集合、所有者或令牌ID（Mimir）列出/搜索ARC72 NFT |
arc72_collections | 列出ARC72 NFT集合（Mimir） |
arc72_transfers | 获取ARC72 NFT传输历史记录（Mimir） |
HumbleSwap池工具
| 工具 | 说明 |
|---|---|
humble_pool_state | 返回池状态，包括令牌ID、储备和价格 |
humble_quote | 使用带费用的恒定产品公式估算掉期产出 |
HumbleSwap API工具
| 工具 | 说明 |
|---|---|
humble_protocol_stats | 全协议统计（TVL、24小时交易量、费用） |
humble_pools | 列出所有带有代币对和池ID的流动性池 |
humble_pool_details | 详细的池信息（储备、费用、协议余额、LP代币数据） |
humble_pool_analytics | 池分析，包括TVL和流动性深度 |
humble_tokens | 列出所有跟踪的令牌，包括名称、符号、小数和供应 |
humble_token_metadata | 丰富的代币元数据，包括市值 |
humble_token_price | 代币交易的所有池的当前价格数据 |
humble_price_history | 用于绘制趋势图的历史价格数据 |
humble_router | 查找两个令牌之间的所有交换路径（直接和多跳） |
humble_arbitrage | 检测跨池的套利机会 |
SnowballSwap聚合工具
| 工具 | 说明 |
|---|---|
snowball_quote | HumbleSwap和Nomadex之间的多池交换报价，带路由 |
snowball_pool | 详细的池信息（储备、费用、流动性） |
snowball_pools | 列出所有已配置的交换池 |
snowball_tokens | 列出所有支持的令牌及其元数据 |
enVoi命名服务工具
| 工具 | 说明 |
|---|---|
envoi_resolve_name | 将VOI地址解析为enVoi名称和配置文件元数据 |
envoi_resolve_address | 解析enVoi名称（例如。 shelly.voi)到其地址 |
envoi_resolve_token | 将enVoi令牌ID解析为名称、所有者和元数据 |
envoi_search | 搜索与模式匹配的enVoi名称 |
市场工具
| 工具 | 说明 |
|---|---|
mp_listings | 获取活跃的NFT市场列表（Mimir） |
mp_sales | 获取NFT市场销售历史（Mimir） |
mp_deletes | 获取已取消/删除的市场列表（Mimir） |
事务生成器工具
| 工具 | 说明 |
|---|---|
arc200_transfer_txn | 构建未签名的ARC-200代币转移交易 |
arc200_approve_txn | 构建未签名的ARC-200审批交易 |
arc200_transferFrom_txn | 构建未签名的ARC-200委托转账交易 |
arc72_transferFrom_txn | 构建未签名的ARC-72 NFT传输交易 |
humble_swap_txn | 构建未签名的HumbleSwap掉期交易（处理VOI包装） |
envoi_purchase_txn | 建立未签名的enVoi名称注册交易 |
aramid_bridge_txn | 构建未签名的Aramid Bridge交易（瞧↔ 阿尔戈兰德） |
payment_txn | 构建未签名的本地支付交易（VOI或ALGO） |
Algod工具
| 工具 | 说明 |
|---|---|
algod_send_raw_transactions | 将已签名的交易提交到网络（与algorand mcp兼容） |
x402支付工具
| 工具 | 说明 |
|---|---|
x402_pay_to | 按网络返回已配置的付款接收方地址 |
x402_check | 探测URL以发现其x402付款要求，而无需付款 |
支持的网络
algorand-mainnetvoi-mainnet
用环境变量覆盖端点：
ALGORAND_MAINNET_ALGOD_URL=https://your-node.example.com
ALGORAND_MAINNET_ALGOD_TOKEN=your-token
ALGORAND_MAINNET_INDEXER_URL=https://your-indexer.example.com
ALGORAND_MAINNET_INDEXER_TOKEN=your-token同样的模式也适用于其他网络(VOI_MAINNET_*).
模仿API
网络与 模仿API 支持（目前 voi-mainnet)将其用作ARC200、ARC72和市场工具的主要数据源。ARC200工具退回到在没有Mimir的网络上通过ulujs进行直接链上查询。
VOI_MAINNET_MIMIR_URL=https://voi-mainnet-mimirapi.nftnavigator.xyzSnowballSwap API
SnowballSwap聚合器提供跨HumbleSwap和Nomadex池的跨DEX路由。
SNOWBALL_API_URL=https://swap-api-iota.vercel.appAPI
这 跋 命名服务解析VOI名称和地址。
ENVOI_API_URL=https://api.envoi.shx402付款
这 x402 该协议支持按请求付费API。这 x402_check 该工具探测端点以发现支付要求。通过HTTP托管时(serve.js)，工具调用在x402付款后被屏蔽。
X402_AVM_PAY_TO=IR7EOSEN5S3L2HWHW6OXQW6CBG2I2N73VEGI3NXZLYPKZXAP3EUXG4EINU
X402_AVM_PRICE=1000000 # Price per request in base units (e.g. 1 VOI)
X402_AVM_ASSET=0 # Asset ID (default: 0 for native VOI)
X402_AVM_NETWORK=avm:voi-mainnet # Network identifier (default)
X402_EVM_PAY_TO=0xYourEvmAddress # EVM receiver (future)
X402_EVM_PRICE=10000 # EVM price in base units (future)当两者同时发生时，付款将被强制执行 PAY_TO 和 PRICE 为网络设置。没有有效请求的请求 PAYMENT-SIGNATURE 标题接收a 402 Payment Required 使用已接受的付款选项进行响应。
项目结构
UluMCP/
index.js # MCP server entry point (stdio)
serve.js # HTTP server entry point (x402 gated)
serve-billed.js # HTTP server with WAD metered billing
package.json
.env.example # Environment configuration template
config/
networks.js # Network configuration with env overrides
lib/
clients.js # Algod/Indexer client factory
mimir.js # Mimir API client
snowball.js # SnowballSwap API client
envoi.js # enVoi naming service client
x402.js # x402 payment client
billing/
config.js # Billing constants and WAD math
db.js # SQLite schema and queries
pricing.js # Tool cost registry
meter.js # Usage tracking and thresholds
settlement.js # On-chain WAD settlement
worker.js # Background settlement worker
auth/
auth.js # Wallet auth (challenge/verify/tokens)
chain/
wad.js # WAD ARC-200 token operations
test/
billing.test.js # Billing logic tests
tools/
arc200.js # ARC200 token tools
arc72.js # ARC72 NFT tools
swap200.js # HumbleSwap pool tools
snowball.js # SnowballSwap aggregator tools
envoi.js # enVoi naming service tools
marketplace.js # NFT marketplace tools
humble.js # HumbleSwap API tools
txns.js # Transaction builder tools
algod.js # Algod tools (send raw transactions)
x402.js # x402 payment tools