@claudium/solana-mcp-server/CLAUDE.md

MCP server for Solana blockchain interaction via Solscan Pro API

# CLAUDE.md - Solana MCP Server Development Guide

## 🎯 Project Overview
Building a modular MCP server for Solana blockchain interaction using Solscan Pro API v2.0.

**API Documentation**: https://pro-api.solscan.io/pro-api-docs/v2.0/reference/

**API Key**: Store your Solscan Pro API key in .env as SOLANA_API_KEY
Get your key at: https://pro-api.solscan.io/

## 📊 Solscan Pro API Categories

1. **Account APIs** - Wallet/account operations
2. **Token APIs** - Token data and analytics
3. **NFT APIs** - NFT collections and activities
4. **Transaction APIs** - Transaction details and history
5. **Block APIs** - Block information
6. **Market APIs** - Market data and liquidity pools
7. **Program APIs** - Program and platform data
8. **Monitoring APIs** - API usage monitoring
9. **Chain Information** - Blockchain statistics

## 🏗️ Approved Project Structure

```
solana-mcp-server/
├── providers/
│   ├── solscan/
│   │   ├── base.py          # Solscan base client with API key
│   │   ├── endpoints.py     # All endpoint URLs
│   │   └── client.py        # Main Solscan client
│   └── ...existing providers (dexscreener, jupiter)
│
└── tools/
    ├── account/              # 👛 WALLET/ACCOUNT OPERATIONS
    │   ├── account_info.py       # Get account details and SOL balance
    │   ├── account_tokens.py     # List all tokens in wallet
    │   ├── account_portfolio.py  # Complete portfolio value & breakdown
    │   ├── account_transactions.py # Transaction history
    │   ├── account_defi.py       # DeFi activities & positions
    │   ├── account_staking.py    # Staking info & rewards
    │   └── account_transfers.py  # Transfer history & exports
    │
    ├── token/                # 🪙 TOKEN OPERATIONS
    │   ├── token_info.py         # Token metadata, supply, price
    │   ├── token_holders.py      # Top holders list
    │   ├── token_markets.py      # Trading pairs & liquidity
    │   ├── token_price.py        # Current & historical prices
    │   ├── token_trending.py     # Trending tokens
    │   ├── token_latest.py       # New token launches
    │   └── token_transfers.py    # Token transfer activity
    │
    ├── market/               # 📈 MARKET DATA
    │   ├── market_overview.py    # Overall market stats
    │   ├── market_volume.py      # Volume leaders & stats
    │   ├── liquidity_pools.py    # Pool information
    │   └── top_gainers.py        # Top gainers/losers
    │
    ├── transaction/          # 📝 TRANSACTION TOOLS
    │   ├── tx_details.py         # Transaction details & decoding
    │   ├── tx_latest.py          # Latest transactions
    │   └── tx_simulate.py        # Simulate transactions
    │
    ├── nft/                  # 🎨 NFT TOOLS
    │   ├── nft_collections.py    # Collection info
    │   ├── nft_activities.py     # NFT trading activity
    │   └── nft_new.py            # New NFT launches
    │
    ├── defi/                 # 💰 DEFI ANALYTICS
    │   ├── defi_positions.py     # User DeFi positions
    │   ├── defi_yields.py        # Yield farming opportunities
    │   └── defi_activities.py    # DeFi transaction history
    │
    └── analytics/            # 📊 ADVANCED ANALYTICS
        ├── whale_tracker.py       # Whale movements
        ├── leaderboard.py        # Top traders/accounts
        └── chain_stats.py        # Blockchain statistics
```

## 📝 Implementation Priority Order

### Phase 1 - Core Tools (COMPLETED ✅)
1. ✅ Basic structure created (token_info, trending, calculator)
2. ✅ `token_info` - Upgraded to Solscan API with comprehensive data
3. ✅ `account_tokens` - List all tokens in wallet with balances
4. ✅ `account_portfolio` - Complete portfolio analysis
5. ✅ `token_trending` - Find trending tokens with Solscan
6. ✅ `token_price` - Get token prices (supports single/batch queries)

### Phase 2 - Trading Tools
7. ⏳ `token_holders` - See top holders
8. ⏳ `market_volume` - Volume leaders
9. ⏳ `account_transactions` - Transaction history
10. ⏳ `token_transfers` - Token movement tracking
11. ⏳ `liquidity_pools` - Pool information

### Phase 3 - Advanced Features
12. ⏳ `defi_positions` - DeFi tracking
13. ⏳ `whale_tracker` - Whale movements
14. ⏳ `nft_collections` - NFT data
15. ⏳ `account_staking` - Staking rewards

## 💬 Tool Description Standards

Each tool MUST have:
1. **Clear natural language description** for the MCP tool decorator
2. **Detailed parameter descriptions** with examples
3. **User-friendly error messages**
4. **Formatted response** for easy reading

Example:
```python
@mcp.tool()
async def get_token_info(token_address: str) -> Dict[str, Any]:
    """
    Get complete information about any Solana token including price, market cap, 
    holders count, and liquidity. Works with token addresses like 
    'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v' for USDC.
    
    Args:
        token_address: Solana token mint address (e.g., USDC: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v)
    
    Returns:
        Token name, symbol, price, market cap, holders, liquidity, 24h change
    """
```

## 🔧 Technical Requirements

### Caching Strategy
- Token prices: 30 seconds
- Account data: 60 seconds  
- Trending/Latest: 5 minutes
- NFT/Historical: 10 minutes

### Error Handling
- User-friendly messages (no technical jargon)
- Fallback to cached data when API fails
- Suggest alternatives when data unavailable

### Response Format
- Clean, readable JSON
- Include source attribution
- Add helpful context (% changes, rankings)

## 🚀 Current Status

**Server Configuration**:
- ✅ MCP server created and connected to Claude Code
- ✅ Project-level configuration in `.mcp.json`
- ✅ Environment variables configured in `.env`
- ✅ Solscan Pro API v2.0 integrated with authentication

**Completed Phase 1 Tools** (January 29, 2025):
- ✅ **Token Tools**:
  - `get_solana_token_info` - Complete token data with price, market cap, holders
  - `get_token_prices` - Single and batch price queries (up to 100 tokens)
  - `get_solana_trending_tokens` - Trending tokens with sorting options
- ✅ **Account Tools**:
  - `get_wallet_tokens` - All tokens in wallet with balances and values
  - `get_wallet_portfolio` - Complete portfolio analysis with DeFi and activity
- ✅ **Legacy Tools** (backward compatibility):
  - Calculator, search, and original token info still available

**Next Steps**:
1. Implement Phase 2 trading tools (holders, volume, transactions)
2. Add market data and liquidity pool tools
3. Implement DeFi and NFT analytics
4. Add comprehensive caching and error handling

## 📌 Important Notes

- **API Key**: Stored in `.env` as `SOLANA_API_KEY`
- **Base URL**: `https://pro-api.solscan.io/v2.0/`
- **Rate Limits**: Check API documentation for limits
- **Testing**: Use USDC (EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v) for testing

## 🛠️ Development Commands

```bash
# Run server
python solana-mcp-server/server.py

# Test basic functionality
python solana-mcp-server/test_basic.py

# Check MCP connection
claude mcp list

# View logs
tail -f ~/.claude/logs/mcp.log
```

---
**Last Updated**: Initial setup with basic tools complete, ready for Solscan integration