Jovay Interaction MCP Server

A Model Context Protocol (MCP) server that enables AI assistants and other MCP clients to interact with the Jovay blockchain network through the jovay-cli command-line tool.

Overview

This MCP server provides a standardized interface for blockchain operations on Jovay, a Layer 2 network. It wraps the jovay-cli functionality into MCP tools, allowing AI assistants to perform wallet management, transaction handling, and smart contract interactions programmatically.

Features

🔗 Network Management

• jovay_init - Initialize network and wallet configuration
• jovay_network_get - Retrieve current network configuration and wallet info
• jovay_network_switch - Switch between testnet and mainnet
• jovay_network_set - Update network RPC configuration

👛 Wallet Operations

• jovay_wallet_address - Get wallet address
• jovay_wallet_balance - Check ETH or ERC20 token balances
• jovay_wallet_airdrop - Request testnet ETH (0.001 ETH, once per 24 hours)
• jovay_wallet_transfer - Transfer ETH or ERC20 tokens
• jovay_wallet_approve - Approve ERC20 token allowances
• jovay_wallet_set - Update wallet configuration

📝 Transaction Management

• jovay_transaction_info - Get transaction details by hash
• jovay_transaction_send - Broadcast signed transactions

🔗 Smart Contract Interaction

• jovay_contract_call - Read contract data (view/pure functions)
• jovay_contract_write - Send transactions to modify contract state

Installation

Prerequisites

• Node.js ≥16.0.0
• jovay-cli installed and available in PATH

Install from npm

npm install -g @jovaylabs/jovay-interaction-mcp

Configure in MCP Client

Add to your MCP client configuration (e.g., Claude Code):

{
  "mcpServers": {
    "jovay-interaction": {
      "command": "jovay-interaction-mcp",
      "env": {
        "JOVAY_NETWORK": "testnet",
        "JOVAY_TESTNET_L2_RPC": "https://sepolia.jovay.io",
        "JOVAY_TESTNET_L1_RPC": "https://sepolia.infura.io/v3/YOUR_PROJECT_ID"
      }
    }
  }
}

Local Development

git clone https://github.com/jovaynetwork/jovay-cli.git
cd jovay-cli/.ai/jovay-interaction-mcp
npm install
npm start

Configuration

Configure the server using environment variables:

Network Configuration

• JOVAY_NETWORK - Network selection ("testnet" or "mainnet")

RPC Endpoints (Network-specific)

• JOVAY_TESTNET_L1_RPC - Testnet Ethereum L1 RPC
• JOVAY_TESTNET_L2_RPC - Testnet Jovay L2 RPC
• JOVAY_MAINNET_L1_RPC - Mainnet Ethereum L1 RPC
• JOVAY_MAINNET_L2_RPC - Mainnet Jovay L2 RPC

Fallback RPCs

• JOVAY_L1_RPC - Generic L1 RPC fallback
• JOVAY_L2_RPC - Generic L2 RPC fallback
• JOVAY_RPC - Ultimate RPC fallback

Authentication

• JOVAY_SECRET_KEY - Private key for wallet operations
• JOVAY_ENC_KEY - Encryption key for wallet security
• JOVAY_API_KEY - ZAN API key for enhanced services

Usage Examples

Initialize Wallet

{
  "tool_name": "jovay_init",
  "parameters": {
    "network": "testnet",
    "generate_random": true,
    "encrypt": true
  }
}

Check Balance

{
  "tool_name": "jovay_wallet_balance",
  "parameters": {
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb9",
    "token": "ETH"
  }
}

Call Contract Function

{
  "tool_name": "jovay_contract_call",
  "parameters": {
    "contract": "0xA0b86a33E6441c3f2d0dA881775D77808812e4FA",
    "method": "balanceOf",
    "inputs": "address",
    "args": "[\"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb9\"]"
  }
}

Transfer Tokens

{
  "tool_name": "jovay_wallet_transfer",
  "parameters": {
    "to": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb9",
    "amount": "1.5",
    "token": "ETH",
    "broadcast": true
  }
}

API Reference

Tool Parameters

All tools support optional parameters for network configuration:

• rpc - Custom RPC endpoint
• l1 - Use L1 network (default: L2)

Contract tools support:

• abi - Path to ABI JSON file
• dry_run - Simulate without execution

Transaction tools support:

• broadcast - Submit to network (default: false for write operations)

Security Features

• Environment Variable Protection: Private keys and sensitive data stored in environment variables
• Optional Encryption: Wallet encryption with custom keys
• Network Isolation: Clear separation between mainnet and testnet operations
• Dry Run Mode: Test contract interactions before execution

Error Handling

The server provides detailed error messages for:

• Missing or invalid configuration
• Network connectivity issues
• Insufficient funds
• Contract execution failures
• Authentication errors

Development

Project Structure

jovay-interaction-mcp/
├── index.mjs           # Main server implementation
├── package.json        # Package configuration
└── README.md          # Documentation

Building and Testing

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests (when implemented)
npm test

NPM Distribution

This package is configured for npm distribution with:

• Scoped package name: @jovaylabs/jovay-interaction-mcp
• Public repository access
• MIT License
• Modern ES modules
• Node.js ≥16.0.0 requirement

Publishing

# Version bump
npm version patch|minor|major

# Publish to npm
npm publish

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

• GitHub Issues: https://github.com/jovaynetwork/jovay-cli/issues
• Documentation: [Add documentation URL]

Changelog

v0.0.1

• Initial release
• Basic wallet operations
• Network management
• Contract interaction support
• MCP protocol implementation