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

Dokümantasyon

Klever MCP Sunucusu

Klever blok zinciri akıllı sözleşme geliştirme için özelleştirilmiş bir Model Bağlam Protokolü (MCP) sunucusu. Bu sunucu, Klever VM SDK ile çalışan geliştiriciler için kod desenleri, en iyi uygulamalar ve çalışma zamanı davranışı dahil olmak üzere bağlamsal bilgiyi korur ve sunar.

Özellikler

🚀 Üçlü Mod Çalışması: HTTP API sunucusu, MCP stdio sunucusu veya genel barındırılan MCP sunucusu olarak çalıştırın
💾 Esnek Depolama: Bellek içi veya Redis arka uç desteği
🔍 Akıllı Bağlam Erişimi: Türe, etiketlere veya sözleşme türüne göre sorgulama
📝 Otomatik Desen Çıkarma: Örnekleri ve desenleri çıkarmak için Klever sözleşmelerini ayrıştırma
🎯 Alaka Düzeyi Sıralaması: Bağlamın akıllı puanlanması ve sıralanması
🔄 Canlı Güncellemeler: Gerçek zamanlı olarak bağlam ekleyin ve güncelleyin
🛡️ Tür Güvenliği: Zod doğrulaması ile tam TypeScript
📚 Kapsamlı Bilgi Tabanı: Klever VM desenleri, en iyi uygulamalar ve örneklerle önceden yüklenmiş
🔧 Sözleşme Doğrulama: Yaygın sorunların ve anti-desenlerin otomatik tespiti
🚀 Dağıtım Betikleri: Sözleşme dağıtımı, yükseltme ve sorgulama için kullanıma hazır betikler

Hızlı Başlangıç

npx aracılığıyla anında kurun ve çalıştırın — klonlamaya gerek yok:

npx -y @klever/mcp-server

Veya barındırılan genel sunucuya bağlanın:

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

İstemciye özel yapılandırma için MCP İstemci Entegrasyonu bölümüne bakın.

Mimari

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

Yapılan Temel İyileştirmeler

Depolama Katmanı
- InMemoryStorage'da OOM'yi önlemek için bellek sınırları eklendi
- O(N) KEYS komutundan kaçınmak için Redis sorguları optimize edildi
- Redis işlemleri için atomik işlemler eklendi
- Hata işleme ve doğrulama iyileştirildi
API Güvenliği
- Tüm uç noktalar için girdi doğrulaması eklendi
- Toplu işlem boyutu sınırları
- Dahili bilgileri sızdırmayan uygun hata yanıtları
- Ortama duyarlı hata mesajları
Tür Güvenliği
- Merkezi şema doğrulaması
- Seçenekler için uygun TypeScript arayüzleri
- Depolanan verilerin çalışma zamanı doğrulaması
Performans
- Redis MGET kullanarak toplu işlemler
- Tam taramalar yerine dizin tabanlı sorgular
- Optimize edilmiş sayım işlemleri

Kurulum

Depoyu klonlayın:

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

Bağımlılıkları yükleyin:

pnpm install

Ortam yapılandırmasını kopyalayın:

cp .env.example .env

Klever SDK araçlarını yükleyin (işlemler için gereklidir):

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

Projeyi derleyin:

pnpm run build

Yapılandırma

Sunucuyu yapılandırmak için .env dosyasını düzenleyin:

# 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

MCP İstemci Entegrasyonu

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

claude_desktop_config.json dosyanıza ekleyin:

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

Ayrıntılı kurulum için Claude Desktop Kurulum Kılavuzu bölümüne bakın.

Cursor

Cursor MCP ayarlarınıza (.cursor/mcp.json) ekleyin:

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

VS Code (GitHub Copilot)

Projenizdeki .vscode/mcp.json dosyasına ekleyin:

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

Ayrıntılı kurulum için VS Code Kurulum Kılavuzu bölümüne bakın.

Genel MCP Sunucusu

Klever MCP Sunucusu, herhangi bir geliştiricinin yerel olarak çalıştırmadan bağlanmasına olanak tanıyan genel bir paylaşılan hizmet olarak barındırılabilir.

Genel Sunucuya Bağlanma

# 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

Kullanılabilir Araçlar (Genel Mod)

Genel sunucu, güvenlik için salt okunur bir araç alt kümesi sunar:

Araç	Açıklama
`query_context`	Klever VM bilgi tabanında arama yapın
`get_context`	Kimliğe göre belirli bir bağlamı alın
`find_similar`	Verilen bir bağlama benzer bağlamları bulun
`get_knowledge_stats`	Bilgi tabanı istatistiklerini alın
`enhance_with_context`	Sorguları ilgili Klever VM bağlamıyla zenginleştirin

Yazma işlemleri (add_context) ve kabuk tabanlı araçlar (init_klever_project, add_helper_scripts) genel modda devre dışıdır.

Docker ile Kendi Kendine Barındırma

# 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

Ardından bağlanın:

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

Docker Olmadan Kendi Kendine Barındırma

pnpm install
pnpm run build
pnpm run start:public

Ortam Değişkenleri (Genel Mod)

Değişken	Varsayılan	Açıklama
`MODE`	`http`	Barındırılan mod için `public` olarak ayarlayın
`PORT`	`3000`	Sunucu portu
`CORS_ORIGINS`	(ayarlanmamış)	Virgülle ayrılmış izin verilen kaynaklar. Ayarlanmamış veya `*` tüm kaynaklara izin verir
`RATE_LIMIT_MCP`	`60`	IP başına MCP uç noktası istek/dk
`RATE_LIMIT_API`	`30`	IP başına API uç noktası istek/dk
`BODY_SIZE_LIMIT`	`1mb`	Maksimum istek gövdesi boyutu

Dağıtım Notları

mcp.klever.org adresinde üretim için:

TLS sonlandırma için Docker konteynerini bir ters proxy (nginx/Caddy/bulut LB) arkasına dağıtın
Proxy'nin mcp-session-id başlığını ilettiğinden ve SSE'yi desteklediğinden emin olun (yanıt tamponlamayı devre dışı bırakın)
Sunucu bellek içi bilgi tabanıyla salt okunur olduğundan tek örnek yeterlidir
DDoS koruması için Cloudflare düşünün (SSE desteklenir)

Kullanım

Bilgi Tabanı Yükleme

Sunucu, depolama türünüze bağlı olarak Klever bilgi tabanını otomatik olarak yükler:

Bellek Depolama (Varsayılan)

Bilgi, sunucu başladığında otomatik olarak yüklenir
pnpm run ingest ayrıca çalıştırmaya gerek yoktur
Veriler yalnızca sunucu çalışırken var olur
Geliştirme ve test için en iyisidir

Redis Depolama

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

# Then start the server
pnpm run dev

Bilgi Redis veritabanında kalıcıdır
Sunucu yeniden başlatmalarında hayatta kalır
Üretim kullanımı için en iyisidir

Bu şunları yükleyecektir:

Akıllı sözleşme şablonları ve örnekleri
Ek açıklama kuralları ve en iyi uygulamalar
Depolama eşleyici desenleri ve karşılaştırmaları
Dağıtım ve sorgu betikleri
Yaygın hatalar ve çözümler
Test desenleri
API referans dokümantasyonu

HTTP Sunucusu Olarak Çalıştırma

# Development mode
pnpm run dev

# Production mode
pnpm run build && pnpm start

HTTP API'si http://localhost:3000/api adresinde kullanılabilir olacaktır

MCP Sunucusu Olarak Çalıştırma

MODE=mcp pnpm start

Herhangi bir MCP uyumlu istemciyle kullanın.

API Uç Noktaları

POST `/api/context`

Sisteme yeni bağlam ekleyin.

{
  "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`

Kimliğe göre belirli bağlamı alın.

POST `/api/context/query`

Filtrelerle bağlamları sorgulayın.

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

PUT `/api/context/:id`

Mevcut bağlamı güncelleyin.

DELETE `/api/context/:id`

Bağlamı silin.

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

Benzer bağlamları bulun.

POST `/api/context/batch`

Birden çok bağlamı toplu olarak ekleyin.

MCP Araçları

MCP sunucusu olarak çalışırken aşağıdaki araçlar kullanılabilir:

query_context: İlgili Klever geliştirme bağlamını arayın
add_context: Bilgi tabanına yeni bağlam ekleyin
get_context: Kimliğe göre belirli bağlamı alın
find_similar: Verilen bir bağlama benzer bağlamları bulun
get_knowledge_stats: Bilgi tabanı hakkında istatistikler alın
init_klever_project: Yardımcı betiklerle yeni bir Klever akıllı sözleşme projesi başlatın
enhance_with_context: Sorguları ilgili Klever VM bağlamıyla otomatik olarak zenginleştirin

Bağlam Türleri

code_example: Çalışan kod parçacıkları ve örnekler (Rust akıllı sözleşme kodu)
best_practice: Önerilen desenler ve uygulamalar
security_tip: Güvenlik hususları ve uyarılar
optimization: Performans optimizasyon teknikleri
documentation: Genel dokümantasyon ve kılavuzlar
error_pattern: Yaygın hatalar ve çözümler
deployment_tool: Dağıtım betikleri ve yardımcı programlar (bash betikleri, araçlar)
runtime_behavior: Çalışma zamanı davranış açıklamaları

Önceden Yüklenmiş Bilgi Tabanı

MCP sunucusu, 11 kategoride düzenlenmiş 95'ten fazla giriş içeren kapsamlı bir bilgi tabanı içerir:

Kritik Desenler

Ödeme işleme ve token işlemleri
Ondalık dönüşümler ve hesaplamalar
Olay yayma ve parametre kuralları
CLI aracı kullanımı ve en iyi uygulamalar

Sözleşme Desenleri ve Örnekleri

Temel sözleşme yapısı şablonları
Tam piyango oyunu uygulaması
Ödüllü staking sözleşmesi
Çapraz sözleşme iletişim desenleri
Uzak depolama erişim desenleri
Token eşleyici yardımcı modülleri

Geliştirme Araçları

Koperator: Argüman kodlaması ile tam CLI referansı
KSC: Derleme komutları ve proje kurulumu
Dağıtım, yükseltme ve sorgu betikleri
Etkileşimli sözleşme yönetim araçları
Ortak yardımcı program kütüphanesi (bech32, ağ yönetimi)

Depolama ve Optimizasyon

Performans karşılaştırmaları ile depolama eşleyici seçim kılavuzu
Ad alanı organizasyon desenleri
Verimli sorgular için görünüm uç noktaları
Gaz optimizasyon teknikleri
OptionalValue vs Option desenleri

En İyi Uygulamalar ve Güvenlik

Girdi doğrulama desenleri
Hata işleme stratejileri
Admin ve duraklatma modülü kullanımı
Erişim kontrol desenleri
Yaygın hatalar ve çözümler

Sözleşmeleri Ekleme

Klever sözleşmelerini ayrıştırmak ve içe aktarmak için yerleşik ekleme yardımcı programlarını kullanın:

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();

Geliştirme

# 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

Sözleşme Doğrulama

Sunucu, Klever sözleşmelerini otomatik olarak doğrulayabilir ve sorunları tespit edebilir:

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

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

Doğrulama kontrolleri şunları içerir:

Olay ek açıklama formatı (çift tırnak, camelCase)
Yönetilen tür API parametreleri
Transferlerde sıfır adres doğrulaması
Optimum depolama eşleyici seçimi
Modül adlandırma kuralları

Örnek Kullanım Durumları

1. Akıllı Sözleşme Geliştirme Asistanı

Klever sözleşme geliştirme için bağlama duyarlı öneriler sağlamak üzere IDE'nizle entegre edin.

2. Kod İnceleme Aracı

Sözleşmeleri en iyi uygulamalara ve güvenlik desenlerine göre otomatik olarak kontrol edin.

3. Öğrenme Platformu

Klever geliştirmeyi öğrenen geliştiriciler için örnekler ve açıklamalar sağlayın.

4. Dokümantasyon Oluşturucu

Sözleşme dokümantasyonunu otomatik olarak çıkarın ve düzenleyin.

Proje Spesifikasyonları ve Örnekler

Tam proje uygulama örnekleri ve spesifikasyonları için bakınız:

Proje Spesifikasyon Şablonu - Klever akıllı sözleşme projelerini belirtmek için doldurulabilir bir şablon. Yapay zeka asistanlarını MCP bilgi keşfi, görev takibi ve aşamalı uygulama boyunca yönlendirir. Bir KleverDice örneği içerir.

Proje Başlatma

MCP sunucusu, gerekli tüm yardımcı betiklerle yeni bir Klever akıllı sözleşme projesi oluşturan güçlü bir proje başlatma aracı içerir.

init_klever_project Aracını Kullanma

MCP aracılığıyla bağlandığında init_klever_project aracını kullanın:

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

Parametreler:

name (gerekli): Sözleşmenizin adı
template (isteğe bağlı): Kullanılacak şablon (varsayılan: "empty")
noMove (isteğe bağlı): true ise projeyi alt dizinde tutar (varsayılan: false)

Oluşturulan Yardımcı Betikler

Araç, scripts/ dizininde aşağıdaki betikleri oluşturur:

build.sh: Akıllı sözleşmeyi derler
deploy.sh: Sözleşme yapıtlarının otomatik tespiti ile Klever testnet'e dağıtır
upgrade.sh: Mevcut sözleşmeyi yükseltir (history.json'dan otomatik tespit)
query.sh: Uygun kodlama/kod çözme ile sözleşme uç noktalarını sorgular
test.sh: Sözleşme testlerini çalıştırır
interact.sh: Kullanım örneklerini ve kullanılabilir komutları gösterir

Örnek İş Akışı

Projeyi başlatın:

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

Sözleşmeyi derleyin:
```
./scripts/build.sh
```
Testnet'e dağıtın:
```
./scripts/deploy.sh
```

Sözleşmeyi sorgulayın:

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

Sözleşmeyi yükseltin:
```
./scripts/upgrade.sh
```

Tüm dağıtım geçmişi, kolay başvuru için output/history.json dosyasında izlenir.

Otomatik Bağlam Zenginleştirme

MCP sunucusu, sorguları ilgili Klever VM bağlamıyla otomatik olarak zenginleştirebilir. Bu, MCP istemcinizin her zaman en alakalı bilgilere erişmesini sağlar.

Bağlam Zenginleştirmeyi Kullanma

Herhangi bir sorguya otomatik olarak ilgili bağlam eklemek için enhance_with_context aracını kullanın:

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

Bu şunları yapacaktır:

Sorgudan ilgili anahtar kelimeleri çıkarın
Eşleşen bağlamlar için bilgi tabanında arama yapın
Bağlam dahil edilmiş zenginleştirilmiş bir sorgu döndürün
Ne bulunduğu hakkında meta veri sağlayın

Entegrasyon Deseni

Her zaman önce Klever bağlamını kontrol etmek isteyen MCP istemcileri için:

// 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
}

Bağlam zenginleştirme özelliği, sorguları kapsamlı bilgi tabanından ilgili Klever VM bilgisiyle otomatik olarak zenginleştirir.

Entegrasyon Örnekleri

VS Code Eklentisi

// 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'
  })
});

CLI Aracı

# 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"]
    }
  }'

Katkıda Bulunma

Katkılarınızı bekliyoruz! Lütfen:

Depoyu çatallayın (fork)
Bir özellik dalı (feature branch) oluşturun
Değişikliklerinizi yapın
Testleri ekleyin
Bir çekme isteği (pull request) gönderin

Lisans

MIT Lisansı - ayrıntılar için LICENSE dosyasına bakın

Teşekkürler

Context7 by Upstash tarafından ilham alınmıştır
Klever Blockchain için geliştirilmiştir
Klever VM SDK (Rust) kullanır