Klever VM MCP Server

offiziell

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

Dokumentation

Klever VM MCP-Server

Ein Model Context Protocol (MCP)-Server, zugeschnitten auf die Entwicklung von Klever-Blockchain-Smart-Contracts. Dieser Server pflegt und stellt kontextuelles Wissen bereit, einschließlich Code-Mustern, Best Practices und Laufzeitverhalten für Entwickler, die mit dem Klever VM SDK arbeiten.

Funktionen

🚀 Dreifacher Betriebsmodus: Ausführung als HTTP-API-Server, MCP-stdio-Server oder öffentlich gehosteter MCP-Server
💾 Flexible Speicherung: In-Memory- oder Redis-Backend-Unterstützung
🔍 Intelligente Kontextabfrage: Abfrage nach Typ, Tags oder Vertragstyp
📝 Automatische Musterextraktion: Klever-Verträge parsen, um Beispiele und Muster zu extrahieren
🎯 Relevanzbewertung: Intelligentes Scoring und Ranking von Kontext
🔄 Live-Updates: Kontext in Echtzeit hinzufügen und aktualisieren
🛡️ Typsicherheit: Vollständiges TypeScript mit Zod-Validierung
📚 Umfassende Wissensdatenbank: Vorgeladen mit Klever VM-Mustern, Best Practices und Beispielen
🔧 Vertragsvalidierung: Automatische Erkennung häufiger Probleme und Anti-Patterns
🚀 Deployment-Skripte: Einsatzbereite Skripte für Vertragsbereitstellung, -upgrade und -abfragen

Schnellstart

Installation und Ausführung sofort über npx – kein Klonen erforderlich:

npx -y @klever/mcp-server

Oder verbinden Sie sich mit dem gehosteten öffentlichen Server:

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

Siehe MCP-Client-Integration für clientspezifische Konfiguration.

Architektur

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

Wichtige vorgenommene Verbesserungen

Speicherschicht
- Speicherlimits hinzugefügt, um OOM in InMemoryStorage zu verhindern
- Redis-Abfragen optimiert, um O(N) KEYS-Befehl zu vermeiden
- Atomare Transaktionen für Redis-Operationen hinzugefügt
- Verbesserte Fehlerbehandlung und Validierung
API-Sicherheit
- Eingabevalidierung für alle Endpunkte hinzugefügt
- Größenbeschränkungen für Stapeloperationen
- Ordnungsgemäße Fehlerantworten ohne Preisgabe interner Details
- Umgebungsabhängige Fehlermeldungen
Typsicherheit
- Zentralisierte Schema-Validierung
- Ordnungsgemäße TypeScript-Schnittstellen für Optionen
- Laufzeitvalidierung gespeicherter Daten
Leistung
- Stapeloperationen mit Redis MGET
- Indexbasierte Abfragen statt vollständiger Scans
- Optimierte Zähloperationen

Installation

Repository klonen:

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

Abhängigkeiten installieren:

pnpm install

Umgebungskonfiguration kopieren:

cp .env.example .env

Klever SDK-Tools installieren (erforderlich für Transaktionen):

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

Projekt bauen:

pnpm run build

Konfiguration

Bearbeiten Sie die Datei .env, um den Server zu konfigurieren:

# 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-Client-Integration

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

Zu Ihrer claude_desktop_config.json hinzufügen:

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

Für detaillierte Einrichtung siehe Claude Desktop-Installationsanleitung.

Cursor

Zu Ihren Cursor MCP-Einstellungen hinzufügen (.cursor/mcp.json):

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

VS Code (GitHub Copilot)

Zu .vscode/mcp.json in Ihrem Projekt hinzufügen:

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

Für detaillierte Einrichtung siehe VS Code-Installationsanleitung.

Öffentlicher MCP-Server

Der Klever MCP-Server kann als öffentlicher, gemeinsam genutzter Dienst gehostet werden, sodass sich jeder Entwickler verbinden kann, ohne ihn lokal auszuführen.

Verbindung zum öffentlichen Server

# 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

Verfügbare Tools (Öffentlicher Modus)

Der öffentliche Server stellt aus Sicherheitsgründen eine schreibgeschützte Teilmenge der Tools bereit:

Tool	Beschreibung
`query_context`	Die Klever VM-Wissensdatenbank durchsuchen
`get_context`	Einen bestimmten Kontext anhand der ID abrufen
`find_similar`	Ähnliche Kontexte zu einem gegebenen Kontext finden
`get_knowledge_stats`	Statistiken zur Wissensdatenbank abrufen
`enhance_with_context`	Abfragen mit relevantem Klever VM-Kontext anreichern

Schreiboperationen (add_context) und Shell-basierte Tools (init_klever_project, add_helper_scripts) sind im öffentlichen Modus deaktiviert.

Self-Hosting mit 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

Dann verbinden:

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

Self-Hosting ohne Docker

pnpm install
pnpm run build
pnpm run start:public

Umgebungsvariablen (Öffentlicher Modus)

Variable	Standard	Beschreibung
`MODE`	`http`	Auf `public` für gehosteten Modus setzen
`PORT`	`3000`	Server-Port
`CORS_ORIGINS`	(nicht gesetzt)	Kommagetrennte erlaubte Ursprünge. Nicht gesetzt oder `*` erlaubt alle Ursprünge
`RATE_LIMIT_MCP`	`60`	MCP-Endpunkt-Anfragen/min pro IP
`RATE_LIMIT_API`	`30`	API-Endpunkt-Anfragen/min pro IP
`BODY_SIZE_LIMIT`	`1mb`	Maximale Anfrage-Body-Größe

Bereitstellungshinweise

Für Produktion unter mcp.klever.org:

Docker-Container hinter einem Reverse-Proxy (nginx/Caddy/Cloud-LB) für TLS-Terminierung bereitstellen
Sicherstellen, dass der Proxy den mcp-session-id-Header weitergibt und SSE unterstützt (Antwortpufferung deaktivieren)
Eine einzelne Instanz ist ausreichend, da der Server schreibgeschützt mit einer In-Memory-Wissensdatenbank ist
Cloudflare für DDoS-Schutz in Betracht ziehen (SSE wird unterstützt)

Verwendung

Laden der Wissensdatenbank

Der Server lädt die Klever-Wissensdatenbank automatisch basierend auf Ihrem Speichertyp:

Speichertyp Memory (Standard)

Wissen wird automatisch geladen, wenn der Server startet
Kein separater Aufruf von pnpm run ingest erforderlich
Daten existieren nur, solange der Server läuft
Am besten für Entwicklung und Tests geeignet

Speichertyp Redis

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

# Then start the server
pnpm run dev

Wissen bleibt in der Redis-Datenbank erhalten
Übersteht Server-Neustarts
Am besten für den Produktionseinsatz geeignet

Dies lädt:

Smart-Contract-Vorlagen und Beispiele
Anmerkungsregeln und Best Practices
Storage-Mapper-Muster und Vergleiche
Bereitstellungs- und Abfrageskripte
Häufige Fehler und Lösungen
Testmuster
API-Referenzdokumentation

Ausführung als HTTP-Server

# Development mode
pnpm run dev

# Production mode
pnpm run build && pnpm start

Die HTTP-API ist unter http://localhost:3000/api verfügbar.

Ausführung als MCP-Server

MODE=mcp pnpm start

Verwendung mit jedem MCP-kompatiblen Client.

API-Endpunkte

POST `/api/context`

Neuen Kontext in das System aufnehmen.

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

Bestimmten Kontext anhand der ID abrufen.

POST `/api/context/query`

Kontexte mit Filtern abfragen.

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

PUT `/api/context/:id`

Vorhandenen Kontext aktualisieren.

DELETE `/api/context/:id`

Kontext löschen.

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

Ähnliche Kontexte finden.

POST `/api/context/batch`

Mehrere Kontexte als Stapel aufnehmen.

MCP-Tools

Bei Ausführung als MCP-Server stehen die folgenden Tools zur Verfügung:

query_context: Nach relevantem Klever-Entwicklungskontext suchen
add_context: Neuen Kontext zur Wissensdatenbank hinzufügen
get_context: Bestimmten Kontext anhand der ID abrufen
find_similar: Ähnliche Kontexte zu einem gegebenen Kontext finden
get_knowledge_stats: Statistiken zur Wissensdatenbank abrufen
init_klever_project: Ein neues Klever-Smart-Contract-Projekt mit Hilfsskripten initialisieren
enhance_with_context: Abfragen automatisch mit relevantem Klever VM-Kontext anreichern

Kontexttypen

code_example: Funktionierende Code-Snippets und Beispiele (Rust-Smart-Contract-Code)
best_practice: Empfohlene Muster und Praktiken
security_tip: Sicherheitsüberlegungen und Warnungen
optimization: Techniken zur Leistungsoptimierung
documentation: Allgemeine Dokumentation und Anleitungen
error_pattern: Häufige Fehler und Lösungen
deployment_tool: Bereitstellungsskripte und Dienstprogramme (Bash-Skripte, Tools)
runtime_behavior: Erklärungen zum Laufzeitverhalten

Vorgeladene Wissensdatenbank

Der MCP-Server enthält eine umfassende Wissensdatenbank mit über 95 Einträgen, organisiert in 11 Kategorien:

Kritische Muster

Zahlungsabwicklung und Token-Operationen
Dezimalkonvertierungen und Berechnungen
Ereignisausgabe und Parameterregeln
CLI-Tool-Nutzung und Best Practices

Vertragsmuster & Beispiele

Grundlegende Vertragsstrukturvorlagen
Vollständige Lotteriespiel-Implementierung
Staking-Vertrag mit Belohnungen
Muster für vertragsübergreifende Kommunikation
Muster für entfernten Speicherzugriff
Token-Mapper-Hilfsmodule

Entwicklungstools

Koperator: Vollständige CLI-Referenz mit Argumentkodierung
KSC: Build-Befehle und Projekteinrichtung
Bereitstellungs-, Upgrade- und Abfrageskripte
Interaktive Vertragsverwaltungstools
Allgemeine Dienstprogrammbibliothek (bech32, Netzwerkverwaltung)

Speicher & Optimierung

Auswahlhilfe für Storage-Mapper mit Leistungsvergleichen
Muster für Namespace-Organisation
View-Endpunkte für effiziente Abfragen
Techniken zur Gas-Optimierung
OptionalValue vs. Option-Muster

Best Practices & Sicherheit

Muster zur Eingabevalidierung
Strategien zur Fehlerbehandlung
Verwendung von Admin- und Pause-Modulen
Muster zur Zugriffskontrolle
Häufige Fehler und Lösungen

Verträge aufnehmen

Verwenden Sie die integrierten Aufnahme-Dienstprogramme, um Klever-Verträge zu parsen und zu importieren:

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

Entwicklung

# 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

Vertragsvalidierung

Der Server kann Klever-Verträge automatisch validieren und Probleme erkennen:

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

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

Validierungsprüfungen umfassen:

Ereignisanmerkungsformat (doppelte Anführungszeichen, camelCase)
Verwaltete Typ-API-Parameter
Nulladressenvalidierung bei Überweisungen
Optimale Storage-Mapper-Auswahl
Modulbenennungskonventionen

Beispielanwendungsfälle

1. Assistent für Smart-Contract-Entwicklung

Integration in Ihre IDE, um kontextbezogene Vorschläge für die Klever-Vertragsentwicklung bereitzustellen.

2. Code-Review-Tool

Verträge automatisch anhand von Best Practices und Sicherheitsmustern überprüfen.

3. Lernplattform

Beispiele und Erklärungen für Entwickler bereitstellen, die die Klever-Entwicklung erlernen.

4. Dokumentationsgenerator

Vertragsdokumentation automatisch extrahieren und organisieren.

Projektspezifikationen und Beispiele

Für vollständige Projektimplementierungsbeispiele und -spezifikationen siehe:

Projektspezifikationsvorlage - Eine ausfüllbare Vorlage zur Spezifikation von Klever-Smart-Contract-Projekten. Führt KI-Assistenten durch MCP-Wissensentdeckung, Aufgabenverfolgung und phasenweise Implementierung. Enthält ein KleverDice-Beispiel.

Projektinitialisierung

Der MCP-Server enthält ein leistungsstarkes Projektinitialisierungstool, das ein neues Klever-Smart-Contract-Projekt mit allen notwendigen Hilfsskripten erstellt.

Verwendung des init_klever_project-Tools

Bei Verbindung über MCP verwenden Sie das init_klever_project-Tool:

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

Parameter:

name (erforderlich): Der Name Ihres Vertrags
template (optional): Zu verwendende Vorlage (Standard: "empty")
noMove (optional): Wenn true, wird das Projekt im Unterverzeichnis behalten (Standard: false)

Generierte Hilfsskripte

Das Tool erstellt die folgenden Skripte im Verzeichnis scripts/:

build.sh: Baut den Smart Contract
deploy.sh: Stellt im Klever-Testnetz mit automatischer Erkennung von Vertragsartefakten bereit
upgrade.sh: Aktualisiert bestehenden Vertrag (automatische Erkennung aus history.json)
query.sh: Fragt Vertragsendpunkte mit ordnungsgemäßer Kodierung/Dekodierung ab
test.sh: Führt Vertragstests aus
interact.sh: Zeigt Verwendungsbeispiele und verfügbare Befehle

Beispiel-Workflow

Projekt initialisieren:

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

Vertrag bauen:
```
./scripts/build.sh
```
Im Testnetz bereitstellen:
```
./scripts/deploy.sh
```

Vertrag abfragen:

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

Vertrag aktualisieren:
```
./scripts/upgrade.sh
```

Der gesamte Bereitstellungsverlauf wird zur einfachen Referenz in output/history.json verfolgt.

Automatische Kontextanreicherung

Der MCP-Server kann Abfragen automatisch mit relevantem Klever VM-Kontext anreichern. Dies stellt sicher, dass Ihr MCP-Client immer Zugriff auf die relevantesten Informationen hat.

Verwendung der Kontextanreicherung

Verwenden Sie das enhance_with_context-Tool, um automatisch relevanten Kontext zu jeder Abfrage hinzuzufügen:

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

Dies wird:

Relevante Schlüsselwörter aus der Abfrage extrahieren
Die Wissensdatenbank nach passenden Kontexten durchsuchen
Eine angereicherte Abfrage mit enthaltenem Kontext zurückgeben
Metadaten darüber bereitstellen, was gefunden wurde

Integrationsmuster

Für MCP-Clients, die immer zuerst den Klever-Kontext prüfen möchten:

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

Die Kontextanreicherungsfunktion reichert Abfragen automatisch mit relevantem Klever VM-Wissen aus der umfassenden Wissensdatenbank an.

Integrationsbeispiele

VS Code-Erweiterung

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

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

Mitwirken

Beiträge sind willkommen! Bitte:

Forken Sie das Repository
Erstellen Sie einen Feature-Branch
Nehmen Sie Ihre Änderungen vor
Fügen Sie Tests hinzu
Reichen Sie einen Pull-Request ein

Lizenz

MIT-Lizenz – siehe LICENSE-Datei für Details

Danksagungen

Inspiriert von Context7 by Upstash
Entwickelt für die Klever Blockchain
Verwendet das Klever VM SDK (Rust)