BofAI · Hades-Ye · Mar 9, 2026 · Mar 9, 2026 · Mar 9, 2026 · Mar 9, 2026
diff --git a/docs/McpServer-Skills/MCP/SUNMCPServer/API.md b/docs/McpServer-Skills/MCP/SUNMCPServer/API.md
@@ -0,0 +1,88 @@
+# API Reference
+
+## Tools
+
+### Wallet & Address
+
+| Tool Name                  | Description                                                                 | Key Parameters |
+|---------------------------|-----------------------------------------------------------------------------|----------------|
+| sunswap_get_wallet_address | Get the active TRON wallet address (Base58) used for SUNSWAP operations.   | network        |
+
+### Balances
+
+| Tool Name           | Description                                      | Key Parameters                 |
+|--------------------|--------------------------------------------------|--------------------------------|
+| sunswap_get_balances | Get TRX and TRC20 balances for an address.      | network, ownerAddress, tokens  |
+
+### Pricing & Quoting
+
+| Tool Name                  | Description                                              | Key Parameters              |
+|---------------------------|----------------------------------------------------------|-----------------------------|
+| sunswap_get_token_price   | Get token prices from SUN.IO API by address/symbol.      | tokenAddress, symbol        |
+| sunswap_quote_exact_input | Quote exact-input swap via a router’s view function.      | network, routerAddress, args, abi |
+
+### Smart Contracts (Read)
+
+| Tool Name             | Description                                           | Key Parameters                    |
+|----------------------|-------------------------------------------------------|-----------------------------------|
+| sunswap_read_contract | Call view/pure functions on a TRON contract.          | network, address, functionName, args, abi |
+
+### Smart Contracts (Write)
+
+| Tool Name              | Description                                           | Key Parameters                         |
+|------------------------|-------------------------------------------------------|----------------------------------------|
+| sunswap_send_contract  | Execute a state-changing contract function.           | network, address, functionName, args, value, abi |
+
+### Swaps
+
+| Tool Name                 | Description                                                                 | Key Parameters                                    |
+|---------------------------|-----------------------------------------------------------------------------|---------------------------------------------------|
+| sunswap_swap              | Execute a swap via Universal Router (tokenIn, tokenOut, amountIn).         | tokenIn, tokenOut, amountIn, network, slippage    |
+| sunswap_swap_exact_input  | Execute router swapExactInput with explicit router and args.                | network, routerAddress, functionName, args, value, abi |
+
+### V2 Liquidity
+
+| Tool Name                     | Description                                                                 | Key Parameters                                                                 |
+|------------------------------|-----------------------------------------------------------------------------|--------------------------------------------------------------------------------|
+| sunswap_v2_add_liquidity     | Add liquidity to a V2 pool; uses addLiquidityETH if one token is native TRX. | network, routerAddress, tokenA, tokenB, amountADesired, amountBDesired, to, deadline |
+| sunswap_v2_remove_liquidity  | Remove V2 liquidity; uses removeLiquidityETH if one token is TRX.           | network, routerAddress, tokenA, tokenB, liquidity, to, deadline               |
+
+### V3 Liquidity
+
+| Tool Name                       | Description                                  | Key Parameters                                                                 |
+|--------------------------------|----------------------------------------------|--------------------------------------------------------------------------------|
+| sunswap_v3_mint_position       | Mint a new V3 concentrated liquidity position. | network, positionManagerAddress, token0, token1, fee, tickLower, tickUpper, amount0Desired, amount1Desired, recipient, deadline |
+| sunswap_v3_increase_liquidity  | Increase liquidity of an existing V3 position. | network, positionManagerAddress, tokenId, amount0Desired, amount1Desired, amount0Min, amount1Min, deadline |
+| sunswap_v3_decrease_liquidity  | Decrease liquidity of an existing V3 position. | network, positionManagerAddress, tokenId, liquidity, amount0Min, amount1Min, deadline |
+
+## OpenAPI-Derived Tools (SUN.IO API)
+
+Tools are generated from `specs/sunio-open-api.json`. Naming follows the spec; parameters map to the corresponding API. Main groups:
+
+- **Transactions**: scanTransactions
+- **Tokens**: getTokens, searchTokens
+- **Protocols**: getProtocol, getVolHistory, getUsersCountHistory, getTransactionsHistory, getPoolsCountHistory, getLiqHistory
+- **Prices**: getPrice
+- **Positions**: getUserPositions, getPoolUserPositionTick
+- **Pools**: getPools, getTopApyPoolList, searchPools, searchCountPools, getPoolHooks, getPoolVolHistory, getPoolLiqHistory
+- **Pairs**: getPairsFromEntity
+- **Farms**: getFarms, getFarmTransactions, getFarmPositions
+
+## Default Contract Addresses
+
+Defined in `src/sunswap/constants.ts`:
+
+- **V2 Mainnet**: Factory, Router
+- **V2 Nile**: Factory, Router
+- **V3 Mainnet**: Factory, NonfungiblePositionManager
+- **V3 Nile**: Factory, NonfungiblePositionManager
+- **TRX**: `T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb`
+- **WTRX** (mainnet/Nile): Used internally for TRX-pair lookups
+
+Tool callers can rely on these defaults by passing `network` and token addresses, or override router/position-manager addresses and ABIs via tool parameters.
+
+## Network Parameter
+
+Where applicable, tools accept:
+
+- **network** (optional): `mainnet` (default), `nile`, or `shasta`.
diff --git a/docs/McpServer-Skills/MCP/SUNMCPServer/Configuration.md b/docs/McpServer-Skills/MCP/SUNMCPServer/Configuration.md
@@ -0,0 +1,122 @@
+# Configuration
+
+## Environment Variables
+
+**Security**: Do not store private keys or mnemonics in MCP config files (e.g. `claude_desktop_config.json` or `mcp.json`). Set them as environment variables in your OS or shell.
+
+### Network & API
+
+- **TRONGRID_API_KEY** (optional): TronGrid API key for mainnet RPC. Reduces rate limits and improves reliability.
+- **TRON_RPC_URL** (optional): Override TRON RPC base URL; replaces default fullNode/solidityNode/eventServer for the chosen network.
+
+### Wallet (for write operations)
+
+**Option 1: Private key**
+
+```bash
+export TRON_PRIVATE_KEY="<YOUR_PRIVATE_KEY_HEX>"
+```
+
+**Option 2: Mnemonic**
+
+```bash
+export TRON_MNEMONIC="word1 word2 ... word12"
+export TRON_ACCOUNT_INDEX="0"   # Optional; default 0
+```
+
+If neither is set and no Agent Wallet provider is supplied, write tools (transfers, swaps, liquidity) will fail with a “no wallet” error.
+
+### Server & OpenAPI
+
+- **OPENAPI_SPEC_PATH**: Path to OpenAPI spec (default from `config.json`, e.g. `./specs/sunio-open-api.json`).
+- **TARGET_API_BASE_URL**: SUN.IO API base URL (default from config, e.g. `https://open.sun.io`).
+- **MCP_TRANSPORT**: `stdio` or `streamable-http`.
+- **MCP_SERVER_HOST**, **MCP_SERVER_PORT**, **MCP_SERVER_PATH**: Used when transport is `streamable-http`.
+- **MCP_WHITELIST_OPERATIONS**, **MCP_BLACKLIST_OPERATIONS**: Filter which OpenAPI operations are exposed as tools.
+- **TARGET_API_TIMEOUT_MS**: Request timeout for SUN.IO API calls.
+
+Configuration priority: CLI arguments &gt; environment variables &gt; `config.json`.
+
+## Server Modes
+
+- **stdio** (default): For local MCP clients. Start with `npm start`.
+- **streamable-http**: For HTTP/SSE clients. Start with:
+
+  ```bash
+  npm start -- --transport streamable-http --host 127.0.0.1 --port 8080 --mcpPath /mcp
+  ```
+
+## Client Configuration
+
+### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the equivalent path on your OS:
+
+```json
+{
+  "mcpServers": {
+    "sun-mcp-server": {
+      "command": "node",
+      "args": ["/ABSOLUTE/PATH/TO/sun-mcp-server/dist/src/server.js"],
+      "env": {
+        "OPENAPI_SPEC_PATH": "/ABSOLUTE/PATH/TO/sun-mcp-server/specs/sunio-open-api.json",
+        "TARGET_API_BASE_URL": "https://open.sun.io"
+      },
+      "enabled": true
+    }
+  }
+}
+```
+
+Omit `env` for wallet keys if they are already set in your shell.
+
+### Cursor
+
+Project root `.cursor/mcp.json`:
+
+```json
+{
+  "servers": [
+    {
+      "name": "sun-mcp-server",
+      "command": "node",
+      "args": ["/ABSOLUTE/PATH/TO/sun-mcp-server/dist/src/server.js"],
+      "env": {
+        "OPENAPI_SPEC_PATH": "/ABSOLUTE/PATH/TO/sun-mcp-server/specs/sunio-open-api.json",
+        "TARGET_API_BASE_URL": "https://open.sun.io"
+      }
+    }
+  ]
+}
+```
+
+### HTTP (streamable-http)
+
+When using HTTP transport, call the MCP endpoint with:
+
+- **Accept**: `application/json, text/event-stream`
+- **Content-Type**: `application/json`
+
+Example (tools/call):
+
+```bash
+curl -X POST "http://127.0.0.1:8080/mcp" \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "1",
+    "method": "tools/call",
+    "params": {
+      "name": "sunswap_v2_add_liquidity",
+      "arguments": {
+        "network": "nile",
+        "routerAddress": "TMn1qrmYUMSTXo9babrJLzepKZoPC7M6Sy",
+        "tokenA": "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf",
+        "tokenB": "TWMCMCoJPqCGw5RR7eChF2HoY3a9B8eYA3",
+        "amountADesired": "1000000",
+        "amountBDesired": "1500000"
+      }
+    }
+  }'
+```
diff --git a/docs/McpServer-Skills/MCP/SUNMCPServer/Features.md b/docs/McpServer-Skills/MCP/SUNMCPServer/Features.md
@@ -0,0 +1,60 @@
+# Features
+
+## SUN.IO API (Read-Only)
+
+Tools are generated from `specs/sunio-open-api.json` and target the SUN.IO public API. Supported domains include:
+
+- **Transactions**: Scan swap/add/withdraw activity with pagination.
+- **Tokens**: Fetch token metadata and search tokens.
+- **Protocols**: Protocol snapshots and historical KPI (volume, users, transactions, pools, liquidity).
+- **Prices**: Token price by address.
+- **Positions**: User liquidity positions and pool tick-level data.
+- **Pools**: List/search pools, top APY, hooks, volume and liquidity history.
+- **Pairs**: Token pair information.
+- **Farms**: Farm list, farm transactions, user farm positions.
+
+## SUNSWAP Custom Tools
+
+### Wallet & Balances
+
+- **sunswap_get_wallet_address**: Resolve the active TRON wallet (local key/mnemonic or Agent Wallet).
+- **sunswap_get_balances**: TRX and TRC20 balances for an address (default: active wallet).
+
+### Pricing & Quoting
+
+- **sunswap_get_token_price**: Token prices from SUN.IO API by address and/or symbol.
+- **sunswap_quote_exact_input**: Quote exact-input swap via a given router’s view function.
+
+### Smart Contract Interaction
+
+- **sunswap_read_contract**: Call view/pure functions on any TRON contract (uses solidity-node read path where applicable).
+- **sunswap_send_contract**: Execute state-changing contract calls with optional TRX value.
+
+### Swaps
+
+- **sunswap_swap**: High-level swap via Universal Router; only needs tokenIn, tokenOut, amountIn (optional network/slippage).
+- **sunswap_swap_exact_input**: Low-level router swap by router address, function name, and ABI-ordered args.
+
+### V2 Liquidity
+
+- **sunswap_v2_add_liquidity**: Add liquidity to a V2 pool. If one token is native TRX (`T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb`), uses addLiquidityETH; otherwise addLiquidity. Optimal amounts are computed from pool reserves to match ratio; TRC20 approvals are handled automatically.
+- **sunswap_v2_remove_liquidity**: Remove V2 liquidity. Uses removeLiquidityETH when one side is TRX. LP allowance and amountMin/amountBMin (from reserves + slippage) are handled automatically.
+
+### V3 Liquidity
+
+- **sunswap_v3_mint_position**: Mint a new V3 concentrated liquidity position (NonfungiblePositionManager). Auto-approval for token0/token1; optional amountMin and deadline defaults.
+- **sunswap_v3_increase_liquidity**: Add liquidity to an existing V3 position.
+- **sunswap_v3_decrease_liquidity**: Decrease liquidity of an existing V3 position.
+
+## Supported Networks
+
+| Network   | Identifier   | Notes                    |
+|----------|--------------|--------------------------|
+| Mainnet  | `mainnet`    | Default                  |
+| Nile     | `nile`       | Testnet                  |
+| Shasta   | `shasta`     | Testnet                  |
+
+## Transport
+
+- **stdio**: Default; for local MCP clients (e.g. Claude Desktop, Cursor).
+- **streamable-http**: HTTP + Server-Sent Events for remote clients; configurable host, port, and path.
diff --git a/docs/McpServer-Skills/MCP/SUNMCPServer/Installation.md b/docs/McpServer-Skills/MCP/SUNMCPServer/Installation.md
@@ -0,0 +1,37 @@
+# Installation
+
+## Prerequisites
+
+- **Node.js** 20.0.0 or higher.
+- **npm** (or compatible package manager).
+- Optional: **TronGrid API key** for higher rate limits and stability on mainnet.
+
+## Run Installation
+
+```bash
+# Clone the repository
+git clone <your-repo-url>
+cd sun-mcp-server
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+```
+
+## Verify
+
+```bash
+# Run tests
+npm test
+
+# Start server (stdio)
+npm start
+```
+
+For HTTP (streamable-http) mode:
+
+```bash
+npm start -- --transport streamable-http --host 127.0.0.1 --port 8080 --mcpPath /mcp
+```
diff --git a/docs/McpServer-Skills/MCP/SUNMCPServer/Intro.md b/docs/McpServer-Skills/MCP/SUNMCPServer/Intro.md
@@ -0,0 +1,34 @@
+# Introduction
+
+A Model Context Protocol (MCP) server focused on the **SUN.IO (SUNSWAP)** ecosystem on the TRON network. It enables AI agents to query SUN.IO API data (tokens, pools, prices, protocol metrics, transactions, farming, contracts) and to execute DeFi operations such as swaps and V2/V3 liquidity management through a unified tool interface.
+
+The SUN MCP Server uses the [Model Context Protocol](https://modelcontextprotocol.io/) to expose blockchain and API services to MCP-compatible clients (e.g. Claude Desktop, Cursor, Google Antigravity). It combines:
+
+- **OpenAPI-derived tools** from the SUN.IO public API spec (`specs/sunio-open-api.json`) for read-only queries.
+- **Custom SUNSWAP tools** (`sunswap_*`) for wallet, balances, quoting, swaps, and V2/V3 liquidity, backed by `tronweb` and on-chain contract calls.
+
+## Key Features
+
+- **SUN.IO API**: Query tokens, pools, prices, protocol history, positions, farms, and transactions.
+- **Smart contracts**: Read and write TRON contracts; automatic TRC20 approval checks for liquidity and swap flows.
+- **Tokens & swaps**: Get TRX/TRC20 balances; quote and execute swaps via Universal Router or custom router.
+- **Liquidity**: Add/remove V2 liquidity (including native TRX via addLiquidityETH/removeLiquidityETH); mint, increase, and decrease V3 positions with automatic amount and slippage handling.
+- **Wallet**: Private key or BIP-39 mnemonic; optional Agent Wallet provider for remote signing.
+- **Multi-network**: Mainnet, Nile, and Shasta with configurable RPC and TronGrid API key.
+
+## MCP Server URL
+
+|Environment|url|
+|:---|:---|
+|Production|[sun-mcp-server.bankofai.io/mcp](sun-mcp-server.bankofai.io/mcp)|
+
+## Security Considerations
+
+- **Private key management**: Configure `TRON_PRIVATE_KEY` or `TRON_MNEMONIC` via environment variables only. Do not hardcode them or store them in config files that may be committed.
+- **Testnet first**: Test on Nile or Shasta before performing mainnet operations.
+- **Least privilege**: Use wallets with only the minimum funds needed for the agent’s tasks.
+- **Audit**: Consider a security review of the server and integration before production use.
+
+## License
+
+This project is released under the MIT License.
diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/Intro.md b/docs/McpServer-Skills/MCP/TRONMCPServer/Intro.md
@@ -13,6 +13,12 @@ The TRON MCP server leverages the Model Context Protocol to deliver blockchain s
 - **Wallet Integration**: Supports private key and mnemonic (BIP-39) wallets.
 - **Multi-Network**: Seamless support for Mainnet, Nile, and Shasta.
 
+## MCP Server URL
+
+| Environment | url                                                                |
+| :---------- | :----------------------------------------------------------------- |
+| Production  | [tron-mcp-server.bankofai.io/mcp](tron-mcp-server.bankofai.io/mcp) |
+
 ## Security Considerations
 
 - **Private Key Management**: Private keys and mnemonics should always be managed securely via environment variables. Never hardcode them or store them in insecure files.