<div align="center">

# 🔗 0G Chain MCP Server v0.1.0

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org)
[![MCP Protocol](https://img.shields.io/badge/MCP-2024--11--05-blue)](https://modelcontextprotocol.io)
[![Docker Ready](https://img.shields.io/badge/Docker-Ready-blue)](https://www.docker.com)

**Production-ready Model Context Protocol (MCP) server for 0G Chain blockchain operations**

[Features](#-features) • [Quick Start](#-quick-start) • [Tools](#-available-tools) • [Prompts](#-prompts) • [Security](#-security) • [Contributing](#-contributing)

</div>

---

## 🚀 Features

### ⛓️ **0G Chain Integration**
- Native 0G token operations (send, balance checks)
- Staking and delegation management
- Validator discovery and analytics
- Rewards tracking with auto-compounding support
- Ethereum-compatible wallet generation
- Direct interaction with 0G Chain Mainnet

### 🏗️ **Dual-Server Architecture**
- HTTP server (Express) for REST API access
- MCP stdio server for Claude Desktop integration
- Seamless communication between both servers
- Process management with graceful shutdown
- Health monitoring endpoints

### 🛠️ **Professional Structure**
- Modular tool system with separate tools.js
- Utility helpers in dedicated utils.js file
- Clean separation of concerns
- Easy to extend and maintain
- Production-tested components

### 🔧 **Developer-Friendly**
- Simple JSON-RPC interface
- Comprehensive error handling
- Environment-based configuration
- Docker containerization support
- MCP protocol 2024-11-05 implementation
- Zero-configuration deployment with sensible defaults

### 🎯 **9 Powerful Tools**
- Wallet creation and management
- Balance checks and token transfers
- Staking/unstaking operations
- Validator information and discovery
- Rewards tracking and calculations
- Explorer integration

---

## 📦 Quick Start

### ✅ Prerequisites
```bash
# Required
Node.js >= 18.0.0
npm >= 9.0.0
```

### 🔑 Configuration

Create a `.env` file in the project root (optional - defaults to 0G Mainnet):

```env
# 0G Chain Configuration (defaults to Mainnet if not specified)
OG_RPC_URL=https://evmrpc.0g.ai
OG_CHAIN_ID=16661

# Wallet Configuration (required for transactions)
WALLET_PRIVATE_KEY=your_private_key_here
WALLET_ADDRESS=your_wallet_address_here

# HTTP Server Configuration
PORT=8080
```

> **Note:** `WALLET_PRIVATE_KEY` and `WALLET_ADDRESS` are only required for transaction operations (send, stake, unstake). Read-only operations work without them.

### 📥 Installation

```bash
# Clone the repository
git clone https://github.com/Tairon-ai/0g-chain-mcp.git
cd 0g-chain-mcp/mcp-server

# Install dependencies
npm install

# Configure environment (optional)
cp .env.example .env
# Edit .env with your wallet credentials (if needed)

# Start the HTTP server
npm start

# MCP stdio server for Claude Desktop
npm run mcp
```

### 🤖 Claude Desktop Integration

**To configure the MCP server in Claude Desktop:**

1. Open Claude Desktop application
2. Click on **Settings** (gear icon)
3. Navigate to **Developer** tab
4. Click **Edit Config** button
5. Add the following configuration to your MCP servers:

```json
{
  "mcpServers": {
    "0g-chain": {
      "command": "node",
      "args": ["/absolute/path/to/0g-chain-mcp/mcp/index.js"],
      "env": {
        "OG_RPC_URL": "https://evmrpc.0g.ai",
        "OG_CHAIN_ID": "16661",
        "WALLET_PRIVATE_KEY": "your_private_key_here",
        "WALLET_ADDRESS": "your_wallet_address_here"
      }
    }
  }
}
```

6. Save the configuration and restart Claude Desktop

> **Security Note:** Only add `WALLET_PRIVATE_KEY` if you plan to perform transactions through Claude. For read-only operations, you can omit it.

---

## 🛠 Available Tools

### 🔐 **Wallet Management**

| Tool | Description | Parameters | Returns |
|------|-------------|------------|---------|
| `create_wallet` | Generate new 0G Chain wallet | None | Address, private key, mnemonic phrase |

### 💰 **Balance & Transfers**

| Tool | Description | Parameters | Returns |
|------|-------------|------------|---------|
| `get_balance` | Check 0G token balance | `address` (optional) | Balance in 0G and wei |
| `send_native_token` | Send 0G tokens | `to_address`, `amount`, `from_private_key` (optional), `gas_limit` (optional) | Transaction hash, explorer link |

### 🎯 **Staking Operations**

| Tool | Description | Parameters | Returns |
|------|-------------|------------|---------|
| `stake_tokens` | Delegate tokens to validator | `validator_pubkey` (address or pubkey), `amount`, `delegator_private_key` (optional) | Transaction hash, validator info, estimated rewards |
| `unstake_tokens` | Undelegate tokens from validator | `validator_pubkey`, `amount` (or "all"), `withdrawal_address` (optional), `delegator_private_key` (optional) | Transaction hash, shares burned, unbonding details |
| `get_staking_info` | Get delegation details | `validator_pubkey`, `delegator_address` (optional) | Current stake, shares, rewards estimates |
| `get_accumulated_rewards` | View accumulated rewards | `validator_pubkey`, `delegator_address` (optional), `original_stake_amount` (optional) | Current stake value, accumulated rewards, future estimates |

### 📊 **Validator Discovery**

| Tool | Description | Parameters | Returns |
|------|-------------|------------|---------|
| `get_validators_list` | List known validators | `include_details` (optional, boolean) | Validator addresses, names, optional on-chain details |
| `get_validator_info` | Detailed validator analytics | `validator_pubkey` (address or pubkey) | Complete validator metrics, commission, rewards, calculations |

---

## 🤖 Prompts

### 💬 Example Prompts for Claude

#### **Wallet Operations**
```
"Create a new 0G Chain wallet for me"
"Check my 0G balance"
"What's the balance of address 0x..."
"Send 10 0G tokens to 0x..."
```

#### **Staking Operations**
```
"Show me all available 0G validators"
"Get detailed information about validator 0x..."
"Stake 1 0G token to validator 0x..."
"What are my accumulated rewards from validator 0x...?"
"Unstake 0.5 0G from validator 0x..."
"Unstake all my tokens from validator 0x..."
```

#### **Analytics & Research**
```
"Compare all validators and their commission rates"
"Which validator has the best APY?"
"How much would I earn staking 10 0G for a year?"
"Show me my current staking positions"
"Calculate my rewards if I originally staked 5 0G"
```

### 🌐 HTTP API Testing

```bash
# List available tools
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

# Check balance
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "get_balance", "arguments": {}}, "id": 1}'

# Get validators list
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "get_validators_list", "arguments": {"include_details": false}}, "id": 1}'
```

---

## 🔒 Security

### 🛡️ Security Best Practices

- **Private Key Protection** - Never commit `.env` files or private keys to Git
- **Environment Variables** - Store sensitive data (private keys) in environment variables only
- **Read-Only by Default** - Most tools work without private keys for maximum security
- **Input Validation** - All addresses and amounts are validated before processing
- **Error Handling** - Errors don't expose sensitive information
- **Secure RPC** - Uses HTTPS for all blockchain communication
- **Explorer Integration** - Verify all transactions on 0G Chain explorer

### ⚠️ Important Notes

- **21-Day Unbonding Period**: Unstaked tokens are locked for 21 days before withdrawal
- **Auto-Compounding Rewards**: Rewards automatically compound into your stake (no separate claim needed)
- **Withdrawal Fee**: Small fee charged when unstaking (set by validator)
- **Commission Rates**: Validators charge commission on staking rewards (typically 5-10%)
- **Gas Fees**: All transactions require 0G tokens for gas fees

---

## 🚀 Deployment

### 🏭 Production Deployment

```bash
# Start production server
NODE_ENV=production npm start

# With PM2
pm2 start server.js --name 0g-chain-mcp

# With Docker
docker build -t 0g-chain-mcp .
docker run -d -p 8080:8080 --env-file .env 0g-chain-mcp
```

### 🔑 Environment Variables

```env
# 0G Chain Network Configuration
OG_RPC_URL=https://evmrpc.0g.ai
OG_CHAIN_ID=16661

# Wallet Configuration (optional for read-only operations)
WALLET_PRIVATE_KEY=your_private_key_here
WALLET_ADDRESS=your_wallet_address_here

# Server Configuration
PORT=8080
NODE_ENV=production

# Advanced Settings (optional)
RATE_LIMIT_REQUESTS_PER_SECOND=10
```

---

## 🤝 Contributing

We welcome contributions! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our development process.

```bash
# Fork the repository
git clone https://github.com/Tairon-ai/0g-chain-mcp.git

# Create feature branch
git checkout -b feature/amazing-feature

# Make changes and commit
git commit -m 'feat: add amazing feature'
git push origin feature/amazing-feature

# Open Pull Request
```

---

## 📊 0G Chain Information

### 🌐 Network Details

- **Network Name**: 0G Chain Mainnet
- **Chain ID**: 16661
- **RPC URL**: https://evmrpc.0g.ai
- **Explorer**: https://explorer.0g.ai/mainnet
- **Chain Scanner**: https://chainscan.0g.ai
- **Staking Contract**: 0xea224dBB52F57752044c0C86aD50930091F561B9

---

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

## 📚 Resources

- [MCP Protocol Specification](https://modelcontextprotocol.io/docs/getting-started/intro)
- [MCP GitHub Repository](https://github.com/modelcontextprotocol)
- [0G Chain Documentation](https://docs.0g.ai)
- [ethers.js Documentation](https://docs.ethers.org/v6/)
- [Express.js Documentation](https://expressjs.com/)

---

<div align="center">

**Built by [Tairon.ai](https://tairon.ai) team with help from Claude**

</div>