io.github.klever-io/mcp-klever-vm

Install

Config snippet generator goes here (5 client tabs)

README

# Klever MCP Server

A Model Context Protocol (MCP) server tailored for Klever blockchain smart contract development. This server maintains and serves contextual knowledge including code patterns, best practices, and runtime behavior for developers working with the Klever VM SDK.

## Features

- 🚀 **Triple Mode Operation**: Run as HTTP API server, MCP stdio server, or public hosted MCP server
- 💾 **Flexible Storage**: In-memory or Redis backend support
- 🔍 **Smart Context Retrieval**: Query by type, tags, or contract type
- 📝 **Automatic Pattern Extraction**: Parse Klever contracts to extract examples and patterns
- 🎯 **Relevance Ranking**: Intelligent scoring and ranking of context
- 🔄 **Live Updates**: Add and update context in real-time
- 🛡️ **Type Safety**: Full TypeScript with Zod validation
- 📚 **Comprehensive Knowledge Base**: Pre-loaded with Klever VM patterns, best practices, and examples
- 🔧 **Contract Validation**: Automatic detection of common issues and anti-patterns
- 🚀 **Deployment Scripts**: Ready-to-use scripts for contract deployment, upgrade, and querying

## Quick Start

Install and run instantly via npx — no cloning required:

```bash
npx -y @klever/mcp-server
```

Or connect to the hosted public server:

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

See [MCP Client Integration](#mcp-client-integration) for client-specific configuration.

## 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
   - Batch operation size limits
   - Proper error responses without leaking internals
   - Environment-aware error messages

3. **Type Safety**
   - Centralized schema validation
   - Proper TypeScript interfaces for options
   - Runtime validation of stored data

4. **Performance**
   - Batch operations using Redis MGET
   - Index-based queries instead of full scans
   - Optimized count operations

## Installation

1. Clone the repository:
```bash
git clone https://github.com/klever-io/mcp-klever-vm.git
cd mcp-klever-vm
```

2. Install dependencies:
```bash
pnpm install
```

3. Copy environment configuration:
```bash
cp .env.example .env
```

4. Install Klever SDK tools (required for transactions):
```bash
chmod +x scripts/install-sdk.sh && ./scripts/install-sdk.sh
```

5. Build the project:
```bash
pnpm run build
```

## Configuration

Edit `.env` file to configure the server:

```env
# 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

```bash
# 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`:

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

For detailed setup, see the [Claude Desktop Installation Guide](docs/install-claude.md).

### Cursor

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

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

###