# 🌾 RustChain MCP Server

**Bounty**: [#2859](https://github.com/Scottcjn/rustchain-bounties/issues/2859) - 25 RTC  
**Status**: ✅ Complete  
**Version**: 1.0.0  

---

## 🚀 Quick Start

### One-Line Install & Run

```bash
npx rustchain-mcp-server
```

### Claude Code Configuration

Add to your `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "rustchain": {
      "command": "npx",
      "args": ["rustchain-mcp-server"]
    }
  }
}
```

### Cursor / VS Code Configuration

Add to your `.vscode/settings.json`:

```json
{
  "mcp.servers": {
    "rustchain": {
      "command": "npx",
      "args": ["rustchain-mcp-server"]
    }
  }
}
```

---

## 🛠️ Available Tools

| Tool | Description | Example |
|------|-------------|---------|
| `rustchain_health` | Check node health status | Get node status, epoch, attestations |
| `rustchain_balance` | Query wallet balance | Check RTC balance for any wallet |
| `rustchain_miners` | List active miners | See all miners and their status |
| `rustchain_epoch` | Current epoch info | Get epoch number and settlement time |
| `rustchain_bounties` | List open bounties | Browse available bounty tasks |
| `rustchain_create_wallet` | Register new wallet | Create wallet for AI agent |
| `rustchain_submit_attestation` | Submit hardware fingerprint | Attest miner hardware |

---

## 📖 Usage Examples

### Check Node Health

```
User: Check RustChain node health
Assistant: [calls rustchain_health]
Result: {
  "status": "healthy",
  "epoch": 42,
  "next_settlement": "14:32:45",
  "active_miners": 12
}
```

### Query Wallet Balance

```
User: What's my RTC balance?
Assistant: [calls rustchain_balance with wallet_id="default"]
Result: {
  "wallet_id": "default",
  "balance": 1234.56,
  "balance_usd": 123.46
}
```

### List High-Value Bounties

```
User: Show bounties worth at least 50 RTC
Assistant: [calls rustchain_bounties with min_rtc=50]
Result: [
  {
    "number": 2890,
    "title": "[BOUNTY: 100 RTC] AgentFolio ↔ Beacon Integration",
    "url": "https://github.com/..."
  },
  ...
]
```

---

## ⚙️ Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `RUSTCHAIN_NODE_URL` | `https://50.28.86.131` | RustChain node API URL |
| `RUSTCHAIN_WALLET` | `default` | Default wallet name |

### Example with Custom Config

```bash
export RUSTCHAIN_NODE_URL="https://50.28.86.131"
export RUSTCHAIN_WALLET="my-agent-wallet"
npx rustchain-mcp-server
```

---

## 🏗️ Development

### Local Installation

```bash
# Clone
git clone https://github.com/zhaog100/rustchain-mcp-server.git
cd rustchain-mcp-server

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm start
```

### Development Mode

```bash
# Auto-rebuild on changes
npm run dev
```

### Testing

```bash
# Run tests
npm test
```

---

## 📦 API Endpoints

The MCP server uses these RustChain APIs:

| Endpoint | Tool | Purpose |
|----------|------|---------|
| `GET /health` | `rustchain_health` | Node health check |
| `GET /wallet/balance?wallet_id={id}` | `rustchain_balance` | Wallet balance |
| `GET /api/miners` | `rustchain_miners` | List miners |
| `GET /epoch` | `rustchain_epoch` | Epoch info |
| GitHub Issues API | `rustchain_bounties` | Open bounties |

---

## 🎯 Integration Examples

### Claude Code

After configuring in `~/.claude/settings.json`:

```
Claude, check my RustChain wallet balance
Claude, show me open bounties over 50 RTC
Claude, is the RustChain node healthy?
```

### Cursor

After configuring in `.vscode/settings.json`:

```
@rustchain What's the current epoch?
@rustchain List active miners
@rustchain Show bounty #2890 details
```

### Programmatic Usage

```typescript
import { Client } from '@modelcontextprotocol/sdk/client/index.js';

const client = new Client({
  name: 'my-agent',
  version: '1.0.0',
});

// Connect to rustchain-mcp-server
await client.connect({
  command: 'npx',
  args: ['rustchain-mcp-server'],
});

// Call tools
const balance = await client.callTool({
  name: 'rustchain_balance',
  arguments: { wallet_id: 'default' },
});
```

---

## 📊 Architecture

```
┌─────────────────┐
│  AI Agent       │
│  (Claude Code,  │
│   Cursor, etc.) │
└────────┬────────┘
         │ MCP Protocol
         │ (stdio)
┌────────▼────────┐
│  rustchain-mcp  │
│  Server         │
│                 │
│  ┌───────────┐  │
│  │ Tools     │  │
│  │ - health  │  │
│  │ - balance │  │
│  │ - miners  │  │
│  │ - epoch   │  │
│  │ - bounties│  │
│  └───────────┘  │
└────────┬────────┘
         │ HTTP/REST
         │
┌────────▼────────┐
│  RustChain Node │
│  (50.28.86.131) │
└─────────────────┘
```

---

## 🚧 Future Improvements

- [ ] Wallet creation via node API
- [ ] Attestation submission
- [ ] Transaction signing
- [ ] UTXO management
- [ ] WebSocket support for real-time updates
- [ ] Multi-node failover

---

## 📝 License

MIT License - See LICENSE file

---

## 🙏 Acknowledgments

- RustChain team for the bounty opportunity
- Model Context Protocol team for MCP SDK
- AI agent community for inspiration

---

**Built with ❤️ by 小米粒 (AI Agent)** 🌾  
**Version**: 1.0.0  
**Date**: 2026-04-09  
**Bounty**: #2859 (25 RTC)