MCP Klever Vm

🚀 Klever MCP Server

The Klever MCP Server is a specialized Model Context Protocol (MCP) server designed for Klever blockchain smart contract development. It stores and provides contextual knowledge, including code patterns, best practices, and runtime behavior, for developers using the Klever VM SDK.

✨ Features

• 🚀 Triple Mode Operation: It can operate as an HTTP API server, an MCP stdio server, or a public hosted MCP server.
• 💾 Flexible Storage: Supports both in - memory and Redis backends.
• 🔍 Smart Context Retrieval: Allows queries by type, tags, or contract type.
• 📝 Automatic Pattern Extraction: Parses Klever contracts to extract examples and patterns.
• 🎯 Relevance Ranking: Offers intelligent scoring and ranking of context.
• 🔄 Live Updates: Enables real - time addition and update of context.
• 🛡️ Type Safety: Fully written in TypeScript with Zod validation.
• 📚 Comprehensive Knowledge Base: Pre - loaded with Klever VM patterns, best practices, and examples.
• 🔧 Contract Validation: Automatically detects common issues and anti - patterns.
• 🚀 Deployment Scripts: Provides ready - to - use scripts for contract deployment, upgrade, and querying.

🚀 Quick Start

You can install and run the server instantly via npx without cloning:

npx -y @klever/mcp-server

Or connect to the hosted public server:

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

Refer to MCP Client Integration for client - specific configuration.

📦 Installation

1. Clone the repository:

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

2. Install dependencies:

pnpm install

3. Copy environment configuration:

cp .env.example .env

4. Install Klever SDK tools (required for transactions):

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

5. Build the project:

pnpm run build

💻 Usage Examples

Basic Usage

# Install and run via npx
npx -y @klever/mcp-server

Advanced Usage

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

📚 Documentation

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

Key Improvements Made

1. Storage Layer
   • Added memory limits to prevent OOM in InMemoryStorage.
   • Optimized Redis queries to avoid O(N) KEYS command.
   • Added atomic transactions for Redis operations.
   • Improved error handling and validation.
2. API Security
   • Added input validation for all endpoints.
   • Set batch operation size limits.
   • Provided proper error responses without leaking internals.
   • Used environment - aware error messages.
3. Type Safety
   • Centralized schema validation.
   • Defined proper TypeScript interfaces for options.
   • Implemented runtime validation of stored data.
4. Performance
   • Used batch operations with Redis MGET.
   • Employed index - based queries instead of full scans.
   • Optimized count operations.

Configuration

Edit the .env file to configure the 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

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

Add to your claude_desktop_config.json:

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

For detailed setup, see the Claude Desktop Installation Guide.

Cursor

Add to your Cursor MCP settings (.cursor/mcp.json):

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

VS Code (GitHub Copilot)

Add to .vscode/mcp.json in your project:

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

For detailed setup, see the VS Code Installation Guide.

Public MCP Server

The Klever MCP Server can be hosted as a public shared service, allowing any developer to connect without running it locally.

Connecting to the Public 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

Available Tools (Public Mode)

The public server exposes a read - only subset of tools for security:

Write operations (add_context) and shell - based tools (init_klever_project, add_helper_scripts) are disabled in public mode.

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

Then connect:

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

Self - Hosting without Docker

pnpm install
pnpm run build
pnpm run start:public

Environment Variables (Public Mode)

Deployment Notes

For production at mcp.klever.org:

• Deploy the Docker container behind a reverse proxy (nginx/Caddy/cloud LB) for TLS termination.
• Ensure the proxy passes the mcp-session-id header and supports SSE (disable response buffering).
• A single instance is sufficient as the server is read - only with an in - memory knowledge base.
• Consider using Cloudflare for DDoS protection (SSE is supported).

Usage

Knowledge Base Loading

The server automatically loads the Klever knowledge base based on your storage type:

Memory Storage (Default)

• Knowledge is automatically loaded when the server starts.
• There is no need to run pnpm run ingest separately.
• Data exists only while the server is running.
• Best for development and testing.

Redis Storage

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

# Then start the server
pnpm run dev

• Knowledge persists in the Redis database.
• Survives server restarts.
• Best for production use.

This will load:

• Smart contract templates and examples.
• Annotation rules and best practices.
• Storage mapper patterns and comparisons.
• Deployment and query scripts.
• Common errors and solutions.
• Testing patterns.
• API reference documentation.

Running as HTTP Server

# Development mode
pnpm run dev

# Production mode
pnpm run build && pnpm start

The HTTP API will be available at http://localhost:3000/api

Running as MCP Server

MODE=mcp pnpm start

Use with any MCP - compatible client.

API Endpoints

POST /api/context

Ingest new context into the system.

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

Retrieve specific context by ID.

POST /api/context/query

Query contexts with filters.

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

PUT /api/context/:id

Update existing context.

DELETE /api/context/:id

Delete context.

GET /api/context/:id/similar

Find similar contexts.

POST /api/context/batch

Batch ingest multiple contexts.

MCP Tools

When running as an MCP server, the following tools are available:

• query_context: Search for relevant Klever development context.
• add_context: Add new context to the knowledge base.
• get_context: Retrieve specific context by ID.
• find_similar: Find contexts similar to a given context.
• get_knowledge_stats: Get statistics about the knowledge base.
• init_klever_project: Initialize a new Klever smart contract project with helper scripts.
• enhance_with_context: Automatically enhance queries with relevant Klever VM context.

Context Types

• code_example: Working code snippets and examples (Rust smart contract code).
• best_practice: Recommended patterns and practices.
• security_tip: Security considerations and warnings.
• optimization: Performance optimization techniques.
• documentation: General documentation and guides.
• error_pattern: Common errors and solutions.
• deployment_tool: Deployment scripts and utilities (bash scripts, tools).
• runtime_behavior: Runtime behavior explanations.

Pre - loaded Knowledge Base

The MCP server includes a comprehensive knowledge base with 95+ entries organized into 11 categories:

Critical Patterns

• Payment handling and token operations.
• Decimal conversions and calculations.
• Event emission and parameter rules.
• CLI tool usage and best practices.

Contract Patterns & Examples

• Basic contract structure templates.
• Complete lottery game implementation.
• Staking contract with rewards.
• Cross - contract communication patterns.
• Remote storage access patterns.
• Token mapper helper modules.

Development Tools

• Koperator: Complete CLI reference with argument encoding.
• KSC: Build commands and project setup.
• Deployment, upgrade, and query scripts.
• Interactive contract management tools.
• Common utilities library (bech32, network management).

Storage & Optimization

• Storage mapper selection guide with performance comparisons.
• Namespace organization patterns.
• View endpoints for efficient queries.
• Gas optimization techniques.
• OptionalValue vs Option patterns.

Best Practices & Security

• Input validation patterns.
• Error handling strategies.
• Admin and pause module usage.
• Access control patterns.
• Common mistakes and solutions.

Ingesting Contracts

Use the built - in ingestion utilities to parse and import Klever contracts:

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

Development

# 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

Contract Validation

The server can automatically validate Klever contracts and detect issues:

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

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

Validation checks include:

• Event annotation format (double quotes, camelCase).
• Managed type API parameters.
• Zero address validation in transfers.
• Optimal storage mapper selection.
• Module naming conventions.

Example Use Cases

1. Smart Contract Development Assistant

Integrate with your IDE to provide context - aware suggestions for Klever contract development.

2. Code Review Tool

Automatically check contracts against best practices and security patterns.

3. Learning Platform

Provide examples and explanations for developers learning Klever development.

4. Documentation Generator

Extract and organize contract documentation automatically.

Project Specifications and Examples

For complete project implementation examples and specifications, see:

• Project Specification Template - A fill - in template for specifying Klever smart contract projects. Guides AI assistants through MCP knowledge discovery, task tracking, and phased implementation. Includes a KleverDice example.

Project Initialization

The MCP server includes a powerful project initialization tool that creates a new Klever smart contract project with all necessary helper scripts.

Using the init_klever_project Tool

When connected via MCP, use the init_klever_project tool:

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

Parameters:

• name (required): The name of your contract.
• template (optional): Template to use (default: "empty").
• noMove (optional): If true, keeps project in subdirectory (default: false).

Generated Helper Scripts

The tool creates the following scripts in the scripts/ directory:

• build.sh: Builds the smart contract.
• deploy.sh: Deploys to Klever testnet with auto - detection of contract artifacts.
• upgrade.sh: Upgrades existing contract (auto - detects from history.json).
• query.sh: Query contract endpoints with proper encoding/decoding.
• test.sh: Run contract tests.
• interact.sh: Shows usage examples and available commands.

Example Workflow

1. Initialize project:

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

2. Build contract:

   ./scripts/build.sh
   

3. Deploy to testnet:

   ./scripts/deploy.sh
   

4. Query contract:

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

5. Upgrade contract:

   ./scripts/upgrade.sh
   

All deployment history is tracked in output/history.json for easy reference.

Automatic Context Enhancement

The MCP server can automatically enhance queries with relevant Klever VM context. This ensures your MCP client always has access to the most relevant information.

Using Context Enhancement

Use the enhance_with_context tool to automatically add relevant context to any query:

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

This will:

1. Extract relevant keywords from the query.
2. Search the knowledge base for matching contexts.
3. Return an enhanced query with context included.
4. Provide metadata about what was found.

Integration Pattern

For MCP clients that want to always check Klever context first:

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

The context enhancement feature automatically enriches queries with relevant Klever VM knowledge from the comprehensive knowledge base.

Integration Examples

VS Code Extension

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

🔧 Technical Details

The server is implemented with a modular architecture, including an HTTP API layer, a context management service, and multiple storage backends. It uses TypeScript for type safety and Zod for validation. The knowledge base is pre - loaded with a large number of Klever VM - related patterns, best practices, and examples, which can be ingested and updated dynamically.

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

Acknowledgments

• Inspired by Context7 by Upstash.
• Built for the Klever Blockchain.
• Uses the Klever VM SDK (Rust).