Klever VM MCP Server

resmi

MCP server for [Klever](https://klever.org) blockchain smart contract development, on-chain data exploration, and VM interaction. Public remote server available at `https://mcp.klever.org/mcp`.

GitHub

Dokumentasi

Klever MCP Server

Server Model Context Protocol (MCP) yang disesuaikan untuk pengembangan kontrak pintar blockchain Klever. Server ini memelihara dan menyajikan pengetahuan kontekstual termasuk pola kode, praktik terbaik, dan perilaku runtime bagi pengembang yang bekerja dengan Klever VM SDK.

Fitur

🚀 Operasi Tiga Mode: Berjalan sebagai server API HTTP, server MCP stdio, atau server MCP publik yang dihosting
💾 Penyimpanan Fleksibel: Dukungan backend dalam memori atau Redis
🔍 Pengambilan Konteks Cerdas: Kueri berdasarkan tipe, tag, atau tipe kontrak
📝 Ekstraksi Pola Otomatis: Mengurai kontrak Klever untuk mengekstrak contoh dan pola
🎯 Peringkat Relevansi: Penilaian dan peringkat konteks yang cerdas
🔄 Pembaruan Langsung: Menambah dan memperbarui konteks secara real-time
🛡️ Keamanan Tipe: TypeScript penuh dengan validasi Zod
📚 Basis Pengetahuan Komprehensif: Dimuat dengan pola, praktik terbaik, dan contoh Klever VM
🔧 Validasi Kontrak: Deteksi otomatis masalah umum dan anti-pola
🚀 Skrip Deployment: Skrip siap pakai untuk deployment, upgrade, dan kueri kontrak

Mulai Cepat

Instal dan jalankan langsung melalui npx — tidak perlu kloning:

npx -y @klever/mcp-server

Atau sambungkan ke server publik yang dihosting:

claude mcp add -t http klever-vm https://mcp.klever.org/mcp

Lihat Integrasi Klien MCP untuk konfigurasi spesifik klien.

Arsitektur

mcp-klever-vm/
├── src/
│   ├── api/          # HTTP API routes with validation
│   ├── context/      # Context management service layer
│   ├── mcp/          # MCP protocol server implementation
│   ├── parsers/      # Klever contract parser and validator
│   ├── storage/      # Storage backends (memory/Redis)
│   │   ├── memory.ts # In-memory storage with size limits
│   │   └── redis.ts  # Redis storage with optimized queries
│   ├── types/        # TypeScript type definitions
│   ├── utils/        # Utilities and ingestion tools
│   └── knowledge/    # Modular knowledge base (95+ entries)
│       ├── core/     # Core concepts and imports
│       ├── storage/  # Storage patterns and mappers
│       ├── events/   # Event handling and rules
│       ├── tokens/   # Token operations and decimals
│       ├── modules/  # Built-in modules (admin, pause)
│       ├── tools/    # CLI tools (koperator, ksc)
│       ├── scripts/  # Helper scripts
│       ├── examples/ # Complete contract examples
│       ├── errors/   # Error patterns
│       ├── best-practices/ # Optimization and validation
│       └── documentation/  # API reference
├── tests/            # Test files
└── docs/             # Documentation

Peningkatan Utama yang Dilakukan

Lapisan Penyimpanan
- Menambahkan batas memori untuk mencegah OOM di InMemoryStorage
- Mengoptimalkan kueri Redis untuk menghindari perintah KEYS O(N)
- Menambahkan transaksi atomik untuk operasi Redis
- Meningkatkan penanganan kesalahan dan validasi
Keamanan API
- Menambahkan validasi input untuk semua endpoint
- Batas ukuran operasi batch
- Respons kesalahan yang tepat tanpa membocorkan internal
- Pesan kesalahan yang sadar lingkungan
Keamanan Tipe
- Validasi skema terpusat
- Antarmuka TypeScript yang tepat untuk opsi
- Validasi runtime data yang disimpan
Kinerja
- Operasi batch menggunakan Redis MGET
- Kueri berbasis indeks alih-alih pemindaian penuh
- Operasi penghitungan yang dioptimalkan

Instalasi

Kloning repositori:

git clone https://github.com/klever-io/mcp-klever-vm.git
cd mcp-klever-vm

Instal dependensi:

pnpm install

Salin konfigurasi lingkungan:

cp .env.example .env

Instal alat Klever SDK (diperlukan untuk transaksi):

chmod +x scripts/install-sdk.sh && ./scripts/install-sdk.sh

Bangun proyek:

pnpm run build

Konfigurasi

Edit file .env untuk mengonfigurasi server:

# Server Mode (http, mcp, or public)
MODE=http

# HTTP Server Port (only for http mode)
PORT=3000

# Storage Backend (memory or redis)
STORAGE_TYPE=memory

# Maximum contexts for in-memory storage (default: 10000)
MEMORY_MAX_SIZE=10000

# Redis URL (only if STORAGE_TYPE=redis)
REDIS_URL=redis://localhost:6379

# Node environment (development or production)
NODE_ENV=development

Integrasi Klien MCP

Claude Code

# Add via npx (recommended)
claude mcp add klever-vm -- npx -y @klever/mcp-server

# Or connect to the public hosted server
claude mcp add -t http klever-vm https://mcp.klever.org/mcp

Claude Desktop

Tambahkan ke claude_desktop_config.json Anda:

{
  "mcpServers": {
    "klever-vm": {
      "command": "npx",
      "args": ["-y", "@klever/mcp-server"]
    }
  }
}

Untuk pengaturan detail, lihat Panduan Instalasi Claude Desktop.

Cursor

Tambahkan ke pengaturan MCP Cursor Anda (.cursor/mcp.json):

{
  "mcpServers": {
    "klever-vm": {
      "command": "npx",
      "args": ["-y", "@klever/mcp-server"]
    }
  }
}

VS Code (GitHub Copilot)

Tambahkan ke .vscode/mcp.json di proyek Anda:

{
  "servers": {
    "klever-vm": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@klever/mcp-server"]
    }
  }
}

Untuk pengaturan detail, lihat Panduan Instalasi VS Code.

Server MCP Publik

Klever MCP Server dapat dihosting sebagai layanan bersama publik, memungkinkan pengembang mana pun untuk terhubung tanpa menjalankannya secara lokal.

Menghubungkan ke Server Publik

# Add permanently (user-level)
claude mcp add -t http klever-vm https://mcp.klever.org/mcp

# Add for current project only
claude mcp add -t http -s project klever-vm https://mcp.klever.org/mcp

Alat yang Tersedia (Mode Publik)

Server publik mengekspos subset alat hanya-baca untuk keamanan:

Alat	Deskripsi
`query_context`	Cari basis pengetahuan Klever VM
`get_context`	Ambil konteks tertentu berdasarkan ID
`find_similar`	Temukan konteks yang mirip dengan konteks yang diberikan
`get_knowledge_stats`	Dapatkan statistik basis pengetahuan
`enhance_with_context`	Tingkatkan kueri dengan konteks Klever VM yang relevan

Operasi tulis (add_context) dan alat berbasis shell (init_klever_project, add_helper_scripts) dinonaktifkan dalam mode publik.

Hosting Sendiri dengan Docker

# Build and run
docker build -t mcp-klever-vm .
docker run -p 3000:3000 mcp-klever-vm

# Or using docker compose
docker compose up -d

Kemudian sambungkan:

claude mcp add -t http klever-vm-local http://localhost:3000/mcp

Hosting Sendiri tanpa Docker

pnpm install
pnpm run build
pnpm run start:public

Variabel Lingkungan (Mode Publik)

Variabel	Default	Deskripsi
`MODE`	`http`	Atur ke `public` untuk mode hosted
`PORT`	`3000`	Port server
`CORS_ORIGINS`	(tidak disetel)	Origin yang diizinkan dipisahkan koma. Tidak disetel atau `*` mengizinkan semua origin
`RATE_LIMIT_MCP`	`60`	Permintaan endpoint MCP/menit per IP
`RATE_LIMIT_API`	`30`	Permintaan endpoint API/menit per IP
`BODY_SIZE_LIMIT`	`1mb`	Ukuran maksimum badan permintaan

Catatan Deployment

Untuk produksi di mcp.klever.org:

Deploy kontainer Docker di belakang proxy balik (nginx/Caddy/cloud LB) untuk terminasi TLS
Pastikan proxy meneruskan header mcp-session-id dan mendukung SSE (nonaktifkan buffering respons)
Satu instans sudah cukup karena server bersifat hanya-baca dengan basis pengetahuan dalam memori
Pertimbangkan Cloudflare untuk perlindungan DDoS (SSE didukung)

Penggunaan

Pemuatan Basis Pengetahuan

Server secara otomatis memuat basis pengetahuan Klever berdasarkan tipe penyimpanan Anda:

Penyimpanan Memori (Default)

Pengetahuan dimuat secara otomatis saat server dimulai
Tidak perlu menjalankan pnpm run ingest secara terpisah
Data hanya ada saat server berjalan
Terbaik untuk pengembangan dan pengujian

Penyimpanan Redis

# First, ingest the knowledge base (one time)
pnpm run ingest

# Then start the server
pnpm run dev

Pengetahuan bertahan di database Redis
Bertahan saat server restart
Terbaik untuk penggunaan produksi

Ini akan memuat:

Template dan contoh kontrak pintar
Aturan anotasi dan praktik terbaik
Pola dan perbandingan storage mapper
Skrip deployment dan kueri
Kesalahan umum dan solusi
Pola pengujian
Dokumentasi referensi API

Menjalankan sebagai Server HTTP

# Development mode
pnpm run dev

# Production mode
pnpm run build && pnpm start

API HTTP akan tersedia di http://localhost:3000/api

Menjalankan sebagai Server MCP

MODE=mcp pnpm start

Gunakan dengan klien yang kompatibel dengan MCP.

Endpoint API

POST `/api/context`

Masukkan konteks baru ke dalam sistem.

{
  "type": "code_example",
  "content": "contract code here",
  "metadata": {
    "title": "Token Contract Example",
    "description": "ERC20-like token implementation",
    "tags": ["token", "fungible"],
    "contractType": "token"
  }
}

GET `/api/context/:id`

Ambil konteks tertentu berdasarkan ID.

POST `/api/context/query`

Kueri konteks dengan filter.

{
  "query": "transfer",
  "types": ["code_example", "best_practice"],
  "tags": ["token"],
  "contractType": "token",
  "limit": 10,
  "offset": 0
}

PUT `/api/context/:id`

Perbarui konteks yang ada.

DELETE `/api/context/:id`

Hapus konteks.

GET `/api/context/:id/similar`

Temukan konteks yang mirip.

POST `/api/context/batch`

Masukkan beberapa konteks secara batch.

Alat MCP

Saat berjalan sebagai server MCP, alat berikut tersedia:

query_context: Cari konteks pengembangan Klever yang relevan
add_context: Tambahkan konteks baru ke basis pengetahuan
get_context: Ambil konteks tertentu berdasarkan ID
find_similar: Temukan konteks yang mirip dengan konteks yang diberikan
get_knowledge_stats: Dapatkan statistik tentang basis pengetahuan
init_klever_project: Inisialisasi proyek kontrak pintar Klever baru dengan skrip pembantu
enhance_with_context: Tingkatkan kueri secara otomatis dengan konteks Klever VM yang relevan

Tipe Konteks

code_example: Cuplikan kode dan contoh yang berfungsi (kode kontrak pintar Rust)
best_practice: Pola dan praktik yang direkomendasikan
security_tip: Pertimbangan dan peringatan keamanan
optimization: Teknik optimasi kinerja
documentation: Dokumentasi dan panduan umum
error_pattern: Kesalahan umum dan solusi
deployment_tool: Skrip deployment dan utilitas (skrip bash, alat)
runtime_behavior: Penjelasan perilaku runtime

Basis Pengetahuan yang Dimuat Sebelumnya

Server MCP mencakup basis pengetahuan komprehensif dengan 95+ entri yang diorganisir ke dalam 11 kategori:

Pola Kritis

Penanganan pembayaran dan operasi token
Konversi desimal dan perhitungan
Emisi event dan aturan parameter
Penggunaan alat CLI dan praktik terbaik

Pola & Contoh Kontrak

Template struktur kontrak dasar
Implementasi permainan lotere lengkap
Kontrak staking dengan hadiah
Pola komunikasi lintas kontrak
Pola akses penyimpanan jarak jauh
Modul pembantu token mapper

Alat Pengembangan

Koperator: Referensi CLI lengkap dengan encoding argumen
KSC: Perintah build dan pengaturan proyek
Skrip deployment, upgrade, dan kueri
Alat manajemen kontrak interaktif
Pustaka utilitas umum (bech32, manajemen jaringan)

Penyimpanan & Optimasi

Panduan pemilihan storage mapper dengan perbandingan kinerja
Pola organisasi namespace
Endpoint view untuk kueri efisien
Teknik optimasi gas
Pola OptionalValue vs Option

Praktik Terbaik & Keamanan

Pola validasi input
Strategi penanganan kesalahan
Penggunaan modul admin dan pause
Pola kontrol akses
Kesalahan umum dan solusi

Menyerap Kontrak

Gunakan utilitas penyerapan bawaan untuk mengurai dan mengimpor kontrak Klever:

import { StorageFactory } from './storage/index.js';
import { ContextService } from './context/service.js';
import { ContractIngester } from './utils/ingest.js';

const storage = StorageFactory.create('memory');
const contextService = new ContextService(storage);
const ingester = new ContractIngester(contextService);

// Ingest a single contract
await ingester.ingestContract('./path/to/contract.rs', 'AuthorName');

// Ingest entire directory
await ingester.ingestDirectory('./contracts', 'AuthorName');

// Add common patterns
await ingester.ingestCommonPatterns();

Pengembangan

# Run tests
pnpm test

# Lint code
pnpm run lint

# Format code
pnpm run format

# Watch mode
pnpm run dev

# Ingest/update knowledge base
pnpm run ingest

Validasi Kontrak

Server dapat secara otomatis memvalidasi kontrak Klever dan mendeteksi masalah:

import { KleverValidator } from './parsers/validators.js';

const issues = KleverValidator.validateContract(contractCode);
// Returns array of detected issues with suggestions

Pemeriksaan validasi meliputi:

Format anotasi event (tanda kutip ganda, camelCase)
Parameter API tipe terkelola
Validasi alamat nol dalam transfer
Pemilihan storage mapper yang optimal
Konvensi penamaan modul

Contoh Kasus Penggunaan

1. Asisten Pengembangan Kontrak Pintar

Integrasikan dengan IDE Anda untuk memberikan saran sadar konteks untuk pengembangan kontrak Klever.

2. Alat Tinjauan Kode

Periksa kontrak secara otomatis terhadap praktik terbaik dan pola keamanan.

3. Platform Pembelajaran

Sediakan contoh dan penjelasan bagi pengembang yang belajar pengembangan Klever.

4. Generator Dokumentasi

Ekstrak dan atur dokumentasi kontrak secara otomatis.

Spesifikasi dan Contoh Proyek

Untuk contoh dan spesifikasi implementasi proyek lengkap, lihat:

Template Spesifikasi Proyek - Template isian untuk menentukan spesifikasi proyek kontrak pintar Klever. Memandu asisten AI melalui penemuan pengetahuan MCP, pelacakan tugas, dan implementasi bertahap. Termasuk contoh KleverDice.

Inisialisasi Proyek

Server MCP mencakup alat inisialisasi proyek yang kuat yang membuat proyek kontrak pintar Klever baru dengan semua skrip pembantu yang diperlukan.

Menggunakan Alat init_klever_project

Saat terhubung melalui MCP, gunakan alat init_klever_project:

{
  "name": "my-token-contract",
  "template": "empty",
  "noMove": false
}

Parameter:

name (wajib): Nama kontrak Anda
template (opsional): Template yang akan digunakan (default: "empty")
noMove (opsional): Jika true, menyimpan proyek di subdirektori (default: false)

Skrip Pembantu yang Dihasilkan

Alat ini membuat skrip berikut di direktori scripts/:

build.sh: Membangun kontrak pintar
deploy.sh: Deploy ke testnet Klever dengan deteksi otomatis artefak kontrak
upgrade.sh: Upgrade kontrak yang ada (deteksi otomatis dari history.json)
query.sh: Kueri endpoint kontrak dengan encoding/decoding yang tepat
test.sh: Jalankan pengujian kontrak
interact.sh: Menampilkan contoh penggunaan dan perintah yang tersedia

Alur Kerja Contoh

Inisialisasi proyek:

# Via MCP tool
init_klever_project({"name": "my-contract"})

Bangun kontrak:
```
./scripts/build.sh
```
Deploy ke testnet:
```
./scripts/deploy.sh
```

Kueri kontrak:

./scripts/query.sh --endpoint getSum
./scripts/query.sh --endpoint getValue --arg myKey

Upgrade kontrak:
```
./scripts/upgrade.sh
```

Semua riwayat deployment dilacak di output/history.json untuk referensi mudah.

Peningkatan Konteks Otomatis

Server MCP dapat secara otomatis meningkatkan kueri dengan konteks Klever VM yang relevan. Ini memastikan klien MCP Anda selalu memiliki akses ke informasi yang paling relevan.

Menggunakan Peningkatan Konteks

Gunakan alat enhance_with_context untuk secara otomatis menambahkan konteks yang relevan ke kueri apa pun:

{
  "tool": "enhance_with_context",
  "arguments": {
    "query": "How do I create a storage mapper?",
    "autoInclude": true
  }
}

Ini akan:

Mengekstrak kata kunci yang relevan dari kueri
Mencari basis pengetahuan untuk konteks yang cocok
Mengembalikan kueri yang ditingkatkan dengan konteks yang disertakan
Menyediakan metadata tentang apa yang ditemukan

Pola Integrasi

Untuk klien MCP yang ingin selalu memeriksa konteks Klever terlebih dahulu:

// Always enhance Klever-related queries
if (query.match(/klever|kvm|smart contract|endpoint/i)) {
  const enhanced = await callTool('enhance_with_context', { query });
  // Use enhanced.enhancedQuery for processing
}

Fitur peningkatan konteks secara otomatis memperkaya kueri dengan pengetahuan Klever VM yang relevan dari basis pengetahuan komprehensif.

Contoh Integrasi

Ekstensi VS Code

// Query for token transfer examples
const response = await fetch('http://localhost:3000/api/context/query', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    query: 'transfer',
    types: ['code_example'],
    contractType: 'token'
  })
});

Alat CLI

# Using curl to add context
curl -X POST http://localhost:3000/api/context \
  -H "Content-Type: application/json" \
  -d '{
    "type": "security_tip",
    "content": "Always check for zero address",
    "metadata": {
      "title": "Zero Address Check",
      "tags": ["security", "validation"]
    }
  }'

Berkontribusi

Kontribusi sangat diterima! Silakan:

Fork repositori
Buat branch fitur
Lakukan perubahan Anda
Tambahkan pengujian
Kirim pull request

Lisensi

Lisensi MIT - lihat file LICENSE untuk detailnya

Ucapan Terima Kasih

Terinspirasi oleh Context7 by Upstash
Dibangun untuk Klever Blockchain
Menggunakan Klever VM SDK (Rust)