AssetMCP

AssetMCP

stdio Model Context Protocol server for UluOS: normalized ASA, ARC-200, and ARC-72 reads plus unsigned transaction payloads on Algorand mainnet and Voi mainnet.

Signing and broadcasting are intentionally out of scope—use UluWalletMCP and UluBroadcastMCP (or your wallet) after fetching base64 txn groups from this service.

Service summary (for UluOS docs)

| Field | Value | |--------|--------| | Name | asset-mcp | | Transport | stdio | | Version | 0.1.0 | | Networks | algorand-mainnet, voi-mainnet | | Stack | @modelcontextprotocol/sdk, algosdk (ASA), ulujs → arccjs (ARC-200 / ARC-72 simulation) | | Output | JSON text content; BigInts as strings; binary as base64; txn builders return ordered transactions: string[] (base64 unsigned bytes) |

Setup

npm install
npm start
# or: node /absolute/path/to/AssetMCP/index.js

Node: >= 20.9 (required by ulujs).

Configuration

Defaults use Nodely free-tier Algod + Indexer endpoints (Algorand mainnet: .4160.nodely.dev; Voi mainnet: .voi.nodely.dev). No API key required. Override with environment variables:

Pattern: ASSET_MCP_<NETWORK>_<SUFFIX> where <NETWORK> is ALGORAND_MAINNET or VOI_MAINNET, and <SUFFIX> is one of:

• ALGOD_URL
• ALGOD_TOKEN
• INDEXER_URL
• INDEXER_TOKEN

Example:

export ASSET_MCP_ALGORAND_MAINNET_ALGOD_URL="https://..."
export ASSET_MCP_ALGORAND_MAINNET_ALGOD_TOKEN="..."

Response shape

Successful tool calls return JSON:

{
  "ok": true,
  "network": "algorand-mainnet",
  "standard": "asa",
  "method": "asa_get_asset",
  "assetId": 31566704,
  "data": { }
}

Transaction builders add txCount and put base64 unsigned transactions under data.transactions (array order is the signing order).

Errors:

{
  "ok": false,
  "error": {
    "code": "malformed_address",
    "message": "...",
    "details": null
  }
}

Tools (by namespace)

asa_* (algosdk / AVM)

| Tool | Purpose | |------|---------| | asa_get_asset | ASA params by ID | | asa_get_holding | One account’s balance / frozen flag for an ASA | | asa_search_holdings | Indexer: paginated holdings; optional assetId filter | | asa_transfer_txn | Unsigned axfer | | asa_optin_txn | Unsigned opt-in (0-amount self transfer) | | asa_closeout_txn | Unsigned transfer + closeRemainderTo (supply full amount) |

arc200_* (ulujs ARC-200)

| Tool | Purpose | |------|---------| | arc200_get_metadata | name, symbol, decimals, totalSupply | | arc200_balance_of | Balance (base units, string in JSON) | | arc200_allowance | Allowance | | arc200_has_balance | hasBalance (ulujs dual-ABI helper) | | arc200_has_allowance | hasAllowance (ulujs dual-ABI helper) | | arc200_get_events | getEvents → Transfer + Approval streams | | arc200_transfer_txn | Simulated transfer → unsigned txn group | | arc200_transfer_from_txn | Simulated transferFrom | | arc200_approve_txn | Simulated approve |

arc72_* (ulujs ARC-72)

| Tool | Purpose | |------|---------| | arc72_get_metadata | totalSupply; with tokenId: owner, tokenURI, approved; optional supportsInterface via interfaceSelectorHex | | arc72_owner_of | Owner | | arc72_balance_of | NFT count | | arc72_get_approved | Approved address for token | | arc72_is_approved_for_all | Operator flag | | arc72_token_uri | Token URI | | arc72_total_supply | Total supply | | arc72_get_events | Transfer / Approval / ApprovalForAll | | arc72_transfer_txn | transferFrom(from, to, tokenId) (signer must be authorized) | | arc72_approve_txn | Approve spender for tokenId | | arc72_set_approval_for_all_txn | setApprovalForAll via arccjs (ulujs wrapper is broken upstream) |

Cursor MCP config

This repo includes .cursor/mcp.json so asset-mcp is available when you open the repo as the workspace folder. Reload the window or restart Cursor after changing it.

To add manually or merge into another project:

{
  "mcpServers": {
    "asset-mcp": {
      "command": "node",
      "args": ["${workspaceFolder}/index.js"]
    }
  }
}

Machine-readable capabilities

See examples/capabilities.json.

Live demo: from the repo root, npm run demo (or node examples/demo.mjs) spawns the MCP server over stdio and calls asa_get_asset (Algorand USDC), arc200_get_metadata (Voi wVOI), and arc72_total_supply (sample ARC-72 collection).

Implementation notes

• stdout hygiene: ulujs / arccjs call console.log during simulation. Unless ASSET_MCP_DEBUG is set, console.log is redirected to stderr so MCP JSON-RPC on stdout stays valid.
• ARC txn bytes: Built by simulating with simulate: true and returning the unsigned group from arccjs (txns array). Extra group transactions (e.g. box / resource-sharing) may appear—sign the full ordered group.
• ARC-200 / ARC-72 reads: Use ulujs Contract with the public simulation sender (oneAddress from ulujs) for readonly ABI calls.
• Event filters: address is forwarded to the indexer as sender (arccjs API).
• ARC-72 setApprovalForAll: Implemented against contractInstance.arc72_setApprovalForAll because ulujs safe_arc72_setApprovalForAll references undefined variables (upstream bug).

License

MIT (see LICENSE).