Klever VM MCP Server

officiel

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

Documentation

Serveur MCP Klever VM

Un serveur Model Context Protocol (MCP) conçu pour le développement de smart contracts sur la blockchain Klever. Ce serveur maintient et fournit des connaissances contextuelles, incluant des modèles de code, des bonnes pratiques et le comportement à l'exécution pour les développeurs travaillant avec le SDK Klever VM.

Fonctionnalités

🚀 Fonctionnement en triple mode : Exécution en tant que serveur API HTTP, serveur MCP stdio ou serveur MCP public hébergé
💾 Stockage flexible : Support backend en mémoire ou Redis
🔍 Récupération intelligente du contexte : Requête par type, tags ou type de contrat
📝 Extraction automatique de modèles : Analyse des contrats Klever pour extraire des exemples et des modèles
🎯 Classement par pertinence : Notation et classement intelligents du contexte
🔄 Mises à jour en direct : Ajout et mise à jour du contexte en temps réel
🛡️ Sécurité de type : TypeScript complet avec validation Zod
📚 Base de connaissances complète : Préchargée avec des modèles, bonnes pratiques et exemples Klever VM
🔧 Validation de contrat : Détection automatique des problèmes courants et des anti-modèles
🚀 Scripts de déploiement : Scripts prêts à l'emploi pour le déploiement, la mise à niveau et l'interrogation des contrats

Démarrage rapide

Installez et exécutez instantanément via npx — aucun clonage requis :

npx -y @klever/mcp-server

Ou connectez-vous au serveur public hébergé :

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

Voir Intégration client MCP pour la configuration spécifique au client.

Architecture

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

Principales améliorations apportées

Couche de stockage
- Ajout de limites de mémoire pour éviter les OOM dans InMemoryStorage
- Optimisation des requêtes Redis pour éviter la commande KEYS O(N)
- Ajout de transactions atomiques pour les opérations Redis
- Amélioration de la gestion des erreurs et de la validation
Sécurité de l'API
- Ajout de la validation des entrées pour tous les endpoints
- Limites de taille des opérations par lot
- Réponses d'erreur appropriées sans fuite d'informations internes
- Messages d'erreur adaptés à l'environnement
Sécurité de type
- Validation centralisée des schémas
- Interfaces TypeScript appropriées pour les options
- Validation à l'exécution des données stockées
Performance
- Opérations par lot utilisant Redis MGET
- Requêtes basées sur des index au lieu de scans complets
- Optimisation des opérations de comptage

Installation

Cloner le dépôt :

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

Installer les dépendances :

pnpm install

Copier la configuration d'environnement :

cp .env.example .env

Installer les outils SDK Klever (nécessaires pour les transactions) :

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

Construire le projet :

pnpm run build

Configuration

Modifier le fichier .env pour configurer le serveur :

# 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

Intégration client 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

Ajouter à votre claude_desktop_config.json :

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

Pour une configuration détaillée, voir le Guide d'installation Claude Desktop.

Cursor

Ajouter à vos paramètres Cursor MCP (.cursor/mcp.json) :

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

VS Code (GitHub Copilot)

Ajouter à .vscode/mcp.json dans votre projet :

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

Pour une configuration détaillée, voir le Guide d'installation VS Code.

Serveur MCP public

Le serveur MCP Klever peut être hébergé en tant que service public partagé, permettant à tout développeur de se connecter sans l'exécuter localement.

Connexion au serveur public

# 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

Outils disponibles (Mode public)

Le serveur public expose un sous-ensemble d'outils en lecture seule pour des raisons de sécurité :

Outil	Description
`query_context`	Rechercher dans la base de connaissances Klever VM
`get_context`	Récupérer un contexte spécifique par ID
`find_similar`	Trouver des contextes similaires à un contexte donné
`get_knowledge_stats`	Obtenir des statistiques sur la base de connaissances
`enhance_with_context`	Améliorer les requêtes avec le contexte Klever VM pertinent

Les opérations d'écriture (add_context) et les outils basés sur le shell (init_klever_project, add_helper_scripts) sont désactivés en mode public.

Auto-hébergement avec 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

Puis connecter :

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

Auto-hébergement sans Docker

pnpm install
pnpm run build
pnpm run start:public

Variables d'environnement (Mode public)

Variable	Défaut	Description
`MODE`	`http`	Définir à `public` pour le mode hébergé
`PORT`	`3000`	Port du serveur
`CORS_ORIGINS`	(non défini)	Origines autorisées séparées par des virgules. Non défini ou `*` autorise toutes les origines
`RATE_LIMIT_MCP`	`60`	Requêtes endpoint MCP/min par IP
`RATE_LIMIT_API`	`30`	Requêtes endpoint API/min par IP
`BODY_SIZE_LIMIT`	`1mb`	Taille maximale du corps de la requête

Notes de déploiement

Pour la production sur mcp.klever.org :

Déployer le conteneur Docker derrière un proxy inverse (nginx/Caddy/cloud LB) pour la terminaison TLS
S'assurer que le proxy transmet l'en-tête mcp-session-id et prend en charge SSE (désactiver la mise en mémoire tampon des réponses)
Une seule instance est suffisante car le serveur est en lecture seule avec une base de connaissances en mémoire
Envisager Cloudflare pour la protection DDoS (SSE est pris en charge)

Utilisation

Chargement de la base de connaissances

Le serveur charge automatiquement la base de connaissances Klever en fonction de votre type de stockage :

Stockage mémoire (Défaut)

La connaissance est automatiquement chargée au démarrage du serveur
Pas besoin d'exécuter pnpm run ingest séparément
Les données existent uniquement pendant l'exécution du serveur
Idéal pour le développement et les tests

Stockage Redis

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

# Then start the server
pnpm run dev

La connaissance persiste dans la base de données Redis
Survit aux redémarrages du serveur
Idéal pour la production

Cela chargera :

Des modèles et exemples de smart contracts
Des règles d'annotation et bonnes pratiques
Des modèles de mappeurs de stockage et comparaisons
Des scripts de déploiement et d'interrogation
Des erreurs courantes et solutions
Des modèles de test
De la documentation de référence API

Exécution en tant que serveur HTTP

# Development mode
pnpm run dev

# Production mode
pnpm run build && pnpm start

L'API HTTP sera disponible sur http://localhost:3000/api

Exécution en tant que serveur MCP

MODE=mcp pnpm start

Utiliser avec n'importe quel client compatible MCP.

Endpoints API

POST `/api/context`

Ingérer un nouveau contexte dans le système.

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

Récupérer un contexte spécifique par ID.

POST `/api/context/query`

Interroger les contextes avec des filtres.

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

PUT `/api/context/:id`

Mettre à jour un contexte existant.

DELETE `/api/context/:id`

Supprimer un contexte.

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

Trouver des contextes similaires.

POST `/api/context/batch`

Ingérer par lot plusieurs contextes.

Outils MCP

Lors de l'exécution en tant que serveur MCP, les outils suivants sont disponibles :

query_context : Rechercher un contexte de développement Klever pertinent
add_context : Ajouter un nouveau contexte à la base de connaissances
get_context : Récupérer un contexte spécifique par ID
find_similar : Trouver des contextes similaires à un contexte donné
get_knowledge_stats : Obtenir des statistiques sur la base de connaissances
init_klever_project : Initialiser un nouveau projet de smart contract Klever avec des scripts d'aide
enhance_with_context : Améliorer automatiquement les requêtes avec le contexte Klever VM pertinent

Types de contexte

code_example : Extraits de code fonctionnels et exemples (code de smart contract Rust)
best_practice : Modèles et pratiques recommandés
security_tip : Considérations de sécurité et avertissements
optimization : Techniques d'optimisation des performances
documentation : Documentation générale et guides
error_pattern : Erreurs courantes et solutions
deployment_tool : Scripts de déploiement et utilitaires (scripts bash, outils)
runtime_behavior : Explications du comportement à l'exécution

Base de connaissances préchargée

Le serveur MCP inclut une base de connaissances complète avec plus de 95 entrées organisées en 11 catégories :

Modèles critiques

Gestion des paiements et opérations sur les tokens
Conversions décimales et calculs
Règles d'émission d'événements et de paramètres
Utilisation des outils CLI et bonnes pratiques

Modèles de contrat et exemples

Modèles de structure de contrat de base
Implémentation complète d'un jeu de loterie
Contrat de staking avec récompenses
Modèles de communication inter-contrats
Modèles d'accès au stockage distant
Modules d'aide au mappage de tokens

Outils de développement

Koperator : Référence CLI complète avec encodage des arguments
KSC : Commandes de construction et configuration de projet
Scripts de déploiement, mise à niveau et interrogation
Outils interactifs de gestion de contrat
Bibliothèque d'utilitaires communs (bech32, gestion de réseau)

Stockage et optimisation

Guide de sélection des mappeurs de stockage avec comparaisons de performances
Modèles d'organisation des espaces de noms
Endpoints de vue pour des requêtes efficaces
Techniques d'optimisation du gaz
Modèles OptionalValue vs Option

Bonnes pratiques et sécurité

Modèles de validation des entrées
Stratégies de gestion des erreurs
Utilisation des modules admin et pause
Modèles de contrôle d'accès
Erreurs courantes et solutions

Ingestion de contrats

Utiliser les utilitaires d'ingestion intégrés pour analyser et importer des contrats 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();

Développement

# 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

Validation de contrat

Le serveur peut valider automatiquement les contrats Klever et détecter les problèmes :

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

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

Les vérifications de validation incluent :

Format d'annotation d'événement (guillemets doubles, camelCase)
Paramètres d'API de type managé
Validation d'adresse zéro dans les transferts
Sélection optimale du mappeur de stockage
Conventions de nommage des modules

Exemples de cas d'utilisation

1. Assistant de développement de smart contract

Intégrer avec votre IDE pour fournir des suggestions contextuelles pour le développement de contrats Klever.

2. Outil de revue de code

Vérifier automatiquement les contrats par rapport aux bonnes pratiques et aux modèles de sécurité.

3. Plateforme d'apprentissage

Fournir des exemples et des explications pour les développeurs apprenant le développement Klever.

4. Générateur de documentation

Extraire et organiser automatiquement la documentation des contrats.

Spécifications du projet et exemples

Pour des exemples complets d'implémentation de projet et des spécifications, voir :

Modèle de spécification de projet - Un modèle à remplir pour spécifier des projets de smart contract Klever. Guide les assistants IA à travers la découverte de connaissances MCP, le suivi des tâches et l'implémentation par phases. Inclut un exemple KleverDice.

Initialisation de projet

Le serveur MCP inclut un outil puissant d'initialisation de projet qui crée un nouveau projet de smart contract Klever avec tous les scripts d'aide nécessaires.

Utilisation de l'outil init_klever_project

Lors de la connexion via MCP, utiliser l'outil init_klever_project :

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

Paramètres :

name (requis) : Le nom de votre contrat
template (optionnel) : Modèle à utiliser (défaut : "empty")
noMove (optionnel) : Si vrai, conserve le projet dans un sous-répertoire (défaut : false)

Scripts d'aide générés

L'outil crée les scripts suivants dans le répertoire scripts/ :

build.sh : Construit le smart contract
deploy.sh : Déploie sur le testnet Klever avec détection automatique des artefacts du contrat
upgrade.sh : Met à niveau un contrat existant (détection automatique depuis history.json)
query.sh : Interroge les endpoints du contrat avec un encodage/décodage approprié
test.sh : Exécute les tests du contrat
interact.sh : Affiche des exemples d'utilisation et les commandes disponibles

Exemple de flux de travail

Initialiser le projet :

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

Construire le contrat :
```
./scripts/build.sh
```
Déployer sur le testnet :
```
./scripts/deploy.sh
```

Interroger le contrat :

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

Mettre à niveau le contrat :
```
./scripts/upgrade.sh
```

Tout l'historique de déploiement est suivi dans output/history.json pour une référence facile.

Amélioration automatique du contexte

Le serveur MCP peut automatiquement améliorer les requêtes avec le contexte Klever VM pertinent. Cela garantit que votre client MCP a toujours accès aux informations les plus pertinentes.

Utilisation de l'amélioration de contexte

Utiliser l'outil enhance_with_context pour ajouter automatiquement un contexte pertinent à toute requête :

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

Cela va :

Extraire les mots-clés pertinents de la requête
Rechercher dans la base de connaissances les contextes correspondants
Retourner une requête améliorée avec le contexte inclus
Fournir des métadonnées sur ce qui a été trouvé

Modèle d'intégration

Pour les clients MCP qui souhaitent toujours vérifier d'abord le contexte Klever :

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

La fonctionnalité d'amélioration du contexte enrichit automatiquement les requêtes avec les connaissances Klever VM pertinentes de la base de connaissances complète.

Exemples d'intégration

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

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

Contribution

Les contributions sont les bienvenues ! Veuillez :

Forker le dépôt
Créer une branche de fonctionnalité
Apporter vos modifications
Ajouter des tests
Soumettre une pull request

Licence

Licence MIT - voir le fichier LICENSE pour plus de détails

Remerciements

Inspiré par Context7 by Upstash
Construit pour la Klever Blockchain
Utilise le Klever VM SDK (Rust)