devion-mcp-server/README.md

MCP server for Devion blockchain infrastructure - AI-native blockchain data access for developers and AI agents

# 🚀 Devion MCP Server

The **first AI-native blockchain infrastructure** - providing AI agents with direct access to multi-chain blockchain data through the Model Context Protocol (MCP).

[![NPM Version](https://img.shields.io/npm/v/devion-mcp-server)](https://www.npmjs.com/package/devion-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)

## ✨ **What This Enables**

Transform AI agents into blockchain-native applications with enterprise-grade infrastructure:

```
AI Agent: "What's vitalik.eth's balance across all L2 networks?"
Devion:   "Checking Ethereum, Base, Arbitrum, and Polygon..."
Result:   Complete multi-chain portfolio with USD values
```

```
AI Agent: "Compare gas costs for a DEX swap across networks"
Devion:   "Analyzing current gas prices and costs..."
Result:   Arbitrum: $0.02, Base: $0.05, Ethereum: $15.30
```

## 🎯 **Key Features**

- 🔗 **Multi-Chain Support** - Ethereum, Base, Arbitrum, Polygon + testnets
- ⚡ **High Performance** - Sub-second responses with enterprise caching
- 🛡️ **Production Ready** - Rate limiting, error handling, retry logic
- 🤖 **AI Optimized** - Structured responses perfect for AI consumption
- 📊 **Advanced Analytics** - Portfolio analysis, gas optimization, DeFi insights
- 🔧 **Developer Friendly** - Full TypeScript support with comprehensive validation

---

## 🚀 **Quick Start**

### **1. Installation**

```bash
npm install -g devion-mcp-server
```

### **2. Get Your Devion API Key**

```bash
# Sign up at https://devion.dev 
# ⚠️ IMPORTANT: Growth tier or higher required for MCP access
export DEVION_API_KEY="your-api-key-here"
```

> **🚀 Growth Tier Required**: MCP access is exclusive to Growth tier subscribers ($49/month) and above. This provides access to AI-native blockchain tools with enterprise-grade infrastructure.

### **3. Configure Claude Desktop**

Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "devion": {
      "command": "devion-mcp-server",
      "env": {
        "DEVION_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### **4. Restart Claude Desktop**

You're ready! Claude now has access to blockchain data across 6+ networks.

---

## 🛠️ **Available Tools**

### **💰 Balance & Portfolio Tools**

#### `get_account_balance`
Get native token balance for any address on any supported network.

```typescript
// AI can ask: "What's the ETH balance of vitalik.eth?"
{
  address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  network?: "ethereum-mainnet" | "base-mainnet" | "arbitrum-mainnet" | "polygon-mainnet",
  formatted?: boolean,
  include_usd_value?: boolean
}
```

#### `get_multichain_balances`
Check balances across multiple networks simultaneously.

```typescript
// AI can ask: "Show me this wallet's balances on all L2 networks"
{
  address: "0x...",
  networks?: ["base-mainnet", "arbitrum-mainnet", "polygon-mainnet"],
  include_usd_values?: boolean,
  min_balance_threshold?: number
}
```

### **📊 Transaction Tools**

#### `get_transaction_details`
Get comprehensive transaction information including gas usage and status.

```typescript
// AI can ask: "Analyze this transaction hash"
{
  tx_hash: "0x...",
  network?: "ethereum-mainnet",
  include_receipt?: boolean
}
```

#### `get_recent_transactions`
Get recent transactions for an address (requires indexing service integration).

### **⛽ Network & Gas Tools**

#### `get_latest_block`
Get current block information including gas usage and transaction count.

```typescript
// AI can ask: "What's the latest block on Base?"
{
  network?: "base-mainnet",
  include_transactions?: boolean
}
```

#### `get_gas_prices`
Get current gas prices across multiple networks with cost estimates.

```typescript
// AI can ask: "What are gas prices right now?"
{
  networks?: ["ethereum-mainnet", "base-mainnet", "arbitrum-mainnet"],
  include_estimates?: boolean
}
```

#### `compare_gas_costs`
Compare transaction costs across networks to find the cheapest option.

```typescript
// AI can ask: "Where's the cheapest place to do a DEX swap?"
{
  networks?: ["ethereum-mainnet", "base-mainnet", "arbitrum-mainnet"],
  transaction_type?: "simple_transfer" | "erc20_transfer" | "contract_interaction" | "dex_swap",
  include_time_estimates?: boolean
}
```

### **🔧 Smart Contract Tools**

#### `call_contract_function`
Execute read-only smart contract function calls.

```typescript
// AI can ask: "Call the balanceOf function on this ERC20 token"
{
  contract_address: "0x...",
  function_data: "0x70a08231000000000000000000000000...", // Encoded function call
  network?: "ethereum-mainnet",
  from_address?: "0x...",
  block_number?: "latest"
}
```

#### `get_contract_info`
Get basic contract information including bytecode size and type.

```typescript
// AI can ask: "Is this address a smart contract?"
{
  contract_address: "0x...",
  network?: "ethereum-mainnet",
  include_bytecode?: boolean
}
```

---

## 🌐 **Supported Networks**

| Network | Chain ID | Status | Features |
|---------|----------|--------|----------|
| **Ethereum Mainnet** | 1 | ✅ Production | Full support |
| **Base Mainnet** | 8453 | ✅ Production | Full support |
| **Arbitrum One** | 42161 | ✅ Production | Full support |
| **Polygon Mainnet** | 137 | ✅ Production | Full support |
| **Base Sepolia** | 84532 | ✅ Testnet | Development |
| **Arbitrum Sepolia** | 421614 | ✅ Testnet | Development |

---

## 💡 **Example AI Conversations**

### **Portfolio Analysis**
```
Human: "Analyze this crypto wallet's portfolio: 0x742d35Cc6635C0532925a3b8D007EbA3fFC2C5DD"

AI: I'll analyze this wallet across multiple blockchain networks using the Devion MCP server.

*calls get_multichain_balances with USD values*

This wallet has:
- Ethereum: 1.23 ETH ($3,075)
- Base: 0.45 ETH ($1,125) 
- Arbitrum: 2.1 ETH ($5,250)
- Polygon: 150 MATIC ($120)

Total portfolio value: $9,570
Largest holding: Arbitrum (54.9%)
```

### **Gas Optimization**
```
Human: "I want to swap tokens but gas is expensive. What's the cheapest network?"

AI: Let me compare gas costs for DEX swaps across networks.

*calls compare_gas_costs with transaction_type: "dex_swap"*

Current DEX swap costs:
- Arbitrum: $0.15 (cheapest) ⚡
- Base: $0.22 (2nd cheapest)
- Polygon: $0.08 (cheapest overall!)
- Ethereum: $45.30 (301x more expensive)

Recommendation: Use Polygon for 99.8% cost savings!
```

### **Transaction Investigation**
```
Human: "This transaction failed, can you tell me why? 0x123..."

AI: I'll investigate this transaction for you.

*calls get_transaction_details with receipt*

Transaction Analysis:
- Status: Failed ❌
- Network: Ethereum Mainnet
- Gas Used: 89,432 / 150,000 (59.6%)
- Failure Reason: The transaction ran out of gas during execution

The contract call consumed more gas than estimated. Try increasing the gas limit to ~120,000 for similar transactions.
```

---

## 🏗️ **Architecture**

```typescript
// MCP Server Architecture
devion-mcp-server/
├── src/
│   ├── index.ts              // Main MCP server
│   ├── types.ts              // TypeScript definitions
│   └── tools/
│       ├── balances.ts       // Balance & portfolio tools
│       ├── transactions.ts   // Transaction analysis
│       ├── blocks.ts         // Block & network data
│       ├── contracts.ts      // Smart contract interactions
│       └── multichain.ts     // Cross-chain analysis
└── Powered by Devion SDK ⚡
```

### **Response Format**

All tools return consistent, AI-optimized responses:

```typescript
{
  success: boolean,
  data: {
    // Tool-specific data
  },
  error?: string,
  details?: {
    // Additional context
  }
}
```

---

## 🔧 **Development**

### **Local Development**

```bash
# Clone the repository
git clone https://github.com/devion-dev/devion-mcp-server
cd devion-mcp-server

# Install dependencies
npm install

# Set environment variables
export DEVION_API_KEY="your-api-key"

# Run in development mode
npm run dev

# Build for production
npm run build

# Start production server
npm start
```

### **Testing**

```bash
# Run with a specific tool
echo '{"method": "tools/call", "params": {"name": "get_account_balance", "arguments": {"address": "0x742d35Cc6635C0532925a3b8D007EbA3fFC2C5DD"}}}' | node dist/index.js
```

### **Environment Variables**

| Variable | Required | Description |
|----------|----------|-------------|
| `DEVION_API_KEY` | ✅ Yes | Your Devion API key from devion.dev |

---

## 📈 **Growth Tier Integration**

The Devion MCP Server is included in **Devion Growth tier plans**:

- 🚀 **5M MCP calls/month**
- ⚡ **Advanced blockchain analytics**
- 🔗 **Multi-chain operations**
- 🛡️ **Priority support**
- 📊 **Real-time data across 6+ networks**

[**Upgrade to Growth Tier →**](https://devion.dev/pricing)

---

## 🤝 **Contributing**

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

### **Adding New Tools**

```typescript
// src/tools/my-tool.ts
export const myNewTool: McpTool = {
  name: 'my_new_tool',
  description: 'What this tool does for AI agents',
  inputSchema: {
    // JSON Schema for validation
  },
  async handler(args) {
    // Implementation using Devion SDK
  }
};
```

---

## 🔐 **Access Control & Security**

### **Growth Tier Validation**

The MCP server includes automatic subscription tier validation:

- ✅ **Startup Validation**: Checks subscription tier when server starts
- ✅ **Runtime Validation**: Validates tier for each tool call
- ✅ **Real-time Monitoring**: Tracks usage against subscription limits
- ✅ **Graceful Errors**: Clear error messages with upgrade paths

### **Error Handling**

If you don't have Growth tier access:

```bash
❌ MCP ACCESS DENIED
═══════════════════════════════════════════════════════════════════════

🚀 MCP Access requires Growth tier!

✨ Upgrade to Growth tier to unlock:
• AI-native blockchain tools for Claude
• 5M API calls/month
• Multi-chain portfolio analysis
• Gas optimization recommendations
• Priority support

💫 Upgrade now: https://devion.dev/pricing

═══════════════════════════════════════════════════════════════════════
```

### **Supported Subscription Tiers**

| Tier | MCP Access | Monthly Calls | Features |
|------|------------|---------------|----------|
| **Free** | ❌ No | 100K | Standard API access |
| **Growth** | ✅ Yes | 5M | MCP + AI tools |
| **Scale** | ✅ Yes | 50M | MCP + Priority support |

---

## 📄 **License**

MIT License - see [LICENSE](LICENSE) file for details.

---

## 🆘 **Support**

- 📧 **Email**: support@devion.dev
- 💬 **Discord**: [Join our community](https://discord.gg/devion)
- 📖 **Docs**: [devion.dev/docs](https://devion.dev/docs)
- 🐛 **Issues**: [GitHub Issues](https://github.com/devion-dev/devion-mcp-server/issues)

---

## 🚀 **What's Next?**

- 🔮 **DeFi Analytics** - Yield farming, liquidity positions, impermanent loss
- 🎨 **NFT Tools** - Collection analysis, floor prices, metadata
- 🤖 **AI Trading** - Portfolio rebalancing, arbitrage detection
- 🔐 **Security Analysis** - Contract auditing, rug pull detection

**Built with ❤️ by the Devion team**