# VeChain AI Terminal ~ MCP Server

![VeChain AI Terminal Banner](src/docs/images/vechain-terminal-banner.png)

A Model Context Protocol (MCP) server that enables Claude Desktop to interact with the VeChain blockchain through natural language commands. The server provides comprehensive blockchain operations including token transfers, DEX trading, cross-chain bridges, NFT management, and VeBetter DAO interactions.

## Overview

VeChain AI Terminal bridges the gap between AI assistants and blockchain functionality by providing a natural language interface to VeChain's ecosystem. Users can perform complex blockchain operations through simple conversational commands with Claude Desktop.

## Architecture

![VeChain AI Architecture Banner](src/docs/images/vechain-terminal-arc.png)

```mermaid
graph TB
    subgraph "Claude Desktop"
        A[User Interface]
        B[Claude AI]
    end
    
    subgraph "MCP Server"
        C[Tool Registry]
        D[Plugin System]
        E[Core Framework]
    end
    
    subgraph "VeChain Plugins"
        F[Token Operations]
        G[DEX Trading]
        H[Cross-Chain Bridges]
        I[NFT Management]
        J[VeBetter DAO]
        K[StarGate Staking]
        L[Analytics]
    end
    
    subgraph "VeChain Network"
        M[VeChain Mainnet]
        N[VeChain Testnet]
        O[Smart Contracts]
    end
    
    subgraph "External APIs"
        P[VeChainStats API]
        Q[WanBridge API]
        R[XFlows API]
        S[B32 Repository]
    end
    
    A --> B
    B <--> C
    C --> D
    D --> E
    E --> F
    E --> G
    E --> H
    E --> I
    E --> J
    E --> K
    E --> L
    
    F --> M
    F --> N
    G --> O
    H --> Q
    H --> R
    I --> O
    J --> O
    K --> O
    L --> P
    L --> S
```


![VeChain AI Tools Banner](src/docs/images/vechain-terminal-tools.png)

## System Components

### Core Framework
- **Tool Decorator System**: Marks functions as AI-accessible tools with parameter validation
- **Plugin Base**: Abstract foundation for all blockchain operation plugins
- **Wallet Client**: Manages VeChain wallet connections and transaction signing
- **Registry Services**: Maintains contract addresses, token definitions, and ABI mappings

### Plugin Architecture

![VeChain AI Architecture Banner](src/docs/images/vechain-terminal-plugin.png)


```mermaid
graph LR
    subgraph "Plugin Structure"
        A[Plugin Class] --> B[Service Layer]
        B --> C[Tool Methods]
        C --> D[Parameter Validation]
        D --> E[Blockchain Execution]
    end
    
    subgraph "Available Plugins"
        F[Token Plugin<br/>VET/VTHO/B3TR transfers]
        G[DEX Plugin<br/>VeSwap, BetterSwap trading]
        H[Bridge Plugin<br/>WanBridge, XFlows]
        I[NFT Plugin<br/>VIP-181 operations]
        J[VeBetter Plugin<br/>Sustainable rewards]
        K[StarGate Plugin<br/>NFT staking & delegation]
        L[Stats Plugin<br/>Blockchain analytics]
    end
```

## Features

### Blockchain Operations
- **Token Transfers**: Native VET and VIP-180 token operations
- **Balance Queries**: Real-time account balance monitoring
- **Transaction History**: Comprehensive transaction tracking
- **Gas Estimation**: Automatic fee calculation and optimization

### DEX Integration
- **Multi-DEX Support**: VeSwap, BetterSwap, Vexchange integration
- **Price Discovery**: Real-time token price feeds and comparison
- **Liquidity Analysis**: Pool information and trading volume metrics
- **Swap Execution**: Automated token exchange with slippage protection

### Cross-Chain Operations
- **WanBridge Integration**: Secure asset transfers between networks
- **XFlows Support**: Advanced cross-chain swap protocols
- **Bridge Monitoring**: Real-time transfer status tracking
- **Multi-Network Support**: Ethereum, Polygon, BSC connectivity

### NFT Management
- **VIP-181 Operations**: Complete NFT lifecycle management
- **Metadata Handling**: IPFS integration for rich media content
- **Collection Analytics**: Comprehensive NFT project statistics
- **Transfer Operations**: Secure ownership transfers

### VeBetter DAO
- **Sustainable Actions**: Submit and validate eco-friendly activities
- **B3TR Rewards**: Automated token distribution for verified actions
- **Governance Participation**: Proposal voting and delegation
- **Impact Tracking**: Environmental contribution monitoring

### StarGate Staking
- **NFT-Based Staking**: Stake VET to mint tier-specific StarGate NFTs
- **Multi-Tier System**: Support for all 10 StarGate tiers (Dawn to Mjolnir X)
- **Delegation Rewards**: Start/stop delegation for enhanced VTHO rewards  
- **Legacy Migration**: Seamless migration from old VeChain nodes
- **Real-time Analytics**: Track staking performance and reward accumulation
- **Complete Operations**: 13 fully functional MCP tools for all StarGate operations

## Quick Start

### Prerequisites

- Claude Desktop application
- Node.js 18 or higher
- pnpm package manager
- VeChain wallet (private key or mnemonic)

### Installation

1. **Clone and build the server**
   ```bash
   git clone https://github.com/VeChain-AI-Terminal/vechain-mcp-server
   cd vechain-mcp-server
   pnpm install
   pnpm build
   ```

2. **Configure environment variables**
   ```bash
   cp .env.example .env
   ```
   Edit `.env` file with your wallet credentials and network preferences.

3. **Automated Setup (Recommended)**
   
   Use the automated setup script to configure your preferred AI application:
   
   ```bash
   # Interactive mode - choose which application to configure
   pnpm setup
   
   # Configure Claude Desktop only
   pnpm setup:claude
   
   # Configure Cursor editor only
   pnpm setup:cursor
   
   # Configure VS Code only
   pnpm setup:code
   
   # Configure multiple applications
   ./setup-mcp.sh --claude --cursor --code
   ```
   
   The setup script will:
   - Read your `.env` configuration
   - Generate the appropriate MCP configuration
   - Install it in the correct location for your chosen application(s)
   - Provide restart instructions

4. **Manual Configuration (Alternative)**
   
   If you prefer manual setup, you can configure the applications directly:
   
   **Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json`
   **Cursor Editor**: `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project-specific)  
   **VS Code**: `~/Library/Application Support/Code/User/mcp.json` (global) or `.vscode/mcp.json` (project-specific)
   
   The configuration format should look like:
   ```json
   {
     "mcpServers": {
       "vechain-mcp": {
         "command": "node",
         "args": ["/absolute/path/to/vechain-mcp-server/dist/index.js"],
         "env": {
           "WALLET_MNEMONIC": "your twelve word mnemonic phrase here",
           "VECHAIN_NETWORK": "testnet",
           "VECHAINSTATS_API_KEY": "your_vechainstats_api_key",
           "VEBETTER_REWARDS_POOL_ADDRESS": "0x5F8f86B8D0Fa93cdaE20936d150175dF0205fB38",
           "VEBETTER_B3TR_TOKEN_ADDRESS": "0xbf64cf86894Ee0877C4e7d03936e35Ee8D8b864F",
           "VEBETTER_APPS_REGISTRY_ADDRESS": "0xcB23Eb1bBD5c07553795b9538b1061D0f4ABA153",
           "VEBETTER_APP_ID": "your_app_id_here",
           "BRIDGE_API_URL": "https://bridge-api.wanchain.org/api",
           "BRIDGE_PARTNER": "vechain-ai-superapp"
         }
       }
     }
   }
   ```

5. **Restart your AI application**

Close and reopen Claude Desktop, Cursor, or VS Code to load the MCP server.

### Environment Configuration

| Variable | Required | Description |
|----------|----------|-------------|
| `WALLET_PRIVATE_KEY` | Either | VeChain wallet private key |
| `WALLET_MNEMONIC` | Either | VeChain wallet mnemonic phrase |
| `VECHAIN_NETWORK` | Yes | Network selection: `mainnet` or `testnet` |
| `VECHAINSTATS_API_KEY` | No | Enhanced blockchain data access |
| `VEBETTER_ACTION_CONTRACT` | No | VeBetter action submission contract |
| `VEBETTER_REWARD_CONTRACT` | No | VeBetter reward distribution contract |

### Network Endpoints

- **Testnet**: `https://testnet.veblocks.net` (development use)
- **Mainnet**: `https://mainnet.veblocks.net` (production use)

## Usage Examples

### Token Operations
```
"Transfer 100 VET to 0x742d35Cc6651Fb66D8dD9b2a5D35bfa2F9d2E7c7"
"Check my VTHO balance"
"Send 50 B3TR tokens to alice.vet"
```

### DEX Trading
```
"Swap 100 VET for VTHO on VeSwap"
"Get the best price for 1000 B3TR to VET"
"What's the current VET/VTHO exchange rate?"
```

### Cross-Chain Operations
```
"Bridge 500 VET from VeChain to Ethereum using WanBridge"
"Check my bridge transaction status for hash 0x..."
"What are the current bridge fees for VET to Polygon?"
```

### NFT Operations
```
"Mint an NFT with metadata from ipfs://QmHash"
"Transfer my NFT #123 from collection 0x... to 0x..."
"Show me all NFTs in my wallet"
```

### VeBetter Rewards
```
"Submit a sustainable action: I used public transport for 20km today"
"Check my available B3TR rewards"
"Claim my pending VeBetter rewards"
```

### StarGate Staking Operations
```
"Stake 10,000 VET for a Dawn tier StarGate NFT"
"Show me all my StarGate NFTs and their details"
"Start delegating my StarGate NFT #123 for rewards"
"Claim my VTHO rewards from token 456"
"What are the current StarGate staking tiers and requirements?"
"Stop delegation for my Mjolnir X node"
"Get delegation status for my StarGate NFT #789"
"Check if my StarGate NFT can be transferred"
"Get maturity information for my StarGate NFT"
"Unstake my StarGate NFT to get my VET back"
```

## StarGate Operations Reference

The VeChain AI Terminal provides comprehensive StarGate staking functionality with 13 fully tested MCP tools:

### 🏦 Staking Functions

#### `stake_vet`
Stake VET to mint a StarGate NFT of specified level
- **Parameters:**
  - `levelId` (number, 1-10): StarGate tier level ID
  - `autoDelegate` (boolean, optional): Auto-delegate for additional rewards
- **Example:** "Stake 5 VET for Lightning level with auto-delegation"

#### `unstake_stargate_nft`
Unstake a StarGate NFT to burn it and retrieve the staked VET
- **Parameters:**
  - `tokenId` (string): StarGate NFT token ID to unstake
- **Example:** "Unstake my StarGate NFT #100165"

### 📊 Query Functions

#### `get_staking_levels`
Get all available StarGate staking levels with requirements and rewards
- **Parameters:**
  - `category` (optional): Filter by 'all', 'eco', 'x', or 'new-eco'
- **Returns:** All 10 levels (Dawn, Lightning, Flash, VeThorX, Strength, StrengthX, Thunder, ThunderX, Mjolnir, MjolnirX)

#### `get_user_stakes`
Get all StarGate NFTs owned by an address with detailed information
- **Parameters:**
  - `address` (string): User address to check stakes for
- **Returns:** Complete portfolio with NFT details

#### `get_stake_info`
Get detailed information about a specific StarGate NFT by token ID
- **Parameters:**
  - `tokenId` (string): StarGate NFT token ID to get info for
- **Returns:** Complete token details, maturity status, claimable VTHO

### 🔍 Utility Functions

#### `get_ids_owned_by`
Get all StarGate NFT token IDs owned by an address
- **Parameters:**
  - `address` (string): Address to get owned token IDs for

#### `get_level_supply`
Get circulating supply and cap for a specific StarGate level
- **Parameters:**
  - `levelId` (number): Level ID to get supply info for

#### `token_exists`
Check if a StarGate NFT token exists
- **Parameters:**
  - `tokenId` (string): Token ID to check existence

#### `can_transfer_stargate_nft`
Check if a StarGate NFT can be transferred (maturity period has ended)
- **Parameters:**
  - `tokenId` (string): Token ID to check transfer eligibility

#### `get_maturity_end_block`
Get the block number when the maturity period ends for a StarGate NFT
- **Parameters:**
  - `tokenId` (string): Token ID to get maturity end block for

#### `is_under_maturity_period`
Check if a StarGate NFT is still under maturity period
- **Parameters:**
  - `tokenId` (string): Token ID to check maturity status

#### `get_token_level`
Get the level ID of a StarGate NFT
- **Parameters:**
  - `tokenId` (string): Token ID to get level for

### 💰 VTHO Reward Functions

#### `claim_vtho_rewards`
Claim accumulated VTHO rewards for a StarGate NFT
- **Parameters:**
  - `tokenId` (string): StarGate NFT token ID to claim rewards for

### 🎯 StarGate Tier System

| Level | Name | VET Required | Maturity | Reward Factor | Type |
|-------|------|--------------|----------|---------------|------|
| 1 | Strength | 100 VET | 30 days | 1.5x | Standard |
| 2 | Thunder | 1,000 VET | 60 days | 2.0x | Standard |
| 3 | Mjolnir | 10,000 VET | 90 days | 2.5x | Standard |
| 4 | VeThorX | 100,000 VET | No maturity | 3.0x | X-Series |
| 5 | StrengthX | 500,000 VET | No maturity | 3.5x | X-Series |
| 6 | ThunderX | 1,000,000 VET | No maturity | 4.0x | X-Series |
| 7 | MjolnirX | 5,000,000 VET | No maturity | 4.5x | X-Series |
| 8 | Dawn | 1 VET | 7 days | 1.2x | Standard |
| 9 | Lightning | 5 VET | 14 days | 1.3x | Standard |
| 10 | Flash | 50 VET | 21 days | 1.4x | Standard |

### ✅ Testing Status
All 13 StarGate MCP functions have been successfully tested with real transactions on VeChain testnet, including:
- ✅ Staking operations (stake_vet, unstake_stargate_nft)
- ✅ Portfolio queries (get_user_stakes, get_stake_info)
- ✅ Utility functions (token_exists, can_transfer_stargate_nft)
- ✅ Maturity checks (is_under_maturity_period, get_maturity_end_block)
- ✅ VTHO rewards (claim_vtho_rewards)
- ✅ Level management (get_staking_levels, get_level_supply)

### Analytics and Data
```
"Show me the latest VeChain network statistics"
"What's the current VET price and market cap?"
"Get transaction history for the last 7 days"
```

## Development

### Plugin Development

Create new plugins by extending the base plugin class:

```typescript
import { PluginBase } from '../core/PluginBase';
import { Tool } from '../core/Tool.decorator';

export class CustomPlugin extends PluginBase {
  @Tool({
    description: "Custom blockchain operation",
    parameters: {
      address: { type: "string", description: "Target address" }
    }
  })
  async customOperation(address: string) {
    // Implementation
  }
}
```

### Adding New Tools

1. Create plugin file in `src/plugins/`
2. Implement service methods with `@Tool` decorators
3. Register plugin in `src/index.ts`
4. Build and test functionality

### Testing

```bash
# Development mode
pnpm dev

# Type checking
pnpm typecheck

# Production build
pnpm build

# Test MCP connection
pnpm test-mcp
```

## Security Considerations

### Wallet Security
- Store private keys securely using environment variables
- Never commit credentials to version control
- Use testnet for development and testing
- Verify all transaction details before execution

### API Security
- Protect API keys with appropriate access controls
- Use HTTPS for all external API communications
- Implement rate limiting for high-frequency operations
- Validate all input parameters and responses

### Network Security
- Use official RPC endpoints for blockchain connections
- Verify smart contract addresses before interaction
- Monitor transaction fees and gas usage
- Implement proper error handling and logging

## Integration APIs

### VeChain SDK
Core blockchain operations using official VeChain TypeScript SDK with support for transaction creation, signing, and broadcasting.

### VeChainStats API
Comprehensive blockchain analytics including network statistics, token information, and transaction history.

### WanBridge API
Cross-chain bridge operations for secure asset transfers between VeChain and other blockchain networks.

### XFlows API
Advanced cross-chain swap protocols enabling complex multi-hop transactions across different networks.

### B32 Repository
Dynamic ABI loading system for smart contract interactions without requiring manual ABI management.

## Troubleshooting

### Common Issues

**Tool not found errors**
- Restart Claude Desktop after configuration changes
- Verify absolute paths in configuration file
- Check environment variable settings

**Invalid address formats**
- Ensure VeChain addresses start with 0x
- Verify address checksums for accuracy
- Use proper ENS name resolution where supported

**Insufficient balance errors**
- Check VET balance for transaction fees
- Verify token balances before transfers
- Consider network congestion effects on gas prices

**Network connectivity issues**
- Verify RPC endpoint accessibility
- Check firewall and proxy settings
- Test alternative network endpoints

### Debug Mode

Enable detailed logging:
```bash
export DEBUG=true
pnpm dev
```

## Contributing

This project demonstrates AI-blockchain integration patterns and welcomes contributions. Please follow these guidelines:

1. Fork the repository and create feature branches
2. Follow TypeScript coding standards and conventions
3. Add comprehensive tests for new functionality
4. Update documentation for API changes
5. Submit pull requests with detailed descriptions

## License

MIT License - see LICENSE file for complete terms and conditions.

---

**VeChain AI Terminal** - Bridging artificial intelligence with blockchain technology through natural language interactions.