From 11787f5930f45c95757a2892a30ffaee48d86191 Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Tue, 17 Mar 2026 22:31:42 +0800 Subject: [PATCH 1/5] fix --- .github/workflows/docker.yml | 78 +++ docs/McpServer-Skills/Intro.md | 12 + docs/McpServer-Skills/MCP/SUNMCPServer/API.md | 160 ----- docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md | 579 ++++++++++++++++++ .../MCP/SUNMCPServer/Intro.md | 149 +++-- .../SUNMCPServer/LocalPrivatizedDeployment.md | 431 ++++++++++--- .../MCP/SUNMCPServer/OfficialServerAccess.md | 199 +++++- .../MCP/SUNMCPServer/QuickStart.md | 119 ++++ .../MCP/SUNMCPServer/ToolList.md | 354 +++++++++++ .../McpServer-Skills/MCP/TRONMCPServer/API.md | 216 ------- .../McpServer-Skills/MCP/TRONMCPServer/FAQ.md | 242 ++++++++ .../MCP/TRONMCPServer/Intro.md | 122 ++-- .../LocalPrivatizedDeployment.md | 326 ++++++++-- .../MCP/TRONMCPServer/OfficialServerAccess.md | 209 ++++++- .../MCP/TRONMCPServer/QuickStart.md | 126 ++++ .../MCP/TRONMCPServer/ToolList.md | 368 +++++++++++ docs/McpServer-Skills/SKILLS/BANKOFAISkill.md | 303 ++++----- docs/McpServer-Skills/SKILLS/Faq.md | 196 ++++-- docs/McpServer-Skills/SKILLS/Intro.md | 173 ++++-- docs/Openclaw-extension/FAQ.md | 228 +++++++ docs/Openclaw-extension/Intro.md | 61 ++ docs/Openclaw-extension/Overview.md | 66 -- docs/Openclaw-extension/QuickStart.md | 143 +++++ docs/Openclaw-extension/Setup-use.md | 74 --- .../getting-started/quickstart-for-human.md | 2 +- .../getting-started/quickstart-for-sellers.md | 366 +++++------ .../current/McpServer-Skills/Intro.md | 16 +- .../McpServer-Skills/MCP/SUNMCPServer/API.md | 156 ----- .../McpServer-Skills/MCP/SUNMCPServer/FAQ.md | 579 ++++++++++++++++++ .../MCP/SUNMCPServer/Intro.md | 150 +++-- .../SUNMCPServer/LocalPrivatizedDeployment.md | 432 ++++++++++--- .../MCP/SUNMCPServer/OfficialServerAccess.md | 196 +++++- .../MCP/SUNMCPServer/QuickStart.md | 119 ++++ .../MCP/SUNMCPServer/ToolList.md | 354 +++++++++++ .../McpServer-Skills/MCP/TRONMCPServer/API.md | 216 ------- .../McpServer-Skills/MCP/TRONMCPServer/FAQ.md | 242 ++++++++ .../MCP/TRONMCPServer/Intro.md | 122 ++-- .../LocalPrivatizedDeployment.md | 328 ++++++++-- .../MCP/TRONMCPServer/OfficialServerAccess.md | 210 ++++++- .../MCP/TRONMCPServer/QuickStart.md | 126 ++++ .../MCP/TRONMCPServer/ToolList.md | 367 +++++++++++ .../McpServer-Skills/SKILLS/BANKOFAISkill.md | 302 ++++----- .../current/McpServer-Skills/SKILLS/Faq.md | 197 ++++-- .../current/McpServer-Skills/SKILLS/Intro.md | 171 ++++-- .../current/Openclaw-extension/FAQ.md | 229 +++++++ .../current/Openclaw-extension/Intro.md | 61 ++ .../current/Openclaw-extension/Overview.md | 65 -- .../current/Openclaw-extension/QuickStart.md | 142 +++++ .../current/Openclaw-extension/Setup-use.md | 74 --- .../current/sidebars.js | 11 +- .../getting-started/quickstart-for-human.md | 2 +- .../getting-started/quickstart-for-sellers.md | 15 +- sidebars.js | 12 +- 53 files changed, 7818 insertions(+), 2378 deletions(-) create mode 100644 .github/workflows/docker.yml delete mode 100644 docs/McpServer-Skills/MCP/SUNMCPServer/API.md create mode 100644 docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md create mode 100644 docs/McpServer-Skills/MCP/SUNMCPServer/QuickStart.md create mode 100644 docs/McpServer-Skills/MCP/SUNMCPServer/ToolList.md delete mode 100644 docs/McpServer-Skills/MCP/TRONMCPServer/API.md create mode 100644 docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md create mode 100644 docs/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md create mode 100644 docs/McpServer-Skills/MCP/TRONMCPServer/ToolList.md create mode 100644 docs/Openclaw-extension/FAQ.md create mode 100644 docs/Openclaw-extension/Intro.md delete mode 100644 docs/Openclaw-extension/Overview.md create mode 100644 docs/Openclaw-extension/QuickStart.md delete mode 100644 docs/Openclaw-extension/Setup-use.md delete mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/API.md create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/FAQ.md create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/QuickStart.md create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/ToolList.md delete mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/API.md create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/ToolList.md create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/FAQ.md create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/Intro.md delete mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/Overview.md create mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/QuickStart.md delete mode 100644 i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/Setup-use.md diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml new file mode 100644 index 00000000..9ece33f5 --- /dev/null +++ b/.github/workflows/docker.yml @@ -0,0 +1,78 @@ +name: Build and Push Docker Image + +on: + push: + branches: + - main + - master + tags: + - 'v*.*.*' + pull_request: + branches: + - main + - master + workflow_dispatch: + +env: + REGISTRY: ghcr.io + IMAGE_NAME: ${{ github.repository }} + +jobs: + build-and-push: + name: Build and Push Docker Image + runs-on: ubuntu-latest + permissions: + contents: read + packages: write + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + + - name: Log in to GitHub Container Registry + if: github.event_name != 'pull_request' + uses: docker/login-action@v3 + with: + registry: ${{ env.REGISTRY }} + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + + - name: Extract Docker metadata + id: meta + uses: docker/metadata-action@v5 + with: + images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }} + tags: | + type=ref,event=branch + type=ref,event=pr + type=semver,pattern={{version}} + type=semver,pattern={{major}}.{{minor}} + type=sha,prefix=sha- + type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master' }} + + - name: Determine APP_ENV + id: app_env + run: | + if [[ "${{ github.ref }}" == "refs/heads/main" || "${{ github.ref }}" == "refs/heads/master" ]]; then + echo "APP_ENV=production" >> $GITHUB_OUTPUT + elif [[ "${{ github.ref }}" == refs/tags/* ]]; then + echo "APP_ENV=production" >> $GITHUB_OUTPUT + else + echo "APP_ENV=development" >> $GITHUB_OUTPUT + fi + + - name: Build and push Docker image + uses: docker/build-push-action@v6 + with: + context: . + push: ${{ github.event_name != 'pull_request' }} + tags: ${{ steps.meta.outputs.tags }} + labels: ${{ steps.meta.outputs.labels }} + build-args: | + APP_ENV=${{ steps.app_env.outputs.APP_ENV }} + cache-from: type=gha + cache-to: type=gha,mode=max + platforms: linux/amd64,linux/arm64 diff --git a/docs/McpServer-Skills/Intro.md b/docs/McpServer-Skills/Intro.md index 90c813df..d5f772af 100644 --- a/docs/McpServer-Skills/Intro.md +++ b/docs/McpServer-Skills/Intro.md @@ -3,3 +3,15 @@ BANK OF AI provides a complete solution, from infrastructure to business logic, for building autonomous AI Agents based on blockchain networks through a dual-layer architecture of MCP Server and Skills. Developers only need to deploy the MCP Server and load the corresponding Skills to evolve AI agents from "chatbots" into Web3 economic entities with asset management capabilities and on-chain interaction abilities. + +## Architecture Overview + +| Layer | Component | Role | +| :--- | :--- | :--- | +| Infrastructure Layer | **MCP Server** | Provides AI agents with low-level capabilities for blockchain interaction (querying data, initiating transactions, calling contracts, etc.) | +| Business Logic Layer | **Skills** | Provides AI agents with domain-specific operation guides and workflows (e.g., DEX trading, payment protocols, etc.) | + +## Quick Navigation + +- **Learn about MCP Server**: Go to [MCP Server Introduction](./MCP/Intro.md) to understand the protocol architecture and communication mechanisms. +- **Learn about Skills**: Go to [Skills Introduction](./SKILLS/Intro.md) to understand the design philosophy and usage of skill packages. diff --git a/docs/McpServer-Skills/MCP/SUNMCPServer/API.md b/docs/McpServer-Skills/MCP/SUNMCPServer/API.md deleted file mode 100644 index 804c3f09..00000000 --- a/docs/McpServer-Skills/MCP/SUNMCPServer/API.md +++ /dev/null @@ -1,160 +0,0 @@ -# API Reference - -## Tools - -### Wallet & Address - -| Tool Name | Description | Key Parameters | Mode | -| :-- | :-- | :-- | :-- | -| `sunswap_get_wallet_address` | Get the active TRON wallet address (Base58) used for SUNSWAP operations. | `network?` | Read | -| `sunswap_list_wallets` | List all available wallets (agent-wallet mode only). | - | Read | -| `sunswap_select_wallet` | Switch the active wallet (agent-wallet mode only). | `walletId` | Write | - -### Balances - -| Tool Name | Description | Key Parameters | Mode | -| :-- | :-- | :-- | :-- | -| `sunswap_get_balances` | Get TRX and TRC20 balances for a wallet. | `tokens`, `network?`, `ownerAddress?` | Read | - -### Pricing & Quoting - -| Tool Name | Description | Key Parameters | Mode | -| :-- | :-- | :-- | :-- | -| `sunswap_get_token_price` | Get token prices from SUN.IO API by address/symbol. | `tokenAddress?`, `symbol?` | Read | -| `sunswap_quote_exact_input` | Get swap quote from the smart router. | `routerAddress`, `args`, `network?`, `functionName?`, `abi?` | Read | - -### Smart Contracts (Read) - -| Tool Name | Description | Key Parameters | Mode | -| :-- | :-- | :-- | :-- | -| `sunswap_read_contract` | Read data from a TRON smart contract (view/pure functions). | `address`, `functionName`, `network?`, `args?`, `abi?` | Read | - -### Smart Contracts (Write) - -| Tool Name | Description | Key Parameters | Mode | -| :-- | :-- | :-- | :-- | -| `sunswap_send_contract` | Execute a state-changing contract transaction. | `address`, `functionName`, `network?`, `args?`, `value?`, `abi?` | Write | - -### Swaps - -| Tool Name | Description | Key Parameters | Mode | -| :-- | :-- | :-- | :-- | -| `sunswap_swap` | Execute a token swap via Universal Router. Automatically finds best route and handles Permit2. | `tokenIn`, `tokenOut`, `amountIn`, `network?`, `slippage?` | Write | -| `sunswap_swap_exact_input` | Low-level router swap with full control. | `routerAddress`, `args`, `network?`, `functionName?`, `value?`, `abi?` | Write | - -### V2 Liquidity - -| Tool Name | Description | Key Parameters | Mode | -| :-- | :-- | :-- | :-- | -| `sunswap_v2_add_liquidity` | Add liquidity to a V2 pool. Automatically handles TRX via `addLiquidityETH`. | `routerAddress`, `tokenA`, `tokenB`, `amountADesired`, `amountBDesired`, `network?`, `amountAMin?`, `amountBMin?`, `to?`, `deadline?`, `abi?` | Write | -| `sunswap_v2_remove_liquidity` | Remove liquidity from a V2 pool. | `routerAddress`, `tokenA`, `tokenB`, `liquidity`, `network?`, `amountAMin?`, `amountBMin?`, `to?`, `deadline?`, `abi?` | Write | - -### V3 Liquidity - -| Tool Name | Description | Key Parameters | Mode | -| :-- | :-- | :-- | :-- | -| `sunswap_v3_mint_position` | Mint a new V3 concentrated liquidity position with auto-compute features. | `positionManagerAddress`, `token0`, `token1`, `network?`, `fee?`, `tickLower?`, `tickUpper?`, `amount0Desired?`, `amount1Desired?`, `amount0Min?`, `amount1Min?`, `recipient?`, `deadline?`, `abi?` | Write | -| `sunswap_v3_increase_liquidity` | Add liquidity to an existing V3 position. | `positionManagerAddress`, `tokenId`, `network?`, `token0?`, `token1?`, `fee?`, `amount0Desired?`, `amount1Desired?`, `amount0Min?`, `amount1Min?`, `deadline?` | Write | -| `sunswap_v3_decrease_liquidity` | Remove liquidity from an existing V3 position. | `positionManagerAddress`, `tokenId`, `liquidity`, `network?`, `token0?`, `token1?`, `fee?`, `amount0Min?`, `amount1Min?`, `deadline?` | Write | -| `sunswap_v3_collect` | Collect accrued fees from a V3 position. | `positionManagerAddress`, `tokenId`, `network?`, `recipient?` | Write | - -### V4 Liquidity - -| Tool Name | Description | Key Parameters | Mode | -| :-- | :-- | :-- | :-- | -| `sunswap_v4_mint_position` | Mint a new V4 concentrated liquidity position with Permit2 authorization. | `token0`, `token1`, `network?`, `fee?`, `tickLower?`, `tickUpper?`, `amount0Desired?`, `amount1Desired?`, `slippage?`, `recipient?`, `deadline?`, `sqrtPriceX96?`, `createPoolIfNeeded?` | Write | -| `sunswap_v4_increase_liquidity` | Increase liquidity of an existing V4 position. | `tokenId`, `token0`, `token1`, `network?`, `fee?`, `amount0Desired?`, `amount1Desired?`, `slippage?`, `deadline?` | Write | -| `sunswap_v4_decrease_liquidity` | Decrease liquidity of an existing V4 position. | `tokenId`, `liquidity`, `token0`, `token1`, `network?`, `fee?`, `amount0Min?`, `amount1Min?`, `slippage?`, `deadline?` | Write | -| `sunswap_v4_collect` | Collect accrued fees from a V4 position. | `tokenId`, `network?`, `token0?`, `token1?`, `fee?`, `deadline?` | Write | - ---- - -## 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. - -### Transactions - -| Tool Name | Description | Key Parameters | Mode | -| :-- | :-- | :-- | :-- | -| `scanTransactions` | Scan DEX transactions by protocol, token/pool, type, and time range. | `protocol?`, `token?`, `pool?`, `type?`, `timeRange?` | Read | - -### Tokens - -| Tool Name | Description | Key Parameters | Mode | -| :-- | :-- | :-- | :-- | -| `getTokens` | Fetch tokens by address and protocol. | `address?`, `protocol?` | Read | -| `searchTokens` | Fuzzy token search by keyword. | `keyword` | Read | - -### Protocols - -| Tool Name | Description | Key Parameters | Mode | -| :-- | :-- | :-- | :-- | -| `getProtocol` | Protocol snapshot data. | - | Read | -| `getVolHistory` | Protocol volume history. | - | Read | -| `getUsersCountHistory` | Protocol users history. | - | Read | -| `getTransactionsHistory` | Protocol transaction count history. | - | Read | -| `getPoolsCountHistory` | Protocol pool count history. | - | Read | -| `getLiqHistory` | Protocol liquidity history. | - | Read | - -### Prices - -| Tool Name | Description | Key Parameters | Mode | -| :-- | :-- | :-- | :-- | -| `getPrice` | Token price query. | `tokenAddress` | Read | - -### Positions - -| Tool Name | Description | Key Parameters | Mode | -| :-- | :-- | :-- | :-- | -| `getUserPositions` | User liquidity positions. | `userAddress` | Read | -| `getPoolUserPositionTick` | Pool tick-level position/liquidity details. | `poolAddress`, `userAddress` | Read | - -### Pools - -| Tool Name | Description | Key Parameters | Mode | -| :-- | :-- | :-- | :-- | -| `getPools` | Fetch pools by address, token, or protocol. | `address?`, `token?`, `protocol?` | Read | -| `getTopApyPoolList` | Paginated top APY pools. | `limit?`, `offset?` | Read | -| `searchPools` | Pool search endpoint. | `keyword` | Read | -| `searchCountPools` | Pool search count endpoint. | `keyword` | Read | -| `getPoolHooks` | Pool hooks list. | `poolAddress` | Read | -| `getPoolVolHistory` | Pool volume history. | `poolAddress` | Read | -| `getPoolLiqHistory` | Pool liquidity history. | `poolAddress` | Read | - -### Pairs - -| Tool Name | Description | Key Parameters | Mode | -| :-- | :-- | :-- | :-- | -| `getPairsFromEntity` | Token pair entity query. | `token0?`, `token1?` | Read | - -### Farms - -| Tool Name | Description | Key Parameters | Mode | -| :-- | :-- | :-- | :-- | -| `getFarms` | Farming pool list. | - | Read | -| `getFarmTransactions` | Farm transaction scanning. | `farmAddress` | Read | -| `getFarmPositions` | User farming positions. | `userAddress` | Read | - ---- - -## Default Contract Addresses - -Defined in `src/sunswap/constants.ts`: - -- **V2 Mainnet**: Factory (`SUNSWAP_V2_MAINNET_FACTORY`), Router (`SUNSWAP_V2_MAINNET_ROUTER`) -- **V2 Nile**: Factory (`SUNSWAP_V2_NILE_FACTORY`), Router (`SUNSWAP_V2_NILE_ROUTER`) -- **V3 Mainnet**: Factory (`SUNSWAP_V3_MAINNET_FACTORY`), Position Manager (`SUNSWAP_V3_MAINNET_POSITION_MANAGER`) -- **V3 Nile**: Factory (`SUNSWAP_V3_NILE_FACTORY`), Position Manager (`SUNSWAP_V3_NILE_POSITION_MANAGER`) -- **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/FAQ.md b/docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md new file mode 100644 index 00000000..f8047732 --- /dev/null +++ b/docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md @@ -0,0 +1,579 @@ +--- +title: FAQ & Troubleshooting +description: SUN MCP Server FAQ covering connection, authentication, DeFi operations and troubleshooting. +--- + +# FAQ & Troubleshooting + +This page collects frequently asked questions when using SUN MCP Server and their solutions. + +## Connection Issues + +### Claude Desktop "Cannot Connect to MCP Server" + +**Symptom:** Claude Desktop shows server unresponsive or connection refused. + +**Resolution Steps:** + +1. **Check Node.js Installation** + ```bash + node --version # Should return v18+ + npm --version + ``` + +2. **Verify Server Running** + ```bash + # If using official server + npx -y @bankofai/sun-mcp-server + + # If using local deployment + npm start + ``` + +3. **Check JSON Format** + - Verify JSON format of `stdio.json` in Claude Desktop configuration + - Common errors: trailing commas, unmatched brackets + +4. **Restart Claude Desktop** + - Completely close application + - Clear cache: delete temporary files in `~/.claude` directory + - Restart application + +5. **Check Server Logs** + ```bash + # If using official server, enable verbose logging + DEBUG=* npx -y @bankofai/sun-mcp-server + ``` + +**If issue persists:** See [Official Server Access Guide](OfficialServerAccess.md) for latest configuration examples. + +### "Connection Refused" in HTTP Mode + +**Symptom:** Getting connection refused error when trying to connect via HTTP. + +**Common Causes and Solutions:** + +1. **Server Not Running** + ```bash + # Start server in HTTP mode + sun-mcp-server --http --port 8080 + ``` + +2. **Port 8080 Already in Use** + ```bash + # Check port usage + lsof -i :8080 + + # Use different port + sun-mcp-server --http --port 8081 + ``` + +3. **Firewall Blocking Connection** + - Check local firewall rules + - Ensure localhost:8080 connection is allowed + - On macOS: System Settings > Security & Privacy > Firewall + +4. **Confirm Server Address** + - Use `http://localhost:8080` rather than `127.0.0.1:8080` + - Ensure no typos + +### Only Read Tools in Tool List + +**Symptom:** Cannot see `sunswap_swap`, `sunswap_add_liquidity` and other write tools. + +**Cause:** No wallet configured. + +**Solution:** + +1. **Configure Agent Wallet** + ```bash + export AGENT_WALLET_PASSWORD="your_secure_password" + ``` + +2. **Or Configure Private Key (Testnet Only)** + ```bash + export TRON_PRIVATE_KEY="your_64_hex_char_private_key" + ``` + +3. **Or Configure Mnemonic** + ```bash + export TRON_MNEMONIC="word1 word2 ... word12" + ``` + +4. **Restart server** and reconnect Claude Desktop + +Verify successful configuration by checking [Full Capability List](ToolList.md) for Full Capability List. + +## Authentication and Key Issues + +### "Invalid Private Key" Error + +**Symptom:** Server rejects provided private key. + +**Private Key Format Requirements:** +- Must be 64 hexadecimal characters (excluding `0x` prefix) +- Valid range: `0x0000000000000000000000000000000000000000000000000000000000000001` to `0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364140` + +**Verification Steps:** +```bash +# Check private key length +echo -n "your_private_key" | wc -c +# Should output 64 + +# Check if valid hexadecimal +echo "your_private_key" | grep -E '^[0-9a-fA-F]{64}$' +# If output exists, format is correct +``` + +**Common Errors:** +- Contains `0x` prefix (remove it) +- Length less than 64 characters (get complete key from export tool) +- Contains spaces or special characters + +### "Agent Wallet Password Incorrect" + +**Symptom:** Server cannot decrypt Agent Wallet. + +**Resolution Steps:** + +1. **Verify Password Environment Variable** + ```bash + echo $AGENT_WALLET_PASSWORD + # Should output your password + ``` + +2. **Check Agent Wallet Directory** + ```bash + # Default location + ls ~/.agent-wallet/ + # Should contain wallet.json and other files + ``` + +3. **Reinitialize Wallet** + ```bash + # Delete existing wallet (backup important data!) + rm -rf ~/.agent-wallet/ + + # Restart server with correct password + export AGENT_WALLET_PASSWORD="your_new_password" + sun-mcp-server + ``` + +4. **Verify Password Complexity** + - Use strong password (minimum 8 characters) + - Avoid special characters, use alphanumeric combination + +### TronGrid API Key Not Working + +**Symptom:** API calls return errors or rate limiting errors. + +**Resolution Steps:** + +1. **Check Environment Variable Name** + ```bash + # Correct name + export TRON_GRID_API_KEY="your_api_key" + + # Incorrect name (common error) + export TRONGRID_API_KEY="..." # ❌ Don't do this + ``` + +2. **Verify API Key Validity** + - Log in to [TronGrid Dashboard](https://dashboard.trongrid.io) + - Confirm API Key not expired or disabled + - Check request quota is sufficient + +3. **Verify Environment Variable Set** + ```bash + echo $TRON_GRID_API_KEY + ``` + +4. **Restart Server** + ```bash + # Restart after setting + npx -y @bankofai/sun-mcp-server + ``` + +5. **Check Network Connection** + ```bash + curl -H "TRONGRID-API-KEY: $TRON_GRID_API_KEY" \ + https://api.trongrid.io/v1/now + # Should return block information + ``` + +### "Conflicting Wallet Modes" + +**Symptom:** Error "Conflicting wallet modes detected". + +**Cause:** Multiple wallet environment variables set simultaneously. + +**Solution:** Set only one of the following: + +```bash +# Option 1: Agent Wallet (recommended for production) +export AGENT_WALLET_PASSWORD="your_password" +unset TRON_PRIVATE_KEY +unset TRON_MNEMONIC + +# Option 2: Private Key (testnet only) +export TRON_PRIVATE_KEY="your_64_hex_chars" +unset AGENT_WALLET_PASSWORD +unset TRON_MNEMONIC + +# Option 3: Mnemonic +export TRON_MNEMONIC="word1 word2 ... word12" +unset AGENT_WALLET_PASSWORD +unset TRON_PRIVATE_KEY +``` + +**Verify Configuration:** +```bash +# Clear all wallet-related environment variables +unset AGENT_WALLET_PASSWORD TRON_PRIVATE_KEY TRON_MNEMONIC + +# Set only one +export AGENT_WALLET_PASSWORD="your_password" + +# Restart server +sun-mcp-server +``` + +## DeFi Operation Errors + +### "Swap Failed" + +**Symptom:** `sunswap_swap` call returns error. + +**Common Causes and Solutions:** + +1. **Insufficient Balance** + ```bash + # Check source token balance + sunswap_get_balances # List all balances + ``` + - Confirm sufficient source tokens + - Account amount should include Gas fees + +2. **Slippage Tolerance Too Low** + ``` + # Example: 2% slippage tolerance may not be enough + Increase to 3-5% + ``` + - May need higher tolerance in volatile markets + - But higher tolerance increases frontrunning risk + +3. **Token Not Tradeable** + - Check if token listed on SunSwap + - Some new tokens may not support trading + - Verify token contract address is correct + +4. **Insufficient Liquidity** + ``` + Use sunswap_quote_exact_input to check available liquidity + ``` + - Small trades may fail + - Try smaller amount or use multi-hop routes + +**Diagnostic Steps:** +``` +1. Check balance +2. Use sunswap_quote_exact_input to estimate output +3. Try higher slippage tolerance +4. Check network status +``` + +### "Add Liquidity Failed" + +**Symptom:** `sunswap_add_liquidity` returns error. + +**Common Causes and Solutions:** + +1. **Tokens Not Authorized** + ``` + Need to authorize both tokens for SunSwap contract + ``` + - Call `sunswap_approve_token` or `permit2_approve` + - Grant sufficient amount + - Both tokens need authorization + +2. **Amount Ratio Not Reasonable** + ``` + Current price may have changed + Reduce slippage tolerance to allow wider ratio range + ``` + - Check current pool price + - Adjust token amounts to match pool ratio + - Or increase tolerance percentage + +3. **Amount Too Small** + ``` + Minimum liquidity requirement may not be met + ``` + - Try increasing amount + - Check SunSwap's minimum position requirement + +4. **Pool Doesn't Exist** + - Verify trading pair exists on SunSwap + - Check fee tier is correct (V2: 0.3%, V3: 0.01%-1%) + +**Diagnostic Tip:** Always verify balance and authorization first, before calling add liquidity. + +### "Permit2 Signature Failed" + +**Symptom:** Permit2 authorization returns signature error. + +**Resolution Steps:** + +1. **Check Wallet Support** + ```bash + # Agent Wallet must support signTypedData + echo $AGENT_WALLET_PASSWORD # Confirm set + ``` + +2. **Verify Signature Data** + - Check Permit2 request structured data + - Confirm chain ID, token address, deadline correct + +3. **Reinitialize Wallet** + ```bash + rm -rf ~/.agent-wallet/ + export AGENT_WALLET_PASSWORD="your_password" + sun-mcp-server + ``` + +4. **Use Alternate Authorization Method** + ``` + If Permit2 continues to fail, use sunswap_approve_token instead + ``` + +### Transaction Shows "REVERT" Status + +**Symptom:** Transaction submitted but reverted on-chain. + +**Common Causes:** + +1. **Balance Decreased After Transaction Signed** + - Wallet may be participating in other transactions simultaneously + - Space sufficient time between submissions + +2. **Slippage Price Changed** + - Price changed while transaction queued + - Increase slippage tolerance and retry + +3. **Contract State Changed** + - Pool or token contract updated + - Retry after one block + +4. **Insufficient Authorization** + - Permit2 authorization expired or used up + - Re-authorize and retry + +5. **Insufficient Gas** + - Uncommon on TRON, but check account balance + - Ensure account has sufficient TRX as Gas + +**Debug Tip:** +``` +Check transaction hash details on https://tronscan.org for error message +``` + +## AI Behavior Issues + +### AI Constructed Invalid Token Address + +**Symptom:** AI used non-existent token address, causing operation failure. + +**Solution:** + +1. **Provide Accurate Address in Prompt** + ``` + Please use USDT (T9yD14Nj9j7xAB4dbGknA47WWJcZ541TZJ) + ``` + +2. **Use Official Token List** + - Get address from SunSwap or TronScan + - Always verify address format (case and length) + +3. **Have AI Verify Address** + ``` + Before executing any operation, use sunswap_get_token_price + to verify token exists + ``` + +### AI Tried to Call Non-existent Tool + +**Symptom:** AI called `invalid_tool_name` or other non-existent tool. + +**Solution:** + +1. **Reference Official Tool List** + - Check [SUN MCP Server Tool List](ToolList.md) + - Provide correct tool names to AI + +2. **Explicitly List Tools in Prompt** + ``` + Available swap tools include: + - sunswap_swap + - sunswap_quote_exact_input + - sunswap_quote_exact_output + ``` + +3. **Simplify Request** + - Request single operation rather than complex multi-step workflow + - AI will call correct tool more reliably + +### Slow Response Speed + +**Symptom:** Querying data or executing operations takes long time. + +**Optimization Steps:** + +1. **Configure TronGrid API Key** + ```bash + export TRON_GRID_API_KEY="your_api_key" + ``` + - Without API Key uses public node, slower speed + - With API Key accesses dedicated node + +2. **Simplify Workflow** + - Reduce multi-tool coordination steps + - Avoid large number of consecutive queries + +3. **Use Local Server** + - See [Local Privatized Deployment](LocalPrivatizedDeployment.md) + - May be faster than official server (depends on network) + +4. **Batch Operations** + ``` + Merge related queries to reduce round trips + ``` + +## General Questions + +### What's the Difference Between Mainnet, Nile and Shasta? + +| Feature | Mainnet | Nile Testnet | Shasta Testnet | +|------|---|---|---| +| **Purpose** | Production | Official testing | Community testing | +| **Network Parameter** | `mainnet` | `nile` | `shasta` | +| **Real Value** | Yes | No (test TRX) | No (test TRX) | +| **Transaction Finality** | Immediate | Immediate | Immediate | +| **Recommended Use** | Production DeFi | Development and testing | Experimentation | +| **Stability** | Highest | High | Medium | +| **Get Test TRX** | N/A | [Nile Faucet](https://nile.trongrid.io/join/getjoined) | [Shasta Faucet](https://shasta.trongrid.io/join/getjoined) | + +**Best Practice:** +- Always use Nile during development +- Final testing on Shasta +- Only migrate to mainnet after sufficient verification + +### Can I Use Multiple MCP Server Instances Simultaneously? + +**Yes.** For example, can run official mainnet server and local Nile instance simultaneously. + +**Configuration Example (Claude Desktop):** + +```json +{ + "mcpServers": { + "sun-mainnet": { + "command": "npx", + "args": ["-y", "@bankofai/sun-mcp-server"], + "env": { + "TRON_NETWORK": "mainnet", + "AGENT_WALLET_PASSWORD": "your_mainnet_password" + } + }, + "sun-nile": { + "command": "sun-mcp-server", + "args": ["--port", "8081"], + "env": { + "TRON_NETWORK": "nile", + "TRON_PRIVATE_KEY": "your_testnet_private_key" + } + } + } +} +``` + +**Note:** Use different wallet credentials for each instance to avoid confusion. + +### How to Update to Latest Version? + +**Using npx (Recommended):** +```bash +# npx automatically gets latest version +npx -y @bankofai/sun-mcp-server + +# Force clear cache and get latest version +npx --clear-cache -y @bankofai/sun-mcp-server +``` + +**Using Local Installation:** +```bash +# Update global installation +npm install -g @bankofai/sun-mcp-server + +# Or update in project +npm update @bankofai/sun-mcp-server +``` + +**Using Git Repository:** +```bash +# Clone or update repository +git clone https://github.com/BofAI/sun-mcp-server.git +cd sun-mcp-server + +# Pull latest code +git pull + +# Install dependencies and start +npm install +npm start +``` + +### Too Many Tools Cause LLM Context Overflow? + +**Symptom:** Claude reports token limit exceeded or tool list too long. + +**Solution: Use Tool Filtering:** + +```bash +# Enable only specific tools (whitelist) +sun-mcp-server --whitelist sunswap_swap,sunswap_get_balances,sunswap_quote_exact_input + +# Exclude certain tools (blacklist) +sun-mcp-server --blacklist getUserPositions,getPoolVolHistory +``` + +**Optimization Tips:** +- Create multiple server instances for different tasks +- Use whitelist to load only necessary tools +- Regularly clean up unused tool configurations + +### Which MCP Protocol Version is Supported? + +**SUN MCP Server supports MCP 1.10.2 and higher.** + +**Verify Version:** +```bash +# Check version in dependencies +npm list @modelcontextprotocol/sdk + +# Should output similar to: +# @modelcontextprotocol/sdk@1.10.2 +``` + +**Upgrade MCP SDK:** +```bash +npm update @modelcontextprotocol/sdk +``` + +--- + +## Get More Help + +- **GitHub Issues:** https://github.com/BofAI/sun-mcp-server/issues +- **Complete Documentation:** Check [Tool List](ToolList.md) and [Best Practices](BestPractices.md) +- **Local Deployment:** See [Local Privatized Deployment](LocalPrivatizedDeployment.md) +- **Official Server:** See [Official Server Access](OfficialServerAccess.md) diff --git a/docs/McpServer-Skills/MCP/SUNMCPServer/Intro.md b/docs/McpServer-Skills/MCP/SUNMCPServer/Intro.md index 48c3aa06..a9185a4b 100644 --- a/docs/McpServer-Skills/MCP/SUNMCPServer/Intro.md +++ b/docs/McpServer-Skills/MCP/SUNMCPServer/Intro.md @@ -1,90 +1,107 @@ - # Introduction -SUN MCP Server is a Model Context Protocol (MCP) server for the **SUN.IO (SUNSWAP)** ecosystem on the TRON network. It allows AI agents to query SUN.IO API data (tokens, pools, prices, protocol metrics, transactions, farming, contracts) and perform DeFi operations such as swaps and V2/V3 liquidity management through a unified tool interface. +## What is SUN MCP Server? + +SUN MCP Server is the bridge connecting AI assistants to [SUN.IO (SunSwap)](https://sun.io), the largest decentralized exchange on the TRON blockchain. Built on the [Model Context Protocol (MCP)](../Intro.md) standard, it lets you query DeFi data, execute token swaps, and manage liquidity positions using natural language—without directly interacting with contracts or handling complex on-chain parameters. + +For example: just tell Claude "swap 100 USDT to TRX using SunSwap's best route," and the AI will automatically find the optimal path, estimate slippage, ask you to confirm, then execute the trade. No need to open a frontend, manually approve contracts, or understand the routing contract internals. + +What this means for different people: + +- If you're a **DeFi user**, it lets you operate SunSwap conversationally—swapping, adding liquidity, collecting fees, as naturally as sending a message. +- If you're a **Web3 developer**, it's your tool for quickly querying SunSwap on-chain state and protocol metrics, saving significant API integration work. +- If you're an **AI Agent builder**, it provides a standardized DeFi toolkit you can directly orchestrate into automated trading or market-making strategies. +- If you're a **data analyst**, SunSwap's trading volume, pool APYs, and position data are all within reach—no API documentation required. + +--- + +## What can it do? -Based on the [Model Context Protocol](https://modelcontextprotocol.io/), this service provides on-chain and API capabilities to MCP-compatible clients (such as Claude Desktop, Cursor, Google Antigravity) and integrates: +SUN MCP Server covers the full range of SunSwap DEX interactions, from on-chain data queries to token swaps and liquidity management, providing **41 tools** (18 custom tools + 23 SUN.IO OpenAPI tools). -- **OpenAPI-based tools**: From the SUN.IO public API specification (`specs/sunio-open-api.json`), used for read-only queries. -- **Custom SUNSWAP tools** (`sunswap_*`): Wallets, balances, quotes, swaps, and V2/V3 liquidity, supported by `tronweb` and on-chain contract calls. +Here's a capability overview—each item can be triggered through natural language: -## MCP Server URL -For the convenience of users with different needs, you can choose to connect directly to the [official cloud service](./OfficialServerAccess.md) or choose to perform [local deployment](./LocalPrivatizedDeployment.md) on your own computer. The official service only provides read-only services. +**Data Queries (read-only, no private key needed):** -| Environment | URL | -| :--- | :--- | -| Production | [https://sun-mcp-server.bankofai.io/mcp](https://sun-mcp-server.bankofai.io/mcp) | +| Capability | Description | Try saying | +| :--- | :--- | :--- | +| **Token Prices** | Query real-time prices for any token on SunSwap | "What's the current USDT/TRX price?" | +| **Swap Quotes** | Get the optimal route and expected output for a given input | "How much TRX can I get for 100 USDT?" | +| **Pool Data** | Query pool lists, APY, trading volume, liquidity history | "What's the current APY for the USDT-TRX pool?" | +| **Position Query** | View liquidity positions for any address on SunSwap | "Check my SunSwap positions" | +| **Protocol Stats** | Overall SunSwap trading volume, user counts, pool count history | "What was SunSwap's trading volume in the past 7 days?" | +| **Farm Info** | Query farm lists and user mining positions | "What yield farms are available on SunSwap?" | +**DeFi Operations (write, requires private key):** -## Core Capabilities Overview +| Capability | Description | Try saying | +| :--- | :--- | :--- | +| **Token Swap** | Execute optimal-route swaps via the Universal Router | "Swap 100 USDT to TRX for me" | +| **V2 Liquidity** | Add/remove V2 pool liquidity, auto-handles TRX/WTRX conversion | "Add 100 USDT of liquidity to the USDT-TRX V2 pool" | +| **V3 Liquidity** | Mint and manage concentrated liquidity positions, collect fees | "Collect the accrued fees from my V3 position" | +| **V4 Liquidity** | V4 concentrated liquidity operations with Permit2 authorization | "Mint a V4 USDT-TRX position" | +| **Contract Interaction** | Directly read or call any TRON smart contract function | "Query the current slot0 state of this contract" | -* **SUN.IO API (Read-only)**: Query tokens, pools, prices, protocol history, positions, farms, and transactions. -* **Wallet & Balance**: Get wallet address, list/switch wallets, query TRX and TRC20 balances. -* **Pricing & Quoting**: Get token prices by address/symbol; get swap quotes via the smart router. -* **Smart Contract Interaction**: Read and write TRON contracts; automatic TRC20 allowance checks during liquidity and swap processes. -* **Swaps**: Smart swap via Universal Router or low-level swap with specified router. -* **V2 Liquidity**: Add/remove V2 liquidity, with automatic native TRX handling. -* **V3 Liquidity**: Mint, increase, decrease V3 concentrated liquidity positions and collect fees. -* **V4 Liquidity**: Mint, increase, decrease V4 concentrated liquidity positions and collect fees, with Permit2 support. -* **Wallet & Security**: Supports private keys or BIP-39 mnemonics; optional Agent Wallet; full coverage of Mainnet, Nile, and Shasta. +For the Full Capability List and parameter details, see [Full Capability List](./ToolList.md). +--- -## Detailed Functional Features +## Two Access Modes -A specific list of functions provided by SUN MCP Server, for reference by developers and advanced users: +Now that you understand SUN MCP Server's capabilities, you need to choose an access mode. There are two paths depending on your use case: -### SUN.IO API (Read-only) -* **Transactions**: Scan DEX transactions by protocol, token/pool, type, and time range. -* **Tokens**: Get token information by address and protocol, with fuzzy keyword search support. -* **Protocol**: Protocol snapshot data and historical KPIs (volume, users, transactions, pool count, liquidity). -* **Prices**: Query token prices by address. -* **Positions**: Query user liquidity positions and pool tick-level position/liquidity details. -* **Pools**: List/search pools, top APY pools, hooks, volume and liquidity history. -* **Trading Pairs**: Token pair entity queries. -* **Farms**: Farm list, farm transaction scanning, user farm positions. +**[Official Cloud Service](./OfficialServerAccess.md)** — Best for quick exploration and data queries. No installation required—just add a service address to your AI client config and you're ready. The cloud service is **read-only**: it supports querying token prices, pool data, protocol stats, but does not support executing swaps or adding liquidity. -### Wallet & Balance -* **Wallet Address**: Get the current TRON wallet address (Base58) used for SUNSWAP operations. -* **Wallet List**: List all available wallets (agent-wallet mode only). -* **Switch Wallet**: Switch the active wallet (agent-wallet mode only). -* **Balance Query**: Query TRX and TRC20 balances for an address. +**[Local Private Deployment](./LocalPrivatizedDeployment.md)** — For users who need full DeFi functionality. Run SUN MCP Server on your own machine, configure a wallet, and unlock swaps, liquidity management, and all other operations. Private keys stay entirely local and are never uploaded to any remote service. -### Pricing & Quoting -* **Token Price**: Get token prices by address/symbol via SUN.IO API. -* **Swap Quote**: Get exact input swap quotes via the smart router. +The core difference comes down to one thing: **whether you need to sign transactions**. -### Smart Contract Interaction -* **Read Contract**: Call view/pure functions on TRON contracts. -* **Write Contract**: Execute state-changing contract function calls, with optional TRX value. +| Comparison | Official Cloud Service | Local Private Deployment | +| :--- | :--- | :--- | +| **Feature scope** | Read-only (data queries) | Full (queries + swaps + liquidity) | +| **Setup difficulty** | Add one line of config | Requires local install and build | +| **Private key required** | No | Yes (required for write operations) | +| **Token swaps / liquidity** | Not supported | Supported | +| **Best for** | Data queries, getting started | DeFi operations, automated strategies | +| **Security** | High (no private key exposure risk) | Depends on your key management | -### Swaps -* **Smart Swap**: Execute swaps via Universal Router, automatically finding the best route and handling Permit2 authorization. -* **Low-level Swap**: Execute swaps with specified router and parameters, with full control over routing details. +:::tip Not sure which to choose? +If you just want to check SunSwap prices and pool data, start with the [Official Cloud Service](./OfficialServerAccess.md)—it takes 1 minute to connect. When you need to execute swaps or manage liquidity, switch to [Local Private Deployment](./LocalPrivatizedDeployment.md). +::: -### V2 Liquidity -* **Add Liquidity**: Add liquidity to a V2 pool; automatically uses `addLiquidityETH` when one side is native TRX, with automatic TRC20 approval handling. -* **Remove Liquidity**: Remove V2 liquidity; automatically uses `removeLiquidityETH` when one side is TRX. +--- -### V3 Liquidity -* **Mint Position**: Mint a new V3 concentrated liquidity position with auto-compute features. -* **Increase Liquidity**: Increase liquidity for an existing V3 position. -* **Decrease Liquidity**: Decrease liquidity for an existing V3 position. -* **Collect Fees**: Collect accrued fees from a V3 position. +## Supported Networks -### V4 Liquidity -* **Mint Position**: Mint a new V4 concentrated liquidity position with Permit2 authorization. -* **Increase Liquidity**: Increase liquidity for an existing V4 position. -* **Decrease Liquidity**: Decrease liquidity for an existing V4 position. -* **Collect Fees**: Collect accrued fees from a V4 position. +Both access modes support the following three networks (mainnet by default): -### Wallet & Security -* **Flexible Configuration**: Supports configuration via `TRON_PRIVATE_KEY` or `TRON_MNEMONIC`. -* **Agent Wallet**: Optional Agent Wallet provider for remote signing. -* **Multi-Network Support**: Full coverage of Mainnet, Nile, and Shasta, with configurable RPC and TronGrid API Key. +| Network | Identifier | Purpose | Block Explorer | +| :--- | :--- | :--- | :--- | +| **Mainnet** | `mainnet` | Production, real assets | [tronscan.org](https://tronscan.org) | +| **Nile Testnet** | `nile` | Development and testing (recommended) | [nile.tronscan.org](https://nile.tronscan.org) | +| **Shasta Testnet** | `shasta` | Development and testing | [shasta.tronscan.org](https://shasta.tronscan.org) | + +Specify the target network via the `network` parameter when calling tools. **We strongly recommend validating any new operation on the Nile testnet first**—mainnet operations involve real assets and cannot be undone. + +--- ## Security Notes -- **Private Keys and Mnemonics**: Only configure `TRON_PRIVATE_KEY` or `TRON_MNEMONIC` through environment variables. Do not hardcode in code or configuration files that may be committed. -- **Use Testnet First**: Test thoroughly on Nile or Shasta before operating on mainnet. -- **Minimum Privilege**: The wallet configured for the agent should only hold the minimum funds required to complete the task. -- **Audit**: A security audit of the server and integration approach is recommended before production use. +:::warning +Before you start, keep these security principles in mind—DeFi operations directly involve on-chain assets and mistakes cannot be reversed: + +- **Never hardcode private keys**: Do not write private keys or mnemonics directly into config files. Use system environment variables or encrypted wallet management. +- **Test on testnet first**: Before executing any swap or liquidity operation on mainnet, verify it on the Nile testnet. +- **Minimum funds principle**: Only keep the funds needed for the current task in the AI Agent's wallet. +- **Watch authorization risk**: Token `approve` operations require extra care—avoid granting unlimited allowances. +- **Confirm every transaction**: Before executing any on-chain write operation, the AI will present transaction details and ask for confirmation. Don't skip this step. +::: + +--- + +## Next Steps + +- Want the fastest way to try it out? → [Quick Start](./QuickStart.md) +- Only need to query on-chain data? → [Official Cloud Service](./OfficialServerAccess.md) +- Need token swaps or liquidity management? → [Local Private Deployment](./LocalPrivatizedDeployment.md) +- Want to explore all 41 tools? → [Full Capability List](./ToolList.md) diff --git a/docs/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md b/docs/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md index 77465c43..69ff4028 100644 --- a/docs/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md +++ b/docs/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md @@ -3,151 +3,422 @@ import TabItem from '@theme/TabItem'; # Local Privatized Deployment -If you need to perform write operations such as transfers and contract calls, you must deploy the server locally. Local deployment allows you to securely configure private keys, thereby enabling full transaction functions. +## What is Local Privatized Deployment? -## Environment Requirements -- **Node.js** 20.0.0 or higher. -- **npm** (or compatible package manager). -- Optional: **TronGrid API Key**, used for higher rate limiting and stability on the mainnet. +Local privatized deployment refers to running a complete instance of SUN MCP Server on your own computer. Unlike relying on third-party services, local deployment gives you full control over your wallet, network connection, and data privacy. +This mode is particularly suitable for scenarios that require executing DeFi operations. By configuring wallet private keys or mnemonics, you can unlock the following write operations: -## Key Configuration (Environment Variables) +- **Swap**: Automatic routing swaps using Universal Router +- **Liquidity Management**: Add and remove liquidity for SunSwap V2/V3/V4 +- **Position Management**: Mint, increase, decrease positions and collect fees for SunSwap V3/V4 +- **Contract Interaction**: Call arbitrary contracts via `sunswap_send_contract` -**Security**: Do not save private keys or mnemonics in MCP configuration files (such as `claude_desktop_config.json` or `mcp.json`), they should be set through environment variables in the system or shell. +:::info +Without wallet configuration, SUN MCP Server will run in **read-only mode**, allowing querying on-chain data but unable to execute write operations. +::: -### 1. Network and API +--- -- **TRONGRID_API_KEY** (Optional): TronGrid API Key used by mainnet RPC, which can reduce rate limiting and improve stability. -- **TRON_RPC_URL** (Optional): Overwrite the TRON RPC base address; after setting, it replaces the default fullNode/solidityNode/eventServer of the current network. +## Before You Start -### 2. Wallet (Write Operations) +### Environment Requirements -**Method 1: Private Key** +| Item | Requirement | Description | +|------|------|------| +| Node.js | >= 20.0.0 | v20.0.0 or higher ([download](https://nodejs.org/)) | +| npm | >= 10.0 | Usually installed with Node.js | +| Operating System | Linux / macOS / Windows | Cross-platform support | +| Disk Space | >= 100 MB | For dependency installation | +| Network | Internet Connection | Communication with TRON network | + +### Security Principles + +:::danger Important Security Tips +1. **Private Key Protection**: Never commit private keys to version control. Use `.env` files and add them to `.gitignore`. +2. **Permission Management**: Ensure `.env` file permissions are `600` (owner read-only). +3. **Multiple Wallet Mode Prohibited**: Configuring multiple wallet methods simultaneously will trigger an error. Only one method can be used at a time. +4. **Mnemonic Terminology**: In this document, "mnemonic" refers to BIP-39 standard 12-word or 24-word recovery phrases. +5. **Mainnet Caution**: Before using real funds on mainnet, thoroughly test on testnets (Nile, Shasta). +::: + +--- + +## Installation Steps +### Step 1: Configure Wallet + +The wallet determines which identity the AI assistant uses to perform on-chain operations. SUN MCP Server supports three wallet modes; if no wallet is configured, the server automatically runs in read-only mode. + +#### There are three wallet options — choose based on your needs + +| Feature | Agent Wallet | Private Key | Mnemonic | +| :--- | :--- | :--- | :--- | +| Security Level | High (encrypted storage) | Low (plaintext) | Low (plaintext) | +| Multi-Wallet Support | Yes | No | No | +| Runtime Wallet Switching | Yes | No | No | +| Setup Complexity | Medium | Simple | Simple | +| Recommended For | Production, significant funds | Development, small amounts | Development, small amounts | + +#### Option 1: Agent Wallet (Recommended) + +This is the most secure option. Private keys are encrypted and stored on local disk, never exposed as plaintext in environment variables. Even if environment variables are leaked, the attacker still needs the encrypted keystore file to access funds. + +**Install and initialize Agent Wallet:** + +```bash +# Install +npm install -g @bankofai/agent-wallet + +# Create encrypted wallet +agent-wallet start +``` +Agent Wallet also supports **multi-wallet management** — you can create multiple wallets and switch between them at runtime using the `select_wallet` tool, ideal for scenarios requiring operations across different accounts. + +> For detailed installation and usage instructions, see the [agent-wallet documentation](https://github.com/BofAI/agent-wallet/blob/main/doc/getting-started.md). + +**Set environment variables:** + +```bash +# Add to ~/.zshrc or ~/.bashrc +export AGENT_WALLET_PASSWORD="" + +# Optional: specify custom wallet directory (default: ~/.agent-wallet) +export AGENT_WALLET_DIR="~/.agent-wallet" +``` + + + +#### Option 2: Private Key + +Provide the private key directly via environment variable. Simplest setup, but lower security. + +```bash +# Add to ~/.zshrc or ~/.bashrc +export TRON_PRIVATE_KEY="" +``` + +The private key can be in hex format with or without the `0x` prefix. + +:::warning +Using a plaintext private key in environment variables carries a **real risk of fund theft** — environment variables can be leaked via shell history, process listings (`ps aux`), or log files. **Only keep small amounts of funds** in wallets configured this way. +::: + +#### Option 3: Mnemonic Phrase + +Use a BIP-39 mnemonic phrase for HD wallet derivation. + +```bash +# Add to ~/.zshrc or ~/.bashrc +export TRON_MNEMONIC="word1 word2 word3 ... word12" + +# Optional: specify HD wallet derivation index (default: 0) +# Derivation path: m/44'/195'/0'/0/{index} +export TRON_ACCOUNT_INDEX="0" +``` + +:::warning +Same security risks as the private key option. Mnemonic phrases stored in plaintext are vulnerable to exposure. Use this only for development/testing wallets with small balances. +::: + + +--- + +### Step 2: Configure Network (Optional) + +#### TronGrid API Key + +TronGrid is the official TRON RPC provider. Using an API Key can increase request rate limits. + +**Getting an API Key:** + +1. Visit [TronGrid Official Website](https://www.trongrid.io) +2. Register an account or log in +3. Generate an API Key in the console +4. Copy the API Key to environment variable + +**Environment Variables:** ```bash -export TRON_PRIVATE_KEY="" +TRON_GRID_API_KEY=your_api_key_here ``` -**Method 2: Mnemonic** +:::info +If you don't set `TRON_GRID_API_KEY`, SUN MCP Server will use public endpoints, but may be subject to rate limiting. +::: + + +--- + +### Step 3: Install Server + +#### Option A: Run directly with npx (Recommended) + +The simplest and quickest method, no installation or cloning needed. + +**Command:** ```bash -export TRON_MNEMONIC="word1 word2 ... word12" -export TRON_ACCOUNT_INDEX="0" # Optional, default 0 +npx -y @bankofai/sun-mcp-server ``` -If neither is set and no Agent Wallet provider is provided, write-type tools (transfer, swap, liquidity) will report a "no wallet available" error. +**Description:** +- `npx` automatically downloads the latest version of `@bankofai/sun-mcp-server` +- `-y` flag automatically confirms prompts +- First run may take a few seconds to download + +**Run with environment variables:** + +```bash +TRON_NETWORK=nile TRON_GRID_API_KEY=your_api_key npx -y @bankofai/sun-mcp-server +``` +#### Option B: Clone from Source -## Installation -1. **Clone and enter the directory**: - ```shell - git clone https://github.com/BofAI/sun-mcp-server.git - cd sun-mcp-server - ``` -2. **Install and build**: - ```shell - npm install && npm run build - ``` +Suitable for development and custom modifications. +**Steps:** -## Verification -Default stdio mode: ```bash -# Run tests -npm test +# 1. Clone repository +git clone https://github.com/BofAI/sun-mcp-server.git +cd sun-mcp-server -# Start service (stdio) -npm start +# 2. Install dependencies +npm install + +# 3. Build project +npm run build + +# 4. Run server +npx tsx src/index.ts ``` -When using HTTP (streamable-http) mode: +**Or install globally:** ```bash -npm start -- --transport streamable-http --host 127.0.0.1 --port 8080 --mcpPath /mcp +npm install -g @bankofai/sun-mcp-server +sun-mcp-server ``` +--- + +### Step 4: Connect AI Client + +After configuration is complete, you need to add the connection definition of SUN MCP Server in your AI client. + +#### Find Configuration File + +Depending on your AI client, the configuration file location is as follows: + +| Client | Configuration File Path | +|--------|-------------| +| **Claude Desktop** | `~/.claude/resources/mcp/servers.json` | +| **Cursor** | `~/.cursor/extensions/mcp/servers.json` | +| **Claude Code (CLI)** | `~/.claude/mcp_servers.json` or via environment variable | + +#### Add Server Definition + +Choose the tab corresponding to your deployment method: -## Client Integration -To use this server with MCP clients such as Claude Desktop, Cursor, etc., you need to add it to your configuration file. - + -Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the equivalent path under your system: +**Claude Desktop Configuration:** + +Add to `~/.claude/resources/mcp/servers.json`: ```json { "mcpServers": { - "sun-mcp-server": { + "sun": { "command": "npx", - "args": ["tsx", "/ABSOLUTE/PATH/TO/sun-mcp-server/src/index.ts"], + "args": ["-y", "@bankofai/sun-mcp-server"], "env": { - "TRON_PRIVATE_KEY": "YOUR_KEY_HERE (Or set in system env)", - "TRONGRID_API_KEY": "YOUR_KEY_HERE (Or set in system env)" - }, - "enabled": true + "AGENT_WALLET_PASSWORD": "your_secure_password", + "AGENT_WALLET_DIR": "~/.agent-wallet", + "TRON_GRID_API_KEY": "your_api_key", + "TRON_NETWORK": "nile" + } } } } ``` -If wallet-related environment variables have been configured in the shell, the private key/mnemonic in `env` can be omitted. +**Claude Code (CLI) Configuration:** + +```bash +export MCP_SERVERS='{"sun":{"command":"npx","args":["-y","@bankofai/sun-mcp-server"],"env":{"TRON_NETWORK":"nile","TRON_GRID_API_KEY":"your_api_key"}}}' +claude code +``` +**Cursor Configuration:** +Add to `~/.cursor/extensions/mcp/servers.json`: + +```json +{ + "mcpServers": { + "sun": { + "command": "npx", + "args": ["-y", "@bankofai/sun-mcp-server"], + "env": { + "TRON_NETWORK": "nile", + "TRON_GRID_API_KEY": "your_api_key" + } + } + } +} +``` - -Configure in `.cursor/mcp.json` at the project root: + + +For running from source code. + +**Claude Desktop Configuration:** + +Add to `~/.claude/resources/mcp/servers.json`: ```json { - "servers": [ - { - "name": "sun-mcp-server", + "mcpServers": { + "sun": { "command": "npx", - "args": ["tsx", "/ABSOLUTE/PATH/TO/sun-mcp-server/src/index.ts"], + "args": ["tsx", "/path/to/sun-mcp-server/src/index.ts"], "env": { - "TRON_PRIVATE_KEY": "YOUR_KEY_HERE (Or set in system env)", - "TRONGRID_API_KEY": "YOUR_KEY_HERE (Or set in system env)" + "AGENT_WALLET_PASSWORD": "your_secure_password", + "TRON_GRID_API_KEY": "your_api_key", + "TRON_NETWORK": "nile" } } - ] + } } ``` - +**Cursor Configuration:** + +Add to `~/.cursor/extensions/mcp/servers.json`: + +```json +{ + "mcpServers": { + "sun": { + "command": "npx", + "args": ["tsx", "/path/to/sun-mcp-server/src/index.ts"], + "env": { + "TRON_NETWORK": "nile", + "TRON_GRID_API_KEY": "your_api_key" + } + } + } +} +``` - + -When using HTTP transport, requesting the MCP interface requires carrying: + -- **Accept**: `application/json, text/event-stream` -- **Content-Type**: `application/json` +Run SUN MCP Server in HTTP server mode, allowing remote connections. -Example (tools/call): +**Start HTTP Server:** ```bash -curl -X POST "Your local MCP URL" \ - -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" - } +sun-mcp-server --transport streamable-http --host 127.0.0.1 --port 8080 --mcpPath /mcp +``` + +**Claude Desktop Configuration:** + +```json +{ + "mcpServers": { + "sun": { + "url": "http://127.0.0.1:8080/mcp" + } + } +} +``` + +**Cursor Configuration:** + +```json +{ + "mcpServers": { + "sun": { + "url": "http://127.0.0.1:8080/mcp" } - }' + } +} ``` +:::warning +HTTP mode is suitable for local development and testing. For remote deployment, use HTTPS and appropriate authentication. +::: - \ No newline at end of file + + +:::tip About Environment Variables +- **npx Run**: Environment variables are set in the `"env"` field of the configuration file, or exported directly in the terminal before running. +- **HTTP Mode**: When starting the HTTP server, environment variables should be exported before the startup command: + +```bash +export TRON_NETWORK=nile +export TRON_GRID_API_KEY=your_api_key +sun-mcp-server --transport streamable-http --host 127.0.0.1 --port 8080 --mcpPath /mcp +``` + +- **Restart Required**: After modifying configuration, you need to restart the AI client for changes to take effect. +::: + +--- + +### Step 5: Verify Connection + +After starting the AI client, you should be able to see the tool list of SUN MCP Server. Perform the following tests to confirm the configuration is correct: + +#### Query Test + +Try the following command in chat: + +``` +Query the block height of TRON mainnet +``` + +Expect to receive the current block number. + +#### If Testing on Testnet + +If you configured to use Nile testnet: + +```bash +TRON_NETWORK=nile +``` + +You can get test TRX from [TRON Nile Faucet](https://nile.trongrid.io/join), then try the following operations: + +- Query test account balance +- Execute a test swap (if wallet is configured) +- Check transaction history + +:::info Diagnostic Steps +If you encounter connection issues: + +1. **Check Network Connection**: Ensure you can access TRON network endpoints +2. **Verify API Key**: If `TRON_GRID_API_KEY` is configured, ensure it's valid +3. **View Logs**: When running the server, check console output for error messages +4. **Test Network**: Try switching to testnet (Nile) to rule out network issues +::: + +--- + +## Next Steps + +Now that you've successfully deployed SUN MCP Server! Next you can: + +1. **View Full Capability List**: Browse [Full Capability List](./ToolList.md) to understand all available operations +2. **Resolve Common Issues**: Consult [Frequently Asked Questions](./FAQ.md) for help + +:::success +Congratulations! You can now interact with the TRON blockchain through your AI client. Start exploring the unlimited possibilities of DeFi! +::: diff --git a/docs/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md b/docs/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md index 1489bb15..cf5946b2 100644 --- a/docs/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md +++ b/docs/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md @@ -1,40 +1,79 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Official Server Access +# Official Cloud Service Access -For users who only need to read blockchain data (not involving transactions), you can connect directly to the officially hosted instance. **Note: The official service only provides a read-only interface and does not support operations such as transfers or contract writing.** +## What is the Official Cloud Service? -## Service Information +The official cloud service is a SUN MCP Server instance hosted by **BANK OF AI**, providing AI clients with **read-only query capabilities for SunSwap on-chain data**. -| Environment | URL | -| :---------- | :------------------------------------------------------------------------------- | -| Production | [https://sun-mcp-server.bankofai.io/mcp](https://sun-mcp-server.bankofai.io/mcp) | +If you want your AI assistant to query token prices, pool APYs, or protocol trading volume on SunSwap, or analyze a specific address's liquidity positions — these are all read-only operations that can be completed via the official cloud service, with no local installation required and no wallet credentials needed. -- **Transport Protocol**: - - **stdio**: Default; used for local MCP clients (such as Claude Desktop, Cursor). - - **streamable-http**: HTTP + server-side push events, for remote clients; configurable host, port, path. -- **Mode**: Read-only (write tools disabled) +**The core purpose of the official cloud service is to handle all infrastructure for you.** You only need to add a single service URL to your AI client's configuration to start interacting with SunSwap. -**Security**: Do not save private keys or mnemonics in MCP configuration files (such as `claude_desktop_config.json` or `mcp.json`), they should be set through environment variables in the system or shell. +### Key Advantages -## Client Integration +**1. No local installation required** — No Node.js, no repository clone, no build commands. Just add a JSON snippet to your config file, restart your AI client, and you're ready in under 2 minutes. + +**2. No private key exposure risk** — Since the cloud service is read-only, you never need to provide a wallet private key or mnemonic. This eliminates key leakage risks and makes team sharing straightforward. + +**3. Official maintenance and continuous updates** — The service always runs the latest stable version, including SunSwap protocol updates and SUN.IO API synchronization. No manual rebuilds needed. + +**4. Covers a large number of practical use cases** — Querying token prices and swap quotes, analyzing pool data and APYs, getting protocol statistics and historical metrics, viewing user liquidity positions — all the most commonly used DeFi data queries are fully supported. Only when you need to actually execute swaps or manage liquidity do you need to switch to [Local Private Deployment](./LocalPrivatizedDeployment.md). + +> In short: **The official cloud service acts as a "read-only data gateway" for SunSwap** — AI clients only need the service URL to query all public data on SunSwap. + +:::warning Important +The official cloud service only provides **read-only access**. It does **not support** token swaps, adding/removing liquidity, or any other on-chain write operations. For full functionality, please use [Local Private Deployment](./LocalPrivatizedDeployment.md). +::: + +--- + +## How to Connect + +Add the following MCP service endpoint to your AI client configuration: + +**`https://sun-mcp-server.bankofai.io/mcp`** + +> Note: This is an MCP protocol endpoint, not a webpage. Opening it directly in a browser will not display anything. + +The official cloud service supports **two usage modes**: + +| Mode | Rate Limit | Description | +| :--- | :--- | :--- | +| **Without API Key (default)** | 100,000 requests / day | Ready to use immediately, suitable for getting started and low-frequency queries | +| **With TronGrid API Key** | 500,000 requests / day | Higher request limit, suitable for frequent queries and production use | + +For use cases involving frequent mainnet data queries, it is recommended to register a free TronGrid API Key at [trongrid.io](https://www.trongrid.io/), and configure it in the request header for higher throughput and stability. + +--- + +## Client Configuration +Configuration file path: +- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` +- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` + +**Basic Config (No API Key)**: + ```json { "mcpServers": { "sun-mcp-server": { "command": "npx", - "args": ["mcp-remote", "https://sun-mcp-server.bankofai.io/mcp"] + "args": [ + "mcp-remote", + "https://sun-mcp-server.bankofai.io/mcp" + ] } } } ``` -With TronGrid API Key: +**Config with TronGrid API Key**: ```json { @@ -52,16 +91,18 @@ With TronGrid API Key: } ``` +Replace `` with your actual TronGrid API Key. + -CLI command: +**Add via command line**: -```shell +```bash claude mcp add --transport http sun-mcp-server https://sun-mcp-server.bankofai.io/mcp ``` -Or add `.mcp.json` to the project root: +**Or add `.mcp.json` to your project root**: ```json { @@ -75,38 +116,128 @@ Or add `.mcp.json` to the project root: ``` + + +Add `.cursor/mcp.json` to your project root: - +```json +{ + "mcpServers": { + "sun-mcp-server": { + "url": "https://sun-mcp-server.bankofai.io/mcp" + } + } +} +``` -When using HTTP transport, requesting the MCP interface requires carrying: + + -- **Accept**: `application/json, text/event-stream` -- **Content-Type**: `application/json` +If you want to integrate SUN MCP Server into your own application, you can call it via standard HTTP requests. -Example (tools/call): +**Step 1: Initialize Connection** ```bash -curl -X POST "https://sun-mcp-server.bankofai.io/mcp" \ +curl -X POST https://sun-mcp-server.bankofai.io/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{ "jsonrpc": "2.0", - "id": "1", + "method": "initialize", + "params": { + "protocolVersion": "2025-03-26", + "capabilities": {}, + "clientInfo": {"name": "my-client", "version": "1.0"} + }, + "id": 1 + }' +``` + +The response will include an `mcp-session-id` header — you will need it for subsequent requests. + +**Step 2: Call a Tool** + +Use the `mcp-session-id` from Step 1: + +```bash +curl -X POST https://sun-mcp-server.bankofai.io/mcp \ + -H "Content-Type: application/json" \ + -H "Accept: application/json, text/event-stream" \ + -H "mcp-session-id: " \ + -d '{ + "jsonrpc": "2.0", "method": "tools/call", "params": { - "name": "sunswap_v2_add_liquidity", - "arguments": { - "network": "nile", - "routerAddress": "TMn1qrmYUMSTXo9babrJLzepKZoPC7M6Sy", - "tokenA": "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf", - "tokenB": "TWMCMCoJPqCGw5RR7eChF2HoY3a9B8eYA3", - "amountADesired": "1000000", - "amountBDesired": "1500000" - } - } + "name": "getPrice", + "arguments": {"tokenAddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"} + }, + "id": 2 }' +``` + +**Step 3: Discover Available Tools** +```bash +curl -X POST https://sun-mcp-server.bankofai.io/mcp \ + -H "Content-Type: application/json" \ + -H "Accept: application/json, text/event-stream" \ + -H "mcp-session-id: " \ + -d '{ + "jsonrpc": "2.0", + "method": "tools/list", + "params": {}, + "id": 3 + }' ``` +:::info Session Management +- Each `initialize` creates a new session +- Sessions automatically expire after 30 minutes of inactivity +- Use `DELETE /mcp` (with `mcp-session-id` header) to explicitly close a session +::: + + +--- + +## Verify Connection + +After configuration, **fully quit and restart** your AI client, then enter the following test query: + +``` +Check the current prices of USDT and TRX on SunSwap +``` + +If you receive a normal response, the connection is working. + +If you encounter issues, first confirm: +1. Node.js version >= 20.0.0 (run `node --version` to check) +2. Network can reach `sun-mcp-server.bankofai.io` +3. AI client has been fully quit and restarted (not just refreshed) + +--- + +## Available Capabilities Overview + +When connected via the official cloud service, you can use all **read-only** tools, including: + +| Category | Example Capabilities | +| :--- | :--- | +| **Token Prices** | Query real-time token prices by address or symbol | +| **Swap Quotes** | Get the optimal swap quote for an exact input via smart routing | +| **Token Info** | Search token information by address, protocol, or keyword | +| **Pool Data** | Pool lists, APY rankings, trading volume history, liquidity history | +| **Position Queries** | User liquidity positions, tick-level position details | +| **Protocol Stats** | Trading volume, user counts, transaction counts, pool count history | +| **Farm Info** | Farm lists, farm transactions, user farm positions | +| **Contract Reading** | Call view/pure functions on any TRON contract | + +For the Full Capability List, see [Full Capability List](./ToolList.md). + +--- + +## Next Steps + +- Need token swaps or liquidity management? → [Local Private Deployment](./LocalPrivatizedDeployment.md) +- Want the detailed description of all available tools? → [Full Capability List](./ToolList.md) diff --git a/docs/McpServer-Skills/MCP/SUNMCPServer/QuickStart.md b/docs/McpServer-Skills/MCP/SUNMCPServer/QuickStart.md new file mode 100644 index 00000000..ba07ff4e --- /dev/null +++ b/docs/McpServer-Skills/MCP/SUNMCPServer/QuickStart.md @@ -0,0 +1,119 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Quick Start + +The goal of this page is simple: **get you integrated and make your first DeFi query in just 1 minute.** + +We'll use the [official cloud service](./OfficialServerAccess.md) for this quick experience. The cloud service is read-only, requires no wallet, and is ready to use immediately. + +--- + +## Preparation + +Before you get started, make sure you have: + +1. **Node.js** >= 20.0.0 ([download link](https://nodejs.org/)) +2. **MCP Client**: Any AI client that supports MCP. For example [Claude Desktop](https://claude.ai/download), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), or [Cursor](https://cursor.sh). + +--- + +## Add Configuration + +Choose the configuration method that matches the tool you're using: + + + + +1. Open the Claude Desktop configuration file: + - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` + - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` + +2. Add the following configuration in the `mcpServers` section: + +```json +{ + "mcpServers": { + "sun-mcp-server": { + "command": "npx", + "args": ["mcp-remote", "https://sun-mcp-server.bankofai.io/mcp"] + } + } +} +``` + +3. Save the file and restart Claude Desktop. + + + + + +Run the following command in the terminal to add SUN MCP Server: + +```bash +claude mcp add --transport http sun-mcp-server https://sun-mcp-server.bankofai.io/mcp +``` + + + + + +1. Open the Cursor configuration file: `.cursor/mcp.json` + +2. Add the following in the configuration: + +```json +{ + "mcpServers": { + "sun-mcp-server": { + "command": "npx", + "args": ["mcp-remote", "https://sun-mcp-server.bankofai.io/mcp"] + } + } +} +``` + +3. Save the file and restart Cursor. + + + + +--- + +## Restart and Test + +After completing the configuration, restart your MCP client. Then try the following query in a conversation: + +``` +Check the current prices of USDT and TRX on SunSwap +``` + +:::info About Cloud Service +The official cloud service we provide is **read-only**, suitable for querying data and analysis. If you need to execute on-chain transactions, deploy contracts, or other write operations, please see [Local Privatized Deployment](./LocalPrivatizedDeployment.md). +::: + +--- + +## Continue Exploring + +Here are some common DeFi query examples: + +| Operation | Example Prompt | +|------|--------| +| **Price Query** | Query the real-time price of USDT/TRX | +| **Liquidity Pool Data** | Get pool information for the TRX-USDC trading pair on SunSwap | +| **Position Query** | View all liquidity positions of address TR... on SunSwap | +| **Trade Quote** | Get a quote for swapping 1000 USDT for TRX | +| **Protocol Stats** | Get SunSwap statistics including TVL and 24-hour trading volume | + +--- + +## Next Steps + +- **[Local Privatized Deployment](./LocalPrivatizedDeployment.md)** - Learn how to run SUN MCP Server locally and perform write operations +- **[Official Server Access](./OfficialServerAccess.md)** - Learn more about the official cloud service +- **[Full Capability List](./ToolList.md)** - View all available tools and features + +--- + +Happy coding! If you have any questions, feel free to provide feedback. diff --git a/docs/McpServer-Skills/MCP/SUNMCPServer/ToolList.md b/docs/McpServer-Skills/MCP/SUNMCPServer/ToolList.md new file mode 100644 index 00000000..fb5fd1dc --- /dev/null +++ b/docs/McpServer-Skills/MCP/SUNMCPServer/ToolList.md @@ -0,0 +1,354 @@ +# Full Capability List + +SUN MCP Server provides **41 tools** (18 custom DeFi tools + 23 SUN.IO OpenAPI derived tools). + +## Understanding Two Key Concepts + +:::info Read vs Write +- **Read Tools**: Only query data, do not affect on-chain state. Can be used in both cloud service and local deployment. +- **Write Tools**: Modify on-chain state (swaps, liquidity operations, etc.). Only available in local deployment with configured wallet. +::: + +:::tip network Parameter +Most tools have an optional `network` parameter to specify the network environment for interaction. Defaults to mainnet configuration, can also switch to testnet. +::: + +--- + +## Custom Tools (18 total) + +### Wallet and Balance + +| Tool Name | Function Description | Tool Type | Required Parameters | Optional Parameters | +|--------|---------|---------|---------|---------| +| `sunswap_get_wallet_address` | Get current active TRON wallet address | Read | - | `network` | +| `sunswap_get_balances` | Query TRX and TRC20 token balances | Read | `tokens` | `network`, `ownerAddress` | + +**Try saying this:** +- "Query my TRON wallet address" +- "Show my balance for USDT and SUNFLARE" +- "Get my TRX balance on testnet" + +--- + +### Price and Quotes + +| Tool Name | Function Description | Tool Type | Required Parameters | Optional Parameters | +|--------|---------|---------|---------|---------| +| `sunswap_get_token_price` | Get token price (via SUN.IO API) | Read | `tokenAddress` or `symbol` | `network` | +| `sunswap_quote_exact_input` | Swap quote for exact input amount (smart routing) | Read | `routerAddress`, `args` | `network`, `functionName`, `abi` | + +**Try saying this:** +- "What is the current price of SUNFLARE?" +- "If I swap 1000 USDT for SUNFLARE, how much will I get?" +- "Query the current price of USDC on testnet" + +--- + +### Swaps + +| Tool Name | Function Description | Tool Type | Required Parameters | Optional Parameters | +|--------|---------|---------|---------|---------| +| `sunswap_swap` | Execute generic router swap (supports auto-routing + Permit2) | Write | `tokenIn`, `tokenOut`, `amountIn` | `network`, `slippage` | +| `sunswap_swap_exact_input` | Exact input swap (smart router) | Write | `routerAddress`, `args` | `network`, `functionName`, `value`, `abi` | + +**Try saying this:** +- "I want to swap 500 USDT for SUNFLARE with 1% slippage" +- "Execute a swap of 1000 USDC for TRX" +- "Help me swap SUNFLARE to USDT, completed in less than 2 seconds" + +:::caution Wallet Required +Swap tools require local deployment of SUN MCP Server with configured wallet private key. +::: + +--- + +### V2 Liquidity + +| Tool Name | Function Description | Tool Type | Required Parameters | Optional Parameters | +|--------|---------|---------|---------|---------| +| `sunswap_v2_add_liquidity` | Add V2 liquidity (automatic TRX/WTRX handling) | Write | `routerAddress`, `tokenA`, `tokenB`, `amountADesired`, `amountBDesired` | `network`, `amountAMin`, `amountBMin`, `to`, `deadline`, `abi` | +| `sunswap_v2_remove_liquidity` | Remove V2 liquidity | Write | `routerAddress`, `tokenA`, `tokenB`, `liquidity` | `network`, `amountAMin`, `amountBMin`, `to`, `deadline`, `abi` | + +**Try saying this:** +- "I want to add 1000 USDT and equivalent SUNFLARE to V2 liquidity pool" +- "Remove 50% of my liquidity from the USDC-TRX pool" +- "Add V2 liquidity with minimum 950 USDT and 9500 SUNFLARE" + +:::info Auto-handling +When the pair involves TRX, the tool automatically converts to WTRX. +::: + +--- + +### V3 Liquidity + +| Tool Name | Function Description | Tool Type | Required Parameters | Optional Parameters | +|--------|---------|---------|---------|---------| +| `sunswap_v3_mint_position` | Create V3 concentrated liquidity position | Write | `positionManagerAddress`, `token0`, `token1` | `network`, `fee`, `tickLower`, `tickUpper`, `amount0Desired`, `amount1Desired`, `amount0Min`, `amount1Min`, `recipient`, `deadline`, `abi` | +| `sunswap_v3_increase_liquidity` | Increase V3 liquidity | Write | `positionManagerAddress`, `tokenId` | `network`, `token0`, `token1`, `fee`, `amount0Desired`, `amount1Desired`, `amount0Min`, `amount1Min`, `deadline` | +| `sunswap_v3_decrease_liquidity` | Decrease V3 liquidity | Write | `positionManagerAddress`, `tokenId`, `liquidity` | `network`, `token0`, `token1`, `fee`, `amount0Min`, `amount1Min`, `deadline` | +| `sunswap_v3_collect` | Collect V3 fees | Write | `positionManagerAddress`, `tokenId` | `network`, `recipient`, `abi` | + +**Try saying this:** +- "Help me create liquidity in the USDT-SUNFLARE V3 0.3% fee pool with range ±50 ticks" +- "Increase my V3 position #12345 by adding 1000 USDT" +- "Collect fees from my V3 position" +- "Decrease V3 liquidity to 50%" + +:::tip Auto-calculation +When creating a new position, the system automatically calculates tick range (±50×tickSpacing) and optimal single-sided input amounts. +::: + +--- + +### V4 Liquidity + +| Tool Name | Function Description | Tool Type | Required Parameters | Optional Parameters | +|--------|---------|---------|---------|---------| +| `sunswap_v4_mint_position` | Create V4 position (Permit2 supported) | Write | `token0`, `token1` | `network`, `fee`, `tickLower`, `tickUpper`, `amount0Desired`, `amount1Desired`, `slippage`, `recipient`, `deadline`, `sqrtPriceX96`, `createPoolIfNeeded` | +| `sunswap_v4_increase_liquidity` | Increase V4 liquidity (Permit2 supported) | Write | `tokenId`, `token0`, `token1` | `network`, `fee`, `amount0Desired`, `amount1Desired`, `slippage`, `deadline` | +| `sunswap_v4_decrease_liquidity` | Decrease V4 liquidity | Write | `tokenId`, `liquidity`, `token0`, `token1` | `network`, `fee`, `amount0Min`, `amount1Min`, `slippage`, `deadline` | +| `sunswap_v4_collect` | Collect V4 fees | Write | `tokenId` | `network`, `token0`, `token1`, `fee`, `deadline` | + +**Try saying this:** +- "Create a USDC-SUNFLARE liquidity position in V4 with 5% slippage" +- "Increase my V4 position #67890 by injecting 5000 USDC" +- "Collect all accumulated fees from V4 position" +- "Decrease V4 liquidity ensuring slippage stays within 3%" + +:::info Permit2 Support +V4 tools natively support Permit2 signature authorization, improving user experience. +::: + +--- + +### Contract Interaction + +| Tool Name | Function Description | Tool Type | Required Parameters | Optional Parameters | +|--------|---------|---------|---------|---------| +| `sunswap_read_contract` | Read data from TRON smart contract (view/pure) | Read | `address`, `functionName` | `network`, `args`, `abi` | +| `sunswap_send_contract` | Send state-changing contract transaction | Write | `address`, `functionName` | `network`, `args`, `value`, `abi` | + +**Try saying this:** +- "Query the total supply of SUNFLARE contract" +- "Read my balance in the liquidity contract" +- "Call contract function to update pool parameters" +- "Send 0.1 TRX to contract and execute specific function" + +:::caution ABI Requirement +If ABI is not provided, the system will attempt to retrieve contract ABI from TronScan. +::: + +--- + +## SUN.IO OpenAPI Derived Tools (23 total) + +### Transactions + +| Tool Name | Function Description | Required Parameters | Optional Parameters | +|--------|---------|---------|---------| +| `scanTransactions` | Scan DEX transactions | - | `protocol`, `token`, `pool`, `type`, `timeRange` | +| `getFarmTransactions` | Scan farm pool transactions | `farmAddress` | - | + +**Try saying this:** +- "View SUN protocol transactions from the past 24 hours" +- "Query all transactions in the SUNFLARE-USDT pool" +- "Get transaction data from the last 7 days" + +--- + +### Tokens + +| Tool Name | Function Description | Required Parameters | Optional Parameters | +|--------|---------|---------|---------| +| `getTokens` | Get tokens by address or protocol | - | `address`, `protocol` | +| `searchTokens` | Fuzzy search tokens | `keyword` | - | +| `getPrice` | Get token price by address | `tokenAddress` | - | + +**Try saying this:** +- "Search for 'SUNFLARE' token" +- "Get token information for address `TR7NHqjeKQxGTCi8q282JHJC8YXQFg...`" +- "Query USDT price in SUN protocol" + +--- + +### Protocol + +| Tool Name | Function Description | Required Parameters | Optional Parameters | +|--------|---------|---------|---------| +| `getProtocol` | Protocol snapshot data | - | - | +| `getVolHistory` | Protocol volume history | - | - | +| `getLiqHistory` | Protocol liquidity history | - | - | +| `getUsersCountHistory` | Protocol user count history | - | - | +| `getTransactionsHistory` | Protocol transaction count history | - | - | +| `getPoolsCountHistory` | Protocol pool count history | - | - | + +**Try saying this:** +- "Get the latest snapshot of SUN protocol" +- "View volume trends over the past 30 days" +- "Get protocol user growth information" + +--- + +### Price + +| Tool Name | Function Description | Required Parameters | Optional Parameters | +|--------|---------|---------|---------| +| `getPrice` | Token price query | `tokenAddress` | - | + +**Try saying this:** +- "Get the real-time price of SUNFLARE token" + +--- + +### Positions + +| Tool Name | Function Description | Required Parameters | Optional Parameters | +|--------|---------|---------|---------| +| `getUserPositions` | User liquidity positions | `userAddress` | - | +| `getPoolUserPositionTick` | Pool user tick-level position details | `poolAddress`, `userAddress` | - | +| `getFarmPositions` | User farm positions | `userAddress` | - | + +**Try saying this:** +- "View all my liquidity positions" +- "Get my tick-level details in the USDT-SUNFLARE pool" +- "Query my farm yield positions" + +--- + +### Pools + +| Tool Name | Function Description | Required Parameters | Optional Parameters | +|--------|---------|---------|---------| +| `getPools` | Get pools | - | `address`, `token`, `protocol` | +| `searchPools` | Search pools | `keyword` | - | +| `searchCountPools` | Pool search count | `keyword` | - | +| `getTopApyPoolList` | Get top APY pool list | - | `limit`, `offset` | +| `getPoolHooks` | Pool hooks | `poolAddress` | - | +| `getPoolVolHistory` | Pool volume history | `poolAddress` | - | +| `getPoolLiqHistory` | Pool liquidity history | `poolAddress` | - | + +**Try saying this:** +- "Get detailed information about the SUNFLARE-USDT pool" +- "Find the top 10 pools with highest APY" +- "Get volume history of the USDC-TRX pool" +- "Query all hooks used by the pool" + +--- + +### Trading Pairs + +| Tool Name | Function Description | Required Parameters | Optional Parameters | +|--------|---------|---------|---------| +| `getPairsFromEntity` | Token pair query | - | `token0`, `token1` | + +**Try saying this:** +- "Get trading pair information between SUNFLARE and USDT" +- "Query all trading pairs containing USDC" + +--- + +### Farm + +| Tool Name | Function Description | Required Parameters | Optional Parameters | +|--------|---------|---------|---------| +| `getFarms` | Farm pool list | - | - | + +**Try saying this:** +- "List all available farm pools" +- "Query current farm reward situation" + +--- + +## Auto-Calculation Features + +SUN MCP Server has multiple tools with built-in intelligent auto-calculation features designed to simplify user interaction: + +### V3 Liquidity Auto-Calculation + +**`sunswap_v3_mint_position` Auto Features:** + +| Feature | Description | Use Case | +|------|------|---------| +| **Default Fee** | If `fee` not specified, system automatically uses `3000` (0.3%) | Quickly create standard liquidity position | +| **Tick Range Calculation** | Automatically set `tickLower` and `tickUpper` to `±50 × tickSpacing` | No need to manually calculate complex math, get reasonable range directly | +| **Single-Sided Input Handling** | Can specify only one token amount, system automatically calculates required amount of other token | Simplify multi-token liquidity deployment | + +**Example:** +``` +Request: Create V3 position in USDT-SUNFLARE pool, inject 1000 USDT +System automatically: + - Set fee to 3000 (0.3%) + - Calculate ±50 tick range + - Based on current price, calculate required SUNFLARE amount + - Submit multi-token authorization and transaction in one go +``` + +### V4 Liquidity Auto-Calculation + +**`sunswap_v4_mint_position` Auto Features:** + +| Feature | Description | Use Case | +|------|------|---------| +| **Tick Range Calculation** | Automatically set `tickLower` and `tickUpper` to `±100 × tickSpacing` | V4's more flexible range configuration | +| **Default Slippage** | If `slippage` not specified, system automatically uses `5%` | Protect users from price volatility | +| **Permit2 Authorization** | Native support for Permit2 signature process, no need for multiple approvals | Improve user experience, complete all authorizations with one signature | +| **Dynamic Pool Creation** | If pool doesn't exist, `createPoolIfNeeded` can automatically create new pool | Quickly establish liquidity for new trading pairs | + +**Example:** +``` +Request: Create USDC-SUNFLARE position in V4 with 3% slippage +System automatically: + - Calculate ±100 tick range + - Use Permit2 signature authorization + - Create new pool if it doesn't exist + - Based on current price, calculate optimal input ratio +``` + +### Smart Swap Routing + +**`sunswap_swap` Auto Features:** + +| Feature | Description | Use Case | +|------|------|---------| +| **Multi-Route Optimization** | Automatically find optimal swap path, support direct trading pairs and multi-hop routes | Get best price | +| **Permit2 Integration** | No need to pre-approve tokens, complete authorization and swap with one signature | Improve user flow | + +**Example:** +``` +Request: Swap 1000 USDT for SUNFLARE with 1% slippage +System automatically: + - Evaluate direct USDT-SUNFLARE pool + - Evaluate USDT → intermediate → SUNFLARE routes + - Choose optimal path + - Use Permit2 one-time signature to complete authorization and trade + - Ensure slippage doesn't exceed 1% +``` + +### Key Parameter Reference + +| Parameter | Default Value | When Auto-Calculated | +|------|--------|-----------| +| `fee` (V3) | 3000 | When not provided | +| `tickLower`, `tickUpper` (V3) | ±50×tickSpacing | When not provided | +| `tickLower`, `tickUpper` (V4) | ±100×tickSpacing | When not provided | +| `slippage` (V4) | 5% | When not provided | +| Counterparty token amount | Calculated by current price | When only one token amount specified | + +:::tip Best Practice +Although most parameters are auto-calculated, for critical operations (such as adding large amounts of liquidity), it's recommended to actively specify parameters to get higher control precision. +::: + +--- + +## Quick Reference + +**Need to query data?** Use read tools: `get_*`, `search_*`, `scan*` series. + +**Need to execute transactions?** Use write tools: `swap`, `mint`, `add`, `remove`, `collect`, `send_contract` series. + +**Not sure about parameters?** Tools will auto-calculate reasonable defaults, or prompt you for additional info when necessary. + +**Want to learn more?** Check [SUN MCP Server main documentation](../README.md) or [API Reference](../API-Reference.md). + diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/API.md b/docs/McpServer-Skills/MCP/TRONMCPServer/API.md deleted file mode 100644 index 8bcfd510..00000000 --- a/docs/McpServer-Skills/MCP/TRONMCPServer/API.md +++ /dev/null @@ -1,216 +0,0 @@ -# API Reference - -## Tools (95 total) - -### Wallet & Address - -| Tool Name | Description | Key Parameters | Mode | -| :-- | :-- | :-- | :-- | -| `get_wallet_address` | Get the address of the configured wallet. | - | Read | -| `list_wallets` | List all available wallets. | - | Read | -| `select_wallet` | Switch the active wallet at runtime. | `walletId` | Write | -| `sign_message` | Sign an arbitrary message using the configured wallet. | `message` | Write | -| `convert_address` | Convert addresses between Hex and Base58 formats. | `address` | Read | - -### Network & Chain - -| Tool Name | Description | Key Parameters | Mode | -| :-- | :-- | :-- | :-- | -| `get_chain_info` | Get current block number and chain ID. | `network` | Read | -| `get_chain_parameters` | Get current energy and bandwidth unit prices. | `network` | Read | -| `get_supported_networks` | List all supported TRON networks. | - | Read | - -### Blocks - -| Tool Name | Description | Key Parameters | Mode | -| :-- | :-- | :-- | :-- | -| `get_block` | Get block details by number or hash. | `blockIdentifier`, `network` | Read | -| `get_latest_block` | Get the latest block. | `network` | Read | - -### Transactions - -| Tool Name | Description | Key Parameters | Mode | -| :-- | :-- | :-- | :-- | -| `get_transaction` | Get transaction details by hash. | `txHash`, `network` | Read | -| `get_transaction_info` | Get receipt including resource usage. | `txHash`, `network` | Read | - -### Balances - -| Tool Name | Description | Key Parameters | Mode | -| :-- | :-- | :-- | :-- | -| `get_balance` | Get TRX balance of an address. | `address`, `network` | Read | -| `get_token_balance` | Get TRC20 token balance of an address. | `address`, `tokenAddress`, `network` | Read | - -### Transfers - -| Tool Name | Description | Key Parameters | Mode | -| :-- | :-- | :-- | :-- | -| `transfer_trx` | Transfer TRX to an address. | `to`, `amount`, `network` | Write | -| `transfer_trc20` | Transfer TRC20 tokens to an address. | `tokenAddress`, `to`, `amount`, `network` | Write | - -### Smart Contracts - -| Tool Name | Description | Key Parameters | Mode | -| :-- | :-- | :-- | :-- | -| `read_contract` | Call read-only functions on a smart contract. | `contractAddress`, `functionName`, `args`, `abi`, `network` | Read | -| `write_contract` | Execute state-changing functions on a smart contract. | `contractAddress`, `functionName`, `args`, `abi`, `value`, `network` | Write | -| `deploy_contract` | Deploy a smart contract to the network. | `abi`, `bytecode`, `args`, `name`, `network`, `feeLimit` | Write | -| `estimate_energy` | Estimate energy consumption for a contract call. | `address`, `functionName`, `args`, `abi`, `network` | Read | -| `multicall` | Execute multiple read-only calls in a single batch. | `calls`, `network`, `multicallAddress`, `version` | Read | -| `get_contract` | Get raw contract metadata (ABI and bytecode). | `contractAddress`, `network` | Read | -| `get_contract_info` | Get high-level contract information. | `contractAddress`, `network` | Read | -| `fetch_contract_abi` | Fetch contract ABI from the chain. | `contractAddress`, `network` | Read | -| `update_contract_setting` | Update contract consume_user_resource_percent. | `contractAddress`, `consumeUserResourcePercent`, `network` | Write | -| `update_energy_limit` | Update contract originEnergyLimit. | `contractAddress`, `originEnergyLimit`, `network` | Write | -| `clear_abi` | Clear the on-chain ABI metadata of a contract. | `contractAddress`, `network` | Write | - -### Account Management - -| Tool Name | Description | Key Parameters | Mode | -| :-- | :-- | :-- | :-- | -| `get_account` | Get full account info (balance, resources, permissions). | `address`, `network` | Read | -| `get_account_balance` | Get TRX balance at a specific block height. | `address`, `blockHash`, `blockNumber`, `network` | Read | -| `get_account_net` | Get bandwidth resource information. | `address`, `network` | Read | -| `get_account_resource` | Get energy, bandwidth, frozen balance, and delegation info. | `address`, `network` | Read | -| `get_delegated_resource` | Query delegated resources between two accounts. | `fromAddress`, `toAddress`, `network` | Read | -| `get_delegated_resource_index` | Query resource delegation index. | `address`, `network` | Read | -| `generate_account` | Generate a new TRON account. | - | Read | -| `validate_address` | Validate a TRON address and detect format. | `address` | Read | -| `create_account` | Activate a new account on the network. | `address`, `network` | Write | -| `update_account` | Update account name. | `accountName`, `network` | Write | -| `account_permission_update` | Update account permissions (multi-sig). | `ownerPermission`, `activePermissions`, `witnessPermission`, `network` | Write | - -### Account Data (TronGrid) - -| Tool Name | Description | Key Parameters | Mode | -| :-- | :-- | :-- | :-- | -| `get_account_info` | Get comprehensive account info from TronGrid. | `address`, `network` | Read | -| `get_account_transactions` | Get transaction history for an account. | `address`, `limit`, `fingerprint`, `network` | Read | -| `get_account_trc20_transactions` | Get TRC20 transfer history. | `address`, `contractAddress`, `limit`, `fingerprint`, `network` | Read | -| `get_account_internal_transactions` | Get internal transactions for an account. | `address`, `limit`, `fingerprint`, `network` | Read | -| `get_account_trc20_balances` | Get all TRC20 token balances. | `address`, `network` | Read | - -### Contract Data (TronGrid) - -| Tool Name | Description | Key Parameters | Mode | -| :-- | :-- | :-- | :-- | -| `get_contract_transactions` | Get transaction history for a contract. | `address`, `limit`, `fingerprint`, `network` | Read | -| `get_contract_internal_transactions` | Get internal transactions for a contract. | `address`, `limit`, `fingerprint`, `network` | Read | -| `get_trc20_token_holders` | Get token holder list for a TRC20 contract. | `address`, `limit`, `fingerprint`, `network` | Read | - -### Resource Delegation (Stake 2.0) - -| Tool Name | Description | Key Parameters | Mode | -| :-- | :-- | :-- | :-- | -| `delegate_resource` | Delegate staked resources to another address. | `receiverAddress`, `amount`, `resource`, `lock`, `lockPeriod`, `network` | Write | -| `undelegate_resource` | Revoke previously delegated resources. | `receiverAddress`, `amount`, `resource`, `network` | Write | -| `get_can_delegated_max_size` | Get max delegatable TRX amount. | `address`, `resource`, `network` | Read | -| `get_delegated_resource_v2` | Get delegated resource details between two addresses. | `fromAddress`, `toAddress`, `network` | Read | -| `get_delegated_resource_account_index_v2` | Get delegated resource account index. | `address`, `network` | Read | - -### Staking (Stake 2.0) - -| Tool Name | Description | Key Parameters | Mode | -| :-- | :-- | :-- | :-- | -| `freeze_balance_v2` | Freeze TRX to obtain resources. | `amount`, `resource`, `network` | Write | -| `unfreeze_balance_v2` | Unfreeze TRX to release resources. | `amount`, `resource`, `network` | Write | -| `withdraw_expire_unfreeze` | Withdraw expired unfrozen balance. | `network` | Write | -| `cancel_all_unfreeze_v2` | Cancel pending unfreezes and re-stake. | `network` | Write | -| `get_available_unfreeze_count` | Get remaining unfreeze operations count. | `address`, `network` | Read | -| `get_can_withdraw_unfreeze_amount` | Get withdrawable unstaked TRX amount. | `address`, `timestampMs`, `network` | Read | - -### Governance & Super Representatives - -| Tool Name | Description | Key Parameters | Mode | -| :-- | :-- | :-- | :-- | -| `list_witnesses` | List all Super Representatives on the network. | `network` | Read | -| `get_paginated_witnesses` | Get paginated list of active SRs. | `offset`, `limit`, `network` | Read | -| `get_next_maintenance_time` | Get next maintenance window timestamp. | `network` | Read | -| `get_reward` | Query unclaimed voting reward for an address. | `address`, `network` | Read | -| `get_brokerage` | Query SR brokerage ratio. | `witnessAddress`, `network` | Read | -| `create_witness` | Apply to become a Super Representative (9999 TRX). | `url`, `network` | Write | -| `update_witness` | Update SR website URL. | `url`, `network` | Write | -| `vote_witness` | Vote for Super Representatives. | `votes`, `network` | Write | -| `withdraw_balance` | Withdraw accumulated voting rewards. | `network` | Write | -| `update_brokerage` | Update SR brokerage ratio. | `brokerage`, `network` | Write | - -### Proposals - -| Tool Name | Description | Key Parameters | Mode | -| :-- | :-- | :-- | :-- | -| `list_proposals` | List all governance proposals. | `network` | Read | -| `get_proposal` | Get proposal details by ID. | `proposalId`, `network` | Read | -| `create_proposal` | Create a governance proposal (SR only). | `parameters`, `network` | Write | -| `approve_proposal` | Vote to approve/disapprove a proposal. | `proposalId`, `approve`, `network` | Write | -| `delete_proposal` | Delete a governance proposal. | `proposalId`, `network` | Write | - -### Events - -| Tool Name | Description | Key Parameters | Mode | -| :-- | :-- | :-- | :-- | -| `get_events_by_transaction_id` | Get events emitted by a transaction. | `transactionId`, `network` | Read | -| `get_events_by_contract_address` | Get events emitted by a contract. | `contractAddress`, `eventName`, `limit`, `network` | Read | -| `get_events_by_block_number` | Get events in a specific block. | `blockNumber`, `network` | Read | -| `get_events_of_latest_block` | Get events from the latest block. | `network` | Read | - -### Mempool - -| Tool Name | Description | Key Parameters | Mode | -| :-- | :-- | :-- | :-- | -| `get_pending_transactions` | Get pending transaction IDs in the mempool. | `network` | Read | -| `get_transaction_from_pending` | Get a specific pending transaction. | `txId`, `network` | Read | -| `get_pending_size` | Get number of pending transactions. | `network` | Read | - -### Node - -| Tool Name | Description | Key Parameters | Mode | -| :-- | :-- | :-- | :-- | -| `list_nodes` | List all connected node addresses. | `network` | Read | -| `get_node_info` | Get detailed node information. | `network` | Read | - -### Full-Node Query API - -| Tool Name | Description | Key Parameters | Mode | -| :-- | :-- | :-- | :-- | -| `get_block_by_num` | Query block by height. | `num`, `network` | Read | -| `get_block_by_id` | Query block by hash. | `value`, `network` | Read | -| `get_block_by_latest_num` | Get most recent N blocks. | `num`, `network` | Read | -| `get_block_by_limit_next` | Get blocks within a height range. | `startNum`, `endNum`, `network` | Read | -| `get_now_block` | Get current latest block. | `network` | Read | -| `get_transaction_by_id` | Query transaction by hash. | `value`, `network` | Read | -| `get_transaction_info_by_id` | Query transaction receipt. | `value`, `network` | Read | -| `get_transaction_info_by_block_num` | Get receipts for all transactions in a block. | `num`, `network` | Read | -| `get_energy_prices` | Query historical energy unit prices. | `network` | Read | -| `get_bandwidth_prices` | Query historical bandwidth unit prices. | `network` | Read | -| `get_burn_trx` | Query total TRX burned from fees. | `network` | Read | -| `get_approved_list` | Query accounts that signed a transaction. | `transaction`, `network` | Read | -| `get_block_balance` | Get all balance changes in a block. | `hash`, `number`, `network` | Read | - -### Broadcast & Transaction Building - -| Tool Name | Description | Key Parameters | Mode | -| :-- | :-- | :-- | :-- | -| `broadcast_transaction` | Broadcast a signed transaction (JSON). | `transaction`, `network` | Write | -| `broadcast_hex` | Broadcast a signed transaction (hex). | `transaction`, `network` | Write | -| `create_transaction` | Create an unsigned TRX transfer transaction. | `ownerAddress`, `toAddress`, `amount`, `network` | Write | - ---- - -## Prompts (6 total) - -| Prompt Name | Description | Key Parameters | Requires Wallet | -| :-- | :-- | :-- | :-- | -| `prepare_transfer` | Safely prepare and execute a token transfer with validation checks. | `tokenType`, `recipient`, `amount`, `network`, `tokenAddress` | Yes | -| `interact_with_contract` | Safely execute write operations on a smart contract with validation. | `contractAddress`, `functionName`, `args`, `value`, `network` | Yes | -| `diagnose_transaction` | Analyze transaction status, failures, and provide debugging insights. | `txHash`, `network` | No | -| `explain_tron_concept` | Explain TRON and blockchain concepts with examples. | `concept` | No | -| `analyze_wallet` | Get comprehensive overview of wallet assets and activity. | `address`, `network`, `tokens` | No | -| `check_network_status` | Check current network health and conditions. | `network` | No | - ---- - -## Resources (1 total) - -| Resource Name | URI | Description | -| :-- | :-- | :-- | -| `supported_networks` | `tron://networks` | Get list of all supported TRON networks and their configuration. | diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md b/docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md new file mode 100644 index 00000000..d515d7b8 --- /dev/null +++ b/docs/McpServer-Skills/MCP/TRONMCPServer/FAQ.md @@ -0,0 +1,242 @@ +# FAQ & Troubleshooting + +When you encounter problems, check here first. Organized by the order you're most likely to encounter them: connection issues (most common), then authentication and keys, on-chain errors, AI behavior issues, and finally some general questions. + +--- + +## Connection Issues + +Connection issues usually occur during the initial configuration phase. If your AI client can't recognize the TRON tools, this is likely where the problem is. + +### "Failed to connect to MCP server" in Claude Desktop + +This is the most common issue. Troubleshoot in the following order: + +1. **Check Node.js version**. TRON MCP Server requires v20.0.0 or higher: + ```bash + node --version # Should output v20.x.x or higher + ``` + If your version is too low, upgrade Node.js first. + +2. **Check that npx is available**. Run `npx --version` in your terminal. If the command is not found, your Node.js installation is incomplete — reinstall it. + +3. **Verify config file format**. `claude_desktop_config.json` must be valid JSON. Common mistakes include trailing commas, missing quotes, or mismatched brackets. Quickly validate with: + ```bash + cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python3 -m json.tool + ``` + If formatted JSON is printed, the format is fine. If there's an error, fix it according to the message. + +4. **Fully quit and restart**. Closing the window is not the same as quitting — you need to fully exit Claude Desktop from the menu bar/system tray, then reopen it. On macOS, right-click the Dock icon and choose "Quit". + +5. **Check logs**. If none of the above resolves the issue, check Claude Desktop's log files. On macOS they're in `~/Library/Logs/Claude/` — search for entries containing "mcp" or "tron". + +### "Connection refused" in HTTP mode + +When using HTTP mode (`npm run start:http`) and clients cannot connect, the usual causes are: + +1. **Server is not running**. Confirm first: + ```bash + curl http://localhost:3001/health + ``` + If it returns "Connection refused", the server process is not started or has exited. + +2. **Port is occupied**. Another program may be using port 3001: + ```bash + lsof -i :3001 + ``` + If there's a conflict, switch to a different port via environment variable: + ```bash + export MCP_PORT=3002 + ``` + +3. **Firewall blocking**. If you're accessing the local HTTP service from another machine, check whether the firewall allows inbound connections on that port. + +### Only read tools in the tool list, no write tools + +This is not an error — it's by design. Write tools (transfers, staking, etc.) are only registered into the AI's tool list after a wallet is configured. If you haven't set any wallet environment variables, the server automatically runs in read-only mode. + +To unlock write tools, configure one of the three wallet modes: + +- Set `AGENT_WALLET_PASSWORD` (Agent Wallet mode, recommended) +- Set `TRON_PRIVATE_KEY` (Private Key mode) +- Set `TRON_MNEMONIC` (Mnemonic mode) + +After configuring, restart your AI client. For detailed instructions, see [Local Private Deployment](./LocalPrivatizedDeployment.md). + +--- + +## Authentication & Key Issues + +### "Invalid private key" error + +If the server reports an invalid private key at startup, it's usually a format issue: + +1. **Check key format**. The private key should be a 64-character hex string, with or without the `0x` prefix: + ``` + # Valid formats: + abc123def456... (64 hex characters) + 0xabc123def456... (0x + 64 hex characters) + ``` + +2. **Avoid extra spaces or quotes**. Environment variable values must not contain extra spaces, nested quotes, or newline characters: + ```bash + # Correct + export TRON_PRIVATE_KEY=abc123def456... + + # Wrong (quotes become part of the value) + export TRON_PRIVATE_KEY="'abc123def456...'" + ``` + +3. **Verify the key is valid**. Import the same private key into a TRON wallet (like TronLink) to confirm it works. + +### "Agent wallet password incorrect" error + +`AGENT_WALLET_PASSWORD` must exactly match the master password set during `agent-wallet init`. If you're not sure: + +1. **Check that the wallet directory exists**: + ```bash + ls ~/.agent-wallet/ # Default location + ``` + If you used a custom directory, ensure `AGENT_WALLET_DIR` points to the correct path. + +2. **If the password is lost**, you'll need to re-initialize. Note: this creates a new wallet — funds in the old wallet must be recovered through other means. + ```bash + agent-wallet init + ``` + +### TronGrid API Key not working + +The API Key is configured but requests are still rate-limited — check the following: + +1. **Is the variable name correct?** The correct name is `TRONGRID_API_KEY` (not `TRON_API_KEY` or other variants). + +2. **Is the Key still active?** Log into [trongrid.io](https://www.trongrid.io/) to confirm your API Key is active. + +3. **Header format for cloud service**. When using the official cloud service with an API Key, the `--header` parameter format must be `TRONGRID-API-KEY:your-key` with no spaces around the colon. + +--- + +## On-Chain Errors + +These errors occur during transaction execution and are usually related to on-chain resources or contract logic. + +### "Bandwidth not sufficient" error + +Every TRON transaction consumes Bandwidth. If the account has neither enough staked Bandwidth nor enough TRX to burn for Bandwidth, the transaction fails. + +**How to resolve:** +- Have the AI check your Bandwidth first: "Check the bandwidth resources of my address" +- Stake some TRX for Bandwidth: "Stake 100 TRX for Bandwidth" +- Or ensure the account has enough TRX balance — even without staked Bandwidth, the system will automatically burn TRX to pay for it + +### "Energy not sufficient" error + +Interacting with smart contracts (including TRC20 token transfers) requires Energy. If staked Energy is insufficient, TRX is burned to cover the cost; if TRX is also insufficient, the transaction fails. + +**How to resolve:** +- Estimate cost first: "Estimate how much Energy is needed to call this contract's transfer function" +- Stake TRX for Energy: "Stake 500 TRX for Energy" +- If using `write_contract`, have the AI increase the `feeLimit` parameter + +### "Account not found" or "Account not activated" + +New TRON addresses must be "activated" before they can be used. An address is automatically activated when it receives its first TRX transfer. + +**How to resolve:** +- Send a small amount of TRX to the address (0.1 TRX is enough) +- Or use the `create_account` tool to explicitly activate it + +### Transaction shows "REVERT" status + +The transaction was included in a block but execution failed, meaning a `require()` condition in the smart contract code was not met. + +**How to diagnose:** +1. Have the AI diagnose: "Diagnose why transaction [hash] reverted" +2. Common causes include: insufficient token balance or approval amount, calling a function without the required permission, passing invalid parameters, or a contract-specific business logic condition not met +3. Use `read_contract` to query the contract state and understand what preconditions need to be met + +--- + +## AI Behavior Issues + +These issues relate to the behavior of the AI model itself, not bugs in TRON MCP Server. + +### AI constructs an invalid address + +AI models sometimes "hallucinate" TRON addresses that are correctly formatted but don't actually exist. TRON MCP Server has built-in address validation — most tools that accept addresses will automatically reject invalid ones. + +**Prevention:** +- Always provide exact addresses by copy-pasting; don't describe addresses and let the AI guess +- When uncertain, use `validate_address` to verify: "Validate this address TXyz..." + +### AI tries to call a tool that doesn't exist + +The AI may confuse TRON MCP Server capabilities with other blockchain tools. If it tries to call a nonexistent tool, it will receive an error and automatically try using the correct one. + +If this keeps happening, remind the AI: "Please only use tools provided by TRON MCP Server", or consult the [Full Capability List](./ToolList.md) to confirm available tools. + +### Responses are slow + +Several common causes and solutions: + +- **No TronGrid API Key**: Public RPC has rate limits; adding a free API Key can significantly improve performance +- **Complex multi-tool workflows**: Some operations (like full wallet analysis) require multiple sequential calls — waiting is normal +- **Use testnet for development**: Nile and Shasta testnets are usually faster +- **Be more specific in prompts**: Reduce the AI's exploratory calls — tell it directly which tool to use and which network to query + +--- + +## General Questions + +### What's the difference between Mainnet, Nile, and Shasta? + +| Network | Purpose | Real Value | How to Get Tokens | +| :--- | :--- | :--- | :--- | +| **Mainnet** | Production environment | Yes (real TRX) | Buy on exchanges | +| **Nile** | Development testing (recommended) | No (test tokens) | Free from faucet | +| **Shasta** | Development testing | No (test tokens) | Free from faucet | + +Always develop and test on Nile first, then execute on Mainnet after confirming everything works. + +### Can I use multiple TRON MCP Servers simultaneously? + +Yes. Define multiple MCP Server entries in your config — for example, one connecting to the mainnet cloud service (read-only) and another connecting to a local testnet deployment (with wallet). Just use different names: + +```json +{ + "mcpServers": { + "tron-mainnet": { + "command": "npx", + "args": ["mcp-remote", "https://tron-mcp-server.bankofai.io/mcp"] + }, + "tron-local": { + "command": "npx", + "args": ["-y", "@bankofai/mcp-server-tron"], + "env": { + "AGENT_WALLET_PASSWORD": "your-password" + } + } + } +} +``` + +### How do I update to the latest version? + +If you're using the `npx` method, you always get the latest published version. To force clearing the cache: + +```bash +npx clear-npx-cache +``` + +If you cloned from source: + +```bash +cd mcp-server-tron +git pull +npm install +npm run build +``` + +### What MCP protocol version is supported? + +TRON MCP Server supports MCP protocol version **2025-11-25**, using `@modelcontextprotocol/sdk` 1.22.0 or higher. diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/Intro.md b/docs/McpServer-Skills/MCP/TRONMCPServer/Intro.md index fe6450dc..054efd9c 100644 --- a/docs/McpServer-Skills/MCP/TRONMCPServer/Intro.md +++ b/docs/McpServer-Skills/MCP/TRONMCPServer/Intro.md @@ -1,60 +1,98 @@ # Introduction -TRON MCP Server is designed to provide AI agents with the ability to interact with the TRON blockchain. Through a unified interface, AI agents can utilize tools and AI-guided prompts to access TRON network services, supporting TRX, TRC20 tokens, and smart contract operations. The server leverages the `tronweb` library to fully support the TRON ecosystem. +## What is TRON MCP Server? -## MCP Server URL -For the convenience of users with different needs, you can choose to connect directly to the [official cloud service](./OfficialServerAccess.md) or choose to perform [local deployment](./LocalPrivatizedDeployment.md) on your own computer. Among them, the official service only provides reading services. +TRON MCP Server is a bridge that connects AI assistants with the TRON blockchain. Built on the [Model Context Protocol (MCP)](../Intro.md) standard, it lets you interact with the blockchain using natural language — checking balances, initiating transfers, calling smart contracts — without writing any code. -| Environment | URL | -| :------- | :--------------------------------------- | -| Production | [https://tron-mcp-server.bankofai.io/mcp](https://tron-mcp-server.bankofai.io/mcp) | +For example: just tell Claude "Check how much USDT this address has", and the AI will automatically call the on-chain query tool, organize the results, and return them to you. No need to open a block explorer, no need to construct API requests, no need to understand the underlying JSON-RPC protocol. +This means different things to different people: -## Core Capabilities Overview +- If you are an **AI application user**, it lets you operate blockchain directly in Claude Desktop, Cursor, and other tools — as easy as everyday chat. +- If you are a **Web3 developer**, it's your rapid on-chain prototyping tool — debug contracts and query state in natural language, saving vast amounts of boilerplate code. +- If you are an **AI Agent builder**, it provides 95 standardized on-chain tools that can be orchestrated directly into your automation workflows. +- If you are a **data analyst**, it turns on-chain data queries into conversation — no more writing scripts to scrape and parse. -* **Blockchain Data**: Read blocks, transactions, and chain parameters (such as energy/bandwidth costs). -* **Smart Contracts**: Interact with any TRON smart contract (supports read/write). -* **Token Services**: Transfer TRX and TRC20 tokens; check balances and metadata. -* **Address Management**: Convert and verify addresses between Hex and Base58 formats. -* **Security Integration**: Supports private key and mnemonic (BIP-39) wallets to ensure secure operations. -* **Multi-Network Support**: Fully covers Mainnet, Nile, and Shasta testnets. +--- +## What Can It Do? -## Detailed Functional Features +TRON MCP Server covers almost all common TRON blockchain operations, from read-only queries to asset management, providing **95 tools**, **6 prompt templates**, and **1 resource definition**. -A specific list of functions provided by TRON MCP Server for the reference of developers and advanced users: +Here is an overview of core capabilities — each one can be triggered via natural language: -### Blockchain Data Access -* **Multi-Network Support**: Supports Mainnet, Nile, and Shasta networks. -* **Chain Information Query**: Get current block height, chain ID, and RPC node information. -* **Block Data**: Access detailed block information via block number or hash. -* **Transaction Details**: Get full details of transactions, including resource consumption (energy/bandwidth). -* **Resource Cost Query**: Real-time query of price parameters for energy and bandwidth on the chain. +| Capability | Description | You can say | +| :--- | :--- | :--- | +| **Balance Queries** | Query TRX or any TRC20 token balance | "How much USDT does this address have?" | +| **Transfer Operations** | Send TRX or TRC20 tokens to specified addresses | "Transfer 100 TRX to TXyz..." | +| **Smart Contracts** | Read, write, deploy, and debug smart contracts | "Call the balanceOf method of this contract" | +| **Transaction Queries** | Look up transaction details, status, and resource consumption | "Check the status of this transaction hash" | +| **Account Management** | View account resources, permissions, staking status | "Show the Energy and Bandwidth of this address" | +| **Staking & Delegation** | Stake TRX for resources, delegate Energy/Bandwidth | "Stake 1000 TRX for Energy" | +| **Governance Participation** | View Super Representatives, vote, manage proposals | "List all current Super Representative candidates" | +| **On-Chain Events** | Query contract events and transaction logs | "Get the recent Transfer events of this contract" | +| **Network Status** | Block production, resource prices, chain health | "What is the current TRON block height?" | +| **Wallet Management** | Multi-wallet switching, message signing, address conversion | "Convert this address to Base58 format" | -### Token Services -* **Native TRX**: Supports balance query and transfer operations. -* **TRC20 Tokens**: - * Query token balance. - * Execute token transfers. - * Get token metadata (name, symbol, precision). +For the Full Capability List and parameter descriptions, see the [Full Capability List](./ToolList.md). -### Address Services -* **Format Conversion**: Seamlessly convert between Hex (`41...` or `0x...`) and Base58 (`T...`) formats. -* **Address Verification**: Verify the validity of a specific address on the TRON network. +--- -### Smart Contract Interaction -* **Read Contract**: Call `view` and `pure` type functions. -* **Write Contract**: Execute contract functions that change the state on the chain. -* **ABI Auto-Acquisition**: Automatically acquire the ABI interface of verified contracts from the blockchain. +## Two Access Methods -### Wallet and Security -* **Flexible Configuration**: Supports configuration via `TRON_PRIVATE_KEY` or `TRON_MNEMONIC`. -* **Hierarchical Deterministic (HD) Wallet**: Supports BIP-44 derivation path `m/44'/195'/0'/0/{index}`. -* **Message Signing**: Supports secure signing of arbitrary messages. +Once you understand what TRON MCP Server can do, you need to choose an access method. There are two paths depending on your use case: + +**[Official Cloud Service](./OfficialServerAccess.md)** — Ideal for quick experimentation and data queries. No installation needed — just add one line in your AI client configuration to get started. However, the cloud service only provides **read-only** capabilities; it does not support transfers, contract writes, or other operations. + +**[Local Private Deployment](./LocalPrivatizedDeployment.md)** — For users who need full functionality. Run TRON MCP Server on your own machine, and once your wallet is configured, all read and write capabilities are unlocked. Private keys are managed entirely locally and are never uploaded to any remote service. + +The core distinction comes down to one point: **whether you need to sign transactions**. + +| Comparison Item | Official Cloud Service | Local Private Deployment | +| :--- | :--- | :--- | +| **Feature Scope** | Read-only (queries only) | Full features (read + write) | +| **Setup Difficulty** | Just add one config line | Requires local installation and build | +| **Private Key Required** | No | Yes (for write operations) | +| **Transfer/Contract Writing** | Not supported | Supported | +| **Suitable For** | Quick queries, getting started | Development, debugging, automated trading | +| **Security** | High (no private key exposure) | Depends on your key management | + +:::tip Not Sure Which to Choose? +If you just want to try it out, or only need to query on-chain data in your daily use, start with the [Official Cloud Service](./OfficialServerAccess.md) — connect in 1 minute. When you need to transfer funds or write to contracts, switch to [Local Private Deployment](./LocalPrivatizedDeployment.md). +::: + +--- + +## Supported Networks + +Regardless of which access method you choose, TRON MCP Server supports the following three networks (defaulting to Mainnet): + +| Network | Identifier | Purpose | Explorer | +| :--- | :--- | :--- | :--- | +| **Mainnet** | `mainnet` | Production environment, real assets | [tronscan.org](https://tronscan.org) | +| **Nile Testnet** | `nile` | Development testing (recommended) | [nile.tronscan.org](https://nile.tronscan.org) | +| **Shasta Testnet** | `shasta` | Development testing | [shasta.tronscan.org](https://shasta.tronscan.org) | + +Specify the target network via the `network` parameter when calling tools, e.g., "Check the balance of this address on the Nile testnet." + +--- ## 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. -* **Testnet First**: Always thoroughly test on Nile or Shasta testnets before deploying any operations to the mainnet. -* **Principle of Least Privilege**: Wallets configured for AI agents should only contain the minimum funds required to perform their tasks. - +:::warning +Before getting started, keep these security principles in mind — especially for operations involving real assets: + +- **Never hardcode private keys**: Do not write private keys or mnemonic phrases directly in configuration files (such as `claude_desktop_config.json`). Use system environment variables or an encrypted wallet instead. +- **Test on testnet first**: Always run through and verify on Nile or Shasta testnets before performing any operation on Mainnet. +- **Minimum funds principle**: The wallet configured for AI agents should only hold the minimum funds required for the task. +- **Pay attention to authorization risks**: Be especially cautious with token approval (`approve`) operations — avoid granting unlimited authorization. +::: + +--- + +## Next Steps + +- Want the fastest way to get started? → [Quick Start](./QuickStart.md) +- Only need to query on-chain data? → [Official Cloud Service Access](./OfficialServerAccess.md) +- Need transfers, contract calls, and full functionality? → [Local Private Deployment](./LocalPrivatizedDeployment.md) +- Want to see all 95 tools? → [Full Capability List](./ToolList.md) diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md b/docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md index f7bc2ed9..13ea15ee 100644 --- a/docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md +++ b/docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md @@ -1,97 +1,225 @@ -# Local Privatized Deployment +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; -If you need to perform write operations such as transfers and contract calls, you must deploy the server locally. Local deployment allows you to securely configure private keys, thereby enabling full transaction functions. +# Local Private Deployment -## Environment Requirements -* **Node.js**: v20.0.0 or higher. -* Optional: **TronGrid API Key**: It is recommended to apply ([trongrid.io](https://www.trongrid.io/)) to avoid mainnet frequency limits. +## What is Local Private Deployment? +Local private deployment means running TRON MCP Server on your own machine, giving your AI assistant **full read and write access** to the TRON blockchain. -## Key Configuration (Environment Variables) -**Important Security Note**: For your safety, **NEVER** save your private keys or mnemonics directly in MCP configuration files (such as `claude_desktop_config.json` or `mcp.json`). Instead, please set them as environment variables in your operating system or shell configuration. +With the [official cloud service](./OfficialServerAccess.md), you can query all publicly available on-chain data. But once you need actual asset operations — sending TRX to an address, calling state-changing functions on smart contracts, staking TRX for energy, voting for Super Representatives — these operations require signing transactions with your private key. For security reasons, private keys can only be managed locally and are never uploaded to any remote service. -To enable write operations (transfers, contract calls) and ensure reliable API access, you should configure the following variables. +**The core purpose of local deployment is to run a complete MCP Server on your machine, securely holding wallet credentials, so the AI assistant can sign and broadcast transactions on your behalf.** -### 1. Network Configuration +### What Can Local Deployment Do? -* `TRONGRID_API_KEY`: (Optional) Your TronGrid API key. - * **Reason**: TRON mainnet RPC has strict rate limits. Using an API key from [TronGrid](https://www.trongrid.io/) ensures reliable performance and higher throughput. - * **Usage**: - - ```shell - export TRONGRID_API_KEY="" - ``` -* Server Configuration +Compared to the read-only cloud service, local deployment unlocks full write operation capabilities: - * The server runs in HTTP mode on port **3001** by default. +- **Transfers**: Send TRX and TRC20 tokens +- **Smart Contracts**: Deploy new contracts, call state-changing functions, manage contract settings +- **Staking & Delegation**: Freeze TRX for energy/bandwidth, delegate resources to other addresses +- **Governance**: Vote for Super Representatives, create and approve proposals +- **Wallet Management**: Multi-wallet switching, message signing, account permission updates +- **Transaction Construction**: Create unsigned transactions, broadcast signed transactions -### 2. Wallet Configuration (Using Environment Variables) +Of course, all read-only query capabilities are also fully retained. -**Option 1: Private Key** +--- -```shell -# Recommended: Add this to your ~/.zshrc or ~/.bashrc -export TRON_PRIVATE_KEY="" +## Before You Start + +### Environment Requirements + +| Requirement | Description | +| :--- | :--- | +| **Node.js** | v20.0.0 or higher ([download](https://nodejs.org/)) | +| **TronGrid API Key** | Optional but recommended ([apply here](https://www.trongrid.io/)) | + +Verify your Node.js version: + +```bash +node --version # Should output v20.x.x or higher +``` + +### Security Principles + +Before configuring your wallet, make sure to understand the following security principles: + +:::danger Security Warning +**Never** save private keys or mnemonic phrases directly in MCP configuration files (such as `claude_desktop_config.json` or `mcp.json`). These files are often unencrypted and could be accidentally shared or committed to Git. Always use system environment variables or encrypted wallets. +::: + +--- +## Installation Steps +### Step 1: Configure Wallet + +The wallet determines which identity the AI assistant uses to perform on-chain operations. TRON MCP Server supports three wallet modes; if no wallet is configured, the server automatically runs in read-only mode. + +#### There are three wallet options — choose based on your needs + +| Feature | Agent Wallet | Private Key | Mnemonic | +| :--- | :--- | :--- | :--- | +| Security Level | High (encrypted storage) | Low (plaintext) | Low (plaintext) | +| Multi-Wallet Support | Yes | No | No | +| Runtime Wallet Switching | Yes | No | No | +| Setup Complexity | Medium | Simple | Simple | +| Recommended For | Production, significant funds | Development, small amounts | Development, small amounts | + +#### Option 1: Agent Wallet (Recommended) + +This is the most secure option. Private keys are encrypted and stored on local disk, never exposed as plaintext in environment variables. Even if environment variables are leaked, the attacker still needs the encrypted keystore file to access funds. + +**Install and initialize Agent Wallet:** + +```bash +# Install +npm install -g @bankofai/agent-wallet + +# Create encrypted wallet +agent-wallet start +``` +Agent Wallet also supports **multi-wallet management** — you can create multiple wallets and switch between them at runtime using the `select_wallet` tool, ideal for scenarios requiring operations across different accounts. + +> For detailed installation and usage instructions, see the [agent-wallet documentation](https://github.com/BofAI/agent-wallet/blob/main/doc/getting-started.md). + +**Set environment variables:** + +```bash +# Add to ~/.zshrc or ~/.bashrc +export AGENT_WALLET_PASSWORD="" + +# Optional: specify custom wallet directory (default: ~/.agent-wallet) +export AGENT_WALLET_DIR="~/.agent-wallet" +``` + + + +#### Option 2: Private Key + +Provide the private key directly via environment variable. Simplest setup, but lower security. + +```bash +# Add to ~/.zshrc or ~/.bashrc +export TRON_PRIVATE_KEY="" ``` -**Option 2: Mnemonic** +The private key can be in hex format with or without the `0x` prefix. + +:::warning +Using a plaintext private key in environment variables carries a **real risk of fund theft** — environment variables can be leaked via shell history, process listings (`ps aux`), or log files. **Only keep small amounts of funds** in wallets configured this way. +::: + +#### Option 3: Mnemonic Phrase -```shell -# Recommended: Add this to your ~/.zshrc or ~/.bashrc -export TRON_MNEMONIC=" ... " -export TRON_ACCOUNT_INDEX="0" # Optional, default: 0 +Use a BIP-39 mnemonic phrase for HD wallet derivation. + +```bash +# Add to ~/.zshrc or ~/.bashrc +export TRON_MNEMONIC="word1 word2 word3 ... word12" + +# Optional: specify HD wallet derivation index (default: 0) +# Derivation path: m/44'/195'/0'/0/{index} +export TRON_ACCOUNT_INDEX="0" ``` -## Installation -1. **Clone and enter the directory**: - ```shell - git clone https://github.com/BofAI/mcp-server-tron.git - cd mcp-server-tron - ``` -2. **Install and Build**: - ```shell - npm install && npm run build - ``` +:::warning +Same security risks as the private key option. Mnemonic phrases stored in plaintext are vulnerable to exposure. Use this only for development/testing wallets with small balances. +::: + +--- + +### Step 2: Configure Network (Optional) + +#### TronGrid API Key + +The TRON Mainnet public RPC has strict rate limits. For frequent on-chain queries, it is strongly recommended to configure a free TronGrid API Key: -## Verification -Default stdio mode: ```bash -# Run tests -npm test +# Add to ~/.zshrc or ~/.bashrc +export TRONGRID_API_KEY="" +``` + +Register for free at [trongrid.io](https://www.trongrid.io/). The server still works without this, but may encounter rate-limiting errors during high-frequency operations. Testnet networks (Nile, Shasta) are less affected by rate limits. + + +--- -# Start service (stdio) -npm start +### Step 3: Local Private Deployment + +Two options are available. For most users, Option A is sufficient. + +#### Option A: Run directly with npx (Recommended) + +No need to clone the repository — run the latest version directly via `npx`. This is also the default method used in the MCP client configuration examples below. + +```bash +npx -y @bankofai/mcp-server-tron ``` -When using HTTP (streamable-http) mode: +#### Option B: Clone from Source + +For developers who need to modify the source code or contribute: ```bash -npm run start:http +git clone https://github.com/BofAI/mcp-server-tron.git +cd mcp-server-tron +npm install +npm run build ``` -## Client Integration +--- -To use this server with MCP clients such as Claude Desktop, Cursor, or Google Antigravity, you need to add it to your configuration file. +### Step 4: Client Configuration -### 1. Find Your Configuration File +With environment variables set and installation done, now point your AI client to the local server. + +#### Find Your Configuration File | Application | Operating System | Configuration Path | -| :-- | :-- | :-- | +| :--- | :--- | :--- | | **Claude Desktop** | macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` | | | Windows | `%APPDATA%\Claude\claude_desktop_config.json` | | **Cursor** | All | Project root: `.cursor/mcp.json` | | **Google Antigravity** | All | `~/.config/antigravity/mcp.json` | | **Opencode** | All | `~/.config/opencode/mcp.json` | +#### Add Server Definition + + + + +Run the latest version directly from npm. No need to clone any repository. + +**Claude Desktop** (`claude_desktop_config.json`): + +```json +{ + "mcpServers": { + "mcp-server-tron": { + "command": "npx", + "args": ["-y", "@bankofai/mcp-server-tron"], + "env": { + "AGENT_WALLET_PASSWORD": "YOUR_PASSWORD (Or set in system env)", + "TRONGRID_API_KEY": "YOUR_KEY_HERE (Or set in system env)" + } + } + } +} +``` +**Claude Code**: -### 2. Add Server Definition +```bash +# Basic +claude mcp add mcp-server-tron -- npx -y @bankofai/mcp-server-tron -Choose one of the following methods to add it to your `mcpServers` object. +# With environment variables +claude mcp add -e AGENT_WALLET_PASSWORD=xxx -e TRONGRID_API_KEY=xxx mcp-server-tron -- npx -y @bankofai/mcp-server-tron +``` -**Option A: Quick Start (Recommended)** Run the latest version directly from npm. +**Cursor** (`.cursor/mcp.json`): ```json { @@ -100,7 +228,29 @@ Choose one of the following methods to add it to your `mcpServers` object. "command": "npx", "args": ["-y", "@bankofai/mcp-server-tron"], "env": { - "TRON_PRIVATE_KEY": "YOUR_KEY_HERE (Or set in system env)", + "AGENT_WALLET_PASSWORD": "YOUR_PASSWORD (Or set in system env)", + "TRONGRID_API_KEY": "YOUR_KEY_HERE (Or set in system env)" + } + } + } +} +``` + + + + +For developers running from a cloned repository. + +**Claude Desktop** (`claude_desktop_config.json`): + +```json +{ + "mcpServers": { + "mcp-server-tron": { + "command": "npx", + "args": ["tsx", "/absolute/path/to/mcp-server-tron/src/index.ts"], + "env": { + "AGENT_WALLET_PASSWORD": "YOUR_PASSWORD (Or set in system env)", "TRONGRID_API_KEY": "YOUR_KEY_HERE (Or set in system env)" } } @@ -108,16 +258,18 @@ Choose one of the following methods to add it to your `mcpServers` object. } ``` -**Option B: Local Development** For developers running from a cloned repository. +Replace the path with your actual cloned repository path. + +**Cursor** (`.cursor/mcp.json`): ```json { "mcpServers": { "mcp-server-tron": { "command": "npx", - "args": ["tsx", "/ABSOLUTE/PATH/TO/mcp-server-tron/src/index.ts"], + "args": ["tsx", "/absolute/path/to/mcp-server-tron/src/index.ts"], "env": { - "TRON_PRIVATE_KEY": "YOUR_KEY_HERE (Or set in system env)", + "AGENT_WALLET_PASSWORD": "YOUR_PASSWORD (Or set in system env)", "TRONGRID_API_KEY": "YOUR_KEY_HERE (Or set in system env)" } } @@ -125,5 +277,63 @@ Choose one of the following methods to add it to your `mcpServers` object. } ``` -**Important Note**: If you have already set these variables in your system environment, we recommend omitting the `env` section. If your MCP client does not inherit system variables, please use placeholders or ensure the configuration file is not shared or committed to version control. + + + +If you started the server in HTTP mode (`npm run start:http`), connect via HTTP URL: + +**Claude Code**: + +```bash +claude mcp add --transport http mcp-server-tron http://localhost:3001/mcp +``` + +**Cursor** (`.cursor/mcp.json`): + +```json +{ + "mcpServers": { + "mcp-server-tron": { + "url": "http://localhost:3001/mcp" + } + } +} +``` + + + + +:::tip About the `env` Section in Configuration +If you have already set environment variables in your system (via `~/.zshrc` or `~/.bashrc`), you can omit the `env` section from the configuration entirely — the server will automatically read system environment variables. + +If your MCP client does not inherit system environment variables, you'll need to set them in the `env` section. In that case, **make sure the configuration file is never shared or committed to version control**. +::: + +--- + +### Step 5: Verify Connection + +After completing configuration, **fully exit and restart** your AI client, then try: + +``` +What is the address of my configured wallet? +``` + +If everything is working, the AI will call the `get_wallet_address` tool and return your wallet's Base58 and Hex addresses. + +You can also try a testnet transfer (make sure you have test TRX on Nile): + +``` +Transfer 1 TRX to address TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL on the Nile testnet +``` + +:::info Getting Test TRX +You can get free test TRX for the Nile testnet from the TRON faucet. Visit [nile.tronscan.org](https://nile.tronscan.org) and look for the faucet option, or search for "TRON Nile faucet" online. +::: + +--- + +## Next Steps +- Want to see detailed parameters and usage for each tool? → [Full Capability Listt](./ToolList.md) +- Encountering issues? → [FAQ](./FAQ.md) diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md b/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md index d055bbe4..86127c3a 100644 --- a/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md +++ b/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md @@ -1,28 +1,110 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Official Server Access -For users who only need to read blockchain data (not involving transactions), you can connect directly to the officially hosted instance. **Note: The official service only provides a read-only interface and does not support operations such as transfers or contract writing.** +# Official Cloud Service Access -## Service Information -| Environment | URL | -| :--- | :--- | -| Production | [https://tron-mcp-server.bankofai.io/mcp](https://tron-mcp-server.bankofai.io/mcp) | +## What is the Official Cloud Service? + +The official cloud service is a TRON MCP Server instance hosted by **BANK OF AI**, providing AI clients with **read-only query capabilities for the TRON blockchain**. + +In the traditional approach, if you want an AI assistant to read on-chain data, you typically need to: + +- Install Node.js and related dependencies locally +- Clone the repository and complete the build +- Configure environment variables and network parameters +- Maintain server version updates yourself + +This is far too much overhead for users who simply want to check a balance. + +**The core purpose of the official cloud service is to handle all of this infrastructure for you.** You only need to add a single service URL to your AI client's configuration to start interacting with the TRON blockchain. + +### Key Advantages + +**1. No local installation required** + +No Node.js, no repository clone, no build commands. Just add a JSON snippet to your config file, restart your AI client, and you're ready to use. The entire process usually takes no more than 2 minutes. + +**2. No private key exposure risk** + +Since the cloud service is read-only, you never need to provide a wallet private key or mnemonic. This fundamentally eliminates risks like key leakage and config files accidentally committed to Git. It's especially convenient for team collaboration — any member can connect directly without key distribution or management concerns. + +**3. Official maintenance and continuous updates** + +The cloud service is maintained by the official team and always runs the latest stable version of TRON MCP Server. This includes: + +- Updates with new tools and features +- Adaptations for underlying TRON network upgrades +- Continuous performance and stability improvements + +You don't need to worry about version numbers or manually run `npm install` or rebuild. + +**4. Covers the vast majority of real-world use cases** + +The most common daily operations — checking address balances, analyzing transaction details, reading contract state, viewing the Super Representative list, monitoring on-chain events — are all read-only queries, fully supported through the cloud service. Only when you need to actually move assets (transfers, staking, contract writes) do you need to switch to [Local Private Deployment](./LocalPrivatizedDeployment.md). + +> In short: **The official cloud service acts as a "read-only API gateway" for the TRON blockchain** — AI clients only need the service URL to query all public on-chain data. + +:::warning Important +The official cloud service only provides **read-only access**. It does **not support** transfers, contract writes, staking, or any other write operations. For full functionality, please use [Local Private Deployment](./LocalPrivatizedDeployment.md). +::: + +--- -- **Transport Protocol**: Streamable HTTP -- **Mode**: Read-only (write tools disabled) +## How to Connect -* Optional: **TronGrid API Key**: It is recommended to apply ([trongrid.io](https://www.trongrid.io/)) to avoid mainnet frequency limits. +To connect to the official cloud service, simply add the official **MCP service URL** to your AI client configuration: [https://tron-mcp-server.bankofai.io/mcp](https://tron-mcp-server.bankofai.io/mcp) +> Note: This is an MCP protocol endpoint, not a webpage. Opening it directly in a browser will not display anything. -**Important Security Note**: For your safety, **NEVER** save your private keys or mnemonics directly in MCP configuration files (such as `claude_desktop_config.json` or `mcp.json`). Instead, please set them as environment variables in your operating system or shell configuration. +The official cloud service supports **two usage modes**: +| Mode | Rate Limit | Description | +| :--- | :--- | :--- | +| **Without API Key (default)** | 100,000 requests / day | Ready to use immediately, suitable for getting started and low-frequency queries | +| **With TronGrid API Key** | 500,000 requests / day | Higher request limit, suitable for frequent queries and production use | -## Client Integration +Both modes use the same connection method — the only difference is the request rate limit. + +--- + +### Without API Key Mode (Default) + +No API Key configuration needed to get started. Best for: + +- First-time experience with TRON MCP Server +- Occasional on-chain data queries +- Teaching, demos, and feature verification + +In this mode, all tools are available, but mainnet queries under high-frequency usage may trigger TronGrid's public RPC rate limits. + +--- + +### With TronGrid API Key Mode (Recommended) + +For frequent mainnet queries, apply for a free TronGrid API Key to get a higher request rate limit. + +**How to apply:** + +1. Visit [trongrid.io](https://www.trongrid.io/) +2. Register an account and create a project +3. Copy the generated API Key +4. Add the API Key header in your configuration (see client configuration examples below) + +After configuring the API Key, your requests will go through TronGrid's authenticated channel, with more stable performance and higher throughput. + +--- + +## Client Configuration +Configuration file path: +- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` +- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` + +**Basic Config (No API Key)**: + ```json { "mcpServers": { @@ -37,7 +119,7 @@ For users who only need to read blockchain data (not involving transactions), yo } ``` -With TronGrid API Key: +**Config with TronGrid API Key**: ```json { @@ -55,16 +137,18 @@ With TronGrid API Key: } ``` +Replace `` with your actual TronGrid API Key. + -CLI command: +**Command line:** -```shell +```bash claude mcp add --transport http mcp-server-tron https://tron-mcp-server.bankofai.io/mcp ``` -Or add `.mcp.json` to the project root: +**Or add `.mcp.json` to your project root**: ```json { @@ -78,12 +162,28 @@ Or add `.mcp.json` to the project root: ``` + - +Add the following to your project root `.cursor/mcp.json`: -Initialize connection: +```json +{ + "mcpServers": { + "mcp-server-tron": { + "url": "https://tron-mcp-server.bankofai.io/mcp" + } + } +} +``` -```shell + + + +If you want to integrate TRON MCP Server into your own application, you can call it via standard HTTP requests. + +**Step 1: Initialize Connection** + +```bash curl -X POST https://tron-mcp-server.bankofai.io/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ @@ -99,13 +199,17 @@ curl -X POST https://tron-mcp-server.bankofai.io/mcp \ }' ``` -Call a tool (use the `mcp-session-id` from the initialize response): +The response will include a `mcp-session-id` header — you'll need it for subsequent requests. + +**Step 2: Call a Tool** -```shell +Use the `mcp-session-id` from Step 1: + +```bash curl -X POST https://tron-mcp-server.bankofai.io/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ - -H "mcp-session-id: " \ + -H "mcp-session-id: " \ -d '{ "jsonrpc": "2.0", "method": "tools/call", @@ -117,6 +221,67 @@ curl -X POST https://tron-mcp-server.bankofai.io/mcp \ }' ``` - +**Step 3: Discover Available Tools** + +```bash +curl -X POST https://tron-mcp-server.bankofai.io/mcp \ + -H "Content-Type: application/json" \ + -H "Accept: application/json, text/event-stream" \ + -H "mcp-session-id: " \ + -d '{ + "jsonrpc": "2.0", + "method": "tools/list", + "params": {}, + "id": 3 + }' +``` +:::info Session Management +- Each `initialize` creates a new session +- Sessions automatically expire after 30 minutes of inactivity +- Use `DELETE /mcp` (with `mcp-session-id` header) to explicitly close a session +::: + + + +--- + +## Verify Connection + +After completing configuration, **fully exit and restart** your AI client, then enter the following test prompt: + +``` +Query the current block height of TRON mainnet +``` + +If you receive a normal response (e.g., showing the current block height), the connection is working. + +If you encounter issues, please check [FAQ](./FAQ.md) for troubleshooting. + +--- + +## Available Capabilities + +When connected via the official cloud service, you can use all **read-only** tools, including but not limited to: + +| Category | Example Capabilities | +| :--- | :--- | +| Balance Queries | Query TRX balance, TRC20 token balance, all token holdings | +| Transaction Queries | Look up transaction details, receipts, resource consumption | +| Block Data | Query by block number, by hash, latest block, batch queries | +| Account Info | Account details, resources, delegation info, bandwidth/energy | +| Smart Contract Reading | Call view/pure functions, get ABI, contract metadata | +| Event Queries | Query events by transaction, contract, block number | +| Network Status | Chain info, resource prices, supported networks | +| Governance | List Super Representatives, proposals, reward queries | +| Address Utilities | Format conversion, address validation | + +For the Full Capability List, please refer to [Full Capability List](./ToolList.md). + +--- + +## Next Steps + +- Need transfers, staking, or contract writes? → [Local Private Deployment](./LocalPrivatizedDeployment.md) +- Want the detailed description of all 95 tools? → [Full Capability List](./ToolList.md) diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md b/docs/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md new file mode 100644 index 00000000..1aeda6bb --- /dev/null +++ b/docs/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md @@ -0,0 +1,126 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Quick Start + +The goal of this page is simple: **get you connected in 1 minute and make your first blockchain query.** + +We'll use the [official cloud service](./OfficialServerAccess.md) for this quick start. The cloud service is read-only — no dependencies to install, no wallet to configure, no API Key required. Just copy a config snippet into your AI client, restart, and start asking questions. + +--- + +## Prerequisites + +Before you begin, make sure you have the following installed: + +- Any AI client that supports MCP: for example [Claude Desktop](https://claude.ai/download), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), or [Cursor](https://cursor.sh). +- **Node.js v20.0.0 or higher** (needed for `npx` command execution) ([Node.js Download](https://nodejs.org/)) + +Verify your Node.js version: + +```bash +node --version # should output v20.x.x or higher +``` + +--- + +## Add Configuration + +Choose your AI client and copy in the corresponding configuration: + + + + +Open your configuration file: +- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` +- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` + +Add the following content: + +```json +{ + "mcpServers": { + "mcp-server-tron": { + "command": "npx", + "args": [ + "mcp-remote", + "https://tron-mcp-server.bankofai.io/mcp" + ] + } + } +} +``` + + + + +Run the following command in your terminal: + +```bash +claude mcp add --transport http mcp-server-tron https://tron-mcp-server.bankofai.io/mcp +``` + + + + +Add the following to your project root `.cursor/mcp.json`: + +```json +{ + "mcpServers": { + "mcp-server-tron": { + "url": "https://tron-mcp-server.bankofai.io/mcp" + } + } +} +``` + + + + +--- + +## Restart and Test + +After saving the configuration, **completely quit and restart** your AI client. After restarting, the client will automatically connect to TRON MCP Server. + +Then enter your first query in the chat: + +``` +Check the TRX balance of TRON address TXyz... +``` + +If everything is working, the AI will automatically call the `get_balance` tool and return the TRX balance of that address. Seeing a result means you've successfully connected. + +:::info About the Cloud Service's Capabilities +The configuration above connects to the **official cloud read-only service**, which supports all query operations (checking balances, looking up transactions, reading contract state, etc.) but does not support write operations (transfers, contract calls, etc.). For full read/write capabilities, please refer to [Local Private Deployment](./LocalPrivatizedDeployment.md). +::: + +--- + +## Continue Exploring + +Once connected, try a few more prompts to get a feel for what TRON MCP Server can do: + +| Try saying | What it does | +| :--- | :--- | +| "Check the USDT balance of address TXyz..." | Query the TRC20 token balance of a specified address | +| "Look up the details of transaction hash abc123..." | Get transaction details, resource consumption, and status | +| "What is the current latest block number on TRON mainnet?" | Query the latest block height and chain info | +| "Query the current Energy and Bandwidth prices on TRON mainnet" | Get real-time resource prices | +| "Convert address 41abc... to Base58 format" | Address format conversion | +| "Show the resource usage of account TXyz..." | Get account energy, bandwidth, and staking details | +| "Get the ABI of contract TXyz..." | Read a smart contract interface definition | +| "Query the latest events triggered by contract TXyz..." | Get contract event logs | + +These are just the tip of the iceberg. For the full list of 95 tools and 6 prompt templates, see [Full Capability List](./ToolList.md). + +--- + +## Next Steps + +You've completed your first on-chain interaction. What you do next depends on what you want to do: + +- Need transfers, contract calls, or other write operations? → [Local Private Deployment](./LocalPrivatizedDeployment.md) +- Want to explore cloud service configuration options (such as TronGrid API Key)? → [Official Cloud Service Access](./OfficialServerAccess.md) +- Want to see the detailed description of all available tools? → [Full Capability List](./ToolList.md) diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/ToolList.md b/docs/McpServer-Skills/MCP/TRONMCPServer/ToolList.md new file mode 100644 index 00000000..52442e40 --- /dev/null +++ b/docs/McpServer-Skills/MCP/TRONMCPServer/ToolList.md @@ -0,0 +1,368 @@ +# Full Capability List + +TRON MCP Server provides **95 tools**, **6 prompts**, and **1 resource** for interacting with the TRON blockchain. Tools are the core capability — they are the actual functions the AI calls on your behalf. + +:::info Read vs Write +- **Read** tools: Available in both cloud (read-only) and local deployments. These are query-only operations with no on-chain impact. +- **Write** tools: Only available with local deployment + wallet configured. These modify blockchain state (transfers, staking, contract calls, etc.). + +If no wallet is configured, write tools are automatically hidden from the AI. +::: + +--- + +## Tools (95 total) + +### Wallet & Address + +| Tool Name | Description | Key Parameters | Mode | +| :--- | :--- | :--- | :--- | +| `get_wallet_address` | Get the address (Base58 & Hex) of the currently configured wallet. | - | Read | +| `list_wallets` | List all available wallets with IDs and addresses (Agent Wallet mode). | - | Read | +| `select_wallet` | Switch the active wallet at runtime (Agent Wallet mode). | `walletId` | Write | +| `sign_message` | Sign an arbitrary message using the configured wallet. | `message` | Write | +| `convert_address` | Convert addresses between Hex (`41...`/`0x...`) and Base58 (`T...`) formats. | `address` | Read | + +**Example prompts:** +- "What is the address of my configured wallet?" +- "Convert address 41a1e39aefa49eb34bb8f8abe226e1de2c6c2e79 to Base58" +- "List all my available wallets" + +--- + +### Network & Chain + +| Tool Name | Description | Key Parameters | Mode | +| :--- | :--- | :--- | :--- | +| `get_chain_info` | Get current block number and chain ID. | `network` | Read | +| `get_chain_parameters` | Get current energy and bandwidth unit prices. | `network` | Read | +| `get_supported_networks` | List all supported TRON networks. | - | Read | + +**Example prompts:** +- "What is the current TRON mainnet block height?" +- "How much does Energy and Bandwidth cost on TRON right now?" +- "Which networks does TRON MCP Server support?" + +--- + +### Blocks + +| Tool Name | Description | Key Parameters | Mode | +| :--- | :--- | :--- | :--- | +| `get_block` | Get block details by number or hash. | `blockIdentifier`, `network` | Read | +| `get_latest_block` | Get the latest block info. | `network` | Read | + +**Example prompts:** +- "Show me the details of TRON block 65000000" +- "What's in the latest TRON block?" + +--- + +### Transactions + +| Tool Name | Description | Key Parameters | Mode | +| :--- | :--- | :--- | :--- | +| `get_transaction` | Get full transaction details by hash. | `txHash`, `network` | Read | +| `get_transaction_info` | Get receipt including resource usage (energy/bandwidth consumed). | `txHash`, `network` | Read | + +**Example prompts:** +- "Look up transaction abc123... on TRON" +- "How much Energy did transaction xyz... consume?" + +--- + +### Balances + +| Tool Name | Description | Key Parameters | Mode | +| :--- | :--- | :--- | :--- | +| `get_balance` | Get TRX balance of an address. | `address`, `network` | Read | +| `get_token_balance` | Get TRC20 token balance of an address. | `address`, `tokenAddress`, `network` | Read | + +**Example prompts:** +- "Check the TRX balance of TXyz..." +- "How much USDT (TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t) does address TXyz... hold?" + +--- + +### Transfers + +| Tool Name | Description | Key Parameters | Mode | +| :--- | :--- | :--- | :--- | +| `transfer_trx` | Transfer TRX to an address. | `to`, `amount`, `network` | Write | +| `transfer_trc20` | Transfer TRC20 tokens to an address. | `tokenAddress`, `to`, `amount`, `network` | Write | + +**Example prompts:** +- "Transfer 50 TRX to address TXyz..." +- "Send 100 USDT to TXyz... on Nile testnet" + +:::warning +Transfer operations are irreversible. The AI will confirm details with you before executing. +::: + +--- + +### Smart Contracts + +| Tool Name | Description | Key Parameters | Mode | +| :--- | :--- | :--- | :--- | +| `read_contract` | Call read-only (`view`/`pure`) functions on a smart contract. | `contractAddress`, `functionName`, `args`, `abi`, `network` | Read | +| `write_contract` | Execute state-changing functions on a smart contract. | `contractAddress`, `functionName`, `args`, `abi`, `value`, `network` | Write | +| `deploy_contract` | Deploy a smart contract to the network. | `abi`, `bytecode`, `args`, `name`, `network`, `feeLimit` | Write | +| `estimate_energy` | Estimate energy consumption for a contract call. | `address`, `functionName`, `args`, `abi`, `network` | Read | +| `multicall` | Execute multiple read-only calls in a single batch. | `calls`, `network`, `multicallAddress`, `version` | Read | +| `get_contract` | Get raw contract metadata (ABI and bytecode). | `contractAddress`, `network` | Read | +| `get_contract_info` | Get high-level contract information (ABI, function list). | `contractAddress`, `network` | Read | +| `fetch_contract_abi` | Fetch ABI entry array for verified contracts from the chain. | `contractAddress`, `network` | Read | +| `update_contract_setting` | Update contract `consume_user_resource_percent` (creator only). | `contractAddress`, `consumeUserResourcePercent`, `network` | Write | +| `update_energy_limit` | Update contract `originEnergyLimit` (creator only). | `contractAddress`, `originEnergyLimit`, `network` | Write | +| `clear_abi` | Clear the on-chain ABI metadata of a contract (creator only). | `contractAddress`, `network` | Write | + +**Example prompts:** +- "Call the `balanceOf` function of contract TXyz... with my address" +- "Get the ABI of contract TXyz..." +- "Estimate how much Energy it would cost to call `transfer` on this contract" +- "Deploy this smart contract to Nile testnet" + +--- + +### Account Management + +| Tool Name | Description | Key Parameters | Mode | +| :--- | :--- | :--- | :--- | +| `get_account` | Get full account info (balance, resources, permissions). | `address`, `network` | Read | +| `get_account_balance` | Get TRX balance at a specific block height (historical query). | `address`, `blockHash`, `blockNumber`, `network` | Read | +| `get_account_net` | Get bandwidth resource information for an account. | `address`, `network` | Read | +| `get_account_resource` | Get energy, bandwidth, frozen balance, and delegation info. | `address`, `network` | Read | +| `get_delegated_resource` | Query delegated resources between two accounts. | `fromAddress`, `toAddress`, `network` | Read | +| `get_delegated_resource_index` | Query resource delegation index (who delegated to/from this account). | `address`, `network` | Read | +| `generate_account` | Generate a new TRON keypair offline (does not activate on-chain). | - | Read | +| `validate_address` | Validate a TRON address and detect its format. | `address` | Read | +| `create_account` | Activate a new account on the network (costs bandwidth). | `address`, `network` | Write | +| `update_account` | Update account name (can only be set once). | `accountName`, `network` | Write | +| `account_permission_update` | Update account permissions (multi-signature configuration). | `ownerPermission`, `activePermissions`, `witnessPermission`, `network` | Write | + +**Example prompts:** +- "Show the full account details for address TXyz..." +- "How much Energy and Bandwidth does address TXyz... have?" +- "Generate a new TRON address" +- "Is this a valid TRON address: TXyz...?" + +--- + +### Account Data (via TronGrid API) + +These tools use TronGrid's indexed API for richer account data queries. + +| Tool Name | Description | Key Parameters | Mode | +| :--- | :--- | :--- | :--- | +| `get_account_info` | Get comprehensive account info from TronGrid. | `address`, `network` | Read | +| `get_account_transactions` | Get transaction history for an account. | `address`, `limit`, `fingerprint`, `network` | Read | +| `get_account_trc20_transactions` | Get TRC20 transfer history. | `address`, `contractAddress`, `limit`, `fingerprint`, `network` | Read | +| `get_account_internal_transactions` | Get internal transactions for an account. | `address`, `limit`, `fingerprint`, `network` | Read | +| `get_account_trc20_balances` | Get all TRC20 token balances for an account. | `address`, `network` | Read | + +**Example prompts:** +- "Show the recent transaction history for address TXyz..." +- "What TRC20 tokens does address TXyz... hold?" +- "Show the USDT transfer history for this address" + +:::info Pagination +Tools that return lists support `limit` and `fingerprint` parameters for pagination. Use the `fingerprint` from the previous response to get the next page. +::: + +--- + +### Contract Data (via TronGrid API) + +| Tool Name | Description | Key Parameters | Mode | +| :--- | :--- | :--- | :--- | +| `get_contract_transactions` | Get transaction history for a contract. | `address`, `limit`, `fingerprint`, `network` | Read | +| `get_contract_internal_transactions` | Get internal transactions for a contract. | `address`, `limit`, `fingerprint`, `network` | Read | +| `get_trc20_token_holders` | Get token holder list for a TRC20 contract. | `address`, `limit`, `fingerprint`, `network` | Read | + +**Example prompts:** +- "Who are the top holders of this TRC20 token?" +- "Show the recent transactions on this contract" + +--- + +### Resource Delegation (Stake 2.0) + +| Tool Name | Description | Key Parameters | Mode | +| :--- | :--- | :--- | :--- | +| `delegate_resource` | Delegate staked Energy or Bandwidth to another address. | `receiverAddress`, `amount`, `resource`, `lock`, `lockPeriod`, `network` | Write | +| `undelegate_resource` | Revoke previously delegated resources. | `receiverAddress`, `amount`, `resource`, `network` | Write | +| `get_can_delegated_max_size` | Get max delegatable TRX amount for an address. | `address`, `resource`, `network` | Read | +| `get_delegated_resource_v2` | Get delegated resource details between two addresses. | `fromAddress`, `toAddress`, `network` | Read | +| `get_delegated_resource_account_index_v2` | Get delegated resource account index. | `address`, `network` | Read | + +**Example prompts:** +- "Delegate 500 TRX worth of Energy to address TXyz..." +- "How much can I delegate to others?" +- "Show all my resource delegations" + +--- + +### Staking (Stake 2.0) + +| Tool Name | Description | Key Parameters | Mode | +| :--- | :--- | :--- | :--- | +| `freeze_balance_v2` | Freeze (stake) TRX to obtain Energy or Bandwidth. | `amount`, `resource`, `network` | Write | +| `unfreeze_balance_v2` | Unfreeze (unstake) TRX to release resources. | `amount`, `resource`, `network` | Write | +| `withdraw_expire_unfreeze` | Withdraw expired unfrozen balance back to available TRX. | `network` | Write | +| `cancel_all_unfreeze_v2` | Cancel pending unfreezes and re-stake immediately. | `network` | Write | +| `get_available_unfreeze_count` | Get remaining unfreeze operations count (max 32 concurrent). | `address`, `network` | Read | +| `get_can_withdraw_unfreeze_amount` | Get withdrawable unstaked TRX amount at a given timestamp. | `address`, `timestampMs`, `network` | Read | + +**Example prompts:** +- "Stake 1000 TRX for Energy" +- "Unstake 500 TRX from Bandwidth" +- "Do I have any expired unfreezes I can withdraw?" + +:::info About Stake 2.0 +TRON uses Stake 2.0 for resource management. When you freeze TRX, you get Energy (for smart contract execution) or Bandwidth (for regular transactions). Unfreezing has a ~14-day waiting period before you can withdraw the TRX back. +::: + +--- + +### Governance & Super Representatives + +| Tool Name | Description | Key Parameters | Mode | +| :--- | :--- | :--- | :--- | +| `list_witnesses` | List all Super Representatives on the network. | `network` | Read | +| `get_paginated_witnesses` | Get paginated list of active SRs. | `offset`, `limit`, `network` | Read | +| `get_next_maintenance_time` | Get next maintenance window timestamp (vote tally time). | `network` | Read | +| `get_reward` | Query unclaimed voting reward for an address. | `address`, `network` | Read | +| `get_brokerage` | Query SR brokerage ratio (reward split with voters). | `witnessAddress`, `network` | Read | +| `create_witness` | Apply to become a Super Representative candidate (costs 9999 TRX). | `url`, `network` | Write | +| `update_witness` | Update Super Representative website URL. | `url`, `network` | Write | +| `vote_witness` | Vote for Super Representatives with frozen TRX. | `votes`, `network` | Write | +| `withdraw_balance` | Withdraw accumulated SR voting rewards. | `network` | Write | +| `update_brokerage` | Update SR brokerage ratio. | `brokerage`, `network` | Write | + +**Example prompts:** +- "List the top 27 Super Representatives on TRON" +- "How much unclaimed voting reward does my address have?" +- "Vote for SR candidate TXyz... with 1000 votes" + +--- + +### Proposals + +| Tool Name | Description | Key Parameters | Mode | +| :--- | :--- | :--- | :--- | +| `list_proposals` | List all governance proposals. | `network` | Read | +| `get_proposal` | Get proposal details by ID. | `proposalId`, `network` | Read | +| `create_proposal` | Create a governance proposal (SR only). | `parameters`, `network` | Write | +| `approve_proposal` | Vote to approve/disapprove a proposal. | `proposalId`, `approve`, `network` | Write | +| `delete_proposal` | Delete a governance proposal (creator only). | `proposalId`, `network` | Write | + +**Example prompts:** +- "Show all active TRON governance proposals" +- "What are the details of proposal #42?" + +--- + +### Events + +| Tool Name | Description | Key Parameters | Mode | +| :--- | :--- | :--- | :--- | +| `get_events_by_transaction_id` | Get events emitted by a specific transaction. | `transactionId`, `network` | Read | +| `get_events_by_contract_address` | Get events emitted by a specific contract. | `contractAddress`, `eventName`, `limit`, `network` | Read | +| `get_events_by_block_number` | Get events emitted in a specific block. | `blockNumber`, `network` | Read | +| `get_events_of_latest_block` | Get events from the latest block. | `network` | Read | + +**Example prompts:** +- "What events did transaction abc123... emit?" +- "Show the recent Transfer events from USDT contract" +- "What events happened in the latest block?" + +--- + +### Mempool + +| Tool Name | Description | Key Parameters | Mode | +| :--- | :--- | :--- | :--- | +| `get_pending_transactions` | Get pending transaction IDs in the mempool. | `network` | Read | +| `get_transaction_from_pending` | Get a specific pending transaction by ID. | `txId`, `network` | Read | +| `get_pending_size` | Get number of pending transactions in the pool. | `network` | Read | + +**Example prompts:** +- "How many transactions are pending in the TRON mempool?" +- "Is transaction abc123... still pending?" + +--- + +### Node + +| Tool Name | Description | Key Parameters | Mode | +| :--- | :--- | :--- | :--- | +| `list_nodes` | List all connected node addresses. | `network` | Read | +| `get_node_info` | Get detailed node information (version, resources, etc.). | `network` | Read | + +--- + +### Full-Node Query API + +These tools provide direct access to TRON full-node RPC methods for advanced queries. + +| Tool Name | Description | Key Parameters | Mode | +| :--- | :--- | :--- | :--- | +| `get_block_by_num` | Query block by block height. | `num`, `network` | Read | +| `get_block_by_id` | Query block by block hash. | `value`, `network` | Read | +| `get_block_by_latest_num` | Get the most recent N blocks (solidified). | `num`, `network` | Read | +| `get_block_by_limit_next` | Get blocks within a height range `[startNum, endNum)`. | `startNum`, `endNum`, `network` | Read | +| `get_now_block` | Get the current latest block. | `network` | Read | +| `get_transaction_by_id` | Query transaction by hash. | `value`, `network` | Read | +| `get_transaction_info_by_id` | Query transaction receipt by hash. | `value`, `network` | Read | +| `get_transaction_info_by_block_num` | Get receipts for all transactions in a block. | `num`, `network` | Read | +| `get_energy_prices` | Query historical energy unit prices over time. | `network` | Read | +| `get_bandwidth_prices` | Query historical bandwidth unit prices over time. | `network` | Read | +| `get_burn_trx` | Query total TRX burned from transaction fees. | `network` | Read | +| `get_approved_list` | Query accounts that signed a given transaction. | `transaction`, `network` | Read | +| `get_block_balance` | Get all balance change operations in a specific block. | `hash`, `number`, `network` | Read | + +--- + +### Broadcast & Transaction Building + +| Tool Name | Description | Key Parameters | Mode | +| :--- | :--- | :--- | :--- | +| `broadcast_transaction` | Broadcast a signed transaction (JSON format). | `transaction`, `network` | Write | +| `broadcast_hex` | Broadcast a signed transaction (hex-encoded protobuf). | `transaction`, `network` | Write | +| `create_transaction` | Create an unsigned TRX transfer transaction. | `ownerAddress`, `toAddress`, `amount`, `network` | Write | + +**Example prompts:** +- "Create an unsigned transaction to transfer 10 TRX from my address to TXyz..." +- "Broadcast this signed transaction: {...}" + +--- + +## Prompts (6 total) + +Prompts are pre-defined workflow templates that guide the AI through complex multi-step operations. They help ensure safety (e.g., confirming before transfers) and thoroughness (e.g., checking balance before sending). + +| Prompt Name | Description | Key Parameters | Requires Wallet | +| :--- | :--- | :--- | :--- | +| `prepare_transfer` | Safely prepare and execute a token transfer with balance checks, cost estimation, and user confirmation. | `tokenType`, `recipient`, `amount`, `network`, `tokenAddress` | Yes | +| `interact_with_contract` | Safely execute write operations on a smart contract with parameter validation, cost estimation, and confirmation. | `contractAddress`, `functionName`, `args`, `value`, `network` | Yes | +| `diagnose_transaction` | Analyze transaction status, identify failure causes, and provide debugging insights. | `txHash`, `network` | No | +| `explain_tron_concept` | Explain TRON and blockchain concepts (Energy, Bandwidth, Staking, etc.) with examples. | `concept` | No | +| `analyze_wallet` | Get comprehensive overview of wallet assets, balances, and activity. | `address`, `network`, `tokens` | No | +| `check_network_status` | Check current network health, block production, and resource costs. | `network` | No | + +**Example prompts:** +- "Help me transfer 100 TRX to TXyz... safely" (triggers `prepare_transfer`) +- "Analyze transaction abc123... — why did it fail?" (triggers `diagnose_transaction`) +- "Explain how Energy works on TRON" (triggers `explain_tron_concept`) +- "Give me a full analysis of wallet TXyz..." (triggers `analyze_wallet`) + +--- + +## Resources (1 total) + +Resources provide static reference data that the AI can query for context. + +| Resource Name | URI | Description | +| :--- | :--- | :--- | +| `supported_networks` | `tron://networks` | Returns the list of all supported TRON networks and their configuration (RPC URLs, explorer links, etc.). | diff --git a/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md b/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md index 83745aa4..daa1a0b6 100644 --- a/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md +++ b/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md @@ -1,262 +1,227 @@ # BANK OF AI Skills -BANK OF AI Skills is a set of reusable skill packages designed for AI agents. Each skill encapsulates knowledge in a specific domain (e.g., DEX trading, on-chain data querying, payment protocols, etc.), with `SKILL.md` as its core, providing agents with step-by-step operational guidance, executable scripts, and examples of common usage patterns, enabling agents to perform on-chain operations like professional users. +BANK OF AI Skills is a ready-to-use skill pack designed for AI agents, covering core DeFi scenarios in the TRON/BNB ecosystem — DEX trading, perpetual contracts, on-chain data queries, and payment protocols. Each skill encapsulates a complete business workflow: from how to call APIs and what order to execute steps, to handling approvals and protecting user assets, all embedded in `SKILL.md` and accompanying scripts. -BANK OF AI Skills supports integration with MCP-compatible AI Agents such as OpenClaw, Claude Code, Claude Desktop, and Cursor. You don't need to write code; simply describe the task in natural language, and the agent will automatically match and execute the corresponding skill. +You don't need to write code — just tell the AI in natural language what you want to do, and it will automatically find and execute the corresponding skill. -:::warning Security Pre-declaration — Please read before using any Skill -BankOfAI Skills can operate on **real on-chain assets**. Once a blockchain transaction is on-chain, it is **irreversible**. There is no "undo" button, no customer service rollback, and funds sent to the wrong address cannot be recovered. Before you begin, please keep these three iron rules in mind: +:::warning Before Using Any Skill, Please Read +BANK OF AI Skills can operate on **real on-chain assets**. Blockchain transactions are **irreversible** once on-chain — there's no "undo" button, no customer service rollback, and funds sent to the wrong address cannot be recovered. Remember three essential rules before using: -1. **Private keys should never appear in chat windows, prompts, or configuration files.** Only pass them through environment variables (e.g., `TRON_PRIVATE_KEY`, `PRIVATE_KEY`). Do not paste private keys into any AI conversation, do not hardcode them in scripts, and certainly do not commit them to version control systems. If a private key is accidentally leaked, replace it immediately. -2. **Testnet first, then Mainnet.** Every new operation—whether it's swapping, transferring, or adding liquidity—must first be verified on the Nile or Shasta testnets before being executed on the mainnet. Testnet tokens have no real value, so you can experiment with confidence without any economic loss. -3. **Write operations must be manually confirmed.** Before executing any on-chain transaction, the Agent should show you the complete operation details—including recipient address, token type, amount, estimated fees, and slippage—and wait for your explicit confirmation before broadcasting the transaction. Never enable automatic execution for write operations. +1. **Private keys must never appear in chat windows or config files.** Only pass them through environment variables (like `TRON_PRIVATE_KEY`). If a private key is compromised, move assets to a new wallet immediately. +2. **Test on testnet first, then mainnet.** Every new operation must be verified first on Nile or Shasta testnet before switching to mainnet execution. +3. **Write operations require manual confirmation.** Before executing any on-chain transaction, the AI should show you the complete operation details and wait for your explicit confirmation. ::: +--- -## Skill List - -Below are the currently available skills, covering scenarios such as DEX trading, on-chain data querying, payment protocols, and NFTs: - -| SKILL | Function | -| :--- | :--- | -| **x402-payment** | x402 payment skill, used to call paid agents and paid APIs on supported chains. | -| **sunswap** | SunSwap DEX skill, used for balance queries, quotes, swaps, and liquidity-related workflows. | -| **tronscan-skill** | TRON blockchain data query via TronScan API, supporting accounts, transactions, tokens, blocks, and network statistics. | - +## Available Skills Overview -## Quick Start +| Skill | Version | Functionality | Required Credentials | +| :--- | :--- | :--- | :--- | +| **sunswap** | v2.0.0 | SunSwap DEX trading — balance, quotes, swaps, V2/V3 liquidity | `TRON_PRIVATE_KEY` | +| **sunperp-skill** | v1.0.0 | SunPerp perpetual contracts — market data, orders, positions, withdrawals | `SUNPERP_ACCESS_KEY` + `SUNPERP_SECRET_KEY` | +| **tronscan-skill** | v1.0.0 | TronScan on-chain data queries — accounts, transactions, tokens, blocks | `TRONSCAN_API_KEY` | +| **x402-payment** | v1.4.0 | x402 protocol payments — calling paid APIs and paid agents | `TRON_PRIVATE_KEY` or `EVM_PRIVATE_KEY` | +| **ainft-skill** | v1.1.1 | AINFT balance queries, order history, TRC20 deposits | `AINFT_API_KEY` | -Taking `OpenClaw + OpenClaw Extension` as an example. +--- -### 1. Installation +## Installation -Install [OpenClaw Extension](https://github.com/BofAI/openclaw-extension), which automatically installs the integration layer, connects to the MCP server, and installs the skill repository. +The simplest installation method is using **OpenClaw Extension** — install all components with one command, automatically configure the skills directory, and the AI is ready out of the box: ```bash +# Method 1: Direct run (for trusted sources) curl -fsSL https://raw.githubusercontent.com/BofAI/openclaw-extension/refs/heads/main/install.sh | bash -``` - -If you want to inspect the installation script before running: -```bash +# Method 2: Check script before running (recommended) git clone https://github.com/BofAI/openclaw-extension.git cd openclaw-extension ./install.sh ``` -### 2. Verification - -After installation, verify that the skill repository is available. +After installation, skills will be placed in the `~/.openclaw/skills/` directory, and OpenClaw will automatically discover and load them. -Check the local skill directory: +Verify that skills are ready after installation: ```bash ls ~/.openclaw/skills ``` -You should see entries like `sunswap`, `x402-payment`, `x402-payment-demo`, `tronscan-skill`. - -Then verify in OpenClaw with a prompt: - -```text -Read the sunswap skill and tell me what this skill can do. -``` - -### 3. First Use - -Start with a simple read-only workflow. There are two ways to call a skill: +You should see directories like `sunswap`, `sunperp-skill`, `tronscan-skill`, `x402-payment`, `ainft-skill`, etc. -**Explicit Call** — Directly tell the agent which skill file to read. Suitable when you know the target skill or need deterministic behavior: +### Installation on Other Platforms -```text -Read the sunswap skill and help me check how much TRX 100 USDT can swap for on SunSwap. -``` +If you use Claude Code, Cursor, or other AI tools that support Skills, you can also install manually: -**Implicit Trigger** — Describe the task and let the agent automatically match and activate the corresponding skill. Suitable when the skill is installed and the request clearly corresponds to a workflow: +**Claude Code:** -```text -Help me check how much TRX 100 USDT can swap for on SunSwap right now. +```bash +git clone https://github.com/BofAI/skills.git /tmp/bofai-skills +mkdir -p ~/.config/claude-code/skills +cp -r /tmp/bofai-skills/* ~/.config/claude-code/skills/ ``` -:::tip Usage Tips -* **Provide clear context**: For example, "Use `xxx` skill to handle `yyy` task." -* **Specify parameters**: If the skill requires specific information (e.g., amount, currency, date), providing all of it at once in the instruction can significantly increase the success rate. -* **Start with read-only operations**: For first-time use, it is recommended to start with query-type operations (e.g., balance inquiry, price quote) to familiarize yourself with how the skill works before attempting write operations (e.g., swaps, transfers). -::: +Claude Code will automatically load these skills when it starts. +**Cursor:** -## Other Platform Installations +```bash +# Clone to project root +git clone https://github.com/BofAI/skills.git .cursor/skills +``` -### OpenClaw +In Cursor Chat, use the `@` symbol to reference specific `SKILL.md` files for context, or add the skills path to `.cursorrules`. -OpenClaw provides the most complete integration experience, automatically connecting skills and MCP dependencies. +**Universal Method (any AI tool):** ```bash -curl -fsSL https://raw.githubusercontent.com/BofAI/openclaw-extension/refs/heads/main/install.sh | bash +git clone https://github.com/BofAI/skills.git ~/bofai-skills ``` -### Claude Code - -1. Clone the repository: - ```bash - git clone https://github.com/BofAI/skills.git /tmp/bofai-skills - ``` -2. Copy the skills to the Claude Code configuration directory for automatic discovery: - ```bash - mkdir -p ~/.config/claude-code/skills - cp -r /tmp/bofai-skills/* ~/.config/claude-code/skills/ - ``` -3. Claude Code will automatically load these skills upon startup. +Then explicitly tell the AI to read a skill file in your conversation: -### Cursor - -1. Clone the repository to the project root directory: - ```bash - git clone https://github.com/BofAI/skills.git .cursor/skills - ``` -2. To make skills available project-wide, you can add the skill path to `.cursorrules`, or use the `@` symbol in Cursor Chat to reference specific `SKILL.md` files to provide context. +``` +Please read ~/bofai-skills/sunswap/SKILL.md and help me check the current price of TRX. +``` +--- +## Verify Installation +After installation, starting with read-only operations is the best entry point — no private keys needed, zero risk, perfect for getting familiar with how skills work. -## Skill Usage Examples +In your client, enter: -### Operation Type Description +``` +How much TRX can I get for 100 USDT on SunSwap? +``` -- 🟢 **Read** — Read-only query, no on-chain transactions will occur -- ⚠️ **Write** — Will initiate on-chain transactions (requires user confirmation) +``` +Help me check the current market data for BTC-USDT perpetual contract. +``` --- -### x402-payment - -**Call Paid Endpoint (⚠️ Write):** -> Use the x402 protocol to call this paid agent endpoint. +## Usage Examples for Each Skill ---- +Each example is marked with an operation type: +- 🟢 **Read-only** — produces no on-chain transactions, no private key needed +- ⚠️ **Write operation** — initiates on-chain transactions, requires user confirmation before execution ### sunswap -**Balance Query (🟢 Read):** -> Help me check my TRX and USDT balances on SunSwap. - -**Price Query (🟢 Read):** -> What is the current price of TRX? - -**Swap Quote (🟢 Read):** -> How much TRX can 100 USDT swap for on SunSwap? - -**Execute Swap (⚠️ Write):** -> Swap 100 TRX for USDT on SunSwap. +``` +# 🟢 Query balance +Help me check my TRX and USDT balances. -**Liquidity Operations (⚠️ Write):** -> Add 100 TRX and 15 USDT liquidity to the SunSwap V2 pool. +# 🟢 Query price +What's the current price of TRX? ---- +# 🟢 Get swap quote +How much TRX can I get for 100 USDT on SunSwap? -### tronscan-skill +# ⚠️ Execute swap +Swap 100 TRX for USDT on SunSwap Nile testnet. -**Account Query (🟢 Read):** -> Help me query the account information for address TXXXXXXXXXXXXXXXXXXXXXXX. +# ⚠️ Add liquidity +Add 100 TRX and 15 USDT liquidity to the TRX/USDT pool on SunSwap V2. -**Wallet Portfolio (🟢 Read):** -> Show the wallet portfolio and USD valuation for this address. +# 🟢 View V3 positions +Help me check all my current SunSwap V3 liquidity positions. -**Transaction Verification (🟢 Read):** -> Query the details and execution status of this transaction hash. +# ⚠️ Collect fees +Help me collect fee rewards from V3 position #12345. +``` -**Token Ranking (🟢 Read):** -> Show the top 10 TRC20 tokens by market capitalization. +### sunperp-skill -**Network Overview (🟢 Read):** -> Give me a TRON network overview — transaction throughput, super representatives, and supply metrics. +``` +# 🟢 View market data +What are the current price, 24h change, and funding rate for BTC-USDT perpetual contract? -## Security Guidelines +# 🟢 View account +What's my SunPerp account balance and available margin? -On-chain operations are irreversible. The following are not suggestions, but **rules that must be followed**. +# 🟢 View open positions +What open positions do I have? Show entry price, unrealized P&L and liquidation price. -### Private Key Management +# ⚠️ Open position +Open 1 BTC-USDT long position at market price on SunPerp with 10x leverage, set 5% stop loss. -``` -✗ Never do this: -"Help me execute a swap with private key a]K9x...z3" → Private key exposed in chat history/logs +# ⚠️ Close position +Close all my BTC-USDT positions. -✓ Correct practice: -export TRON_PRIVATE_KEY="Your private key" → Pass via environment variables +# ⚠️ Withdraw +Withdraw 10 USDT from SunPerp to my on-chain address. ``` -Principle: **Private keys must never appear anywhere in prompts, configuration files, or chat logs.** Agents should obtain them through environment variables or secure key management services. - -### Network Environment Isolation - -| Operation Phase | Recommended Network | Description | -|---------|---------|------| -| First Use/Learning | Nile Testnet | Zero-cost trial and error, play around freely | -| Feature Verification | Shasta Testnet | Closer to mainnet environment | -| Formal Operation | Mainnet | Switch only after confirming everything is correct | - -When switching networks, always **explicitly declare** to avoid the Agent executing transactions on the wrong network: +### tronscan-skill -```text -"Switch to TRON Mainnet, then help me check the balance." ``` +# 🟢 Account query +Help me query the complete account info and holdings for address TDqSquXBgUCLYvYC4XZgrprLK589dkhSCf. -### DeFi Operation Security - -- **Slippage Protection**: When executing a Swap, always set a slippage tolerance (recommended 0.5%–1%) to prevent losses due to price fluctuations. -- **Quote First, then Execute**: For any swap operation, first let the Agent query for a quote, and only execute after confirming the price is reasonable. -- **Large Amount Splitting**: For large transactions, it is recommended to split them into multiple smaller executions to reduce the risk of slippage for a single transaction. -- **Authorization Management**: Regularly check token authorizations (Approve) and revoke authorizations that are no longer in use. +# 🟢 Transaction query +Query the details of this transaction hash: abc123... -### Operation Confirmation Checklist +# 🟢 Token info +Show the top 10 TRC20 tokens by market cap. -For any **write operation**, the Agent should confirm the following information with the user before execution: +# 🟢 Network overview +Give me a TRON network overview: current TPS, number of Super Representatives, total accounts. -1. Operation type (Swap / Add Liquidity / Transfer, etc.) -2. Involved tokens and amounts -3. Current network (Testnet / Mainnet) -4. Estimated Gas fees -5. Slippage settings +# 🟢 Transfer history +Query the last 20 USDT transfers from address TXX... +``` -**Execute only after explicit user confirmation.** +### x402-payment +``` +# ⚠️ Call paid endpoint +Use x402 protocol to call this paid agent endpoint: https://api.example.com -## Best Practices +# 🟢 Check Gasfree status +Help me check the current Gasfree wallet status and available balance. +``` -### Tips for Giving Instructions +### ainft-skill -**Provide all parameters at once** to reduce agent guessing and follow-up questions: +``` +# 🟢 Query balance +How much balance does my AINFT account have? -```text -# Bad → Agent needs to ask repeatedly -"Help me swap some tokens." +# 🟢 Query orders +Show my recent AINFT order history. -# Good → All key information in one go -"Swap 100 USDT for TRX on SunSwap, set slippage to 0.5%, use Mainnet." +# ⚠️ Deposit +Deposit 1 USDT to my AINFT account. ``` -### Recommended Learning Path +--- -``` -1. Read-only queries → Familiarize with Skill interaction - ↓ -2. Testnet write operations → Verify full process, zero risk - ↓ -3. Mainnet small amount operations → Confirm everything is working - ↓ -4. Formal Mainnet use → Daily operations -``` +## Recommended Learning Path + +If you're just starting with BANK OF AI Skills, following this order makes it smoother: -### Common Troubleshooting +Step 1: Read-only queries + → Start with tronscan-skill to query accounts and check transactions, get familiar with skill interaction + → Use sunswap to check prices and quotes, no real trades -| Problem | Possible Cause | Solution | -|------|---------|---------| -| Agent says "Skill not found" | Skill file not in correct directory | Check installation path, refer to installation section | -| Agent behavior does not match expectations | Implicit trigger matched wrong skill | Use explicit call instead | -| On-chain transaction failed | Insufficient Gas / Too low slippage / Network error | Check balance, adjust slippage, confirm network | -| Quote differs significantly from actual execution | Insufficient liquidity or market volatility | Reduce transaction amount, or wait for market stabilization | +Step 2: Testnet write operations + → Execute swaps, add liquidity, open contracts on Nile testnet + → Confirm AI behavior matches expectations, parameters pass correctly +Step 3: Mainnet small transactions + → Verify the complete workflow with small amounts of capital +Step 4: Mainnet production use + → Daily operations, adjust parameters and skill combinations as needed +--- +## Next Steps +- Want to understand how Skills work? → [What Are Skills?](./Intro.md) +- Encountering issues? → [FAQ](./Faq.md) +- Using OpenClaw Extension? → [OpenClaw Extension Documentation](../../Openclaw-extension/Intro.md) diff --git a/docs/McpServer-Skills/SKILLS/Faq.md b/docs/McpServer-Skills/SKILLS/Faq.md index 4b6a50be..459d92b4 100644 --- a/docs/McpServer-Skills/SKILLS/Faq.md +++ b/docs/McpServer-Skills/SKILLS/Faq.md @@ -1,82 +1,204 @@ # FAQ -### Q: Do skills need to be installed separately? - -**A**: No. Skills are simply documents and script collections that the AI agent reads directly. You just need to place the skill directory in the correct location, and the AI can automatically discover and use it. If a skill contains a `scripts/` directory, you need to run `npm install` first to install its dependencies. +The following questions are arranged in the order you're most likely to encounter them. --- -### Q: What is the difference between a Skill and the MCP Server? +## Foundational Concepts + +### What's the difference between Skill and MCP Server? + +This is the most common question. In one sentence: **MCP Server is a toolbox, Skill is an instruction manual.** + +MCP Server provides atomic-level tools — like "check balance", "initiate transfer", or "call contract". Skills tell the AI how to combine these tools to complete a full task — for example, "swap tokens on a DEX" requires executing balance check, get quote, verify approval, and execute swap in sequence. Skills define this workflow. + +### Do Skills require separate installation? -**A**: +No additional application needed. A Skill is just a folder — you only need to place it in a directory that your AI tool can read, and the AI will automatically discover and use it. -| | Skill | MCP Server | -| :--- | :--- | :--- | -| **Definition** | Instruction document + script collection | Tool service | -| **Role** | Teaches AI **how to do** something | Provides AI **the ability to do** something | -| **Example** | sunswap skill teaches AI the swap workflow | tron-mcp-server provides on-chain interaction capabilities | +However, if a skill contains a `scripts/` directory (as sunswap, sunperp-skill, and tronscan-skill do), you need to run `npm install` once in that directory to install script dependencies. This step is automatic when using OpenClaw Extension. -In short: a Skill is the "operation manual," and an MCP Server is the "toolbox." Skills tell the AI how to use the tools provided by MCP Servers. +### Which AI tools support Skills? + +Currently supported: **OpenClaw** (most complete integration), **Claude Code**, **Cursor**, and any AI assistant that can read local files (using explicit invocation method). --- -### Q: How do I know what dependencies a skill requires? +## Installation and Configuration -**A**: Check two files in the skill directory: +### How do I know the skill installed successfully? -1. YAML frontmatter at the top of `SKILL.md`: -```yaml -dependencies: - - node >= 18 - - tron-mcp-server +```bash +ls ~/.openclaw/skills ``` -2. npm dependencies in `package.json`: +You should see directories like `sunswap`, `sunperp-skill`, `tronscan-skill`, `x402-payment`, `ainft-skill`, etc. + +Then verify in OpenClaw: + +``` +Read the sunswap skill and tell me what this skill can do. +``` + +If the AI accurately describes the skill content, installation was successful. + +### What if npm install fails? + +First confirm your Node.js version: + ```bash -cd skills/sunswap && npm install +node --version # needs >= 18 ``` ---- +If the version is too old, use nvm to upgrade: + +```bash +nvm install 18 +nvm use 18 +``` -### Q: What if the AI agent cannot find a skill? +Then run `npm install` again in the skill directory. -**A**: You can explicitly tell the AI the skill's path: +### How do I configure credentials (private keys/API keys)? -> Please read `skills/sunswap/SKILL.md` and check how much TRX I can get for 100 USDT. +Configure through environment variables. Depending on which skills you use, add the corresponding variables in `~/.zshrc` or `~/.bashrc`: -If installed via the OpenClaw extension, skills are automatically configured, and the AI can match them through implicit triggering. +```bash +# TRON wallet (needed for sunswap, sun-mcp-server, x402-payment) +export TRON_PRIVATE_KEY="your_private_key" +export TRONGRID_API_KEY="your_TronGrid_API_Key" ---- +# SunPerp contract trading (needed for sunperp-skill) +export SUNPERP_ACCESS_KEY="your_SunPerp_Access_Key" +export SUNPERP_SECRET_KEY="your_SunPerp_Secret_Key" -### Q: Can I modify a skill? +# TronScan data queries (needed for tronscan-skill) +export TRONSCAN_API_KEY="your_TronScan_API_Key" -**A**: Yes. Simply edit `SKILL.md` or the scripts in `scripts/`, and the AI agent will read the latest version on its next invocation. +# AINFT (needed for ainft-skill) +export AINFT_API_KEY="your_AINFT_API_Key" +``` + +After adding them, run `source ~/.zshrc` to apply, then restart your AI tool. --- -### Q: How do I switch between testnet and mainnet? +## Usage Issues -**A**: Specify via the `--network` parameter. It is recommended to always complete verification on a testnet (`nile` or `shasta`) first before switching to `mainnet`. +### The AI says "skill not found" or behaves unexpectedly. What should I do? + +First switch to **explicit invocation** — directly tell the AI where the skill file is: + +``` +Please read ~/.openclaw/skills/sunswap/SKILL.md and help me check the current price of TRX. +``` + +If explicit invocation works normally, the issue is with implicit triggering matching. Try adding clearer keywords in your task description, like "use sunswap skill", "use tronscan-skill". + +If explicit invocation also doesn't work, check if the skill directory exists, npm install is complete, and environment variables are set correctly. + +### How do I switch between testnet and mainnet? + +Use the `--network` parameter to specify. **Strongly recommend testing every new operation on testnet first**: ```bash -# Testnet +# Testnet (default, try this first) node scripts/swap.js TRX USDT 100 --network nile -# Mainnet +# Mainnet (only after confirming everything works) node scripts/swap.js TRX USDT 100 --network mainnet --execute ``` +You can also tell the AI directly in conversation: + +``` +Help me swap 100 TRX for USDT on the Nile testnet. +``` + +### Why does the AI require confirmation before executing? + +This is a safety mechanism by design — all write operations (operations involving on-chain transactions) must be explicitly confirmed by the user before execution. + +The AI will show in the confirmation prompt: operation type, tokens and amounts involved, target network, estimated Gas, and slippage. This gives you a chance to verify the operation matches expectations before your funds are actually used. **Don't skip this step, and never enable automatic execution of write operations.** + +### What does dry-run (simulation) mean? + +Scripts in sunswap and other Skills support running without the `--execute` flag — this is dry-run mode. It simulates the execution flow, checks balance and approval status, and gets quotes, but doesn't broadcast any on-chain transactions. + +```bash +# Dry-run: simulate check, no execution +node scripts/swap.js TRX USDT 100 + +# Real execution +node scripts/swap.js TRX USDT 100 --execute +``` + +Running dry-run first is a good habit when unsure. + +### Why is there a difference between the quoted price and the actual execution price? + +Because there's a time difference between getting the quote and actual execution, during which the price may change. The sunswap script uses a two-step quoting strategy to handle this: the first quote is shown to you for confirmation; after you confirm, it fetches the latest quote right before submitting the actual transaction, then uses the latest quote to calculate the `amountOutMin` as slippage protection. + +If extreme market volatility causes transaction failure, increasing the slippage tolerance (`--slippage 1.0`) usually fixes it. + --- -### Q: How do I configure private keys? +## Security and Advanced + +### Can I modify a skill? + +Yes. Edit `SKILL.md` or scripts in `scripts/` directly, and the AI will read the latest version on the next call. You can change operation steps, add custom rules, adjust safety parameters, or add new examples. -**A**: Configure via environment variables. Never hardcode them in your code: +Modifying `sunperp-skill/resources/sunperp_config.json` lets you adjust leverage limits and stop-loss defaults: + +```json +{ + "safety": { + "max_leverage": 20, + "stop_loss": { + "required": true, + "default_percent": 5, + "max_percent": 25 + } + } +} +``` + +### How is skill versioning managed? + +Skill versions are marked by the `version` field in the YAML frontmatter of `SKILL.md`. When using OpenClaw Extension, you can specify a specific version via the `GITHUB_BRANCH` environment variable: ```bash -export TRON_PRIVATE_KEY="your_private_key" -export TRONGRID_API_KEY="your_api_key" # Recommended for mainnet +GITHUB_BRANCH=v1.4.10 ./install.sh # Install specific version +GITHUB_BRANCH=main ./install.sh # Use latest main branch ``` -Private key loading priority: `TRON_PRIVATE_KEY` > `PRIVATE_KEY` > Config file > Wallet file +The default uses the `v1.4.12` tag version. + +### What if my private key is compromised? + +**Act immediately, don't hesitate:** + +1. Stop using the current AI tool +2. Create a new TRON/EVM wallet address +3. Transfer all assets to the new address (check for pending transactions in the current account first) +4. Update all environment variables to point to the new private key +5. Revoke token approvals on all protocols using the old wallet +6. Review the transaction history of the old wallet to confirm whether any unauthorized operations have occurred +Agent Wallet (encrypted storage) is safer than plaintext private keys — even if environment variables are compromised, attackers still need additional encryption keys to access funds. If you manage significant capital, consider switching to Agent Wallet mode. +### How do I uninstall or update a skill? + +**Uninstall:** + +```bash +rm -rf ~/.openclaw/skills/sunswap # Delete specific skill +``` + +**Update (reinstall the latest version):** + +```bash +cd openclaw-extension +./install.sh # If a skill with the same name exists, the installer will ask if you want to overwrite +``` diff --git a/docs/McpServer-Skills/SKILLS/Intro.md b/docs/McpServer-Skills/SKILLS/Intro.md index 0c2e41b9..c9e0c2dc 100644 --- a/docs/McpServer-Skills/SKILLS/Intro.md +++ b/docs/McpServer-Skills/SKILLS/Intro.md @@ -1,106 +1,143 @@ -# Introduction +# What Are Skills? -## What are Skills? -Simply put, they are "skill packs." +You may have already used MCP Server to let an AI assistant check balances, send transfers, and invoke contracts. But you'll notice that some tasks aren't "call a tool once and done" — for example, swapping tokens on a DEX requires checking your balance first, getting a quote, approving the transaction, then executing the swap. Each step involves decision-making and parameter handling. -**Agent Skills** is an open format that allows AI to learn new capabilities. You can think of it as a **plugin package** or a **skill folder**. +**Skills exist precisely for this kind of multi-step task.** -Each "skill pack" contains everything needed to complete a specific task: -* **Instructions**: Tells the AI when to use this skill and how to do it. -* **Toolbox**: Contains automated scripts or code to help the AI perform tasks. -* **References**: Professional documents or templates that provide a basis for the AI's work. +A Skill is a "task handbook" — it's not a tool itself, but rather instructions that tell the AI how to combine a series of tools in the correct order with the correct parameters to complete a full business workflow. -In this way, you can "load" new capabilities into your AI at any time, and these capabilities are **reusable, shareable, and controllable**. +--- + +## The Difference Between Skills and MCP Server +Many people ask this question when first encountering Skills: what's the difference from MCP Server? +| | MCP Server | Skill | +| :--- | :--- | :--- | +| **Essence** | Tool service | Task handbook + script collection | +| **Purpose** | Provide AI with **atomic capabilities to get things done** | Teach AI **how to combine capabilities to complete a task** | +| **Example** | `mcp-server-tron` provides the `send_trx` tool | `sunswap` tells AI how to use multiple tools to execute a DEX swap | +| **Analogy** | Kitchen knives, pots, and stoves | A recipe | -## What's inside a skill pack? +Simply put: **MCP Server is a toolbox, Skill is an instruction manual.** A Skill tells the AI which drawer to open, which tool to grab, and what steps to follow to complete the task. + +--- -Opening a skill folder, you will usually see the following: +## What Does a Skill Look Like? -| Folder/File | Role | Function | +A Skill is a folder with a very simple structure: + +| File/Directory | Purpose | Required? | | :--- | :--- | :--- | -| `SKILL.md` | **Core Brain** | **Required!** Contains the skill's name, description, and detailed operating guidelines. | -| `scripts/` | **Automation Tools** | Optional. Contains script code that the AI can directly run to process data. | -| `references/` | **Knowledge Base** | Optional. Contains professional documents, API specifications, and other reference materials. | -| `assets/` | **Asset Library** | Optional. Contains templates, images, or other resources. | +| `SKILL.md` | Core instruction document — where AI learns how to execute the task | **Yes** | +| `scripts/` | Executable scripts — AI calls these to perform specific operations | Optional | +| `resources/` | Reference data — contract addresses, token lists, config files, etc. | Optional | +| `package.json` | npm dependency declaration (required if the Skill has scripts) | Optional | + +The top of `SKILL.md` contains YAML Frontmatter that declares basic information about the Skill: + +```yaml +--- +name: SunSwap DEX Trading +description: Execute token swaps on SunSwap DEX for TRON blockchain using automated scripts. +version: 2.0.0 +dependencies: + - node >= 18.0.0 + - tronweb +tags: + - defi + - dex + - swap + - tron +--- +# SunSwap DEX Trading Skill -## Core Principle -The "memory" of large models (i.e., the context window) is extremely valuable and expensive. If all detailed descriptions of all skills are fed to the AI at once, it will not only consume a huge amount of tokens (making it expensive) but also lead to AI distraction, slow responses, and even frequent "hallucinations" (making it less intelligent). +## 🚀 Quick Start +...(specific operation instructions) +``` -To solve this problem, the Skills architecture introduces the **Progressive Disclosure design philosophy** and a **three-tier graded loading mechanism**. +The `name` and `description` fields are key for AI to identify and match skills — the more accurate they are, the more easily the AI can find them at the right moment. The main content is the specific operation instructions with no format restrictions — it can be text explanations, code examples, parameter tables, or anything that helps the AI understand. -### "Load on demand" like finding a book in a library -This is like looking up information in a library; you wouldn't move hundreds of books to your desk at once. Instead, you follow an efficient retrieval logic: +--- -* **Level 1: Metadata (Lightweight Card Catalog) – Scanning Shelf Labels** - * **Principle**: When the AI starts, the system only exposes the `name` and `description` of all mounted skills to it. - * **Advantage**: Since only "cards" are loaded, resource consumption is extremely low. This allows the AI to easily "remember" and manage hundreds or thousands of skills simultaneously, maintaining fast response times. +## Why Not Just Give All Instructions Directly to the AI? -* **Level 2: Instruction Document (Practical Guide) – Opening a Specific Directory** - * **Principle**: Only when your needs precisely match a certain skill will the AI read the corresponding `SKILL.md` file. - * **Advantage**: This exclusive guide provides the AI with the operational logic, boundary constraints, and Standard Operating Procedures (SOPs) for the current task at critical moments, ensuring that execution stays on track. +The key question for understanding Skills design: if we just tell the AI how to operate, why not just say it in the conversation? -* **Level 3: External Resources (Deep Toolchain) – Consulting Appendices and Practical Operations** - * **Principle**: When the task enters deep waters (e.g., executing complex Python scripts, pulling large API data), the AI will only call underlying tools at the moment they are needed. - * **Advantage**: These tools run silently in the background, ultimately returning only refined core results to the AI. They hardly occupy the AI's valuable thinking space, achieving a perfect balance of performance and depth. +This approach has two fundamental problems: +**Context window is limited and expensive.** If we stuff the complete content of all Skills into every conversation, the instructions alone would consume huge amounts of tokens, making the AI slower and dramatically increasing costs per conversation. -## Calling Logic +**Scattered attention.** When the AI faces detailed explanations for dozens of Skills, it struggles to focus on the current task and easily confuses rules and parameters across different skills, leading to errors. -The process of AI selecting and executing a Skill can be divided into four precise steps: +Skills solve this with **three-tier progressive loading** — only loading what's needed when it's needed. -
- RangeOrder1 -
+--- -### Step 1: Intent Recognition -The AI first parses your natural language request, quickly scans the "identity cards" (metadata) of all Skills in its resource library, and precisely locks onto the skill that best matches the current task. +## Three-Tier Progressive Loading -### Step 2: Rule Internalization -After selecting a Skill, the AI immediately retrieves the corresponding "operation manual" (`SKILL.md`) and carefully studies the specific execution steps, rule limitations, and contextual requirements. +Think of Skills as a library's retrieval system: -### Step 3: Tool Execution -Based on the manual's guidance, the AI begins to plan its path and execute. When it encounters a specific operational node, it accurately invokes the underlying bound tools or scripts to complete the substantive work. +**Tier 1: Shelf Index (ultra-lightweight)** -### Step 4: Feedback and Reflection -After the task is completed, the AI organizes the results into an easy-to-read format and reports them to you; if it encounters missing information or execution anomalies, it will promptly ask you for help. +When starting up, the system only exposes to the AI the `name` and `description` of all Skills — like labels on shelves. These "index cards" are tiny, so loading even hundreds of Skills at once creates no burden. Through this tier, the AI decides "which skill do I need for this task?" +**Tier 2: Operation Manual (loaded on demand)** -## `SKILL.md` File Format +Only when the AI confirms it needs a particular Skill does it read the complete `SKILL.md` content. This step triggers only when a skill is matched, providing the AI with specific execution steps, parameter requirements, edge conditions, and common error handling. -`SKILL.md` is written in a way that both AI and humans can understand. -At the top of the `SKILL.md` file, the following `Frontmatter` must be included: -* `name`: A short identifier (skill name) -* `description`: Explains when the skill should be used +**Tier 3: Tool Execution (real-time invocation)** -The body of the Markdown document contains the actual operating instructions and has no specific restrictions on structure or content. +Only when the task execution reaches a point requiring actual operations (like querying on-chain balance, executing a swap), the AI calls the corresponding script or MCP tool to do the substantive work, then returns the result to the conversation. + +This design lets the system manage large numbers of Skills while maintaining low latency and high accuracy. -```yaml --- -name: pdf-processing -description: Extract PDF text, fill forms, merge files. Use when handling PDFs. + +## How Does the AI Find and Use a Skill? + +The AI selects and executes a Skill in four steps: + +**Step 1: Intent Recognition** + +You send a request (e.g., "Help me swap 100 USDT for TRX on SunSwap"), the AI parses the intent, scans the descriptions of all mounted Skills, and finds the best match. + +**Step 2: Rule Internalization** + +The AI reads the Skill's `SKILL.md`, understanding the execution steps, parameter formats, network selection, and security constraints. + +**Step 3: Tool Execution** + +Following the manual's guidance, the AI proceeds step by step — calling scripts to check balance, get quotes, verify approvals, execute the swap — waiting for your confirmation at critical points. + +**Step 4: Result Feedback** + +After completion, the AI presents results in an easy-to-read format. When information is missing or execution fails, it asks proactively. + --- -# PDF Processing +## Two Ways to Invoke Skills -## When to use this skill -Use this skill when the user needs to work with PDF files... +You can trigger a Skill in two ways: -## How to extract text -1. Use pdfplumber for text extraction... +**Explicit Invocation** — directly tell the AI which Skill to read, suitable for scenarios requiring deterministic behavior: -## How to fill forms -... ``` +Read the sunswap skill and help me check how much TRX I can get for 100 USDT on SunSwap. +``` + +**Implicit Triggering** — describe the task and let the AI auto-match, suitable for everyday conversation: + +``` +Check how much TRX I can get for 100 USDT on SunSwap right now. +``` + +The difference lies in control: explicit invocation ensures the AI uses the Skill you specified; implicit triggering is more natural but if the description isn't clear enough, the AI might match the wrong Skill. When execution doesn't meet expectations, switching to explicit invocation usually solves the problem. + +--- + +## Next Steps -### Advantages: -1. **Easy to Understand**: Humans can read it, making it convenient for you to modify and optimize the AI's behavior at any time. -2. **Infinitely Expandable**: It can be simple text instructions or complex automated workflows. -3. **Easy to Transfer**: A skill is just a folder; you can send it to friends or use it universally across different AI tools. +- Want to know what Skills BANK OF AI provides? → [BANK OF AI Skills](./BANKOFAISkill.md) +- Have questions? → [FAQ](./Faq.md) diff --git a/docs/Openclaw-extension/FAQ.md b/docs/Openclaw-extension/FAQ.md new file mode 100644 index 00000000..f25e7148 --- /dev/null +++ b/docs/Openclaw-extension/FAQ.md @@ -0,0 +1,228 @@ +# FAQ & Troubleshooting + +When you encounter problems, check here first. Organized by the most likely issues you'll encounter: installation problems, connection issues, credential problems, runtime problems, and finally some general questions. + +--- + +## Installation Problems + +### Installer reports error "command not found: node" + +The installer requires Node.js v18.0.0 or higher. Check if it's installed: + +```bash +node --version +``` + +If not installed or version is too old, download and install the latest LTS version from [nodejs.org](https://nodejs.org/). After installing Node.js, the `npx` command will also be available. + +### Installer reports error "command not found: python3" + +The installer uses Python to process JSON configuration files. macOS typically comes with Python 3; on Linux, install via package manager: + +```bash +# Ubuntu/Debian +sudo apt install python3 + +# macOS (via Homebrew) +brew install python3 +``` + +### Installer warning "OpenClaw not found" + +The installer detected that `~/.openclaw` directory doesn't exist. This means OpenClaw might not be installed or was installed in a non-standard location. + +The installer will ask if you want to continue — you can choose to proceed (MCP Servers and Skills will still be configured), but OpenClaw may not auto-load them on startup. Recommend first completing installation from the [OpenClaw official repository](https://github.com/openclaw). + +### Skills clone failed + +If `git clone` fails, common causes include: + +- **Network issues**: Check if you can access GitHub. Try `git clone https://github.com/BofAI/skills.git` to test manually. +- **Git not installed**: Run `git --version` to confirm. +- **Specified branch/tag doesn't exist**: If you set the `GITHUB_BRANCH` environment variable, confirm the branch or tag actually exists. + +Skills clone failure won't interrupt the entire installation — MCP Server configuration remains intact. You can install Skills manually later. + +### npm install failed + +When installing Skills, some Skills (like sunswap, x402-payment) need to run `npm install` to install dependencies. If it fails: + +- Check network connectivity (npm needs to access registry.npmjs.org) +- Confirm Node.js version >= 18 +- Try running manually: + ```bash + cd ~/.openclaw/skills/sunswap # or other Skill directory + npm install + ``` + +npm install failure won't interrupt the installer — it will issue a warning but continue. That Skill's functionality may be limited until dependencies are successfully installed. + +--- + +## Connection Issues + +### Can't see blockchain tools in OpenClaw after startup + +**Most common cause**: OpenClaw wasn't restarted. After modifying mcporter.json, you must completely exit and restart OpenClaw. + +If you still can't see them after restarting: + +1. **Check mcporter.json format**: + ```bash + python3 -m json.tool ~/.mcporter/mcporter.json + ``` + If there's a JSON syntax error, fix the format issues and restart. + +2. **Check mcporter.json contents**: Confirm there are Server entries under `mcpServers` for what you installed. + +3. **Manually test MCP Server**: + ```bash + npx -y @bankofai/mcp-server-tron + ``` + If this command starts normally (shows logging output), the MCP Server itself is fine; the issue is in OpenClaw's configuration reading. + +### Only query tools available, no write tools like transfers + +This is by design. Write tools only appear after wallet credentials are configured. Check if any of these are set: + +- Environment variable `TRON_PRIVATE_KEY` (mcp-server-tron) +- Environment variable `PRIVATE_KEY` (bnbchain-mcp) +- `env.TRON_PRIVATE_KEY` or `env.PRIVATE_KEY` for corresponding Server in mcporter.json + +After configuring credentials, restart OpenClaw. For detailed instructions, see [Configuration Reference](./Configuration.md). + +### MCP Server startup timeout + +If OpenClaw times out starting an MCP Server, it may be that npx is downloading packages too slowly. The first run downloads packages from npm, which can take tens of seconds. + +Speed this up by pre-downloading: + +```bash +npx -y @bankofai/mcp-server-tron --help +npx -y @bnb-chain/mcp@latest --help +``` + +After downloading completes, subsequent startups will use cache and be much faster. + +--- + +## Credential Issues + +### "Invalid private key" error + +**TRON private key** should be a 64-character hexadecimal string, with or without `0x` prefix. + +**EVM private key** should have `0x` prefix. The installer automatically adds `0x` to private keys without it, but if you manually edit config files, ensure the format is correct. + +Common mistakes: +- Extra spaces, newlines, or quote nesting +- Invisible characters when copying from elsewhere + +Validation: Import the private key into the appropriate wallet (TronLink or MetaMask) to confirm validity. + +### TronGrid API Key not working + +1. **Is variable name correct?**: Must be `TRONGRID_API_KEY` (not `TRON_API_KEY`) +2. **Is Key still valid?**: Log in to [trongrid.io](https://www.trongrid.io/) to check status +3. **Is it properly loaded?**: If set in environment variables, confirm you ran `source ~/.zshrc` + +### Gasfree credentials not working + +Check format and contents of `~/.x402-config.json`: + +```bash +cat ~/.x402-config.json +``` + +Confirm it contains valid `gasfree_api_key` and `gasfree_api_secret`. If you need to reconfigure, you can edit the file directly or re-run the installer. + +### AINFT API Key invalid + +Check contents of `~/.mcporter/ainft-config.json`: + +```bash +cat ~/.mcporter/ainft-config.json +``` + +Confirm the `api_key` field contains a valid Key. Note that ainft-skill has a credential priority order (CLI arguments > environment variables > config files); if you set different values in multiple places, you might read the unexpected one. + +--- + +## Runtime Problems + +### Rate limiting (429 errors) + +Mainnet's public RPC has strict rate limits. Solutions: + +- **Configure TronGrid API Key**: After free registration, set `TRONGRID_API_KEY`, significantly increasing quota +- **Use testnet**: Nile and Shasta testnets have fewer restrictions +- **Reduce concurrent queries**: In prompts, avoid having the AI execute large numbers of queries simultaneously + +### Skill execution failed + +If a Skill errors, troubleshoot in this order: + +1. **Check if dependencies are installed**: + ```bash + cd ~/.openclaw/skills/ + npm install # if there's package.json + ``` + +2. **Check Node.js version**: Some Skills require >= 18.0.0. + +### Transaction failed + +Common reasons for on-chain transaction failures: + +- **Insufficient balance**: TRX balance doesn't cover gas fees (bandwidth/energy) +- **Insufficient energy**: Smart contract calls (including TRC20 transfers) consume energy +- **Account not activated**: New TRON addresses need to receive one TRX first to activate +- **Insufficient approval**: TRC20 token transfers may require prior approval + +Use mcp-server-tron's `get_transaction_info` tool to see the specific reason for transaction failure. + +--- + +## General Questions + +### Can I install only some components? + +Yes. The installer lets you selectively install at each stage. For example, you can install only mcp-server-tron without other MCP Servers, or only sunswap Skill while skipping others. + +### Can I run the installer multiple times? + +Yes. The installer uses deep merge strategy for mcporter.json and won't overwrite existing configurations. For Skills, if a Skill with the same name already exists at the target location, it will ask if you want to overwrite. + +### How do I completely uninstall? + +OpenClaw Extension has no automatic uninstaller. Manual uninstall steps: + +1. **Remove MCP Server configuration**: Edit `~/.mcporter/mcporter.json`, remove corresponding Server entries +2. **Delete Skills**: Delete Skill folders in installation directory (default `~/.openclaw/skills/`) +3. **Delete credential files**: + ```bash + rm -f ~/.x402-config.json + rm -f ~/.mcporter/ainft-config.json + rm -f ~/.clawdbot/wallets/.deployer_pk + ``` +4. **Clean environment variables**: Remove related export statements from `~/.zshrc` or `~/.bashrc` + +### Which operating systems are supported? + +The installer is a Bash script supporting: +- **macOS** (Intel and Apple Silicon) +- **Linux** (Ubuntu, Debian, CentOS, etc.) +- **Windows**: Requires WSL (Windows Subsystem for Linux) to run + +### What's the difference from TRON MCP Server's official cloud service? + +The [official cloud service](../McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md) is a remote-hosted read-only MCP Server, requiring no local installation. OpenClaw Extension runs the MCP Server locally, and with private keys configured, unlocks full read-write capabilities. + +If you only need to query on-chain data, cloud service is simpler. If you need transfers, contract writes, or want to use Skills (like SunSwap trading), you need OpenClaw Extension. + +--- + +## Next Steps + +- Start fresh → [Quick Start](./QuickStart.md) diff --git a/docs/Openclaw-extension/Intro.md b/docs/Openclaw-extension/Intro.md new file mode 100644 index 00000000..e2bc6f2f --- /dev/null +++ b/docs/Openclaw-extension/Intro.md @@ -0,0 +1,61 @@ +# Introduction + +## What is OpenClaw Extension? + +OpenClaw Extension is a toolkit developed by **BANK OF AI** that equips [OpenClaw](https://github.com/openclaw) (an open-source AI assistant) with **blockchain interaction capabilities**. Once installed, your AI assistant can directly manage on-chain assets — check balances, initiate transfers, invoke smart contracts, and swap tokens on DEXs — all through natural language conversation. + +Traditionally, enabling an AI to interact with blockchain requires you to manually set up MCP Servers, manage configuration files, and install various tools individually. OpenClaw Extension packages all of this into an interactive installer — run one command, follow the prompts to select the components you need, and within minutes your AI assistant will have multi-chain operation capabilities. + +--- + +## Core Vision + +OpenClaw Extension aims to build a financial infrastructure for the AI agent economy — enabling every AI agent with independent financial capabilities: + +- **Earn Revenue**: Receive payments for tasks and services through standard interfaces like the x402 protocol +- **Autonomous Spending**: Independently pay for compute, data, and storage resources +- **Agent Interconnection**: Facilitate direct financial transactions and settlements between agents (A2A) +- **DeFi Interaction**: Seamlessly interact with decentralized finance protocols and smart contracts + +--- + +## What Does It Include? + +OpenClaw Extension consists of two main categories of components: **MCP Servers** and **Skills**. You can choose which components to enable at installation time. + +### MCP Server — On-Chain Operation Capabilities + +MCP Servers are bridges between your AI assistant and the blockchain, providing on-chain operation capabilities through the [Model Context Protocol (MCP)](../McpServer-Skills/MCP/Intro.md) standard interface. Currently supports MCP Servers for three blockchain chains and one remote service: + +| MCP Server | Target Chain | Core Capabilities | +| :--- | :--- | :--- | +| **[mcp-server-tron](https://github.com/BofAI/mcp-server-tron)** | TRON | 95 tools covering wallets, transfers, contracts, staking, governance, and all operations | +| **[bnbchain-mcp](https://github.com/bnb-chain/bnbchain-mcp)** | BSC / opBNB / Ethereum | Multi-chain EVM operations, wallets, contracts, cross-chain | + +### Skills — Pre-built Workflows + +Skills are encapsulated business process templates. Unlike individual tools provided by MCP Servers, a single Skill can chain multiple operations together to complete complex tasks — for example, "swap tokens on SunSwap" involves checking prices, verifying balances, executing the swap, and confirming results, all handled by one Skill. + +| Skill | Functionality | +| :--- | :--- | +| **sunswap** | SunSwap DEX trading including balance queries, quotes, swaps, and liquidity management | +| **sunperp-skill** | SunPerp perpetual futures trading — market data, orders, positions, leverage, withdrawals | +| **tronscan-skill** | Query on-chain data via TronScan API (accounts, transactions, tokens, blocks, network statistics) | +| **x402-payment** | x402 payment skill for calling paid agents and APIs, supporting Gasfree zero-gas transactions | +| **ainft-skill** | AINFT balance and order queries, plus TRC20 top-ups | + + +--- + +## Who Should Use This? + +- **OpenClaw Users**: Want your AI assistant to interact directly with blockchain without manually setting up MCP Servers +- **Web3 Developers**: Need a quick on-chain development environment to debug contracts and query data using natural language +- **AI Agent Builders**: Need to equip automation agents with multi-chain operation capabilities +- **DeFi Users**: Want to use your AI assistant to trade on SunSwap or manage liquidity + +--- + +## Next Steps + +- Want to get started immediately? → [Quick Start](./QuickStart.md) diff --git a/docs/Openclaw-extension/Overview.md b/docs/Openclaw-extension/Overview.md deleted file mode 100644 index d257182a..00000000 --- a/docs/Openclaw-extension/Overview.md +++ /dev/null @@ -1,66 +0,0 @@ -# Introduction - -The OpenClaw extension is a suite of tools developed by **BANK OF AI** designed to empower AI agents with financial sovereignty. It enables agents to hold wallets, execute transactions, and monetize services via the **x402 Protocol** (HTTP 402 Payment Required). - -## Vision - -To build a "central bank" for the agent economy, ensuring every AI agent can: - -- **Earn Revenue**: Accept payments for tasks and services through standard protocols. -- **Autonomous Consumption**: Independently pay for resources (compute, data, storage). -- **Connect and Interact**: Facilitate direct financial activities and settlements between agents (A2A). -- **Seamless Transactions**: Interact seamlessly with DeFi and smart contracts. - -## Core Components - -This extension provides tools for blockchain interaction: - -### MCP Server - -Multi-chain blockchain access for AI agents via Model Context Protocol (MCP): - -- **[mcp-server-tron](https://github.com/BofAI/mcp-server-tron)** - TRON blockchain interaction - - Wallet management, message signing, address conversion & validation - - Balance checks, TRX/TRC20 transfers, smart contract calls - - Contract deployment, multicall, ABI fetching, contract settings management - - Block & transaction queries (by height, hash, range) - - Resource estimation (Energy/Bandwidth), staking (Stake 2.0), resource delegation - - Governance & proposals, event queries, mempool, node info - - Account management, TronGrid data queries, transaction broadcast - - Full-node query API (energy/bandwidth price history, TRX burn stats, block balance changes) - - Multi-network support (Mainnet, Nile, Shasta) - - Read-only mode for safe public deployment - -- **[sun-mcp-server](https://github.com/BofAI/sun-mcp-server)** - SUN.IO (SUNSWAP) DeFi interaction - - SUN.IO API queries: tokens, pools, prices, protocol metrics, transactions, farming - - Wallet management, balance queries (TRX & TRC20), multi-wallet switching - - Token pricing & swap quoting via smart router - - Smart swaps via Universal Router with automatic best-route finding - - V2 liquidity: add/remove with automatic native TRX handling - - V3 concentrated liquidity: mint, increase, decrease positions & collect fees - - V4 concentrated liquidity: mint, increase, decrease positions with Permit2 support - - Smart contract interaction: read/write with automatic TRC20 approval handling - - Multi-network support (Mainnet, Nile, Shasta) - - Supports private keys, BIP-39 mnemonics, and Agent Wallet - -- **[bnbchain-mcp](https://github.com/bnb-chain/bnbchain-mcp)** - BNB Chain official MCP server - - Multi-chain support: BSC, opBNB, Ethereum, Greenfield - - Wallet operations, smart contracts, token transfers - - Cross-chain capabilities - -### Skills - -Pre-built workflows and tools from the **[skills repository](https://github.com/BofAI/skills)**: - -**Available Skills:** - - -| Skill | Function | -| :--- | :--- | -| **x402-payment** | x402 payment skill for invoking paid agents and paid APIs on supported chains. | -| **sunswap** | SunSwap DEX skill for balance queries, quotes, swaps, and liquidity workflows. | -| **tronscan-skill** | TRON blockchain data query via TronScan API, supporting accounts, transactions, tokens, blocks, and network statistics. | - -For complete documentation and usage instructions, see the [skills repository](https://github.com/BofAI/skills). - -The installer will let you select which skills to install during setup. \ No newline at end of file diff --git a/docs/Openclaw-extension/QuickStart.md b/docs/Openclaw-extension/QuickStart.md new file mode 100644 index 00000000..06119e32 --- /dev/null +++ b/docs/Openclaw-extension/QuickStart.md @@ -0,0 +1,143 @@ +# Quick Start + +The goal of this page is: **Get you up and running with a complete installation and your first blockchain query in just a few minutes.** + +The installer is interactive, guiding you to select which MCP Servers and Skills to install, then automatically completing all configuration. You just need to follow the prompts. + +--- + +## Prerequisites + +Before running the installer, ensure the following tools are ready: + +| Requirement | Description | Verification Command | Download | +| :--- | :--- | :--- | :--- | +| **OpenClaw** | Your open-source AI assistant | Check if `~/.openclaw` directory exists | [OpenClaw official repository](https://github.com/openclaw) | +| **Node.js v18+** | Required to run MCP Servers | `node --version` | [Node.js official site](https://nodejs.org/) | +| **Python 3** | Used by installer to handle JSON configuration | `python3 --version` | [Python official site](https://www.python.org/downloads/) | +| **Git** | Clone Skills repository | `git --version` | [Git official site](https://git-scm.com/) | + +--- + +## Running the Installer + +### Method 1: One-Click Install (Recommended) + +```bash +curl -fsSL https://raw.githubusercontent.com/BofAI/openclaw-extension/refs/heads/main/install.sh | bash +``` + +### Method 2: Install from Source + +```bash +git clone https://github.com/BofAI/openclaw-extension.git +cd openclaw-extension +./install.sh +``` + +Once started, the installer automatically checks environment dependencies (Node.js, npx, Git, Python). If any are missing, it will alert you immediately. + +--- + +## Installation Process Details + +The installer consists of two main phases, each with interactive selection at every step. + +### Phase 1: Select and Configure MCP Servers + +The installer displays all available MCP Servers and asks which ones you want to install: + +``` +📦 Available MCP Servers: + 1) mcp-server-tron - TRON blockchain interaction + 2) bnbchain-mcp - BNB Chain (BSC, opBNB, Ethereum) interaction + 3) ainft-merchant - Remote AINFT recharge MCP + +Select servers to install (e.g., 1,2,3 or 'all'): +``` + +For each selected server, the installer continues by asking how you want to store credentials: + +- **Option 1: Save to Configuration File** — Keys stored in plaintext in `~/.mcporter/mcporter.json`. Convenient but lower security. +- **Option 2: Use Environment Variables (Recommended)** — Keys read from system environment variables, not written to any files. + +If you choose to save to a configuration file, the installer will ask for specific key values (private keys, API Keys, etc.). If you choose environment variables, the installer will tell you which variables need to be set. + +> **Tip**: If you just want to quickly experience the features, you can skip key configuration for now (just press Enter to leave it empty). Without a private key, the MCP Server will run in read-only mode, and you can still query on-chain data. + +### Phase 2: Select and Install Skills + +The installer clones the [Skills repository](https://github.com/BofAI/skills) from GitHub, automatically discovers all available Skills, and asks you to select: + +``` +🔧 Available Skills: + 1) sunswap - SunSwap DEX trading skill + 2) tronscan-skill - TRON blockchain data lookup + 3) x402-payment - Agent payment protocol (x402) + 4) ainft-skill - AINFT balance/order queries + +Select skills to install (e.g., 1,2,3 or 'all'): +``` + +Then choose the installation location: + +| Option | Path | Use Case | +| :--- | :--- | :--- | +| **User-level (Recommended)** | `~/.openclaw/skills/` | Shared across all projects | +| **Workspace-level** | `.openclaw/skills/` | Used only by current project | +| **Custom Path** | Directory you specify | Special requirements | + +Some Skills have additional credential requirements, which the installer will prompt you for during installation: + +- **x402-payment** — Optional configuration of Gasfree API credentials (for zero-gas transactions) +- **ainft-skill** — Requires AINFT API Key +- **tronscan-skill** — Prompts you to set `TRONSCAN_API_KEY` environment variable in your shell +- **sunswap** — Prompts to configure TRON private key (if not configured earlier) + +--- + +## Verifying the Installation + +After installation completes, **restart OpenClaw**, then in your conversation, enter: + +``` +Check the current block height on TRON mainnet +``` + +If you receive a normal response showing the current block height, it means mcp-server-tron has been successfully connected. + +You can also try: + +``` +Check the TRX balance of TRON address TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX +``` + +``` +What are the current energy and bandwidth prices on TRON mainnet? +``` + +If all these queries return results normally, you're all set. + +:::info About Read-Only Mode +If you didn't configure a private key during installation, the MCP Server will run in read-only mode — all query operations (check balance, check transactions, check contract state, etc.) work normally, but transfer and contract write operations are unavailable. To unlock write capabilities, see [Configuration Reference](./Configuration.md). +::: + +--- + +## Having Problems? + +If your AI assistant can't recognize blockchain tools after installation, common causes include: + +- **OpenClaw not restarted** — Configuration changes require a full restart +- **Node.js version too old** — Ensure v18.0.0 or higher +- **mcporter.json format error** — You can check with `python3 -m json.tool ~/.mcporter/mcporter.json` + +For more troubleshooting, see [FAQ & Troubleshooting](./FAQ.md). + +--- + +## Next Steps + +- Want to understand the detailed features of each MCP Server and Skill? → [Component Details](./Components.md) +- Want to configure private keys, API Keys, or security options? → [Configuration Reference](./Configuration.md) +- Having issues? → [FAQ & Troubleshooting](./FAQ.md) diff --git a/docs/Openclaw-extension/Setup-use.md b/docs/Openclaw-extension/Setup-use.md deleted file mode 100644 index 80a98398..00000000 --- a/docs/Openclaw-extension/Setup-use.md +++ /dev/null @@ -1,74 +0,0 @@ -# Installation and Usage -OpenClaw Extension provides a CLI installer to help you quickly set up your environment. - -## 🛠 Installation - -### Prerequisites -- **OpenClaw** (Your personal, open-source AI assistant) - [Install from here](https://github.com/openclaw) -- **Node.js** (v18+) -- **Python 3** (for configuration helpers) -- **Git** (for cloning skills repository) -- **TRON Wallet** (Private Key & API Key for TRON network interaction) - -**Note**: This installer uses OpenClaw's configuration system. Make sure OpenClaw is installed before running this installer. - -### Quick Start - -**One-command installation:** - -```bash -curl -fsSL https://raw.githubusercontent.com/BofAI/openclaw-extension/refs/heads/main/install.sh | bash -``` - -Or from source: - -```bash -git clone https://github.com/BofAI/openclaw-extension.git -cd openclaw-extension -./install.sh -``` - -### What Gets Installed - -- ✅ **MCP servers** - TRON and BSC blockchain access configured in `~/.mcporter/mcporter.json` -- ✅ **Skills** - Pre-built workflows installed to your chosen location -- ✅ **Available components**: See [mcp-server-tron](https://github.com/BofAI/mcp-server-tron), [bnbchain-mcp](https://github.com/bnb-chain/bnbchain-mcp), and [skills repository](https://github.com/BofAI/skills) - -**Note**: This installer uses `mcporter` (OpenClaw's official MCP manager) for configuration. Ensure OpenClaw is installed first. - -## 🔐 Security - -### Credential Storage Options - -The installer offers two methods for storing blockchain credentials: - -**Option 1: Config File Storage** -- Keys stored in `~/.mcporter/mcporter.json` -- Convenient but less secure (plaintext) -- **Important**: Secure the file with `chmod 600 ~/.mcporter/mcporter.json` -- Never share or commit this file to version control - -**Option 2: Environment Variables (Recommended)** -- Keys read from shell environment -- More secure, not stored in config files -- Add to your shell profile (`~/.zshrc`, `~/.bashrc`, etc.): - ```bash - # For TRON - export TRON_PRIVATE_KEY="your_private_key_here" - export TRONGRID_API_KEY="your_api_key_here" - - # For BSC/EVM chains - export PRIVATE_KEY="0x_your_private_key_here" - ``` -- Restart your shell or run `source ~/.zshrc` after adding - -### Best Practices - -- Use dedicated agent wallets with limited funds -- Never use your main personal wallet -- Test on testnets (Nile for TRON, BSC Testnet for BSC) before using mainnet -- Do not allow AI agents to scan files containing private keys - -## Use at your own risk - -Allowing AI agents to handle private keys directly involves substantial security risks. We advise using only small amounts of cryptocurrency and exercising caution. Despite the built-in safeguards, there is no guarantee that your assets are immune to loss. This extension is currently in an experimental stage and has not been subjected to rigorous testing. It is provided without any warranty or assumption of liability. Always validate your setup on testnets (Nile for TRON, BSC Testnet for BSC) before interacting with mainnets. diff --git a/docs/x402/getting-started/quickstart-for-human.md b/docs/x402/getting-started/quickstart-for-human.md index 2fb9efda..c3f1a544 100644 --- a/docs/x402/getting-started/quickstart-for-human.md +++ b/docs/x402/getting-started/quickstart-for-human.md @@ -93,7 +93,7 @@ This guide is for developers who want to **call an x402-protected API from code* Run the following in your terminal: ```bash -pip install "bankofai-x402[tron] @ git+https://github.com/BofAI/x402.git@v0.3.1#subdirectory=python/x402" +pip install "bankofai-x402[tron] @ git+https://github.com/BofAI/x402.git#subdirectory=python/x402" ``` Also install EVM (BSC) dependencies: diff --git a/docs/x402/getting-started/quickstart-for-sellers.md b/docs/x402/getting-started/quickstart-for-sellers.md index 317eb017..91e44deb 100644 --- a/docs/x402/getting-started/quickstart-for-sellers.md +++ b/docs/x402/getting-started/quickstart-for-sellers.md @@ -3,17 +3,17 @@ import TabItem from '@theme/TabItem'; # Quickstart for Sellers -> **Testnet First:** This guide uses testnet by default — all operations use free test tokens and **no real funds are involved**. Once your integration is verified, see [Running on Mainnet](#running-on-mainnet) at the end of this guide to go live. +> **Testnet First:** This guide uses the testnet by default. All operations use free test tokens — **no real funds are involved**. Once testing is complete, refer to the [Switch to Mainnet](#running-on-mainnet) section at the end of this guide. ## What You'll Build -After completing this guide, you'll have an **API service that charges per call**: +After completing this guide, you'll have a **service that charges for API calls**: -- When a user or AI agent calls your API, the system automatically requires them to pay in the token you specify (USDT by default; USDD and custom TRC-20/BEP-20 tokens are also supported) +- When a user or AI agent calls your API, the system automatically requires payment of a specified token - Supports per-request billing, metered usage, dynamic pricing, and more - Payment verification and blockchain settlement are fully automated — funds go directly to your wallet -The full setup takes **4 steps**, estimated time: **15–20 minutes**. +The entire flow takes **4 steps**, estimated time: **15–20 minutes**. --- @@ -21,122 +21,130 @@ The full setup takes **4 steps**, estimated time: **15–20 minutes**. ### Verify Your Environment -Run the following commands in your terminal (macOS/Linux Terminal, or Windows PowerShell) to confirm the required tools are installed: +In your terminal (Terminal on macOS/Linux, or PowerShell/Command Prompt on Windows), run the following commands to confirm the required tools are installed: ```bash python --version # Requires 3.10 or higher -pip --version # Installed with Python +pip --version # Installed alongside Python git --version # Version control tool ``` -If any command returns "not found", install the missing tools: -- Python: [python.org](https://www.python.org/downloads/) -- Git: [git-scm.com](https://git-scm.com/) +If any command says "command not found", install it first: +- Python: go to [python.org](https://www.python.org/downloads/) to download the installer +- Git: go to [git-scm.com](https://git-scm.com/) to download --- -### Create a Receiving Wallet +### Create a Payment Wallet -You need a blockchain wallet address to receive tokens (USDT or USDD) from your API users. Follow the steps below for your chosen network: - -> 💡 **About USDD:** USDD is TRON's native stablecoin, fully supported by x402 alongside USDT. It is a great primary option on TRON mainnet. BSC currently supports USDT only. +You need a blockchain wallet address to receive tokens from users. Follow the steps below based on your chosen network: -**Create a TronLink wallet (~3 min):** +**Create a TronLink Wallet (approx. 3 minutes):** -1. Install the [TronLink browser extension](https://www.tronlink.org/) (Chrome/Firefox) or the mobile app +1. Install the [TronLink extension](https://www.tronlink.org/) in your browser (Chrome/Firefox supported), or download the TronLink app on your phone 2. Open the extension and click "Create Wallet" -3. Set a local password to unlock the wallet -4. **Important:** Write down your seed phrase (12 English words) on paper and store it safely — it's the only way to recover your wallet -5. Confirm the seed phrase when prompted; your wallet is now created -6. Copy your wallet address from the home screen (starts with **`T`**, e.g. `TXyz1234...`) +3. Set a login password (used to unlock the wallet, stored locally only) +4. **Important:** The system will display a seed phrase (12 English words) — **write it down on paper** and keep it safe; this is the only way to recover your wallet +5. Verify the seed phrase as prompted to complete wallet creation +6. Copy your wallet address from the home screen (starts with the letter **`T`**, e.g. `TXyz1234...`) -**Claim free test tokens (~2 min):** +**Claim Free Test Tokens (approx. 2 minutes):** 1. Go to the [Nile Testnet Faucet](https://nileex.io/join/getJoinPage) -2. Paste your TRON wallet address and claim free test TRX and USDT/USDD -3. In TronLink, switch to the "Nile Testnet" and refresh to confirm your TRX and USDT/USDD balance +2. Paste your TRON wallet address into the input field +3. Click to claim and wait about 1–2 minutes +4. Switch to "Nile Testnet" in TronLink, refresh, and confirm your TRX and USDT/USDD balance has arrived -> ✅ **Success check:** Wallet shows test TRX and test USDT (or USDD) balance greater than 0 +> ✅ **Success:** Wallet shows test TRX and test USDT (or USDD) balance greater than 0 -**Create a MetaMask wallet (~3 min):** +**Create a MetaMask Wallet (approx. 3 minutes):** -1. Install the [MetaMask browser extension](https://metamask.io/) (Chrome/Firefox/Edge) -2. Click "Create a new wallet", set a password, and **write down your seed phrase on paper** -3. Confirm the seed phrase; your wallet is now created -4. Copy your wallet address from the home screen (starts with **`0x`**, e.g. `0xAbc123...`) +1. Install the [MetaMask extension](https://metamask.io/) in your browser (Chrome/Firefox/Edge supported) +2. Open the extension and click "Create a new wallet" +3. Set a password, then **write down your seed phrase (12 English words) on paper and keep it safe** +4. Verify the seed phrase as prompted to complete creation +5. Copy your wallet address from the home screen (starts with **`0x`**, e.g. `0xAbc123...`) -**Claim free test tokens (~2 min):** +**Claim Free Test Tokens (approx. 2 minutes):** 1. Go to the [BSC Testnet Faucet](https://www.bnbchain.org/en/testnet-faucet) -2. Paste your wallet address and claim test BNB and USDT -3. In MetaMask, switch to the BSC Testnet and confirm the balance arrived +2. Paste your wallet address and claim test BNB and test USDT +3. Switch to BSC Testnet in MetaMask and confirm the balance has arrived -> ✅ **Success check:** Wallet shows test BNB and test USDT balance greater than 0 +> ✅ **Success:** Wallet shows test BNB and test USDT balance greater than 0 -> ⚠️ **Wallet security:** Your seed phrase and private key are the master key to your wallet. **Never share them with anyone — including support staff.** Write the seed phrase on paper; do not store it in cloud storage or screenshots. +> ⚠️ **Wallet Security Reminder:** +> - Your seed phrase and private key are the "master key" to your wallet — **no one (including platform support) should ever ask you for them** +> - Write your seed phrase on paper and store it in a safe physical location — do not save it in your phone gallery or cloud storage +> - This tutorial uses a test wallet; it is recommended to create a dedicated new wallet for testing rather than using a wallet with real assets --- ### Configuration Reference -| Item | Description | How to Obtain | -|------|-------------|---------------| -| **TRON Receiving Address** | Wallet address starting with `T` | Copy from TronLink | -| **BSC Receiving Address** | Wallet address starting with `0x` | Copy from MetaMask | -| **Test TRX** | Gas token for TRON testnet | [Nile Faucet](https://nileex.io/join/getJoinPage) | -| **Test USDT/USDD (TRON)** | TRON test payment tokens (both supported) | [Nile Faucet](https://nileex.io/join/getJoinPage) | -| **Test BNB** | Gas token for BSC testnet | [BSC Testnet Faucet](https://www.bnbchain.org/en/testnet-faucet) | +| Configuration | Description | How to Obtain | +|--------|------|----------| +| **TRON Wallet Address** | Wallet address starting with `T` | Copy from TronLink | +| **BSC Wallet Address** | Wallet address starting with `0x` | Copy from MetaMask | +| **Test TRX** | TRON testnet fee token | [Nile Faucet](https://nileex.io/join/getJoinPage) | +| **Test USDT/USDD (TRON)** | TRON test payment token (both USDT and USDD supported) | [Nile Faucet](https://nileex.io/join/getJoinPage) | +| **Test BNB** | BSC testnet fee token | [BSC Testnet Faucet](https://www.bnbchain.org/en/testnet-faucet) | | **Test USDT (BSC)** | BSC test payment token | [BSC Testnet Faucet](https://www.bnbchain.org/en/testnet-faucet) | **Testnet vs. Mainnet:** -- **Testnet**: Free test tokens, no real funds. Network identifiers: `tron:nile` / `eip155:97` -- **Mainnet**: Real USDT/USDD payments. Network identifiers: `tron:mainnet` / `eip155:56` +- **Testnet**: Uses free test tokens, no real funds involved, suitable for development and debugging. Network identifiers: `tron:nile` / `eip155:97` +- **Mainnet**: Involves real payments, used when going live. Network identifiers: `tron:mainnet` / `eip155:56` --- -## Step One: Install x402 SDK +## Step 1: Install the x402 SDK -Open your terminal and run the install command: +Open your terminal and run the following install command: -**Recommended (install directly from GitHub):** +**Recommended (install directly from GitHub, ideal for getting started quickly):** ```bash -pip install "bankofai-x402[tron,fastapi] @ git+https://github.com/BofAI/x402.git@v0.3.1#subdirectory=python/x402" +pip install "bankofai-x402[tron,fastapi] @ git+https://github.com/BofAI/x402.git#subdirectory=python/x402" ``` -Verify the installation: +After installation, run the following command to verify it succeeded: ```bash python -c "import bankofai.x402; print('SDK installed successfully!')" ``` -> ✅ **Success check:** Terminal prints `SDK installed successfully!` +> ✅ **Success:** Terminal outputs `SDK installed successfully!` -**Alternative (install from source, for development):** +**Alternative (install from source, for developers who need to modify the source code):** ```bash +# Clone the repository git clone https://github.com/BofAI/x402.git cd x402/python/x402 + +# Install (with FastAPI support) pip install -e ".[fastapi]" ``` -> 💡 **Permission error?** Prefix the command with `sudo` (macOS/Linux) or run PowerShell as Administrator (Windows). +> 💡 **Permission error?** Prefix the command with `sudo` (macOS/Linux), or run PowerShell as Administrator (Windows). --- -## Step Two: Create Your Payment-Protected Server +## Step 2: Create a Payment-Protected API Server -Create a new file named `server.py` in your project directory and paste the code for your chosen network: +Now let's create an API server with payment protection. The x402 SDK provides an `@x402_protected` decorator — simply add it to any endpoint you want to charge for, and the SDK will automatically handle all payment verification logic. + +In your project directory, create a new file named `server.py` and paste in the following code: @@ -150,25 +158,25 @@ from bankofai.x402.config import NetworkConfig app = FastAPI() -# ========== Edit these two values ========== -# Replace with your actual TRON wallet address (for receiving payments) +# ========== Modify the following two settings ========== +# Replace the address below with your TRON wallet address from Prerequisites (used to receive payments) PAY_TO_ADDRESS = "YourTronWalletAddressHere" -# Facilitator URL (will be configured in Step 3 — leave as-is for now) +# Facilitator service URL (will be started in Step 3, default address does not need to change) FACILITATOR_URL = "http://localhost:8001" -# =========================================== +# ======================================================== -# Initialize the x402 server +# Initialize x402 server server = X402Server() server.set_facilitator(FacilitatorClient(FACILITATOR_URL)) -# This endpoint requires payment to access +# Add payment protection to this API endpoint @app.get("/protected") @x402_protected( server=server, prices=["0.0001 USDT"], # Charge per request (adjust as needed) schemes=["exact_permit"], # Payment scheme - network=NetworkConfig.TRON_NILE, # Testnet (change to TRON_MAINNET for production) + network=NetworkConfig.TRON_NILE, # Using testnet now (change to TRON_MAINNET when going live) pay_to=PAY_TO_ADDRESS, # Your receiving wallet address ) async def protected_endpoint(): @@ -194,26 +202,26 @@ from bankofai.x402.mechanisms.evm.exact import ExactEvmServerMechanism app = FastAPI() -# ========== Edit these two values ========== -# Replace with your actual BSC wallet address (for receiving payments) +# ========== Modify the following two settings ========== +# Replace the address below with your BSC wallet address from Prerequisites (used to receive payments) PAY_TO_ADDRESS = "0xYourBscWalletAddressHere" -# Facilitator URL (will be configured in Step 3 — leave as-is for now) +# Facilitator service URL (will be started in Step 3, default address does not need to change) FACILITATOR_URL = "http://localhost:8001" -# =========================================== +# ======================================================== -# Initialize the x402 server and register BSC mechanisms +# Initialize x402 server and register BSC payment mechanisms server = X402Server() server.register(NetworkConfig.BSC_TESTNET, ExactPermitEvmServerMechanism()) server.register(NetworkConfig.BSC_TESTNET, ExactEvmServerMechanism()) server.set_facilitator(FacilitatorClient(FACILITATOR_URL)) -# This endpoint requires payment to access +# Add payment protection to this API endpoint @app.get("/protected") @x402_protected( server=server, prices=["0.0001 USDT"], # Charge per request - network=NetworkConfig.BSC_TESTNET, # Testnet (change to BSC_MAINNET for production) + network=NetworkConfig.BSC_TESTNET, # Using testnet now (change to BSC_MAINNET when going live) pay_to=PAY_TO_ADDRESS, # Your receiving wallet address schemes=["exact_permit"], ) @@ -229,85 +237,85 @@ if __name__ == "__main__": -**Key configuration parameters:** +**Key Configuration Parameters:** -| Parameter | Description | Example | -|-----------|-------------|---------| +| Parameter | Description | Example Value | +|------|------|--------| | `PAY_TO_ADDRESS` | Your receiving wallet address | `TXyz...` (TRON) or `0xAbc...` (BSC) | -| `prices` | Charge per request | `["0.0001 USDT"]` | +| `prices` | Price per request | `["0.0001 USDT"]` | | `network` | Network to use | Testnet: `TRON_NILE` / `BSC_TESTNET` | | `schemes` | Payment scheme | `["exact_permit"]` | -**How it works:** When an unpaid request arrives, your server automatically returns HTTP 402 (Payment Required) with payment instructions in the response header. The client SDK handles payment and retries the request automatically — users barely notice. +**How it works:** When an unpaid request reaches your API, the server automatically returns an HTTP 402 (Payment Required) response with payment instructions in the response headers. The client SDK automatically completes the payment and re-sends the request — the process is nearly invisible to the end user. --- -## Step Three: Connect to a Facilitator +## Step 3: Connect to a Facilitator ### What is a Facilitator? -Think of the Facilitator as an **automated notary**: when someone pays your API, the Facilitator verifies the payment is genuine and records the settlement on-chain. +Simply put, a Facilitator is an **automated settlement service**: when someone pays your API, the Facilitator verifies that the payment is genuine and settles it on the blockchain, ensuring funds are recorded on-chain. -**You must complete the Facilitator setup before starting your API server.** +**You must complete the Facilitator configuration before starting your API server.** -### Which option should I choose? +### Two Options — Which Should You Choose? | | Official Facilitator (Recommended) | Self-Hosted Facilitator | |---|---|---| -| **Infrastructure to maintain** | None — fully hosted | You run it yourself | -| **Wallet private key required** | No | Yes (to pay gas fees) | -| **Setup difficulty** | Low (get an API Key) | Medium (deploy and configure) | -| **Best for** | Most users, fast launch | Custom fee rate strategies | +| **Maintenance required** | No — officially hosted | Yes — you run it yourself | +| **Wallet private key required** | No | Yes (to pay transaction fees) | +| **Difficulty** | Low (just apply for an API Key) | Medium (requires deployment and configuration) | +| **Best for** | Fast deployment, most users | Full control over fee strategy | -The official hosted Facilitator requires **no infrastructure on your end**. Detailed information can also be found in [OfficialFacilitator](../core-concepts/OfficialFacilitator.md) +The officially hosted Facilitator service requires **no infrastructure to maintain**. You can also refer to [Official Facilitator](../core-concepts/OfficialFacilitator.md) for details. #### 3.1 Configure the Service Endpoint -Set your `FACILITATOR_URL` to the Official Facilitator service endpoint: +Set your `FACILITATOR_URL` to the official Facilitator service address: ``` https://facilitator.bankofai.io ``` -This is the address your x402 server calls to verify and settle payments. It is for **API calls only** — do not open it in a browser. +This is the address your x402 server uses to verify and settle payments — **for API calls only**, no need to open it in a browser. -> ⚠️ **Without an API Key, this endpoint is rate-limited to 1 request/minute per IP.** This is fine for testing, but will block your API in production. Proceed to step 3.2 to get your API Key. +> ⚠️ **Without an API Key, this endpoint is rate-limited to 1 request per minute per IP address.** This is sufficient for testing, but in production it will throttle your API. Continue to step 3.2 to apply for an API Key. -#### 3.2 Get Your API Key +#### 3.2 Apply for an API Key -Apply for a free API Key at the admin portal: +Apply for a free API Key in the admin dashboard: [https://admin-facilitator.bankofai.io](https://admin-facilitator.bankofai.io) 1. Open the link above in your browser -2. Click **TronLink** to sign in with your wallet (identity verification only — **no funds deducted**) -3. On the Dashboard, click **"Create API Key"** -4. Click Confirm, then click **View** to reveal and copy your API Key +2. Click **TronLink** to log in with your wallet (for identity verification only — **no charges will be made**) +3. After logging in, go to the Dashboard and click **"Create API Key"** +4. Confirm, then click **View** in the Dashboard to see and copy your API Key -With an API Key configured, the rate limit rises to **1,000 requests/minute** — enough for production. +With an API Key, the rate limit increases to **1,000 requests/minute**, sufficient for production use. -> 📖 **Step-by-step screenshots:** [Official Facilitator](../core-concepts/OfficialFacilitator.md) +> 📖 **Detailed step-by-step guide** available at: [Official Facilitator](../core-concepts/OfficialFacilitator.md) -> ⚠️ **Security:** Your API Key is a service credential — **treat it like a password and never commit it to Git.** +> ⚠️ **Security reminder:** Your API Key is a service credential — **treat it like a password and never commit it to Git** -#### 3.3 Configure Your `.env` File +#### 3.3 Configure the `.env` File -The Facilitator authenticates requests via the HTTP header `X-API-KEY: `. The SDK handles this automatically — just set the following in your `.env` file and the SDK attaches the header on every Facilitator call: +In your project directory (where `server.py` is located), create or edit the `.env` file and add the following: ```bash -# Official Facilitator service endpoint +# Official Facilitator service URL FACILITATOR_URL=https://facilitator.bankofai.io -# API Key — SDK sends this as the X-API-KEY header automatically +# API Key (apply at admin-facilitator.bankofai.io) — SDK passes it automatically via the X-API-KEY header FACILITATOR_API_KEY=paste_your_api_key_here ``` -#### 3.4 Update server.py to Use the Official Facilitator +#### 3.4 Update server.py to Connect to the Official Facilitator -Add `import os` at the top of `server.py` and update the Facilitator initialization: +Update the Facilitator initialization section in `server.py` to read configuration from environment variables (add `import os` at the top of the file): @@ -316,11 +324,11 @@ Add `import os` at the top of `server.py` and update the Facilitator initializat import os # ... other imports unchanged ... -# Official Facilitator URL (read from environment variable) -# The SDK reads FACILITATOR_API_KEY from env automatically — no need to pass it explicitly +# Official Facilitator service URL (read from environment variable) +# SDK automatically reads FACILITATOR_API_KEY from the environment — no need to pass it explicitly FACILITATOR_URL = os.getenv("FACILITATOR_URL", "https://facilitator.bankofai.io") -# Initialize x402 server, connect to Official Facilitator +# Initialize x402 server and connect to Official Facilitator server = X402Server() server.set_facilitator(FacilitatorClient(FACILITATOR_URL)) ``` @@ -332,8 +340,8 @@ server.set_facilitator(FacilitatorClient(FACILITATOR_URL)) import os # ... other imports unchanged ... -# Official Facilitator URL (read from environment variable) -# The SDK reads FACILITATOR_API_KEY from env automatically — no need to pass it explicitly +# Official Facilitator service URL (read from environment variable) +# SDK automatically reads FACILITATOR_API_KEY from the environment — no need to pass it explicitly FACILITATOR_URL = os.getenv("FACILITATOR_URL", "https://facilitator.bankofai.io") # Initialize x402 server, register BSC mechanisms, connect to Official Facilitator @@ -346,49 +354,49 @@ server.set_facilitator(FacilitatorClient(FACILITATOR_URL)) -> ✅ **Done!** The Official Facilitator is configured. **No local service to start** — go straight to Step Four. +> ✅ **Done!** The Official Facilitator is configured — **no local service to start**. Proceed directly to Step 4 to test. -Self-hosting gives you full control over fee policies and energy management — suited for advanced users with custom requirements. +The self-hosted option gives you full control over fee strategy and energy management. It is intended for advanced users with specific customization requirements. -> ⚠️ **Security — please read first:** -> - Requires a **dedicated wallet** private key to pay blockchain gas fees — **keep it separate from your receiving wallet** -> - Only put a small amount of tokens in the Facilitator wallet (just enough for gas) -> - The private key lives only in your `.env` file — **never push it to GitHub or share it** +> ⚠️ **Security reminder — please read first:** +> - You need the private key of a **dedicated wallet** to pay blockchain transaction fees — **this wallet should be separate from your receiving wallet** +> - The Facilitator wallet only needs a small amount of tokens (for fees) — do not deposit large amounts +> - The private key lives only in the `.env` file — **never upload it to GitHub or share it with anyone** #### 3.1 Prepare a Dedicated Facilitator Wallet -Create a brand-new wallet for the Facilitator (same steps as your receiving wallet), then claim test tokens from the faucet to cover gas fees. +Create a dedicated new wallet for the Facilitator, following the same steps as in Prerequisites, then claim test tokens from the faucet (to pay transaction fees). -#### 3.2 Clone and Configure the Facilitator +#### 3.2 Clone and Configure the Facilitator Project -Open a **new terminal window** (keep the current one open) and run: +Open a **new terminal window** (keep the existing one open) and run: ```bash -# Download the demo project (includes Facilitator implementation) +# Download the demo project (includes the Facilitator implementation) git clone https://github.com/BofAI/x402-demo.git cd x402-demo # Install dependencies pip install -r requirements.txt -# Create config file from template +# Create configuration file from the template cp .env.sample .env ``` -Open the `.env` file in `x402-demo` with any text editor and fill in the Facilitator wallet's private key: +Open the `.env` file in the `x402-demo` directory with a text editor and fill in the private key for your dedicated Facilitator wallet: ```bash -# Private key of the Facilitator's dedicated wallet (NOT your receiving wallet!) -# How to export: TronLink → Settings → Account Management → Export Private Key +# Private key of the dedicated Facilitator wallet (NOT your receiving wallet!) +# How to get it: TronLink → Settings → Account Management → Export Private Key TRON_PRIVATE_KEY=paste_your_facilitator_private_key_here -# TronGrid API Key (required for mainnet, optional for testnet) +# TronGrid API Key (required for mainnet, can be left blank for testnet) # Apply at: https://www.trongrid.io/ TRON_GRID_API_KEY= ``` @@ -397,21 +405,21 @@ TRON_GRID_API_KEY= ```bash -# Private key of the Facilitator's dedicated wallet (NOT your receiving wallet!) -# How to export: MetaMask → Account Details → Export Private Key +# Private key of the dedicated Facilitator wallet (NOT your receiving wallet!) +# How to get it: MetaMask → Account Details → Export Private Key BSC_PRIVATE_KEY=paste_your_facilitator_private_key_here ``` -#### 3.3 Start the Facilitator +#### 3.3 Start the Facilitator Service ```bash ./start.sh facilitator ``` -**Expected output:** +**After a successful start, you should see:** ``` Facilitator running on http://localhost:8001 @@ -422,84 +430,86 @@ Supported endpoints: POST /fee/quote ``` -> ✅ **Success check:** Terminal shows `Facilitator running on http://localhost:8001` — **keep this window open** +> ✅ **Success:** Terminal shows `Facilitator running on http://localhost:8001` — **keep this terminal window open, do not close it** -The `FACILITATOR_URL = "http://localhost:8001"` in `server.py` is already correct for self-hosted. **No changes needed** — proceed to Step Four. +The `FACILITATOR_URL = "http://localhost:8001"` in `server.py` is already configured for self-hosting — **no changes needed**. Proceed to Step 4. --- -## Step Four: Start and Test Your API +## Step 4: Start and Test Your API -### 4.1 Start Your API Server +### 4.1 Start the API Server -Open a **third terminal window** (keep the previous terminals running), navigate to your `server.py` directory, and run: +Open a **third terminal window** (do not close the previous ones), navigate to the directory containing `server.py`, and run: ```bash python server.py ``` -**Expected output:** +**After a successful start, you should see:** ``` INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit) INFO: Application startup complete. ``` -> ✅ **Success check:** Terminal shows `Uvicorn running on http://0.0.0.0:8000` +> ✅ **Success:** Terminal shows `Uvicorn running on http://0.0.0.0:8000` + +### 4.2 Test Unpaid Access (Should Be Rejected) -### 4.2 Test Unpaid Access (Should Be Blocked) +In any terminal, run: ```bash curl http://localhost:8000/protected ``` -**Expected result:** +**Expected result:** The server returns an HTTP 402 response with content similar to: ```json {"error": "Payment required", "x402Version": 1} ``` -> ✅ **This is exactly what we want!** Payment protection is working — unpaid requests are blocked. +> ✅ **This is exactly what we want!** It confirms that payment protection is working — unpaid requests are successfully blocked. ### 4.3 Test the Full Payment Flow -To test payment end-to-end, you need a client that can sign payments: +To test the complete pay → receive content flow, you need a client that can sign payments: -- [Quickstart for Human Users](./quickstart-for-human.md) — call your paid API via code -- [Quickstart for AI Agents](./quickstart-for-agent.md) — configure an AI agent to pay automatically +- [Human User Quickstart](./quickstart-for-human.md) — Call your paid API using code +- [AI Agent Quickstart](./quickstart-for-agent.md) — Configure an AI agent to call your API automatically --- ## Troubleshooting | Issue | Solution | -|-------|----------| -| `Connection refused` to Facilitator | **Self-hosted:** confirm the Facilitator terminal is still running on port 8001. **Official:** check that `FACILITATOR_URL` is set to `https://facilitator.bankofai.io` | -| `ModuleNotFoundError: bankofai` | Re-run the Step One install command | -| Invalid wallet address error | TRON address starts with `T`; BSC address starts with `0x` — check for a complete copy | -| Facilitator fails to start (self-hosted) | Check the private key in `.env` — no extra spaces or line breaks | -| API Key invalid or rate-limited (official) | Confirm `FACILITATOR_API_KEY` is correct; visit [admin-facilitator.bankofai.io](https://admin-facilitator.bankofai.io) to check key status | -| `server.py` startup error | Confirm `PAY_TO_ADDRESS` has been replaced with your real wallet address | +|------|----------| +| `Connection refused` when connecting to Facilitator | If using **self-hosted**: confirm the Facilitator terminal from Step 3 is still running on port 8001. If using **official**: check that `FACILITATOR_URL` is correctly set to `https://facilitator.bankofai.io` | +| `ModuleNotFoundError: bankofai` | Re-run the install command from Step 1 | +| Wallet address format error | TRON addresses start with `T`; BSC addresses start with `0x` — check that the address was copied in full | +| Facilitator fails to start (self-hosted) | Check that the private key in the `.env` file is correctly filled in, with no extra spaces or line breaks | +| API Key invalid or rate limited (official) | Confirm `FACILITATOR_API_KEY` is correctly filled in; go to [admin-facilitator.bankofai.io](https://admin-facilitator.bankofai.io) to check the key status | +| `server.py` fails to start | Confirm `PAY_TO_ADDRESS` has been replaced with a real wallet address (do not leave the placeholder text) | -**More examples and references:** +**Need more examples and references?** -- [Full server example](https://github.com/BofAI/x402-demo/tree/main/server) -- [Facilitator example](https://github.com/BofAI/x402-demo/tree/main/facilitator) -- [Facilitator deep-dive](../core-concepts/facilitator.md) — detailed setup comparison for both options -- [Official Facilitator](../core-concepts/OfficialFacilitator.md) — step-by-step with screenshots +- [Complete server example code](https://github.com/BofAI/x402-demo/tree/main/server) +- [Facilitator example code](https://github.com/BofAI/x402-demo/tree/main/facilitator) +- [Facilitator reference](../core-concepts/facilitator.md) — Full setup comparison for both options +- [Official Facilitator](../core-concepts/OfficialFacilitator.md) — Step-by-step guide with screenshots for the API Key --- ## Running on Mainnet -Once your testnet integration is fully verified, follow these steps to accept real USDT/USDD payments: +After fully validating on the testnet, only a few steps are needed to go live and accept real payments: ### 1. Update Server Configuration -Change the `network` parameter in the `@x402_protected` decorator in `server.py`: +Modify the `network` parameter in the `@x402_protected` decorator in `server.py`: @@ -509,7 +519,7 @@ Change the `network` parameter in the `@x402_protected` decorator in `server.py` server=server, prices=["0.0001 USDT"], schemes=["exact_permit"], - network=NetworkConfig.TRON_MAINNET, # Changed from TRON_NILE + network=NetworkConfig.TRON_MAINNET, # Changed from TRON_NILE to TRON_MAINNET pay_to=PAY_TO_ADDRESS, ) ``` @@ -522,7 +532,7 @@ Change the `network` parameter in the `@x402_protected` decorator in `server.py` server=server, prices=["0.0001 USDT"], schemes=["exact_permit"], - network=NetworkConfig.BSC_MAINNET, # Changed from BSC_TESTNET + network=NetworkConfig.BSC_MAINNET, # Changed from BSC_TESTNET to BSC_MAINNET pay_to=PAY_TO_ADDRESS, ) ``` @@ -530,60 +540,60 @@ Change the `network` parameter in the `@x402_protected` decorator in `server.py` -### 2. Update Your Facilitator +### 2. Update Facilitator Configuration -1. **Apply for a TronGrid API Key**: Register at [TronGrid](https://www.trongrid.io/) and add the key to `TRON_GRID_API_KEY` in your `.env` (required for mainnet) -2. **Update private key**: Replace the Facilitator wallet private key with a mainnet wallet key -3. **Fund gas fees**: Deposit enough real TRX in the Facilitator wallet to cover Energy and Bandwidth fees -4. **Switch network**: Update the Facilitator's network config to `NetworkConfig.TRON_MAINNET` +1. **Apply for a TronGrid API Key**: go to [TronGrid](https://www.trongrid.io/) to register and create an API Key, then fill it into the `TRON_GRID_API_KEY` field in `.env` (required for mainnet) +2. **Replace the private key**: update the private key in `.env` to the mainnet Facilitator wallet's private key +3. **Fund the fee wallet**: transfer sufficient real TRX to the Facilitator mainnet wallet (to pay Energy and Bandwidth fees) +4. **Update the network config**: change the network configuration in the Facilitator code to `NetworkConfig.TRON_MAINNET` -1. **Fund gas fees**: Deposit enough real BNB in the Facilitator wallet to cover gas fees -2. **Switch network**: Update the Facilitator's network config to `NetworkConfig.BSC_MAINNET` +1. **Fund the fee wallet**: transfer sufficient real BNB to the Facilitator mainnet wallet (to pay Gas fees) +2. **Update the network config**: change the network configuration in the Facilitator code to `NetworkConfig.BSC_MAINNET` ### 3. Confirm Your Receiving Wallet Address -Make sure `PAY_TO_ADDRESS` is your **real mainnet wallet address** and that you have the seed phrase or private key backed up. +Ensure that `PAY_TO_ADDRESS` is set to a **real mainnet wallet address** you control, and confirm you have a backup of the seed phrase or private key for that wallet. -### 4. Do a Small Real-Money Test First +### 4. Perform a Small Real-Money Test Before Going Live -> ⚠️ **Mainnet warning — real funds involved. Follow these steps strictly:** +> ⚠️ **Mainnet warning — real funds are involved. Please follow these steps carefully:** > -> 1. Complete all testing on testnet before switching to mainnet -> 2. After going live, **send one minimal test payment first (e.g. 0.0001 USDT)** -> 3. Confirm the transaction on the block explorer ([TronScan](https://tronscan.org) or [BscScan](https://bscscan.com)) -> 4. Open your receiving wallet and confirm the funds arrived -> 5. Only open your API to the public after this verification passes +> 1. Ensure all functionality (payment, receipt, error handling) has been fully validated on the testnet +> 2. After going live on mainnet, **start with one minimum-amount real test (e.g. 0.0001 USDT)** +> 3. Confirm the transaction succeeded on the blockchain explorer ([TronScan](https://tronscan.org) or [BscScan](https://bscscan.com)) +> 4. Open your receiving wallet and confirm the funds have arrived +> 5. Only open your API to the public after confirming everything is correct --- ## Next Steps -- Explore [demo examples](https://github.com/BofAI/x402-demo/tree/main/server) for more complex payment flows -- Read the [Core Concepts](../core-concepts/http-402.md) to understand how x402 works under the hood -- Want to understand both Facilitator options in detail? See the [Facilitator guide](../core-concepts/facilitator.md) -- Experience the [user perspective](./quickstart-for-human.md) or set up an [AI agent](./quickstart-for-agent.md) to call your API +- View [demo examples](https://github.com/BofAI/x402-demo/tree/main/server) for more complex payment flows +- Read the [core concepts](../core-concepts/http-402.md) to understand how the x402 protocol works +- Want detailed configuration for both Facilitator options? See the [Facilitator documentation](../core-concepts/facilitator.md) +- Experience calling a paid API from the [user perspective](./quickstart-for-human.md), or configure an [AI agent](./quickstart-for-agent.md) to call your service automatically --- ## Summary -Congratulations 🎉! You've completed the seller quickstart. Here's what you accomplished: +Congratulations 🎉! You've completed the Seller Quickstart. Here's everything you accomplished: -| Step | Accomplished | -|------|-------------| -| **Prerequisites** | Created a receiving wallet and claimed test tokens | -| **Step One** | Installed the x402 SDK | -| **Step Two** | Created a payment-protected API endpoint | -| **Step Three** | Connected to a Facilitator settlement service | -| **Step Four** | Verified payment protection and the full payment flow | +| Step | What You Did | +|------|----------| +| **Prerequisites** | Created a receiving wallet, obtained test tokens, reviewed configuration parameters | +| **Step 1** | Installed the x402 SDK | +| **Step 2** | Created an API server with payment protection | +| **Step 3** | Configured and connected the Facilitator settlement service | +| **Step 4** | Verified payment protection and the full payment flow | -Your API is now ready to receive blockchain payments via x402! +Your API is now ready to accept blockchain payments via the x402 protocol! diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/Intro.md index 01a156be..93ef4ec9 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/Intro.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/Intro.md @@ -1,5 +1,17 @@ # 简介 -BANK OF AI 通过 MCP Server 与 Skills 的双层架构，为构建基于区块链网络的自主智能体（AI Agents）提供了从基础设施 to 业务逻辑的完整解决方案。 +BANK OF AI 通过 **MCP Server** 与 **Skills** 的双层架构，为构建基于区块链网络的自主智能体（AI Agents）提供了从基础设施到业务逻辑的完整解决方案。 -开发者只需部署 MCP Server 并加载相应的 Skills，即可让 AI 智能体从“聊天机器人”进化为具备资产管理能力与链上交互能力的 Web3 经济实体。 +## 架构概览 + +| 层级 | 组件 | 作用 | +| :--- | :--- | :--- | +| 基础设施层 | **MCP Server** | 为 AI 智能体提供与区块链交互的底层能力（查询数据、发起交易、调用合约等） | +| 业务逻辑层 | **Skills** | 为 AI 智能体提供特定领域的操作指南和工作流（如 DEX 交易、支付协议等） | + +开发者只需部署 MCP Server 并加载相应的 Skills，即可让 AI 智能体从"聊天机器人"进化为具备资产管理能力与链上交互能力的 Web3 经济实体。 + +## 快速导航 + +- **了解 MCP Server**：前往 [MCP Server 简介](./MCP/Intro.md)，了解协议架构与通信机制。 +- **了解 Skills**：前往 [Skills 简介](./SKILLS/Intro.md)，了解技能包的设计理念与使用方式。 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/API.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/API.md deleted file mode 100644 index bc9e48e2..00000000 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/API.md +++ /dev/null @@ -1,156 +0,0 @@ -# API 参考 - -## 工具 - -### 钱包与地址 - -| 工具名称 | 说明 | 主要参数 | 模式 | -|---------------------------|--------------------------------------------|------------|------| -| sunswap_get_wallet_address | 获取当前用于 SUNSWAP 操作的 TRON 钱包地址（Base58）。 | `network?` | 读取 | -| sunswap_list_wallets | 列出所有可用钱包（仅 agent-wallet 模式）。 | - | 读取 | -| sunswap_select_wallet | 切换活跃钱包（仅 agent-wallet 模式）。 | `walletId` | 写入 | - -### 余额 - -| 工具名称 | 说明 | 主要参数 | 模式 | -|----------------------|--------------------------------|-------------------------|------| -| sunswap_get_balances | 查询某地址的 TRX 与 TRC20 余额。 | `tokens`, `network?`, `ownerAddress?` | 读取 | - -### 价格与报价 - -| 工具名称 | 说明 | 主要参数 | 模式 | -|---------------------------|----------------------------------------|------------------------|------| -| sunswap_get_token_price | 通过 SUN.IO API 按地址/符号获取代币价格。 | `tokenAddress?`, `symbol?` | 读取 | -| sunswap_quote_exact_input | 通过路由器的 view 函数进行精确输入兑换报价。 | `routerAddress`, `args`, `network?`, `functionName?`, `abi?` | 读取 | - -### 智能合约（读） - -| 工具名称 | 说明 | 主要参数 | 模式 | -|----------------------|--------------------------------|----------------------------------|------| -| sunswap_read_contract | 调用 TRON 合约的 view/pure 函数。 | `address`, `functionName`, `network?`, `args?`, `abi?` | 读取 | - -### 智能合约（写） - -| 工具名称 | 说明 | 主要参数 | 模式 | -|------------------------|------------------------------|---------------------------------------|------| -| sunswap_send_contract | 执行会改变状态的合约函数调用。 | `address`, `functionName`, `network?`, `args?`, `value?`, `abi?` | 写入 | - -### 兑换 - -| 工具名称 | 说明 | 主要参数 | 模式 | -|---------------------------|----------------------------------------------------|--------------------------------------|------| -| sunswap_swap | 通过 Universal Router 执行兑换（tokenIn, tokenOut, amountIn）。 | `tokenIn`, `tokenOut`, `amountIn`, `network?`, `slippage?` | 写入 | -| sunswap_swap_exact_input | 使用指定路由器与参数执行 swapExactInput。 | `routerAddress`, `args`, `network?`, `functionName?`, `value?`, `abi?` | 写入 | - -### V2 流动性 - -| 工具名称 | 说明 | 主要参数 | 模式 | -|-----------------------------|----------------------------------------------------------------------|--------------------------------------------------------------------------|------| -| sunswap_v2_add_liquidity | 向 V2 池添加流动性；若其中一档为原生 TRX 则使用 addLiquidityETH。 | `routerAddress`, `tokenA`, `tokenB`, `amountADesired`, `amountBDesired`, `network?`, `amountAMin?`, `amountBMin?`, `to?`, `deadline?`, `abi?` | 写入 | -| sunswap_v2_remove_liquidity | 移除 V2 流动性；若其中一档为 TRX 则使用 removeLiquidityETH。 | `routerAddress`, `tokenA`, `tokenB`, `liquidity`, `network?`, `amountAMin?`, `amountBMin?`, `to?`, `deadline?`, `abi?` | 写入 | - -### V3 流动性 - -| 工具名称 | 说明 | 主要参数 | 模式 | -|------------------------------|------------------------------------|--------------------------------------------------------------------------|------| -| sunswap_v3_mint_position | 铸造新的 V3 集中流动性仓位。 | `positionManagerAddress`, `token0`, `token1`, `network?`, `fee?`, `tickLower?`, `tickUpper?`, `amount0Desired?`, `amount1Desired?`, `amount0Min?`, `amount1Min?`, `recipient?`, `deadline?`, `abi?` | 写入 | -| sunswap_v3_increase_liquidity | 为已有 V3 仓位增加流动性。 | `positionManagerAddress`, `tokenId`, `network?`, `token0?`, `token1?`, `fee?`, `amount0Desired?`, `amount1Desired?`, `amount0Min?`, `amount1Min?`, `deadline?` | 写入 | -| sunswap_v3_decrease_liquidity | 减少已有 V3 仓位的流动性。 | `positionManagerAddress`, `tokenId`, `liquidity`, `network?`, `token0?`, `token1?`, `fee?`, `amount0Min?`, `amount1Min?`, `deadline?` | 写入 | -| sunswap_v3_collect | 收取 V3 仓位累积的手续费。 | `positionManagerAddress`, `tokenId`, `network?`, `recipient?` | 写入 | - -### V4 流动性 - -| 工具名称 | 说明 | 主要参数 | 模式 | -|------------------------------|------------------------------------|--------------------------------------------------------------------------|------| -| sunswap_v4_mint_position | 铸造新的 V4 集中流动性仓位，支持 Permit2 授权。 | `token0`, `token1`, `network?`, `fee?`, `tickLower?`, `tickUpper?`, `amount0Desired?`, `amount1Desired?`, `slippage?`, `recipient?`, `deadline?`, `sqrtPriceX96?`, `createPoolIfNeeded?` | 写入 | -| sunswap_v4_increase_liquidity | 增加已有 V4 仓位的流动性。 | `tokenId`, `token0`, `token1`, `network?`, `fee?`, `amount0Desired?`, `amount1Desired?`, `slippage?`, `deadline?` | 写入 | -| sunswap_v4_decrease_liquidity | 减少已有 V4 仓位的流动性。 | `tokenId`, `liquidity`, `token0`, `token1`, `network?`, `fee?`, `amount0Min?`, `amount1Min?`, `slippage?`, `deadline?` | 写入 | -| sunswap_v4_collect | 收取 V4 仓位累积的手续费。 | `tokenId`, `network?`, `token0?`, `token1?`, `fee?`, `deadline?` | 写入 | - ---- - -## OpenAPI 衍生工具（SUN.IO API） - -工具由 `specs/sunio-open-api.json` 生成，命名与参数与规范一致。 - -### 交易 - -| 工具名称 | 说明 | 主要参数 | 模式 | -| :-- | :-- | :-- | :-- | -| `scanTransactions` | 按协议、代币/池子、类型和时间范围扫描 DEX 交易。 | `protocol?`, `token?`, `pool?`, `type?`, `timeRange?` | 读取 | - -### 代币 - -| 工具名称 | 说明 | 主要参数 | 模式 | -| :-- | :-- | :-- | :-- | -| `getTokens` | 按地址和协议获取代币。 | `address?`, `protocol?` | 读取 | -| `searchTokens` | 按关键字模糊搜索代币。 | `keyword` | 读取 | - -### 协议 - -| 工具名称 | 说明 | 主要参数 | 模式 | -| :-- | :-- | :-- | :-- | -| `getProtocol` | 协议快照数据。 | - | 读取 | -| `getVolHistory` | 协议交易量历史。 | - | 读取 | -| `getUsersCountHistory` | 协议用户数历史。 | - | 读取 | -| `getTransactionsHistory` | 协议交易笔数历史。 | - | 读取 | -| `getPoolsCountHistory` | 协议池数量历史。 | - | 读取 | -| `getLiqHistory` | 协议流动性历史。 | - | 读取 | - -### 价格 - -| 工具名称 | 说明 | 主要参数 | 模式 | -| :-- | :-- | :-- | :-- | -| `getPrice` | 代币价格查询。 | `tokenAddress` | 读取 | - -### 持仓 - -| 工具名称 | 说明 | 主要参数 | 模式 | -| :-- | :-- | :-- | :-- | -| `getUserPositions` | 用户流动性持仓。 | `userAddress` | 读取 | -| `getPoolUserPositionTick` | 池子 tick 级别的持仓/流动性详情。 | `poolAddress`, `userAddress` | 读取 | - -### 池子 - -| 工具名称 | 说明 | 主要参数 | 模式 | -| :-- | :-- | :-- | :-- | -| `getPools` | 按地址、代币或协议获取池子。 | `address?`, `token?`, `protocol?` | 读取 | -| `getTopApyPoolList` | 分页获取 APY 最高的池子。 | `limit?`, `offset?` | 读取 | -| `searchPools` | 池子搜索。 | `keyword` | 读取 | -| `searchCountPools` | 池子搜索计数。 | `keyword` | 读取 | -| `getPoolHooks` | 池子 hooks 列表。 | `poolAddress` | 读取 | -| `getPoolVolHistory` | 池子交易量历史。 | `poolAddress` | 读取 | -| `getPoolLiqHistory` | 池子流动性历史。 | `poolAddress` | 读取 | - -### 交易对 - -| 工具名称 | 说明 | 主要参数 | 模式 | -| :-- | :-- | :-- | :-- | -| `getPairsFromEntity` | 代币交易对实体查询。 | `token0?`, `token1?` | 读取 | - -### 矿池 - -| 工具名称 | 说明 | 主要参数 | 模式 | -| :-- | :-- | :-- | :-- | -| `getFarms` | 矿池列表。 | - | 读取 | -| `getFarmTransactions` | 矿池交易扫描。 | `farmAddress` | 读取 | -| `getFarmPositions` | 用户矿池持仓。 | `userAddress` | 读取 | - -## 默认合约地址 - -在 `src/sunswap/constants.ts` 中定义： - -- **V2 主网**：Factory (`SUNSWAP_V2_MAINNET_FACTORY`)、Router (`SUNSWAP_V2_MAINNET_ROUTER`) -- **V2 Nile**：Factory (`SUNSWAP_V2_NILE_FACTORY`)、Router (`SUNSWAP_V2_NILE_ROUTER`) -- **V3 主网**：Factory (`SUNSWAP_V3_MAINNET_FACTORY`)、Position Manager (`SUNSWAP_V3_MAINNET_POSITION_MANAGER`) -- **V3 Nile**：Factory (`SUNSWAP_V3_NILE_FACTORY`)、Position Manager (`SUNSWAP_V3_NILE_POSITION_MANAGER`) -- **TRX**：`T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb` -- **WTRX**（主网/Nile）：内部用于 TRX 交易对查询 - -调用方可仅传 `network` 与代币地址使用上述默认地址，也可通过工具参数覆盖路由器/仓位管理器地址与 ABI。 - -## 网络参数 - -在支持的工具中可传入： - -- **network**（可选）：`mainnet`（默认）、`nile` 或 `shasta`。 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/FAQ.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/FAQ.md new file mode 100644 index 00000000..2c83c38a --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/FAQ.md @@ -0,0 +1,579 @@ +--- +title: 常见问题与排查 +description: SUN MCP Server 的常见问题解答，涵盖连接、认证、DeFi 操作和故障排除。 +--- + +# 常见问题与排查 + +本页面收集了使用 SUN MCP Server 时的常见问题及其解决方案。 + +## 连接问题 + +### Claude Desktop "无法连接到 MCP 服务器" + +**症状：** Claude Desktop 显示服务器未响应或连接被拒绝。 + +**解决步骤：** + +1. **检查 Node.js 安装** + ```bash + node --version # 应返回 v18+ + npm --version + ``` + +2. **验证服务器运行** + ```bash + # 如果使用官方服务器 + npx -y @bankofai/sun-mcp-server + + # 如果使用本地部署 + npm start + ``` + +3. **检查 JSON 格式** + - 在 Claude Desktop 配置中验证 `stdio.json` 的 JSON 格式 + - 常见错误：末尾多余逗号、未匹配的括号 + +4. **重启 Claude Desktop** + - 完全关闭应用程序 + - 清除缓存：删除 `~/.claude` 目录中的临时文件 + - 重新启动应用程序 + +5. **检查服务器日志** + ```bash + # 如果使用官方服务器，启用详细日志 + DEBUG=* npx -y @bankofai/sun-mcp-server + ``` + +**如果问题持续：** 查看 [官方服务器访问指南](OfficialServerAccess.md) 以获取最新的配置示例。 + +### HTTP 模式下"连接被拒绝" + +**症状：** 尝试通过 HTTP 连接时出现连接被拒绝错误。 + +**常见原因和解决方案：** + +1. **服务器未运行** + ```bash + # 启动服务器在 HTTP 模式 + sun-mcp-server --http --port 8080 + ``` + +2. **端口 8080 被占用** + ```bash + # 检查端口占用 + lsof -i :8080 + + # 使用不同的端口 + sun-mcp-server --http --port 8081 + ``` + +3. **防火墙阻止连接** + - 检查本地防火墙规则 + - 确保允许 localhost:8080 连接 + - 在 macOS 上：系统设置 > 安全与隐私 > 防火墙 + +4. **确认服务器地址** + - 使用 `http://localhost:8080` 而非 `127.0.0.1:8080` + - 确保没有拼写错误 + +### 工具列表中只有读取工具 + +**症状：** 无法看到 `sunswap_swap`、`sunswap_add_liquidity` 等写入工具。 + +**原因：** 未配置钱包。 + +**解决方案：** + +1. **配置 Agent Wallet** + ```bash + export AGENT_WALLET_PASSWORD="your_secure_password" + ``` + +2. **或配置私钥（仅测试网）** + ```bash + export TRON_PRIVATE_KEY="your_64_hex_char_private_key" + ``` + +3. **或配置助记词** + ```bash + export TRON_MNEMONIC="word1 word2 ... word12" + ``` + +4. **重新启动服务器**并重新连接 Claude Desktop + +验证配置成功的方式：查看 [完整能力清单](ToolList.md) 中的完整能力清单。 + +## 认证与密钥问题 + +### "私钥无效"错误 + +**症状：** 服务器拒绝提供的私钥。 + +**私钥格式要求：** +- 必须是 64 个十六进制字符（不包括 `0x` 前缀） +- 有效范围：`0x0000000000000000000000000000000000000000000000000000000000000001` 至 `0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364140` + +**检查步骤：** +```bash +# 检查私钥长度 +echo -n "your_private_key" | wc -c +# 应输出 64 + +# 检查是否为有效的十六进制 +echo "your_private_key" | grep -E '^[0-9a-fA-F]{64}$' +# 如果有输出，则格式正确 +``` + +**常见错误：** +- 包含 `0x` 前缀（移除它） +- 长度不足 64 字符（从导出工具获取完整密钥） +- 包含空格或特殊字符 + +### "Agent Wallet 密码错误" + +**症状：** 服务器无法解密 Agent Wallet。 + +**解决步骤：** + +1. **验证密码环境变量** + ```bash + echo $AGENT_WALLET_PASSWORD + # 应输出你的密码 + ``` + +2. **检查 Agent Wallet 目录** + ```bash + # 默认位置 + ls ~/.agent-wallet/ + # 应包含 wallet.json 等文件 + ``` + +3. **重新初始化 Wallet** + ```bash + # 删除现有 wallet（备份重要数据！） + rm -rf ~/.agent-wallet/ + + # 使用正确的密码重启服务器 + export AGENT_WALLET_PASSWORD="your_new_password" + sun-mcp-server + ``` + +4. **验证密码复杂性** + - 使用强密码（最少 8 字符） + - 避免特殊字符，使用字母数字组合 + +### TronGrid API Key 不生效 + +**症状：** API 调用返回错误或速率限制错误。 + +**解决步骤：** + +1. **检查环境变量名称** + ```bash + # 正确的名称 + export TRON_GRID_API_KEY="your_api_key" + + # 错误的名称（常见错误） + export TRONGRID_API_KEY="..." # ❌ 不要这样做 + ``` + +2. **验证 API Key 有效性** + - 登录 [TronGrid 控制面板](https://dashboard.trongrid.io) + - 确认 API Key 未过期或被禁用 + - 检查请求限额是否足够 + +3. **验证环境变量已设置** + ```bash + echo $TRON_GRID_API_KEY + ``` + +4. **重启服务器** + ```bash + # 设置后重启 + npx -y @bankofai/sun-mcp-server + ``` + +5. **检查网络连接** + ```bash + curl -H "TRONGRID-API-KEY: $TRON_GRID_API_KEY" \ + https://api.trongrid.io/v1/now + # 应返回块信息 + ``` + +### "Conflicting wallet modes" + +**症状：** 错误 "检测到冲突的钱包模式"。 + +**原因：** 同时设置了多个钱包环境变量。 + +**解决方案：** 仅设置以下之一： + +```bash +# 选项 1：Agent Wallet（推荐用于生产） +export AGENT_WALLET_PASSWORD="your_password" +unset TRON_PRIVATE_KEY +unset TRON_MNEMONIC + +# 选项 2：私钥（仅限测试网） +export TRON_PRIVATE_KEY="your_64_hex_chars" +unset AGENT_WALLET_PASSWORD +unset TRON_MNEMONIC + +# 选项 3：助记词 +export TRON_MNEMONIC="word1 word2 ... word12" +unset AGENT_WALLET_PASSWORD +unset TRON_PRIVATE_KEY +``` + +**验证配置：** +```bash +# 清除所有钱包相关环境变量 +unset AGENT_WALLET_PASSWORD TRON_PRIVATE_KEY TRON_MNEMONIC + +# 只设置一个 +export AGENT_WALLET_PASSWORD="your_password" + +# 重启服务器 +sun-mcp-server +``` + +## DeFi 操作错误 + +### "兑换失败" + +**症状：** `sunswap_swap` 调用返回错误。 + +**常见原因和解决方案：** + +1. **余额不足** + ```bash + # 检查源代币余额 + sunswap_get_balances # 列出所有余额 + ``` + - 确认有足够的源代币 + - 账户中的金额应包括 Gas 费用 + +2. **滑点容限过低** + ``` + # 示例：2% 滑点容限可能不够 + 增加到 3-5% + ``` + - 波动市场中可能需要更高的容限 + - 但过高的容限增加了被抢先交易的风险 + +3. **代币不可交易** + - 检查代币是否在 SunSwap 上列出 + - 某些新代币可能不支持交易 + - 验证代币合约地址是否正确 + +4. **流动性不足** + ``` + 使用 sunswap_quote_exact_input 检查可用流动性 + ``` + - 小额交易可能失败 + - 尝试更小的数量或使用多跳路由 + +**诊断步骤：** +``` +1. 检查余额 +2. 使用 sunswap_quote_exact_input 估计输出 +3. 尝试使用更高的滑点容限 +4. 检查网络状态 +``` + +### "添加流动性失败" + +**症状：** `sunswap_add_liquidity` 返回错误。 + +**常见原因和解决方案：** + +1. **代币未授权** + ``` + 需要授权两个代币用于 SunSwap 合约 + ``` + - 调用 `sunswap_approve_token` 或 `permit2_approve` + - 授予足够的金额 + - 两个代币都需要授权 + +2. **数量比例不合理** + ``` + 当前价格可能已变化 + 减少滑点容限允许更大范围的比例 + ``` + - 检查池子的当前价格 + - 调整代币数量以匹配池子的比例 + - 或增加容限百分比 + +3. **金额太小** + ``` + 最小流动性要求可能未满足 + ``` + - 尝试增加金额 + - 检查 SunSwap 的最小头寸要求 + +4. **池子不存在** + - 验证池子对是否在 SunSwap 上存在 + - 检查费用等级是否正确（V2：0.3%，V3：0.01%-1%） + +**诊断提示：** 始终先验证余额和授权，再调用添加流动性。 + +### "Permit2 签名失败" + +**症状：** Permit2 授权返回签名错误。 + +**解决步骤：** + +1. **检查 Wallet 支持** + ```bash + # Agent Wallet 必须支持 signTypedData + echo $AGENT_WALLET_PASSWORD # 确认已设置 + ``` + +2. **验证签名数据** + - 检查 Permit2 请求的结构化数据 + - 确认链 ID、代币地址、截止时间正确 + +3. **重新初始化 Wallet** + ```bash + rm -rf ~/.agent-wallet/ + export AGENT_WALLET_PASSWORD="your_password" + sun-mcp-server + ``` + +4. **使用备用授权方法** + ``` + 如果 Permit2 持续失败，改用 sunswap_approve_token + ``` + +### 交易显示"REVERT"状态 + +**症状：** 交易提交但在链上还原。 + +**常见原因：** + +1. **余额在交易签署后减少** + - 钱包可能同时参与其他交易 + - 间隔足够的时间确保提交 + +2. **滑点价格变化** + - 交易排队期间价格已改变 + - 增加滑点容限重试 + +3. **合约状态改变** + - 池子或代币合约已更新 + - 等待一个区块后重试 + +4. **授权不足** + - Permit2 授权已过期或用尽 + - 重新授权后重试 + +5. **Gas 不足** + - TRON 上不常见，但检查账户余额 + - 确保账户有足够的 TRX 作为 Gas + +**调试提示：** +``` +检查交易哈希在 https://tronscan.org 上的详细错误信息 +``` + +## AI 行为问题 + +### AI 构造了无效代币地址 + +**症状：** AI 使用了不存在的代币地址，导致操作失败。 + +**解决方案：** + +1. **在提示中提供准确的地址** + ``` + 请使用 USDT（T9yD14Nj9j7xAB4dbGknA47WWJcZ541TZJ） + ``` + +2. **使用官方代币列表** + - 从 SunSwap 或 TronScan 获取地址 + - 始终验证地址格式（大小写和长度） + +3. **让 AI 验证地址** + ``` + 在执行任何操作前，使用 sunswap_get_token_price + 验证代币是否存在 + ``` + +### AI 尝试调用不存在的工具 + +**症状：** AI 调用了 `invalid_tool_name` 等不存在的工具。 + +**解决方案：** + +1. **参考官方工具列表** + - 查阅 [SUN MCP Server 工具列表](ToolList.md) + - 提供正确的工具名称给 AI + +2. **提示中明确列出工具** + ``` + 可用的兑换工具包括： + - sunswap_swap + - sunswap_quote_exact_input + - sunswap_quote_exact_output + ``` + +3. **简化请求** + - 请求单个操作而非复杂的多步骤工作流 + - AI 会更可靠地调用正确的工具 + +### 响应速度较慢 + +**症状：** 查询数据或执行操作需要很长时间。 + +**优化步骤：** + +1. **配置 TronGrid API Key** + ```bash + export TRON_GRID_API_KEY="your_api_key" + ``` + - 无 API Key 使用公开节点，速度较慢 + - 有 API Key 访问专用节点 + +2. **简化工作流** + - 减少多工具协调的步骤数 + - 避免大量连续查询 + +3. **使用本地服务器** + - 参考 [本地私有化部署](LocalPrivatizedDeployment.md) + - 可能比官方服务器更快（取决于网络） + +4. **批量操作** + ``` + 合并相关查询以减少往返次数 + ``` + +## 通用问题 + +### 主网、Nile 和 Shasta 有什么区别？ + +| 特性 | 主网（Mainnet） | Nile 测试网 | Shasta 测试网 | +|------|---|---|---| +| **用途** | 生产环境 | 官方测试 | 社区测试 | +| **网络参数** | `mainnet` | `nile` | `shasta` | +| **真实价值** | 是 | 否（测试 TRX） | 否（测试 TRX） | +| **交易最终性** | 立即 | 立即 | 立即 | +| **推荐用途** | 生产 DeFi | 开发和测试 | 实验 | +| **稳定性** | 最高 | 高 | 中等 | +| **获取测试 TRX** | 不适用 | [Nile Faucet](https://nile.trongrid.io/join/getjoined) | [Shasta Faucet](https://shasta.trongrid.io/join/getjoined) | + +**最佳实践：** +- 开发时始终使用 Nile +- 最终测试在 Shasta +- 仅在充分验证后迁移到主网 + +### 能否同时使用多个 MCP Server 实例？ + +**是的。** 例如，可以同时运行官方主网服务器和本地 Nile 实例。 + +**配置示例（Claude Desktop）：** + +```json +{ + "mcpServers": { + "sun-mainnet": { + "command": "npx", + "args": ["-y", "@bankofai/sun-mcp-server"], + "env": { + "TRON_NETWORK": "mainnet", + "AGENT_WALLET_PASSWORD": "your_mainnet_password" + } + }, + "sun-nile": { + "command": "sun-mcp-server", + "args": ["--port", "8081"], + "env": { + "TRON_NETWORK": "nile", + "TRON_PRIVATE_KEY": "your_testnet_private_key" + } + } + } +} +``` + +**注意：** 分别为每个实例使用不同的钱包凭证，以避免混淆。 + +### 如何更新到最新版本？ + +**使用 npx（推荐）：** +```bash +# npx 自动获取最新版本 +npx -y @bankofai/sun-mcp-server + +# 强制清除缓存并获取最新版本 +npx --clear-cache -y @bankofai/sun-mcp-server +``` + +**使用本地安装：** +```bash +# 更新全局安装 +npm install -g @bankofai/sun-mcp-server + +# 或在项目中更新 +npm update @bankofai/sun-mcp-server +``` + +**使用 Git 仓库：** +```bash +# 克隆或更新仓库 +git clone https://github.com/BofAI/sun-mcp-server.git +cd sun-mcp-server + +# 拉取最新代码 +git pull + +# 安装依赖和启动 +npm install +npm start +``` + +### 工具太多导致 LLM 上下文溢出？ + +**症状：** Claude 报告 token 限制被超出或工具列表太长。 + +**解决方案：使用工具过滤：** + +```bash +# 仅启用特定工具（白名单） +sun-mcp-server --whitelist sunswap_swap,sunswap_get_balances,sunswap_quote_exact_input + +# 排除某些工具（黑名单） +sun-mcp-server --blacklist getUserPositions,getPoolVolHistory +``` + +**优化提示：** +- 为不同任务创建多个服务器实例 +- 使用白名单仅加载必要工具 +- 定期清理未使用的工具配置 + +### 支持哪个 MCP 协议版本？ + +**SUN MCP Server 支持 MCP 1.10.2 及更高版本。** + +**验证版本：** +```bash +# 检查依赖中的版本 +npm list @modelcontextprotocol/sdk + +# 应输出类似： +# @modelcontextprotocol/sdk@1.10.2 +``` + +**升级 MCP SDK：** +```bash +npm update @modelcontextprotocol/sdk +``` + +--- + +## 获取更多帮助 + +- **GitHub Issues：** https://github.com/BofAI/sun-mcp-server/issues +- **完整文档：** 查阅 [工具列表](ToolList.md) +- **本地部署：** 参考 [本地私有化部署](LocalPrivatizedDeployment.md) +- **官方服务器：** 参考 [官方服务器访问](OfficialServerAccess.md) diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/Intro.md index 0d61747f..cfcb528f 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/Intro.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/Intro.md @@ -1,91 +1,107 @@ - # 简介 -SUN MCP Server 是面向 **TRON 网络上 SUN.IO（SUNSWAP）** 生态的 Model Context Protocol (MCP) 服务端。它让 AI 智能体通过统一工具接口查询 SUN.IO API 数据（代币、池子、价格、协议指标、交易、挖矿、合约），并执行兑换、V2/V3 流动性管理等 DeFi 操作。 +## SUN MCP Server 是什么？ + +SUN MCP Server 是连接 AI 助手与 TRON 链上最大去中心化交易所 [SUN.IO（SunSwap）](https://sun.io) 的桥梁。它基于 [Model Context Protocol (MCP)](../Intro.md) 标准协议，让你可以用自然语言查询 DeFi 数据、执行代币兑换、管理流动性仓位——而无需自己与合约交互或处理复杂的链上参数。 + +举个例子：你只需对 Claude 说"帮我把 100 USDT 换成 TRX，用 SunSwap 的最优路径"，AI 就会自动查询最佳兑换路径、估算滑点、请求你确认，然后执行交易。不需要打开前端界面，不需要手动审批合约，也不需要了解路由合约的细节。 + +这对不同的人意味着不同的事情： + +- 如果你是 **DeFi 用户**，它让你用对话的方式操作 SunSwap——兑换、添加流动性、收取手续费，像发消息一样自然。 +- 如果你是 **Web3 开发者**，它是你快速查询 SunSwap 链上状态和协议指标的工具，省去大量 API 对接工作。 +- 如果你是 **AI Agent 构建者**，它提供标准化的 DeFi 工具集，可以直接编排进你的自动化交易或做市策略。 +- 如果你是 **数据分析师**，它让 SunSwap 的交易量、池子 APY、持仓数据触手可及，无需翻 API 文档。 + +--- + +## 它能做什么？ + +SUN MCP Server 覆盖了与 SunSwap DEX 交互的完整操作，从链上数据查询到代币兑换和流动性管理，共提供 **41 个工具**（18 个自定义工具 + 23 个 SUN.IO OpenAPI 工具）。 + +以下是核心能力概览——每一项都可以通过自然语言触发： + +**数据查询（只读，无需私钥）：** + +| 能力 | 描述 | 你可以这样说 | +| :--- | :--- | :--- | +| **代币价格** | 查询 SunSwap 上任意代币的实时价格 | "USDT/TRX 现在的价格是多少？" | +| **兑换报价** | 获取指定输入金额的最优兑换路径和预期输出 | "100 USDT 能换多少 TRX？" | +| **池子数据** | 查询池子列表、APY、交易量、流动性历史 | "USDT-TRX 池子当前 APY 是多少？" | +| **持仓查询** | 查看某地址在 SunSwap 上的流动性仓位 | "查一下我的 SunSwap 仓位" | +| **协议统计** | 获取 SunSwap 整体交易量、用户数、池数量历史 | "过去 7 天 SunSwap 的交易量是多少？" | +| **矿池信息** | 查询矿池列表和用户的挖矿持仓 | "SunSwap 上有哪些收益矿池？" | + +**DeFi 操作（写入，需要私钥）：** -本服务基于 [Model Context Protocol](https://modelcontextprotocol.io/)，向兼容 MCP 的客户端（如 Claude Desktop、Cursor、Google Antigravity）提供链上与 API 能力，并整合： +| 能力 | 描述 | 你可以这样说 | +| :--- | :--- | :--- | +| **代币兑换** | 通过 Universal Router 执行最优路径兑换 | "帮我把 100 USDT 换成 TRX" | +| **V2 流动性** | 向 V2 池添加/移除流动性，自动处理 TRX/WTRX 转换 | "向 USDT-TRX V2 池添加 100 USDT 流动性" | +| **V3 流动性** | 铸造和管理集中流动性仓位，收取手续费 | "收取我 V3 仓位累积的手续费" | +| **V4 流动性** | V4 集中流动性操作，支持 Permit2 授权 | "铸造一个 V4 USDT-TRX 仓位" | +| **合约交互** | 直接读取或调用任意 TRON 智能合约函数 | "查询这个合约的当前 slot0 状态" | -- **基于 OpenAPI 的工具**：来自 SUN.IO 公开 API 规范（`specs/sunio-open-api.json`），用于只读查询。 -- **自定义 SUNSWAP 工具**（`sunswap_*`）：钱包、余额、报价、兑换及 V2/V3 流动性，由 `tronweb` 与链上合约调用支持。 +完整的工具列表和参数说明，请参阅 [完整能力清单](./ToolList.md)。 -## MCP 服务器 URL -为了方便不同需求的用户，你可以选择直接连接[官方云服务](./OfficialServerAccess.md)，也可以选择在自己的电脑上进行[本地化部署](./LocalPrivatizedDeployment.md)。其中官方服务只提供读取服务。 +--- -|环境|url| -|:---|:---| -|生产环境|[https://sun-mcp-server.bankofai.io/mcp](https://sun-mcp-server.bankofai.io/mcp)| +## 两种接入方式 +了解了 SUN MCP Server 的能力后，你需要选择一种接入方式。根据你的使用场景，有两条路径： -## 核心能力概览 +**[官方云服务](./OfficialServerAccess.md)** — 适合快速体验和数据查询。不需要安装任何东西，在 AI 客户端配置中加一行服务地址就能开始使用。但云服务只提供**只读**能力——查询代币价格、池子数据、协议统计等，不支持执行兑换、添加流动性等链上写操作。 -* **SUN.IO API（只读）**：查询代币、池子、价格、协议历史、持仓、矿池与交易。 -* **钱包与余额**：获取钱包地址、列出/切换钱包、查询 TRX 与 TRC20 余额。 -* **价格与报价**：按地址/符号获取代币价格；通过智能路由器获取兑换报价。 -* **智能合约交互**：读写 TRON 合约；流动性与兑换流程中自动进行 TRC20 授权检查。 -* **兑换**：通过 Universal Router 智能兑换或使用指定路由器低级别兑换。 -* **V2 流动性**：添加/移除 V2 流动性，含原生 TRX 自动处理。 -* **V3 流动性**：铸造、增加、减少 V3 集中流动性仓位及收取手续费。 -* **V4 流动性**：铸造、增加、减少 V4 集中流动性仓位及收取手续费，支持 Permit2。 -* **钱包与安全**：支持私钥或 BIP-39 助记词；可选 Agent Wallet；全面覆盖 Mainnet、Nile、Shasta。 +**[本地私有化部署](./LocalPrivatizedDeployment.md)** — 适合需要完整 DeFi 功能的用户。在你自己的机器上运行 SUN MCP Server，配置钱包后即可解锁兑换、流动性管理等全部操作。私钥完全在本地管理，不会上传到任何远程服务。 +两者的核心区别归结为一点：**是否需要签名交易**。 -## 详细功能特性 +| 对比项 | 官方云服务 | 本地私有化部署 | +| :--- | :--- | :--- | +| **功能范围** | 仅读取（数据查询） | 完整功能（查询 + 兑换 + 流动性） | +| **上手难度** | 加一条配置即可 | 需本地安装和构建 | +| **是否需要私钥** | 不需要 | 需要（写入操作必须） | +| **代币兑换/流动性** | 不支持 | 支持 | +| **适合场景** | 数据查询、入门体验 | DeFi 操作、自动化交易策略 | +| **安全性** | 高（无私钥暴露风险） | 取决于你的密钥管理方式 | -SUN MCP Server 提供的具体功能列表，供开发者和高级用户参考： +:::tip 不确定选哪个？ +如果你只是想查查 SunSwap 的价格和池子数据，从[官方云服务](./OfficialServerAccess.md)开始就好，1 分钟即可接入。等到需要执行兑换或管理流动性时，再切换到[本地私有化部署](./LocalPrivatizedDeployment.md)。 +::: -### SUN.IO API（只读） -* **交易**：按协议、代币/池子、类型和时间范围扫描 DEX 交易。 -* **代币**：按地址和协议获取代币信息，支持关键字模糊搜索。 -* **协议**：协议快照数据及历史 KPI（交易量、用户数、交易笔数、池数量、流动性）。 -* **价格**：按地址查询代币价格。 -* **持仓**：查询用户流动性持仓与池子 tick 级别的持仓/流动性详情。 -* **池子**：列表/搜索池子、最高 APY 池子、hooks、交易量与流动性历史。 -* **交易对**：代币交易对实体查询。 -* **矿池**：矿池列表、矿池交易扫描、用户矿池持仓。 +--- -### 钱包与余额 -* **钱包地址**：获取当前用于 SUNSWAP 操作的 TRON 钱包地址（Base58）。 -* **钱包列表**：列出所有可用钱包（仅 agent-wallet 模式）。 -* **切换钱包**：切换活跃钱包（仅 agent-wallet 模式）。 -* **余额查询**：查询某地址的 TRX 与 TRC20 余额。 +## 支持的网络 -### 价格与报价 -* **代币价格**：通过 SUN.IO API 按地址/符号获取代币价格。 -* **兑换报价**：通过智能路由器获取精确输入兑换报价。 +无论选择哪种接入方式，SUN MCP Server 都支持以下三个网络（默认连接主网）： -### 智能合约交互 -* **读取合约**：调用 TRON 合约的 view/pure 函数。 -* **写入合约**：执行会改变状态的合约函数调用，可附带 TRX 金额。 +| 网络 | 标识符 | 用途 | 区块浏览器 | +| :--- | :--- | :--- | :--- | +| **主网** | `mainnet` | 生产环境，真实资产 | [tronscan.org](https://tronscan.org) | +| **Nile 测试网** | `nile` | 开发测试（推荐） | [nile.tronscan.org](https://nile.tronscan.org) | +| **Shasta 测试网** | `shasta` | 开发测试 | [shasta.tronscan.org](https://shasta.tronscan.org) | -### 兑换 -* **智能兑换**：通过 Universal Router 执行兑换，自动寻找最佳路径并处理 Permit2 授权。 -* **低级别兑换**：使用指定路由器与参数执行兑换，完全控制路由细节。 +调用工具时，通过 `network` 参数指定目标网络。**强烈建议每次新操作先在 Nile 测试网上验证**，主网操作直接涉及真实资产，错误无法撤回。 -### V2 流动性 -* **添加流动性**：向 V2 池添加流动性；若其中一档为原生 TRX 则自动使用 `addLiquidityETH`，TRC20 授权自动处理。 -* **移除流动性**：移除 V2 流动性；当一侧为 TRX 时自动使用 `removeLiquidityETH`。 +--- -### V3 流动性 -* **铸造仓位**：铸造新的 V3 集中流动性仓位，支持自动计算功能。 -* **增加流动性**：为已有 V3 仓位增加流动性。 -* **减少流动性**：减少已有 V3 仓位的流动性。 -* **收取手续费**：收取 V3 仓位累积的手续费。 +## 安全注意事项 -### V4 流动性 -* **铸造仓位**：铸造新的 V4 集中流动性仓位，支持 Permit2 授权。 -* **增加流动性**：增加已有 V4 仓位的流动性。 -* **减少流动性**：减少已有 V4 仓位的流动性。 -* **收取手续费**：收取 V4 仓位累积的手续费。 +:::warning +在开始使用之前，有几条安全原则值得牢记——DeFi 操作直接涉及链上资产，错误操作无法撤回： -### 钱包与安全 -* **灵活配置**：支持通过 `TRON_PRIVATE_KEY` 或 `TRON_MNEMONIC` 进行配置。 -* **Agent Wallet**：可选 Agent Wallet 提供方以支持远程签名。 -* **多网络支持**：全面覆盖 Mainnet、Nile 和 Shasta，可配置 RPC 与 TronGrid API Key。 +- **切勿硬编码私钥**：不要将私钥或助记词直接写入配置文件，应通过系统环境变量或加密钱包管理。 +- **先在测试网验证**：任何兑换或流动性操作在主网执行前，先在 Nile 测试网上跑通。 +- **最小资金原则**：为 AI Agent 配置的钱包只存放执行任务所需的最低金额。 +- **注意授权风险**：代币授权（`approve`）操作要格外谨慎，避免授予无限额度。 +- **确认每笔交易**：AI 执行链上写操作前会展示交易详情请求确认，不要跳过这一步。 +::: -## 安全说明 +--- -- **私钥与助记词**：仅通过环境变量配置 `TRON_PRIVATE_KEY` 或 `TRON_MNEMONIC`，不要写死在代码或可能被提交的配置文件中。 -- **先用测试网**：在主网操作前请在 Nile 或 Shasta 上充分测试。 -- **最小权限**：为智能体配置的钱包仅保留完成任务所需的最低资金。 -- **审计**：生产使用前建议对服务端与集成方式做安全审计。 +## 下一步 +- 想用最快的速度体验一下？ → [快速开始](./QuickStart.md) +- 只需要查询链上数据？ → [官方云服务接入](./OfficialServerAccess.md) +- 需要代币兑换或流动性管理？ → [本地私有化部署](./LocalPrivatizedDeployment.md) +- 想了解全部 41 个工具？ → [完整能力清单](./ToolList.md) diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md index 6b08f744..bb1970e5 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md @@ -3,150 +3,422 @@ import TabItem from '@theme/TabItem'; # 本地私有化部署 -如果您需要执行转账、合约调用等写操作，必须在本地部署服务器。本地部署允许您安全地配置私钥，从而启用完整的交易功能。 +## 什么是本地私有化部署？ -## 环境要求 -- **Node.js** 20.0.0 或更高。 -- **npm**（或兼容的包管理器）。 -- 可选：**TronGrid API Key**，用于主网更高限流与稳定性。 +本地私有化部署是指在您自己的计算机上运行 SUN MCP Server 的完整实例。与依赖第三方服务不同，本地部署让您完全控制您的钱包、网络连接和数据隐私。 +这种模式特别适合需要执行 DeFi 操作的场景。通过配置钱包私钥或助记词，您可以解锁以下写入操作： -## 关键配置（环境变量） +- **Swap**：使用 Universal Router 进行自动路由交换 +- **流动性管理**：SunSwap V2/V3/V4 添加和移除流动性 +- **头寸管理**：SunSwap V3/V4 铸造、增加、减少头寸和收集费用 +- **合约交互**：通过 `sunswap_send_contract` 调用任意合约 -**安全**：不要在 MCP 配置文件（如 `claude_desktop_config.json` 或 `mcp.json`）中保存私钥或助记词，应在系统或 shell 中通过环境变量设置。 +:::info +无钱包配置下，SUN MCP Server 将以**只读模式**运行，允许查询链上数据但无法执行写入操作。 +::: -### 1. 网络与 API +--- -- **TRONGRID_API_KEY**（可选）：主网 RPC 使用的 TronGrid API Key，可降低限流、提高稳定性。 -- **TRON_RPC_URL**（可选）：覆盖 TRON RPC 基础地址；设置后替代当前网络的默认 fullNode/solidityNode/eventServer。 +## 开始之前 -### 2. 钱包（写操作） +### 环境要求 -**方式一：私钥** +| 项目 | 要求 | 说明 | +|------|------|------| +| Node.js | >= 20.0.0 | v20.0.0 或更高版本（[下载](https://nodejs.org/)） | +| npm | >= 10.0 | 通常与 Node.js 一起安装 | +| 操作系统 | Linux / macOS / Windows | 跨平台支持 | +| 磁盘空间 | >= 100 MB | 用于安装依赖 | +| 网络 | 互联网连接 | 与 TRON 网络通信 | + +### 安全原则 + +:::danger 重要安全提示 +1. **私钥保护**：永远不要将私钥提交到版本控制系统。使用 `.env` 文件并将其添加到 `.gitignore`。 +2. **权限管理**：确保 `.env` 文件的权限为 `600`（仅所有者可读）。 +3. **多钱包模式禁止**：同时配置多个钱包方式将触发错误。只能同时使用一种方式。 +4. **助记词用语**：在本文档中，"助记词"指的是 BIP-39 标准的 12 词或 24 词恢复短语。 +5. **主网谨慎**：在主网中使用实际资金前，请务必在测试网（Nile、Shasta）上充分测试。 +::: + +--- + +## 安装步骤 +### 第一步：配置钱包 + +钱包决定了 AI 助手以哪个身份执行链上操作。SUN MCP Server 支持三种钱包模式，若未配置任何钱包，服务器会自动以只读模式运行。 + +#### 有三种创建钱包的方式，请根据需要选择 + +| 特性 | Agent Wallet | 私钥 | 助记词 | +| :--- | :--- | :--- | :--- | +| 安全等级 | 高（加密存储） | 低（明文） | 低（明文） | +| 多钱包支持 | 是 | 否 | 否 | +| 运行时切换钱包 | 是 | 否 | 否 | +| 配置复杂度 | 中等 | 简单 | 简单 | +| 推荐场景 | 生产环境、较多资金 | 开发测试、少量资金 | 开发测试、少量资金 | + +#### 方式一：通过 Agent Wallet（推荐）创建钱包 + +这是最安全的方式。私钥加密存储在本地磁盘，不会以明文形式暴露在环境变量中。即使环境变量被泄露，攻击者仍需要加密的密钥库文件才能访问资金。 + +**安装并初始化 Agent Wallet：** ```bash -export TRON_PRIVATE_KEY="<你的私钥十六进制>" +# 安装 +npm install -g @bankofai/agent-wallet + +# 创建加密钱包 +agent-wallet start ``` +Agent Wallet 还支持**多钱包管理**——你可以创建多个钱包，在运行时通过 `select_wallet` 工具随时切换，非常适合需要在不同账户间操作的场景。 + +> 了解详细的安装和使用说明请参阅 [agent-wallet 文档](https://github.com/BofAI/agent-wallet/blob/main/doc/getting-started.md)。 -**方式二：助记词** +**设置环境变量：** ```bash -export TRON_MNEMONIC="词1 词2 ... 词12" -export TRON_ACCOUNT_INDEX="0" # 可选，默认 0 +# 添加到 ~/.zshrc 或 ~/.bashrc +export AGENT_WALLET_PASSWORD="<你的主密码>" + +# 可选：指定自定义钱包目录（默认：~/.agent-wallet） +export AGENT_WALLET_DIR="~/.agent-wallet" ``` -若两者都未设置且未提供 Agent Wallet 提供方，写类工具（转账、兑换、流动性）将报“无可用钱包”错误。 -## 安装 -1. **克隆并进入目录**： - ```shell - git clone https://github.com/BofAI/sun-mcp-server.git - cd sun-mcp-server - ``` -2. **安装与构建**： - ```shell - npm install && npm run build - ``` +#### 方式二：通过私钥导入钱包 + +通过环境变量直接提供私钥。配置最简单，但安全性较低。 -## 验证 -默认 stdio 模式： ```bash -# 运行测试 -npm test +# 添加到 ~/.zshrc 或 ~/.bashrc +export TRON_PRIVATE_KEY="<你的私钥十六进制值>" +``` + +私钥可以是带 `0x` 前缀或不带前缀的十六进制格式。 + +:::warning +在环境变量中使用明文私钥存在**真实的资金被盗风险**——环境变量可能通过 shell 历史记录、进程列表（`ps aux`）或日志文件泄露。**这类钱包只应存放少量资金**。 +::: + +#### 方式三：通过助记词导入钱包 + +通过 BIP-39 助记词进行 HD 钱包派生。 -# 启动服务（stdio） -npm start +```bash +# 添加到 ~/.zshrc 或 ~/.bashrc +export TRON_MNEMONIC="单词1 单词2 单词3 ... 单词12" + +# 可选：指定 HD 钱包派生索引（默认：0） +# 派生路径：m/44'/195'/0'/0/{index} +export TRON_ACCOUNT_INDEX="0" ``` -使用 HTTP（streamable-http）模式时： +:::warning +与私钥方式的安全风险相同。明文存储的助记词容易泄露，请只用于存放少量资金的开发/测试钱包。 +::: + + +--- + +### 第二步：配置网络（可选） + +#### TronGrid API Key + +TronGrid 是官方的 TRON RPC 提供商。使用 API Key 可以提高请求速率限制。 + +**获取 API Key：** + +1. 访问 [TronGrid 官方网站](https://www.trongrid.io) +2. 注册账户或登录 +3. 在控制台生成 API Key +4. 复制 API Key 到环境变量 + +**环境变量：** ```bash -npm start -- --transport streamable-http --host 127.0.0.1 --port 8080 --mcpPath /mcp +TRON_GRID_API_KEY=your_api_key_here ``` +:::info +如果不设置 `TRON_GRID_API_KEY`，SUN MCP Server 将使用公共端点，但可能受到速率限制。 +::: + + +--- + +### 第三步：安装服务器 + +#### 方式 A：npx 直接运行（推荐） + +最简单快捷的方式，无需安装或克隆。 + +**命令：** + +```bash +npx -y @bankofai/sun-mcp-server +``` + +**说明：** +- `npx` 会自动下载最新版本的 `@bankofai/sun-mcp-server` +- `-y` 标志自动确认提示 +- 首次运行可能需要几秒钟下载 + +**带环境变量运行：** + +```bash +TRON_NETWORK=nile TRON_GRID_API_KEY=your_api_key npx -y @bankofai/sun-mcp-server +``` + +#### 方式 B：从源码克隆 + +适合开发和自定义修改。 + +**步骤：** + +```bash +# 1. 克隆仓库 +git clone https://github.com/BofAI/sun-mcp-server.git +cd sun-mcp-server + +# 2. 安装依赖 +npm install + +# 3. 构建项目 +npm run build + +# 4. 运行服务器 +npx tsx src/index.ts +``` + +**或者全局安装：** + +```bash +npm install -g @bankofai/sun-mcp-server +sun-mcp-server +``` + +--- + +### 第四步：连接 AI 客户端 + +配置完成后，需要在 AI 客户端中添加 SUN MCP Server 的连接定义。 + +#### 找到配置文件 + +根据您使用的 AI 客户端，配置文件位置如下： + +| 客户端 | 配置文件路径 | +|--------|-------------| +| **Claude Desktop** | `~/.claude/resources/mcp/servers.json` | +| **Cursor** | `~/.cursor/extensions/mcp/servers.json` | +| **Claude Code (CLI)** | `~/.claude/mcp_servers.json` 或通过环境变量 | + +#### 添加服务器定义 + +选择与您的部署方式对应的选项卡： -## 客户端集成 -要将此服务器与 Claude Desktop、Cursor 等 MCP 客户端一起使用，您需要将其添加到您的配置文件中。 - + -编辑 `~/Library/Application Support/Claude/claude_desktop_config.json` （macOS）或您系统下的等效路径： +**Claude Desktop 配置：** + +在 `~/.claude/resources/mcp/servers.json` 中添加： ```json { "mcpServers": { - "sun-mcp-server": { + "sun": { "command": "npx", - "args": ["tsx", "/ABSOLUTE/PATH/TO/sun-mcp-server/src/index.ts"], + "args": ["-y", "@bankofai/sun-mcp-server"], "env": { - "TRON_PRIVATE_KEY": "YOUR_KEY_HERE (Or set in system env)", - "TRONGRID_API_KEY": "YOUR_KEY_HERE (Or set in system env)" - }, - "enabled": true + "AGENT_WALLET_PASSWORD": "your_secure_password", + "AGENT_WALLET_DIR": "~/.agent-wallet", + "TRON_GRID_API_KEY": "your_api_key", + "TRON_NETWORK": "nile" + } } } } ``` -若已在 shell 中配置钱包相关环境变量，可省略 `env` 中的私钥/助记词。 +**Claude Code (CLI) 配置：** + +```bash +export MCP_SERVERS='{"sun":{"command":"npx","args":["-y","@bankofai/sun-mcp-server"],"env":{"TRON_NETWORK":"nile","TRON_GRID_API_KEY":"your_api_key"}}}' +claude code +``` +**Cursor 配置：** +在 `~/.cursor/extensions/mcp/servers.json` 中添加： + +```json +{ + "mcpServers": { + "sun": { + "command": "npx", + "args": ["-y", "@bankofai/sun-mcp-server"], + "env": { + "TRON_NETWORK": "nile", + "TRON_GRID_API_KEY": "your_api_key" + } + } + } +} +``` - -在项目根目录的 `.cursor/mcp.json` 中配置： + + +适用于从源码运行的情况。 + +**Claude Desktop 配置：** + +在 `~/.claude/resources/mcp/servers.json` 中添加： ```json { - "servers": [ - { - "name": "sun-mcp-server", + "mcpServers": { + "sun": { "command": "npx", - "args": ["tsx", "/ABSOLUTE/PATH/TO/sun-mcp-server/src/index.ts"], + "args": ["tsx", "/path/to/sun-mcp-server/src/index.ts"], "env": { - "TRON_PRIVATE_KEY": "YOUR_KEY_HERE (Or set in system env)", - "TRONGRID_API_KEY": "YOUR_KEY_HERE (Or set in system env)" + "AGENT_WALLET_PASSWORD": "your_secure_password", + "TRON_GRID_API_KEY": "your_api_key", + "TRON_NETWORK": "nile" } } - ] + } } ``` - +**Cursor 配置：** + +在 `~/.cursor/extensions/mcp/servers.json` 中添加： + +```json +{ + "mcpServers": { + "sun": { + "command": "npx", + "args": ["tsx", "/path/to/sun-mcp-server/src/index.ts"], + "env": { + "TRON_NETWORK": "nile", + "TRON_GRID_API_KEY": "your_api_key" + } + } + } +} +``` - + -使用 HTTP 传输时，请求 MCP 接口需携带： + -- **Accept**：`application/json, text/event-stream` -- **Content-Type**：`application/json` +以 HTTP 服务器模式运行 SUN MCP Server，允许远程连接。 -示例（tools/call）： +**启动 HTTP 服务器：** ```bash -curl -X POST "您本地的 MCP URL" \ - -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" - } +sun-mcp-server --transport streamable-http --host 127.0.0.1 --port 8080 --mcpPath /mcp +``` + +**Claude Desktop 配置：** + +```json +{ + "mcpServers": { + "sun": { + "url": "http://127.0.0.1:8080/mcp" + } + } +} +``` + +**Cursor 配置：** + +```json +{ + "mcpServers": { + "sun": { + "url": "http://127.0.0.1:8080/mcp" } - }' + } +} ``` +:::warning +HTTP 模式适用于本地开发和测试。对于远程部署，请使用 HTTPS 和适当的身份验证。 +::: - \ No newline at end of file + + +:::tip 关于环境变量部分 +- **npx 运行**：环境变量在配置文件的 `"env"` 字段中设置，或直接在终端导出后运行。 +- **HTTP 模式**：启动 HTTP 服务器时，环境变量应在启动命令前导出： + +```bash +export TRON_NETWORK=nile +export TRON_GRID_API_KEY=your_api_key +sun-mcp-server --transport streamable-http --host 127.0.0.1 --port 8080 --mcpPath /mcp +``` + +- **重启生效**：修改配置后，需重启 AI 客户端使更改生效。 +::: + +--- + +### 第五步：验证接入是否成功 + +启动 AI 客户端后，应该能看到 SUN MCP Server 的工具列表。进行以下测试以确认配置正确： + +#### 查询测试 + +在聊天中尝试以下命令： + +``` +查询 TRON 主网的区块高度 +``` + +期望返回当前区块号。 + +#### 如果在测试网中 + +如果您配置为使用 Nile 测试网： + +```bash +TRON_NETWORK=nile +``` + +可以在 [TRON Nile 水龙头](https://nile.trongrid.io/join) 获取测试 TRX，然后尝试以下操作： + +- 查询测试账户余额 +- 执行一次测试交换（如果已配置钱包） +- 检查交易历史 + +:::info 诊断步骤 +如果遇到连接问题： + +1. **检查网络连接**：确保能访问 TRON 网络端点 +2. **验证 API Key**：如果配置了 `TRON_GRID_API_KEY`，确保其有效 +3. **查看日志**：运行服务器时查看控制台输出，寻找错误信息 +4. **测试网络**：尝试切换到测试网（Nile）排除网络问题 +::: + +--- + +## 下一步 + +现在您已成功部署 SUN MCP Server！接下来可以： + +1. **查看完整能力清单**：浏览 [完整能力清单](./ToolList.md) 了解所有可用操作 +2. **解决常见问题**：查阅 [常见问题解答](./FAQ.md) 获取帮助 + +:::success +恭喜！您现在可以通过 AI 客户端与 TRON 区块链进行交互。开始探索 DeFi 的无限可能吧！ +::: diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md index 4f74f3e2..5c3a676d 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md @@ -1,28 +1,72 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# 官方服务接入 -对于仅需要读取区块链数据（不涉及交易）的用户，可以直接连接到官方托管的实例。**注意：官方服务仅提供只读接口，不支持转账或合约写入等操作。** +# 官方云服务接入 -## 服务信息 -| 环境 | URL | -| :--- | :--- | -| 生产环境 | [https://sun-mcp-server.bankofai.io/mcp](https://sun-mcp-server.bankofai.io/mcp)| +## 什么是官方云服务？ + +官方云服务是由 **BANK OF AI** 托管的 SUN MCP Server 实例，用于为 AI 客户端提供 **SunSwap 链上数据的只读查询能力**。 + +如果你想让 AI 助手查询 SunSwap 上的代币价格、池子 APY、协议交易量，或者分析某个地址的流动性持仓——这些都是只读操作，通过官方云服务即可完成，不需要在本地安装任何东西，也不需要提供任何钱包凭证。 + +**官方云服务的核心作用，就是将基础设施工作全部托管。** 你只需要在 AI 客户端的配置中添加一行服务地址，即可开始与 SunSwap 对话。 + +### 使用官方云服务的主要优点 + +**1. 无需任何本地安装** + +不用安装 Node.js、不用克隆仓库、不用运行构建命令。只需在配置文件中添加一段 JSON，重启 AI 客户端，即可使用。整个过程通常不超过 2 分钟。 + +**2. 无私钥暴露风险** + +由于云服务是只读的，你完全不需要提供任何钱包私钥或助记词。这从根本上消除了密钥泄露的风险。在团队协作场景中尤为方便——任何成员都可以直接接入，不存在密钥分发和管理的问题。 + +**3. 官方维护与持续升级** + +云服务始终运行最新稳定版本，包括 SunSwap 协议更新的适配和 SUN.IO API 的同步。你无需关心版本号，也不需要手动重新构建。 + +**4. 覆盖大量实用场景** + +查询代币价格和兑换报价、分析池子数据和 APY、获取协议统计和历史指标、查看用户流动性持仓——这些日常最常用的 DeFi 数据查询，通过云服务全部可以完成。只有当你需要实际执行兑换或管理流动性时，才需要切换到[本地私有化部署](./LocalPrivatizedDeployment.md)。 + +> 简单来说：**官方云服务就像 SunSwap 的"只读数据网关"**，AI 客户端只需要知道服务地址，就可以查询 SunSwap 上的一切公开数据。 + +:::warning 重要说明 +官方云服务仅提供**只读访问**。**不支持**代币兑换、添加/移除流动性以及任何其他链上写操作。如需完整功能，请使用[本地私有化部署](./LocalPrivatizedDeployment.md)。 +::: + +--- + +## 如何接入官方云服务？ -- **传输协议**： - - **stdio**：默认；用于本地 MCP 客户端（如 Claude Desktop、Cursor）。 - - **streamable-http**：HTTP + 服务端推送事件，供远程客户端使用；可配置 host、port、path。 -- **模式**：只读（写入工具已禁用） +要接入官方云服务，只需在 AI 客户端配置中添加以下 MCP 服务地址： +**`https://sun-mcp-server.bankofai.io/mcp`** -**安全**：不要在 MCP 配置文件（如 `claude_desktop_config.json` 或 `mcp.json`）中保存私钥或助记词，应在系统或 shell 中通过环境变量设置。 +> 注意：这是一个 MCP 协议端点，不是网页地址。在浏览器中直接打开不会显示任何内容。 +官方云服务支持**两种使用模式**： -## 客户端集成 +| 模式 | 限速 |说明 | +| :--- | :--- | :--- | +| **无 API Key（默认）** |100,000 Requests / Day |即开即用，适合入门体验和低频查询 | +| **带 TronGrid API Key** |500,000 Requests / Day |更高的请求频率上限，适合频繁查询和生产级使用 | + +如果你的使用场景涉及频繁查询主网数据，建议在 [trongrid.io](https://www.trongrid.io/) 注册一个免费的 TronGrid API Key，配置到请求头中以获得更高的吞吐量和稳定性。 + +--- + +## 客户端配置 +配置文件路径： +- **macOS**：`~/Library/Application Support/Claude/claude_desktop_config.json` +- **Windows**：`%APPDATA%\Claude\claude_desktop_config.json` + +**基础配置（不含 API Key）**： + ```json { "mcpServers": { @@ -37,7 +81,7 @@ import TabItem from '@theme/TabItem'; } ``` -带 TronGrid API Key： +**含 TronGrid API Key 的配置**： ```json { @@ -55,16 +99,18 @@ import TabItem from '@theme/TabItem'; } ``` +将 `` 替换为你的实际 TronGrid API Key。 + -CLI 命令： +**命令行添加**： -```shell +```bash claude mcp add --transport http sun-mcp-server https://sun-mcp-server.bankofai.io/mcp ``` -或在项目根目录添加 `.mcp.json`： +**或在项目根目录添加 `.mcp.json`**： ```json { @@ -78,44 +124,128 @@ claude mcp add --transport http sun-mcp-server https://sun-mcp-server.bankofai.i ``` + + +在项目根目录添加 `.cursor/mcp.json`： + +```json +{ + "mcpServers": { + "sun-mcp-server": { + "url": "https://sun-mcp-server.bankofai.io/mcp" + } + } +} +``` + + + - +如果你想将 SUN MCP Server 集成到自己的应用中，可以通过标准 HTTP 请求调用。 -使用 HTTP 传输时，请求 MCP 接口需携带： +**第一步：初始化连接** -- **Accept**：`application/json, text/event-stream` -- **Content-Type**：`application/json` +```bash +curl -X POST https://sun-mcp-server.bankofai.io/mcp \ + -H "Content-Type: application/json" \ + -H "Accept: application/json, text/event-stream" \ + -d '{ + "jsonrpc": "2.0", + "method": "initialize", + "params": { + "protocolVersion": "2025-03-26", + "capabilities": {}, + "clientInfo": {"name": "my-client", "version": "1.0"} + }, + "id": 1 + }' +``` + +响应中会包含 `mcp-session-id` 请求头，后续请求需要用到它。 + +**第二步：调用工具** -示例（tools/call）： +使用第一步获得的 `mcp-session-id`： ```bash -curl -X POST "https://sun-mcp-server.bankofai.io/mcp" \ +curl -X POST https://sun-mcp-server.bankofai.io/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ + -H "mcp-session-id: " \ -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" - } - } + "name": "getPrice", + "arguments": {"tokenAddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"} + }, + "id": 2 + }' +``` + +**第三步：查看可用工具列表** + +```bash +curl -X POST https://sun-mcp-server.bankofai.io/mcp \ + -H "Content-Type: application/json" \ + -H "Accept: application/json, text/event-stream" \ + -H "mcp-session-id: " \ + -d '{ + "jsonrpc": "2.0", + "method": "tools/list", + "params": {}, + "id": 3 }' ``` +:::info Session 管理 +- 每次 `initialize` 会创建一个新 Session +- Session 在 30 分钟无活动后自动过期 +- 可用 `DELETE /mcp`（携带 `mcp-session-id` 请求头）显式关闭 Session +::: + +--- +## 验证接入是否成功 +配置完成后，**完全退出并重启** AI 客户端，然后输入以下测试问法： + +``` +查一下 SunSwap 上 USDT 和 TRX 的当前价格 +``` + +如果收到正常响应，说明接入成功。 + +如遇到问题，请先确认： +1. Node.js 版本 >= 20.0.0（运行 `node --version` 检查） +2. 网络能正常访问 `sun-mcp-server.bankofai.io` +3. AI 客户端已完全退出重启（不是刷新） + +--- + +## 可用能力一览 + +通过官方云服务连接时，可以使用全部**只读**工具，包括： + +| 分类 | 示例能力 | +| :--- | :--- | +| **代币价格** | 按地址或符号查询代币实时价格 | +| **兑换报价** | 通过智能路由获取精确输入的最优兑换报价 | +| **代币信息** | 按地址、协议或关键字搜索代币信息 | +| **池子数据** | 池子列表、APY 排行、交易量历史、流动性历史 | +| **持仓查询** | 用户流动性持仓、tick 级别持仓详情 | +| **协议统计** | 交易量、用户数、交易笔数、池子数量历史 | +| **矿池信息** | 矿池列表、矿池交易记录、用户矿池持仓 | +| **合约读取** | 调用任意 TRON 合约的 view/pure 函数 | +完整能力清单请参阅 [完整能力清单](./ToolList.md)。 +--- +## 下一步 +- 需要代币兑换或流动性管理？ → [本地私有化部署](./LocalPrivatizedDeployment.md) +- 想看所有可用工具的详细说明？ → [完整能力清单](./ToolList.md) diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/QuickStart.md new file mode 100644 index 00000000..0d20a5e0 --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/QuickStart.md @@ -0,0 +1,119 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# 快速开始 + +这个页面的目标很简单：**让你在 1 分钟内完成接入，发起第一次 DeFi 查询。** + +我们会使用[官方云服务](./OfficialServerAccess.md)来完成这次快速体验。云服务是只读的，无需钱包，立即可用。 + +--- + +## 准备工作 + +在开始之前，请确保你已经有： + +1. **Node.js** >= 20.0.0（[下载链接](https://nodejs.org/)） +2. **MCP 客户端**：所有支持 MCP 的 AI 客户端。例如 [Claude Desktop](https://claude.ai/download)、[Claude Code](https://docs.anthropic.com/en/docs/claude-code) 或 [Cursor](https://cursor.sh) 。 + +--- + +## 添加配置 + +根据你使用的工具选择对应的配置方式： + + + + +1. 打开 Claude Desktop 的配置文件： + - **macOS**：`~/Library/Application Support/Claude/claude_desktop_config.json` + - **Windows**：`%APPDATA%\Claude\claude_desktop_config.json` + +2. 在 `mcpServers` 部分添加以下配置： + +```json +{ + "mcpServers": { + "sun-mcp-server": { + "command": "npx", + "args": ["mcp-remote", "https://sun-mcp-server.bankofai.io/mcp"] + } + } +} +``` + +3. 保存文件并重启 Claude Desktop。 + + + + + +在终端中运行以下命令添加 SUN MCP Server： + +```bash +claude mcp add --transport http sun-mcp-server https://sun-mcp-server.bankofai.io/mcp +``` + + + + + +1. 打开 Cursor 的配置文件：`.cursor/mcp.json` + +2. 在配置中添加： + +```json +{ + "mcpServers": { + "sun-mcp-server": { + "command": "npx", + "args": ["mcp-remote", "https://sun-mcp-server.bankofai.io/mcp"] + } + } +} +``` + +3. 保存文件并重启 Cursor。 + + + + +--- + +## 重启并测试 + +完成配置后，重启你的 MCP 客户端。然后在对话中尝试以下查询： + +``` +查一下 SunSwap 上 USDT 和 TRX 的当前价格 +``` + +:::info 关于云服务 +我们提供的官方云服务是**只读的**，适合查询数据和分析。如果你需要执行链上交易、部署合约等写操作，请查看[本地私有化部署](./LocalPrivatizedDeployment.md)。 +::: + +--- + +## 继续探索 + +以下是一些常见的 DeFi 查询示例： + +| 操作 | 示例提示 | +|------|--------| +| **价格查询** | 查询 USDT/TRX 的实时价格 | +| **流动性池数据** | 获取 SunSwap 中 TRX-USDC 交易对的池信息 | +| **头寸查询** | 查看地址 TR... 在 SunSwap 中的所有流动性头寸 | +| **交易报价** | 获取交换 1000 USDT 为 TRX 的报价 | +| **协议统计** | 获取 SunSwap 的 TVL、24 小时交易量等统计数据 | + +--- + +## 下一步 + +- **[本地私有化部署](./LocalPrivatizedDeployment.md)** - 学习如何在本地运行 SUN MCP Server 并进行写操作 +- **[官方服务器访问](./OfficialServerAccess.md)** - 了解官方云服务的详细信息 +- **[完成能力清单](./ToolList.md)** - 查看所有可用的工具和功能 + +--- + +祝你使用愉快！如有问题，欢迎反馈。 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/ToolList.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/ToolList.md new file mode 100644 index 00000000..be658d11 --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/ToolList.md @@ -0,0 +1,354 @@ +# 完整能力清单 + +SUN MCP Server 提供 **41 个工具**（18 个自定义 DeFi 工具 + 23 个 SUN.IO OpenAPI 衍生工具）。 + +## 先了解两个概念 + +:::info 读取 vs 写入 +- **读取工具**：只查询数据，不影响链上状态。在云服务和本地部署中均可使用。 +- **写入工具**：会修改链上状态（兑换、流动性操作等）。仅在本地部署且配置了钱包后才可使用。 +::: + +:::tip network 参数 +大多数工具都有可选的 `network` 参数，用于指定交互的网络环境。默认使用主网配置，也可切换至测试网。 +::: + +--- + +## 自定义工具（共 18 个） + +### 钱包与余额 + +| 工具名 | 功能描述 | 工具类型 | 必需参数 | 可选参数 | +|--------|---------|---------|---------|---------| +| `sunswap_get_wallet_address` | 获取当前活跃的 TRON 钱包地址 | 读取 | - | `network` | +| `sunswap_get_balances` | 查询 TRX 和 TRC20 代币余额 | 读取 | `tokens` | `network`, `ownerAddress` | + +**试试这样说：** +- "查询我的 TRON 钱包地址" +- "查看我 USDT 和 SUNFLARE 的余额" +- "获取我在测试网上的 TRX 余额" + +--- + +### 价格与报价 + +| 工具名 | 功能描述 | 工具类型 | 必需参数 | 可选参数 | +|--------|---------|---------|---------|---------| +| `sunswap_get_token_price` | 获取代币价格（通过 SUN.IO API） | 读取 | `tokenAddress` 或 `symbol` | `network` | +| `sunswap_quote_exact_input` | 精确输入金额的兑换报价（智能路由） | 读取 | `routerAddress`, `args` | `network`, `functionName`, `abi` | + +**试试这样说：** +- "SUNFLARE 现在的价格是多少？" +- "我想兑换 1000 USDT 换 SUNFLARE，会得到多少？" +- "在测试网上查询 USDC 的当前价格" + +--- + +### 兑换 + +| 工具名 | 功能描述 | 工具类型 | 必需参数 | 可选参数 | +|--------|---------|---------|---------|---------| +| `sunswap_swap` | 执行通用路由器兑换（支持自动路由 + Permit2） | 写入 | `tokenIn`, `tokenOut`, `amountIn` | `network`, `slippage` | +| `sunswap_swap_exact_input` | 精确输入兑换（智能路由器） | 写入 | `routerAddress`, `args` | `network`, `functionName`, `value`, `abi` | + +**试试这样说：** +- "我想用 500 USDT 兑换 SUNFLARE，滑点 1%" +- "执行 1000 USDC 换 TRX 的交易" +- "帮我兑换 SUNFLARE 到 USDT，尽量少于 2 秒内完成" + +:::caution 钱包要求 +兑换工具需要本地部署 SUN MCP Server 并配置钱包私钥。 +::: + +--- + +### V2 流动性 + +| 工具名 | 功能描述 | 工具类型 | 必需参数 | 可选参数 | +|--------|---------|---------|---------|---------| +| `sunswap_v2_add_liquidity` | 添加 V2 流动性（自动 TRX/WTRX 处理） | 写入 | `routerAddress`, `tokenA`, `tokenB`, `amountADesired`, `amountBDesired` | `network`, `amountAMin`, `amountBMin`, `to`, `deadline`, `abi` | +| `sunswap_v2_remove_liquidity` | 移除 V2 流动性 | 写入 | `routerAddress`, `tokenA`, `tokenB`, `liquidity` | `network`, `amountAMin`, `amountBMin`, `to`, `deadline`, `abi` | + +**试试这样说：** +- "我想添加 1000 USDT 和等量的 SUNFLARE 到 V2 流动性池" +- "移除我在 USDC-TRX 池中的 50% 流动性" +- "添加 V2 流动性，USDT 最少 950，SUNFLARE 最少 9500" + +:::info 自动处理 +当配对涉及 TRX 时，工具会自动转换为 WTRX。 +::: + +--- + +### V3 流动性 + +| 工具名 | 功能描述 | 工具类型 | 必需参数 | 可选参数 | +|--------|---------|---------|---------|---------| +| `sunswap_v3_mint_position` | 创建 V3 集中流动性头寸 | 写入 | `positionManagerAddress`, `token0`, `token1` | `network`, `fee`, `tickLower`, `tickUpper`, `amount0Desired`, `amount1Desired`, `amount0Min`, `amount1Min`, `recipient`, `deadline`, `abi` | +| `sunswap_v3_increase_liquidity` | 增加 V3 流动性 | 写入 | `positionManagerAddress`, `tokenId` | `network`, `token0`, `token1`, `fee`, `amount0Desired`, `amount1Desired`, `amount0Min`, `amount1Min`, `deadline` | +| `sunswap_v3_decrease_liquidity` | 减少 V3 流动性 | 写入 | `positionManagerAddress`, `tokenId`, `liquidity` | `network`, `token0`, `token1`, `fee`, `amount0Min`, `amount1Min`, `deadline` | +| `sunswap_v3_collect` | 收取 V3 费用 | 写入 | `positionManagerAddress`, `tokenId` | `network`, `recipient`, `abi` | + +**试试这样说：** +- "帮我在 USDT-SUNFLARE 的 V3 0.3% 费率池中创建流动性，范围 ±50 ticks" +- "增加我的 V3 头寸 #12345，再添加 1000 USDT" +- "从我的 V3 头寸中收取费用" +- "减少 V3 头寸的流动性至 50%" + +:::tip 自动计算 +创建新头寸时，系统自动计算 tick 范围（±50×tickSpacing）和单边输入最优量。 +::: + +--- + +### V4 流动性 + +| 工具名 | 功能描述 | 工具类型 | 必需参数 | 可选参数 | +|--------|---------|---------|---------|---------| +| `sunswap_v4_mint_position` | 创建 V4 头寸（支持 Permit2） | 写入 | `token0`, `token1` | `network`, `fee`, `tickLower`, `tickUpper`, `amount0Desired`, `amount1Desired`, `slippage`, `recipient`, `deadline`, `sqrtPriceX96`, `createPoolIfNeeded` | +| `sunswap_v4_increase_liquidity` | 增加 V4 流动性（支持 Permit2） | 写入 | `tokenId`, `token0`, `token1` | `network`, `fee`, `amount0Desired`, `amount1Desired`, `slippage`, `deadline` | +| `sunswap_v4_decrease_liquidity` | 减少 V4 流动性 | 写入 | `tokenId`, `liquidity`, `token0`, `token1` | `network`, `fee`, `amount0Min`, `amount1Min`, `slippage`, `deadline` | +| `sunswap_v4_collect` | 收取 V4 费用 | 写入 | `tokenId` | `network`, `token0`, `token1`, `fee`, `deadline` | + +**试试这样说：** +- "在 V4 中创建 USDC-SUNFLARE 的流动性头寸，滑点 5%" +- "增加我的 V4 头寸 #67890，再注入 5000 USDC" +- "从 V4 头寸中收取所有累积费用" +- "减少 V4 流动性，确保滑点在 3% 以内" + +:::info Permit2 支持 +V4 工具原生支持 Permit2 签名授权，提升用户体验。 +::: + +--- + +### 合约交互 + +| 工具名 | 功能描述 | 工具类型 | 必需参数 | 可选参数 | +|--------|---------|---------|---------|---------| +| `sunswap_read_contract` | 从 TRON 智能合约读取数据（view/pure） | 读取 | `address`, `functionName` | `network`, `args`, `abi` | +| `sunswap_send_contract` | 发送状态改变的合约交易 | 写入 | `address`, `functionName` | `network`, `args`, `value`, `abi` | + +**试试这样说：** +- "查询 SUNFLARE 合约的总供应量" +- "读取我在流动性合约中的余额" +- "调用合约函数更新矿池参数" +- "向合约发送 0.1 TRX 并执行特定函数" + +:::caution ABI 要求 +若不提供 ABI，系统将尝试从 TronScan 获取合约 ABI。 +::: + +--- + +## SUN.IO OpenAPI 衍生工具（共 23 个） + +### 交易 + +| 工具名 | 功能描述 | 必需参数 | 可选参数 | +|--------|---------|---------|---------| +| `scanTransactions` | 扫描 DEX 交易 | - | `protocol`, `token`, `pool`, `type`, `timeRange` | +| `getFarmTransactions` | 扫描挖矿池交易 | `farmAddress` | - | + +**试试这样说：** +- "查看 SUN 协议过去 24 小时的交易" +- "查询 SUNFLARE-USDT 池的所有交易" +- "获取最近 7 天的交易数据" + +--- + +### 代币 + +| 工具名 | 功能描述 | 必需参数 | 可选参数 | +|--------|---------|---------|---------| +| `getTokens` | 按地址或协议获取代币 | - | `address`, `protocol` | +| `searchTokens` | 模糊搜索代币 | `keyword` | - | +| `getPrice` | 按地址获取代币价格 | `tokenAddress` | - | + +**试试这样说：** +- "搜索 'SUNFLARE' 代币" +- "获取地址 `TR7NHqjeKQxGTCi8q282JHJC8YXQFg...` 的代币信息" +- "查询 USDT 在 SUN 协议中的价格" + +--- + +### 协议 + +| 工具名 | 功能描述 | 必需参数 | 可选参数 | +|--------|---------|---------|---------| +| `getProtocol` | 协议快照数据 | - | - | +| `getVolHistory` | 协议成交量历史 | - | - | +| `getLiqHistory` | 协议流动性历史 | - | - | +| `getUsersCountHistory` | 协议用户数历史 | - | - | +| `getTransactionsHistory` | 协议交易数历史 | - | - | +| `getPoolsCountHistory` | 协议矿池数历史 | - | - | + +**试试这样说：** +- "获取 SUN 协议的最新快照" +- "查看过去 30 天的成交量趋势" +- "获取协议用户数增长情况" + +--- + +### 价格 + +| 工具名 | 功能描述 | 必需参数 | 可选参数 | +|--------|---------|---------|---------| +| `getPrice` | 代币价格查询 | `tokenAddress` | - | + +**试试这样说：** +- "获取 SUNFLARE 代币的实时价格" + +--- + +### 持仓 + +| 工具名 | 功能描述 | 必需参数 | 可选参数 | +|--------|---------|---------|---------| +| `getUserPositions` | 用户流动性头寸 | `userAddress` | - | +| `getPoolUserPositionTick` | 矿池用户 Tick 级别头寸详情 | `poolAddress`, `userAddress` | - | +| `getFarmPositions` | 用户挖矿头寸 | `userAddress` | - | + +**试试这样说：** +- "查看我所有的流动性头寸" +- "获取我在 USDT-SUNFLARE 池中的 Tick 详情" +- "查询我的挖矿收益头寸" + +--- + +### 池子 + +| 工具名 | 功能描述 | 必需参数 | 可选参数 | +|--------|---------|---------|---------| +| `getPools` | 获取矿池 | - | `address`, `token`, `protocol` | +| `searchPools` | 搜索矿池 | `keyword` | - | +| `searchCountPools` | 矿池搜索计数 | `keyword` | - | +| `getTopApyPoolList` | 获取最高 APY 矿池列表 | - | `limit`, `offset` | +| `getPoolHooks` | 矿池钩子（Hooks） | `poolAddress` | - | +| `getPoolVolHistory` | 矿池成交量历史 | `poolAddress` | - | +| `getPoolLiqHistory` | 矿池流动性历史 | `poolAddress` | - | + +**试试这样说：** +- "获取 SUNFLARE-USDT 池的详细信息" +- "查找最高 APY 的前 10 个矿池" +- "获取 USDC-TRX 池的成交量历史" +- "查询矿池使用的所有 Hooks" + +--- + +### 交易对 + +| 工具名 | 功能描述 | 必需参数 | 可选参数 | +|--------|---------|---------|---------| +| `getPairsFromEntity` | 代币交易对查询 | - | `token0`, `token1` | + +**试试这样说：** +- "获取 SUNFLARE 和 USDT 之间的交易对信息" +- "查询所有包含 USDC 的交易对" + +--- + +### 矿池 + +| 工具名 | 功能描述 | 必需参数 | 可选参数 | +|--------|---------|---------|---------| +| `getFarms` | 挖矿池列表 | - | - | + +**试试这样说：** +- "列出所有可用的挖矿池" +- "查询当前的挖矿奖励情况" + +--- + +## 自动计算特性 + +SUN MCP Server 的多个工具内置了智能自动计算功能，旨在简化用户交互： + +### V3 流动性自动计算 + +**`sunswap_v3_mint_position` 自动特性：** + +| 特性 | 说明 | 使用场景 | +|------|------|---------| +| **默认费率** | 若未指定 `fee`，系统自动使用 `3000`（0.3%） | 快速创建标准流动性头寸 | +| **Tick 范围计算** | 自动设置 `tickLower` 和 `tickUpper` 为 `±50 × tickSpacing` | 无需手动计算复杂数学，直接获得合理范围 | +| **单边输入处理** | 可只指定一种代币金额，系统自动计算另一种代币所需金额 | 简化多币种流动性部署 | + +**示例：** +``` +请求：在 USDT-SUNFLARE 池中创建 V3 头寸，注入 1000 USDT +系统自动： + - 设定费率为 3000（0.3%） + - 计算 ±50 个 tick 范围 + - 根据当前价格，计算所需 SUNFLARE 数量 + - 一次性提交多币种授权和交易 +``` + +### V4 流动性自动计算 + +**`sunswap_v4_mint_position` 自动特性：** + +| 特性 | 说明 | 使用场景 | +|------|------|---------| +| **Tick 范围计算** | 自动设置 `tickLower` 和 `tickUpper` 为 `±100 × tickSpacing` | V4 更灵活的范围配置 | +| **默认滑点** | 若未指定 `slippage`，系统自动使用 `5%` | 保护用户免受价格波动影响 | +| **Permit2 授权** | 原生支持 Permit2 签名流程，无需多次批准 | 改善用户体验，一次签名完成所有授权 | +| **动态池创建** | 若池不存在，`createPoolIfNeeded` 可自动创建新池 | 为新交易对快速建立流动性 | + +**示例：** +``` +请求：在 V4 中创建 USDC-SUNFLARE 头寸，滑点 3% +系统自动： + - 计算 ±100 个 tick 范围 + - 使用 Permit2 签名授权 + - 若池不存在，创建新池 + - 根据当前价格计算最优输入比例 +``` + +### 智能兑换路由 + +**`sunswap_swap` 自动特性：** + +| 特性 | 说明 | 使用场景 | +|------|------|---------| +| **多路由优化** | 自动查找最优兑换路径，支持直接交易对及多跳路由 | 获取最佳价格 | +| **Permit2 集成** | 无需预先批准代币，一次签名完成授权和兑换 | 改善用户流程 | + +**示例：** +``` +请求：1000 USDT 换 SUNFLARE，滑点 1% +系统自动： + - 评估直接 USDT-SUNFLARE 池 + - 评估 USDT → 中间币 → SUNFLARE 路由 + - 选择最优路径 + - 使用 Permit2 一次签名完成授权和交易 + - 确保滑点不超过 1% +``` + +### 关键参数说明 + +| 参数 | 默认值 | 何时自动计算 | +|------|--------|-----------| +| `fee`（V3） | 3000 | 未提供时 | +| `tickLower`, `tickUpper`（V3） | ±50×tickSpacing | 未提供时 | +| `tickLower`, `tickUpper`（V4） | ±100×tickSpacing | 未提供时 | +| `slippage`（V4） | 5% | 未提供时 | +| 对方代币金额 | 根据当前价格计算 | 只指定一种代币时 | + +:::tip 最佳实践 +虽然大多数参数已自动计算，但在关键操作（如添加大额流动性）时，建议主动指定参数以获得更高的控制精度。 +::: + +--- + +## 快速参考 + +**需要查询数据？** 使用读取工具：`get_*`, `search_*`, `scan*` 系列。 + +**需要执行交易？** 使用写入工具：`swap`, `mint`, `add`, `remove`, `collect`, `send_contract` 系列。 + +**不确定参数？** 工具会自动计算合理的默认值，或在必要时提示您补充信息。 + +**想了解更多？** 查看 [SUN MCP Server 主文档](../README.md) 或 [API 参考](../API-Reference.md)。 + diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/API.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/API.md deleted file mode 100644 index cfcddd27..00000000 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/API.md +++ /dev/null @@ -1,216 +0,0 @@ -# API 参考 - -## 工具（共 95 个） - -### 钱包与地址 - -| 工具名称 | 描述 | 关键参数 | 模式 | -| :-- | :-- | :-- | :-- | -| `get_wallet_address` | 获取已配置钱包的地址。 | - | 读取 | -| `list_wallets` | 列出所有可用钱包。 | - | 读取 | -| `select_wallet` | 在运行时切换活跃钱包。 | `walletId` | 写入 | -| `sign_message` | 使用已配置的钱包签署任意消息。 | `message` | 写入 | -| `convert_address` | 在 Hex 和 Base58 格式之间转换地址。 | `address` | 读取 | - -### 网络与链 - -| 工具名称 | 描述 | 关键参数 | 模式 | -| :-- | :-- | :-- | :-- | -| `get_chain_info` | 获取当前区块号和链 ID。 | `network` | 读取 | -| `get_chain_parameters` | 获取当前能量和带宽单价。 | `network` | 读取 | -| `get_supported_networks` | 列出所有支持的 TRON 网络。 | - | 读取 | - -### 区块 - -| 工具名称 | 描述 | 关键参数 | 模式 | -| :-- | :-- | :-- | :-- | -| `get_block` | 按区块号或哈希获取区块详情。 | `blockIdentifier`, `network` | 读取 | -| `get_latest_block` | 获取最新区块。 | `network` | 读取 | - -### 交易 - -| 工具名称 | 描述 | 关键参数 | 模式 | -| :-- | :-- | :-- | :-- | -| `get_transaction` | 按哈希获取交易详情。 | `txHash`, `network` | 读取 | -| `get_transaction_info` | 获取交易收据，包括资源使用情况。 | `txHash`, `network` | 读取 | - -### 余额 - -| 工具名称 | 描述 | 关键参数 | 模式 | -| :-- | :-- | :-- | :-- | -| `get_balance` | 获取地址的 TRX 余额。 | `address`, `network` | 读取 | -| `get_token_balance` | 获取地址的 TRC20 代币余额。 | `address`, `tokenAddress`, `network` | 读取 | - -### 转账 - -| 工具名称 | 描述 | 关键参数 | 模式 | -| :-- | :-- | :-- | :-- | -| `transfer_trx` | 向指定地址转账 TRX。 | `to`, `amount`, `network` | 写入 | -| `transfer_trc20` | 向指定地址转账 TRC20 代币。 | `tokenAddress`, `to`, `amount`, `network` | 写入 | - -### 智能合约 - -| 工具名称 | 描述 | 关键参数 | 模式 | -| :-- | :-- | :-- | :-- | -| `read_contract` | 调用智能合约的只读函数。 | `contractAddress`, `functionName`, `args`, `abi`, `network` | 读取 | -| `write_contract` | 执行智能合约的状态变更函数。 | `contractAddress`, `functionName`, `args`, `abi`, `value`, `network` | 写入 | -| `deploy_contract` | 将智能合约部署到网络。 | `abi`, `bytecode`, `args`, `name`, `network`, `feeLimit` | 写入 | -| `estimate_energy` | 估算合约调用的能量消耗。 | `address`, `functionName`, `args`, `abi`, `network` | 读取 | -| `multicall` | 在单次批量中执行多个只读调用。 | `calls`, `network`, `multicallAddress`, `version` | 读取 | -| `get_contract` | 获取合约原始元数据（ABI 和字节码）。 | `contractAddress`, `network` | 读取 | -| `get_contract_info` | 获取合约高级信息。 | `contractAddress`, `network` | 读取 | -| `fetch_contract_abi` | 从链上获取合约 ABI。 | `contractAddress`, `network` | 读取 | -| `update_contract_setting` | 更新合约的 consume_user_resource_percent。 | `contractAddress`, `consumeUserResourcePercent`, `network` | 写入 | -| `update_energy_limit` | 更新合约的 originEnergyLimit。 | `contractAddress`, `originEnergyLimit`, `network` | 写入 | -| `clear_abi` | 清除合约的链上 ABI 元数据。 | `contractAddress`, `network` | 写入 | - -### 账户管理 - -| 工具名称 | 描述 | 关键参数 | 模式 | -| :-- | :-- | :-- | :-- | -| `get_account` | 获取完整账户信息（余额、资源、权限）。 | `address`, `network` | 读取 | -| `get_account_balance` | 获取指定区块高度的 TRX 余额。 | `address`, `blockHash`, `blockNumber`, `network` | 读取 | -| `get_account_net` | 获取带宽资源信息。 | `address`, `network` | 读取 | -| `get_account_resource` | 获取能量、带宽、冻结余额和委托信息。 | `address`, `network` | 读取 | -| `get_delegated_resource` | 查询两个账户之间的委托资源。 | `fromAddress`, `toAddress`, `network` | 读取 | -| `get_delegated_resource_index` | 查询资源委托索引。 | `address`, `network` | 读取 | -| `generate_account` | 生成新的 TRON 账户。 | - | 读取 | -| `validate_address` | 验证 TRON 地址并检测格式。 | `address` | 读取 | -| `create_account` | 在网络上激活新账户。 | `address`, `network` | 写入 | -| `update_account` | 更新账户名称。 | `accountName`, `network` | 写入 | -| `account_permission_update` | 更新账户权限（多签）。 | `ownerPermission`, `activePermissions`, `witnessPermission`, `network` | 写入 | - -### 账户数据（TronGrid） - -| 工具名称 | 描述 | 关键参数 | 模式 | -| :-- | :-- | :-- | :-- | -| `get_account_info` | 从 TronGrid 获取综合账户信息。 | `address`, `network` | 读取 | -| `get_account_transactions` | 获取账户的交易历史。 | `address`, `limit`, `fingerprint`, `network` | 读取 | -| `get_account_trc20_transactions` | 获取 TRC20 转账历史。 | `address`, `contractAddress`, `limit`, `fingerprint`, `network` | 读取 | -| `get_account_internal_transactions` | 获取账户的内部交易。 | `address`, `limit`, `fingerprint`, `network` | 读取 | -| `get_account_trc20_balances` | 获取所有 TRC20 代币余额。 | `address`, `network` | 读取 | - -### 合约数据（TronGrid） - -| 工具名称 | 描述 | 关键参数 | 模式 | -| :-- | :-- | :-- | :-- | -| `get_contract_transactions` | 获取合约的交易历史。 | `address`, `limit`, `fingerprint`, `network` | 读取 | -| `get_contract_internal_transactions` | 获取合约的内部交易。 | `address`, `limit`, `fingerprint`, `network` | 读取 | -| `get_trc20_token_holders` | 获取 TRC20 合约的代币持有者列表。 | `address`, `limit`, `fingerprint`, `network` | 读取 | - -### 资源委托（Stake 2.0） - -| 工具名称 | 描述 | 关键参数 | 模式 | -| :-- | :-- | :-- | :-- | -| `delegate_resource` | 将已质押的资源委托给另一个地址。 | `receiverAddress`, `amount`, `resource`, `lock`, `lockPeriod`, `network` | 写入 | -| `undelegate_resource` | 撤销之前委托的资源。 | `receiverAddress`, `amount`, `resource`, `network` | 写入 | -| `get_can_delegated_max_size` | 获取可委托的最大 TRX 数量。 | `address`, `resource`, `network` | 读取 | -| `get_delegated_resource_v2` | 获取两个地址之间的委托资源详情。 | `fromAddress`, `toAddress`, `network` | 读取 | -| `get_delegated_resource_account_index_v2` | 获取委托资源账户索引。 | `address`, `network` | 读取 | - -### 质押（Stake 2.0） - -| 工具名称 | 描述 | 关键参数 | 模式 | -| :-- | :-- | :-- | :-- | -| `freeze_balance_v2` | 冻结 TRX 以获取资源。 | `amount`, `resource`, `network` | 写入 | -| `unfreeze_balance_v2` | 解冻 TRX 以释放资源。 | `amount`, `resource`, `network` | 写入 | -| `withdraw_expire_unfreeze` | 提取已过期的解冻余额。 | `network` | 写入 | -| `cancel_all_unfreeze_v2` | 取消待处理的解冻并重新质押。 | `network` | 写入 | -| `get_available_unfreeze_count` | 获取剩余可解冻操作次数。 | `address`, `network` | 读取 | -| `get_can_withdraw_unfreeze_amount` | 获取可提取的已解质押 TRX 数量。 | `address`, `timestampMs`, `network` | 读取 | - -### 治理与超级代表 - -| 工具名称 | 描述 | 关键参数 | 模式 | -| :-- | :-- | :-- | :-- | -| `list_witnesses` | 列出网络上所有超级代表。 | `network` | 读取 | -| `get_paginated_witnesses` | 获取活跃超级代表的分页列表。 | `offset`, `limit`, `network` | 读取 | -| `get_next_maintenance_time` | 获取下一个维护窗口时间戳。 | `network` | 读取 | -| `get_reward` | 查询地址的未领取投票奖励。 | `address`, `network` | 读取 | -| `get_brokerage` | 查询超级代表的佣金比例。 | `witnessAddress`, `network` | 读取 | -| `create_witness` | 申请成为超级代表（9999 TRX）。 | `url`, `network` | 写入 | -| `update_witness` | 更新超级代表网站 URL。 | `url`, `network` | 写入 | -| `vote_witness` | 为超级代表投票。 | `votes`, `network` | 写入 | -| `withdraw_balance` | 提取累积的投票奖励。 | `network` | 写入 | -| `update_brokerage` | 更新超级代表佣金比例。 | `brokerage`, `network` | 写入 | - -### 提案 - -| 工具名称 | 描述 | 关键参数 | 模式 | -| :-- | :-- | :-- | :-- | -| `list_proposals` | 列出所有治理提案。 | `network` | 读取 | -| `get_proposal` | 按 ID 获取提案详情。 | `proposalId`, `network` | 读取 | -| `create_proposal` | 创建治理提案（仅限超级代表）。 | `parameters`, `network` | 写入 | -| `approve_proposal` | 投票批准/否决提案。 | `proposalId`, `approve`, `network` | 写入 | -| `delete_proposal` | 删除治理提案。 | `proposalId`, `network` | 写入 | - -### 事件 - -| 工具名称 | 描述 | 关键参数 | 模式 | -| :-- | :-- | :-- | :-- | -| `get_events_by_transaction_id` | 获取交易触发的事件。 | `transactionId`, `network` | 读取 | -| `get_events_by_contract_address` | 获取合约触发的事件。 | `contractAddress`, `eventName`, `limit`, `network` | 读取 | -| `get_events_by_block_number` | 获取指定区块中的事件。 | `blockNumber`, `network` | 读取 | -| `get_events_of_latest_block` | 获取最新区块中的事件。 | `network` | 读取 | - -### 内存池 - -| 工具名称 | 描述 | 关键参数 | 模式 | -| :-- | :-- | :-- | :-- | -| `get_pending_transactions` | 获取内存池中待处理的交易 ID。 | `network` | 读取 | -| `get_transaction_from_pending` | 获取特定的待处理交易。 | `txId`, `network` | 读取 | -| `get_pending_size` | 获取待处理交易数量。 | `network` | 读取 | - -### 节点 - -| 工具名称 | 描述 | 关键参数 | 模式 | -| :-- | :-- | :-- | :-- | -| `list_nodes` | 列出所有已连接的节点地址。 | `network` | 读取 | -| `get_node_info` | 获取节点详细信息。 | `network` | 读取 | - -### 全节点查询 API - -| 工具名称 | 描述 | 关键参数 | 模式 | -| :-- | :-- | :-- | :-- | -| `get_block_by_num` | 按高度查询区块。 | `num`, `network` | 读取 | -| `get_block_by_id` | 按哈希查询区块。 | `value`, `network` | 读取 | -| `get_block_by_latest_num` | 获取最近 N 个区块。 | `num`, `network` | 读取 | -| `get_block_by_limit_next` | 获取指定高度范围内的区块。 | `startNum`, `endNum`, `network` | 读取 | -| `get_now_block` | 获取当前最新区块。 | `network` | 读取 | -| `get_transaction_by_id` | 按哈希查询交易。 | `value`, `network` | 读取 | -| `get_transaction_info_by_id` | 查询交易收据。 | `value`, `network` | 读取 | -| `get_transaction_info_by_block_num` | 获取区块中所有交易的收据。 | `num`, `network` | 读取 | -| `get_energy_prices` | 查询历史能量单价。 | `network` | 读取 | -| `get_bandwidth_prices` | 查询历史带宽单价。 | `network` | 读取 | -| `get_burn_trx` | 查询手续费销毁的 TRX 总量。 | `network` | 读取 | -| `get_approved_list` | 查询已签署交易的账户。 | `transaction`, `network` | 读取 | -| `get_block_balance` | 获取区块中所有余额变动。 | `hash`, `number`, `network` | 读取 | - -### 广播与交易构建 - -| 工具名称 | 描述 | 关键参数 | 模式 | -| :-- | :-- | :-- | :-- | -| `broadcast_transaction` | 广播已签名的交易（JSON）。 | `transaction`, `network` | 写入 | -| `broadcast_hex` | 广播已签名的交易（hex）。 | `transaction`, `network` | 写入 | -| `create_transaction` | 创建未签名的 TRX 转账交易。 | `ownerAddress`, `toAddress`, `amount`, `network` | 写入 | - ---- - -## 提示（共 6 个） - -| 提示名称 | 描述 | 关键参数 | 需要钱包 | -| :-- | :-- | :-- | :-- | -| `prepare_transfer` | 安全地准备和执行带验证检查的代币转账。 | `tokenType`, `recipient`, `amount`, `network`, `tokenAddress` | 是 | -| `interact_with_contract` | 安全地执行带验证的智能合约写入操作。 | `contractAddress`, `functionName`, `args`, `value`, `network` | 是 | -| `diagnose_transaction` | 分析交易状态、失败原因并提供调试建议。 | `txHash`, `network` | 否 | -| `explain_tron_concept` | 通过示例解释 TRON 和区块链概念。 | `concept` | 否 | -| `analyze_wallet` | 获取钱包资产和活动的综合概览。 | `address`, `network`, `tokens` | 否 | -| `check_network_status` | 检查当前网络健康状况和运行条件。 | `network` | 否 | - ---- - -## 资源（共 1 个） - -| 资源名称 | URI | 描述 | -| :-- | :-- | :-- | -| `supported_networks` | `tron://networks` | 获取所有支持的 TRON 网络及其配置列表。 | diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md new file mode 100644 index 00000000..1f7053e9 --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/FAQ.md @@ -0,0 +1,242 @@ +# 常见问题与排查 + +遇到问题时，先来这里找找答案。本页按照你最可能遇到的顺序组织：先是连接问题（最常见），然后是认证与密钥、链上错误、AI 行为异常，最后是一些通用的常见问题。 + +--- + +## 连接问题 + +连接问题通常发生在首次配置阶段。如果 AI 客户端无法识别 TRON 工具，多半是这里出了问题。 + +### Claude Desktop 提示"无法连接到 MCP 服务器" + +这是最常见的问题。按以下顺序逐一排查： + +1. **检查 Node.js 版本**。TRON MCP Server 需要 v20.0.0 或更高版本： + ```bash + node --version # 应输出 v20.x.x 或更高 + ``` + 如果版本太低，请先升级 Node.js。 + +2. **检查 npx 是否可用**。在终端运行 `npx --version`。如果找不到命令，说明 Node.js 安装不完整，需要重新安装。 + +3. **验证配置文件格式**。`claude_desktop_config.json` 必须是合法的 JSON。常见错误包括多余的逗号、缺少引号或括号不匹配。可以用这个命令快速验证： + ```bash + cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python3 -m json.tool + ``` + 如果输出了格式化的 JSON，说明格式没问题。如果报错，按照错误提示修复。 + +4. **完全重启**。关闭窗口不等于退出——你需要从菜单栏/系统托盘彻底退出 Claude Desktop，然后重新打开。macOS 上可以在 Dock 图标上右键选择"退出"。 + +5. **查看日志**。如果以上都没解决问题，查看 Claude Desktop 的日志文件。macOS 上在 `~/Library/Logs/Claude/` 目录下，搜索包含 "mcp" 或 "tron" 的条目。 + +### HTTP 模式下"连接被拒绝" + +使用 HTTP 模式（`npm run start:http`）时客户端无法连接，通常是以下原因： + +1. **服务器没有在运行**。先确认一下： + ```bash + curl http://localhost:3001/health + ``` + 如果返回"Connection refused"，说明服务器进程没有启动或已经退出。 + +2. **端口被占用**。可能有其他程序占用了 3001 端口： + ```bash + lsof -i :3001 + ``` + 如果端口冲突，通过环境变量换一个端口： + ```bash + export MCP_PORT=3002 + ``` + +3. **防火墙拦截**。如果你从另一台机器访问本地 HTTP 服务，检查防火墙是否允许该端口的入站连接。 + +### 工具列表中只有读取工具，没有写入工具 + +这不是一个错误——它是设计如此。写入工具（转账、质押等）仅在配置了钱包之后才会注册到 AI 的工具列表中。如果你没有设置任何钱包环境变量，服务器会自动以只读模式运行。 + +要解锁写入工具，配置以下三种钱包模式之一： + +- 设置 `AGENT_WALLET_PASSWORD`（Agent Wallet 模式，推荐） +- 设置 `TRON_PRIVATE_KEY`（私钥模式） +- 设置 `TRON_MNEMONIC`（助记词模式） + +配置完成后重启 AI 客户端即可。详细说明请参阅[本地私有化部署](./LocalPrivatizedDeployment.md)。 + +--- + +## 认证与密钥问题 + +### "私钥无效"错误 + +服务器启动时报告私钥无效，通常是格式问题： + +1. **检查密钥格式**。私钥应为 64 个字符的十六进制字符串，可以带或不带 `0x` 前缀： + ``` + # 合法格式： + abc123def456... （64 个十六进制字符） + 0xabc123def456... （0x + 64 个十六进制字符） + ``` + +2. **避免多余的空格或引号**。环境变量值不能包含额外的空格、嵌套引号或换行符： + ```bash + # 正确 + export TRON_PRIVATE_KEY=abc123def456... + + # 错误（引号成了值的一部分） + export TRON_PRIVATE_KEY="'abc123def456...'" + ``` + +3. **验证密钥有效性**。将同一私钥导入 TRON 钱包（如 TronLink）确认其有效。 + +### "Agent Wallet 密码错误" + +`AGENT_WALLET_PASSWORD` 必须与执行 `agent-wallet init` 时设置的主密码完全一致。如果你不确定： + +1. **检查钱包目录是否存在**： + ```bash + ls ~/.agent-wallet/ # 默认位置 + ``` + 如果使用了自定义目录，确保 `AGENT_WALLET_DIR` 指向正确路径。 + +2. **密码丢失**时需要重新初始化。注意：这会创建一个新的钱包，旧钱包的资金需要通过其他方式恢复。 + ```bash + agent-wallet init + ``` + +### TronGrid API Key 不生效 + +已配置了 API Key 但请求仍然受到限速，检查以下几点： + +1. **变量名是否正确**。正确的变量名是 `TRONGRID_API_KEY`（不是 `TRON_API_KEY` 或其他变体）。 + +2. **Key 是否仍然有效**。登录 [trongrid.io](https://www.trongrid.io/) 确认 API Key 处于激活状态。 + +3. **云服务的请求头格式**。通过官方云服务使用 API Key 时，`--header` 参数的格式必须是 `TRONGRID-API-KEY:你的key`，冒号前后不能有空格。 + +--- + +## 链上错误 + +这些错误发生在交易执行阶段，通常与链上资源或合约逻辑有关。 + +### "带宽不足" + +每笔 TRON 交易都会消耗带宽。如果账户既没有足够的质押带宽，TRX 余额也不够燃烧换取带宽，交易就会失败。 + +**怎么解决：** +- 先让 AI 查看你的带宽情况："查看我的地址的带宽资源" +- 质押一些 TRX 换取带宽："质押 100 TRX 获取带宽" +- 或者确保账户有足够的 TRX 余额——即使没有质押带宽，系统也会自动燃烧 TRX 来支付 + +### "能量不足" + +与智能合约交互（包括 TRC20 代币转账）需要消耗能量。如果质押的能量不够用，系统会燃烧 TRX 来弥补；如果 TRX 也不够，交易就会失败。 + +**怎么解决：** +- 先预估费用："预估调用这个合约的 transfer 函数需要多少能量" +- 质押 TRX 换取能量："质押 500 TRX 获取能量" +- 如果使用 `write_contract`，可以让 AI 提高 `feeLimit` 参数 + +### "账户不存在"或"账户未激活" + +TRON 上的新地址必须"激活"后才能使用。地址首次收到 TRX 转账时会自动激活。 + +**怎么解决：** +- 向该地址发送少量 TRX（0.1 TRX 就够） +- 或使用 `create_account` 工具显式激活 + +### 交易显示"REVERT"状态 + +交易已被打包但执行失败，说明智能合约代码中某个 `require()` 条件不满足。 + +**怎么排查：** +1. 让 AI 诊断："诊断一下交易 [哈希] 为什么会 revert" +2. 常见原因包括：代币余额或授权额度不足、调用了没有权限的函数、传入了无效参数、合约特定的业务逻辑条件不满足 +3. 使用 `read_contract` 查询合约状态，了解需要满足什么前置条件 + +--- + +## AI 行为问题 + +这些问题与 AI 模型本身的行为有关，而不是 TRON MCP Server 的 bug。 + +### AI 构造了无效地址 + +AI 模型有时会"编造"格式正确但实际不存在的 TRON 地址。TRON MCP Server 内置了地址验证，大多数接受地址的工具会自动拒绝无效地址。 + +**预防措施：** +- 始终通过复制粘贴提供精确地址，不要口头描述让 AI 猜测 +- 不确定时用 `validate_address` 验证："验证一下这个地址 TXyz..." + +### AI 尝试调用不存在的工具 + +AI 可能将 TRON MCP Server 的能力与其他区块链工具混淆。如果它尝试调用一个不存在的工具，会收到错误并自动尝试使用正确的工具。 + +如果反复出现这个问题，可以提醒 AI："请只使用 TRON MCP Server 提供的工具"，或查阅 [完整能力清单](./ToolList.md) 确认可用的工具列表。 + +### 响应速度较慢 + +几种常见原因和对策： + +- **没有 TronGrid API Key**：公共 RPC 有频率限制，添加免费的 API Key 可以显著改善 +- **复杂的多工具工作流**：某些操作（如钱包全貌分析）需要多个串行调用，等待是正常的 +- **使用测试网开发**：Nile 和 Shasta 测试网通常响应更快 +- **提示词更明确**：减少 AI 的探索性调用——直接告诉它用哪个工具、查哪个网络 + +--- + +## 通用问题 + +### 主网、Nile 和 Shasta 有什么区别？ + +| 网络 | 用途 | 是否有真实价值 | 如何获取代币 | +| :--- | :--- | :--- | :--- | +| **主网** | 生产环境 | 是（真实 TRX） | 交易所购买 | +| **Nile** | 开发测试（推荐） | 否（测试代币） | 水龙头免费领取 | +| **Shasta** | 开发测试 | 否（测试代币） | 水龙头免费领取 | + +建议始终先在 Nile 上开发和测试，确认无误后再在主网执行。 + +### 能否同时使用多个 TRON MCP Server 实例？ + +可以。在配置中定义多个 MCP Server 条目即可——比如一个连接主网云服务（只读），另一个连接本地测试网部署（带钱包）。只需使用不同的名称： + +```json +{ + "mcpServers": { + "tron-mainnet": { + "command": "npx", + "args": ["mcp-remote", "https://tron-mcp-server.bankofai.io/mcp"] + }, + "tron-local": { + "command": "npx", + "args": ["-y", "@bankofai/mcp-server-tron"], + "env": { + "AGENT_WALLET_PASSWORD": "your-password" + } + } + } +} +``` + +### 如何更新到最新版本？ + +如果你使用的是 `npx` 方式运行，每次都会自动获取最新发布版本。若要强制刷新缓存： + +```bash +npx clear-npx-cache +``` + +如果你是从源码克隆的： + +```bash +cd mcp-server-tron +git pull +npm install +npm run build +``` + +### 支持哪个 MCP 协议版本？ + +TRON MCP Server 支持 MCP 协议版本 **2025-11-25**，使用 `@modelcontextprotocol/sdk` 1.22.0 或更高版本。 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/Intro.md index 7f66f1c5..0e7421f1 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/Intro.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/Intro.md @@ -1,59 +1,97 @@ - # 简介 -TRON MCP Server 旨在为 AI 代理提供与 TRON 区块链交互的能力。通过统一的接口，AI 代理可以利用工具和 AI 引导的提示来访问 TRON 网络服务，支持 TRX、TRC20 代币以及智能合约操作。该服务器利用 `tronweb` 库，全面支持 TRON 生态系统。 +## TRON MCP Server 是什么？ + +TRON MCP Server 是连接 AI 助手与 TRON 区块链的桥梁。它基于 [Model Context Protocol (MCP)](../Intro.md) 标准协议，让你可以用自然语言与区块链交互——查余额、发起转账、调用智能合约——而无需编写任何代码。 + +举个例子：你只需要对 Claude 说"查一下这个地址有多少 USDT"，AI 就会自动调用链上查询工具，把结果整理好返回给你。不需要打开区块浏览器，不需要拼接 API 请求，也不需要理解底层的 JSON-RPC 协议。 + +这对不同的人意味着不同的事情： + +- 如果你是 **AI 应用用户**，它让你在 Claude Desktop、Cursor 等工具中直接操作区块链，和日常聊天一样简单。 +- 如果你是 **Web3 开发者**，它是你的链上快速原型工具——用自然语言调试合约、查询状态，省去大量样板代码。 +- 如果你是 **AI Agent 构建者**，它提供了 95 个标准化的链上工具，可以直接编排进你的自动化流程。 +- 如果你是 **数据分析师**，它让链上数据查询变成了对话，不再需要写脚本抓取和解析。 + +--- + +## 它能做什么？ + +TRON MCP Server 覆盖了 TRON 区块链上几乎所有常见操作，从只读查询到资产管理，共提供 **95 个工具**、**6 个提示词模板**和 **1 个资源定义**。 -## MCP 服务器 URL -为了方便不同需求的用户，你可以选择直接连接[官方云服务](./OfficialServerAccess.md)，也可以选择在自己的电脑上进行[本地化部署](./LocalPrivatizedDeployment.md)。其中官方服务只提供读取服务。 +以下是核心能力概览——每一项都可以通过自然语言触发： -| 环境 | URL | -| :------- | :--------------------------------------- | -| 生产环境 | [https://tron-mcp-server.bankofai.io/mcp](https://tron-mcp-server.bankofai.io/mcp) | +| 能力 | 描述 | 你可以这样说 | +| :--- | :--- | :--- | +| **余额查询** | 查询 TRX 或任意 TRC20 代币余额 | "这个地址有多少 USDT？" | +| **转账操作** | 向指定地址发送 TRX 或 TRC20 代币 | "向 TXyz... 转 100 TRX" | +| **智能合约** | 读取、写入、部署和调试智能合约 | "调用这个合约的 balanceOf 方法" | +| **交易查询** | 查看交易详情、状态和资源消耗 | "查一下这个交易哈希的状态" | +| **账户管理** | 查看账户资源、权限、质押状态 | "查看这个地址的能量和带宽" | +| **质押与委托** | 质押 TRX 获取资源，委托能量/带宽 | "质押 1000 TRX 换取能量" | +| **治理参与** | 查看超级代表、投票、管理提案 | "列出当前所有超级代表候选人" | +| **链上事件** | 查询合约事件和交易日志 | "获取这个合约最近的 Transfer 事件" | +| **网络状态** | 出块情况、资源价格、链健康度 | "当前 TRON 区块高度是多少？" | +| **钱包管理** | 多钱包切换、消息签名、地址转换 | "把这个地址转换成 Base58 格式" | +完整的工具列表和参数说明，请参阅 [完整能力清单](./ToolList.md)。 -## 核心能力概览 +--- -* **区块链数据**：读取区块、交易和链参数（如能量/带宽成本）。 -* **智能合约**：与任何 TRON 智能合约进行交互（支持读/写）。 -* **代币服务**：转移 TRX 和 TRC20 代币；检查余额及元数据。 -* **地址管理**：在 Hex 和 Base58 格式之间转换并验证地址。 -* **安全集成**：支持私钥和助记词 (BIP-39) 钱包，确保操作安全。 -* **多网络支持**：全面覆盖主网、Nile 和 Shasta 测试网。 +## 两种接入方式 +了解了 TRON MCP Server 的能力后，你需要选择一种接入方式。根据你的使用场景，有两条路径： -## 详细功能特性 +**[官方云服务](./OfficialServerAccess.md)** — 适合快速体验和数据查询。不需要安装任何东西，在 AI 客户端的配置中加一行服务地址就能开始使用。但云服务只提供**只读**能力，不支持转账、合约写入等操作。 -TRON MCP Server 提供的具体功能列表，供开发者和高级用户参考： +**[本地私有化部署](./LocalPrivatizedDeployment.md)** — 适合需要完整功能的用户。在你自己的机器上运行 TRON MCP Server，配置钱包后即可解锁全部读写能力。私钥完全在本地管理，不会上传到任何远程服务。 -### 区块链数据访问 -* **多网络支持**：支持 Mainnet、Nile 和 Shasta 网络。 -* **链信息查询**：获取当前区块高度、链 ID 及 RPC 节点信息。 -* **区块数据**：通过区块号或哈希值访问详细区块信息。 -* **交易详情**：获取交易的完整细节，包括资源消耗（能量/带宽）。 -* **资源成本查询**：实时查询链上能量和带宽的价格参数。 +两者的核心区别归结为一点：**是否需要签名交易**。 -### 代币服务 -* **原生 TRX**：支持余额查询和转账操作。 -* **TRC20 代币**： - * 查询代币余额。 - * 执行代币转账。 - * 获取代币元数据（名称、符号、精度）。 +| 对比项 | 官方云服务 | 本地私有化部署 | +| :--- | :--- | :--- | +| **功能范围** | 仅读取（查询） | 完整功能（读取 + 写入） | +| **上手难度** | 加一条配置即可 | 需本地安装和构建 | +| **是否需要私钥** | 不需要 | 需要（写入操作必须） | +| **转账/合约写入** | 不支持 | 支持 | +| **适合场景** | 快速查询、入门体验 | 开发调试、自动化交易 | +| **安全性** | 高（无私钥暴露风险） | 取决于你的密钥管理方式 | -### 地址服务 -* **格式转换**：在 Hex (`41...` 或 `0x...`) 与 Base58 (`T...`) 格式间无缝转换。 -* **地址验证**：验证特定地址在 TRON 网络上的有效性。 +:::tip 不确定选哪个？ +如果你只是想试一试，或者日常只需要查询链上数据，从[官方云服务](./OfficialServerAccess.md)开始就好，1 分钟即可接入。等到需要转账或合约写入时，再切换到[本地私有化部署](./LocalPrivatizedDeployment.md)。 +::: -### 智能合约交互 -* **读取合约**：调用 `view` 和 `pure` 类型函数。 -* **写入合约**：执行改变链上状态的合约函数。 -* **ABI 自动获取**：自动从区块链获取已验证合约的 ABI 接口。 +--- -### 钱包与安全 -* **灵活配置**：支持通过 `TRON_PRIVATE_KEY` 或 `TRON_MNEMONIC` 进行配置。 -* **分层确定性 (HD) 钱包**：支持 BIP-44 派生路径 `m/44'/195'/0'/0/{index}`。 -* **消息签名**：支持对任意消息进行安全签名。 +## 支持的网络 + +无论选择哪种接入方式，TRON MCP Server 都支持以下三个网络（默认连接主网）： + +| 网络 | 标识符 | 用途 | 区块浏览器 | +| :--- | :--- | :--- | :--- | +| **主网** | `mainnet` | 生产环境，真实资产 | [tronscan.org](https://tronscan.org) | +| **Nile 测试网** | `nile` | 开发测试（推荐） | [nile.tronscan.org](https://nile.tronscan.org) | +| **Shasta 测试网** | `shasta` | 开发测试 | [shasta.tronscan.org](https://shasta.tronscan.org) | + +调用工具时，通过 `network` 参数指定目标网络即可，例如"在 Nile 测试网上查一下这个地址的余额"。 + +--- ## 安全注意事项 -* **私钥管理**：私钥和助记词应始终通过环境变量安全管理，切勿硬编码或存储在不安全的文件中。 -* **测试网优先**：在将任何操作部署到主网之前，务必在 Nile 或 Shasta 测试网上进行充分测试。 -* **最小权限原则**：为 AI 代理配置的钱包应仅包含执行其任务所需的最低资金。 \ No newline at end of file +:::warning +在开始使用之前，有几条安全原则值得牢记——尤其是在涉及真实资产的操作中： + +- **切勿硬编码私钥**：不要将私钥或助记词直接写入配置文件（如 `claude_desktop_config.json`），应通过系统环境变量或加密钱包管理。 +- **先在测试网验证**：任何链上操作在主网执行前，先在 Nile 或 Shasta 测试网上跑通。 +- **最小资金原则**：为 AI Agent 配置的钱包只存放执行任务所需的最低金额。 +- **注意授权风险**：代币授权（`approve`）操作要格外谨慎，避免授予无限额度。 +::: + +--- + +## 下一步 + +- 想用最快的速度体验一下？ → [快速开始](./QuickStart.md) +- 只需要查询链上数据？ → [官方云服务接入](./OfficialServerAccess.md) +- 需要转账、合约调用等完整功能？ → [本地私有化部署](./LocalPrivatizedDeployment.md) +- 想了解全部 95 个工具？ → [完整能力清单](./ToolList.md) diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md index 8a3e10f5..390e12c5 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md @@ -1,98 +1,225 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; # 本地私有化部署 -如果您需要执行转账、合约调用等写操作，必须在本地部署服务器。本地部署允许您安全地配置私钥，从而启用完整的交易功能。 +## 什么是本地私有化部署？ -## 环境要求 -* **Node.js**：v20.0.0 或更高版本。 -* 可选：**TronGrid API Key**：建议申请（[trongrid.io](https://www.trongrid.io/)）以避免主网频率限制。 +本地私有化部署是指在你自己的机器上运行 TRON MCP Server，让 AI 助手获得对 TRON 区块链的 **完整读写能力**。 +通过[官方云服务](./OfficialServerAccess.md)，你可以查询链上所有公开数据。但一旦涉及实际的资产操作——向某个地址转一笔 TRX、调用智能合约的状态变更函数、质押 TRX 获取能量、为超级代表投票——这些操作都需要用你的私钥对交易进行签名。出于安全考虑，私钥只能在你本地管理，不会上传到任何远程服务。 -## 关键配置（环境变量） -**重要安全提示**：为了您的安全，**切勿**将您的私钥或助记词直接保存在 MCP 配置文件（如 `claude_desktop_config.json` 或 `mcp.json`）中。相反，请将它们设置为您操作系统或 shell 配置中的环境变量。 +**本地部署的核心作用，就是在你的机器上运行一个完整的 MCP Server，安全地持有钱包凭证，让 AI 助手可以代你签名并广播交易。** -要启用写入操作（转账、合约调用）并确保可靠的 API 访问，您应该配置以下变量。 +### 本地部署能做什么？ -### 1. 网络配置 +相比云服务的只读模式，本地部署解锁了全部写操作能力： -* `TRONGRID_API_KEY`：(可选) 您的 TronGrid API 密钥。 - * **原因**：TRON 主网 RPC 具有严格的速率限制。使用 [TronGrid](https://www.trongrid.io/) 的 API 密钥可确保可靠的性能和更高的吞吐量。 - * **用法**： - - ```shell - export TRONGRID_API_KEY="" - ``` -* 服务器配置 +- **转账**：发送 TRX 和 TRC20 代币 +- **智能合约**：部署新合约、调用状态变更函数、管理合约设置 +- **质押与委托**：冻结 TRX 获取能量/带宽、将资源委托给其他地址 +- **治理**：为超级代表投票、创建和审批提案 +- **钱包管理**：多钱包切换、消息签名、账户权限更新 +- **交易构建**：创建未签名交易、广播已签名交易 - * 服务器默认以 HTTP 模式在端口 **3001** 上运行。 +当然，所有只读查询能力同样完整保留。 -### 2. 钱包配置（使用环境变量） +--- -**选项 1：私钥** +## 开始之前 -```shell -# 推荐：将其添加到您的 ~/.zshrc 或 ~/.bashrc -export TRON_PRIVATE_KEY="" +### 环境要求 + +| 要求 | 说明 | +| :--- | :--- | +| **Node.js** | v20.0.0 或更高版本（[下载](https://nodejs.org/)） | +| **TronGrid API Key** | 可选但推荐（[申请地址](https://www.trongrid.io/)） | + +验证 Node.js 版本： + +```bash +node --version # 应输出 v20.x.x 或更高 ``` -**选项 2：助记词** +### 安全原则 + +在配置钱包之前，请务必理解以下安全原则： + +:::danger 安全警告 +**切勿**将私钥或助记词直接保存在 MCP 配置文件（如 `claude_desktop_config.json` 或 `mcp.json`）中。这些文件通常未加密，可能被意外分享或提交到 Git。请务必使用系统环境变量或加密钱包。 +::: + +--- +## 安装步骤 +### 第一步：配置钱包 + +钱包决定了 AI 助手以哪个身份执行链上操作。TRON MCP Server 支持三种钱包模式，若未配置任何钱包，服务器会自动以只读模式运行。 + +#### 有三种创建钱包的方式，请根据需要选择 + +| 特性 | Agent Wallet | 私钥 | 助记词 | +| :--- | :--- | :--- | :--- | +| 安全等级 | 高（加密存储） | 低（明文） | 低（明文） | +| 多钱包支持 | 是 | 否 | 否 | +| 运行时切换钱包 | 是 | 否 | 否 | +| 配置复杂度 | 中等 | 简单 | 简单 | +| 推荐场景 | 生产环境、较多资金 | 开发测试、少量资金 | 开发测试、少量资金 | + +#### 方式一：通过 Agent Wallet（推荐）创建钱包 + +这是最安全的方式。私钥加密存储在本地磁盘，不会以明文形式暴露在环境变量中。即使环境变量被泄露，攻击者仍需要加密的密钥库文件才能访问资金。 + +**安装并初始化 Agent Wallet：** + +```bash +# 安装 +npm install -g @bankofai/agent-wallet -```shell -# 推荐：将其添加到您的 ~/.zshrc 或 ~/.bashrc -export TRON_MNEMONIC=" ... " -export TRON_ACCOUNT_INDEX="0" # 可选，默认值：0 +# 创建加密钱包 +agent-wallet start ``` +Agent Wallet 还支持**多钱包管理**——你可以创建多个钱包，在运行时通过 `select_wallet` 工具随时切换，非常适合需要在不同账户间操作的场景。 -## 安装 -1. **克隆并进入目录**： - ```shell - git clone https://github.com/BofAI/mcp-server-tron.git - cd mcp-server-tron - ``` -2. **安装与构建**： - ```shell - npm install && npm run build - ``` +> 了解详细的安装和使用说明请参阅 [agent-wallet 文档](https://github.com/BofAI/agent-wallet/blob/main/doc/getting-started.md)。 +**设置环境变量：** -## 验证 -默认 stdio 模式： ```bash -# 运行测试 -npm test +# 添加到 ~/.zshrc 或 ~/.bashrc +export AGENT_WALLET_PASSWORD="<你的主密码>" -# 启动服务（stdio） -npm start +# 可选：指定自定义钱包目录（默认：~/.agent-wallet） +export AGENT_WALLET_DIR="~/.agent-wallet" ``` -使用 HTTP（streamable-http）模式时： + + +#### 方式二：通过私钥导入钱包 + +通过环境变量直接提供私钥。配置最简单，但安全性较低。 ```bash -npm run start:http +# 添加到 ~/.zshrc 或 ~/.bashrc +export TRON_PRIVATE_KEY="<你的私钥十六进制值>" ``` +私钥可以是带 `0x` 前缀或不带前缀的十六进制格式。 + +:::warning +在环境变量中使用明文私钥存在**真实的资金被盗风险**——环境变量可能通过 shell 历史记录、进程列表（`ps aux`）或日志文件泄露。**这类钱包只应存放少量资金**。 +::: -## 客户端集成 +#### 方式三：通过助记词导入钱包 -要将此服务器与 Claude Desktop、Cursor 或 Google Antigravity 等 MCP 客户端一起使用，您需要将其添加到您的配置文件中。 +通过 BIP-39 助记词进行 HD 钱包派生。 + +```bash +# 添加到 ~/.zshrc 或 ~/.bashrc +export TRON_MNEMONIC="单词1 单词2 单词3 ... 单词12" + +# 可选：指定 HD 钱包派生索引（默认：0） +# 派生路径：m/44'/195'/0'/0/{index} +export TRON_ACCOUNT_INDEX="0" +``` -### 1. 找到您的配置文件 +:::warning +与私钥方式的安全风险相同。明文存储的助记词容易泄露，请只用于存放少量资金的开发/测试钱包。 +::: + + + +--- + +### 第二步：配置网络（可选） + +#### TronGrid API Key + +TRON 主网公共 RPC 有严格的频率限制。如果你的使用场景涉及频繁的链上查询，强烈建议配置一个免费的 TronGrid API Key： + +```bash +# 添加到 ~/.zshrc 或 ~/.bashrc +export TRONGRID_API_KEY="<你的 TronGrid API Key>" +``` + +在 [trongrid.io](https://www.trongrid.io/) 注册即可免费获取。不配置时服务器仍然可以运行，但高频操作下可能出现限速错误。测试网（Nile、Shasta）受频率限制的影响较小。 + + +--- + +### 第三步：本地私有化部署 + +提供两种方式。对于大多数用户，方式 A 就够了。 + +#### 方式 A：npx 直接运行（推荐） + +无需克隆仓库，通过 `npx` 直接运行最新版本。这也是下方 MCP 客户端配置示例中默认采用的方式。 + +```bash +npx -y @bankofai/mcp-server-tron +``` + +#### 方式 B：从源码克隆 + +适用于需要修改源码或参与贡献的开发者： + +```bash +git clone https://github.com/BofAI/mcp-server-tron.git +cd mcp-server-tron +npm install +npm run build +``` + +--- + +### 第四步：客户端配置 + +环境变量和安装都准备好了，现在把 AI 客户端指向本地服务器。 + +#### 找到配置文件 | 应用程序 | 操作系统 | 配置路径 | -| :-- | :-- | :-- | +| :--- | :--- | :--- | | **Claude Desktop** | macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` | | | Windows | `%APPDATA%\Claude\claude_desktop_config.json` | | **Cursor** | 所有 | 项目根目录：`.cursor/mcp.json` | | **Google Antigravity** | 所有 | `~/.config/antigravity/mcp.json` | | **Opencode** | 所有 | `~/.config/opencode/mcp.json` | +#### 添加服务器定义 + + + + +直接从 npm 运行最新版本，无需克隆仓库。 + +**Claude Desktop**（`claude_desktop_config.json`）： + +```json +{ + "mcpServers": { + "mcp-server-tron": { + "command": "npx", + "args": ["-y", "@bankofai/mcp-server-tron"], + "env": { + "AGENT_WALLET_PASSWORD": "YOUR_PASSWORD（或在系统环境变量中设置）", + "TRONGRID_API_KEY": "YOUR_KEY_HERE（或在系统环境变量中设置）" + } + } + } +} +``` +**Claude Code**： -### 2. 添加服务器定义 +```bash +# 基础配置 +claude mcp add mcp-server-tron -- npx -y @bankofai/mcp-server-tron -选择以下方法之一将其添加到您的 `mcpServers` 对象中。 +# 携带环境变量 +claude mcp add -e AGENT_WALLET_PASSWORD=xxx -e TRONGRID_API_KEY=xxx mcp-server-tron -- npx -y @bankofai/mcp-server-tron +``` -**选项 A：快速开始（推荐）** 直接从 npm 运行最新版本。 +**Cursor**（`.cursor/mcp.json`）： ```json { @@ -101,29 +228,112 @@ npm run start:http "command": "npx", "args": ["-y", "@bankofai/mcp-server-tron"], "env": { - "TRON_PRIVATE_KEY": "YOUR_KEY_HERE (Or set in system env)", - "TRONGRID_API_KEY": "YOUR_KEY_HERE (Or set in system env)" + "AGENT_WALLET_PASSWORD": "YOUR_PASSWORD（或在系统环境变量中设置）", + "TRONGRID_API_KEY": "YOUR_KEY_HERE（或在系统环境变量中设置）" + } + } + } +} +``` + + + + +适用于从克隆仓库运行的开发者。 + +**Claude Desktop**（`claude_desktop_config.json`）： + +```json +{ + "mcpServers": { + "mcp-server-tron": { + "command": "npx", + "args": ["tsx", "/mcp-server-tron 的绝对路径/src/index.ts"], + "env": { + "AGENT_WALLET_PASSWORD": "YOUR_PASSWORD（或在系统环境变量中设置）", + "TRONGRID_API_KEY": "YOUR_KEY_HERE（或在系统环境变量中设置）" } } } } ``` -**选项 B：本地开发** 适用于从克隆仓库运行的开发者。 +将路径替换为你实际克隆的仓库路径。 + +**Cursor**（`.cursor/mcp.json`）： ```json { "mcpServers": { "mcp-server-tron": { "command": "npx", - "args": ["tsx", "/ABSOLUTE/PATH/TO/mcp-server-tron/src/index.ts"], + "args": ["tsx", "/mcp-server-tron 的绝对路径/src/index.ts"], "env": { - "TRON_PRIVATE_KEY": "YOUR_KEY_HERE (Or set in system env)", - "TRONGRID_API_KEY": "YOUR_KEY_HERE (Or set in system env)" + "AGENT_WALLET_PASSWORD": "YOUR_PASSWORD（或在系统环境变量中设置）", + "TRONGRID_API_KEY": "YOUR_KEY_HERE（或在系统环境变量中设置）" } } } } ``` -**重要提示**：如果您已在系统环境中设置了这些变量，我们建议省略 `env` 部分。如果您的 MCP 客户端不继承系统变量，请使用占位符或确保配置文件未共享或提交到版本控制。 + + + +如果你以 HTTP 模式启动了服务器（`npm run start:http`），通过 HTTP URL 连接： + +**Claude Code**： + +```bash +claude mcp add --transport http mcp-server-tron http://localhost:3001/mcp +``` + +**Cursor**（`.cursor/mcp.json`）： + +```json +{ + "mcpServers": { + "mcp-server-tron": { + "url": "http://localhost:3001/mcp" + } + } +} +``` + + + + +:::tip 关于配置中的 `env` 部分 +如果你已经在系统中设置了环境变量（通过 `~/.zshrc` 或 `~/.bashrc`），可以完全省略配置中的 `env` 部分，服务器会自动读取系统环境变量。 + +如果你的 MCP 客户端不继承系统环境变量，则需要在 `env` 部分中设置。此时**请确保该配置文件不会被分享或提交到版本控制系统**。 +::: + +--- + +### 第五步：验证接入是否成功 + +完成配置后，**完全退出并重启** AI 客户端，然后尝试： + +``` +我配置的钱包地址是什么？ +``` + +如果一切正常，AI 会调用 `get_wallet_address` 工具，返回你钱包的 Base58 和 Hex 地址。 + +你也可以在测试网上尝试转账（确保 Nile 测试网上有测试 TRX）： + +``` +在 Nile 测试网上向地址 TNPeeaaFB7K9cmo4uQpcU32zGK8G1NYqeL 转 1 TRX +``` + +:::info 获取测试 TRX +可以从 TRON 水龙头免费获取 Nile 测试网的测试 TRX。访问 [nile.tronscan.org](https://nile.tronscan.org) 查找水龙头入口，或在网上搜索"TRON Nile 水龙头"。 +::: + +--- + +## 下一步 + +- 想了解每个工具的详细参数和用法？ → [完整能力清单](./ToolList.md) +- 遇到问题？ → [常见问题](./FAQ.md) diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md index a9128ca9..5a98f93e 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md @@ -1,24 +1,111 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# 官方服务接入 -对于仅需要读取区块链数据（不涉及交易）的用户，可以直接连接到官方托管的实例。**注意：官方服务仅提供只读接口，不支持转账或合约写入等操作。** +# 官方云服务接入 -## 服务信息 -| 环境 | URL | -| :--- | :--- | -| 生产环境 | [https://tron-mcp-server.bankofai.io/mcp](https://tron-mcp-server.bankofai.io/mcp) | +## 什么是官方云服务？ + +官方云服务是由 **BANK OF AI** 托管的 TRON MCP Server 实例，用于为 AI 客户端提供 **TRON 区块链的只读查询能力**。 + +在传统方式下，如果你想让 AI 助手读取链上数据，通常需要： + +- 在本地安装 Node.js 和相关依赖 +- 克隆代码仓库并完成构建 +- 配置环境变量和网络参数 +- 自行维护服务器版本更新 + +这些准备工作对于"只是想查个余额"的用户来说过于繁重。 + +**官方云服务的核心作用，就是将这些基础设施工作全部托管。** 你只需要在 AI 客户端的配置中添加一行服务地址，即可开始与 TRON 区块链对话。 + +### 使用官方云服务的主要优点 + +**1. 无需任何本地安装** + +不用安装 Node.js、不用克隆仓库、不用运行构建命令。只需在配置文件中添加一段 JSON，重启 AI 客户端，即可使用。整个过程通常不超过 2 分钟。 + +**2. 无私钥暴露风险** + +由于云服务是只读的，你完全不需要提供任何钱包私钥或助记词。这从根本上消除了密钥泄露、配置文件被误提交到 Git 等安全隐患。在团队协作场景中尤为方便——任何成员都可以直接接入，不存在密钥分发和管理的问题。 + +**3. 官方维护与持续升级** + +云服务由官方统一维护，始终运行最新稳定版本的 TRON MCP Server。包括： + +- 新工具和功能的更新 +- 底层 TRON 网络升级的适配 +- 性能和稳定性的持续优化 + +你无需关心版本号，也不需要手动执行 `npm install` 或重新构建。 + +**4. 覆盖绝大部分真实场景** + +日常中最常用的操作——查地址余额、分析交易详情、读取合约状态、查看超级代表列表、监控链上事件——全部属于只读查询，通过云服务就能完整覆盖。只有当你需要实际转移资产（转账、质押、合约写入等）时，才需要切换到[本地私有化部署](./LocalPrivatizedDeployment.md)。 + +> 简单来说：**官方云服务就像 TRON 区块链的"只读 API 网关"**，AI 客户端只需要知道服务地址，就可以查询链上的一切公开数据。 + +:::warning 重要说明 +官方云服务仅提供**只读访问**。**不支持**转账、合约写入、质押以及任何其他写操作。如需完整功能，请使用[本地私有化部署](./LocalPrivatizedDeployment.md)。 +::: + +--- + +## 如何接入官方云服务？ -- **传输协议**：Streamable HTTP -- **模式**：只读（写入工具已禁用） +要接入官方云服务，只需要在 AI 客户端配置中添加官方提供的 **MCP 服务地址**：[https://tron-mcp-server.bankofai.io/mcp](https://tron-mcp-server.bankofai.io/mcp) -**重要安全提示**：为了您的安全，**切勿**将您的私钥或助记词直接保存在 MCP 配置文件（如 `claude_desktop_config.json` 或 `mcp.json`）中。相反，请将它们设置为您操作系统或 shell 配置中的环境变量。 -## 客户端集成 +> 注意：这是一个 MCP 协议端点，不是网页地址。在浏览器中直接打开不会显示任何内容。 + +官方云服务支持 **两种使用模式**： + +| 模式 | 限速 | 说明 | +| :--- |--- |:--- | +| **无 API Key（默认）** | 100,000 Requests / Day |即开即用，适合入门体验和低频查询 | +| **带 TronGrid API Key** | 500,000 Requests / Day |更高的请求频率上限，适合频繁查询和生产级使用 | + +两种模式的接入方式完全相同，区别仅在于请求频率限制。 + +--- + +### 无 API Key 模式（默认） + +不配置任何 API Key 即可直接使用。适用于： + +- 首次体验 TRON MCP Server +- 偶尔查询链上数据 +- 教学演示和功能验证 + +在这种模式下，所有工具均可正常调用，但主网查询在高频场景下可能触发 TronGrid 公共 RPC 的速率限制。 + +--- + +### 带 TronGrid API Key 模式（推荐） + +如果你需要频繁查询主网数据，建议申请一个免费的 TronGrid API Key 以获得更高的请求频率上限。 + +**申请步骤：** + +1. 访问 [trongrid.io](https://www.trongrid.io/) +2. 注册账号并创建项目 +3. 复制生成的 API Key +4. 在配置中添加 API Key 请求头（见下方客户端配置示例） + +配置 API Key 后，你的请求会通过 TronGrid 的认证通道，享受更稳定的性能和更高的吞吐量。 + +--- + +## 客户端配置 +配置文件路径： +- **macOS**：`~/Library/Application Support/Claude/claude_desktop_config.json` +- **Windows**：`%APPDATA%\Claude\claude_desktop_config.json` + +**基础配置（不含 API Key）**： + ```json { "mcpServers": { @@ -33,7 +120,7 @@ import TabItem from '@theme/TabItem'; } ``` -带 TronGrid API Key： +**含 TronGrid API Key 的配置**： ```json { @@ -51,16 +138,18 @@ import TabItem from '@theme/TabItem'; } ``` +将 `` 替换为你的实际 TronGrid API Key。 + -CLI 命令： +**命令行添加**： -```shell +```bash claude mcp add --transport http mcp-server-tron https://tron-mcp-server.bankofai.io/mcp ``` -或在项目根目录添加 `.mcp.json`： +**或在项目根目录添加 `.mcp.json`**： ```json { @@ -74,12 +163,28 @@ claude mcp add --transport http mcp-server-tron https://tron-mcp-server.bankofai ``` + +在项目根目录添加 `.cursor/mcp.json`： + +```json +{ + "mcpServers": { + "mcp-server-tron": { + "url": "https://tron-mcp-server.bankofai.io/mcp" + } + } +} +``` + + -初始化连接： +如果你想将 TRON MCP Server 集成到自己的应用中，可以通过标准 HTTP 请求调用。 + +**第一步：初始化连接** -```shell +```bash curl -X POST https://tron-mcp-server.bankofai.io/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ @@ -95,13 +200,17 @@ curl -X POST https://tron-mcp-server.bankofai.io/mcp \ }' ``` -调用工具（使用初始化响应中的 `mcp-session-id`）： +响应中会包含 `mcp-session-id` 请求头，后续请求需要用到它。 -```shell +**第二步：调用工具** + +使用第一步获得的 `mcp-session-id`： + +```bash curl -X POST https://tron-mcp-server.bankofai.io/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ - -H "mcp-session-id: " \ + -H "mcp-session-id: " \ -d '{ "jsonrpc": "2.0", "method": "tools/call", @@ -113,7 +222,68 @@ curl -X POST https://tron-mcp-server.bankofai.io/mcp \ }' ``` - +**第三步：查看可用工具列表** +```bash +curl -X POST https://tron-mcp-server.bankofai.io/mcp \ + -H "Content-Type: application/json" \ + -H "Accept: application/json, text/event-stream" \ + -H "mcp-session-id: " \ + -d '{ + "jsonrpc": "2.0", + "method": "tools/list", + "params": {}, + "id": 3 + }' +``` + +:::info Session 管理 +- 每次 `initialize` 会创建一个新 Session +- Session 在 30 分钟无活动后自动过期 +- 可用 `DELETE /mcp`（携带 `mcp-session-id` 请求头）显式关闭 Session +::: + + +--- + +## 验证接入是否成功 + +配置完成后，**完全退出并重启** AI 客户端，然后输入以下测试问法： + +``` +查询 TRON 主网当前的区块高度 +``` + +如果收到正常响应（例如显示当前区块高度），说明接入成功。 + +如遇到问题，请查阅[常见问题](./FAQ.md)进行排查。 + +--- + +## 可用能力一览 + +通过官方云服务连接时，可以使用全部**只读**工具，包括但不限于： + +| 分类 | 示例能力 | +| :--- | :--- | +| 余额查询 | 查询 TRX 余额、TRC20 代币余额、持仓汇总 | +| 交易查询 | 查询交易详情、收据、资源消耗 | +| 区块数据 | 按区块号、按哈希查询，最新区块，批量查询 | +| 账户信息 | 账户详情、资源情况、委托信息、带宽/能量 | +| 智能合约读取 | 调用 view/pure 函数、获取 ABI、合约元数据 | +| 事件查询 | 按交易、按合约地址、按区块号查询事件 | +| 网络状态 | 链信息、资源价格、支持的网络列表 | +| 治理 | 超级代表列表、提案、奖励查询 | +| 地址工具 | 格式转换、地址验证 | + +完整能力清单请参阅 [完整能力清单](./ToolList.md)。 + +--- + +## 下一步 + +- 需要转账、质押或合约写入？ → [本地私有化部署](./LocalPrivatizedDeployment.md) +- 想看所有 95 个工具的详细说明？ → [完整能力清单](./ToolList.md) + diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md new file mode 100644 index 00000000..d3cde4b3 --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/QuickStart.md @@ -0,0 +1,126 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# 快速开始 + +这个页面的目标很简单：**让你在 1 分钟内完成接入，发起第一次区块链查询。** + +我们会使用[官方云服务](./OfficialServerAccess.md)来完成这次快速体验。云服务是只读的，不需要安装任何依赖、不需要配置钱包、不需要申请 API Key——你只需要把一段配置复制到 AI 客户端，重启，然后开始提问。 + +--- + +## 准备工作 + +在开始之前，确保你已经安装了以下工具： + +- 所有支持 MCP 的 AI 客户端：例如 [Claude Desktop](https://claude.ai/download)、[Claude Code](https://docs.anthropic.com/en/docs/claude-code) 或 [Cursor](https://cursor.sh) 。 +- **Node.js v20.0.0 或更高版本**（用于执行 `npx` 命令）（[Node.js 下载](https://nodejs.org/)） + +验证 Node.js 版本： + +```bash +node --version # 应输出 v20.x.x 或更高 +``` + +--- + +## 添加配置 + +选择你使用的 AI 客户端，把对应的配置复制进去： + + + + +打开配置文件： +- **macOS**：`~/Library/Application Support/Claude/claude_desktop_config.json` +- **Windows**：`%APPDATA%\Claude\claude_desktop_config.json` + +添加以下内容： + +```json +{ + "mcpServers": { + "mcp-server-tron": { + "command": "npx", + "args": [ + "mcp-remote", + "https://tron-mcp-server.bankofai.io/mcp" + ] + } + } +} +``` + + + + +在终端执行： + +```bash +claude mcp add --transport http mcp-server-tron https://tron-mcp-server.bankofai.io/mcp +``` + + + + +在项目根目录添加 `.cursor/mcp.json`： + +```json +{ + "mcpServers": { + "mcp-server-tron": { + "url": "https://tron-mcp-server.bankofai.io/mcp" + } + } +} +``` + + + + +--- + +## 重启并测试 + +保存配置后，**完全退出并重新启动** AI 客户端。重启后客户端会自动连接 TRON MCP Server。 + +然后在对话框中输入你的第一条查询： + +``` +查一下 TRON 地址 TXyz... 的 TRX 余额 +``` + +如果一切正常，AI 会自动调用 `get_balance` 工具并返回该地址的 TRX 余额。看到结果，说明你已经成功接入了。 + +:::info 关于云服务的能力范围 +以上配置连接的是**官方云只读服务**，支持所有查询类操作（查余额、查交易、查合约状态等），但不支持写操作（转账、合约调用等）。如需完整的读写功能，请参阅[本地私有化部署](./LocalPrivatizedDeployment.md)。 +::: + +--- + +## 继续探索 + +接入成功后，不妨多试几个问法，感受一下 TRON MCP Server 的能力范围： + +| 试试这样说 | 它会做什么 | +| :--- | :--- | +| "查一下地址 TXyz... 的 USDT 余额" | 查询指定地址的 TRC20 代币余额 | +| "查一下交易哈希 abc123... 的详细信息" | 获取交易详情、资源消耗和状态 | +| "TRON 主网当前最新区块号是多少？" | 查询最新区块高度和链信息 | +| "查询 TRON 主网当前的能量和带宽价格" | 获取实时资源价格 | +| "把地址 41abc... 转换成 Base58 格式" | 地址格式转换 | +| "查看账户 TXyz... 的资源使用情况" | 获取账户的能量、带宽和质押详情 | +| "获取合约 TXyz... 的 ABI" | 读取智能合约接口定义 | +| "查询合约 TXyz... 最近触发的事件" | 获取合约事件日志 | + +这些只是冰山一角。完整的 95 个工具和 6 个提示词模板，请查阅 [完整能力清单](./ToolList.md)。 + +--- + +## 下一步 + +你已经完成了第一次链上交互。接下来取决于你想做什么： + +- 需要转账、合约调用等写操作？ → [本地私有化部署](./LocalPrivatizedDeployment.md) +- 想深入了解云服务的配置选项（如 TronGrid API Key）？ → [官方云服务接入](./OfficialServerAccess.md) +- 想看所有可用工具的详细说明？ → [完整能力清单](./ToolList.md) diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/ToolList.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/ToolList.md new file mode 100644 index 00000000..dd5dd885 --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/ToolList.md @@ -0,0 +1,367 @@ +# 完整能力清单 + +TRON MCP Server 提供 **95 个工具**、**6 个提示词模板**和 **1 个资源定义**。这个页面是完整的能力清单——当你想知道"它到底能做什么"或者"某个工具叫什么名字"时，来这里查就对了。 + +## 先了解两个概念 + +在浏览工具列表之前，有两件事需要知道： + +:::info 读取 vs 写入 +每个工具都标记了**模式**——"读取"或"写入"： + +- **读取工具**：只查询链上数据，不影响任何状态。在云服务和本地部署中均可使用。 +- **写入工具**：会修改区块链状态（转账、质押、合约调用等）。仅在本地部署且配置了钱包后才可使用。 + +如果你没有配置钱包，写入工具不会出现在 AI 的可用工具列表中——它们会被自动隐藏，不用担心误触。 +::: + +:::tip network 参数 +大多数工具都有一个可选的 `network` 参数，用于指定目标网络（`mainnet`、`nile` 或 `shasta`）。不指定时默认走主网。在测试阶段，建议每次都明确指定 `nile`，避免意外操作主网。 +::: + +--- + +## 工具（共 95 个） + +### 钱包与地址 + +管理钱包身份和地址格式转换。 + +| 工具名称 | 描述 | 关键参数 | 模式 | +| :--- | :--- | :--- | :--- | +| `get_wallet_address` | 获取当前已配置钱包的地址（Base58 和 Hex 格式） | - | 读取 | +| `list_wallets` | 列出所有可用钱包的 ID 和地址（Agent Wallet 模式） | - | 读取 | +| `select_wallet` | 在运行时切换活跃钱包（Agent Wallet 模式） | `walletId` | 写入 | +| `sign_message` | 使用已配置的钱包对任意消息进行签名 | `message` | 写入 | +| `convert_address` | 在 Hex（`41...`/`0x...`）和 Base58（`T...`）格式之间转换地址 | `address` | 读取 | + +**试试这样说：** "我配置的钱包地址是什么？" · "把地址 41a1e39aefa49eb34bb8f8abe226e1de2c6c2e79 转换成 Base58 格式" · "列出我所有可用的钱包" + +--- + +### 网络与链 + +查询网络级别的基础信息。 + +| 工具名称 | 描述 | 关键参数 | 模式 | +| :--- | :--- | :--- | :--- | +| `get_chain_info` | 获取当前区块号和链 ID | `network` | 读取 | +| `get_chain_parameters` | 获取当前能量和带宽单价 | `network` | 读取 | +| `get_supported_networks` | 列出所有支持的 TRON 网络 | - | 读取 | + +**试试这样说：** "TRON 主网当前的区块高度是多少？" · "现在能量和带宽价格是多少？" + +--- + +### 区块 + +按区块号或哈希查询区块内容。 + +| 工具名称 | 描述 | 关键参数 | 模式 | +| :--- | :--- | :--- | :--- | +| `get_block` | 按区块号或哈希获取区块详情 | `blockIdentifier`, `network` | 读取 | +| `get_latest_block` | 获取最新区块信息 | `network` | 读取 | + +**试试这样说：** "查看 TRON 区块 65000000 的详情" · "最新的 TRON 区块里有什么？" + +--- + +### 交易 + +获取交易的完整信息和执行结果。 + +| 工具名称 | 描述 | 关键参数 | 模式 | +| :--- | :--- | :--- | :--- | +| `get_transaction` | 按哈希获取完整交易详情 | `txHash`, `network` | 读取 | +| `get_transaction_info` | 获取交易收据，包括资源消耗（能量/带宽） | `txHash`, `network` | 读取 | + +**试试这样说：** "查一下交易 abc123... 的详情" · "这笔交易消耗了多少能量？" + +--- + +### 余额 + +查询地址的 TRX 和代币持仓。 + +| 工具名称 | 描述 | 关键参数 | 模式 | +| :--- | :--- | :--- | :--- | +| `get_balance` | 查询地址的 TRX 余额 | `address`, `network` | 读取 | +| `get_token_balance` | 查询地址的 TRC20 代币余额 | `address`, `tokenAddress`, `network` | 读取 | + +**试试这样说：** "查一下 TXyz... 的 TRX 余额" · "这个地址持有多少 USDT？" + +--- + +### 转账 + +发送 TRX 和 TRC20 代币。这是最常用的写入操作——执行前 AI 会与你确认详情。 + +| 工具名称 | 描述 | 关键参数 | 模式 | +| :--- | :--- | :--- | :--- | +| `transfer_trx` | 向地址转账 TRX | `to`, `amount`, `network` | 写入 | +| `transfer_trc20` | 向地址转账 TRC20 代币 | `tokenAddress`, `to`, `amount`, `network` | 写入 | + +**试试这样说：** "向地址 TXyz... 转账 50 TRX" · "在 Nile 测试网上向 TXyz... 发送 100 USDT" + +:::warning +转账操作不可撤销。AI 在执行前会与你确认详情。 +::: + +--- + +### 智能合约 + +从读取合约状态到部署新合约，覆盖智能合约交互的全流程。 + +| 工具名称 | 描述 | 关键参数 | 模式 | +| :--- | :--- | :--- | :--- | +| `read_contract` | 调用智能合约的只读（`view`/`pure`）函数 | `contractAddress`, `functionName`, `args`, `abi`, `network` | 读取 | +| `write_contract` | 执行智能合约的状态变更函数 | `contractAddress`, `functionName`, `args`, `abi`, `value`, `network` | 写入 | +| `deploy_contract` | 将智能合约部署到网络 | `abi`, `bytecode`, `args`, `name`, `network`, `feeLimit` | 写入 | +| `estimate_energy` | 预估合约调用的能量消耗 | `address`, `functionName`, `args`, `abi`, `network` | 读取 | +| `multicall` | 在单次批量请求中执行多个只读调用 | `calls`, `network`, `multicallAddress`, `version` | 读取 | +| `get_contract` | 获取合约原始元数据（ABI 和字节码） | `contractAddress`, `network` | 读取 | +| `get_contract_info` | 获取合约高级信息（ABI、函数列表） | `contractAddress`, `network` | 读取 | +| `fetch_contract_abi` | 从链上获取已验证合约的 ABI 数组 | `contractAddress`, `network` | 读取 | +| `update_contract_setting` | 更新合约的 `consume_user_resource_percent`（仅创建者） | `contractAddress`, `consumeUserResourcePercent`, `network` | 写入 | +| `update_energy_limit` | 更新合约的 `originEnergyLimit`（仅创建者） | `contractAddress`, `originEnergyLimit`, `network` | 写入 | +| `clear_abi` | 清除合约的链上 ABI 元数据（仅创建者） | `contractAddress`, `network` | 写入 | + +**试试这样说：** "调用合约 TXyz... 的 `balanceOf` 函数" · "获取合约 TXyz... 的 ABI" · "预估调用 `transfer` 函数需要多少能量" · "把这个合约部署到 Nile 测试网" + +--- + +### 账户管理 + +查询账户的完整信息，包括余额、资源、权限和委托关系。 + +| 工具名称 | 描述 | 关键参数 | 模式 | +| :--- | :--- | :--- | :--- | +| `get_account` | 获取完整账户信息（余额、资源、权限） | `address`, `network` | 读取 | +| `get_account_balance` | 查询特定区块高度时的 TRX 余额（历史查询） | `address`, `blockHash`, `blockNumber`, `network` | 读取 | +| `get_account_net` | 获取账户的带宽资源信息 | `address`, `network` | 读取 | +| `get_account_resource` | 获取能量、带宽、冻结余额和委托信息 | `address`, `network` | 读取 | +| `get_delegated_resource` | 查询两个账户之间的委托资源情况 | `fromAddress`, `toAddress`, `network` | 读取 | +| `get_delegated_resource_index` | 查询账户的资源委托索引 | `address`, `network` | 读取 | +| `generate_account` | 离线生成新的 TRON 密钥对（不会在链上激活） | - | 读取 | +| `validate_address` | 验证 TRON 地址并检测其格式 | `address` | 读取 | +| `create_account` | 在网络上激活新账户（消耗带宽） | `address`, `network` | 写入 | +| `update_account` | 更新账户名称（只能设置一次） | `accountName`, `network` | 写入 | +| `account_permission_update` | 更新账户权限（多签配置） | `ownerPermission`, `activePermissions`, `witnessPermission`, `network` | 写入 | + +**试试这样说：** "查看地址 TXyz... 的完整账户详情" · "这个地址有多少能量和带宽？" · "帮我生成一个新的 TRON 地址" · "验证一下这个地址是否合法" + +--- + +### 账户数据（TronGrid API） + +这些工具通过 TronGrid 索引 API 提供更丰富的账户数据——交易历史、代币持仓等需要索引的数据都在这里。 + +| 工具名称 | 描述 | 关键参数 | 模式 | +| :--- | :--- | :--- | :--- | +| `get_account_info` | 从 TronGrid 获取综合账户信息 | `address`, `network` | 读取 | +| `get_account_transactions` | 获取账户的交易历史 | `address`, `limit`, `fingerprint`, `network` | 读取 | +| `get_account_trc20_transactions` | 获取 TRC20 转账历史 | `address`, `contractAddress`, `limit`, `fingerprint`, `network` | 读取 | +| `get_account_internal_transactions` | 获取账户的内部交易历史 | `address`, `limit`, `fingerprint`, `network` | 读取 | +| `get_account_trc20_balances` | 获取账户持有的所有 TRC20 代币余额 | `address`, `network` | 读取 | + +**试试这样说：** "显示地址 TXyz... 最近的交易" · "这个地址持有哪些 TRC20 代币？" · "查看这个地址的 USDT 转账历史" + +:::info 分页 +返回列表的工具支持 `limit` 和 `fingerprint` 参数进行分页。使用上一次响应中的 `fingerprint` 值获取下一页数据。 +::: + +--- + +### 合约数据（TronGrid API） + +查询合约级别的交易历史和代币持有者信息。 + +| 工具名称 | 描述 | 关键参数 | 模式 | +| :--- | :--- | :--- | :--- | +| `get_contract_transactions` | 获取合约的交易历史 | `address`, `limit`, `fingerprint`, `network` | 读取 | +| `get_contract_internal_transactions` | 获取合约的内部交易历史 | `address`, `limit`, `fingerprint`, `network` | 读取 | +| `get_trc20_token_holders` | 获取 TRC20 代币的持有者列表 | `address`, `limit`, `fingerprint`, `network` | 读取 | + +**试试这样说：** "这个 TRC20 代币的前几大持有者是谁？" · "显示这个合约的最近交易" + +--- + +### 资源委托（Stake 2.0） + +将质押获得的能量或带宽委托给其他地址，或查询委托关系。 + +| 工具名称 | 描述 | 关键参数 | 模式 | +| :--- | :--- | :--- | :--- | +| `delegate_resource` | 将质押的能量或带宽委托给其他地址 | `receiverAddress`, `amount`, `resource`, `lock`, `lockPeriod`, `network` | 写入 | +| `undelegate_resource` | 撤销已委托的资源 | `receiverAddress`, `amount`, `resource`, `network` | 写入 | +| `get_can_delegated_max_size` | 获取地址可委托的最大 TRX 数量 | `address`, `resource`, `network` | 读取 | +| `get_delegated_resource_v2` | 获取两个地址之间的委托资源详情 | `fromAddress`, `toAddress`, `network` | 读取 | +| `get_delegated_resource_account_index_v2` | 获取委托资源账户索引 | `address`, `network` | 读取 | + +**试试这样说：** "向地址 TXyz... 委托价值 500 TRX 的能量" · "我最多可以委托多少资源？" · "显示我所有的资源委托情况" + +--- + +### 质押（Stake 2.0） + +冻结 TRX 获取能量或带宽，解冻释放 TRX。这是 TRON 资源模型的核心操作。 + +| 工具名称 | 描述 | 关键参数 | 模式 | +| :--- | :--- | :--- | :--- | +| `freeze_balance_v2` | 冻结（质押）TRX 以获取能量或带宽 | `amount`, `resource`, `network` | 写入 | +| `unfreeze_balance_v2` | 解冻（解质押）TRX 以释放资源 | `amount`, `resource`, `network` | 写入 | +| `withdraw_expire_unfreeze` | 将已到期的解冻余额提取回可用 TRX | `network` | 写入 | +| `cancel_all_unfreeze_v2` | 取消待处理的解冻并立即重新质押 | `network` | 写入 | +| `get_available_unfreeze_count` | 获取剩余解冻操作次数（最多同时 32 个） | `address`, `network` | 读取 | +| `get_can_withdraw_unfreeze_amount` | 获取在指定时间戳可提取的解冻 TRX 数量 | `address`, `timestampMs`, `network` | 读取 | + +**试试这样说：** "质押 1000 TRX 换取能量" · "解除 500 TRX 的带宽质押" · "我有已到期可提取的解冻余额吗？" + +:::info 关于 Stake 2.0 +TRON 使用 Stake 2.0 进行资源管理。冻结 TRX 后可获得能量（用于智能合约执行）或带宽（用于普通交易）。解冻后有约 14 天的等待期，之后才能将 TRX 提取回来。 +::: + +--- + +### 治理与超级代表 + +查看超级代表列表、投票、管理奖励和佣金。 + +| 工具名称 | 描述 | 关键参数 | 模式 | +| :--- | :--- | :--- | :--- | +| `list_witnesses` | 列出网络上所有超级代表 | `network` | 读取 | +| `get_paginated_witnesses` | 分页获取当前活跃超级代表列表 | `offset`, `limit`, `network` | 读取 | +| `get_next_maintenance_time` | 获取下次维护窗口时间戳（投票统计时间） | `network` | 读取 | +| `get_reward` | 查询地址的未领取投票奖励 | `address`, `network` | 读取 | +| `get_brokerage` | 查询超级代表的佣金比例 | `witnessAddress`, `network` | 读取 | +| `create_witness` | 申请成为超级代表候选人（需花费 9999 TRX） | `url`, `network` | 写入 | +| `update_witness` | 更新超级代表的网站 URL | `url`, `network` | 写入 | +| `vote_witness` | 使用冻结的 TRX 为超级代表投票 | `votes`, `network` | 写入 | +| `withdraw_balance` | 提取累积的超级代表投票奖励 | `network` | 写入 | +| `update_brokerage` | 更新超级代表佣金比例 | `brokerage`, `network` | 写入 | + +**试试这样说：** "列出 TRON 上前 27 个超级代表" · "我有多少未领取的投票奖励？" · "给超级代表 TXyz... 投 1000 票" + +--- + +### 提案 + +TRON 的链上治理机制——超级代表可以创建和投票表决网络参数变更提案。 + +| 工具名称 | 描述 | 关键参数 | 模式 | +| :--- | :--- | :--- | :--- | +| `list_proposals` | 列出所有治理提案 | `network` | 读取 | +| `get_proposal` | 按 ID 获取提案详情 | `proposalId`, `network` | 读取 | +| `create_proposal` | 创建治理提案（仅超级代表） | `parameters`, `network` | 写入 | +| `approve_proposal` | 投票批准/反对提案 | `proposalId`, `approve`, `network` | 写入 | +| `delete_proposal` | 删除治理提案（仅创建者） | `proposalId`, `network` | 写入 | + +**试试这样说：** "显示所有 TRON 活跃治理提案" · "提案 #42 的详细内容是什么？" + +--- + +### 事件 + +查询智能合约触发的事件日志——监控链上活动的核心能力。 + +| 工具名称 | 描述 | 关键参数 | 模式 | +| :--- | :--- | :--- | :--- | +| `get_events_by_transaction_id` | 获取特定交易触发的事件 | `transactionId`, `network` | 读取 | +| `get_events_by_contract_address` | 获取特定合约触发的事件 | `contractAddress`, `eventName`, `limit`, `network` | 读取 | +| `get_events_by_block_number` | 获取特定区块中触发的事件 | `blockNumber`, `network` | 读取 | +| `get_events_of_latest_block` | 获取最新区块中的事件 | `network` | 读取 | + +**试试这样说：** "交易 abc123... 触发了哪些事件？" · "显示 USDT 合约最近的 Transfer 事件" · "最新区块里发生了哪些事件？" + +--- + +### 内存池 + +查看尚未被打包的待处理交易。 + +| 工具名称 | 描述 | 关键参数 | 模式 | +| :--- | :--- | :--- | :--- | +| `get_pending_transactions` | 获取内存池中的待处理交易 ID | `network` | 读取 | +| `get_transaction_from_pending` | 获取内存池中的特定交易详情 | `txId`, `network` | 读取 | +| `get_pending_size` | 获取当前待处理交易数量 | `network` | 读取 | + +**试试这样说：** "TRON 内存池中有多少笔待处理交易？" · "交易 abc123... 还在待处理中吗？" + +--- + +### 节点 + +查询 TRON 网络节点信息。 + +| 工具名称 | 描述 | 关键参数 | 模式 | +| :--- | :--- | :--- | :--- | +| `list_nodes` | 列出所有已连接的节点地址 | `network` | 读取 | +| `get_node_info` | 获取已连接全节点的详细信息（版本、资源等） | `network` | 读取 | + +--- + +### 全节点查询 API + +这些工具直接对应 TRON 全节点的 RPC 方法，适合需要精确控制查询参数的高级用户。日常使用中，上面的高级工具（如 `get_block`、`get_transaction`）已经够用，但如果你需要批量查区块、查历史价格或做更底层的操作，这些工具会很有用。 + +| 工具名称 | 描述 | 关键参数 | 模式 | +| :--- | :--- | :--- | :--- | +| `get_block_by_num` | 按区块高度查询区块 | `num`, `network` | 读取 | +| `get_block_by_id` | 按区块哈希查询区块 | `value`, `network` | 读取 | +| `get_block_by_latest_num` | 获取最近 N 个区块（已固化） | `num`, `network` | 读取 | +| `get_block_by_limit_next` | 获取高度区间 `[startNum, endNum)` 内的区块 | `startNum`, `endNum`, `network` | 读取 | +| `get_now_block` | 获取当前最新区块 | `network` | 读取 | +| `get_transaction_by_id` | 按哈希查询交易 | `value`, `network` | 读取 | +| `get_transaction_info_by_id` | 按哈希查询交易收据 | `value`, `network` | 读取 | +| `get_transaction_info_by_block_num` | 获取某区块中所有交易的收据 | `num`, `network` | 读取 | +| `get_energy_prices` | 查询能量单价历史数据 | `network` | 读取 | +| `get_bandwidth_prices` | 查询带宽单价历史数据 | `network` | 读取 | +| `get_burn_trx` | 查询交易手续费累计销毁的 TRX 总量 | `network` | 读取 | +| `get_approved_list` | 查询对某交易签名的账户列表 | `transaction`, `network` | 读取 | +| `get_block_balance` | 获取某区块中所有余额变动操作 | `hash`, `number`, `network` | 读取 | + +--- + +### 广播与交易构建 + +手动构建和广播交易——适合需要离线签名或自定义交易流程的高级场景。 + +| 工具名称 | 描述 | 关键参数 | 模式 | +| :--- | :--- | :--- | :--- | +| `broadcast_transaction` | 广播已签名的交易（JSON 格式） | `transaction`, `network` | 写入 | +| `broadcast_hex` | 广播已签名的交易（十六进制编码的 protobuf 格式） | `transaction`, `network` | 写入 | +| `create_transaction` | 创建未签名的 TRX 转账交易 | `ownerAddress`, `toAddress`, `amount`, `network` | 写入 | + +**试试这样说：** "创建一个从我的地址向 TXyz... 转 10 TRX 的未签名交易" · "广播这个已签名的交易" + +--- + +## 提示词模板（共 6 个） + +工具是单个操作，而提示词模板是**预定义的多步工作流**。当你触发一个提示词时，AI 会按照预设的流程串联多个工具来完成任务——比如转账前先检查余额、预估费用、请你确认，然后才执行。 + +| 提示词名称 | 描述 | 关键参数 | 是否需要钱包 | +| :--- | :--- | :--- | :--- | +| `prepare_transfer` | 安全准备和执行代币转账，含余额检查、费用预估和用户确认 | `tokenType`, `recipient`, `amount`, `network`, `tokenAddress` | 是 | +| `interact_with_contract` | 安全执行合约写操作，含参数验证、费用预估和确认步骤 | `contractAddress`, `functionName`, `args`, `value`, `network` | 是 | +| `diagnose_transaction` | 分析交易状态，识别失败原因，提供调试建议 | `txHash`, `network` | 否 | +| `explain_tron_concept` | 通过示例解释 TRON 和区块链概念（能量、带宽、质押等） | `concept` | 否 | +| `analyze_wallet` | 全面概览钱包资产、余额和活动情况 | `address`, `network`, `tokens` | 否 | +| `check_network_status` | 检查当前网络健康状况、出块情况和资源价格 | `network` | 否 | + +**试试这样说：** +- "帮我安全地向 TXyz... 转账 100 TRX" → 触发 `prepare_transfer` +- "分析一下交易 abc123... 为什么失败了" → 触发 `diagnose_transaction` +- "解释一下 TRON 上的能量是怎么运作的" → 触发 `explain_tron_concept` +- "给我全面分析一下钱包 TXyz..." → 触发 `analyze_wallet` + +--- + +## 资源（共 1 个） + +资源是静态参考数据，AI 可以随时查询以获取上下文信息。 + +| 资源名称 | URI | 描述 | +| :--- | :--- | :--- | +| `supported_networks` | `tron://networks` | 返回所有支持的 TRON 网络及其配置信息（RPC 地址、浏览器链接等） | diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md index bbc57283..9705fd73 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md @@ -1,262 +1,228 @@ # BANK OF AI Skills -BANK OF AI Skills 是一组为 AI 智能体设计的可复用技能包。每个技能封装了特定领域的知识（如 DEX 交易、链上数据查询、支付协议等），以 `SKILL.md` 为核心，为智能体提供分步操作指引、可执行脚本和常见使用模式的示例，让智能体能够像专业用户一样完成链上操作。 +BANK OF AI Skills 是一组为 AI 智能体设计的现成技能包，覆盖 TRON 生态的核心 DeFi 场景——DEX 交易、永续合约、链上数据查询、支付协议。每个技能封装了完整的业务工作流：从如何调用 API、按什么顺序执行步骤，到如何处理授权、怎样保护用户资产，全部内置在 `SKILL.md` 和配套脚本中。 -BANK OF AI Skills 支持集成至 OpenClaw、Claude Code、Claude Desktop、Cursor 等兼容 MCP 的 AI Agents。你无需编写代码，只需用自然语言描述任务，智能体便会自动匹配并执行对应的技能。 +你无需编写代码，只需用自然语言告诉 AI 你想做什么，AI 会自动找到对应的技能并执行。 -:::warning 安全前置声明 — 请在使用任何 Skill 之前阅读 -BankOfAI Skills 可以操作**真实的链上资产**。区块链交易一旦上链**不可撤销**，没有"撤销"按钮，没有客服回滚，转错地址的资金也无法追回。在你开始之前，请牢记三条铁律： +:::warning 使用任何 Skill 之前，请先阅读 +BANK OF AI Skills 可以操作**真实的链上资产**。区块链交易一旦上链**不可撤销**——没有"撤销"按钮，没有客服回滚，转错地址的资金无法追回。使用前请牢记三条规则： -1. **私钥永远不要出现在聊天窗口、提示词或配置文件中。** 只通过环境变量传递（如 `TRON_PRIVATE_KEY`、`PRIVATE_KEY`）。不要将私钥粘贴到任何 AI 对话中，不要硬编码在脚本里，更不要提交到版本控制系统。一旦私钥意外泄露，请立即更换。 -2. **先测试网，后主网。** 每一个新操作——无论是兑换、转账还是添加流动性——都必须先在 Nile 或 Shasta 测试网上验证通过，再切换到主网执行。测试网代币没有真实价值，你可以放心实验，不会产生任何经济损失。 -3. **写操作必须人工确认。** Agent 执行任何链上交易前，应向你展示完整的操作详情——包括接收地址、代币类型、数量、预估手续费和滑点——并等待你的明确确认后才能广播交易。切勿对写操作启用自动执行。 +1. **私钥永远不要出现在聊天窗口或配置文件中。** 只通过环境变量传递（如 `TRON_PRIVATE_KEY`）。私钥一旦泄露，请立即将资产转移到新钱包。 +2. **先测试网，后主网。** 每一个新操作都必须先在 Nile 或 Shasta 测试网上验证，再切换到主网执行。 +3. **写操作必须人工确认。** AI 在执行任何链上交易前，应向你展示完整的操作详情并等待你的明确确认。 ::: +--- -## 技能列表 - -以下是当前可用的技能，涵盖 DEX 交易、链上数据查询、支付协议和 NFT 等场景： - -| SKILL | 功能 | -| :--- | :--- | -| **x402-payment** | x402 支付技能，用于在受支持的链上调用付费智能体和付费 API。 | -| **sunswap** | SunSwap DEX 技能，用于余额查询、报价、兑换及流动性相关工作流。 | -| **tronscan-skill** | 通过 TronScan API 进行 TRON 区块链数据查询，支持账户、交易、代币、区块及全网统计。 | - +## 可用技能一览 -## 快速开始 +| Skill | 版本 | 功能概述 | 可选凭证 | +| :--- | :--- | :--- | :--- | +| **sunswap** | v2.0.0 | SunSwap DEX 交易——余额、报价、兑换、V2/V3 流动性 | `TRON_PRIVATE_KEY` | +| **sunperp-skill** | v1.0.0 | SunPerp 永续合约——行情、下单、仓位、提现 | `SUNPERP_ACCESS_KEY` + `SUNPERP_SECRET_KEY` | +| **tronscan-skill** | v1.0.0 | TronScan 链上数据查询——账户、交易、代币、区块 | `TRONSCAN_API_KEY` | +| **x402-payment** | v1.4.0 | x402 协议支付——调用付费 API 和付费智能体 | `TRON_PRIVATE_KEY` 或 `EVM_PRIVATE_KEY` | +| **ainft-skill** | v1.1.1 | AINFT 余额查询、订单记录、TRC20 充值 | `AINFT_API_KEY` | -以 `OpenClaw + OpenClaw 扩展` 为例。 +--- -### 1. 安装 +## 安装 -安装 [OpenClaw 扩展](https://github.com/BofAI/openclaw-extension)，它会自动安装集成层、连接 MCP 服务器并安装技能仓库。 +最简单的安装方式是使用 **OpenClaw Extension**——一键安装所有组件，自动配置技能目录，AI 开箱即用： ```bash +# 方式一：直接运行（适合信任来源） curl -fsSL https://raw.githubusercontent.com/BofAI/openclaw-extension/refs/heads/main/install.sh | bash -``` -如果你希望先检查安装脚本再运行： - -```bash +# 方式二：先检查脚本再运行（推荐） git clone https://github.com/BofAI/openclaw-extension.git cd openclaw-extension ./install.sh ``` -### 2. 验证 +安装完成后，技能会被放置到 `~/.openclaw/skills/` 目录，OpenClaw 自动发现并加载。 -安装完成后，验证技能仓库是否可用。 - -检查本地技能目录： +安装后验证技能是否就绪： ```bash ls ~/.openclaw/skills ``` -你应该能看到 `sunswap`、`x402-payment`、`x402-payment-demo`、`tronscan-skill` 等条目。 - -然后在 OpenClaw 中通过提示词验证： - -```text -阅读 sunswap 技能，告诉我这个技能能做什么。 -``` +你应该能看到 `sunswap`、`sunperp-skill`、`tronscan-skill`、`x402-payment`、`ainft-skill` 等目录。 -### 3. 首次使用 +### 其他平台安装 -从一个简单的只读工作流开始。调用技能有两种方式： - -**显式调用** — 直接告诉智能体要读取哪个技能文件。适用于你已知目标技能或需要确定性行为的场景： - -```text -阅读 sunswap 技能，帮我查看 100 USDT 在 SunSwap 上能兑换多少 TRX。 -``` +如果你使用 Claude Code、Cursor 或其他支持 Skills 的 AI 工具，也可以手动安装： -**隐式触发** — 描述任务，让智能体自动匹配并激活对应技能。适用于技能已安装且请求能明确对应某个工作流的场景： +**Claude Code：** -```text -帮我查一下现在 100 USDT 在 SunSwap 能换多少 TRX。 +```bash +git clone https://github.com/BofAI/skills.git /tmp/bofai-skills +mkdir -p ~/.config/claude-code/skills +cp -r /tmp/bofai-skills/* ~/.config/claude-code/skills/ ``` -:::tip 使用建议 -* **提供清晰的上下文**：比如"使用 `xxx` 技能处理 `yyy` 任务"。 -* **指定参数**：如果技能需要特定信息（如金额、币种、日期），在指令中一次性给全，能显著提高成功率。 -* **从只读操作开始**：首次使用建议先从查询类操作入手（如余额查询、价格报价），熟悉技能运作方式后再尝试写操作（如兑换、转账）。 -::: +Claude Code 启动时会自动加载这些技能。 +**Cursor：** -## 其他平台安装 +```bash +# 克隆到项目根目录 +git clone https://github.com/BofAI/skills.git .cursor/skills +``` -### OpenClaw +在 Cursor Chat 中，使用 `@` 符号引用特定 `SKILL.md` 文件提供上下文，或将技能路径添加到 `.cursorrules`。 -OpenClaw 提供最完整的集成体验，自动连接技能和 MCP 依赖。 +**通用方式（任何 AI 工具）：** ```bash -curl -fsSL https://raw.githubusercontent.com/BofAI/openclaw-extension/refs/heads/main/install.sh | bash +git clone https://github.com/BofAI/skills.git ~/bofai-skills ``` -### Claude Code - -1. 克隆仓库： - ```bash - git clone https://github.com/BofAI/skills.git /tmp/bofai-skills - ``` -2. 将技能复制到 Claude Code 配置目录以实现自动发现： - ```bash - mkdir -p ~/.config/claude-code/skills - cp -r /tmp/bofai-skills/* ~/.config/claude-code/skills/ - ``` -3. Claude Code 启动时将自动加载这些技能。 - -### Cursor +然后在对话中显式告诉 AI 读取某个技能文件： -1. 将仓库克隆到项目根目录： - ```bash - git clone https://github.com/BofAI/skills.git .cursor/skills - ``` -2. 如需项目范围内可用，可将技能路径添加到 `.cursorrules`，或在 Cursor Chat 中使用 `@` 符号引用特定的 `SKILL.md` 文件来提供上下文。 +``` +请阅读 ~/bofai-skills/sunswap/SKILL.md，帮我查询 TRX 当前价格。 +``` +--- +## 验证安装结果 +安装完成后，从只读操作开始是最好的起点——不需要私钥，零风险，适合熟悉技能的工作方式。 -## 各技能使用示例 +在客户端输入： -### 操作类型说明 +``` +100 USDT 在 SunSwap 上能换多少 TRX？ +``` -- 🟢 **Read** — 只读查询，不会产生链上交易 -- ⚠️ **Write** — 会发起链上交易（需要用户确认） +``` +帮我查一下 BTC-USDT 永续合约的当前行情。 +``` --- -### x402-payment +## 各技能使用示例 -**调用付费端点（⚠️ Write）：** -> 使用 x402 协议调用这个付费智能体端点。 - ---- +每个示例标注了操作类型： +- 🟢 **只读** — 不产生链上交易，不需要私钥 +- ⚠️ **写操作** — 会发起链上交易，执行前需要用户确认 ### sunswap -**余额查询（🟢 Read）：** -> 帮我查看我在 SunSwap 上的 TRX 和 USDT 余额。 - -**价格查询（🟢 Read）：** -> TRX 当前的价格是多少？ - -**兑换报价（🟢 Read）：** -> 100 USDT 在 SunSwap 上能兑换多少 TRX？ +``` +# 🟢 查询余额 +帮我查看我的 TRX 和 USDT 余额。 -**执行兑换（⚠️ Write）：** -> 在 SunSwap 上将 100 TRX 兑换为 USDT。 +# 🟢 查询价格 +TRX 现在的价格是多少？ -**流动性操作（⚠️ Write）：** -> 在 SunSwap V2 池中添加 100 TRX 和 15 USDT 的流动性。 +# 🟢 兑换报价 +100 USDT 在 SunSwap 上能兑换多少 TRX？ ---- +# ⚠️ 执行兑换 +在 SunSwap Nile 测试网上把 100 TRX 兑换成 USDT。 -### tronscan-skill +# ⚠️ 添加流动性 +在 SunSwap V2 的 TRX/USDT 池中添加 100 TRX 和 15 USDT 的流动性。 -**账户查询（🟢 Read）：** -> 帮我查询地址 TXXXXXXXXXXXXXXXXXXXXXXX 的账户信息。 +# 🟢 查看 V3 仓位 +帮我查看我当前所有的 SunSwap V3 流动性仓位。 -**钱包组合（🟢 Read）：** -> 显示该地址的钱包组合和 USD 估值。 +# ⚠️ 收取手续费 +帮我收取 V3 仓位 #12345 的手续费奖励。 +``` -**交易验证（🟢 Read）：** -> 查询这笔交易哈希的详情和执行状态。 +### sunperp-skill -**代币排名（🟢 Read）：** -> 显示市值排名前 10 的 TRC20 代币。 +``` +# 🟢 查看行情 +BTC-USDT 永续合约的当前价格、24h 涨跌幅和资金费率是多少？ -**全网概览（🟢 Read）：** -> 给我一份 TRON 全网概览 — 交易吞吐量、超级代表和供应量指标。 +# 🟢 查看账户 +我的 SunPerp 账户余额和可用保证金是多少？ -## 安全规范 +# 🟢 查看持仓 +我当前有哪些未平仓位？显示开仓均价、未实现盈亏和强平价。 -链上操作不可逆，以下不是建议，是**必须遵守的规则**。 +# ⚠️ 开仓 +以市价在 SunPerp 开 1 张 BTC-USDT 多单，10 倍杠杆，设置 5% 止损。 -### 私钥管理 +# ⚠️ 平仓 +平掉我所有的 BTC-USDT 仓位。 +# ⚠️ 提现 +从 SunPerp 提现 10 USDT 到我的链上地址。 ``` -✗ 永远不要这样做： -"用私钥 a]K9x...z3 帮我执行兑换" → 私钥暴露在聊天记录/日志中 -✓ 正确做法： -export TRON_PRIVATE_KEY="你的私钥" → 通过环境变量传递 -``` +### tronscan-skill -原则：**私钥绝不出现在提示词、配置文件、聊天记录中的任何地方。** Agent 应通过环境变量或安全密钥管理服务获取。 +``` +# 🟢 账户查询 +帮我查询地址 TDqSquXBgUCLYvYC4XZgrprLK589dkhSCf 的完整账户信息和持仓。 -### 网络环境隔离 +# 🟢 交易查询 +查询这笔交易哈希的详情：abc123... -| 操作阶段 | 推荐网络 | 说明 | -|---------|---------|------| -| 首次使用/学习 | Nile 测试网 | 零成本试错，随便玩 | -| 功能验证 | Shasta 测试网 | 更接近主网环境 | -| 正式操作 | 主网 | 确认无误后再切换 | +# 🟢 代币信息 +显示市值排名前 10 的 TRC20 代币。 -切换网络时务必**显式声明**，避免 Agent 在错误的网络上执行交易： +# 🟢 全网概览 +给我一份 TRON 全网概览：当前 TPS、超级代表数量、账户总数。 -```text -"切换到 TRON 主网，然后帮我查询余额。" +# 🟢 转账记录 +查询地址 TXX... 最近 20 笔 USDT 转账记录。 ``` -### DeFi 操作安全 - -- **滑点保护**：执行 Swap 时务必设置滑点容忍度（建议 0.5%–1%），防止价格波动导致损失 -- **先报价再执行**：任何兑换操作，先让 Agent 查询报价，确认价格合理后再执行 -- **大额拆分**：大额交易建议拆分成多笔小额执行，降低单笔滑点风险 -- **授权管理**：定期检查代币授权（Approve），撤销不再使用的授权 - -### 操作确认清单 - -对于任何**写操作**，Agent 应在执行前向用户确认以下信息： +### x402-payment -1. 操作类型（Swap / 添加流动性 / 转账等） -2. 涉及的代币和金额 -3. 当前网络（测试网 / 主网） -4. 预估 Gas 费用 -5. 滑点设置 +``` +# ⚠️ 调用付费端点 +使用 x402 协议调用这个付费智能体端点：https://api.example.com -**用户明确确认后才执行。** +# 🟢 查询 Gasfree 状态 +帮我查看当前 Gasfree 钱包的状态和可用余额。 +``` +### ainft-skill -## 最佳实践 +``` +# 🟢 查询余额 +我的 AINFT 账户还有多少余额？ -### 给指令的技巧 +# 🟢 查询订单 +显示我最近的 AINFT 订单记录。 -**一次性给全参数**，减少 Agent 的猜测和追问： +# ⚠️ 充值 +给我的 AINFT 账户充值 1 USDT。 +``` -```text -# 不好 → Agent 需要反复追问 -"帮我换点币。" +--- -# 好 → 所有关键信息一步到位 -"在 SunSwap 上将 100 USDT 兑换为 TRX，滑点设为 0.5%，使用主网。" -``` +## 推荐学习路径 -### 推荐的学习路径 +如果你刚开始使用 BANK OF AI Skills，按这个顺序来会更顺畅： -``` -1. 只读查询 → 熟悉 Skill 的交互方式 - ↓ -2. 测试网写操作 → 验证完整流程，零风险 - ↓ -3. 主网小额操作 → 确认一切正常 - ↓ -4. 主网正式使用 → 日常操作 -``` +第一步：只读查询 + → 先用 tronscan-skill 查账户、看交易，熟悉技能的交互方式 + → 用 sunswap 查价格和报价，不执行真实交易 -### 常见排障 +第二步：测试网写操作 + → 在 Nile 测试网执行 swap、添加流动性、开合约 + → 确认 AI 的行为符合预期，确认参数传递正确 -| 问题 | 可能原因 | 解决方案 | -|------|---------|---------| -| Agent 说"找不到技能" | 技能文件未放到正确目录 | 检查安装路径，参考安装章节 | -| Agent 行为与预期不符 | 隐式触发匹配到了错误的技能 | 改用显式调用 | -| 链上交易失败 | Gas 不足 / 滑点过低 / 网络错误 | 检查余额、调整滑点、确认网络 | -| 报价与实际成交差异大 | 流动性不足或市场波动 | 减小交易金额，或等待市场稳定 | +第三步：主网小额操作 + → 用少量资金验证完整流程 +第四步：主网正式使用 + → 日常操作，根据需要调整参数和技能组合 +--- +## 下一步 +- 想深入了解 Skill 的工作原理？ → [Skills 是什么？](./Intro.md) +- 遇到问题？ → [常见问题](./Faq.md) +- 使用 OpenClaw Extension 安装？ → [OpenClaw Extension 文档](../../Openclaw-extension/Intro.md) diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Faq.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Faq.md index 58294a59..95a9d1da 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Faq.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Faq.md @@ -1,85 +1,204 @@ -# 常见问题 +# 常见问题与排查 -### 问：Skill 需要单独安装吗？ - -**答**：不需要。Skill 只是 AI 智能体直接读取的文档和脚本集合。你只需要将技能目录放在正确的位置，AI 就能自动发现和使用它。如果技能包含 `scripts/` 目录，需要先运行 `npm install` 安装其依赖。 +以下问题按你最可能遇到的顺序排列。 --- -### 问：Skill 和 MCP Server 有什么区别？ +## 基础概念 + +### Skill 和 MCP Server 有什么区别？ + +这是最常见的问题。一句话解释：**MCP Server 是工具箱，Skill 是操作手册。** + +MCP Server 提供原子级工具——比如"查余额"、"发起转账"、"调用合约"。Skill 则告诉 AI 如何把这些工具组合起来完成一个完整任务——比如"在 DEX 上兑换代币"需要依次执行查余额、获取报价、检查授权、执行兑换四个步骤，Skill 负责定义这个流程。 -**答**： +### Skill 需要单独安装吗？ -| | Skill | MCP Server | -| :--- | :--- | :--- | -| **定义** | 指令文档 + 脚本集合 | 工具服务 | -| **作用** | 教 AI **如何做**某件事 | 提供 AI **做事的能力** | -| **示例** | sunswap 技能教 AI 如何执行兑换流程 | tron-mcp-server 提供链上交互能力 | +不需要额外安装应用程序。Skill 就是一个文件夹——你只需把它放在 AI 工具能读取的目录里，AI 就能自动发现和使用它。 -简单来说：Skill 是"操作手册"，MCP Server 是"工具箱"。Skill 告诉 AI 如何使用 MCP Server 提供的工具。 +但如果技能包含 `scripts/` 目录（sunswap、sunperp-skill、tronscan-skill 都有），需要在该目录下运行一次 `npm install` 安装脚本依赖。使用 OpenClaw Extension 安装时这步是自动的。 + +### Skills 支持哪些 AI 工具？ + +目前支持：**OpenClaw**（最完整的集成体验）、**Claude Code**、**Cursor**，以及任何支持读取本地文件的 AI 助手（通过显式调用方式）。 --- -### 问：如何知道技能需要哪些依赖？ +## 安装与配置 + +### 怎么知道技能安装成功了？ + +```bash +ls ~/.openclaw/skills +``` -**答**：查看技能目录下的两个文件： +应该能看到 `sunswap`、`sunperp-skill`、`tronscan-skill`、`x402-payment`、`ainft-skill` 等目录。 -1. `SKILL.md` 顶部的 YAML frontmatter： -```yaml -dependencies: - - node >= 18 - - tron-mcp-server +然后在 OpenClaw 中验证： + +``` +阅读 sunswap 技能，告诉我这个技能能做什么。 ``` -2. `package.json` 中的 npm 依赖： +如果 AI 能准确描述技能内容，说明安装成功。 + +### npm install 报错怎么办？ + +先确认 Node.js 版本： + ```bash -cd skills/sunswap && npm install +node --version # 需要 >= 18 ``` ---- +如果版本过低，用 nvm 升级： -### 问：如果 AI 智能体找不到技能怎么办？ +```bash +nvm install 18 +nvm use 18 +``` -**答**：你可以显式告诉 AI 技能的路径： +然后重新在技能目录执行 `npm install`。 -> 请阅读 `skills/sunswap/SKILL.md`，帮我查看 100 USDT 能兑换多少 TRX。 +### 凭证（私钥/API Key）怎么配置？ -如果使用 OpenClaw 扩展安装，技能会被自动配置，AI 可以通过隐式触发自动匹配。 +通过环境变量配置。根据你使用的技能，在 `~/.zshrc` 或 `~/.bashrc` 中添加对应变量： ---- +```bash +# TRON 钱包（sunswap、sun-mcp-server、x402-payment 需要） +export TRON_PRIVATE_KEY="你的私钥" +export TRONGRID_API_KEY="你的 TronGrid API Key" -### 问：我可以修改技能吗？ +# SunPerp 合约交易（sunperp-skill 需要） +export SUNPERP_ACCESS_KEY="你的 SunPerp Access Key" +export SUNPERP_SECRET_KEY="你的 SunPerp Secret Key" -**答**：可以。直接编辑 `SKILL.md` 或 `scripts/` 中的脚本，AI 智能体下次调用时会读取最新版本。 +# TronScan 数据查询（tronscan-skill 需要） +export TRONSCAN_API_KEY="你的 TronScan API Key" + +# AINFT（ainft-skill 需要） +export AINFT_API_KEY="你的 AINFT API Key" +``` + +添加后执行 `source ~/.zshrc` 生效，然后重启 AI 工具。 --- -### 问：如何切换测试网和主网？ +## 使用问题 + +### AI 说"找不到技能"或行为不符合预期怎么办？ -**答**：通过 `--network` 参数指定。建议始终先在测试网（`nile` 或 `shasta`）上完成验证，再切换到 `mainnet`。 +首先换成**显式调用**——直接告诉 AI 技能文件在哪里： + +``` +请阅读 ~/.openclaw/skills/sunswap/SKILL.md，帮我查 TRX 当前价格。 +``` + +如果显式调用正常，说明是隐式触发的匹配问题。可以在任务描述中加入更明确的关键词，比如"使用 sunswap 技能"、"通过 tronscan-skill"。 + +如果显式调用也不工作，检查技能目录是否存在、npm install 是否完成、环境变量是否正确设置。 + +### 如何在测试网和主网之间切换？ + +通过 `--network` 参数指定。**强烈建议每次新操作都先在测试网验证**： ```bash -# 测试网 +# 测试网（默认，推荐先用这个） node scripts/swap.js TRX USDT 100 --network nile -# 主网 +# 主网（确认一切正常后再用） node scripts/swap.js TRX USDT 100 --network mainnet --execute ``` ---- +也可以在对话中直接告诉 AI： +``` +在 Nile 测试网上帮我把 100 TRX 兑换成 USDT。 +``` + +### 为什么 AI 在执行前要让我确认？ + +这是设计如此的安全机制——所有写操作（涉及链上交易的操作）都必须经过用户明确确认才能执行。 -### 问：私钥如何配置？ +AI 会在确认提示中展示：操作类型、涉及的代币和金额、目标网络、预估 Gas 和滑点。这是为了让你在资金真正动用之前，有机会核查操作是否符合预期。**不要跳过这个步骤，更不要开启自动执行写操作。** -**答**：通过环境变量配置，切勿写死在代码中： +### dry-run（模拟执行）是什么意思？ + +sunswap 等 Skill 的脚本支持不带 `--execute` 标志运行——这就是 dry-run 模式。它会模拟执行流程、检查余额和授权状态、获取报价，但不会广播任何链上交易。 ```bash -export TRON_PRIVATE_KEY="your_private_key" -export TRONGRID_API_KEY="your_api_key" # 主网推荐配置 +# Dry-run：模拟检查，不执行 +node scripts/swap.js TRX USDT 100 + +# 真实执行 +node scripts/swap.js TRX USDT 100 --execute ``` -私钥加载优先级：`TRON_PRIVATE_KEY` > `PRIVATE_KEY` > 配置文件 > 钱包文件 +遇到不确定的情况时，先跑 dry-run 是个好习惯。 + +### 为什么报价和实际成交有差异？ + +因为从获取报价到实际执行之间有时间差，这段时间内价格可能发生变化。sunswap 的 `swap.js` 采用两步报价策略来处理这个问题：第一次报价展示给用户确认，用户确认后在实际提交交易前会重新获取最新报价，然后以最新报价计算的 `amountOutMin` 作为滑点保护。 + +如果市场波动剧烈导致交易失败，适当增大滑点容忍度（`--slippage 1.0`）通常能解决。 --- +## 安全与进阶 + +### 我可以修改技能吗？ + +可以。直接编辑 `SKILL.md` 或 `scripts/` 中的脚本，AI 下次调用时会读取最新版本。你可以修改操作步骤、添加自定义规则、调整安全参数，或者添加新的示例。 + +修改 `sunperp-skill/resources/sunperp_config.json` 可以调整杠杆上限和止损默认值： + +```json +{ + "safety": { + "max_leverage": 20, + "stop_loss": { + "required": true, + "default_percent": 5, + "max_percent": 25 + } + } +} +``` + +### 技能的版本怎么管理？ + +技能版本由 `SKILL.md` 的 YAML frontmatter 中的 `version` 字段标记。使用 OpenClaw Extension 时，可以通过 `GITHUB_BRANCH` 环境变量指定安装特定版本： +```bash +GITHUB_BRANCH=v1.4.10 ./install.sh # 安装指定版本 +GITHUB_BRANCH=main ./install.sh # 使用最新主分支 +``` + +默认使用 `v1.4.12` 标签版本。 + +### 私钥泄露了怎么办？ + +**立即行动，不要犹豫：** + +1. 停止使用当前 AI 工具 +2. 创建一个新的 TRON/EVM 钱包地址 +3. 将所有资产转移到新地址（注意检查当前账户是否有待处理交易） +4. 更新所有环境变量，指向新的私钥 +5. 撤销旧钱包在所有协议上的代币授权 +6. 查看旧钱包的交易记录，确认是否已有未授权的操作 + +Agent Wallet（加密存储）比明文私钥更安全——即使环境变量泄露，攻击者还需要额外的加密密钥才能访问资金。如果你管理较多资金，建议切换到 Agent Wallet 模式。 + +### 如何卸载或更新技能？ + +**卸载：** + +```bash +rm -rf ~/.openclaw/skills/sunswap # 删除指定技能 +``` + +**更新（重新安装最新版本）：** + +```bash +cd openclaw-extension +./install.sh # 如果同名技能已存在，安装程序会询问是否覆盖 +``` diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Intro.md index 27c9c526..0b60ac1d 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Intro.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Intro.md @@ -1,108 +1,143 @@ -# 简介 +# Skills 是什么？ -## 什么是 Skills？ -简单来说就是“技能包” +你可能已经在用 MCP Server 让 AI 助手查余额、发转账、调用合约了。但你会发现，有些任务并不是"调一次工具就完事"——比如在 DEX 上兑换代币，需要先查余额、再获取报价、然后授权、最后执行兑换，每一步都有判断和参数要处理。 -**Agent Skills** 是一种让 AI 学习新本领的开放格式。你可以把它想象成一个**插件包**或**技能文件夹**。 +**Skills 就是为这类多步骤任务而生的。** -每个“技能包”里都装好了完成某项任务所需的一切： -* **说明书**：告诉 AI 什么时候该用这个技能，以及具体怎么做。 -* **工具箱**：包含一些自动化脚本或代码，帮 AI 动手干活。 -* **参考资料**：一些专业文档或模板，让 AI 干活时有据可依。 +一个 Skill 是一个"任务手册"——它不是工具，而是告诉 AI 怎样把一系列工具按正确的顺序、用正确的参数组合起来，完成一个完整的业务流程。 -通过这种方式，你可以随时给你的 AI “加载”新能力，而且这些能力是**可复用、可分享、可控制**的。 +--- + +## Skill 和 MCP Server 的区别 +很多人第一次接触 Skills 时会问：这和 MCP Server 有什么不一样？ +| | MCP Server | Skill | +| :--- | :--- | :--- | +| **本质** | 工具服务 | 任务手册 + 脚本集合 | +| **作用** | 提供 AI **做事的原子能力** | 教 AI **如何把能力组合起来完成一件事** | +| **例子** | `mcp-server-tron` 提供 `send_trx` 工具 | `sunswap` 告诉 AI 如何用多个工具完成一次 DEX 兑换 | +| **类比** | 厨房里的刀、锅、炉子 | 菜谱 | -## 技能包里都有那些内容 +简单说：**MCP Server 是工具箱，Skill 是操作手册。** Skill 告诉 AI 打开哪个抽屉、拿哪把工具、按什么步骤完成任务。 + +--- -打开一个技能文件夹，你通常会看到以下几样东西： +## 一个 Skill 长什么样？ -| 文件夹/文件 | 角色 | 作用 | +Skill 是一个文件夹，结构非常简单： + +| 文件/目录 | 作用 | 是否必须 | | :--- | :--- | :--- | -| `SKILL.md` | **核心大脑** | **必须有！** 包含技能的名字、描述和详细的操作指南。 | -| `scripts/` | **自动化工具** | 可选。装的是脚本代码，AI 可以直接运行它们来处理数据。 | -| `references/` | **知识库** | 可选。装的是专业文档、API 说明等参考资料。 | -| `assets/` | **素材库** | 可选。装的是模板、图片或其他资源。 | +| `SKILL.md` | 核心指令文档——AI 从这里学会如何执行任务 | **必须** | +| `scripts/` | 可执行脚本——AI 调用这些脚本完成具体操作 | 可选 | +| `resources/` | 参考数据——合约地址、代币列表、配置文件等 | 可选 | +| `package.json` | npm 依赖声明（有 scripts 的 Skill 需要先安装） | 可选 | +`SKILL.md` 的顶部是一段 YAML Frontmatter，声明技能的基本信息： -## 核心原理 -大模型的“记忆力”（即上下文窗口）极其宝贵且昂贵。如果把所有技能的详尽说明一次性全塞给 AI，不仅会消耗巨量 Token（变贵），还会导致 AI 注意力分散、响应迟缓甚至频发“幻觉”（变笨）。 +```yaml +--- +name: SunSwap DEX Trading +description: Execute token swaps on SunSwap DEX for TRON blockchain using automated scripts. +version: 2.0.0 +dependencies: + - node >= 18.0.0 + - tronweb +tags: + - defi + - dex + - swap + - tron +--- -为了破解这个难题，Skills 架构引入了**渐进式披露 (Progressive Disclosure)的设计哲学**与**三层分级加载**机制。 +# SunSwap DEX Trading Skill -### 像在图书馆找书一样“按需加载” -这就好比在图书馆查资料，你不会一次性把几百本书全搬上桌，而是遵循一套高效的检索逻辑： +## 🚀 Quick Start +...（具体操作指令） +``` -* **Level 1：元数据（轻量名片库）—— 扫视书架标签** - * **原理**：AI 启动时，系统仅向其暴露所有已挂载技能的 `name`（名称）和 `description`（简介）。 - * **优势**：由于只加载“名片”，资源消耗极低。这使得 AI 能够轻松“记住”并同时管理成百上千个技能，保持快速的响应速度。 +`name` 和 `description` 是 AI 识别和匹配技能的关键字段——写得越准确，AI 越容易在合适的时机自动找到它。正文则是具体的操作指令，没有格式限制，可以是文字说明、代码示例、参数表格，或者任何有助于 AI 理解的内容。 -* **Level 2：说明文档（实操指南）—— 翻开特定目录** - * **原理**：只有当你的需求精准命中某个技能后，AI 才会去读取该技能对应的 `SKILL.md` 文件。 - * **优势**：这份专属指南会在关键时刻为 AI 注入当前任务的操作逻辑、边界限制和标准作业程序（SOP），确保执行不跑偏。 +--- -* **Level 3：外部资源（深度工具链）—— 查阅附录与实操** - * **原理**：当任务进入深水区（如执行复杂 Python 脚本、拉取庞大 API 数据）时，AI 才会在需要的那一刻调用底层工具。 - * **优势**：这些工具在后台静默运行，最终只把提炼后的核心结果返回给 AI。它们几乎不占用 AI 宝贵的思考空间，实现了性能与深度的完美平衡。 +## 为什么不把所有指令直接给 AI？ +理解 Skills 设计的关键问题：如果只是告诉 AI 怎么操作，直接在对话里说不就行了？ -## 调用逻辑 +这样做有两个根本问题： -AI 选择并执行一个 Skill 的过程可以分为精密的四步： +**上下文窗口有限且昂贵。** 如果把所有 Skill 的完整内容都塞进每次对话，光是这些指令就会占据大量 token，让 AI 反应变慢，也让每次对话的成本大幅增加。 -
- RangeOrder1 -
+**注意力分散。** 当 AI 面对几十个 Skill 的详细说明时，它很难专注于当前任务，容易混淆不同技能的规则和参数，产生错误。 -### 第一步：意图识别 -AI 首先解析你的自然语言需求，快速扫描资源库中所有 Skill 的“身份卡”（元数据），精准锁定最契合当前任务的那个技能。 +Skills 的解法是**三层渐进式加载**——只在需要的时候才加载需要的内容。 -### 第二步：规则内化 -选定 Skill 后，AI 会立刻调取对应的“操作手册”（`SKILL.md`），仔细研读具体的执行步骤、规则限制和上下文要求。 +--- -### 第三步：工具调用 -基于手册的指引，AI 开始规划路径并动手执行。当遇到具体的操作节点时，它会准确调用底层绑定的工具或脚本，完成实质性工作。 +## 三层渐进式加载 -### 第四步：反馈与复盘 -任务搞定后，AI 会将结果整理成易读的格式向你汇报；如果遇到缺漏信息或执行异常，它也会及时向你提问求助。 +把 Skills 想象成图书馆的检索系统： +**第一层：书架索引（极轻量）** -## `SKILL.md` 文件格式 +AI 启动时，系统只向它暴露所有 Skill 的 `name` 和 `description`——就像书架上的标签。这些"索引卡片"非常小，即使同时加载几百个 Skill 也不会造成负担。AI 通过这一层决定"这次任务需要用到哪个技能"。 -`SKILL.md` 用一种 AI 和人类都能看懂的方式写成。 -在 `SKILL.md` 文件的顶部，必须包含以下 `Frontmatter`： -* `name`：简短的标识符（技能名称） -* `description`：说明何时应该使用该技能 +**第二层：操作手册（按需加载）** -Markdown 的正文部分则包含实际的操作指令，并且对结构或内容没有任何特定的限制。 +当 AI 确认需要某个 Skill，才去读取对应的 `SKILL.md` 完整内容。这一步只在匹配到技能时触发，为 AI 提供具体的执行步骤、参数要求、边界条件和常见错误处理。 + +**第三层：工具执行（实时调用）** + +当任务执行到需要具体操作的环节（比如查询链上余额、执行兑换交易），AI 才调用对应的脚本或 MCP 工具，完成实质性工作，然后把结果返回给对话。 + +这种设计让系统在管理大量 Skill 的同时，保持低延迟和高准确性。 -```yaml --- -name: pdf-processing -description: Extract PDF text, fill forms, merge files. Use when handling PDFs. + +## AI 如何找到并使用一个 Skill？ + +AI 选择并执行一个 Skill 经历四个步骤： + +**步骤 1：意图识别** + +你发出一条请求（比如"帮我在 SunSwap 上把 100 USDT 兑换成 TRX"），AI 解析意图，扫描所有已挂载 Skill 的描述，找到最匹配的那个。 + +**步骤 2：规则内化** + +AI 读取该 Skill 的 `SKILL.md`，理解执行步骤、参数格式、网络选择、安全限制等具体规则。 + +**步骤 3：工具执行** + +按照手册的指引，AI 逐步执行——调用脚本查余额、获取报价、检查授权、执行兑换——在关键节点等待你的确认。 + +**步骤 4：结果反馈** + +任务完成后，AI 将结果整理成易读的格式汇报给你。遇到缺少信息或执行异常时，主动询问。 + --- -# PDF Processing +## 两种调用方式 + +你可以通过两种方式触发 Skill： -## When to use this skill -Use this skill when the user needs to work with PDF files... +**显式调用** — 直接告诉 AI 要读哪个 Skill，适合需要确定性行为的场景： + +``` +阅读 sunswap 技能，帮我查 100 USDT 在 SunSwap 上能兑换多少 TRX。 +``` -## How to extract text -1. Use pdfplumber for text extraction... +**隐式触发** — 描述任务，让 AI 自动匹配，适合日常对话： -## How to fill forms -... +``` +帮我查一下现在 100 USDT 在 SunSwap 能换多少 TRX。 ``` -### 优势： -1. **一看就懂**：人类能读懂，方便你随时修改和优化 AI 的行为。 -2. **无限扩展**：既可以只是简单的文字指令，也可以是复杂的自动化流程。 -3. **轻松搬运**：技能就是一个文件夹，你可以把它发给朋友，或者在不同的 AI 工具里通用。 +两种方式的区别在于控制权：显式调用确保 AI 使用你指定的 Skill；隐式触发更自然，但如果描述不够清晰，AI 可能匹配到错误的 Skill。遇到执行不符合预期时，换成显式调用通常能解决问题。 + +--- +## 下一步 +- 想了解 BANK OF AI 提供了哪些现成的 Skill？ → [BANK OF AI Skills](./BANKOFAISkill.md) +- 有疑问？ → [常见问题](./Faq.md) diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/FAQ.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/FAQ.md new file mode 100644 index 00000000..5f764aad --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/FAQ.md @@ -0,0 +1,229 @@ +# 常见问题与排查 + +遇到问题时，先来这里找找答案。按照你最可能遇到的顺序组织：安装问题、连接问题、凭证问题、运行时问题，最后是一些通用问题。 + +--- + +## 安装问题 + +### 安装程序报错"command not found: node" + +安装程序需要 Node.js v18.0.0 或更高版本。检查是否已安装： + +```bash +node --version +``` + +如果未安装或版本太低，请到 [nodejs.org](https://nodejs.org/) 下载安装最新 LTS 版本。安装 Node.js 后，`npx` 命令会同时可用。 + +### 安装程序报错"command not found: python3" + +安装程序使用 Python 处理 JSON 配置文件。macOS 通常自带 Python 3，Linux 可以通过包管理器安装： + +```bash +# Ubuntu/Debian +sudo apt install python3 + +# macOS (通过 Homebrew) +brew install python3 +``` + +### 安装程序警告"OpenClaw not found" + +安装程序检测到 `~/.openclaw` 目录不存在。这意味着 OpenClaw 可能未安装，或者安装在了非标准路径。 + +安装程序会询问你是否继续——你可以选择继续安装（MCP Server 和 Skills 仍然会被配置），但 OpenClaw 启动后可能无法自动加载它们。建议先到 [OpenClaw 官方仓库](https://github.com/openclaw) 完成安装。 + +### Skills 克隆失败 + +如果 `git clone` 失败，常见原因包括： + +- **网络问题**：检查是否能访问 GitHub。可以尝试 `git clone https://github.com/BofAI/skills.git` 手动测试。 +- **Git 未安装**：运行 `git --version` 确认。 +- **指定的分支/标签不存在**：如果你设置了 `GITHUB_BRANCH` 环境变量，确认对应的分支或标签确实存在。 + +Skills 克隆失败不会中断整个安装——MCP Server 的配置仍然完好。你可以之后手动安装 Skills。 + +### npm install 失败 + +安装 Skills 时，部分 Skill（如 sunswap、x402-payment）需要运行 `npm install` 安装依赖。如果失败： + +- 检查网络连接（npm 需要访问 registry.npmjs.org） +- 确认 Node.js 版本 >= 18 +- 尝试手动运行： + ```bash + cd ~/.openclaw/skills/sunswap # 或其他 Skill 目录 + npm install + ``` + +npm install 失败不会中断安装程序——它会发出警告但继续。该 Skill 的部分功能可能受限，直到依赖安装成功。 + +--- + +## 连接问题 + +### OpenClaw 启动后看不到区块链工具 + +**最常见的原因**：没有重启 OpenClaw。修改 mcporter.json 后，必须完全退出并重新启动 OpenClaw。 + +如果重启后仍然看不到： + +1. **检查 mcporter.json 格式**： + ```bash + python3 -m json.tool ~/.mcporter/mcporter.json + ``` + 如果报 JSON 语法错误，修复格式问题后重启。 + +2. **检查 mcporter.json 内容**：确认 `mcpServers` 下有你安装的 Server 条目。 + +3. **手动测试 MCP Server**： + ```bash + npx -y @bankofai/mcp-server-tron + ``` + 如果这条命令能正常启动（显示日志输出），说明 MCP Server 本身没问题，问题在 OpenClaw 的配置读取。 + +### 只有查询工具可用，没有转账等写入工具 + +这是设计如此。写入工具只在配置了钱包凭证后才会出现。检查以下之一是否已配置： + +- 环境变量 `TRON_PRIVATE_KEY`（mcp-server-tron） +- 环境变量 `PRIVATE_KEY`（bnbchain-mcp） +- mcporter.json 中对应 Server 的 `env.TRON_PRIVATE_KEY` 或 `env.PRIVATE_KEY` + +配置凭证后重启 OpenClaw。详细说明请参阅 [配置参考](./Configuration.md)。 + +### MCP Server 启动超时 + +如果 OpenClaw 在启动 MCP Server 时超时，可能是 npx 下载包太慢。首次运行时需要从 npm 下载包，可能需要几十秒。 + +可以提前手动下载来加速： + +```bash +npx -y @bankofai/mcp-server-tron --help +npx -y @bnb-chain/mcp@latest --help +``` + +下载完成后，后续启动会使用缓存，速度会快很多。 + +--- + +## 凭证问题 + +### "私钥无效"错误 + +**TRON 私钥**应为 64 个字符的十六进制字符串，可以带或不带 `0x` 前缀。 + +**EVM 私钥**应带 `0x` 前缀。安装程序会自动为不带前缀的私钥添加 `0x`，但如果你手动编辑配置文件，请确保格式正确。 + +常见错误： +- 多余的空格、换行或引号嵌套 +- 从其他地方复制时带入了不可见字符 + +验证方法：将私钥导入对应的钱包（TronLink 或 MetaMask）确认有效。 + +### TronGrid API Key 不生效 + +1. **变量名是否正确**：必须是 `TRONGRID_API_KEY`（不是 `TRON_API_KEY`） +2. **Key 是否仍然有效**：登录 [trongrid.io](https://www.trongrid.io/) 确认状态 +3. **是否正确加载**：如果在环境变量中设置，确认已运行 `source ~/.zshrc` + +### Gasfree 凭证不起作用 + +检查 `~/.x402-config.json` 的格式和内容： + +```bash +cat ~/.x402-config.json +``` + +确认包含有效的 `gasfree_api_key` 和 `gasfree_api_secret`。如果需要重新配置，可以直接编辑文件或重新运行安装程序。 + +### AINFT API Key 无效 + +检查 `~/.mcporter/ainft-config.json` 的内容： + +```bash +cat ~/.mcporter/ainft-config.json +``` + +确认 `api_key` 字段包含有效的 Key。注意 ainft-skill 的凭证读取有优先级顺序（CLI 参数 > 环境变量 > 配置文件），如果你在多个地方设置了不同的值，可能会读到意外的那个。 + +--- + +## 运行时问题 + +### 请求限速（429 错误） + +主网的公共 RPC 有严格的频率限制。解决方法： + +- **配置 TronGrid API Key**：免费申请后设置 `TRONGRID_API_KEY`，显著提升限额 +- **使用测试网**：Nile 和 Shasta 测试网受限更少 +- **减少并发查询**：在提示词中避免让 AI 同时执行大量查询 + +### Skill 执行失败 + +如果某个 Skill 报错，按以下顺序排查： + +1. **检查依赖是否安装**： + ```bash + cd ~/.openclaw/skills/ + npm install # 如果有 package.json + ``` + + +2. **检查 Node.js 版本**：部分 Skill 需要 >= 18.0.0。 + +### 交易失败 + +链上交易失败的常见原因： + +- **余额不足**：TRX 余额不够支付 Gas 费（带宽/能量） +- **能量不足**：智能合约调用（包括 TRC20 转账）需要消耗能量 +- **账户未激活**：新的 TRON 地址需要先收到一笔 TRX 才能激活 +- **授权额度不足**：TRC20 代币转账前可能需要先 approve + +使用 mcp-server-tron 的 `get_transaction_info` 工具查看交易失败的具体原因。 + +--- + +## 通用问题 + +### 能否只安装部分组件？ + +可以。安装程序在每个阶段都允许你选择性安装。比如你可以只安装 mcp-server-tron 而不装其他 MCP Server，或者只安装 sunswap Skill 而跳过其他 Skill。 + +### 能否多次运行安装程序？ + +可以。安装程序对 mcporter.json 采用深度合并策略，不会覆盖已有配置。对于 Skills，如果目标位置已存在同名 Skill，会提示你是否覆盖。 + +### 如何完全卸载？ + +OpenClaw Extension 没有自动卸载程序。手动卸载步骤： + +1. **删除 MCP Server 配置**：编辑 `~/.mcporter/mcporter.json`，移除对应的 Server 条目 +2. **删除 Skills**：删除安装目录下的 Skill 文件夹（默认 `~/.openclaw/skills/`） +3. **删除凭证文件**： + ```bash + rm -f ~/.x402-config.json + rm -f ~/.mcporter/ainft-config.json + rm -f ~/.clawdbot/wallets/.deployer_pk + ``` +4. **清理环境变量**：从 `~/.zshrc` 或 `~/.bashrc` 中移除相关 export 语句 + +### 支持哪些操作系统？ + +安装程序是 Bash 脚本，支持： +- **macOS**（Intel 和 Apple Silicon） +- **Linux**（Ubuntu、Debian、CentOS 等） +- **Windows**：需要通过 WSL（Windows Subsystem for Linux）运行 + +### 和 TRON MCP Server 的官方云服务有什么区别？ + +[官方云服务](../McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md)是远程托管的只读 MCP Server，不需要本地安装。OpenClaw Extension 则在你本地运行 MCP Server，配合私钥可以解锁完整的读写能力。 + +如果你只需要查询链上数据，云服务更简单。如果你需要转账、合约写入等操作，或者需要使用 Skills（如 SunSwap 交易），就需要 OpenClaw Extension。 + +--- + +## 下一步 + +- 从头开始 → [快速开始](./QuickStart.md) diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/Intro.md new file mode 100644 index 00000000..c7a55281 --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/Intro.md @@ -0,0 +1,61 @@ +# 简介 + +## OpenClaw Extension 是什么？ + +OpenClaw Extension 是由 **BANK OF AI** 开发的一套扩展工具包，为 [OpenClaw](https://github.com/openclaw)（开源 AI 助手）赋予**区块链交互能力**。安装后，你的 AI 助手就能直接操作链上资产——查余额、发起转账、调用智能合约、在 DEX 上兑换代币——而这一切只需要用自然语言对话完成。 + +传统方式下，让 AI 操作区块链需要自己搭建 MCP Server、手动管理配置文件、逐个安装各种工具。OpenClaw Extension 把这些工作打包成了一个交互式安装程序——运行一条命令，按提示选择你需要的组件，几分钟内就能让 AI 助手具备多链操作能力。 + +--- + +## 核心愿景 + +OpenClaw Extension 的目标是为 AI 代理经济构建一套金融基础设施——让每个 AI 代理都具备独立的金融能力： + +- **赚取收益**：通过 x402 协议等标准接口接受任务和服务的付款 +- **自主消费**：独立支付计算、数据、存储等资源费用 +- **代理互联**：促进代理之间（A2A）的直接金融活动和结算 +- **DeFi 交互**：无缝地与去中心化金融协议和智能合约交互 + +--- + +## 它包含什么？ + +OpenClaw Extension 由两大类组件构成：**MCP Server** 和 **Skills**。你可以在安装时按需选择要启用哪些组件。 + +### MCP Server — 链上操作能力 + +MCP Server 是 AI 助手与区块链之间的桥梁，通过 [Model Context Protocol (MCP)](../McpServer-Skills/MCP/Intro.md) 标准接口提供链上操作能力。目前支持三条链的 MCP Server 和一个远程服务： + +| MCP Server | 目标链 | 核心能力 | +| :--- | :--- | :--- | +| **[mcp-server-tron](https://github.com/BofAI/mcp-server-tron)** | TRON | 95 个工具，覆盖钱包、转账、合约、质押、治理等全部操作 | +| **[bnbchain-mcp](https://github.com/bnb-chain/bnbchain-mcp)** | BSC / opBNB / 以太坊 | 多链 EVM 操作、钱包、合约、跨链 | + +### Skills — 预构建工作流 + +Skills 是封装好的业务流程模板。与 MCP Server 提供的单个工具不同，一个 Skill 可以串联多个操作完成完整的任务——比如"在 SunSwap 上兑换代币"涉及查价格、检查余额、执行兑换、确认结果等步骤，一个 Skill 就能搞定。 + +| Skill | 功能 | +| :--- | :--- | +| **sunswap** | SunSwap DEX 交易——余额查询、报价、兑换、V2/V3 流动性管理 | +| **sunperp-skill** | SunPerp 永续合约交易——行情、下单、仓位管理、杠杆设置、提现 | +| **tronscan-skill** | 通过 TronScan API 查询链上数据（账户、交易、代币、区块、全网统计） | +| **x402-payment** | x402 支付技能，调用付费智能体和付费 API，支持 Gasfree 免 Gas 交易 | +| **ainft-skill** | AINFT 余额和订单查询，以及 TRC20 充值 | + + +--- + +## 适合谁使用？ + +- **OpenClaw 用户**：想让 AI 助手直接操作区块链，而不想自己手动搭建 MCP Server +- **Web3 开发者**：需要一个快速搭建的链上开发环境，用自然语言调试合约和查询数据 +- **AI Agent 构建者**：需要为自动化代理配备多链操作能力 +- **DeFi 用户**：想通过 AI 助手在 SunSwap 上交易或管理流动性 + +--- + +## 下一步 + +- 想立刻体验？ → [快速开始](./QuickStart.md) diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/Overview.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/Overview.md deleted file mode 100644 index c28272c4..00000000 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/Overview.md +++ /dev/null @@ -1,65 +0,0 @@ -# 简介 - -OpenClaw 扩展是由 **BANK OF AI** 开发的一套工具，旨在通过 **x402 协议**（HTTP 402 Payment Required）赋能 AI 代理实现财务主权。它使代理能够持有钱包、执行交易并将其服务货币化。 - -## 愿景 - -为代理经济构建“中央银行”，确保每个 AI 代理都能： -- **赚取收益**: 通过标准协议接受任务和服务的付款。 -- **自主消费**: 自主支付资源（计算、数据、存储）费用。 -- **连接交互**: 促进代理间（A2A）的直接金融活动和结算。 -- **无缝交易**: 无缝地与 DeFi 和智能合约交互。 - -## 📦 核心组件 - -此扩展提供两个主要组件： - -### MCP Server - -通过模型上下文协议（MCP）为 AI 代理提供多链区块链访问： - -- **[mcp-server-tron](https://github.com/BofAI/mcp-server-tron)** - TRON 区块链交互 - - 钱包管理、消息签名、地址转换与验证 - - 余额查询、TRX/TRC20 转账、智能合约调用 - - 合约部署、批量调用（multicall）、ABI 获取、合约参数管理 - - 区块与交易查询（按高度、哈希、范围） - - 资源估算（能量/带宽）、质押（Stake 2.0）、资源委托 - - 治理与提案、事件查询、内存池、节点信息 - - 账户管理、TronGrid 数据查询、交易广播 - - 全节点查询 API（能量/带宽历史价格、TRX 销毁统计、区块余额变动） - - 多网络支持（主网、Nile、Shasta） - - 只读模式，适用于安全的公开部署 - -- **[sun-mcp-server](https://github.com/BofAI/sun-mcp-server)** - SUN.IO (SUNSWAP) DeFi 交互 - - SUN.IO API 查询：代币、池子、价格、协议指标、交易、挖矿 - - 钱包管理、余额查询（TRX 与 TRC20）、多钱包切换 - - 代币价格与智能路由器兑换报价 - - 通过 Universal Router 智能兑换，自动寻找最佳路径 - - V2 流动性：添加/移除，自动处理原生 TRX - - V3 集中流动性：铸造、增加、减少仓位及收取手续费 - - V4 集中流动性：铸造、增加、减少仓位，支持 Permit2 - - 智能合约交互：读写合约，自动处理 TRC20 授权 - - 多网络支持（主网、Nile、Shasta） - - 支持私钥、BIP-39 助记词和 Agent Wallet - -- **[bnbchain-mcp](https://github.com/bnb-chain/bnbchain-mcp)** - BNB Chain 官方 MCP Server - - 多链支持：BSC、opBNB、以太坊、Greenfield - - 钱包操作、智能合约、代币转账 - - 跨链能力 - - -### Skills - -来自 **[Skills 仓库](https://github.com/BofAI/skills)** 的预构建工作流和工具： - -**可用 Skills ：** - -| SKILL | 功能 | -| :--- | :--- | -| **x402-payment** | x402 支付技能，用于在受支持的链上调用付费智能体和付费 API。 | -| **sunswap** | SunSwap DEX 技能，用于余额查询、报价、兑换及流动性相关工作流。 | -| **tronscan-skill** | 通过 TronScan API 进行 TRON 区块链数据查询，支持账户、交易、代币、区块及全网统计。 | - -有关完整的文档和使用说明，请参阅 [Skills 仓库](https://github.com/BofAI/skills)。 - -安装程序将允许您在设置过程中选择要安装的 Skill 。 \ No newline at end of file diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/QuickStart.md new file mode 100644 index 00000000..3d950639 --- /dev/null +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/QuickStart.md @@ -0,0 +1,142 @@ +# 快速开始 + +这个页面的目标是：**让你在几分钟内完成安装，并发起第一次区块链查询。** + +安装程序是交互式的，会引导你选择要安装哪些 MCP Server 和 Skills，然后自动完成所有配置。你只需要按提示操作即可。 + +--- + +## 准备工作 + +在运行安装程序之前，确保以下工具已就绪： + +| 要求 | 说明 | 验证命令 | 下载安装 | +| :--- | :--- | :--- | :--- | +| **OpenClaw** | 你的开源 AI 助手 | 检查 `~/.openclaw` 目录是否存在 |[OpenClaw 官方仓库](https://github.com/openclaw) | +| **Node.js v18+** | 运行 MCP Server 所需 | `node --version` | [Node.js 官方网站](https://nodejs.org/) | +| **Python 3** | 安装程序用于处理 JSON 配置 | `python3 --version` | [Python 官方网站](https://www.python.org/downloads/)| +| **Git** | 克隆 Skills 仓库 | `git --version` | [Git 官方网站](https://git-scm.com/) | + + +--- + +## 运行安装程序 + +### 方式一：一键安装（推荐） + +```bash +curl -fsSL https://raw.githubusercontent.com/BofAI/openclaw-extension/refs/heads/main/install.sh | bash +``` + +### 方式二：从源码安装 + +```bash +git clone https://github.com/BofAI/openclaw-extension.git +cd openclaw-extension +./install.sh +``` + +安装程序启动后，会自动检查环境依赖（Node.js、npx、Git、Python），如果发现缺失会立即提示。 + +如无依赖缺失，进入安装过程，安装过程分为两个主要阶段，每一步都会让你交互式选择。 + +--- + +## 安装过程详解 + +### 第一阶段：选择并配置 MCP Server + +安装程序会列出所有可用的 MCP Server，让你选择要安装哪些： + +``` +📦 Available MCP Servers: + 1) mcp-server-tron - TRON blockchain interaction + 2) bnbchain-mcp - BNB Chain (BSC, opBNB, Ethereum) interaction + 3) ainft-merchant - Remote AINFT recharge MCP + +Select servers to install (e.g., 1,2,3 or 'all'): +``` + +对于每个选中的服务器，安装程序会继续询问凭证存储方式： + +- **选项 1：保存到配置文件** — 密钥以明文存储在 `~/.mcporter/mcporter.json` 中。方便但安全性较低。 +- **选项 2：使用环境变量（推荐）** — 密钥从系统环境变量读取，不写入任何文件。 + +如果你选择保存到配置文件，安装程序会接着询问具体的密钥值（私钥、API Key 等）。如果选择环境变量，安装程序会告诉你需要设置哪些变量。 + +> **建议**：如果你只是想快速体验，可以先跳过密钥配置（直接回车留空）。没有私钥时 MCP Server 会以只读模式运行，你仍然可以查询链上数据。 + +### 第二阶段：选择并安装 Skills + +安装程序会从 GitHub 克隆 [Skills 仓库](https://github.com/BofAI/skills)，自动发现所有可用的 Skill，并让你选择： + +``` +🔧 Available Skills: + 1) sunswap - SunSwap DEX trading skill + 2) tronscan-skill - TRON blockchain data lookup + 3) x402-payment - Agent payment protocol (x402) + 4) ainft-skill - AINFT balance/order queries + +Select skills to install (e.g., 1,2,3 or 'all'): +``` + +然后选择安装位置： + +| 选项 | 路径 | 适用场景 | +| :--- | :--- | :--- | +| **用户级别**（推荐） | `~/.openclaw/skills/` | 所有项目共享 | +| **工作区级别** | `.openclaw/skills/` | 仅当前项目使用 | +| **自定义路径** | 你指定的目录 | 特殊需求 | + +部分 Skill 有额外的凭证需求，安装程序会在安装时逐一提示： + +- **x402-payment** — 可选配置 Gasfree API 凭证（用于免 Gas 交易） +- **ainft-skill** — 需要 AINFT API Key +- **tronscan-skill** — 提示你在 shell 中设置 `TRONSCAN_API_KEY` 环境变量 +- **sunswap** — 提示配置 TRON 私钥（如果前面没有配置） + +--- + +## 验证安装是否成功 + +安装完成后，**重启 OpenClaw**，然后在对话中输入： + +``` +查一下 TRON 主网当前的区块高度 +``` + +如果收到正常响应（显示当前区块高度），说明 mcp-server-tron 已成功接入。 + +你还可以试试： + +``` +查一下 TRON 地址 TXyz... 的 TRX 余额 +``` + +``` +TRON 主网当前的能量和带宽价格是多少？ +``` + +如果这些查询都能正常返回结果，说明一切就绪。 + +:::info 关于只读模式 +如果你在安装时没有配置私钥，MCP Server 会以只读模式运行——所有查询类操作（查余额、查交易、查合约状态等）都可以正常使用，但转账、合约写入等操作不可用。要解锁写入能力，请参阅 [配置参考](./Configuration.md)。 +::: + +--- + +## 遇到问题？ + +如果安装后 AI 助手无法识别区块链工具，常见原因包括： + +- **没有重启 OpenClaw** — 修改配置后必须完全重启 +- **Node.js 版本太低** — 确保 v18.0.0 或更高 +- **mcporter.json 格式错误** — 可以用 `python3 -m json.tool ~/.mcporter/mcporter.json` 检查 + +更多排查方法请参阅 [常见问题](./FAQ.md)。 + +--- + +## 下一步 + +- 遇到问题？ → [常见问题](./FAQ.md) diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/Setup-use.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/Setup-use.md deleted file mode 100644 index e6079298..00000000 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/Setup-use.md +++ /dev/null @@ -1,74 +0,0 @@ -# 安装及使用 -OpenClaw 扩展插件提供了一个 CLI 安装程序，可帮助您快速设置环境。 - -## 🛠 安装 - -### 先决条件 -- **OpenClaw**（您的个人开源 AI 助手）- [从此处安装](https://github.com/openclaw) -- **Node.js** (v18+) -- **Python 3**（用于配置助手） -- **Git**（用于克隆 Skills 仓库） -- **TRON 钱包**（用于 TRON 网络交互的私钥和 API 密钥） - -**注意**：此安装程序使用 OpenClaw 的配置系统。请确保在运行此安装程序之前已安装 OpenClaw。 - -### 快速开始 - -**一键安装：** - -```bash -curl -fsSL https://raw.githubusercontent.com/BofAI/openclaw-extension/refs/heads/main/install.sh | bash -``` - -或从源代码安装： - -```bash -git clone https://github.com/BofAI/openclaw-extension.git -cd openclaw-extension -./install.sh -``` - -### 安装内容 - -- ✅ **MCP Server** - TRON 和 BSC 区块链访问已配置在 `~/.mcporter/mcporter.json` 中 -- ✅ **Skills** - 预构建的工作流已安装到您选择的位置 -- ✅ **可用组件**：请参阅 [mcp-server-tron](https://github.com/BofAI/mcp-server-tron)、[bnbchain-mcp](https://github.com/bnb-chain/bnbchain-mcp) 和 [Skills 仓库](https://github.com/BofAI/skills) - -**注意**：此安装程序使用 `mcporter`（OpenClaw 的官方 MCP 管理器）进行配置。请确保首先安装 OpenClaw。 - -## 🔐 安全 - -### 凭证存储选项 - -安装程序提供两种存储区块链凭证的方法： - -**选项 1：配置文件存储** -- 密钥存储在 `~/.mcporter/mcporter.json` 中 -- 方便但不安全（明文） -- **重要**：使用 `chmod 600 ~/.mcporter/mcporter.json` 保护文件 -- 切勿共享或将此文件提交到版本控制 - -**选项 2：环境变量（推荐）** -- 密钥从 shell 环境中读取 -- 更安全，不存储在配置文件中 -- 添加到您的 shell 配置文件（`~/.zshrc`、`~/.bashrc` 等）： - ```bash - # 适用于 TRON - export TRON_PRIVATE_KEY="您的私钥" - export TRONGRID_API_KEY="您的 API 密钥" - - # 适用于 BSC/EVM 链 - export PRIVATE_KEY="0x_您的私钥" - ``` -- 添加后重启 shell 或运行 `source ~/.zshrc` - -### 最佳实践 - -- 使用有限资金的专用代理钱包 -- 切勿使用您的主个人钱包 -- 在使用主网之前，请在测试网（TRON 的 Nile，BSC 的 BSC Testnet）上进行测试 -- 不要允许 AI 代理扫描包含私钥的文件 - -## 使用风险自负 - -允许 AI 代理直接处理私钥涉及重大的安全风险。我们建议仅使用少量加密货币并谨慎行事。尽管有内置的安全措施，但不能保证您的资产不会丢失。此扩展目前处于实验阶段，尚未经过严格测试。它不提供任何保证或承担任何责任。在与主网交互之前，请务必在测试网（TRON 的 Nile，BSC 的 BSC Testnet）上验证您的设置。 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/sidebars.js b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/sidebars.js index b1ed9ffe..4df37998 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/sidebars.js +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/sidebars.js @@ -103,11 +103,12 @@ const sidebars = { label: 'TRON MCP Server', collapsed: true, items: [ - 'McpServer-Skills/MCP/TRONMCPServer/Intro', + 'McpServer-Skills/MCP/TRONMCPServer/QuickStart', 'McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess', 'McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment', - 'McpServer-Skills/MCP/TRONMCPServer/API', + 'McpServer-Skills/MCP/TRONMCPServer/ToolList', + 'McpServer-Skills/MCP/TRONMCPServer/FAQ', ], }, { @@ -116,9 +117,11 @@ const sidebars = { collapsed: true, items: [ 'McpServer-Skills/MCP/SUNMCPServer/Intro', + 'McpServer-Skills/MCP/SUNMCPServer/QuickStart', 'McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess', 'McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment', - 'McpServer-Skills/MCP/SUNMCPServer/API', + 'McpServer-Skills/MCP/SUNMCPServer/ToolList', + 'McpServer-Skills/MCP/SUNMCPServer/FAQ', ], }, { @@ -149,7 +152,7 @@ const sidebars = { type: 'category', label: 'Openclaw 扩展插件', collapsed: false, - items: ['Openclaw-extension/Overview', 'Openclaw-extension/Setup-use'], + items: ['Openclaw-extension/Intro', 'Openclaw-extension/QuickStart', 'Openclaw-extension/FAQ'], }, ], } diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/getting-started/quickstart-for-human.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/getting-started/quickstart-for-human.md index 5f9f976f..e9e03c1b 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/getting-started/quickstart-for-human.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/getting-started/quickstart-for-human.md @@ -97,7 +97,7 @@ import TabItem from '@theme/TabItem'; 打开终端，执行以下命令安装 x402 Python SDK： ```bash -pip install "bankofai-x402[tron] @ git+https://github.com/BofAI/x402.git@v0.3.1#subdirectory=python/x402" +pip install "bankofai-x402[tron] @ git+https://github.com/BofAI/x402.git#subdirectory=python/x402" ``` 再安装 EVM（BSC）所需的额外依赖： diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/getting-started/quickstart-for-sellers.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/getting-started/quickstart-for-sellers.md index 3f9dd176..f31500d1 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/getting-started/quickstart-for-sellers.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/getting-started/quickstart-for-sellers.md @@ -1,15 +1,15 @@ -# 卖家快速入门 - import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; +# 卖家快速入门 + > **测试网优先：** 本指南默认使用测试网，所有操作均使用免费测试代币，**不会涉及任何真实资金**。待测试通过后，再参考文末的[切换到主网](#在主网运行)章节进行上线。 ## 您将实现什么 完成本指南后，您将拥有一个**可对 API 调用收费的服务**： -- 当用户或 AI 代理调用您的 API 时，系统自动要求对方支付指定代币（默认为 USDT，同时支持 USDD 及自定义 TRC-20/BEP-20 代币） +- 当用户或 AI 代理调用您的 API 时，系统自动要求对方支付指定代币 - 支持按请求收费、计量使用、动态定价等多种收费模式 - 付款验证和区块链结算全程自动完成，收款直接到您的钱包 @@ -37,9 +37,8 @@ git --version # 版本控制工具 ### 创建收款钱包 -您需要一个区块链钱包地址，用于接收用户支付的代币（USDT 或 USDD）。请根据您选择的网络按照以下步骤操作： +您需要一个区块链钱包地址，用于接收用户支付的代币。请根据您选择的网络按照以下步骤操作： -> 💡 **关于 USDD：** USDD 是 TRON 网络的原生稳定币，与 USDT 同样受到 x402 的完整支持，在 TRON 主网上可优先考虑使用。BSC 网络目前仅支持 USDT。 @@ -105,7 +104,7 @@ git --version # 版本控制工具 **测试网 vs. 主网的区别：** - **测试网**：使用免费的测试代币，不涉及真实资金，适合开发和调试。网络标识符：`tron:nile` / `eip155:97` -- **主网**：涉及真实 USDT/USDD 支付，正式上线时使用。网络标识符：`tron:mainnet` / `eip155:56` +- **主网**：涉及真实支付，正式上线时使用。网络标识符：`tron:mainnet` / `eip155:56` --- @@ -116,7 +115,7 @@ git --version # 版本控制工具 **推荐方式（直接从 GitHub 安装，适合快速上手）：** ```bash -pip install "bankofai-x402[tron,fastapi] @ git+https://github.com/BofAI/x402.git@v0.3.1#subdirectory=python/x402" +pip install "bankofai-x402[tron,fastapi] @ git+https://github.com/BofAI/x402.git#subdirectory=python/x402" ``` 安装完成后，运行以下命令验证是否成功： @@ -507,7 +506,7 @@ curl http://localhost:8000/protected ## 在主网运行 -在测试网完整验证后，只需以下几步即可上线接收真实 USDT/USDD 付款： +在测试网完整验证后，只需以下几步即可上线接收真实付款： ### 1. 更新服务器配置 diff --git a/sidebars.js b/sidebars.js index cf477bd9..79785b69 100644 --- a/sidebars.js +++ b/sidebars.js @@ -101,10 +101,11 @@ const sidebars = { collapsed: true, items: [ 'McpServer-Skills/MCP/TRONMCPServer/Intro', + 'McpServer-Skills/MCP/TRONMCPServer/QuickStart', 'McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess', 'McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment', - 'McpServer-Skills/MCP/TRONMCPServer/API', - + 'McpServer-Skills/MCP/TRONMCPServer/ToolList', + 'McpServer-Skills/MCP/TRONMCPServer/FAQ', ], }, { @@ -113,10 +114,11 @@ const sidebars = { collapsed: true, items: [ 'McpServer-Skills/MCP/SUNMCPServer/Intro', + 'McpServer-Skills/MCP/SUNMCPServer/QuickStart', 'McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess', 'McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment', - 'McpServer-Skills/MCP/SUNMCPServer/API', - + 'McpServer-Skills/MCP/SUNMCPServer/ToolList', + 'McpServer-Skills/MCP/SUNMCPServer/FAQ', ], }, { @@ -147,7 +149,7 @@ const sidebars = { type: 'category', label: 'Openclaw Extension', collapsed: false, - items: ['Openclaw-extension/Overview', 'Openclaw-extension/Setup-use'], + items: ['Openclaw-extension/Intro', 'Openclaw-extension/QuickStart', 'Openclaw-extension/FAQ'], }, ], } From f22abdd1afe3a88419ff7a21ee2062e72735047e Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Tue, 17 Mar 2026 23:15:17 +0800 Subject: [PATCH 2/5] fix --- docs/McpServer-Skills/SKILLS/BANKOFAISkill.md | 17 ++++++++++------- docs/McpServer-Skills/SKILLS/Faq.md | 6 +++--- docs/Openclaw-extension/FAQ.md | 12 ++++++------ docs/Openclaw-extension/Intro.md | 7 ++++--- docs/Openclaw-extension/QuickStart.md | 16 ++++++++++------ .../McpServer-Skills/SKILLS/BANKOFAISkill.md | 15 +++++++++------ .../current/McpServer-Skills/SKILLS/Faq.md | 6 +++--- .../current/Openclaw-extension/FAQ.md | 11 ++++++----- .../current/Openclaw-extension/Intro.md | 7 ++++--- .../current/Openclaw-extension/QuickStart.md | 16 ++++++++++------ 10 files changed, 65 insertions(+), 48 deletions(-) diff --git a/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md b/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md index daa1a0b6..512c1fe5 100644 --- a/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md +++ b/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md @@ -22,7 +22,7 @@ BANK OF AI Skills can operate on **real on-chain assets**. Blockchain transactio | **sunperp-skill** | v1.0.0 | SunPerp perpetual contracts — market data, orders, positions, withdrawals | `SUNPERP_ACCESS_KEY` + `SUNPERP_SECRET_KEY` | | **tronscan-skill** | v1.0.0 | TronScan on-chain data queries — accounts, transactions, tokens, blocks | `TRONSCAN_API_KEY` | | **x402-payment** | v1.4.0 | x402 protocol payments — calling paid APIs and paid agents | `TRON_PRIVATE_KEY` or `EVM_PRIVATE_KEY` | -| **ainft-skill** | v1.1.1 | AINFT balance queries, order history, TRC20 deposits | `AINFT_API_KEY` | +| **recharge-skill** | v1.1.1 | BANK OF AI balance queries, order history, TRC20 recharge via MCP | `BANKOFAI_API_KEY` | --- @@ -48,7 +48,7 @@ Verify that skills are ready after installation: ls ~/.openclaw/skills ``` -You should see directories like `sunswap`, `sunperp-skill`, `tronscan-skill`, `x402-payment`, `ainft-skill`, etc. +You should see directories like `sunswap`, `sunperp-skill`, `tronscan-skill`, `x402-payment`, `recharge-skill`, etc. ### Installation on Other Platforms @@ -185,17 +185,20 @@ Use x402 protocol to call this paid agent endpoint: https://api.example.com Help me check the current Gasfree wallet status and available balance. ``` -### ainft-skill +### recharge-skill ``` # 🟢 Query balance -How much balance does my AINFT account have? +How much balance does my BANK OF AI account have? # 🟢 Query orders -Show my recent AINFT order history. +Show my recent BANK OF AI order history. -# ⚠️ Deposit -Deposit 1 USDT to my AINFT account. +# ⚠️ Recharge +Recharge 1 USDT to my BANK OF AI account. + +# ⚠️ Recharge (Chinese) +给 BANK OF AI 充值 1 USDT ``` --- diff --git a/docs/McpServer-Skills/SKILLS/Faq.md b/docs/McpServer-Skills/SKILLS/Faq.md index 459d92b4..d21c64d0 100644 --- a/docs/McpServer-Skills/SKILLS/Faq.md +++ b/docs/McpServer-Skills/SKILLS/Faq.md @@ -32,7 +32,7 @@ Currently supported: **OpenClaw** (most complete integration), **Claude Code**, ls ~/.openclaw/skills ``` -You should see directories like `sunswap`, `sunperp-skill`, `tronscan-skill`, `x402-payment`, `ainft-skill`, etc. +You should see directories like `sunswap`, `sunperp-skill`, `tronscan-skill`, `x402-payment`, `recharge-skill`, etc. Then verify in OpenClaw: @@ -75,8 +75,8 @@ export SUNPERP_SECRET_KEY="your_SunPerp_Secret_Key" # TronScan data queries (needed for tronscan-skill) export TRONSCAN_API_KEY="your_TronScan_API_Key" -# AINFT (needed for ainft-skill) -export AINFT_API_KEY="your_AINFT_API_Key" +# BANK OF AI (needed for recharge-skill) +export BANKOFAI_API_KEY="your_BANKOFAI_API_Key" ``` After adding them, run `source ~/.zshrc` to apply, then restart your AI tool. diff --git a/docs/Openclaw-extension/FAQ.md b/docs/Openclaw-extension/FAQ.md index f25e7148..f81ef02a 100644 --- a/docs/Openclaw-extension/FAQ.md +++ b/docs/Openclaw-extension/FAQ.md @@ -90,7 +90,6 @@ This is by design. Write tools only appear after wallet credentials are configur - Environment variable `PRIVATE_KEY` (bnbchain-mcp) - `env.TRON_PRIVATE_KEY` or `env.PRIVATE_KEY` for corresponding Server in mcporter.json -After configuring credentials, restart OpenClaw. For detailed instructions, see [Configuration Reference](./Configuration.md). ### MCP Server startup timeout @@ -137,15 +136,15 @@ cat ~/.x402-config.json Confirm it contains valid `gasfree_api_key` and `gasfree_api_secret`. If you need to reconfigure, you can edit the file directly or re-run the installer. -### AINFT API Key invalid +### BANK OF AI API Key invalid -Check contents of `~/.mcporter/ainft-config.json`: +Check contents of `~/.mcporter/bankofai-config.json` (or `~/.bankofai/config.json`): ```bash -cat ~/.mcporter/ainft-config.json +cat ~/.mcporter/bankofai-config.json ``` -Confirm the `api_key` field contains a valid Key. Note that ainft-skill has a credential priority order (CLI arguments > environment variables > config files); if you set different values in multiple places, you might read the unexpected one. +Confirm the `api_key` field contains a valid Key. Note that recharge-skill has a credential priority order (CLI arguments > environment variables > `bankofai-config.json` in working directory > `~/.bankofai/config.json` > `~/.mcporter/bankofai-config.json`); if you set different values in multiple places, you might read the unexpected one. --- @@ -203,7 +202,8 @@ OpenClaw Extension has no automatic uninstaller. Manual uninstall steps: 3. **Delete credential files**: ```bash rm -f ~/.x402-config.json - rm -f ~/.mcporter/ainft-config.json + rm -f ~/.mcporter/bankofai-config.json + rm -f ~/.bankofai/config.json rm -f ~/.clawdbot/wallets/.deployer_pk ``` 4. **Clean environment variables**: Remove related export statements from `~/.zshrc` or `~/.bashrc` diff --git a/docs/Openclaw-extension/Intro.md b/docs/Openclaw-extension/Intro.md index e2bc6f2f..f430344e 100644 --- a/docs/Openclaw-extension/Intro.md +++ b/docs/Openclaw-extension/Intro.md @@ -25,12 +25,13 @@ OpenClaw Extension consists of two main categories of components: **MCP Servers* ### MCP Server — On-Chain Operation Capabilities -MCP Servers are bridges between your AI assistant and the blockchain, providing on-chain operation capabilities through the [Model Context Protocol (MCP)](../McpServer-Skills/MCP/Intro.md) standard interface. Currently supports MCP Servers for three blockchain chains and one remote service: +MCP Servers are bridges between your AI assistant and the blockchain, providing on-chain operation capabilities through the [Model Context Protocol (MCP)](../McpServer-Skills/MCP/Intro.md) standard interface. Currently supports MCP Servers for two blockchain chains plus one remote recharge service: -| MCP Server | Target Chain | Core Capabilities | +| MCP Server | Target | Core Capabilities | | :--- | :--- | :--- | | **[mcp-server-tron](https://github.com/BofAI/mcp-server-tron)** | TRON | 95 tools covering wallets, transfers, contracts, staking, governance, and all operations | | **[bnbchain-mcp](https://github.com/bnb-chain/bnbchain-mcp)** | BSC / opBNB / Ethereum | Multi-chain EVM operations, wallets, contracts, cross-chain | +| **bankofai-recharge** | BANK OF AI (Remote) | Remote recharge MCP — top up your BANK OF AI account via on-chain USDT. Default endpoint: `https://recharge.bankofai.io/mcp` | ### Skills — Pre-built Workflows @@ -42,7 +43,7 @@ Skills are encapsulated business process templates. Unlike individual tools prov | **sunperp-skill** | SunPerp perpetual futures trading — market data, orders, positions, leverage, withdrawals | | **tronscan-skill** | Query on-chain data via TronScan API (accounts, transactions, tokens, blocks, network statistics) | | **x402-payment** | x402 payment skill for calling paid agents and APIs, supporting Gasfree zero-gas transactions | -| **ainft-skill** | AINFT balance and order queries, plus TRC20 top-ups | +| **recharge-skill** | BANK OF AI balance and order queries, plus TRC20 recharge via MCP | --- diff --git a/docs/Openclaw-extension/QuickStart.md b/docs/Openclaw-extension/QuickStart.md index 06119e32..6d68195c 100644 --- a/docs/Openclaw-extension/QuickStart.md +++ b/docs/Openclaw-extension/QuickStart.md @@ -51,11 +51,13 @@ The installer displays all available MCP Servers and asks which ones you want to 📦 Available MCP Servers: 1) mcp-server-tron - TRON blockchain interaction 2) bnbchain-mcp - BNB Chain (BSC, opBNB, Ethereum) interaction - 3) ainft-merchant - Remote AINFT recharge MCP + 3) bankofai-recharge - Remote BANK OF AI recharge MCP Select servers to install (e.g., 1,2,3 or 'all'): ``` +> **Note on bankofai-recharge**: This is a remote MCP that connects directly to `https://recharge.bankofai.io/mcp`. No local credentials are needed — the installer configures the endpoint automatically. + For each selected server, the installer continues by asking how you want to store credentials: - **Option 1: Save to Configuration File** — Keys stored in plaintext in `~/.mcporter/mcporter.json`. Convenient but lower security. @@ -71,10 +73,11 @@ The installer clones the [Skills repository](https://github.com/BofAI/skills) fr ``` 🔧 Available Skills: - 1) sunswap - SunSwap DEX trading skill - 2) tronscan-skill - TRON blockchain data lookup - 3) x402-payment - Agent payment protocol (x402) - 4) ainft-skill - AINFT balance/order queries + 1) recharge-skill - BANK OF AI account query and recharge + 2) sunperp-skill - SunPerp perpetual futures trading (TRON) + 3) sunswap - SunSwap DEX trading skill + 4) tronscan-skill - TRON blockchain data lookup + 5) x402-payment - Agent payment protocol (x402) Select skills to install (e.g., 1,2,3 or 'all'): ``` @@ -89,8 +92,9 @@ Then choose the installation location: Some Skills have additional credential requirements, which the installer will prompt you for during installation: +- **recharge-skill** — Requires BANK OF AI API Key (`BANKOFAI_API_KEY`) +- **sunperp-skill** — Requires SunPerp API keys (`SUNPERP_ACCESS_KEY` + `SUNPERP_SECRET_KEY`) - **x402-payment** — Optional configuration of Gasfree API credentials (for zero-gas transactions) -- **ainft-skill** — Requires AINFT API Key - **tronscan-skill** — Prompts you to set `TRONSCAN_API_KEY` environment variable in your shell - **sunswap** — Prompts to configure TRON private key (if not configured earlier) diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md index 9705fd73..3695db57 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md @@ -22,7 +22,7 @@ BANK OF AI Skills 可以操作**真实的链上资产**。区块链交易一旦 | **sunperp-skill** | v1.0.0 | SunPerp 永续合约——行情、下单、仓位、提现 | `SUNPERP_ACCESS_KEY` + `SUNPERP_SECRET_KEY` | | **tronscan-skill** | v1.0.0 | TronScan 链上数据查询——账户、交易、代币、区块 | `TRONSCAN_API_KEY` | | **x402-payment** | v1.4.0 | x402 协议支付——调用付费 API 和付费智能体 | `TRON_PRIVATE_KEY` 或 `EVM_PRIVATE_KEY` | -| **ainft-skill** | v1.1.1 | AINFT 余额查询、订单记录、TRC20 充值 | `AINFT_API_KEY` | +| **recharge-skill** | v1.1.1 | BANK OF AI 余额查询、订单记录、通过 MCP 充值 | `BANKOFAI_API_KEY` | --- @@ -48,7 +48,7 @@ cd openclaw-extension ls ~/.openclaw/skills ``` -你应该能看到 `sunswap`、`sunperp-skill`、`tronscan-skill`、`x402-payment`、`ainft-skill` 等目录。 +你应该能看到 `sunswap`、`sunperp-skill`、`tronscan-skill`、`x402-payment`、`recharge-skill` 等目录。 ### 其他平台安装 @@ -185,17 +185,20 @@ BTC-USDT 永续合约的当前价格、24h 涨跌幅和资金费率是多少？ 帮我查看当前 Gasfree 钱包的状态和可用余额。 ``` -### ainft-skill +### recharge-skill ``` # 🟢 查询余额 -我的 AINFT 账户还有多少余额？ +我的 BANK OF AI 账户还有多少余额？ # 🟢 查询订单 -显示我最近的 AINFT 订单记录。 +显示我最近的 BANK OF AI 订单记录。 # ⚠️ 充值 -给我的 AINFT 账户充值 1 USDT。 +给 BANK OF AI 充值 1 USDT。 + +# ⚠️ 充值（英文） +Recharge 1 USDT to my BANK OF AI account. ``` --- diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Faq.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Faq.md index 95a9d1da..3f094c6e 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Faq.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/Faq.md @@ -32,7 +32,7 @@ MCP Server 提供原子级工具——比如"查余额"、"发起转账"、"调 ls ~/.openclaw/skills ``` -应该能看到 `sunswap`、`sunperp-skill`、`tronscan-skill`、`x402-payment`、`ainft-skill` 等目录。 +应该能看到 `sunswap`、`sunperp-skill`、`tronscan-skill`、`x402-payment`、`recharge-skill` 等目录。 然后在 OpenClaw 中验证： @@ -75,8 +75,8 @@ export SUNPERP_SECRET_KEY="你的 SunPerp Secret Key" # TronScan 数据查询（tronscan-skill 需要） export TRONSCAN_API_KEY="你的 TronScan API Key" -# AINFT（ainft-skill 需要） -export AINFT_API_KEY="你的 AINFT API Key" +# BANK OF AI（recharge-skill 需要） +export BANKOFAI_API_KEY="你的 BANK OF AI API Key" ``` 添加后执行 `source ~/.zshrc` 生效，然后重启 AI 工具。 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/FAQ.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/FAQ.md index 5f764aad..29b344d2 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/FAQ.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/FAQ.md @@ -137,15 +137,15 @@ cat ~/.x402-config.json 确认包含有效的 `gasfree_api_key` 和 `gasfree_api_secret`。如果需要重新配置，可以直接编辑文件或重新运行安装程序。 -### AINFT API Key 无效 +### BANK OF AI API Key 无效 -检查 `~/.mcporter/ainft-config.json` 的内容： +检查 `~/.bankofai/config.json` 或 `~/.mcporter/bankofai-config.json` 的内容： ```bash -cat ~/.mcporter/ainft-config.json +cat ~/.bankofai/config.json ``` -确认 `api_key` 字段包含有效的 Key。注意 ainft-skill 的凭证读取有优先级顺序（CLI 参数 > 环境变量 > 配置文件），如果你在多个地方设置了不同的值，可能会读到意外的那个。 +确认 `api_key` 字段包含有效的 Key。注意 recharge-skill 的凭证读取有优先级顺序（CLI 参数 > 环境变量 > 工作目录 `bankofai-config.json` > `~/.bankofai/config.json` > `~/.mcporter/bankofai-config.json`），如果你在多个地方设置了不同的值，可能会读到意外的那个。 --- @@ -204,7 +204,8 @@ OpenClaw Extension 没有自动卸载程序。手动卸载步骤： 3. **删除凭证文件**： ```bash rm -f ~/.x402-config.json - rm -f ~/.mcporter/ainft-config.json + rm -f ~/.bankofai/config.json + rm -f ~/.mcporter/bankofai-config.json rm -f ~/.clawdbot/wallets/.deployer_pk ``` 4. **清理环境变量**：从 `~/.zshrc` 或 `~/.bashrc` 中移除相关 export 语句 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/Intro.md index c7a55281..3a94dd35 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/Intro.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/Intro.md @@ -25,12 +25,13 @@ OpenClaw Extension 由两大类组件构成：**MCP Server** 和 **Skills**。 ### MCP Server — 链上操作能力 -MCP Server 是 AI 助手与区块链之间的桥梁，通过 [Model Context Protocol (MCP)](../McpServer-Skills/MCP/Intro.md) 标准接口提供链上操作能力。目前支持三条链的 MCP Server 和一个远程服务： +MCP Server 是 AI 助手与区块链之间的桥梁，通过 [Model Context Protocol (MCP)](../McpServer-Skills/MCP/Intro.md) 标准接口提供链上操作能力。目前支持两条链的 MCP Server 和一个远程充值服务： -| MCP Server | 目标链 | 核心能力 | +| MCP Server | 目标 | 核心能力 | | :--- | :--- | :--- | | **[mcp-server-tron](https://github.com/BofAI/mcp-server-tron)** | TRON | 95 个工具，覆盖钱包、转账、合约、质押、治理等全部操作 | | **[bnbchain-mcp](https://github.com/bnb-chain/bnbchain-mcp)** | BSC / opBNB / 以太坊 | 多链 EVM 操作、钱包、合约、跨链 | +| **bankofai-recharge** | BANK OF AI（远程） | 远程充值 MCP——通过链上 USDT 为 BANK OF AI 账户充值。默认端点：`https://recharge.bankofai.io/mcp` | ### Skills — 预构建工作流 @@ -42,7 +43,7 @@ Skills 是封装好的业务流程模板。与 MCP Server 提供的单个工具 | **sunperp-skill** | SunPerp 永续合约交易——行情、下单、仓位管理、杠杆设置、提现 | | **tronscan-skill** | 通过 TronScan API 查询链上数据（账户、交易、代币、区块、全网统计） | | **x402-payment** | x402 支付技能，调用付费智能体和付费 API，支持 Gasfree 免 Gas 交易 | -| **ainft-skill** | AINFT 余额和订单查询，以及 TRC20 充值 | +| **recharge-skill** | BANK OF AI 余额和订单查询，以及通过 MCP 充值 | --- diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/QuickStart.md index 3d950639..8a372b59 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/QuickStart.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/QuickStart.md @@ -52,11 +52,13 @@ cd openclaw-extension 📦 Available MCP Servers: 1) mcp-server-tron - TRON blockchain interaction 2) bnbchain-mcp - BNB Chain (BSC, opBNB, Ethereum) interaction - 3) ainft-merchant - Remote AINFT recharge MCP + 3) bankofai-recharge - Remote BANK OF AI recharge MCP Select servers to install (e.g., 1,2,3 or 'all'): ``` +> **关于 bankofai-recharge**：这是一个远程 MCP，直接连接到 `https://recharge.bankofai.io/mcp`，无需配置本地凭证——安装程序会自动配置好远程端点。 + 对于每个选中的服务器，安装程序会继续询问凭证存储方式： - **选项 1：保存到配置文件** — 密钥以明文存储在 `~/.mcporter/mcporter.json` 中。方便但安全性较低。 @@ -72,10 +74,11 @@ Select servers to install (e.g., 1,2,3 or 'all'): ``` 🔧 Available Skills: - 1) sunswap - SunSwap DEX trading skill - 2) tronscan-skill - TRON blockchain data lookup - 3) x402-payment - Agent payment protocol (x402) - 4) ainft-skill - AINFT balance/order queries + 1) recharge-skill - BANK OF AI account query and recharge + 2) sunperp-skill - SunPerp perpetual futures trading (TRON) + 3) sunswap - SunSwap DEX trading skill + 4) tronscan-skill - TRON blockchain data lookup + 5) x402-payment - Agent payment protocol (x402) Select skills to install (e.g., 1,2,3 or 'all'): ``` @@ -90,8 +93,9 @@ Select skills to install (e.g., 1,2,3 or 'all'): 部分 Skill 有额外的凭证需求，安装程序会在安装时逐一提示： +- **recharge-skill** — 需要 BANK OF AI API Key（`BANKOFAI_API_KEY`） +- **sunperp-skill** — 需要 SunPerp API 密钥（`SUNPERP_ACCESS_KEY` + `SUNPERP_SECRET_KEY`） - **x402-payment** — 可选配置 Gasfree API 凭证（用于免 Gas 交易） -- **ainft-skill** — 需要 AINFT API Key - **tronscan-skill** — 提示你在 shell 中设置 `TRONSCAN_API_KEY` 环境变量 - **sunswap** — 提示配置 TRON 私钥（如果前面没有配置） From 477757c728929ad9ada5d6d99b8e2a1b8109e972 Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Wed, 18 Mar 2026 01:30:02 +0800 Subject: [PATCH 3/5] fix --- docs/McpServer-Skills/Intro.md | 11 +--- docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md | 54 ++--------------- .../MCP/SUNMCPServer/Intro.md | 2 +- .../SUNMCPServer/LocalPrivatizedDeployment.md | 58 +++++------------- .../MCP/SUNMCPServer/OfficialServerAccess.md | 31 +--------- .../MCP/SUNMCPServer/ToolList.md | 29 ++++----- .../LocalPrivatizedDeployment.md | 2 +- .../MCP/TRONMCPServer/OfficialServerAccess.md | 4 +- .../MCP/TRONMCPServer/ToolList.md | 17 +++++- docs/McpServer-Skills/SKILLS/BANKOFAISkill.md | 3 - docs/Openclaw-extension/FAQ.md | 9 --- docs/Openclaw-extension/Intro.md | 2 +- docs/Openclaw-extension/QuickStart.md | 1 - .../current/McpServer-Skills/Intro.md | 12 +--- .../McpServer-Skills/MCP/SUNMCPServer/FAQ.md | 56 ++--------------- .../MCP/SUNMCPServer/Intro.md | 2 +- .../SUNMCPServer/LocalPrivatizedDeployment.md | 60 +++++-------------- .../MCP/SUNMCPServer/OfficialServerAccess.md | 31 +--------- .../MCP/SUNMCPServer/ToolList.md | 22 +++---- .../LocalPrivatizedDeployment.md | 19 ++++-- .../MCP/TRONMCPServer/OfficialServerAccess.md | 4 +- .../McpServer-Skills/SKILLS/BANKOFAISkill.md | 3 - .../current/Openclaw-extension/FAQ.md | 9 --- .../current/Openclaw-extension/Intro.md | 2 +- .../current/Openclaw-extension/QuickStart.md | 1 - 25 files changed, 107 insertions(+), 337 deletions(-) diff --git a/docs/McpServer-Skills/Intro.md b/docs/McpServer-Skills/Intro.md index d5f772af..1ed5acb0 100644 --- a/docs/McpServer-Skills/Intro.md +++ b/docs/McpServer-Skills/Intro.md @@ -1,15 +1,10 @@ # Introduction -BANK OF AI provides a complete solution, from infrastructure to business logic, for building autonomous AI Agents based on blockchain networks through a dual-layer architecture of MCP Server and Skills. +BANK OF AI provides a comprehensive AI Agent capability framework through **MCP Server** and **Skills**: the former delivers standardized blockchain interaction capabilities, while the latter organizes these capabilities into executable workflows, enabling AI Agents to perform complex operations in on-chain environments. -Developers only need to deploy the MCP Server and load the corresponding Skills to evolve AI agents from "chatbots" into Web3 economic entities with asset management capabilities and on-chain interaction abilities. +* **MCP Server** is designed to provide a standardized framework for interactions between Large Language Models (LLMs) and external tools and data sources. Its core lies in a well-defined client-server architecture and layered communication mechanism, ensuring that AI applications can securely and efficiently access and utilize external information. -## Architecture Overview - -| Layer | Component | Role | -| :--- | :--- | :--- | -| Infrastructure Layer | **MCP Server** | Provides AI agents with low-level capabilities for blockchain interaction (querying data, initiating transactions, calling contracts, etc.) | -| Business Logic Layer | **Skills** | Provides AI agents with domain-specific operation guides and workflows (e.g., DEX trading, payment protocols, etc.) | +* **Skills** are capability abstractions that orchestrate multiple tools into structured workflows, enabling AI Agents to complete complex, multi-step tasks. ## Quick Navigation diff --git a/docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md b/docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md index f8047732..45160178 100644 --- a/docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md +++ b/docs/McpServer-Skills/MCP/SUNMCPServer/FAQ.md @@ -163,43 +163,6 @@ echo "your_private_key" | grep -E '^[0-9a-fA-F]{64}$' - Use strong password (minimum 8 characters) - Avoid special characters, use alphanumeric combination -### TronGrid API Key Not Working - -**Symptom:** API calls return errors or rate limiting errors. - -**Resolution Steps:** - -1. **Check Environment Variable Name** - ```bash - # Correct name - export TRON_GRID_API_KEY="your_api_key" - - # Incorrect name (common error) - export TRONGRID_API_KEY="..." # ❌ Don't do this - ``` - -2. **Verify API Key Validity** - - Log in to [TronGrid Dashboard](https://dashboard.trongrid.io) - - Confirm API Key not expired or disabled - - Check request quota is sufficient - -3. **Verify Environment Variable Set** - ```bash - echo $TRON_GRID_API_KEY - ``` - -4. **Restart Server** - ```bash - # Restart after setting - npx -y @bankofai/sun-mcp-server - ``` - -5. **Check Network Connection** - ```bash - curl -H "TRONGRID-API-KEY: $TRON_GRID_API_KEY" \ - https://api.trongrid.io/v1/now - # Should return block information - ``` ### "Conflicting Wallet Modes" @@ -387,7 +350,7 @@ Check transaction hash details on https://tronscan.org for error message 1. **Provide Accurate Address in Prompt** ``` - Please use USDT (T9yD14Nj9j7xAB4dbGknA47WWJcZ541TZJ) + Please use USDT (TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t) ``` 2. **Use Official Token List** @@ -428,22 +391,15 @@ Check transaction hash details on https://tronscan.org for error message **Optimization Steps:** -1. **Configure TronGrid API Key** - ```bash - export TRON_GRID_API_KEY="your_api_key" - ``` - - Without API Key uses public node, slower speed - - With API Key accesses dedicated node - -2. **Simplify Workflow** +1. **Simplify Workflow** - Reduce multi-tool coordination steps - Avoid large number of consecutive queries -3. **Use Local Server** +2. **Use Local Server** - See [Local Privatized Deployment](LocalPrivatizedDeployment.md) - May be faster than official server (depends on network) -4. **Batch Operations** +3. **Batch Operations** ``` Merge related queries to reduce round trips ``` @@ -574,6 +530,6 @@ npm update @modelcontextprotocol/sdk ## Get More Help - **GitHub Issues:** https://github.com/BofAI/sun-mcp-server/issues -- **Complete Documentation:** Check [Tool List](ToolList.md) and [Best Practices](BestPractices.md) +- **Full Capability List:** Check [Full Capability List](ToolList.md) - **Local Deployment:** See [Local Privatized Deployment](LocalPrivatizedDeployment.md) - **Official Server:** See [Official Server Access](OfficialServerAccess.md) diff --git a/docs/McpServer-Skills/MCP/SUNMCPServer/Intro.md b/docs/McpServer-Skills/MCP/SUNMCPServer/Intro.md index a9185a4b..cb3635f5 100644 --- a/docs/McpServer-Skills/MCP/SUNMCPServer/Intro.md +++ b/docs/McpServer-Skills/MCP/SUNMCPServer/Intro.md @@ -17,7 +17,7 @@ What this means for different people: ## What can it do? -SUN MCP Server covers the full range of SunSwap DEX interactions, from on-chain data queries to token swaps and liquidity management, providing **41 tools** (18 custom tools + 23 SUN.IO OpenAPI tools). +SUN MCP Server covers the full range of SunSwap DEX interactions, from on-chain data queries to token swaps and liquidity management, providing **41 tools**. Here's a capability overview—each item can be triggered through natural language: diff --git a/docs/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md b/docs/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md index 69ff4028..e6876113 100644 --- a/docs/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md +++ b/docs/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md @@ -123,33 +123,8 @@ Same security risks as the private key option. Mnemonic phrases stored in plaint --- -### Step 2: Configure Network (Optional) -#### TronGrid API Key - -TronGrid is the official TRON RPC provider. Using an API Key can increase request rate limits. - -**Getting an API Key:** - -1. Visit [TronGrid Official Website](https://www.trongrid.io) -2. Register an account or log in -3. Generate an API Key in the console -4. Copy the API Key to environment variable - -**Environment Variables:** - -```bash -TRON_GRID_API_KEY=your_api_key_here -``` - -:::info -If you don't set `TRON_GRID_API_KEY`, SUN MCP Server will use public endpoints, but may be subject to rate limiting. -::: - - ---- - -### Step 3: Install Server +### Step 2: Local Private Deployment #### Option A: Run directly with npx (Recommended) @@ -169,7 +144,7 @@ npx -y @bankofai/sun-mcp-server **Run with environment variables:** ```bash -TRON_NETWORK=nile TRON_GRID_API_KEY=your_api_key npx -y @bankofai/sun-mcp-server +TRON_NETWORK=nile npx -y @bankofai/sun-mcp-server ``` #### Option B: Clone from Source @@ -202,7 +177,7 @@ sun-mcp-server --- -### Step 4: Connect AI Client +### Step 3: Client Configuration After configuration is complete, you need to add the connection definition of SUN MCP Server in your AI client. @@ -236,7 +211,6 @@ Add to `~/.claude/resources/mcp/servers.json`: "env": { "AGENT_WALLET_PASSWORD": "your_secure_password", "AGENT_WALLET_DIR": "~/.agent-wallet", - "TRON_GRID_API_KEY": "your_api_key", "TRON_NETWORK": "nile" } } @@ -244,11 +218,14 @@ Add to `~/.claude/resources/mcp/servers.json`: } ``` -**Claude Code (CLI) Configuration:** +**Claude Code** ```bash -export MCP_SERVERS='{"sun":{"command":"npx","args":["-y","@bankofai/sun-mcp-server"],"env":{"TRON_NETWORK":"nile","TRON_GRID_API_KEY":"your_api_key"}}}' -claude code +# Basic +claude mcp add sun-mcp-server -- npx -y @bankofai/sun-mcp-server + +# With environment variables +claude mcp add -e AGENT_WALLET_PASSWORD=xxx sun-mcp-server -- npx -y @bankofai/sun-mcp-server ``` **Cursor Configuration:** @@ -262,8 +239,7 @@ Add to `~/.cursor/extensions/mcp/servers.json`: "command": "npx", "args": ["-y", "@bankofai/sun-mcp-server"], "env": { - "TRON_NETWORK": "nile", - "TRON_GRID_API_KEY": "your_api_key" + "TRON_NETWORK": "nile" } } } @@ -288,7 +264,6 @@ Add to `~/.claude/resources/mcp/servers.json`: "args": ["tsx", "/path/to/sun-mcp-server/src/index.ts"], "env": { "AGENT_WALLET_PASSWORD": "your_secure_password", - "TRON_GRID_API_KEY": "your_api_key", "TRON_NETWORK": "nile" } } @@ -307,8 +282,7 @@ Add to `~/.cursor/extensions/mcp/servers.json`: "command": "npx", "args": ["tsx", "/path/to/sun-mcp-server/src/index.ts"], "env": { - "TRON_NETWORK": "nile", - "TRON_GRID_API_KEY": "your_api_key" + "TRON_NETWORK": "nile" } } } @@ -364,7 +338,6 @@ HTTP mode is suitable for local development and testing. For remote deployment, ```bash export TRON_NETWORK=nile -export TRON_GRID_API_KEY=your_api_key sun-mcp-server --transport streamable-http --host 127.0.0.1 --port 8080 --mcpPath /mcp ``` @@ -373,7 +346,7 @@ sun-mcp-server --transport streamable-http --host 127.0.0.1 --port 8080 --mcpPat --- -### Step 5: Verify Connection +### Step 4: Verify Connection After starting the AI client, you should be able to see the tool list of SUN MCP Server. Perform the following tests to confirm the configuration is correct: @@ -382,7 +355,7 @@ After starting the AI client, you should be able to see the tool list of SUN MCP Try the following command in chat: ``` -Query the block height of TRON mainnet +Check the current prices of USDT and TRX on SunSwap ``` Expect to receive the current block number. @@ -405,9 +378,8 @@ You can get test TRX from [TRON Nile Faucet](https://nile.trongrid.io/join), the If you encounter connection issues: 1. **Check Network Connection**: Ensure you can access TRON network endpoints -2. **Verify API Key**: If `TRON_GRID_API_KEY` is configured, ensure it's valid -3. **View Logs**: When running the server, check console output for error messages -4. **Test Network**: Try switching to testnet (Nile) to rule out network issues +2. **View Logs**: When running the server, check console output for error messages +3. **Test Network**: Try switching to testnet (Nile) to rule out network issues ::: --- diff --git a/docs/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md b/docs/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md index cf5946b2..4aa271a2 100644 --- a/docs/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md +++ b/docs/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md @@ -37,15 +37,6 @@ Add the following MCP service endpoint to your AI client configuration: > Note: This is an MCP protocol endpoint, not a webpage. Opening it directly in a browser will not display anything. -The official cloud service supports **two usage modes**: - -| Mode | Rate Limit | Description | -| :--- | :--- | :--- | -| **Without API Key (default)** | 100,000 requests / day | Ready to use immediately, suitable for getting started and low-frequency queries | -| **With TronGrid API Key** | 500,000 requests / day | Higher request limit, suitable for frequent queries and production use | - -For use cases involving frequent mainnet data queries, it is recommended to register a free TronGrid API Key at [trongrid.io](https://www.trongrid.io/), and configure it in the request header for higher throughput and stability. - --- ## Client Configuration @@ -57,7 +48,7 @@ Configuration file path: - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` -**Basic Config (No API Key)**: +**Basic Config**: ```json { @@ -73,26 +64,6 @@ Configuration file path: } ``` -**Config with TronGrid API Key**: - -```json -{ - "mcpServers": { - "sun-mcp-server": { - "command": "npx", - "args": [ - "mcp-remote", - "https://sun-mcp-server.bankofai.io/mcp", - "--header", - "TRONGRID-API-KEY:" - ] - } - } -} -``` - -Replace `` with your actual TronGrid API Key. - diff --git a/docs/McpServer-Skills/MCP/SUNMCPServer/ToolList.md b/docs/McpServer-Skills/MCP/SUNMCPServer/ToolList.md index fb5fd1dc..09625201 100644 --- a/docs/McpServer-Skills/MCP/SUNMCPServer/ToolList.md +++ b/docs/McpServer-Skills/MCP/SUNMCPServer/ToolList.md @@ -1,16 +1,22 @@ # Full Capability List -SUN MCP Server provides **41 tools** (18 custom DeFi tools + 23 SUN.IO OpenAPI derived tools). +SUN MCP Server provides **41 tools**. -## Understanding Two Key Concepts +## Understand Two Key Concepts First + +Before browsing the tool list, there are two things you should know: :::info Read vs Write -- **Read Tools**: Only query data, do not affect on-chain state. Can be used in both cloud service and local deployment. -- **Write Tools**: Modify on-chain state (swaps, liquidity operations, etc.). Only available in local deployment with configured wallet. +Each tool is labeled with a **mode** — "read" or "write": + +- **Read tools**: Only query on-chain data and do not affect any state. They can be used in both cloud services and local deployments. +- **Write tools**: Modify blockchain state (e.g., transfers, staking, contract interactions). These are only available in local deployments with a configured wallet. + +If you have not configured a wallet, write tools will not appear in the AI’s available tool list — they are automatically hidden, so there’s no risk of triggering them by mistake. ::: -:::tip network Parameter -Most tools have an optional `network` parameter to specify the network environment for interaction. Defaults to mainnet configuration, can also switch to testnet. +:::tip `network` parameter +Most tools include an optional `network` parameter used to specify the target network environment. By default, the mainnet is used, but it can be switched to a testnet if needed. ::: --- @@ -340,15 +346,4 @@ System automatically: Although most parameters are auto-calculated, for critical operations (such as adding large amounts of liquidity), it's recommended to actively specify parameters to get higher control precision. ::: ---- - -## Quick Reference - -**Need to query data?** Use read tools: `get_*`, `search_*`, `scan*` series. - -**Need to execute transactions?** Use write tools: `swap`, `mint`, `add`, `remove`, `collect`, `send_contract` series. - -**Not sure about parameters?** Tools will auto-calculate reasonable defaults, or prompt you for additional info when necessary. - -**Want to learn more?** Check [SUN MCP Server main documentation](../README.md) or [API Reference](../API-Reference.md). diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md b/docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md index 13ea15ee..989afc6f 100644 --- a/docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md +++ b/docs/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md @@ -335,5 +335,5 @@ You can get free test TRX for the Nile testnet from the TRON faucet. Visit [nile ## Next Steps -- Want to see detailed parameters and usage for each tool? → [Full Capability Listt](./ToolList.md) +- Want to see detailed parameters and usage for each tool? → [Full Capability List](./ToolList.md) - Encountering issues? → [FAQ](./FAQ.md) diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md b/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md index 86127c3a..f560cab3 100644 --- a/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md +++ b/docs/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md @@ -60,14 +60,14 @@ The official cloud service supports **two usage modes**: | Mode | Rate Limit | Description | | :--- | :--- | :--- | -| **Without API Key (default)** | 100,000 requests / day | Ready to use immediately, suitable for getting started and low-frequency queries | +| **Without TronGrid API Key (default)** | 100,000 requests / day | Ready to use immediately, suitable for getting started and low-frequency queries | | **With TronGrid API Key** | 500,000 requests / day | Higher request limit, suitable for frequent queries and production use | Both modes use the same connection method — the only difference is the request rate limit. --- -### Without API Key Mode (Default) +### Without TronGrid API Key Mode (Default) No API Key configuration needed to get started. Best for: diff --git a/docs/McpServer-Skills/MCP/TRONMCPServer/ToolList.md b/docs/McpServer-Skills/MCP/TRONMCPServer/ToolList.md index 52442e40..d5f361cf 100644 --- a/docs/McpServer-Skills/MCP/TRONMCPServer/ToolList.md +++ b/docs/McpServer-Skills/MCP/TRONMCPServer/ToolList.md @@ -2,13 +2,24 @@ TRON MCP Server provides **95 tools**, **6 prompts**, and **1 resource** for interacting with the TRON blockchain. Tools are the core capability — they are the actual functions the AI calls on your behalf. +## Understand Two Key Concepts First + +Before exploring the tool list, there are two important things you should know: + :::info Read vs Write -- **Read** tools: Available in both cloud (read-only) and local deployments. These are query-only operations with no on-chain impact. -- **Write** tools: Only available with local deployment + wallet configured. These modify blockchain state (transfers, staking, contract calls, etc.). +Each tool is labeled with a **mode** — "read" or "write": + +- **Read tools**: Only query on-chain data and do not affect any state. They can be used in both cloud services and local deployments. +- **Write tools**: Modify blockchain state (e.g., transfers, staking, contract interactions). These are only available in local deployments with a configured wallet. -If no wallet is configured, write tools are automatically hidden from the AI. +If you have not configured a wallet, write tools will not appear in the AI’s available tool list — they are automatically hidden, so there’s no risk of triggering them by mistake. ::: +:::tip `network` parameter +Most tools include an optional `network` parameter used to specify the target network (`mainnet`, `nile`, or `shasta`). If not specified, the default is `mainnet`. + +During testing, it is recommended to explicitly set `nile` each time to avoid unintended operations on the mainnet. +::: --- ## Tools (95 total) diff --git a/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md b/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md index 512c1fe5..56cb8e2b 100644 --- a/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md +++ b/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md @@ -180,9 +180,6 @@ Query the last 20 USDT transfers from address TXX... ``` # ⚠️ Call paid endpoint Use x402 protocol to call this paid agent endpoint: https://api.example.com - -# 🟢 Check Gasfree status -Help me check the current Gasfree wallet status and available balance. ``` ### recharge-skill diff --git a/docs/Openclaw-extension/FAQ.md b/docs/Openclaw-extension/FAQ.md index f81ef02a..9666845f 100644 --- a/docs/Openclaw-extension/FAQ.md +++ b/docs/Openclaw-extension/FAQ.md @@ -126,15 +126,6 @@ Validation: Import the private key into the appropriate wallet (TronLink or Meta 2. **Is Key still valid?**: Log in to [trongrid.io](https://www.trongrid.io/) to check status 3. **Is it properly loaded?**: If set in environment variables, confirm you ran `source ~/.zshrc` -### Gasfree credentials not working - -Check format and contents of `~/.x402-config.json`: - -```bash -cat ~/.x402-config.json -``` - -Confirm it contains valid `gasfree_api_key` and `gasfree_api_secret`. If you need to reconfigure, you can edit the file directly or re-run the installer. ### BANK OF AI API Key invalid diff --git a/docs/Openclaw-extension/Intro.md b/docs/Openclaw-extension/Intro.md index f430344e..d4814867 100644 --- a/docs/Openclaw-extension/Intro.md +++ b/docs/Openclaw-extension/Intro.md @@ -42,7 +42,7 @@ Skills are encapsulated business process templates. Unlike individual tools prov | **sunswap** | SunSwap DEX trading including balance queries, quotes, swaps, and liquidity management | | **sunperp-skill** | SunPerp perpetual futures trading — market data, orders, positions, leverage, withdrawals | | **tronscan-skill** | Query on-chain data via TronScan API (accounts, transactions, tokens, blocks, network statistics) | -| **x402-payment** | x402 payment skill for calling paid agents and APIs, supporting Gasfree zero-gas transactions | +| **x402-payment** | x402 payment skill for calling paid agents and APIs | | **recharge-skill** | BANK OF AI balance and order queries, plus TRC20 recharge via MCP | diff --git a/docs/Openclaw-extension/QuickStart.md b/docs/Openclaw-extension/QuickStart.md index 6d68195c..291c504b 100644 --- a/docs/Openclaw-extension/QuickStart.md +++ b/docs/Openclaw-extension/QuickStart.md @@ -94,7 +94,6 @@ Some Skills have additional credential requirements, which the installer will pr - **recharge-skill** — Requires BANK OF AI API Key (`BANKOFAI_API_KEY`) - **sunperp-skill** — Requires SunPerp API keys (`SUNPERP_ACCESS_KEY` + `SUNPERP_SECRET_KEY`) -- **x402-payment** — Optional configuration of Gasfree API credentials (for zero-gas transactions) - **tronscan-skill** — Prompts you to set `TRONSCAN_API_KEY` environment variable in your shell - **sunswap** — Prompts to configure TRON private key (if not configured earlier) diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/Intro.md index 93ef4ec9..6ce0f812 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/Intro.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/Intro.md @@ -1,15 +1,9 @@ # 简介 -BANK OF AI 通过 **MCP Server** 与 **Skills** 的双层架构，为构建基于区块链网络的自主智能体（AI Agents）提供了从基础设施到业务逻辑的完整解决方案。 +BANK OF AI 通过 **MCP Server** 与 **Skills** 构建了一套完整的 AI Agent 能力体系：前者负责提供标准化的区块链交互能力，后者负责将这些能力组织为可执行的任务流程，从而支持 AI Agents 在链上环境中完成复杂操作。 -## 架构概览 - -| 层级 | 组件 | 作用 | -| :--- | :--- | :--- | -| 基础设施层 | **MCP Server** | 为 AI 智能体提供与区块链交互的底层能力（查询数据、发起交易、调用合约等） | -| 业务逻辑层 | **Skills** | 为 AI 智能体提供特定领域的操作指南和工作流（如 DEX 交易、支付协议等） | - -开发者只需部署 MCP Server 并加载相应的 Skills，即可让 AI 智能体从"聊天机器人"进化为具备资产管理能力与链上交互能力的 Web3 经济实体。 +* **MCP Server** 旨在为大型语言模型 (LLM) 与外部工具和数据源之间的交互提供一个标准化的框架。其核心在于一个清晰定义的客户端-服务器架构和分层通信机制，确保了 AI 应用能够安全、高效地访问和利用外部信息。 +* **Skills** 是用于将多个工具按流程编排起来，帮助 AI 完成复杂任务的能力封装。 ## 快速导航 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/FAQ.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/FAQ.md index 2c83c38a..9e29354e 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/FAQ.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/FAQ.md @@ -163,43 +163,6 @@ echo "your_private_key" | grep -E '^[0-9a-fA-F]{64}$' - 使用强密码（最少 8 字符） - 避免特殊字符，使用字母数字组合 -### TronGrid API Key 不生效 - -**症状：** API 调用返回错误或速率限制错误。 - -**解决步骤：** - -1. **检查环境变量名称** - ```bash - # 正确的名称 - export TRON_GRID_API_KEY="your_api_key" - - # 错误的名称（常见错误） - export TRONGRID_API_KEY="..." # ❌ 不要这样做 - ``` - -2. **验证 API Key 有效性** - - 登录 [TronGrid 控制面板](https://dashboard.trongrid.io) - - 确认 API Key 未过期或被禁用 - - 检查请求限额是否足够 - -3. **验证环境变量已设置** - ```bash - echo $TRON_GRID_API_KEY - ``` - -4. **重启服务器** - ```bash - # 设置后重启 - npx -y @bankofai/sun-mcp-server - ``` - -5. **检查网络连接** - ```bash - curl -H "TRONGRID-API-KEY: $TRON_GRID_API_KEY" \ - https://api.trongrid.io/v1/now - # 应返回块信息 - ``` ### "Conflicting wallet modes" @@ -387,7 +350,7 @@ sun-mcp-server 1. **在提示中提供准确的地址** ``` - 请使用 USDT（T9yD14Nj9j7xAB4dbGknA47WWJcZ541TZJ） + 请使用 USDT（TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t） ``` 2. **使用官方代币列表** @@ -428,22 +391,15 @@ sun-mcp-server **优化步骤：** -1. **配置 TronGrid API Key** - ```bash - export TRON_GRID_API_KEY="your_api_key" - ``` - - 无 API Key 使用公开节点，速度较慢 - - 有 API Key 访问专用节点 - -2. **简化工作流** +1. **简化工作流** - 减少多工具协调的步骤数 - 避免大量连续查询 -3. **使用本地服务器** +2. **使用本地服务器** - 参考 [本地私有化部署](LocalPrivatizedDeployment.md) - 可能比官方服务器更快（取决于网络） -4. **批量操作** +3. **批量操作** ``` 合并相关查询以减少往返次数 ``` @@ -574,6 +530,6 @@ npm update @modelcontextprotocol/sdk ## 获取更多帮助 - **GitHub Issues：** https://github.com/BofAI/sun-mcp-server/issues -- **完整文档：** 查阅 [工具列表](ToolList.md) +- **完整能力清单：** 查阅 [完整能力清单](ToolList.md) - **本地部署：** 参考 [本地私有化部署](LocalPrivatizedDeployment.md) -- **官方服务器：** 参考 [官方服务器访问](OfficialServerAccess.md) +- **官方服务器：** 参考 [官方云服务接入](OfficialServerAccess.md) diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/Intro.md index cfcb528f..2c60b56b 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/Intro.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/Intro.md @@ -17,7 +17,7 @@ SUN MCP Server 是连接 AI 助手与 TRON 链上最大去中心化交易所 [SU ## 它能做什么？ -SUN MCP Server 覆盖了与 SunSwap DEX 交互的完整操作，从链上数据查询到代币兑换和流动性管理，共提供 **41 个工具**（18 个自定义工具 + 23 个 SUN.IO OpenAPI 工具）。 +SUN MCP Server 覆盖了与 SunSwap DEX 交互的完整操作，从链上数据查询到代币兑换和流动性管理，共提供 **41 个工具**。 以下是核心能力概览——每一项都可以通过自然语言触发： diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md index bb1970e5..74b51e8a 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/LocalPrivatizedDeployment.md @@ -120,36 +120,9 @@ export TRON_ACCOUNT_INDEX="0" 与私钥方式的安全风险相同。明文存储的助记词容易泄露，请只用于存放少量资金的开发/测试钱包。 ::: - --- -### 第二步：配置网络（可选） - -#### TronGrid API Key - -TronGrid 是官方的 TRON RPC 提供商。使用 API Key 可以提高请求速率限制。 - -**获取 API Key：** - -1. 访问 [TronGrid 官方网站](https://www.trongrid.io) -2. 注册账户或登录 -3. 在控制台生成 API Key -4. 复制 API Key 到环境变量 - -**环境变量：** - -```bash -TRON_GRID_API_KEY=your_api_key_here -``` - -:::info -如果不设置 `TRON_GRID_API_KEY`，SUN MCP Server 将使用公共端点，但可能受到速率限制。 -::: - - ---- - -### 第三步：安装服务器 +### 第二步：本地私有化部署 #### 方式 A：npx 直接运行（推荐） @@ -169,7 +142,7 @@ npx -y @bankofai/sun-mcp-server **带环境变量运行：** ```bash -TRON_NETWORK=nile TRON_GRID_API_KEY=your_api_key npx -y @bankofai/sun-mcp-server +TRON_NETWORK=nile npx -y @bankofai/sun-mcp-server ``` #### 方式 B：从源码克隆 @@ -202,7 +175,7 @@ sun-mcp-server --- -### 第四步：连接 AI 客户端 +### 第三步：客户端配置 配置完成后，需要在 AI 客户端中添加 SUN MCP Server 的连接定义。 @@ -236,7 +209,6 @@ sun-mcp-server "env": { "AGENT_WALLET_PASSWORD": "your_secure_password", "AGENT_WALLET_DIR": "~/.agent-wallet", - "TRON_GRID_API_KEY": "your_api_key", "TRON_NETWORK": "nile" } } @@ -244,11 +216,14 @@ sun-mcp-server } ``` -**Claude Code (CLI) 配置：** +**Claude Code** ```bash -export MCP_SERVERS='{"sun":{"command":"npx","args":["-y","@bankofai/sun-mcp-server"],"env":{"TRON_NETWORK":"nile","TRON_GRID_API_KEY":"your_api_key"}}}' -claude code +# 基础配置 +claude mcp add sun-mcp-server -- npx -y @bankofai/sun-mcp-server + +# 携带环境变量 +claude mcp add -e AGENT_WALLET_PASSWORD=xxx sun-mcp-server -- npx -y @bankofai/sun-mcp-server ``` **Cursor 配置：** @@ -262,8 +237,7 @@ claude code "command": "npx", "args": ["-y", "@bankofai/sun-mcp-server"], "env": { - "TRON_NETWORK": "nile", - "TRON_GRID_API_KEY": "your_api_key" + "TRON_NETWORK": "nile" } } } @@ -288,7 +262,6 @@ claude code "args": ["tsx", "/path/to/sun-mcp-server/src/index.ts"], "env": { "AGENT_WALLET_PASSWORD": "your_secure_password", - "TRON_GRID_API_KEY": "your_api_key", "TRON_NETWORK": "nile" } } @@ -307,8 +280,7 @@ claude code "command": "npx", "args": ["tsx", "/path/to/sun-mcp-server/src/index.ts"], "env": { - "TRON_NETWORK": "nile", - "TRON_GRID_API_KEY": "your_api_key" + "TRON_NETWORK": "nile" } } } @@ -364,7 +336,6 @@ HTTP 模式适用于本地开发和测试。对于远程部署，请使用 HTTPS ```bash export TRON_NETWORK=nile -export TRON_GRID_API_KEY=your_api_key sun-mcp-server --transport streamable-http --host 127.0.0.1 --port 8080 --mcpPath /mcp ``` @@ -373,7 +344,7 @@ sun-mcp-server --transport streamable-http --host 127.0.0.1 --port 8080 --mcpPat --- -### 第五步：验证接入是否成功 +### 第四步：验证接入是否成功 启动 AI 客户端后，应该能看到 SUN MCP Server 的工具列表。进行以下测试以确认配置正确： @@ -382,7 +353,7 @@ sun-mcp-server --transport streamable-http --host 127.0.0.1 --port 8080 --mcpPat 在聊天中尝试以下命令： ``` -查询 TRON 主网的区块高度 +查一下 SunSwap 上 USDT 和 TRX 的当前价格 ``` 期望返回当前区块号。 @@ -405,9 +376,8 @@ TRON_NETWORK=nile 如果遇到连接问题： 1. **检查网络连接**：确保能访问 TRON 网络端点 -2. **验证 API Key**：如果配置了 `TRON_GRID_API_KEY`，确保其有效 -3. **查看日志**：运行服务器时查看控制台输出，寻找错误信息 -4. **测试网络**：尝试切换到测试网（Nile）排除网络问题 +2. **查看日志**：运行服务器时查看控制台输出，寻找错误信息 +3. **测试网络**：尝试切换到测试网（Nile）排除网络问题 ::: --- diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md index 5c3a676d..17dd6efe 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/OfficialServerAccess.md @@ -45,15 +45,6 @@ import TabItem from '@theme/TabItem'; > 注意：这是一个 MCP 协议端点，不是网页地址。在浏览器中直接打开不会显示任何内容。 -官方云服务支持**两种使用模式**： - -| 模式 | 限速 |说明 | -| :--- | :--- | :--- | -| **无 API Key（默认）** |100,000 Requests / Day |即开即用，适合入门体验和低频查询 | -| **带 TronGrid API Key** |500,000 Requests / Day |更高的请求频率上限，适合频繁查询和生产级使用 | - -如果你的使用场景涉及频繁查询主网数据，建议在 [trongrid.io](https://www.trongrid.io/) 注册一个免费的 TronGrid API Key，配置到请求头中以获得更高的吞吐量和稳定性。 - --- ## 客户端配置 @@ -65,7 +56,7 @@ import TabItem from '@theme/TabItem'; - **macOS**：`~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**：`%APPDATA%\Claude\claude_desktop_config.json` -**基础配置（不含 API Key）**： +**基础配置**： ```json { @@ -81,26 +72,6 @@ import TabItem from '@theme/TabItem'; } ``` -**含 TronGrid API Key 的配置**： - -```json -{ - "mcpServers": { - "sun-mcp-server": { - "command": "npx", - "args": [ - "mcp-remote", - "https://sun-mcp-server.bankofai.io/mcp", - "--header", - "TRONGRID-API-KEY:" - ] - } - } -} -``` - -将 `` 替换为你的实际 TronGrid API Key。 - diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/ToolList.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/ToolList.md index be658d11..d37f9254 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/ToolList.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/SUNMCPServer/ToolList.md @@ -1,12 +1,18 @@ # 完整能力清单 -SUN MCP Server 提供 **41 个工具**（18 个自定义 DeFi 工具 + 23 个 SUN.IO OpenAPI 衍生工具）。 +SUN MCP Server 提供 **41 个工具**。 ## 先了解两个概念 +在浏览工具列表之前，有两件事需要知道： + :::info 读取 vs 写入 -- **读取工具**：只查询数据，不影响链上状态。在云服务和本地部署中均可使用。 -- **写入工具**：会修改链上状态（兑换、流动性操作等）。仅在本地部署且配置了钱包后才可使用。 +每个工具都标记了**模式**——"读取"或"写入"： + +- **读取工具**：只查询链上数据，不影响任何状态。在云服务和本地部署中均可使用。 +- **写入工具**：会修改区块链状态（转账、质押、合约调用等）。仅在本地部署且配置了钱包后才可使用。 + +如果你没有配置钱包，写入工具不会出现在 AI 的可用工具列表中——它们会被自动隐藏，不用担心误触。 ::: :::tip network 参数 @@ -340,15 +346,5 @@ SUN MCP Server 的多个工具内置了智能自动计算功能，旨在简化 虽然大多数参数已自动计算，但在关键操作（如添加大额流动性）时，建议主动指定参数以获得更高的控制精度。 ::: ---- - -## 快速参考 - -**需要查询数据？** 使用读取工具：`get_*`, `search_*`, `scan*` 系列。 - -**需要执行交易？** 使用写入工具：`swap`, `mint`, `add`, `remove`, `collect`, `send_contract` 系列。 - -**不确定参数？** 工具会自动计算合理的默认值，或在必要时提示您补充信息。 -**想了解更多？** 查看 [SUN MCP Server 主文档](../README.md) 或 [API 参考](../API-Reference.md)。 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md index 390e12c5..62c96127 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/LocalPrivatizedDeployment.md @@ -134,15 +134,24 @@ export TRON_ACCOUNT_INDEX="0" #### TronGrid API Key -TRON 主网公共 RPC 有严格的频率限制。如果你的使用场景涉及频繁的链上查询，强烈建议配置一个免费的 TronGrid API Key： +TronGrid 是官方的 TRON RPC 提供商。使用 API Key 可以提高请求速率限制。 + +**获取 API Key：** + +1. 访问 [TronGrid 官方网站](https://www.trongrid.io) +2. 注册账户或登录 +3. 在控制台生成 API Key +4. 复制 API Key 到环境变量 + +**环境变量：** ```bash -# 添加到 ~/.zshrc 或 ~/.bashrc -export TRONGRID_API_KEY="<你的 TronGrid API Key>" +TRON_GRID_API_KEY=your_api_key_here ``` -在 [trongrid.io](https://www.trongrid.io/) 注册即可免费获取。不配置时服务器仍然可以运行，但高频操作下可能出现限速错误。测试网（Nile、Shasta）受频率限制的影响较小。 - +:::info +如果不设置 `TRON_GRID_API_KEY`，TRON MCP Server 将使用公共端点，但可能受到速率限制。 +::: --- diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md index 5a98f93e..c964fdd5 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/MCP/TRONMCPServer/OfficialServerAccess.md @@ -61,14 +61,14 @@ import TabItem from '@theme/TabItem'; | 模式 | 限速 | 说明 | | :--- |--- |:--- | -| **无 API Key（默认）** | 100,000 Requests / Day |即开即用，适合入门体验和低频查询 | +| **无 TronGrid API Key（默认）** | 100,000 Requests / Day |即开即用，适合入门体验和低频查询 | | **带 TronGrid API Key** | 500,000 Requests / Day |更高的请求频率上限，适合频繁查询和生产级使用 | 两种模式的接入方式完全相同，区别仅在于请求频率限制。 --- -### 无 API Key 模式（默认） +### 无 TronGrid API Key 模式（默认） 不配置任何 API Key 即可直接使用。适用于： diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md index 3695db57..899c1caa 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md @@ -180,9 +180,6 @@ BTC-USDT 永续合约的当前价格、24h 涨跌幅和资金费率是多少？ ``` # ⚠️ 调用付费端点 使用 x402 协议调用这个付费智能体端点：https://api.example.com - -# 🟢 查询 Gasfree 状态 -帮我查看当前 Gasfree 钱包的状态和可用余额。 ``` ### recharge-skill diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/FAQ.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/FAQ.md index 29b344d2..0eb63d56 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/FAQ.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/FAQ.md @@ -127,15 +127,6 @@ npx -y @bnb-chain/mcp@latest --help 2. **Key 是否仍然有效**：登录 [trongrid.io](https://www.trongrid.io/) 确认状态 3. **是否正确加载**：如果在环境变量中设置，确认已运行 `source ~/.zshrc` -### Gasfree 凭证不起作用 - -检查 `~/.x402-config.json` 的格式和内容： - -```bash -cat ~/.x402-config.json -``` - -确认包含有效的 `gasfree_api_key` 和 `gasfree_api_secret`。如果需要重新配置，可以直接编辑文件或重新运行安装程序。 ### BANK OF AI API Key 无效 diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/Intro.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/Intro.md index 3a94dd35..cec7b4e9 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/Intro.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/Intro.md @@ -42,7 +42,7 @@ Skills 是封装好的业务流程模板。与 MCP Server 提供的单个工具 | **sunswap** | SunSwap DEX 交易——余额查询、报价、兑换、V2/V3 流动性管理 | | **sunperp-skill** | SunPerp 永续合约交易——行情、下单、仓位管理、杠杆设置、提现 | | **tronscan-skill** | 通过 TronScan API 查询链上数据（账户、交易、代币、区块、全网统计） | -| **x402-payment** | x402 支付技能，调用付费智能体和付费 API，支持 Gasfree 免 Gas 交易 | +| **x402-payment** | x402 支付技能，调用付费智能体和付费 API | | **recharge-skill** | BANK OF AI 余额和订单查询，以及通过 MCP 充值 | diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/QuickStart.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/QuickStart.md index 8a372b59..8a63a4fa 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/QuickStart.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/Openclaw-extension/QuickStart.md @@ -95,7 +95,6 @@ Select skills to install (e.g., 1,2,3 or 'all'): - **recharge-skill** — 需要 BANK OF AI API Key（`BANKOFAI_API_KEY`） - **sunperp-skill** — 需要 SunPerp API 密钥（`SUNPERP_ACCESS_KEY` + `SUNPERP_SECRET_KEY`） -- **x402-payment** — 可选配置 Gasfree API 凭证（用于免 Gas 交易） - **tronscan-skill** — 提示你在 shell 中设置 `TRONSCAN_API_KEY` 环境变量 - **sunswap** — 提示配置 TRON 私钥（如果前面没有配置） From d7083922aaa5c2191102be123121be55901235dd Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Wed, 18 Mar 2026 01:37:24 +0800 Subject: [PATCH 4/5] fix --- docs/McpServer-Skills/SKILLS/BANKOFAISkill.md | 2 +- .../current/McpServer-Skills/SKILLS/BANKOFAISkill.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md b/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md index 56cb8e2b..af00d6c3 100644 --- a/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md +++ b/docs/McpServer-Skills/SKILLS/BANKOFAISkill.md @@ -1,6 +1,6 @@ # BANK OF AI Skills -BANK OF AI Skills is a ready-to-use skill pack designed for AI agents, covering core DeFi scenarios in the TRON/BNB ecosystem — DEX trading, perpetual contracts, on-chain data queries, and payment protocols. Each skill encapsulates a complete business workflow: from how to call APIs and what order to execute steps, to handling approvals and protecting user assets, all embedded in `SKILL.md` and accompanying scripts. +BANK OF AI Skills is a collection of ready-to-use skill packages designed for AI Agents, covering a wide range of scenarios within the TRON ecosystem—such as DEX trading, perpetual contracts, on-chain data queries, and payment protocols. Each skill encapsulates a complete business workflow, including how to call APIs, the order of execution steps, how to handle authorization, and how to safeguard user assets, all defined within `SKILL.md` and supporting scripts. You don't need to write code — just tell the AI in natural language what you want to do, and it will automatically find and execute the corresponding skill. diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md index 899c1caa..96dd9d33 100644 --- a/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md +++ b/i18n/zh-Hans/docusaurus-plugin-content-docs/current/McpServer-Skills/SKILLS/BANKOFAISkill.md @@ -1,6 +1,6 @@ # BANK OF AI Skills -BANK OF AI Skills 是一组为 AI 智能体设计的现成技能包，覆盖 TRON 生态的核心 DeFi 场景——DEX 交易、永续合约、链上数据查询、支付协议。每个技能封装了完整的业务工作流：从如何调用 API、按什么顺序执行步骤，到如何处理授权、怎样保护用户资产，全部内置在 `SKILL.md` 和配套脚本中。 +BANK OF AI Skills 是一组为 AI 智能体设计的现成技能包，覆盖 TRON 生态的各种场景——DEX 交易、永续合约、链上数据查询、支付协议。每个技能封装了完整的业务工作流：从如何调用 API、按什么顺序执行步骤，到如何处理授权、怎样保护用户资产，全部内置在 `SKILL.md` 和配套脚本中。 你无需编写代码，只需用自然语言告诉 AI 你想做什么，AI 会自动找到对应的技能并执行。 From a5be4d25c3691c4fa40680bf70ddb3e664fd1431 Mon Sep 17 00:00:00 2001 From: jerryji-prog Date: Wed, 18 Mar 2026 01:47:30 +0800 Subject: [PATCH 5/5] fix --- .github/workflows/docker.yml | 78 ------------------------------------ 1 file changed, 78 deletions(-) delete mode 100644 .github/workflows/docker.yml diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml deleted file mode 100644 index 9ece33f5..00000000 --- a/.github/workflows/docker.yml +++ /dev/null @@ -1,78 +0,0 @@ -name: Build and Push Docker Image - -on: - push: - branches: - - main - - master - tags: - - 'v*.*.*' - pull_request: - branches: - - main - - master - workflow_dispatch: - -env: - REGISTRY: ghcr.io - IMAGE_NAME: ${{ github.repository }} - -jobs: - build-and-push: - name: Build and Push Docker Image - runs-on: ubuntu-latest - permissions: - contents: read - packages: write - - steps: - - name: Checkout repository - uses: actions/checkout@v4 - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v3 - - - name: Log in to GitHub Container Registry - if: github.event_name != 'pull_request' - uses: docker/login-action@v3 - with: - registry: ${{ env.REGISTRY }} - username: ${{ github.actor }} - password: ${{ secrets.GITHUB_TOKEN }} - - - name: Extract Docker metadata - id: meta - uses: docker/metadata-action@v5 - with: - images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }} - tags: | - type=ref,event=branch - type=ref,event=pr - type=semver,pattern={{version}} - type=semver,pattern={{major}}.{{minor}} - type=sha,prefix=sha- - type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master' }} - - - name: Determine APP_ENV - id: app_env - run: | - if [[ "${{ github.ref }}" == "refs/heads/main" || "${{ github.ref }}" == "refs/heads/master" ]]; then - echo "APP_ENV=production" >> $GITHUB_OUTPUT - elif [[ "${{ github.ref }}" == refs/tags/* ]]; then - echo "APP_ENV=production" >> $GITHUB_OUTPUT - else - echo "APP_ENV=development" >> $GITHUB_OUTPUT - fi - - - name: Build and push Docker image - uses: docker/build-push-action@v6 - with: - context: . - push: ${{ github.event_name != 'pull_request' }} - tags: ${{ steps.meta.outputs.tags }} - labels: ${{ steps.meta.outputs.labels }} - build-args: | - APP_ENV=${{ steps.app_env.outputs.APP_ENV }} - cache-from: type=gha - cache-to: type=gha,mode=max - platforms: linux/amd64,linux/arm64