@tronlink/mcp-server-tronlink

v0.1.1

Published

2 months ago

TronLink MCP Server - MCP server for controlling TronLink browser extension via AI agents

0High
0Medium
0Low

mcp-server-tronlink

TronLink MCP Server — a production-ready MCP server that enables AI agents (Claude, GPT, etc.) to interact with the TRON blockchain through natural language.

Built on @tronlink/tronlink-mcp-core, it provides two operation modes:

Playwright Mode — browser automation to control the TronLink Chrome extension UI (navigate, click, type, screenshot, etc.)
Direct API Mode — on-chain operations via TronGrid API, GasFree transfers, and multi-signature management — no browser required

Architecture

┌──────────────────────────────────────────────┐
│   AI Agent (Claude Desktop / Claude Code)    │
└──────────────────┬───────────────────────────┘
                   │ MCP Protocol (stdio)
┌──────────────────▼───────────────────────────┐
│  @tronlink/mcp-server-tronlink               │
│                                              │
│  ┌── Playwright Mode ─────────────────────┐  │
│  │  TronLinkSessionManager                │  │
│  │  ├── Browser launch & extension load   │  │
│  │  ├── Extension ID auto-detection       │  │
│  │  ├── Multi-tab tracking & role classify │  │
│  │  ├── State extraction (DOM analysis)   │  │
│  │  │   ├── TRON address (T-prefix, 34ch) │  │
│  │  │   ├── TRX balance                   │  │
│  │  │   ├── Network (Mainnet/Nile/Shasta) │  │
│  │  │   └── Screen detection (15 screens) │  │
│  │  └── Confirmation popup handling       │  │
│  └────────────────────────────────────────┘  │
│                                              │
│  ┌── Direct API Mode ─────────────────────┐  │
│  │  TronLinkOnChainCapability (14 tools)  │  │
│  │  ├── TRX/TRC20 transfer, swap, stake  │  │
│  │  ├── Account & resource queries       │  │
│  │  └── Multi-sig setup & signing        │  │
│  │                                        │  │
│  │  TronLinkGasFreeCapability (3 tools)   │  │
│  │  ├── Zero-gas TRC20 transfers         │  │
│  │  └── Account & transaction queries    │  │
│  │                                        │  │
│  │  TronLinkMultiSigCapability (5 tools)  │  │
│  │  ├── Permission queries               │  │
│  │  ├── Transaction submit & list        │  │
│  │  └── WebSocket real-time monitoring   │  │
│  └────────────────────────────────────────┘  │
│                    │ (uses)                   │
│  ┌─────────────────▼──────────────────────┐  │
│  │  @tronlink/tronlink-mcp-core               │  │
│  │  ├── MCP Server (stdio transport)      │  │
│  │  ├── 56+ tl_* tool handlers            │  │
│  │  ├── Knowledge Store                   │  │
│  │  └── Discovery Utils                   │  │
│  └────────────────────────────────────────┘  │
└──────────────────┬───────────────────────────┘
                   │ Playwright (Chromium)     ← only for Playwright mode
┌──────────────────▼───────────────────────────┐
│  Chrome Browser                              │
│  ├── TronLink Extension (MV3)                │
│  │   ├── popup.html#/home                    │
│  │   ├── popup.html#/login                   │
│  │   ├── popup.html#/settings                │
│  │   ├── popup.html#/transfer                │
│  │   └── secondary_popup.html (confirmations)│
│  └── DApp Pages                              │
└──────────────────────────────────────────────┘

Quick Start

Zero-Config Mode (Fastest)

Just configure TL_TRONGRID_URL. If no wallet exists, the server starts and shows two setup options instead of creating one immediately:

{
  "mcpServers": {
    "tronlink": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": ".",
      "env": {
        "TL_TRONGRID_URL": "https://nile.trongrid.io"
      }
    }
  }
}

Auto-create via MCP tool: call tl_wallet_create The server generates a random password, saves it to ~/.agent-wallet/runtime_secrets.json, creates an encrypted main wallet, and enables the running session to use it.
Manual CLI setup:
1. Create a wallet: agent-wallet start local_secure --generate --wallet-id main
2. Add AGENT_WALLET_PASSWORD to your .mcp.json env (must match the password used above)
3. Restart the MCP server

Manual Setup (Existing Wallet or CLI-First)

If you prefer to create a wallet yourself or use an existing one:

Create a wallet: agent-wallet start local_secure --generate --wallet-id main
Add AGENT_WALLET_PASSWORD to your .mcp.json env (must match the password used above)
Restart the MCP server

Once a wallet is configured (auto or manual), on-chain tools (tl_chain_*, tl_gasfree_*, tl_multisig_*) become available.

Playwright Setup

1. Build TronLink Extension (Playwright mode only)

cd /path/to/tronlink-extension-pro
npm install
npm run build
# Output: dist/

2. Install and Build MCP Server

cd /path/to/mcp-server-tronlink
npm install
npm run build

3. Create Wallet Locally (required for on-chain tools)

npm install -g @bankofai/agent-wallet
agent-wallet start local_secure --generate --wallet-id main

4. Configure MCP JSON

All configuration is injected via the env field in the MCP JSON. The server does not read .env files.

See the "Integration" section below. For variable reference, see .env.example.

Two Operation Modes

Playwright Mode — Browser Automation

Controls the TronLink Chrome extension through Playwright. Requires a built TronLink extension.

Use when you need to:

Automate wallet UI interactions (import wallet, navigate screens, click buttons)
Test DApp integrations (connect wallet, sign transactions via popup)
Take screenshots of wallet/DApp state
Run end-to-end tests against the TronLink UI

Tools (27): tl_launch, tl_cleanup, tl_navigate, tl_click, tl_type, tl_screenshot, tl_get_state, tl_describe_screen, tl_accessibility_snapshot, tl_list_testids, tl_switch_to_tab, tl_close_tab, tl_wait_for, tl_wait_for_notification, tl_scroll, tl_keyboard, tl_evaluate, tl_clipboard, tl_seed_contract, tl_seed_contracts, tl_get_contract_address, tl_list_contracts, tl_set_context, tl_get_context, tl_run_steps, tl_list_flows, tl_list_testids

Direct API Mode — On-Chain Operations

Calls TRON blockchain APIs directly using TronWeb-compatible REST calls and local cryptographic signing. No browser or extension required.

Use when you need to:

Query account balances, resources, and transaction history
Send TRX or TRC20 tokens programmatically
Stake/unstake TRX, delegate bandwidth/energy
Execute token swaps via SunSwap V2/V3
Manage multi-signature wallets and transactions
Send gas-free TRC20 transfers

Tool groups:

| Group | Tools | Required Config | |-------|-------|----------------| | On-Chain (14) | tl_chain_* | agent-wallet + TL_TRONGRID_URL | | MultiSig (5) | tl_multisig_* | TL_MULTISIG_BASE_URL + credentials | | GasFree (3) | tl_gasfree_* | TL_GASFREE_BASE_URL + API key |

Both modes can run simultaneously — configure what you need and the server enables the corresponding tools automatically.

Configuration

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | Playwright Mode | | | | TRONLINK_EXTENSION_PATH | TronLink extension build directory (containing manifest.json) | Auto-detected | | TRONLINK_SOURCE_PATH | TronLink extension source directory (enables Build capability) | — | | TL_MODE | Working mode: e2e (test) or prod (production) | prod | | TL_HEADLESS | Run browser in headless mode: true / false | false | | TL_SLOW_MO | Playwright slow-motion delay in ms (for debugging) | 0 | | TronGrid API | | | | TL_TRONGRID_URL | TronGrid full-node API URL | — | | TL_TRONGRID_API_KEY | TronGrid API Key (required for Mainnet, not needed for Nile/Shasta) | — | | Wallet (agent-wallet) | | | | AGENT_WALLET_PASSWORD | Encryption password (optional if using tl_wallet_create; required for manual or existing wallets) | Auto-generated by tl_wallet_create | | AGENT_WALLET_DIR | Custom wallet storage directory | ~/.agent-wallet | | TL_OWNER_WALLET_ID | Owner wallet ID for multisig signing | active wallet | | TL_COSIGNER_WALLET_ID | Co-signer wallet ID for multisig | — | | On-Chain | | | | TL_SUNSWAP_ROUTER | SunSwap V2 Router contract address | — | | TL_SUNSWAP_V3_ROUTER | SunSwap Smart Router (V3) contract address | — | | TL_WTRX_ADDRESS | WTRX contract address | Mainnet default | | Multi-Signature | | | | TL_MULTISIG_BASE_URL | Multi-sig service API URL | — | | TL_MULTISIG_SECRET_ID | Multi-sig service Secret ID | — | | TL_MULTISIG_SECRET_KEY | Multi-sig service Secret Key (HmacSHA256 signing key) | — | | TL_MULTISIG_CHANNEL | Multi-sig service channel name | — | | GasFree | | | | TL_GASFREE_BASE_URL | GasFree service URL | — | | TL_GASFREE_API_KEY | GasFree API Key | — | | TL_GASFREE_API_SECRET | GasFree API Secret | — |

Configuring multisig env vars (BASE_URL + SECRET_ID + SECRET_KEY + CHANNEL) auto-enables the tl_multisig_* tools.
Configuring agent-wallet + TL_TRONGRID_URL enables the tl_chain_* on-chain tool group (14 tools).
Configuring TL_GASFREE_BASE_URL + TL_GASFREE_API_KEY enables the tl_gasfree_* gas-free transfer tool group (3 tools).
Security: Private keys are managed by @bankofai/agent-wallet with encrypted local storage (local_secure). Plain-text keys in env vars are not supported. If no wallet exists at startup, the server shows two paths: call tl_wallet_create to auto-generate one (password saved to ~/.agent-wallet/runtime_secrets.json), or create one manually via CLI and set AGENT_WALLET_PASSWORD.

API Key Acquisition Guide

TronGrid API Key (required for on-chain operations)

Used by all tl_chain_* tools (balance queries, transfers, staking, swaps, etc.)

| Item | Details | |------|---------| | Portal | https://www.trongrid.io/ | | Cost | Free (100,000 requests/day); paid plans available | | Testnet | Nile/Shasta do not require an API Key | | Mainnet | API Key is required |

Steps:

Visit https://www.trongrid.io/ → click Sign Up
Register with email and verify
Go to Dashboard → Create API Key
Enter project name → generate key
Copy the API Key into TL_TRONGRID_API_KEY

GasFree API Key (gas-free TRC20 transfers)

Used by tl_gasfree_* tools — TRC20 token transfers where gas fees are paid by the service provider

| Item | Details | |------|---------| | Developer Center | https://developer.gasfree.io/ | | API Spec | https://gasfree.io/specification | | SDK | npm install @gasfree/gasfree-sdk (GitHub) | | Testnet URL | https://open-test.gasfree.io/nile/ | | Mainnet URL | https://open.gasfree.io/tron/ |

Steps:

Visit https://developer.gasfree.io → register a developer account
Create an application → system generates API Key and API Secret
Fill in TL_GASFREE_API_KEY and TL_GASFREE_API_SECRET
Note: Nile testnet also requires a key, but approval is fast

SunSwap Smart Router Address (DEX trading)

Used by tl_chain_swap_v3 — token swaps via SunSwap V3 concentrated liquidity

| Network | Smart Router Address | Source | |---------|---------------------|--------| | Mainnet | TCFNp179Lg46D16zKoumd4Poa2WFFdtqYj | SUN.io Docs | | Nile | TB6xBCixqRPUSKiXb45ky1GhChFJ7qrfFj | Same |

No application needed — just set the address in TL_SUNSWAP_V3_ROUTER.

The Smart Router is SunSwap's unified entry point that automatically selects the optimal route across V1/V2/V3/PSM/SunCurve pools.

WTRX Contract Address

Used for TRX ↔ Token swaps (Wrapped TRX)

| Network | WTRX Address | |---------|-------------| | Mainnet | TNUC9Qb1rRpS5CbWLmNMxXBjyFoydXjWFR (default, no manual config needed) | | Nile | Query via SunSwap Router's WETH() method |

No configuration needed for Mainnet (uses default). For Nile testnet, query the address and set TL_WTRX_ADDRESS.

Multi-Signature Service Credentials

Used by tl_multisig_* tools — permission queries, transaction submission, real-time monitoring

| Item | Details | |------|---------| | Nile Testnet | https://apinile.walletadapter.org | | Mainnet | https://api.walletadapter.org | | Test Credentials | SECRET_ID=TEST / SECRET_KEY=TESTTESTTEST / CHANNEL=test |

Testnet works out of the box with the test credentials above.

Production: Contact the TronLink team for official credentials.

Wallet Setup (Optional — auto-created if not configured)

If no wallet exists, the server will prompt you to choose one of two paths:

Auto-create in the current MCP session: call tl_wallet_create
Manual CLI setup: create the wallet yourself, then set AGENT_WALLET_PASSWORD and restart

Manual CLI commands:

# 1. Install agent-wallet CLI
npm install -g @bankofai/agent-wallet

# 2. Create an encrypted wallet
agent-wallet start local_secure --generate --wallet-id main

# 3. (Optional) Create a cosigner wallet for multisig
agent-wallet start local_secure --generate --wallet-id cosigner

You can also manage wallets at runtime via MCP tools: tl_wallet_list, tl_wallet_create, tl_wallet_set_active.

Quick Config Reference (Nile Testnet .mcp.json)

{
  "mcpServers": {
    "tronlink": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": ".",
      "env": {
        "TRONLINK_EXTENSION_PATH": "/path/to/tronlink-extension/dist",
        "TL_MODE": "prod",
        "TL_HEADLESS": "false",
        "TL_TRONGRID_URL": "https://nile.trongrid.io",
        "AGENT_WALLET_PASSWORD": "your-wallet-password",
        "TL_SUNSWAP_ROUTER": "TKzxdSv2FZKQrEqkKVgp5DcwEXBEKMg2Ax",
        "TL_SUNSWAP_V3_ROUTER": "TB6xBCixqRPUSKiXb45ky1GhChFJ7qrfFj",
        "TL_MULTISIG_BASE_URL": "https://apinile.walletadapter.org",
        "TL_MULTISIG_SECRET_ID": "TEST",
        "TL_MULTISIG_SECRET_KEY": "TESTTESTTEST",
        "TL_MULTISIG_CHANNEL": "test",
        "TL_GASFREE_BASE_URL": "https://open-test.gasfree.io/nile/",
        "TL_GASFREE_API_KEY": "your_gasfree_api_key",
        "TL_GASFREE_API_SECRET": "your_gasfree_api_secret"
      }
    }
  }
}

Testnet TRX faucet: https://nileex.io/join/getJoinPage

API-Only Config (no Playwright, no browser)

If you only need direct API tools (on-chain, multisig, gasfree) without browser automation, you can omit TRONLINK_EXTENSION_PATH:

{
  "mcpServers": {
    "tronlink": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": ".",
      "env": {
        "TL_TRONGRID_URL": "https://nile.trongrid.io",
        "AGENT_WALLET_PASSWORD": "your-wallet-password",
        "TL_MULTISIG_BASE_URL": "https://apinile.walletadapter.org",
        "TL_MULTISIG_SECRET_ID": "TEST",
        "TL_MULTISIG_SECRET_KEY": "TESTTESTTEST",
        "TL_MULTISIG_CHANNEL": "test",
        "TL_GASFREE_BASE_URL": "https://open-test.gasfree.io/nile/",
        "TL_GASFREE_API_KEY": "your_gasfree_api_key",
        "TL_GASFREE_API_SECRET": "your_gasfree_api_secret"
      }
    }
  }
}

This configuration enables API tools (including 3 wallet management tools) without launching a browser. Playwright-based tools (tl_launch, tl_click, etc.) will not be available. If AGENT_WALLET_PASSWORD is omitted, startup will prompt you to choose either tl_wallet_create or manual CLI setup.

Extension Path Auto-Detection

If TRONLINK_EXTENSION_PATH is not set, the server searches these locations:

./dist
./dist/prd
../tronlink-extension-pro/dist
../tronlink-extension-pro/dist/prd

Condition: directory contains a manifest.json file.

Integration

Option 1: Project-Level `.mcp.json` (Recommended)

The project includes a .mcp.json file. Claude Code auto-detects it. Fill in your credentials. If no wallet exists yet, either call tl_wallet_create after startup, or create the wallet locally first and set AGENT_WALLET_PASSWORD:

# .mcp.json already exists, edit directly
# Fill in TL_MULTISIG_SECRET_ID / SECRET_KEY / CHANNEL etc.
# If you want the manual wallet path, also add AGENT_WALLET_PASSWORD after creating the wallet locally

.mcp.json example:

{
  "mcpServers": {
    "tronlink": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": ".",
      "env": {
        "TRONLINK_EXTENSION_PATH": "../tronlink-extension-pro/dist",
        "TL_MODE": "prod",
        "TL_HEADLESS": "false",
        "TL_SLOW_MO": "0",
        "TL_TRONGRID_URL": "https://nile.trongrid.io",
        "AGENT_WALLET_PASSWORD": "your-wallet-password",
        "TL_TRONGRID_API_KEY": "",
        "TL_MULTISIG_BASE_URL": "https://apinile.walletadapter.org",
        "TL_MULTISIG_SECRET_ID": "your-secret-id",
        "TL_MULTISIG_SECRET_KEY": "your-secret-key",
        "TL_MULTISIG_CHANNEL": "your-channel"
      }
    }
  }
}

.mcp.json is in .gitignore and will not be committed.

Option 2: Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "tronlink": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-tronlink/dist/index.js"],
      "env": {
        "TRONLINK_EXTENSION_PATH": "/absolute/path/to/tronlink-extension-pro/dist",
        "TL_TRONGRID_URL": "https://nile.trongrid.io",
        "AGENT_WALLET_PASSWORD": "your-wallet-password",
        "TL_MULTISIG_BASE_URL": "https://apinile.walletadapter.org",
        "TL_MULTISIG_SECRET_ID": "your-secret-id",
        "TL_MULTISIG_SECRET_KEY": "your-secret-key",
        "TL_MULTISIG_CHANNEL": "your-channel"
      }
    }
  }
}

Option 3: Claude Code Global Settings

Edit ~/.claude/settings.json or project-level .claude/settings.json:

{
  "mcpServers": {
    "tronlink": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-tronlink/dist/index.js"],
      "env": {
        "TRONLINK_EXTENSION_PATH": "/absolute/path/to/tronlink-extension-pro/dist",
        "TL_TRONGRID_URL": "https://nile.trongrid.io",
        "AGENT_WALLET_PASSWORD": "your-wallet-password"
      }
    }
  }
}

Other MCP Clients

Any client supporting the MCP protocol (stdio transport) can connect. The server communicates via stdin/stdout and handles tools/list and tools/call requests.

Usage Examples

Example 1: Direct API — Query Account and Send TRX

User: What is the balance of my account, and send 10 TRX to TAbCdEf...

AI executes:
1. tl_chain_get_address()
   → { address: "TVGcWWdJn9EnJP1LHCJDQaVCEcGsapKrVF" }

2. tl_chain_get_account({ address: "TVGcWWdJn9EnJP1LHCJDQaVCEcGsapKrVF" })
   → { balance_trx: "100.5", bandwidth: 600, energy: 0, ... }

3. tl_chain_send({ to: "TAbCdEf...", amount: "10" })
   → { txId: "abc123...", success: true }

Example 2: Direct API — Stake TRX and Delegate Energy

User: Stake 100 TRX for energy, then delegate energy to TAbCdEf...

AI executes:
1. tl_chain_stake({ action: "freeze", amount_trx: 100, resource: "ENERGY" })
   → { txId: "...", success: true }

2. tl_chain_resource({
     action: "delegate",
     resource: "ENERGY",
     amount_trx: 50,
     receiver: "TAbCdEf..."
   })
   → { txId: "...", success: true }

Example 3: Direct API — Token Swap via SunSwap

User: Swap 10 TRX for USDT

AI executes:
1. tl_chain_swap_v3({
     from_token: "TRX",
     to_token: "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
     amount: "10",
     slippage: 1
   })
   → { txId: "...", amountOut: "1.52", ... }

Example 4: Direct API — GasFree Transfer

User: Send 10 USDT to TAbCdEf... without paying gas

AI executes:
1. tl_gasfree_get_account({ address: "TVGcWWdJn9..." })
   → { eligible: true, daily_quota_remaining: 3, supported_tokens: [...] }

2. tl_gasfree_send({
     to: "TAbCdEf...",
     contract_address: "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
     amount: "10"
   })
   → { txId: "...", success: true, gas_paid_by: "gasfree" }

Example 5: Direct API — Multi-Signature Workflow

User: Check my multisig permissions and submit a transaction

AI executes:
1. tl_multisig_query_auth({ address: "TXz9dfkjui6..." })
   → { permissions: [{ owner_address: "TDqGdq76...",
       active_permissions: [{ threshold: 66, weight: 35 }] }] }

2. tl_multisig_list_tx({ address: "TXz9dfkjui6...", state: 0 })
   → { total: 3, transactions: [{ hash: "18213ab5...",
       threshold: 3, currentWeight: 2, stateText: "processing" }] }

3. tl_multisig_submit_tx({
     address: "TXz9dfkjui6...",
     function_selector: "transfer(address,uint256)",
     transaction: { raw_data: {...}, signature: ["659143f5..."] }
   })
   → { success: true, code: 0, message: "OK" }

4. tl_multisig_connect_ws({ address: "TXz9dfkjui6..." })
   → { connected: true }  // real-time pending tx notifications

Example 6: Playwright — Launch Wallet and Check State

User: Launch TronLink and show me the wallet state

AI executes:
1. tl_launch({ fixture: "default" })
   → { sessionId: "tl-1741504523", extensionId: "abc...", extensionUrl: "chrome-extension://..." }

2. tl_get_state()
   → { currentScreen: "home", isUnlocked: true, accountAddress: "TXyz...",
       networkName: "Mainnet", balanceTrx: "100.5" }

Example 7: Playwright — DApp Interaction

User: Open SunSwap and connect wallet

AI executes:
1. tl_launch({ fixture: "default" })
2. tl_navigate({ target: "url", url: "https://sunswap.com" })
3. tl_click({ selector: ".connect-wallet-btn" })
4. tl_wait_for_notification({ timeout: 30000 })
5. tl_switch_to_tab({ role: "notification" })
6. tl_describe_screen()
7. tl_click({ a11yRef: "e3" })        // approve connection
8. tl_switch_to_tab({ role: "dapp" })
9. tl_screenshot()

Multi-Signature Guide

Network Reference

| Network | TronGrid URL | Multi-Sig Service URL | API Key | |---------|-------------|----------------------|---------| | Nile Testnet | https://nile.trongrid.io | https://apinile.walletadapter.org | Not needed | | Shasta Testnet | https://api.shasta.trongrid.io | — | Not needed | | Mainnet | https://api.trongrid.io | https://api.walletadapter.org | Required |

Testnet TRX faucet: https://nileex.io/join/getJoinPage

TRON Multi-Sig Permission Model

TRON accounts have three permission levels:

| Permission | ID | Description | |------------|-----|-------------| | owner | 0 | Highest level — can modify all permissions and execute all contracts | | witness | 1 | Super representative only (block production) | | active | 2+ | Custom permissions — configurable allowed contract types (up to 8) |

Each permission contains:

threshold: Minimum cumulative weight required to execute
keys: Signer list [{address, weight}] (up to 5 per permission)
operations: 32-byte hex bitmask defining allowed contract types (active only)

Multi-Sig Fees

accountPermissionUpdate: 100 TRX
Each multi-sig transaction: additional 1 TRX

Multi-Sig Complete Flow

1. Setup multi-sig permissions (accountPermissionUpdate)
   ├── Define owner permission (recommended: keep threshold=1 for recovery)
   └── Define active permission (e.g., threshold=2, two signers each weight=1)

2. Create multi-sig transaction (with Permission_id=2)
   └── Transaction specifies active permission

3. Collect signatures
   ├── Signer A signs → submit to multi-sig service
   └── Signer B signs → submit to multi-sig service

4. Auto-broadcast when threshold reached
   └── Service checks currentWeight >= threshold → broadcast

Built-in Multi-Sig Flow Recipes

View with tl_list_flows:

| Flow ID | Description | |---------|-------------| | multisig_query_auth | Query address multi-sig permissions (owner/active, thresholds, weights) | | multisig_list_transactions | List multi-sig transactions (filter by status: pending/success/failed) | | multisig_monitor | WebSocket real-time monitoring + list current pending transactions | | multisig_stop_monitor | Disconnect WebSocket monitoring | | multisig_submit_tx | Submit signed transaction to multi-sig service (auto-broadcast on threshold) | | multisig_check | Full status check: permissions → pending txs → unsigned txs |

Security Recommendations

Keep owner threshold=1: When setting up multi-sig, keep the owner permission as single-sig (threshold=1) so you can always recover if active signers are unavailable
Test on testnet first: Thoroughly test on Nile testnet before operating on Mainnet
Key safety: Private keys are encrypted via @bankofai/agent-wallet (local_secure type). Plain-text keys in env vars are not supported. If you use tl_wallet_create, the password is saved to ~/.agent-wallet/runtime_secrets.json; if you use the manual path, set AGENT_WALLET_PASSWORD yourself. Do not delete runtime_secrets.json — it is required to decrypt existing auto-created wallets
Transaction expiration: Unsigned transactions expire in ~60 seconds — collect all signatures before expiration

All Available Tools

The server exposes 55+ tools via MCP protocol. Tools are grouped by mode:

Playwright Mode Tools

Session Management: tl_launch / tl_cleanup

State & Discovery: tl_get_state / tl_describe_screen / tl_list_testids / tl_accessibility_snapshot

Navigation: tl_navigate / tl_switch_to_tab / tl_close_tab / tl_wait_for_notification

UI Interaction: tl_click / tl_type / tl_wait_for / tl_scroll / tl_keyboard / tl_evaluate

Screenshot & Clipboard: tl_screenshot / tl_clipboard

Contract Seeding (e2e): tl_seed_contract / tl_seed_contracts / tl_get_contract_address / tl_list_contracts

Context: tl_set_context / tl_get_context

Knowledge Store: tl_knowledge_last / tl_knowledge_search / tl_knowledge_summarize / tl_knowledge_sessions

Batch: tl_run_steps

Flow Recipes: tl_list_flows (32 built-in recipes with pre-checks)

Wallet Management Tools

| Tool | Description | |------|-------------| | tl_wallet_list | List all wallets with IDs, types, active status, and TRON addresses | | tl_wallet_create | Auto-generate an encrypted wallet and attach it to the running MCP session | | tl_wallet_set_active | Switch the active wallet by ID (hot-swaps into all capabilities) |

Direct API Tools

On-Chain (requires agent-wallet + TL_TRONGRID_URL):

| Tool | Description | |------|-------------| | tl_chain_get_address | Get TRON address from encrypted agent-wallet | | tl_chain_get_account | Query account: TRX balance, bandwidth, energy, permissions | | tl_chain_get_tokens | Query TRC10 + TRC20 token balances | | tl_chain_send | Send TRX, TRC10, or TRC20 tokens | | tl_chain_get_tx | Get transaction details by txID | | tl_chain_get_history | Query transaction history with pagination | | tl_chain_stake | Freeze/unfreeze TRX for bandwidth or energy (Stake 2.0) | | tl_chain_get_staking | Query staking status: frozen amounts, votes, pending unfreezing | | tl_chain_resource | Delegate/undelegate bandwidth or energy resources | | tl_chain_swap | Estimate or execute token swap via SunSwap V2 | | tl_chain_swap_v3 | Execute token swap via SunSwap V3 Smart Router | | tl_chain_setup_multisig | Configure multi-sig permissions (accountPermissionUpdate) | | tl_chain_create_multisig_tx | Create unsigned multi-sig transaction with permission ID | | tl_chain_sign_multisig_tx | Sign multi-sig transaction with owner or co-signer wallet |

Multi-Signature (requires multisig service config):

| Tool | Description | |------|-------------| | tl_multisig_query_auth | Query address multi-sig permissions (thresholds, weights) | | tl_multisig_submit_tx | Submit signed transaction (auto-broadcast on threshold) | | tl_multisig_list_tx | Query transaction history (pending/success/failed, signature progress) | | tl_multisig_connect_ws | Connect WebSocket for real-time pending tx notifications | | tl_multisig_disconnect_ws | Disconnect WebSocket listener |

GasFree (requires TL_GASFREE_BASE_URL + API key):

| Tool | Description | |------|-------------| | tl_gasfree_get_account | Query account eligibility, supported tokens, daily quota | | tl_gasfree_get_transactions | Query gas-free transaction history with pagination | | tl_gasfree_send | Send TRC20 token with zero gas fee |

Pre-Check Mechanism

All transaction tools automatically perform safety checks before execution:

| Operation | Pre-Check | |-----------|-----------| | Send TRX | Verify sufficient TRX balance | | Send TRC20 | Verify sufficient token balance | | Stake TRX | Verify available TRX balance | | Unstake TRX | Verify sufficient staked amount | | Delegate resource | Verify sufficient frozen resources | | Reclaim delegation | Verify active resource delegation exists | | Setup multi-sig | Verify TRX balance >= 100 TRX | | Create multi-sig tx | Verify multi-sig permissions configured | | Swap (V2/V3) | Verify sufficient source token balance | | GasFree send | Verify eligibility, token support, daily quota, token balance |

Core Components

TronLinkSessionManager (Playwright Mode)

Full implementation of the ISessionManager interface:

| Feature | Details | |---------|---------| | Browser launch | Playwright Chromium with --load-extension for TronLink | | Extension ID resolution | Auto-extract 32-char ID from chrome-extension:// URL or Service Worker | | Extension readiness | Wait for React mount on #root, confirm non-empty DOM | | Screen detection | URL hash-based detection for 15 TronLink screens | | State extraction | DOM analysis for TRON address (T-prefix, 34 chars), TRX balance, network | | Tab tracking | Auto-classify page roles: extension / notification / dapp / other | | Confirmation handling | Poll + waitForEvent('page') for secondary_popup detection | | Safe cleanup | Sequentially close Fixture, Chain, MockServer, then browser |

TronLinkOnChainCapability (Direct API Mode)

| Feature | Details | |---------|---------| | API calls | Direct REST calls to TronGrid full-node API | | Signing | Encrypted wallet signing via @bankofai/agent-wallet | | Address derivation | Resolved from encrypted wallet | | Supported operations | Transfer, stake, delegate, swap (V2/V3), multisig setup/create/sign | | Pre-checks | Balance and permission validation before every transaction |

TronLinkGasFreeCapability (Direct API Mode)

| Feature | Details | |---------|---------| | API calls | GasFree REST API for zero-gas TRC20 transfers | | Eligibility check | Validates account, token support, and daily quota before sending | | Signing | Encrypted wallet signing via @bankofai/agent-wallet for GasFree authorization |

TronLinkMultiSigCapability (Direct API Mode)

| Feature | Details | |---------|---------| | Permission query | REST call to /multi/auth for owner/active permission data | | Transaction submit | REST call to /multi/transaction with signed transaction payload | | Transaction list | REST call to /multi/list with pagination and status filtering | | WebSocket | Real-time /multi/socket connection for pending tx notifications | | Auth signing | Auto-generated HmacSHA256 API signature (sign_version=v1) |

TronLinkBuildCapability

| Feature | Details | |---------|---------| | Build command | Calls TronLink project's npm run build / build:prd:chrome / build:mv2 | | Build detection | Checks output directory for manifest.json | | Timeout | 5 minutes |

TronLinkStateSnapshotCapability

| Feature | Details | |---------|---------| | Screen detection | URL hash matching + password input fallback | | Address extraction | Regex match T[A-Za-z1-9]{33} | | Balance extraction | Regex match [\d,.]+\s*TRX | | Network detection | DOM scan for Mainnet / Nile / Shasta / Testnet keywords |

Project Structure

mcp-server-tronlink/
├── src/
│   ├── index.ts                    # Entry: parse config, register capabilities, start server
│   ├── wallet.ts                   # Unified wallet entry (agent-wallet, encrypted-only, guided auto-create)
│   ├── wallet-tools.ts             # MCP wallet management tools (list, create, switch)
│   ├── session-manager.ts          # TronLinkSessionManager (full ISessionManager implementation)
│   ├── capabilities/
│   │   ├── build.ts                # TronLinkBuildCapability (webpack build)
│   │   ├── state-snapshot.ts       # TronLinkStateSnapshotCapability (UI state extraction)
│   │   ├── multisig.ts             # TronLinkMultiSigCapability (multi-sig REST + WebSocket)
│   │   ├── on-chain.ts             # TronLinkOnChainCapability (14 on-chain operations)
│   │   ├── gasfree.ts              # TronLinkGasFreeCapability (gas-free transfers)
│   │   └── tron-crypto.ts          # TRON crypto utils (address derivation, signing, Base58)
│   └── flows/
│       ├── index.ts                # Flow registration entry (32 built-in recipes)
│       ├── import-wallet.ts        # Import wallet flow (disabled — violates encrypted-only policy)
│       ├── switch-network.ts       # Switch network / enable testnet
│       ├── transfer-trx.ts         # TRX / TRC20 transfer flows
│       ├── multisig.ts             # Multi-sig flows (6 recipes)
│       ├── onchain.ts              # On-chain flows (11 recipes with pre-checks)
│       └── gasfree.ts              # GasFree flows (3 recipes)
├── .env.example                    # Environment variable reference (documentation only)
├── package.json
├── tsconfig.json
└── README.md

Current Limitations

Chrome extension only: Currently supports Chrome desktop TronLink extension; mobile support planned
DOM dependency: State extraction relies on TronLink UI DOM structure; UI refactors may require adaptation
No data-testid: TronLink extension does not use data-testid attributes; relies on accessibility tree and CSS selectors
Headed mode recommended: Chrome extensions may have compatibility issues in headless mode

Requirements

Node.js >= 20
Playwright >= 1.49 (with Chromium) — only needed for Playwright mode
Built TronLink extension (dist/ with manifest.json) — only needed for Playwright mode