@tronlink/mcp-server-tronlink

v0.1.0

Published

11 days 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

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. 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_* | TL_CHAIN_PRIVATE_KEY + 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) | — | | On-Chain | | | | TL_CHAIN_PRIVATE_KEY | Signing private key (64-char hex, testnet only!) | — | | 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 | — | | TL_MULTISIG_OWNER_KEY | Multi-sig owner private key (64-char hex, testnet only!) | — | | TL_MULTISIG_COSIGNER_KEY | Co-signer private key (64-char hex, testnet only!) | — | | 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 TL_CHAIN_PRIVATE_KEY + 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 Warning: TL_CHAIN_PRIVATE_KEY, TL_MULTISIG_OWNER_KEY, and TL_MULTISIG_COSIGNER_KEY are intended for Nile/Shasta testnet automation only. Never use mainnet private keys!

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.

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",
        "TL_CHAIN_PRIVATE_KEY": "your_64_hex_private_key",
        "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",
        "TL_CHAIN_PRIVATE_KEY": "your_64_hex_private_key",
        "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 22 API tools without launching a browser. Playwright-based tools (tl_launch, tl_click, etc.) will not be available.

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. Just fill in your credentials:

# .mcp.json already exists, edit directly
# Fill in TL_MULTISIG_SECRET_ID / SECRET_KEY / CHANNEL etc.

.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",
        "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",
        "TL_MULTISIG_OWNER_KEY": "",
        "TL_MULTISIG_COSIGNER_KEY": ""
      }
    }
  }
}

.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",
        "TL_CHAIN_PRIVATE_KEY": "your_private_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"
      }
    }
  }
}

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",
        "TL_CHAIN_PRIVATE_KEY": "your_private_key"
      }
    }
  }
}

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_trx: "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({ 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...",
     token: "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
Private key safety: TL_MULTISIG_OWNER_KEY and TL_MULTISIG_COSIGNER_KEY are for testnet automation only — injected via MCP JSON env field (.mcp.json is in .gitignore). Never commit to version control
Transaction expiration: Unsigned transactions expire in ~60 seconds — collect all signatures before expiration

All Available Tools

The server exposes 56+ 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)

Direct API Tools

On-Chain (requires TL_CHAIN_PRIVATE_KEY + TL_TRONGRID_URL):

| Tool | Description | |------|-------------| | tl_chain_get_address | Derive TRON address from configured private key | | 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 key |

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 | Local transaction signing via @noble/curves (secp256k1) | | Address derivation | Private key → public key → Keccak256 → Base58Check | | 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 | Local EIP-712 compatible signing 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
│   ├── 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
│       ├── 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