Klever VM

Klever MCP Server

Сервер Model Context Protocol (MCP), адаптированный для разработки смарт-контрактов в блокчейне Klever. Этот сервер поддерживает и предоставляет контекстные знания, включая шаблоны кода, лучшие практики и поведение во время выполнения для разработчиков, работающих с Klever VM SDK.

Возможности

• 🚀 Три режима работы: Запуск как HTTP API сервер, MCP stdio сервер или публичный размещённый MCP сервер
• 💾 Гибкое хранилище: Поддержка хранения в памяти или в Redis
• 🔍 Умное извлечение контекста: Запросы по типу, тегам или типу контракта
• 📝 Автоматическое извлечение шаблонов: Парсинг контрактов Klever для извлечения примеров и шаблонов
• 🎯 Ранжирование по релевантности: Интеллектуальная оценка и ранжирование контекста
• 🔄 Обновления в реальном времени: Добавление и обновление контекста на лету
• 🛡️ Типобезопасность: Полный TypeScript с валидацией через Zod
• 📚 Обширная база знаний: Предзагружена шаблонами Klever VM, лучшими практиками и примерами
• 🔧 Валидация контрактов: Автоматическое обнаружение распространённых проблем и антипаттернов
• 🚀 Скрипты развёртывания: Готовые к использованию скрипты для развёртывания, обновления и запросов к контрактам

Быстрый старт

Установите и запустите мгновенно через npx — клонирование не требуется:

npx -y @klever/mcp-server

Или подключитесь к размещённому публичному серверу:

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

См. раздел Интеграция MCP-клиента для настройки конкретного клиента.

Архитектура

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

Ключевые улучшения

1. Слой хранения

   • Добавлены лимиты памяти для предотвращения OOM в InMemoryStorage
   • Оптимизированы запросы Redis, чтобы избежать команды KEYS с O(N)
   • Добавлены атомарные транзакции для операций Redis
   • Улучшена обработка ошибок и валидация

2. Безопасность API

   • Добавлена валидация входных данных для всех эндпоинтов
   • Ограничения на размер пакетных операций
   • Корректные ответы об ошибках без утечки внутренней информации
   • Сообщения об ошибках с учётом окружения

3. Типобезопасность

   • Централизованная валидация схем
   • Правильные интерфейсы TypeScript для опций
   • Валидация хранимых данных во время выполнения

4. Производительность

   • Пакетные операции с использованием Redis MGET
   • Запросы на основе индексов вместо полного сканирования
   • Оптимизированные операции подсчёта

Установка

1. Клонируйте репозиторий:

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

2. Установите зависимости:

pnpm install

3. Скопируйте конфигурацию окружения:

cp .env.example .env

4. Установите инструменты Klever SDK (необходимы для транзакций):

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

5. Соберите проект:

pnpm run build

Конфигурация

Отредактируйте файл .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-клиента

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:

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

Подробную настройку см. в Руководстве по установке Claude Desktop.

Cursor

Добавьте в настройки Cursor MCP (.cursor/mcp.json):

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

VS Code (GitHub Copilot)

Добавьте в .vscode/mcp.json в вашем проекте:

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

Подробную настройку см. в Руководстве по установке VS Code.

Публичный MCP-сервер

Klever MCP 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

Доступные инструменты (публичный режим)

Публичный сервер предоставляет подмножество инструментов только для чтения в целях безопасности:

Инструмент	Описание
query_context	Поиск в базе знаний Klever VM
get_context	Получение конкретного контекста по ID
find_similar	Поиск контекстов, похожих на заданный
get_knowledge_stats	Получение статистики базы знаний
enhance_with_context	Улучшение запросов релевантным контекстом Klever VM

Операции записи (add_context) и инструменты на основе оболочки (init_klever_project, add_helper_scripts) отключены в публичном режиме.

Самостоятельное размещение с 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

Затем подключитесь:

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

Самостоятельное размещение без Docker

pnpm install
pnpm run build
pnpm run start:public

Переменные окружения (публичный режим)

Переменная	По умолчанию	Описание
MODE	http	Установите public для размещённого режима
PORT	3000	Порт сервера
CORS_ORIGINS	(не задано)	Разрешённые источники через запятую. Если не задано или *, разрешены все источники
RATE_LIMIT_MCP	60	Запросов к MCP эндпоинту в минуту на IP
RATE_LIMIT_API	30	Запросов к API эндпоинту в минуту на IP
BODY_SIZE_LIMIT	1mb	Максимальный размер тела запроса

Заметки по развёртыванию

Для продакшена на mcp.klever.org:

• Разверните Docker-контейнер за обратным прокси (nginx/Caddy/облачный балансировщик) для терминирования TLS
• Убедитесь, что прокси передаёт заголовок mcp-session-id и поддерживает SSE (отключите буферизацию ответов)
• Достаточно одного экземпляра, так как сервер только для чтения с базой знаний в памяти
• Рассмотрите Cloudflare для защиты от DDoS (SSE поддерживается)

Использование

Загрузка базы знаний

Сервер автоматически загружает базу знаний Klever в зависимости от типа хранилища:

Хранилище в памяти (по умолчанию)

• Знания автоматически загружаются при запуске сервера
• Не нужно отдельно запускать pnpm run ingest
• Данные существуют только во время работы сервера
• Лучше всего для разработки и тестирования

Хранилище Redis

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

# Then start the server
pnpm run dev

• Знания сохраняются в базе данных Redis
• Переживают перезапуски сервера
• Лучше всего для продакшена

Будет загружено:

• Шаблоны и примеры смарт-контрактов
• Правила аннотаций и лучшие практики
• Шаблоны отображения хранилища и сравнения
• Скрипты развёртывания и запросов
• Распространённые ошибки и решения
• Шаблоны тестирования
• Справочная документация по API

Запуск как HTTP-сервер

# Development mode
pnpm run dev

# Production mode
pnpm run build && pnpm start

HTTP API будет доступно по адресу http://localhost:3000/api

Запуск как MCP-сервер

MODE=mcp pnpm start

Используйте с любым MCP-совместимым клиентом.

Эндпоинты API

POST /api/context

Добавление нового контекста в систему.

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

Получение конкретного контекста по ID.

POST /api/context/query

Запрос контекстов с фильтрами.

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

PUT /api/context/:id

Обновление существующего контекста.

DELETE /api/context/:id

Удаление контекста.

GET /api/context/:id/similar

Поиск похожих контекстов.

POST /api/context/batch

Пакетное добавление нескольких контекстов.

Инструменты MCP

При запуске как MCP-сервер доступны следующие инструменты:

• query_context: Поиск релевантного контекста разработки Klever
• add_context: Добавление нового контекста в базу знаний
• get_context: Получение конкретного контекста по ID
• find_similar: Поиск контекстов, похожих на заданный
• get_knowledge_stats: Получение статистики базы знаний
• init_klever_project: Инициализация нового проекта смарт-контракта Klever со вспомогательными скриптами
• enhance_with_context: Автоматическое улучшение запросов релевантным контекстом Klever VM

Типы контекста

• code_example: Рабочие фрагменты кода и примеры (код смарт-контрактов на Rust)
• best_practice: Рекомендуемые шаблоны и практики
• security_tip: Соображения безопасности и предупреждения
• optimization: Техники оптимизации производительности
• documentation: Общая документация и руководства
• error_pattern: Распространённые ошибки и решения
• deployment_tool: Скрипты развёртывания и утилиты (bash-скрипты, инструменты)
• runtime_behavior: Объяснения поведения во время выполнения

Предзагруженная база знаний

MCP-сервер включает обширную базу знаний с более чем 95 записями, организованными в 11 категорий:

Критические шаблоны

• Обработка платежей и операции с токенами
• Преобразования десятичных чисел и вычисления
• Генерация событий и правила параметров
• Использование CLI-инструментов и лучшие практики

Шаблоны контрактов и примеры

• Базовые шаблоны структуры контракта
• Полная реализация лотерейной игры
• Контракт стейкинга с вознаграждениями
• Шаблоны межконтрактного взаимодействия
• Шаблоны удалённого доступа к хранилищу
• Вспомогательные модули отображения токенов

Инструменты разработки

• Koperator: Полный справочник CLI с кодированием аргументов
• KSC: Команды сборки и настройка проекта
• Скрипты развёртывания, обновления и запросов
• Интерактивные инструменты управления контрактами
• Библиотека общих утилит (bech32, управление сетью)

Хранилище и оптимизация

• Руководство по выбору отображения хранилища со сравнением производительности
• Шаблоны организации пространств имён
• Эндпоинты просмотра для эффективных запросов
• Техники оптимизации газа
• Шаблоны OptionalValue vs Option

Лучшие практики и безопасность

• Шаблоны валидации входных данных
• Стратегии обработки ошибок
• Использование модулей admin и pause
• Шаблоны контроля доступа
• Распространённые ошибки и решения

Импорт контрактов

Используйте встроенные утилиты импорта для парсинга и импорта контрактов 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();

Разработка

# 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

Валидация контрактов

Сервер может автоматически проверять контракты Klever и обнаруживать проблемы:

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

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

Проверки валидации включают:

• Формат аннотаций событий (двойные кавычки, camelCase)
• Параметры API управляемого типа
• Проверка нулевого адреса в переводах
• Оптимальный выбор отображения хранилища
• Соглашения об именовании модулей

Примеры использования

1. Ассистент разработки смарт-контрактов

Интегрируйте с вашей IDE для предоставления контекстно-зависимых предложений при разработке контрактов Klever.

2. Инструмент проверки кода

Автоматически проверяйте контракты на соответствие лучшим практикам и шаблонам безопасности.

3. Обучающая платформа

Предоставляйте примеры и объяснения для разработчиков, изучающих разработку на Klever.

4. Генератор документации

Автоматически извлекайте и организуйте документацию по контрактам.

Спецификации проекта и примеры

Полные примеры реализации проекта и спецификации см. в:

• Шаблон спецификации проекта — заполняемый шаблон для спецификации проектов смарт-контрактов Klever. Помогает AI-ассистентам в обнаружении знаний MCP, отслеживании задач и поэтапной реализации. Включает пример KleverDice.

Инициализация проекта

MCP-сервер включает мощный инструмент инициализации проекта, который создаёт новый проект смарт-контракта Klever со всеми необходимыми вспомогательными скриптами.

Использование инструмента init_klever_project

При подключении через MCP используйте инструмент init_klever_project:

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

Параметры:

• name (обязательный): Имя вашего контракта
• template (опциональный): Используемый шаблон (по умолчанию: "empty")
• noMove (опциональный): Если true, сохраняет проект в поддиректории (по умолчанию: false)

Сгенерированные вспомогательные скрипты

Инструмент создаёт следующие скрипты в директории scripts/:

• build.sh: Сборка смарт-контракта
• deploy.sh: Развёртывание в тестовой сети Klever с автоопределением артефактов контракта
• upgrade.sh: Обновление существующего контракта (автоопределение из history.json)
• query.sh: Запрос к эндпоинтам контракта с правильным кодированием/декодированием
• test.sh: Запуск тестов контракта
• interact.sh: Показывает примеры использования и доступные команды

Пример рабочего процесса

1. Инициализация проекта:

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

2. Сборка контракта:

   ./scripts/build.sh
   

3. Развёртывание в тестовой сети:

   ./scripts/deploy.sh
   

4. Запрос к контракту:

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

5. Обновление контракта:

   ./scripts/upgrade.sh
   

Вся история развёртывания отслеживается в output/history.json для удобства.

Автоматическое улучшение контекста

MCP-сервер может автоматически улучшать запросы релевантным контекстом Klever VM. Это гарантирует, что ваш MCP-клиент всегда имеет доступ к наиболее релевантной информации.

Использование улучшения контекста

Используйте инструмент enhance_with_context для автоматического добавления релевантного контекста к любому запросу:

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

Это позволит:

1. Извлечь релевантные ключевые слова из запроса
2. Выполнить поиск в базе знаний подходящих контекстов
3. Вернуть улучшенный запрос с включённым контекстом
4. Предоставить метаданные о найденном

Шаблон интеграции

Для MCP-клиентов, которые хотят всегда сначала проверять контекст 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
}

Функция улучшения контекста автоматически обогащает запросы релевантными знаниями Klever VM из обширной базы знаний.

Примеры интеграции

Расширение 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'
  })
});

Инструмент 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"]
    }
  }'

Участие в разработке

Вклады приветствуются! Пожалуйста:

1. Сделайте форк репозитория
2. Создайте ветку для функционала
3. Внесите свои изменения
4. Добавьте тесты
5. Отправьте pull request

Лицензия

Лицензия MIT — подробности см. в файле LICENSE

Благодарности

• Вдохновлено Context7 от Upstash
• Создано для Klever Blockchain
• Использует Klever VM SDK (Rust)