Skip to content

Allen-Saji/corvus

BranchesTags

Repository files navigation

Corvus

Solana DeFi Intelligence — Dual Interface (MCP Server + CLI)

Natural language interface for querying wallets, DeFi positions, protocol metrics, and token prices on Solana blockchain.

Two Deployment Modes:

  • 🤖 MCP Server: Integrate with Archestra/Claude Desktop for AI-powered analysis
  • ⚡ CLI Tool: Standalone terminal commands for direct queries

Table of Contents

Features

Wallet Intelligence

  • SOL Balance: Get native SOL balance with real-time USD valuation
  • Token Holdings: Complete SPL token portfolio with prices and values
  • Transaction History: Human-readable transaction descriptions (powered by Helius Enhanced Transactions)

DeFi Market Data

  • Token Pricing: Batch price lookups for up to 50 tokens (symbols or mint addresses)
  • Protocol TVL: Detailed Total Value Locked metrics for 358+ Solana protocols
  • Protocol Rankings: Top protocols by TVL with category filtering

Advanced Analytics (The Differentiator)

  • DeFi Position Analysis: Intelligent 3-bucket classification system
    • Known DeFi: Registry-based identification (jupSOL, mSOL, JLP, etc.)
    • Likely DeFi: Heuristic detection (LP tokens, vault tokens, protocol patterns)
    • Unclassified: Regular tokens and assets
  • Dust Filtering: Automatically filters tokens < $1 USD or < 0.01 balance
  • Telegram Alerts: Send formatted notifications with severity levels

Quick Start

Prerequisites

  • Node.js 18+
  • Helius API key (free tier: 100k credits/day)
  • Optional: Telegram Bot Token (for alerts)

Installation

# Clone repository
git clone https://github.com/Allen-Saji/corvus.git
cd corvus

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env and add your HELIUS_API_KEY

# Build
npm run build

# Run
npm start

Archestra Platform Deployment (Recommended)

  1. Navigate to MCP Registry in Archestra UI
  2. Click "Self-hosted (orchestrated by Archestra in K8s)"
  3. Fill in the form:
    • Name: Corvus
    • Command: node
    • Docker Image: corvus-mcp:latest
    • Arguments: dist/index.js
    • Environment Variables:
      • HELIUS_API_KEY: Your Helius API key
      • TELEGRAM_BOT_TOKEN: Your Telegram bot token (optional)
  4. Click "Add Server"
  5. Assign to an Agent and test via Chat UI

Docker Deployment

# Build Docker image
docker build -t corvus-mcp:latest .

# Run with environment variables
docker run -d \
  -e HELIUS_API_KEY=your-key \
  -e TELEGRAM_BOT_TOKEN=your-token \
  corvus-mcp:latest

Claude Desktop Integration

Note: This configuration follows standard MCP server patterns but has not been tested with Claude Desktop.

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "corvus": {
      "command": "node",
      "args": ["/path/to/corvus/dist/index.js"],
      "env": {
        "HELIUS_API_KEY": "your-helius-api-key",
        "TELEGRAM_BOT_TOKEN": "your-telegram-token"
      }
    }
  }
}

CLI Mode (Terminal)

Corvus can also run as a standalone command-line tool for direct wallet and DeFi analysis.

Global Installation

# Install globally
npm install -g .

# Or use npm link for development
npm link

CLI Commands

Direct Commands (No AI required):

# Get SOL balance
corvus balance <wallet>

# Get all token holdings
corvus tokens <wallet>

# Get token prices (comma-separated)
corvus price SOL,USDC,JitoSOL

# Get recent transactions
corvus tx <wallet> --limit 20

# Analyze DeFi positions
corvus analyze <wallet>

# Get protocol TVL
corvus protocol jito

# Get top protocols
corvus top --limit 10 --category "Liquid Staking"

# Send Telegram alert
corvus alert <chat_id> "Alert message" --severity warning

# Output raw JSON for any command
corvus balance <wallet> --json

Agentic Chat Mode (AI-powered):

# Start interactive AI chat (auto-detects available provider)
corvus chat

# Use specific provider
corvus chat --provider anthropic
corvus chat --provider openai
corvus chat --provider google

# Use local LLM (free, private)
corvus chat --local

# Example conversation:
You: What are my DeFi positions in wallet 7xKXtg...?
Corvus: [AI analyzes wallet and presents results]

You: Now show me the top 5 lending protocols
Corvus: [AI fetches and displays top lending protocols]

Examples

# Check your wallet balance
corvus balance 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU

# Analyze DeFi positions with pretty formatting
corvus analyze 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU

# Get current SOL and USDC prices
corvus price SOL,USDC

# View top 5 lending protocols
corvus top --limit 5 --category Lending

# Get last 25 transactions
corvus tx <wallet> --limit 25

# Pipe to other tools using --json flag
corvus balance <wallet> --json | jq '.balance_sol'

CLI Features:

  • 🎨 Colored terminal output for better readability
  • 📊 Formatted tables for structured data
  • 🔁 --json flag for raw JSON output (scripting-friendly)
  • ⚡ Direct access to all Corvus tools
  • 🛠️ Cross-platform (Linux, macOS, Windows)
  • 🤖 Agentic chat mode with multi-LLM support (5 providers)
  • 🎯 Custom model selection - use any model from any provider

Agentic Chat Mode

Corvus now supports natural language queries through an interactive AI chat interface. Ask questions in plain English and let the AI orchestrate tool calls automatically.

Supported LLM Providers

Provider Default Model Cost Range Custom Models
Anthropic Claude 3.5 Sonnet $3-75/1M tokens ✅ All Claude models supported
OpenAI GPT-4o $0.15-30/1M tokens ✅ All GPT models supported
Google Gemini 1.5 Flash $0.075-5/1M tokens ✅ All Gemini models supported
Groq Llama 3.3 70B $0.05-0.24/1M tokens ✅ All Groq models supported
Ollama (Local) Llama 3.2 FREE ✅ Any locally installed model

💡 Use corvus models to see all available models | Full Model Guide →

Setup

  1. Add API key to .env (choose at least one):

    ANTHROPIC_API_KEY=sk-ant-...  # Recommended
OPENAI_API_KEY=sk-...
GOOGLE_API_KEY=...
GROQ_API_KEY=gsk-...

  2. Or use local Ollama (no API key needed):

    # Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Pull a model
ollama pull llama2

# Use with Corvus
corvus chat --local

  3. 🆕 Custom Model Selection (choose any model from any provider):

    # View all available models
corvus models              # List all providers
corvus models anthropic    # Filter by provider

# Use custom model via CLI flag
corvus chat --provider openai --model gpt-4o-mini
corvus chat --provider anthropic --model claude-3-5-haiku-20241022
corvus chat --local --model mistral

# Or set default in config
corvus config set llm.model gpt-4o-mini
corvus chat  # Uses config default

    📖 See CUSTOM_MODELS.md for full model list and recommendations

Usage Examples

Basic Chat:

$ corvus chat

🤖 Corvus AI Chat
Provider: anthropic | Model: claude-3-5-sonnet-20241022

You: What's the SOL price?
Corvus: The current SOL price is $79.17 USD.

You: Analyze wallet 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU
Corvus: [Analyzes wallet and shows DeFi positions]

You: exit
📊 Session Summary:
  Turns: 2
  Estimated cost: $0.0023

Advanced Options:

# Use specific provider
corvus chat --provider openai

# Use specific model
corvus chat --provider anthropic --model claude-3-opus-20240229

# Use local LLM (private, free)
corvus chat --local

# Skip privacy warning
corvus chat --no-privacy-warning

Chat Commands

During a chat session:

  • exit or quit - End session and show summary
  • clear - Reset conversation history
  • Any natural language query - Ask questions about Solana/DeFi

Security & Privacy

  • ⚠️ Data Privacy: Queries (including wallet addresses) are sent to the selected LLM provider
  • 🔒 Private Mode: Use --local flag for Ollama to keep all data on your machine
  • 💰 Cost Limits: Sessions auto-terminate after 15 turns or $0.50 estimated cost
  • 🛡️ Input Validation: All tool parameters are validated before execution
  • 🚫 Safety: AI cannot execute destructive actions without confirmation

Available Tools

Tool Description Parameters
get_sol_balance Get SOL balance with USD value wallet (required)
get_token_balances Get all SPL token holdings wallet (required)
get_recent_transactions Get transaction history wallet (required), limit (default: 10, max: 50)
get_token_price Get token prices tokens (comma-separated, max: 50)
get_protocol_tvl Get protocol TVL metrics protocol (name or slug)
get_top_solana_protocols Get top protocols by TVL limit (default: 10, max: 50), category (optional)
analyze_wallet_defi_positions Analyze DeFi positions wallet (required)
send_telegram_alert Send Telegram notification chat_id, message, severity (info/warning/critical)

Architecture

Three-layer design with deterministic tool execution:

┌─────────────────────────────────┐
│   Tools (MCP Interface)         │  8 production-ready tools
│   src/tools/*.ts                │  Input validation, response formatting
└─────────────┬───────────────────┘
              │
┌─────────────▼───────────────────┐
│   Libraries (API Clients)       │  Helius, DeFiLlama clients
│   src/lib/*.ts                  │  Error handling, retries, sanitization
└─────────────┬───────────────────┘
              │
┌─────────────▼───────────────────┐
│   Data (Static Registries)      │  Known DeFi tokens, token symbols
│   src/data/*.ts                 │  Registry-based classification
└─────────────────────────────────┘

Design Principle: All data fetching, validation, formatting, and error handling happens inside the tools. The LLM only selects which tool to use.

Testing

Comprehensive test suite with 210 passing tests (~6 seconds execution):

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run in watch mode
npm run test:watch

Test Coverage:

  • Input validation (11 tests)
  • DeFi classifier (10 tests)
  • Token registry (7 tests)
  • Helius API client (24 tests)
  • DeFiLlama API client (24 tests)
  • Tool implementations (113 tests)
  • MCP server integration (12 tests)
  • Integration tests (9 tests)

All tests are mock-based (no external API dependencies) for fast, deterministic execution.

Example Usage

Get Wallet Balance

User: "Get the SOL balance for wallet 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"

Response:
{
  "balance_sol": 5.5,
  "balance_usd": 550.00,
  "price_per_sol": 100.00
}

Analyze DeFi Positions

User: "Analyze DeFi positions in wallet 7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU"

Response:
Known DeFi Positions:
  - jupSOL: 2.5 tokens ($250 USD) - Jito Liquid Staking
  - mSOL: 1.0 tokens ($100 USD) - Marinade Staking

Likely DeFi Positions:
  - SOL-USDC-LP: 0.5 tokens ($50 USD) - LP token detected

Summary:
  - Total DeFi Value: $400 USD
  - Protocols: Jito, Marinade, Unknown DEX

Get Protocol Rankings

User: "What are the top 5 Solana DeFi protocols by TVL?"

Response:
1. Kamino Lend - $1.65B (Lending)
2. Jito - $1.07B (Liquid Staking)
3. Marinade - $850M (Liquid Staking)
4. Jupiter - $600M (DEX)
5. Drift - $400M (Perpetuals)

Security

  • API Key Management: Environment variables, never hardcoded
  • Input Validation: Solana SDK PublicKey validation for wallet addresses
  • Error Sanitization: Generic error messages, no internal details leaked
  • Request Timeouts: 5-second default with AbortController
  • Rate Limiting: Built-in limits (50 tokens max for pricing, 50 transactions max)
  • Authorization Headers: Proper API authentication

Data Sources

Source Purpose API Key Required Rate Limits
Helius Blockchain data (balances, transactions) Yes (free tier) 100k credits/day
DeFiLlama Protocol TVL, token prices No Public API

The Differentiator: 3-Bucket Classification

Corvus uses a unique dual-strategy approach to identify DeFi positions:

1. Known DeFi (Registry-Based)

Hardcoded registry of verified receipt tokens:

  • Liquid Staking: jupSOL, mSOL, bSOL, stSOL
  • Governance: JUP, JTO, MNDE, RAY, ORCA
  • LP Tokens: JLP, USDC-USDT-LP

2. Likely DeFi (Heuristic-Based)

Pattern detection for unknown tokens:

  • LP Tokens: Contains "LP" or hyphen (SOL-USDC)
  • Vault Tokens: k-prefix (kUSDC = Kamino vault)
  • Protocol Names: Contains known protocol names
  • No Market Price: Receipt tokens typically not traded

Requires 2+ signals to classify as "Likely DeFi"

3. Unclassified

Everything else (regular tokens, base assets, stablecoins)

Why This Matters: Users can instantly see their staking positions, lending deposits, and LP tokens across all protocols without manual tracking.

Contributing

Contributions are welcome! Here's how to help:

Adding DeFi Tokens to Registry

Edit src/data/defi-registry.ts:

{
  mint: "token-mint-address",
  symbol: "TOKEN",
  name: "Token Name",
  protocol: "Protocol Name",
  category: "Liquid Staking" | "Governance" | "LP Token",
  underlying_asset: "SOL", // optional
  description: "Brief description"
}

Adding New Tools

  1. Create src/tools/your-tool.ts
  2. Implement with validation, API calls, structured response
  3. Register in src/index.ts (ListTools and CallTool handlers)
  4. Add tests in tests/unit/tools/your-tool.test.ts
  5. Run npm test to verify

Code Standards

  • TypeScript strict mode
  • All responses include _meta field (data source, timestamp)
  • Input validation before API calls
  • Error handling with sanitized messages
  • Mock-based unit tests (no real API calls)

License

MIT License - see LICENSE for details

Acknowledgments

Built with:

Contact

Built for the 2 Fast 2 MCP Hackathon

About

Solana DeFi intelligence via Model Context Protocol

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages