@missionsquad/mcp-server-tron 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 bankofai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,537 @@
+# MCP Server Tron
+
+![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)
+![TRON Network](https://img.shields.io/badge/Network-TRON-red)
+![TypeScript](https://img.shields.io/badge/TypeScript-5.8+-3178C6)
+![MCP](https://img.shields.io/badge/MCP-1.22.0+-blue)
+![TronWeb](https://img.shields.io/badge/TronWeb-6.0+-green)
+
+A comprehensive Model Context Protocol (MCP) server that provides blockchain services for the TRON network. This server enables AI agents to interact with TRON blockchain with a unified interface through tools and AI-guided prompts for TRX, TRC20 tokens and smart contracts.
+
+## Contents
+
+- [Overview](#overview)
+- [Features](#features)
+- [Supported Networks](#supported-networks)
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Configuration](#configuration)
+  - [Environment Variables](#environment-variables)
+  - [Server Configuration](#server-configuration)
+- [Usage](#usage)
+- [API Reference](#api-reference)
+  - [Tools](#tools)
+  - [Prompts](#prompts)
+- [Security Considerations](#security-considerations)
+- [Project Structure](#project-structure)
+- [License](#license)
+
+## Overview
+
+The MCP TRON Server leverages the Model Context Protocol to provide blockchain services to AI agents. It fully supports the TRON ecosystem using `tronweb`.
+
+Key capabilities:
+
+- **Blockchain Data**: Read blocks, transactions, and chain parameters (Energy/Bandwidth costs).
+- **Smart Contracts**: Interact with any TRON smart contract (Read/Write).
+- **Tokens**: Transfer TRX and TRC20 tokens; check balances.
+- **Address Management**: Convert between Hex (0x...) and Base58 (T...) formats.
+- **Wallet Integration**: Agent-wallet-managed file-backed wallets.
+- **Multi-Network**: Seamless support for Mainnet, Nile, and Shasta.
+- **Dynamic Access Control**: Write-capable tools stay registered; `--readonly` hides them, and wallet-dependent handlers fail at execution time if no wallet is available.
+
+## Features
+
+### Blockchain Data Access
+
+- **TRON network support**: Mainnet, Nile, Shasta.
+- **Chain information**: Block number, Chain ID, RPC endpoints.
+- **Block data**: Access by number or hash.
+- **Transaction details**: Detailed info including resource usage (Energy/Bandwidth).
+- **Resource Costs**: Query current chain parameters for Energy and Bandwidth prices.
+
+### Token Services
+
+- **Native TRX**: Check balance and transfer.
+- **TRC20 Tokens**:
+  - Check balances.
+  - Transfer tokens.
+  - Get token metadata (name, symbol, decimals).
+
+### Address Services
+
+- **Format Conversion**: Convert between Hex (`41...` or `0x...`) and Base58 (`T...`) formats.
+- **Validation**: Verify if an address is valid on TRON.
+
+### Smart Contract Interactions
+
+- **Read Contract**: Call `view` and `pure` functions.
+- **Write Contract**: Execute state-changing functions.
+- **ABI Fetching**: Automatically fetches ABI from the blockchain for verified contracts.
+
+### Governance & Proposals
+
+- **Super Representatives**: List, vote, create/update witnesses, manage brokerage.
+- **Proposals**: List, view, create, approve, and delete governance proposals.
+- **Rewards**: Query and withdraw SR voting rewards.
+
+### Events & Data Queries
+
+- **Contract Events**: Query events by transaction, contract address, or block number.
+- **Account Data**: Transaction history, TRC20 transfers, internal transactions, token balances (via TronGrid).
+- **Contract Data**: Contract transaction history, internal transactions, token holder lists.
+- **Mempool**: View pending transactions and pool size.
+- **Node Info**: List connected nodes and query node details.
+
+### Staking & Resource Delegation (Stake 2.0)
+
+- **Staking**: Freeze/unfreeze TRX for Energy or Bandwidth.
+- **Delegation**: Delegate and undelegate resources to other accounts.
+- **Queries**: Available unfreeze count, withdrawable amounts, delegation details.
+
+### Wallet & Security
+
+- **Agent Wallet**: File-backed wallet storage via `agent-wallet` SDK.
+- **HD Wallet**: Supports BIP-44 derivation path `m/44'/195'/0'/0/{index}`.
+- **Signing**: Sign arbitrary messages and transactions.
+
+## Supported Networks
+
+- **Mainnet**: `mainnet` (Default)
+- **Nile Testnet**: `nile`
+- **Shasta Testnet**: `shasta`
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/) 20.0.0 or higher
+- Optional: [TronGrid API key](https://www.trongrid.io/) to avoid rate limiting on Mainnet.
+
+## Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/MissionSquad/mcp-server-tron.git
+cd mcp-server-tron
+
+# Install dependencies
+npm install
+```
+
+## Configuration
+
+### Environment Variables
+
+**CRITICAL SECURITY NOTE**: For your security, **NEVER** save your private keys or mnemonics directly in MCP client configuration JSON files. In HTTP tenant mode, this server is now an OAuth2 authorization server and issues bearer access tokens after browser-wallet proof. Managed tenant wallets are stored server-side using `agent-wallet`.
+
+#### OAuth / HTTP Tenant Configuration
+
+- `MCP_PUBLIC_ORIGIN`: Required in HTTP mode. Public origin used as OAuth issuer and resource base.
+- `JWT_SECRET`: Required in HTTP mode. Signs OAuth access tokens.
+- `MCP_TENANT_MASTER_SECRET`: Required in HTTP mode. Derives deterministic per-tenant wallet encryption passwords.
+- `MCP_DATA_DIR`: Optional. Directory for tenant wallet storage and refresh-token persistence.
+- `MCP_AUTH_CHALLENGE_TTL_SECONDS`: Optional. Wallet-sign challenge TTL.
+- `MCP_OAUTH_AUTH_CODE_TTL_SECONDS`: Optional. Authorization-code TTL.
+- `MCP_OAUTH_ACCESS_TOKEN_TTL_SECONDS`: Optional. OAuth access-token TTL.
+- `MCP_OAUTH_REFRESH_TOKEN_TTL_SECONDS`: Optional. OAuth refresh-token TTL.
+
+#### Network Configuration
+
+- `TRONGRID_API_KEY`: (Optional) Your TronGrid API key.
+  - **Why**: TRON mainnet RPCs have strict rate limits. When `TRONGRID_API_KEY` is set (and non-empty), the server uses `https://api.trongrid.io` as the default RPC hosts.
+  - **Fallback**: When `TRONGRID_API_KEY` is not set, the server uses `https://hptg.bankofai.io` as the default RPC hosts for `mainnet`.
+  - **Usage**:
+    ```bash
+    export TRONGRID_API_KEY="<YOUR_TRONGRID_API_KEY_HERE>"
+    ```
+- Optional explicit RPC overrides are also supported:
+  - `TRON_MAINNET_FULL_NODE`
+  - `TRON_MAINNET_SOLIDITY_NODE`
+  - `TRON_MAINNET_EVENT_SERVER`
+  - `TRON_NILE_FULL_NODE`
+  - `TRON_NILE_SOLIDITY_NODE`
+  - `TRON_NILE_EVENT_SERVER`
+  - `TRON_SHASTA_FULL_NODE`
+  - `TRON_SHASTA_SOLIDITY_NODE`
+  - `TRON_SHASTA_EVENT_SERVER`
+
+#### Wallet Configuration
+
+Wallets are managed through `agent-wallet` file-backed configuration. In HTTP mode, the server also creates and stores one managed wallet per tenant under its own tenant directory. This repository no longer reads or maps legacy `TRON_PRIVATE_KEY` / `TRON_MNEMONIC` / `TRON_ACCOUNT_INDEX` wallet variables.
+
+> **Prerequisites**: Install and configure [agent-wallet](https://github.com/MissionSquad/agent-wallet/blob/main/doc/getting-started.md)
+
+> See [`agent-wallet`](https://github.com/MissionSquad/agent-wallet) for wallet file formats, local setup, and the SDK-supported `AGENT_WALLET_*` settings.
+
+### Server Configuration
+
+The server runs on port **3001** by default in HTTP mode.
+
+## Usage
+
+### Running Locally
+
+```bash
+# Start in stdio mode (for MCP clients like Claude Desktop/Cursor)
+npm start
+
+# Start in readonly mode (disables write tools)
+npm start -- --readonly
+
+# Start in stateless HTTP mode (Streamable HTTP)
+npm run start:http
+```
+
+### OAuth2 Compatibility
+
+HTTP mode is now designed for MissionSquad external MCP compatibility:
+
+- transport: `streamable_http`
+- auth mode: `oauth2`
+- grant: authorization code + PKCE
+- registration mode: CIMD
+
+HTTP OAuth endpoints:
+
+- `GET /.well-known/oauth-authorization-server`
+- `GET /.well-known/oauth-protected-resource`
+- `GET /oauth/authorize`
+- `POST /oauth/authorize/challenge`
+- `POST /oauth/authorize/verify`
+- `POST /oauth/authorize/create-wallet`
+- `POST /oauth/token`
+
+The authorization page supports:
+
+- connecting an existing managed wallet by browser-wallet signature proof
+- creating a new managed wallet during authorization and revealing the private key once
+
+### Docker
+
+Build the image:
+
+```bash
+docker build -t mcp-server-tron:test .
+```
+
+Run the container with local logs mounted:
+
+```bash
+docker run -d \
+  --name mcp-tron \
+  -p 3001:3001 \
+  -e MCP_HOST=0.0.0.0 \
+  -e MCP_PORT=3001 \
+  -e MCP_LOG_DIR=/app/logs \
+  -v "$(pwd)/logs:/app/logs" \
+  mcp-server-tron:test
+```
+
+Docker logs are written to the mounted `logs/` directory and are named by date, for example:
+
+- `logs/mcp-server-tron-2026-03-18-combined.log`
+- `logs/mcp-server-tron-2026-03-18-error.log`
+
+### Testing
+
+The project includes a comprehensive test suite with unit tests and integration tests (using the Nile testnet).
+
+```bash
+# Run all tests
+npm test
+
+# Unit tests (mocked services, no network)
+npx vitest tests/core/tools.test.ts                    # All MCP tools registration & handlers
+npx vitest tests/core/services/contracts.test.ts       # Contract services
+npx vitest tests/core/services/account-resource.test.ts # Account resource services
+npx vitest tests/core/services/staking.test.ts         # Staking services
+
+# Integration tests (real Nile RPC; write-operation coverage is skipped unless wallet support is explicitly enabled)
+npx vitest tests/core/tools_integration.test.ts        # Full tool flow on Nile
+npx vitest tests/core/services/multicall.test.ts       # Multicall integration
+npx vitest tests/core/services/services.test.ts        # Services integration
+```
+
+- **Unit tests** use mocks and do not need network or wallet.
+- **Integration tests** (`tools_integration.test.ts`) call Nile RPC; most cases are read-only. Wallet-dependent handlers are exercised as runtime failures by default, while write-success paths require an explicit wallet fixture or equivalent setup.
+
+### Client Configuration
+
+#### Option A: Quick Start (Recommended)
+
+Runs the latest version directly from npm via stdio transport.
+
+**Claude Code:**
+
+```bash
+claude mcp add mcp-server-tron -- npx -y @missionsquad/mcp-server-tron
+```
+
+**Cursor** (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "mcp-server-tron": {
+      "command": "npx",
+      "args": ["-y", "@missionsquad/mcp-server-tron"],
+      "env": {
+        "TRONGRID_API_KEY": "YOUR_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+#### Option B: Official Hosted Server (Remote)
+
+Connect to the official hosted server at `https://mcp-tron.missionsquad.ai`. No installation required, readonly mode, stateless HTTP.
+
+**Claude Code:**
+
+```bash
+claude mcp add -transport http mcp-tron https://mcp-tron.missionsquad.ai/mcp
+```
+
+**Cursor** (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "mcp-tron": {
+      "url": "https://mcp-tron.missionsquad.ai/mcp"
+    }
+  }
+}
+```
+
+## API Reference
+
+### Tools
+
+#### Wallet & Address
+
+| Tool Name            | Description                                         | Key Parameters |
+| :------------------- | :-------------------------------------------------- | :------------- |
+| `get_wallet_address` | Get the configured wallet's address (Base58 & Hex). | -              |
+| `list_wallets`       | List all available wallets with IDs and addresses.   | -              |
+| `select_wallet`      | Switch the active wallet at runtime (agent-wallet mode). | `walletId` |
+| `convert_address`    | Convert between Hex and Base58 formats.             | `address`      |
+
+#### Network & Resources
+
+| Tool Name                | Description                             | Key Parameters |
+| :----------------------- | :-------------------------------------- | :------------- |
+| `get_chain_info`         | Get current block and chain ID.         | `network`      |
+| `get_chain_parameters`   | Get current Energy and Bandwidth costs. | `network`      |
+| `get_energy_prices`      | Query historical energy unit price.     | `network`      |
+| `get_bandwidth_prices`   | Query historical bandwidth unit price.  | `network`      |
+| `get_burn_trx`           | Query total TRX burned from fees.       | `network`      |
+| `get_supported_networks` | List available networks.                | -              |
+
+#### Blocks & Transactions
+
+| Tool Name              | Description                                | Key Parameters               |
+| :--------------------- | :----------------------------------------- | :--------------------------- |
+| `get_block`            | Fetch block by number or hash.             | `blockIdentifier`, `network` |
+| `get_latest_block`     | Get the latest block.                      | `network`                    |
+| `get_transaction`      | Get transaction details by hash.           | `txHash`, `network`          |
+| `get_transaction_info` | Get receipt/info including resource usage. | `txHash`, `network`          |
+| `get_block_by_num`     | Query block by block height.               | `num`, `network`             |
+| `get_block_by_id`      | Query block by block ID (hash).            | `value`, `network`           |
+| `get_block_by_latest_num` | Get latest N blocks (solidified).       | `num`, `network`             |
+| `get_block_by_limit_next`  | Get blocks in range [startNum, endNum). | `startNum`, `endNum`, `network` |
+| `get_now_block`        | Get the current latest block info.         | `network`                    |
+| `get_transaction_by_id` | Query transaction status/content by txID. | `value`, `network`           |
+| `get_transaction_info_by_id` | Query transaction receipt by txID.   | `value`, `network`           |
+| `get_transaction_info_by_block_num` | Get receipts for all txs in a block. | `num`, `network`     |
+| `get_approved_list`    | Query the list of accounts that signed a transaction. | `transaction`, `network` |
+| `get_block_balance`    | Get all balance change operations in a block. | `hash`, `number`, `network` |
+
+#### Broadcast & Transaction Building (Write)
+
+| Tool Name               | Description                                                        | Key Parameters                      |
+| :---------------------- | :----------------------------------------------------------------- | :---------------------------------- |
+| `create_transaction`    | Create an unsigned TRX transfer transaction.                       | `ownerAddress`, `toAddress`, `amount`, `network` |
+| `broadcast_transaction` | Broadcast a signed transaction JSON object to the TRON network.     | `transaction`, `network`           |
+| `broadcast_hex`         | Broadcast a signed protobuf-encoded transaction hex string.         | `transaction`, `network`           |
+
+#### Balances
+
+| Tool Name           | Description                             | Key Parameters                       |
+| :------------------ | :-------------------------------------- | :----------------------------------- |
+| `get_balance`       | Get TRX balance for an address.         | `address`, `network`                 |
+| `get_token_balance` | Get TRC20 token balance for an address. | `address`, `tokenAddress`, `network` |
+
+#### Transfers (Write)
+
+| Tool Name        | Description                      | Key Parameters                            |
+| :--------------- | :------------------------------- | :---------------------------------------- |
+| `transfer_trx`   | Send TRX (Native) to an address. | `to`, `amount`, `network`                 |
+| `transfer_trc20` | Send TRC20 tokens to an address. | `tokenAddress`, `to`, `amount`, `network` |
+
+#### Smart Contracts
+
+| Tool Name            | Description                                               | Key Parameters                                                |
+| :------------------- | :-------------------------------------------------------- | :------------------------------------------------------------ |
+| `read_contract`     | Call read-only (`view`/`pure`) functions.                  | `contractAddress`, `functionName`, `args`, `network`          |
+| `get_contract`      | Get raw contract metadata (ABI, bytecode) from chain.    | `contractAddress`, `network`                                 |
+| `get_contract_info` | Get ABI, function list and raw metadata.                  | `contractAddress`, `network`                                  |
+| `fetch_contract_abi`| Fetch ABI entry array for verified contracts.             | `contractAddress`, `network`                                  |
+| `multicall`         | Execute multiple read calls in one batch.                 | `calls`, `network`                                            |
+| `write_contract`    | Execute state-changing contract functions.                | `contractAddress`, `functionName`, `args`, `value`, `network` |
+| `deploy_contract`   | Deploy a smart contract with ABI and bytecode.           | `abi`, `bytecode`, `args`, `network`                          |
+| `estimate_energy`   | Estimate energy consumption for a contract call.         | `address`, `functionName`, `abi`, `network`                   |
+| `update_contract_setting` | Update consume_user_resource_percent (creator only). | `contractAddress`, `consumeUserResourcePercent`, `network`     |
+| `update_energy_limit`    | Update originEnergyLimit (creator only).             | `contractAddress`, `originEnergyLimit`, `network`              |
+| `clear_abi`         | Clear on-chain ABI metadata (creator only).               | `contractAddress`, `network`                                  |
+
+#### Account Management
+
+| Tool Name                       | Description                                                     | Key Parameters                                         |
+| :------------------------------ | :-------------------------------------------------------------- | :----------------------------------------------------- |
+| `get_account`                   | Get full account info (balance, resources, permissions, etc.).   | `address`, `network`                                   |
+| `get_account_balance`           | Get TRX balance at a specific block height.                     | `address`, `blockHash`, `blockNumber`, `network`       |
+| `generate_account`              | Generate a new TRON keypair offline.                            | -                                                      |
+| `validate_address`              | Validate a TRON address and detect format.                      | `address`                                              |
+| `get_account_net`               | Get bandwidth information for an account.                       | `address`, `network`                                   |
+| `get_account_resource`          | Get energy, bandwidth, and delegation details.                  | `address`, `network`                                   |
+| `get_delegated_resource`        | Query delegated resources between two accounts (Stake 2.0).     | `fromAddress`, `toAddress`, `network`                  |
+| `get_delegated_resource_index`  | Query delegation index (who delegated to/from this account).    | `address`, `network`                                   |
+| `create_account`                | Activate a new account on-chain (costs bandwidth).              | `address`, `network`                                   |
+| `update_account`                | Set account name (can only be set once).                        | `accountName`, `network`                               |
+| `account_permission_update`     | Update multi-signature permissions.                             | `ownerPermission`, `activePermissions`, `network`      |
+
+#### Staking (Stake 2.0)
+
+| Tool Name                       | Description                                                       | Key Parameters                  |
+| :------------------------------ | :---------------------------------------------------------------- | :----------------------------- |
+| `freeze_balance_v2`             | Freeze TRX to get resources (BANDWIDTH/ENERGY).                   | `amount`, `resource`, `network` |
+| `unfreeze_balance_v2`           | Unfreeze TRX to release resources.                               | `amount`, `resource`, `network` |
+| `withdraw_expire_unfreeze`      | Withdraw expired unfrozen balance back to available.             | `network`                      |
+| `cancel_all_unfreeze_v2`        | Re-stake pending unfreezes; withdraw expired ones.               | `network`                      |
+| `get_available_unfreeze_count`  | Get remaining unstake operation quota (max 32).                  | `address`, `network`           |
+| `get_can_withdraw_unfreeze_amount` | Get withdrawable TRX from unfreeze at a timestamp.            | `address`, `timestampMs`, `network` |
+
+#### Account resource (Stake 2.0 delegation)
+
+| Tool Name                                | Description                                                    | Key Parameters                                    |
+| :--------------------------------------- | :------------------------------------------------------------- | :----------------------------------------------- |
+| `delegate_resource`                      | Delegate BANDWIDTH/ENERGY to another address.                   | `receiverAddress`, `amount`, `resource`, `network` |
+| `undelegate_resource`                   | Revoke delegated resources.                                   | `receiverAddress`, `amount`, `resource`, `network` |
+| `get_can_delegated_max_size`             | Get max delegatable amount for an address.                     | `address`, `resource`, `network`                  |
+| `get_delegated_resource_v2`              | Get delegation details between two addresses.                  | `fromAddress`, `toAddress`, `network`             |
+| `get_delegated_resource_account_index_v2`| Get who delegated to/from an address.                          | `address`, `network`                             |
+
+#### Governance (Super Representatives)
+
+| Tool Name                  | Description                                                      | Key Parameters                  |
+| :------------------------- | :--------------------------------------------------------------- | :------------------------------ |
+| `list_witnesses`           | Get the full list of all Super Representatives on the network.   | `network`                       |
+| `get_paginated_witnesses`  | Get a paginated list of current active Super Representatives.    | `offset`, `limit`, `network`    |
+| `get_next_maintenance_time`| Get the next SR maintenance (vote tally) time.                   | `network`                       |
+| `get_reward`               | Get unclaimed SR voting reward for an address.                   | `address`, `network`            |
+| `get_brokerage`            | Get SR brokerage ratio (reward split with voters).               | `address`, `network`            |
+| `create_witness`           | Apply to become a Super Representative candidate.                | `url`, `network`                |
+| `update_witness`           | Update Super Representative URL.                                 | `url`, `network`                |
+| `vote_witness`             | Vote for Super Representatives with frozen TRX.                  | `votes`, `network`              |
+| `withdraw_balance`         | Withdraw accumulated SR block rewards.                           | `network`                       |
+| `update_brokerage`         | Update SR brokerage ratio.                                       | `brokerage`, `network`          |
+
+#### Proposals
+
+| Tool Name          | Description                                 | Key Parameters                         |
+| :----------------- | :------------------------------------------ | :------------------------------------- |
+| `list_proposals`   | List all network governance proposals.      | `network`                              |
+| `get_proposal`     | Get details of a specific proposal by ID.   | `proposalId`, `network`               |
+| `create_proposal`  | Create a new governance proposal (SR only). | `parameters`, `network`               |
+| `approve_proposal` | Approve or revoke a proposal (SR only).     | `proposalId`, `hasApproval`, `network` |
+| `delete_proposal`  | Delete a proposal (creator only).           | `proposalId`, `network`               |
+
+#### Events
+
+| Tool Name                       | Description                                           | Key Parameters                           |
+| :------------------------------ | :---------------------------------------------------- | :--------------------------------------- |
+| `get_events_by_transaction_id`  | Get all events emitted by a specific transaction.     | `transactionId`, `onlyConfirmed`, `network` |
+| `get_events_by_contract_address`| Get events emitted by a specific contract.            | `contractAddress`, `eventName`, `network` |
+| `get_events_by_block_number`    | Get all events emitted in a specific block.           | `blockNumber`, `network`                 |
+| `get_events_of_latest_block`    | Get all events from the latest block.                 | `network`                                |
+
+#### Account Data (TronGrid)
+
+| Tool Name                          | Description                                            | Key Parameters                         |
+| :--------------------------------- | :----------------------------------------------------- | :------------------------------------- |
+| `get_account_info`                 | Get account summary from TronGrid.                     | `address`, `network`                   |
+| `get_account_transactions`         | Get transaction history for an account.                | `address`, `limit`, `network`          |
+| `get_account_trc20_transactions`   | Get TRC20 transfer history for an account.             | `address`, `limit`, `network`          |
+| `get_account_internal_transactions`| Get internal transaction history for an account.       | `address`, `limit`, `network`          |
+| `get_account_trc20_balances`       | Get all TRC20 token balances for an account.           | `address`, `network`                   |
+
+#### Contract Data (TronGrid)
+
+| Tool Name                          | Description                                           | Key Parameters                         |
+| :--------------------------------- | :---------------------------------------------------- | :------------------------------------- |
+| `get_contract_transactions`        | Get transaction history for a contract.               | `contractAddress`, `limit`, `network`  |
+| `get_contract_internal_transactions`| Get internal transactions for a contract.            | `contractAddress`, `limit`, `network`  |
+| `get_trc20_token_holders`          | Get holder list for a TRC20 token.                    | `contractAddress`, `limit`, `network`  |
+
+#### Mempool
+
+| Tool Name                       | Description                                              | Key Parameters        |
+| :------------------------------ | :------------------------------------------------------- | :-------------------- |
+| `get_pending_transactions`      | Get transaction IDs in the pending pool (mempool).       | `network`             |
+| `get_transaction_from_pending`  | Get a specific transaction from the pending pool.        | `txId`, `network`     |
+| `get_pending_size`              | Get the current size of the pending transaction pool.    | `network`             |
+
+#### Node
+
+| Tool Name      | Description                                           | Key Parameters |
+| :------------- | :---------------------------------------------------- | :------------- |
+| `list_nodes`   | List all connected node addresses on the network.     | `network`      |
+| `get_node_info`| Get detailed info about the connected full node.      | `network`      |
+
+#### Signing & Security
+
+| Tool Name      | Description                                | Key Parameters |
+| :------------- | :----------------------------------------- | :------------- |
+| `sign_message` | Sign a message with the configured wallet. | `message`      |
+
+### Prompts
+
+- `prepare_transfer`: Interactive guide to prepare TRX/TRC20 transfers.
+- `interact_with_contract`: Step-by-step guide to interact with a smart contract.
+- `diagnose_transaction`: Analyze a transaction hash for status and errors.
+- `explain_tron_concept`: Explain a TRON blockchain concept with examples.
+- `analyze_wallet`: Comprehensive report of wallet assets.
+- `check_network_status`: Report on network health and resource costs.
+
+## Security Considerations
+
+- **Private Keys & Mnemonics**: Keep wallet material inside `agent-wallet` file-backed configuration instead of plain text MCP config files. This repository no longer maps legacy `TRON_*` wallet variables; use `AGENT_WALLET_*` only when following the `agent-wallet` SDK documentation.
+- **Shared Machines**: Be aware that plain environment variables can be visible to other users via `/proc` or system monitoring tools.
+- **Testnets**: Always test on Nile or Shasta before performing operations on Mainnet.
+- **Approvals**: Be cautious when approving token allowances via `write_contract`. Only approve what is necessary.
+
+## Project Structure
+
+```
+mcp-server-tron/
+├── src/
+│   ├── core/
+│   │   ├── chains.ts           # Network definitions
+│   │   ├── tools/              # MCP Tool definitions (split by category)
+│   │   ├── prompts.ts          # MCP Prompt definitions
+│   │   └── services/           # Business logic (TronWeb integration)
+│   │       ├── wallet.ts       # Wallet management
+│   │       ├── transfer.ts     # Transfer logic
+│   │       ├── contracts.ts    # Contract logic
+│   │       ├── address.ts      # Address conversion
+│   │       └── ...
+│   ├── server/                 # HTTP/Stdio server setup
+│   └── index.ts                # Entry point
+├── tests/                      # Unit tests
+└── package.json
+```
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+
+import { fileURLToPath } from "url";
+import { dirname, resolve } from "path";
+import { spawn } from "child_process";
+import { createRequire } from "module";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const require = createRequire(import.meta.url);
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+const httpMode = args.includes("--http") || args.includes("-h");
+
+console.error(`Starting mcp-server-tron in ${httpMode ? "HTTP" : "stdio"} mode...`);
+
+// Determine which file to execute
+const scriptPath = resolve(__dirname, "../build", httpMode ? "server/http-server.js" : "index.js");
+
+try {
+  // Check if the built files exist
+  require.resolve(scriptPath);
+
+  // Execute the server
+  const server = spawn("node", [scriptPath, ...args], {
+    stdio: "inherit",
+    shell: false,
+  });
+
+  server.on("error", (err) => {
+    console.error("Failed to start server:", err);
+    process.exit(1);
+  });
+
+  // Handle clean shutdown
+  const cleanup = () => {
+    if (!server.killed) {
+      server.kill();
+    }
+  };
+
+  process.on("SIGINT", cleanup);
+  process.on("SIGTERM", cleanup);
+  process.on("exit", cleanup);
+} catch (error) {
+  console.error("Error: Server files not found. The package may not be built correctly.");
+  console.error("Please try reinstalling the package or contact the maintainers.");
+  console.error(error);
+  process.exit(1);
+}

package/build/core/chains.d.ts

@@ -0,0 +1,17 @@
+export declare enum TronNetwork {
+    Mainnet = "mainnet",
+    Nile = "nile",
+    Shasta = "shasta"
+}
+export interface NetworkConfig {
+    name: string;
+    fullNode: string;
+    solidityNode: string;
+    eventServer: string;
+    explorer: string;
+}
+export declare const NETWORKS: Record<TronNetwork, NetworkConfig>;
+export declare const DEFAULT_NETWORK = TronNetwork.Mainnet;
+export declare function getNetworkConfig(network?: string): NetworkConfig;
+export declare function getSupportedNetworks(): string[];
+export declare function getRpcUrl(network?: string): string;