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)

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)

arc200_* (ulujs ARC-200)

arc72_* (ulujs ARC-72)

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).