mcp-server-tron: Instructions file for Codex

Agent Guidelines: MCP Server Tron

This document provides essential information for AI agents working on this repository.

🛠 Commands

Development & Build

• Build: npm run build (runs tsc)
• Lint: npm run lint (runs eslint)
• Fix Lint: npm run lint:fix
• Clean: rm -rf build

Testing

• Run all tests: npm test (runs vitest run)
• Run specific test file: npx vitest tests/core/services/utils.test.ts
• Run with UI: npx vitest --ui
• Watch mode: npx vitest

Execution

• Start (Stdio): npm start (uses tsx to run src/index.ts)
• Start (HTTP): npm run start:http
• Read-only mode: Add --readonly or -r to disable write tools (e.g., npm start -- --readonly)
• Inspect: npm run inspect (launches MCP Inspector)

---

🎨 Code Style & Conventions

📦 Imports

• Use ES Modules (import/export).
• When importing from local files, follow NodeNext resolution: use .js extension in the import path (e.g., import { foo } from "./foo.js").
• Organize imports: built-ins first, then external libraries, then internal modules.

🏷 Naming Conventions

• Files: kebab-case.ts (e.g., http-server.ts).
• Tests: name.test.ts or name_integration.ts.
• Variables/Functions: camelCase.
• Classes/Interfaces: PascalCase.
• MCP Tools: snake_case (e.g., get_wallet_address).
• Constants: UPPER_SNAKE_CASE.

🏗 Architecture

• src/core/services: Contains the business logic and TronWeb integrations.
• src/core/tools/: MCP tool definitions split by category (wallet, network, address, block, balance, transaction, contract, transfer, staking, account), with schema validation using zod.
• src/core/prompts.ts: MCP prompt definitions.
• src/server: Protocol-specific server implementations (Stdio/HTTP).

🚦 Error Handling

• Services: Throw descriptive Error objects.
• Tools: Use try-catch blocks. Return isError: true and a structured error message in the content array if an operation fails.
• Avoid process.exit() in library code; let the server handle fatal errors.