@sun-protocol/tron-mcp-server 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 mcpdotdirect
+
+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,282 @@
+# TRON MCP Server
+
+![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**: Support for Private Key and Mnemonic (BIP-39) wallets.
+- **Multi-Network**: Seamless support for Mainnet, Nile, and Shasta.
+
+## 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.
+
+### Wallet & Security
+
+- **Flexible Wallet**: Configure via `TRON_PRIVATE_KEY` or `TRON_MNEMONIC`.
+- **HD Wallet**: Supports BIP-44 derivation path `m/44'/195'/0'/0/{index}`.
+- **Signing**: Sign arbitrary messages.
+
+## 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/sun-protocol/tron-mcp-server.git
+cd tron-mcp-server
+
+# Install dependencies
+npm install
+```
+
+## Configuration
+
+### Environment Variables
+
+**CRITICAL SECURITY NOTE**: For your security, **NEVER** save your private keys or mnemonics directly in the MCP configuration JSON files (like `claude_desktop_config.json` or `mcp.json`). Instead, set them as environment variables in your operating system or shell configuration.
+
+To enable write operations (transfers, contract calls) and ensure reliable API access, you should configure the following variables.
+
+#### Network Configuration
+
+- `TRONGRID_API_KEY`: (Optional) Your TronGrid API key.
+  - **Why**: TRON mainnet RPCs have strict rate limits. Using an API key from [TronGrid](https://www.trongrid.io/) ensures reliable performance and higher throughput.
+  - **Usage**:
+    ```bash
+    export TRONGRID_API_KEY="<YOUR_TRONGRID_API_KEY_HERE>"
+    ```
+
+#### Wallet Configuration (Use Environment Variables)
+
+**Option 1: Private Key**
+
+```bash
+# Recommended: Add this to your ~/.zshrc or ~/.bashrc
+export TRON_PRIVATE_KEY="<YOUR_PRIVATE_KEY_HERE>"
+```
+
+**Option 2: Mnemonic Phrase**
+
+```bash
+# Recommended: Add this to your ~/.zshrc or ~/.bashrc
+export TRON_MNEMONIC="<WORD1> <WORD2> ... <WORD12>"
+export TRON_ACCOUNT_INDEX="0" # Optional, default: 0
+```
+
+### 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 HTTP mode (Server-Sent Events)
+npm run start:http
+```
+
+### Testing
+
+The project includes a comprehensive test suite with unit tests and integration tests (using the Nile network).
+
+```bash
+# Run all tests
+npm test
+
+# Run specific test suites
+npx vitest tests/core/tools.test.ts          # Unit tests for tools
+npx vitest tests/core/services/multicall.test.ts # Multicall integration
+npx vitest tests/core/services/services.test.ts # Services integration
+```
+
+### Connecting from Cursor / Claude Desktop
+
+Add the following to your MCP configuration file (e.g., `~/.config/Claude/claude_desktop_config.json` or `.cursor/mcp.json`).
+
+**Important**: We recommend omitting the `env` section if you have already set these variables in your system environment. If your MCP client doesn't inherit system variables, use placeholders or ensure the config file is not shared or committed to version control.
+
+**For local development (running from source):**
+
+```json
+{
+  "mcpServers": {
+    "tron-mcp-server": {
+      "command": "npx",
+      "args": ["tsx", "/ABSOLUTE/PATH/TO/tron-mcp-server/src/index.ts"],
+      "env": {
+        "TRON_PRIVATE_KEY": "<YOUR_PRIVATE_KEY_HERE>",
+        "TRONGRID_API_KEY": "<YOUR_TRONGRID_API_KEY_HERE>"
+      }
+    }
+  }
+}
+```
+
+**For using the built package (if installed globally or via npx):**
+
+```json
+{
+  "mcpServers": {
+    "tron-mcp-server": {
+      "command": "npx",
+      "args": ["-y", "@sun-protocol/tron-mcp-server"],
+      "env": {
+        "TRON_PRIVATE_KEY": "<YOUR_PRIVATE_KEY_HERE>",
+        "TRONGRID_API_KEY": "<YOUR_TRONGRID_API_KEY_HERE>"
+      }
+    }
+  }
+}
+```
+
+## API Reference
+
+### Tools
+
+#### Wallet & Address
+
+- `get_wallet_address`: Get the configured wallet's address (Base58 & Hex).
+- `convert_address`: Convert between Hex and Base58 formats.
+
+#### Network & Resources
+
+- `get_chain_info`: Get current block and chain ID.
+- `get_chain_parameters`: Get current Energy and Bandwidth costs.
+- `get_supported_networks`: List available networks.
+
+#### Blocks & Transactions
+
+- `get_block`: Fetch block by number or hash.
+- `get_latest_block`: Get the latest block.
+- `get_transaction`: Get transaction details.
+- `get_transaction_info`: Get transaction receipt/info (including resource usage).
+
+#### Balances
+
+- `get_balance`: Get TRX balance.
+- `get_token_balance`: Get TRC20 token balance.
+
+#### Transfers (Write)
+
+- `transfer_trx`: Send TRX.
+- `transfer_trc20`: Send TRC20 tokens.
+
+#### Smart Contracts
+
+- `read_contract`: Call read-only contract functions.
+- `multicall`: Execute multiple read-only functions in a single batch call.
+- `write_contract`: Call state-changing contract functions.
+
+#### Signing
+
+- `sign_message`: Sign a text message with the configured wallet.
+
+### Prompts
+
+- `prepare_transfer`: Interactive guide to prepare TRX/TRC20 transfers.
+- `diagnose_transaction`: Analyze a transaction hash for status and errors.
+- `analyze_wallet`: Comprehensive report of wallet assets.
+- `check_network_status`: Report on network health and resource costs.
+
+## Security Considerations
+
+- **Private Keys & Mnemonics**: **NEVER** save your sensitive wallet information in plain text configuration files (like `mcp.json`). These files are often unencrypted and can be accidentally shared or committed to git. Use system environment variables which are more secure.
+- **Exposure**: If you are using a shared machine, be aware that environment variables might be visible to other users.
+- **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
+
+```
+tron-mcp-server/
+├── src/
+│   ├── core/
+│   │   ├── chains.ts           # Network definitions
+│   │   ├── tools.ts            # MCP Tool definitions
+│   │   ├── 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 TRON MCP Server 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], {
+    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;

package/build/core/chains.js

@@ -0,0 +1,55 @@
+// Tron Network Definitions
+export var TronNetwork;
+(function (TronNetwork) {
+    TronNetwork["Mainnet"] = "mainnet";
+    TronNetwork["Nile"] = "nile";
+    TronNetwork["Shasta"] = "shasta";
+})(TronNetwork || (TronNetwork = {}));
+export const NETWORKS = {
+    [TronNetwork.Mainnet]: {
+        name: "Mainnet",
+        fullNode: "https://api.trongrid.io",
+        solidityNode: "https://api.trongrid.io",
+        eventServer: "https://api.trongrid.io",
+        explorer: "https://tronscan.org",
+    },
+    [TronNetwork.Nile]: {
+        name: "Nile",
+        fullNode: "https://nile.trongrid.io",
+        solidityNode: "https://nile.trongrid.io",
+        eventServer: "https://nile.trongrid.io",
+        explorer: "https://nile.tronscan.org",
+    },
+    [TronNetwork.Shasta]: {
+        name: "Shasta",
+        fullNode: "https://api.shasta.trongrid.io",
+        solidityNode: "https://api.shasta.trongrid.io",
+        eventServer: "https://api.shasta.trongrid.io",
+        explorer: "https://shasta.tronscan.org",
+    },
+};
+export const DEFAULT_NETWORK = TronNetwork.Mainnet;
+export function getNetworkConfig(network = DEFAULT_NETWORK) {
+    const normalizedNetwork = network.toLowerCase();
+    // Direct match
+    if (Object.values(TronNetwork).includes(normalizedNetwork)) {
+        return NETWORKS[normalizedNetwork];
+    }
+    // Aliases
+    if (normalizedNetwork === "tron" ||
+        normalizedNetwork === "trx" ||
+        normalizedNetwork === "mainnet") {
+        return NETWORKS[TronNetwork.Mainnet];
+    }
+    if (normalizedNetwork === "testnet") {
+        return NETWORKS[TronNetwork.Nile]; // Default testnet to Nile
+    }
+    throw new Error(`Unsupported network: ${network}`);
+}
+export function getSupportedNetworks() {
+    return Object.values(TronNetwork);
+}
+export function getRpcUrl(network = DEFAULT_NETWORK) {
+    return getNetworkConfig(network).fullNode;
+}
+//# sourceMappingURL=chains.js.map

package/build/core/chains.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chains.js","sourceRoot":"","sources":["../../src/core/chains.ts"],"names":[],"mappings":"AAAA,2BAA2B;AAE3B,MAAM,CAAN,IAAY,WAIX;AAJD,WAAY,WAAW;IACrB,kCAAmB,CAAA;IACnB,4BAAa,CAAA;IACb,gCAAiB,CAAA;AACnB,CAAC,EAJW,WAAW,KAAX,WAAW,QAItB;AAUD,MAAM,CAAC,MAAM,QAAQ,GAAuC;IAC1D,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE;QACrB,IAAI,EAAE,SAAS;QACf,QAAQ,EAAE,yBAAyB;QACnC,YAAY,EAAE,yBAAyB;QACvC,WAAW,EAAE,yBAAyB;QACtC,QAAQ,EAAE,sBAAsB;KACjC;IACD,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE;QAClB,IAAI,EAAE,MAAM;QACZ,QAAQ,EAAE,0BAA0B;QACpC,YAAY,EAAE,0BAA0B;QACxC,WAAW,EAAE,0BAA0B;QACvC,QAAQ,EAAE,2BAA2B;KACtC;IACD,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE;QACpB,IAAI,EAAE,QAAQ;QACd,QAAQ,EAAE,gCAAgC;QAC1C,YAAY,EAAE,gCAAgC;QAC9C,WAAW,EAAE,gCAAgC;QAC7C,QAAQ,EAAE,6BAA6B;KACxC;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,eAAe,GAAG,WAAW,CAAC,OAAO,CAAC;AAEnD,MAAM,UAAU,gBAAgB,CAAC,UAAkB,eAAe;IAChE,MAAM,iBAAiB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAEhD,eAAe;IACf,IAAI,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,QAAQ,CAAC,iBAAgC,CAAC,EAAE,CAAC;QAC1E,OAAO,QAAQ,CAAC,iBAAgC,CAAC,CAAC;IACpD,CAAC;IAED,UAAU;IACV,IACE,iBAAiB,KAAK,MAAM;QAC5B,iBAAiB,KAAK,KAAK;QAC3B,iBAAiB,KAAK,SAAS,EAC/B,CAAC;QACD,OAAO,QAAQ,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IACvC,CAAC;IACD,IAAI,iBAAiB,KAAK,SAAS,EAAE,CAAC;QACpC,OAAO,QAAQ,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,0BAA0B;IAC/D,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,wBAAwB,OAAO,EAAE,CAAC,CAAC;AACrD,CAAC;AAED,MAAM,UAAU,oBAAoB;IAClC,OAAO,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,UAAkB,eAAe;IACzD,OAAO,gBAAgB,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC;AAC5C,CAAC"}

package/build/core/prompts.d.ts

@@ -0,0 +1,16 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Register task-oriented prompts with the MCP server
+ *
+ * All prompts follow a consistent structure:
+ * - Clear objective statement
+ * - Step-by-step instructions
+ * - Expected outputs
+ * - Safety/security considerations
+ *
+ * Prompts guide the model through complex workflows that would otherwise
+ * require multiple tool calls in the correct sequence.
+ *
+ * @param server The MCP server instance
+ */
+export declare function registerTRONPrompts(server: McpServer): void;