UluCoreMCP

Low-level blockchain interface MCP server for Algorand and Voi networks.

Provides chain primitives: account/asset/app inspection, transaction search, block retrieval, TEAL compilation, and transaction simulation.

Setup

npm install

Usage

node index.js

Adding to a Client

{
  "mcpServers": {
    "ulu-core-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/UluCoreMCP/index.js"]
    }
  }
}

Supported Networks

Default endpoints use Nodely public APIs. Override via the ULU_CORE_NETWORKS environment variable:

{
  "algorand-mainnet": {
    "chain": "algorand",
    "algodUrl": "https://your-algod-url",
    "algodToken": "",
    "indexerUrl": "https://your-indexer-url",
    "indexerToken": ""
  }
}

Tools

Network

• get_network_status — Node status (last round, sync state)
• get_suggested_params — Suggested transaction parameters
• get_block — Block info by round number

Accounts / Assets / Apps

• get_account — Account info (balance, assets, auth address)
• get_asset — Asset info by ID
• get_application — Application info (global state, programs)
• get_application_boxes — List application boxes
• get_application_box — Get a specific box by name (base64)

Transactions

• get_transaction — Look up confirmed transaction by ID
• get_pending_transaction — Pending transaction info
• search_transactions — Search with filters (address, asset, app, round range, time range, type)
• get_transaction_group — All transactions in a group

Utilities

• decode_transaction — Decode unsigned transaction bytes to JSON
• decode_signed_transaction — Decode signed transaction bytes to JSON
• simulate_transactions — Simulate transactions without broadcasting
• compile_teal — Compile TEAL source to bytecode
• disassemble_teal — Disassemble TEAL bytecode to source

Architecture

index.js              MCP server + tool registration
lib/
  config.js           Network configuration loader
  errors.js           Error handling utilities
  networks.js         Algod/Indexer client manager
  algod.js            Algod wrapper functions
  indexer.js          Indexer wrapper functions
  normalize.js        Response normalization (BigInt → string, Uint8Array → base64)

Design

UluCoreMCP returns facts, not interpretation. Raw chain data is normalized for JSON safety (BigInts become strings, byte arrays become base64) but otherwise passed through unmodified.

Protocol-specific logic, ecosystem conventions, wallet management, and transaction signing belong to higher-layer MCPs.

Limitations

• Read-only: no signing, no broadcasting, no wallet management
• Algorand/Voi only (both use the same AVM client logic)
• Transaction group retrieval fetches all transactions in a round and filters by group ID
• Box names must be base64-encoded