npm package: @jovaylabs/jovay-interaction-mcp
Description: MCP server for interacting with Jovay blockchain via jovay-cli
Author: Jovay-Network
Latest version: 0.0.1

# 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
```bash
npm install -g @jovaylabs/jovay-interaction-mcp
```

### Configure in MCP Client

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

```json
{
  "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
```bash
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
```json
{
  "tool_name": "jovay_init",
  "parameters": {
    "network": "testnet",
    "generate_random": true,
    "encrypt": true
  }
}
```

### Check Balance
```json
{
  "tool_name": "jovay_wallet_balance",
  "parameters": {
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb9",
    "token": "ETH"
  }
}
```

### Call Contract Function
```json
{
  "tool_name": "jovay_contract_call",
  "parameters": {
    "contract": "0xA0b86a33E6441c3f2d0dA881775D77808812e4FA",
    "method": "balanceOf",
    "inputs": "address",
    "args": "[\"0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb9\"]"
  }
}
```

### Transfer Tokens
```json
{
  "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
```bash
# 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
```bash
# 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