┌──────────────────────────────────────────────┐
│   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                              │
└──────────────────────────────────────────────┘

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

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

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

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

# 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

{
  "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"
      }
    }
  }
}

{
  "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"
      }
    }
  }
}

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

{
  "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"
      }
    }
  }
}

{
  "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"
      }
    }
  }
}

{
  "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"
      }
    }
  }
}

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 }

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 }

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

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" }

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

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" }

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

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

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