TronLink MCP Core Library — the foundational framework for building TronLink MCP servers.
Provides the MCP protocol layer, 56+ tool definitions, session manager interface (ISessionManager), cross-session knowledge store, and an extensible capability system. This is a core package — it does not run standalone. Consumers must implement ISessionManager to inject TronLink extension logic.
The library supports two operation modes:
- Playwright Mode — browser automation tools for controlling the TronLink Chrome extension UI
- Direct API Mode — on-chain operations, multi-signature management, and gas-free transfers via direct API calls (no browser required)
┌──────────────────────────────────────┐
│ AI Agent (Claude, GPT, etc.) │
└──────────────────┬───────────────────┘
│ MCP Protocol (stdio / JSON-RPC 2.0)
┌──────────────────▼───────────────────┐
│ MCP Server Instance │
│ (created by createMcpServer()) │
│ ┌─────────────────────────────────┐ │
│ │ 56+ tl_* tools │ │
│ │ ├─ Session (launch/cleanup) │ │
│ │ ├─ State & Discovery │ │
│ │ ├─ Navigation & Tabs │ │
│ │ ├─ UI Interaction │ │
│ │ ├─ Screenshot & Clipboard │ │
│ │ ├─ Contract Seeding (e2e) │ │
│ │ ├─ Knowledge Store │ │
│ │ ├─ On-Chain (14 tools) ←─ Direct API │ │
│ │ ├─ Multi-Sig (5 tools) ←─ Direct API │ │
│ │ ├─ GasFree (3 tools) ←─ Direct API │ │
│ │ └─ Batch (run_steps) │ │
│ └─────────────────────────────────┘ │
│ ┌─────────────────────────────────┐ │
│ │ ISessionManager (interface) │ │
│ │ Consumer must implement this │ │
│ └─────────────────────────────────┘ │
│ ┌─────────────────────────────────┐ │
│ │ KnowledgeStore │ │
│ │ Disk-persistent, cross-session │ │
│ └─────────────────────────────────┘ │
└──────────────────┬───────────────────┘
│ Playwright (optional, for UI tools)
┌──────────────────▼───────────────────┐
│ Chrome + TronLink Extension │
└──────────────────────────────────────┘
npm install @tronlink/mcp-coreimport {
createMcpServer,
setSessionManager,
type ISessionManager,
} from '@tronlink/mcp-core';
// 1. Implement the ISessionManager interface (consumer provides concrete logic)
class MyTronLinkSessionManager implements ISessionManager {
// Session lifecycle
hasActiveSession() { ... }
launch(input) { ... }
cleanup() { ... }
// Page management
getPage() { ... }
getTrackedPages() { ... }
// Extension state
getExtensionState() { ... }
// Navigation
navigateToHome() { ... }
navigateToSettings() { ... }
// ... see full method list below
}
// 2. Register the SessionManager
setSessionManager(new MyTronLinkSessionManager());
// 3. Create and start the MCP server
const server = createMcpServer({
name: 'TronLink MCP Server',
version: '1.0.0',
});
await server.start(); // Listens for MCP requests via stdio- stdio transport implementing the MCP protocol (AI Agent ↔ Server, JSON-RPC 2.0)
createMcpServer(config)factory to create server instances- Supports e2e (test) and prod (production) modes
- Standardized tool response format: each response includes
ok(success/failure),result/error, andmeta(timestamp, sessionId, durationMs)
// Success response
{
ok: true,
result: { currentScreen: "home", accountAddress: "TXyz...", balanceTrx: "100" },
meta: { timestamp: "2026-03-09T10:15:23.456Z", sessionId: "tl-1741504523", durationMs: 234 }
}
// Error response
{
ok: false,
error: { code: "TL_CLICK_FAILED", message: "Element not found", details: {...} },
meta: { timestamp: "...", durationMs: 120 }
}| Tool | Description |
|---|---|
tl_launch |
Launch Chrome with TronLink extension (default: headed mode) |
tl_cleanup |
Safely close browser and all services (chain node, fixture server, mock server) |
Fixture presets:
default— unlocked wallet with TRX balanceonboarding— fresh install state (create/import wallet flow)- Custom — pass custom state via
fixtureData
tl_launch({ fixture: "default", startChain: true, headless: false })
// → { sessionId: "tl-1741504523", extensionId: "abc...", extensionUrl: "chrome-extension://..." }| Tool | Description |
|---|---|
tl_navigate |
Navigate to TronLink screens: home, settings, send, receive, swap, assets, notification, address_book, node_management, dapp_list, or custom URL |
tl_switch_to_tab |
Switch tabs by role (extension/dapp/notification) or URL pattern |
tl_close_tab |
Close tabs by role or URL pattern |
tl_wait_for_notification |
Wait for TronLink confirmation popup (transaction signing, connection requests) |
Supported navigation targets (TronLink routes):
| Target | Route | Description |
|---|---|---|
home |
#/home |
Asset home page |
settings |
#/settings |
Settings |
send |
#/transfer/step1 |
Transfer |
receive |
#/receive |
Receive |
assets |
#/assets_management/my_assets |
Asset management |
address_book |
#/address_book |
Address book |
node_management |
#/node_management |
Node management |
dapp_list |
#/dapp_list |
DApp browser |
| Tool | Description |
|---|---|
tl_click |
Click element (3 targeting methods: a11yRef, testId, CSS selector) |
tl_type |
Type text into input fields (supports clearing existing content) |
tl_wait_for |
Wait for element state (visible / hidden / attached / detached) |
tl_clipboard |
Read/write browser clipboard (copy addresses, mnemonics, etc.) |
Three element targeting methods:
// Method 1: Accessibility reference (recommended, most AI-friendly)
tl_click({ a11yRef: "e5" }) // ref from tl_accessibility_snapshot
// Method 2: data-testid
tl_click({ testId: "send-button" })
// Method 3: CSS selector
tl_click({ selector: ".confirm-btn" })| Tool | Description |
|---|---|
tl_get_state |
Get full wallet state: current screen, account address, network, TRX balance, energy, bandwidth |
tl_list_testids |
List all data-testid attributes on current page with visibility |
tl_accessibility_snapshot |
Get trimmed accessibility tree (ARIA) with deterministic refs (e1, e2, e3...) |
tl_describe_screen |
Comprehensive screen description: wallet state + testIds + a11y tree + optional screenshot |
tl_screenshot |
Capture TronLink or DApp screen (supports extension/dapp/active targets) |
tl_accessibility_snapshot output example:
{
"tree": {
"role": "document",
"children": [
{ "role": "heading", "name": "TronLink", "ref": "e1" },
{ "role": "button", "name": "Send", "ref": "e2" },
{ "role": "button", "name": "Receive", "ref": "e3" },
{ "role": "textbox", "name": "Search", "ref": "e4" }
]
},
"refCount": 4
}Screen detection (auto-identifies 15 TronLink screens):
home / login / settings / send / receive / sign / broadcast / assets / address_book / node_management / dapp_list / create_wallet / import_wallet / notification / unknown
Direct blockchain interactions via TronGrid REST API. No browser required. Requires OnChainCapability implementation from the consumer.
| 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 for an address |
tl_chain_send |
Send TRX, TRC10, or TRC20 tokens (signs locally, broadcasts) |
tl_chain_get_tx |
Get transaction details by transaction ID |
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 router |
tl_chain_swap_v3 |
Execute token swap via SunSwap V3 Smart Router |
tl_chain_setup_multisig |
Configure multi-sig permissions (accountPermissionUpdate, costs 100 TRX) |
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 |
Pre-checks: All transaction tools validate balances, permissions, and quotas before execution.
REST + WebSocket integration with the TronLink multi-signature service. Requires MultiSigCapability implementation from the consumer.
| Tool | Description |
|---|---|
tl_multisig_query_auth |
Query address multi-sig permissions (owner/active, thresholds, signer weights) |
tl_multisig_submit_tx |
Submit signed multi-sig transaction (auto-broadcasts when threshold met) |
tl_multisig_list_tx |
Query transaction list (pending/success/failed) with signature progress |
tl_multisig_connect_ws |
Connect WebSocket for real-time pending tx notifications |
tl_multisig_disconnect_ws |
Disconnect WebSocket listener |
TRC20 token transfers where gas fees are paid by the GasFree service provider. Requires GasFreeCapability implementation from the consumer.
| Tool | Description |
|---|---|
tl_gasfree_get_account |
Query account eligibility, supported tokens, and daily quota remaining |
tl_gasfree_get_transactions |
Query gas-free transaction history with pagination |
tl_gasfree_send |
Send TRC20 token with zero gas fee (pre-checks: eligibility, token support, quota, balance) |
| Tool | Description |
|---|---|
tl_seed_contract |
Deploy a single smart contract (e2e mode only) |
tl_seed_contracts |
Batch deploy multiple contracts |
tl_get_contract_address |
Query deployed contract address |
tl_list_contracts |
List all deployed contracts |
Supported contract types:
| Contract | Standard | Description |
|---|---|---|
trc20 |
TRC-20 | Fungible token (like ERC-20) |
trc721 |
TRC-721 | NFT (like ERC-721) |
trc1155 |
TRC-1155 | Multi-token standard |
trc10 |
TRC-10 | TRON native token standard |
multisig |
— | Multi-signature wallet contract |
staking |
— | Staking contract |
energy_rental |
— | Energy rental contract |
Managed through ChainCapability which controls the local chain node (e.g., tron-quickstart) with test accounts and TRX balance allocation.
Automatically records every tool invocation (with timestamp, screen, target, result labels) for AI learning and optimization.
| Tool | Description |
|---|---|
tl_knowledge_last |
Get the last N steps (supports session/global scope) |
tl_knowledge_search |
Search history by tool name, screen, testId, or a11y name |
tl_knowledge_summarize |
Auto-summarize session into a reusable "recipe" (step sequence) |
tl_knowledge_sessions |
List recent sessions with metadata |
Storage structure:
test-artifacts/llm-knowledge/
├── tl-1741504523/
│ ├── session.json
│ └── steps/
│ ├── 2026-03-09T10-15-23-456Z-tl_click.json
│ └── 2026-03-09T10-15-25-789Z-tl_type.json
└── tl-1741504600/
└── ...
Sensitive data protection: Automatically redacts password, mnemonic, private key, and seed fields before recording.
| Tool | Description |
|---|---|
tl_run_steps |
Execute multiple tool steps sequentially; supports stopOnError |
tl_run_steps({
steps: [
{ tool: "navigate", input: { target: "send" } },
{ tool: "type", input: { selector: "#address", text: "TXyz..." } },
{ tool: "type", input: { selector: "#amount", text: "100" } },
{ tool: "click", input: { selector: ".send-btn" } },
],
stopOnError: true,
})| Tool | Description |
|---|---|
tl_set_context |
Switch between e2e (test, with local chain/fixture) and prod (real network) |
tl_get_context |
Get current context, available capabilities, and session info |
Modular capability injection — consumers implement and inject as needed. The tool layer auto-detects available capabilities:
| Capability | Interface | Description |
|---|---|---|
| BuildCapability | build() / getExtensionPath() / isBuilt() |
Build TronLink extension from source |
| FixtureCapability | start() / stop() / getDefaultState() / getOnboardingState() |
Manage wallet state JSON (preset state injection) |
| ChainCapability | start() / stop() / isRunning() / getRpcUrl() / getTestAccounts() |
Control local TRON node |
| ContractSeedingCapability | deployContract() / deployContracts() / listDeployedContracts() |
Contract deployment and registry |
| StateSnapshotCapability | getState() / detectCurrentScreen() |
Extract high-level wallet state from UI |
| MockServerCapability | start() / stop() / isRunning() |
Mock API server (isolated testing) |
| OnChainCapability | getAddress() / getAccount() / send() / stake() / ... |
Direct on-chain operations via TronGrid API |
| MultiSigCapability | queryAuth() / submitTx() / listTx() / connectWs() / ... |
Multi-signature service integration |
| GasFreeCapability | getAccount() / getTransactions() / send() |
Gas-free TRC20 transfer service |
The core interface consumers must implement (6 categories, 25+ methods):
interface ISessionManager {
// Session lifecycle
hasActiveSession(): boolean;
getSessionId(): string | undefined;
launch(input: SessionLaunchInput): Promise<SessionLaunchResult>;
cleanup(): Promise<boolean>;
// Page management
getPage(): Page; // Get current active page
setActivePage(page: Page): void;
getTrackedPages(): TrackedPage[]; // All pages (extension/notification/dapp/other)
classifyPageRole(page: Page): TabRole;
getContext(): BrowserContext;
// Extension state
getExtensionState(): Promise<StateSnapshot>;
// Accessibility ref mapping
setRefMap(map: Map<string, string>): void;
resolveA11yRef(ref: string): string | undefined;
// Navigation
navigateToHome(): Promise<void>;
navigateToSettings(): Promise<void>;
navigateToUrl(url: string): Promise<Page>;
navigateToNotification(): Promise<Page>;
waitForNotificationPage(timeoutMs: number): Promise<Page>;
// Screenshot
screenshot(options: SessionScreenshotOptions): Promise<ScreenshotResult>;
// Capability injection (optional)
getBuildCapability?(): BuildCapability | undefined;
getFixtureCapability?(): FixtureCapability | undefined;
getChainCapability?(): ChainCapability | undefined;
getContractSeedingCapability?(): ContractSeedingCapability | undefined;
getStateSnapshotCapability?(): StateSnapshotCapability | undefined;
getMockServerCapability?(): MockServerCapability | undefined;
getOnChainCapability?(): OnChainCapability | undefined;
getMultiSigCapability?(): MultiSigCapability | undefined;
getGasFreeCapability?(): GasFreeCapability | undefined;
// Environment mode
getEnvironmentMode(): EnvironmentMode;
setContext(context: 'e2e' | 'prod'): void;
getContextInfo(): { currentContext, hasSession, capabilities, canSwitchContext };
}| # | Tool | Category | Mode | Description |
|---|---|---|---|---|
| 1 | tl_launch |
Session | Playwright | Launch Chrome with TronLink extension |
| 2 | tl_cleanup |
Session | Playwright | Safely close browser and services |
| 3 | tl_get_state |
State | Playwright | Get wallet state: screen, account, network, balance, energy, bandwidth |
| 4 | tl_describe_screen |
State | Playwright | Comprehensive screen description (state + testIds + a11y + screenshot) |
| 5 | tl_list_testids |
Discovery | Playwright | List all data-testid attributes on page |
| 6 | tl_accessibility_snapshot |
Discovery | Playwright | Get trimmed a11y tree with deterministic refs |
| 7 | tl_navigate |
Navigation | Playwright | Navigate to TronLink screen or URL |
| 8 | tl_switch_to_tab |
Navigation | Playwright | Switch tab by role or URL |
| 9 | tl_close_tab |
Navigation | Playwright | Close tab by role or URL |
| 10 | tl_wait_for_notification |
Navigation | Playwright | Wait for confirmation popup |
| 11 | tl_click |
Interaction | Playwright | Click element (a11yRef / testId / selector) |
| 12 | tl_type |
Interaction | Playwright | Type text (supports clear) |
| 13 | tl_wait_for |
Interaction | Playwright | Wait for element state |
| 14 | tl_scroll |
Interaction | Playwright | Scroll page or element |
| 15 | tl_keyboard |
Interaction | Playwright | Send keyboard events |
| 16 | tl_evaluate |
Interaction | Playwright | Execute JavaScript in page context |
| 17 | tl_screenshot |
Screenshot | Playwright | Capture screen |
| 18 | tl_clipboard |
Utility | Playwright | Read/write clipboard |
| 19 | tl_seed_contract |
Contract | Playwright (e2e) | Deploy single contract |
| 20 | tl_seed_contracts |
Contract | Playwright (e2e) | Batch deploy contracts |
| 21 | tl_get_contract_address |
Contract | Playwright (e2e) | Query deployed contract address |
| 22 | tl_list_contracts |
Contract | Playwright (e2e) | List all deployed contracts |
| 23 | tl_set_context |
Context | Both | Switch e2e / prod mode |
| 24 | tl_get_context |
Context | Both | Get current context info |
| 25 | tl_knowledge_last |
Knowledge | Both | Get last N steps |
| 26 | tl_knowledge_search |
Knowledge | Both | Search step history |
| 27 | tl_knowledge_summarize |
Knowledge | Both | Generate reusable session recipe |
| 28 | tl_knowledge_sessions |
Knowledge | Both | List recent sessions |
| 29 | tl_run_steps |
Batch | Both | Execute multiple steps sequentially |
| 30 | tl_list_flows |
Flows | Both | List built-in flow recipes |
| 31 | tl_chain_get_address |
On-Chain | Direct API | Derive address from private key |
| 32 | tl_chain_get_account |
On-Chain | Direct API | Query account details |
| 33 | tl_chain_get_tokens |
On-Chain | Direct API | Query TRC10 + TRC20 balances |
| 34 | tl_chain_send |
On-Chain | Direct API | Send TRX/TRC10/TRC20 |
| 35 | tl_chain_get_tx |
On-Chain | Direct API | Get transaction details |
| 36 | tl_chain_get_history |
On-Chain | Direct API | Query transaction history |
| 37 | tl_chain_stake |
On-Chain | Direct API | Freeze/unfreeze TRX (Stake 2.0) |
| 38 | tl_chain_get_staking |
On-Chain | Direct API | Query staking status |
| 39 | tl_chain_resource |
On-Chain | Direct API | Delegate/undelegate resources |
| 40 | tl_chain_swap |
On-Chain | Direct API | SunSwap V2 token swap |
| 41 | tl_chain_swap_v3 |
On-Chain | Direct API | SunSwap V3 token swap |
| 42 | tl_chain_setup_multisig |
On-Chain | Direct API | Configure multi-sig permissions |
| 43 | tl_chain_create_multisig_tx |
On-Chain | Direct API | Create unsigned multi-sig tx |
| 44 | tl_chain_sign_multisig_tx |
On-Chain | Direct API | Sign multi-sig transaction |
| 45 | tl_multisig_query_auth |
Multi-Sig | Direct API | Query multi-sig permissions |
| 46 | tl_multisig_submit_tx |
Multi-Sig | Direct API | Submit signed multi-sig tx |
| 47 | tl_multisig_list_tx |
Multi-Sig | Direct API | List multi-sig transactions |
| 48 | tl_multisig_connect_ws |
Multi-Sig | Direct API | Connect WebSocket for notifications |
| 49 | tl_multisig_disconnect_ws |
Multi-Sig | Direct API | Disconnect WebSocket |
| 50 | tl_gasfree_get_account |
GasFree | Direct API | Query account eligibility & quota |
| 51 | tl_gasfree_get_transactions |
GasFree | Direct API | Query gas-free tx history |
| 52 | tl_gasfree_send |
GasFree | Direct API | Send TRC20 with zero gas |
- AI agent automated testing: TronLink transfer, signing, DApp connection flows
- On-chain operations: Direct TRX/token transfers, staking, and swaps without browser
- Multi-sig management: Set up permissions, create/sign transactions, monitor via WebSocket
- Gas-free transfers: Zero-cost TRC20 transfers for end-user applications
- UI validation: Screenshot + state comparison to verify new features
- Contract testing: Auto-deploy TRC-20/721 contracts → interact → verify transactions
- LLM-controlled wallet: Natural language step-by-step wallet control with path memory
- Regression testing: Replay verified flows via knowledge store recipes
tronlink-mcp-core/
├── src/
│ ├── index.ts # Main entry, all public exports
│ ├── capabilities/
│ │ ├── types.ts # 9 capability interface definitions
│ │ ├── context.ts # Environment config (e2e/prod)
│ │ └── index.ts
│ ├── launcher/
│ │ ├── extension-id-resolver.ts # Resolve extension ID from browser
│ │ ├── extension-readiness.ts # Detect extension load / login / onboarding
│ │ └── index.ts
│ ├── mcp-server/
│ │ ├── server.ts # createMcpServer() main factory
│ │ ├── session-manager.ts # ISessionManager interface + global holder
│ │ ├── knowledge-store.ts # Cross-session knowledge persistence
│ │ ├── discovery.ts # Page inspection (testId collection, a11y snapshot)
│ │ ├── schemas.ts # Zod input validation schemas (all tools)
│ │ ├── constants.ts # Timeouts, limits, URL constants
│ │ ├── types/ # All type definitions
│ │ │ ├── responses.ts # McpResponse / SuccessResponse / ErrorResponse
│ │ │ ├── errors.ts # ErrorCodes enum (20 error codes)
│ │ │ ├── tool-inputs.ts # Tool input types
│ │ │ ├── tool-outputs.ts # Tool output types
│ │ │ ├── session.ts # Session state types
│ │ │ ├── step-record.ts # Step record types
│ │ │ ├── knowledge.ts # Prior knowledge types
│ │ │ └── discovery.ts # TestIdItem / A11yNodeTrimmed
│ │ ├── tools/ # Tool handlers
│ │ │ ├── definitions.ts # Tool registry + routing
│ │ │ ├── run-tool.ts # Execution wrapper (auto-logs to knowledge store)
│ │ │ ├── helpers.ts # Observation collection, screen detection, data redaction
│ │ │ ├── launch.ts # tl_launch
│ │ │ ├── cleanup.ts # tl_cleanup
│ │ │ ├── state.ts # tl_get_state
│ │ │ ├── navigation.ts # tl_navigate / switch_to_tab / close_tab / wait_for_notification
│ │ │ ├── interaction.ts # tl_click / tl_type / tl_wait_for
│ │ │ ├── screenshot.ts # tl_screenshot
│ │ │ ├── discovery-tools.ts # tl_list_testids / accessibility_snapshot / describe_screen
│ │ │ ├── clipboard.ts # tl_clipboard
│ │ │ ├── seeding.ts # tl_seed_contract / seed_contracts / get_contract_address
│ │ │ ├── context.ts # tl_set_context / tl_get_context
│ │ │ ├── knowledge.ts # tl_knowledge_last / search / summarize / sessions
│ │ │ ├── on-chain.ts # tl_chain_* (14 tools with pre-checks)
│ │ │ ├── multisig.ts # tl_multisig_* (5 tools)
│ │ │ ├── gasfree.ts # tl_gasfree_* (3 tools)
│ │ │ └── batch.ts # tl_run_steps + tool registry
│ │ └── utils/
│ │ ├── response.ts # createSuccessResponse / createErrorResponse
│ │ ├── errors.ts # extractErrorMessage
│ │ ├── targets.ts # validateTargetSelection
│ │ └── zod-to-json-schema.ts # Zod → JSON Schema conversion (MCP compatible)
│ └── utils/
│ └── index.ts # generateSessionId / generateFilesafeTimestamp
├── package.json
├── tsconfig.json
└── tsconfig.build.json
- Node.js >= 20
- Playwright >= 1.49 (peer dependency, only needed for Playwright mode tools)
- TypeScript >= 5.3
- Dependencies:
@modelcontextprotocol/sdk^1.12.0,zod^3.23.0
MIT License Copyright (c) 2026 TronLink