Klever VM MCP Server

Klever VM MCP Server

Un servidor de Protocolo de Contexto de Modelo (MCP) diseñado para el desarrollo de contratos inteligentes en la blockchain Klever. Este servidor mantiene y sirve conocimiento contextual, incluyendo patrones de código, mejores prácticas y comportamiento en tiempo de ejecución para desarrolladores que trabajan con el SDK de la Klever VM.

Características

• 🚀 Operación en Triple Modo: Ejecutar como servidor API HTTP, servidor MCP stdio o servidor MCP público alojado
• 💾 Almacenamiento Flexible: Soporte de backend en memoria o Redis
• 🔍 Recuperación Inteligente de Contexto: Consulta por tipo, etiquetas o tipo de contrato
• 📝 Extracción Automática de Patrones: Analiza contratos Klever para extraer ejemplos y patrones
• 🎯 Clasificación por Relevancia: Puntuación y clasificación inteligente de contexto
• 🔄 Actualizaciones en Vivo: Añade y actualiza contexto en tiempo real
• 🛡️ Seguridad de Tipos: TypeScript completo con validación Zod
• 📚 Base de Conocimiento Integral: Precargada con patrones, mejores prácticas y ejemplos de Klever VM
• 🔧 Validación de Contratos: Detección automática de problemas comunes y antipatrones
• 🚀 Scripts de Despliegue: Scripts listos para usar para despliegue, actualización y consulta de contratos

Inicio Rápido

Instala y ejecuta al instante mediante npx — no requiere clonado:

npx -y @klever/mcp-server

O conéctate al servidor público alojado:

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

Consulta Integración con Cliente MCP para la configuración específica del cliente.

Arquitectura

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

Mejoras Clave Realizadas

1. Capa de Almacenamiento

   • Se añadieron límites de memoria para prevenir OOM en InMemoryStorage
   • Se optimizaron las consultas Redis para evitar el comando O(N) KEYS
   • Se añadieron transacciones atómicas para operaciones Redis
   • Se mejoró el manejo de errores y la validación

2. Seguridad de la API

   • Se añadió validación de entrada para todos los endpoints
   • Límites de tamaño de operación por lotes
   • Respuestas de error adecuadas sin filtrar información interna
   • Mensajes de error adaptados al entorno

3. Seguridad de Tipos

   • Validación de esquema centralizada
   • Interfaces TypeScript adecuadas para opciones
   • Validación en tiempo de ejecución de datos almacenados

4. Rendimiento

   • Operaciones por lotes usando Redis MGET
   • Consultas basadas en índices en lugar de escaneos completos
   • Operaciones de conteo optimizadas

Instalación

1. Clona el repositorio:

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

2. Instala las dependencias:

pnpm install

3. Copia la configuración de entorno:

cp .env.example .env

4. Instala las herramientas del SDK de Klever (necesarias para transacciones):

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

5. Construye el proyecto:

pnpm run build

Configuración

Edita el archivo .env para configurar el servidor:

# 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

Integración con Cliente 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

Añade a tu claude_desktop_config.json:

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

Para una configuración detallada, consulta la Guía de Instalación de Claude Desktop.

Cursor

Añade a tu configuración MCP de Cursor (.cursor/mcp.json):

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

VS Code (GitHub Copilot)

Añade a .vscode/mcp.json en tu proyecto:

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

Para una configuración detallada, consulta la Guía de Instalación de VS Code.

Servidor MCP Público

El Klever MCP Server puede alojarse como un servicio público compartido, permitiendo que cualquier desarrollador se conecte sin ejecutarlo localmente.

Conectando al Servidor Público

# 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

Herramientas Disponibles (Modo Público)

El servidor público expone un subconjunto de herramientas de solo lectura por seguridad:

Herramienta	Descripción
query_context	Buscar en la base de conocimiento de Klever VM
get_context	Recuperar un contexto específico por ID
find_similar	Encontrar contextos similares a un contexto dado
get_knowledge_stats	Obtener estadísticas de la base de conocimiento
enhance_with_context	Mejorar consultas con contexto relevante de Klever VM

Las operaciones de escritura (add_context) y las herramientas basadas en shell (init_klever_project, add_helper_scripts) están deshabilitadas en modo público.

Autoalojamiento con 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

Luego conéctate:

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

Autoalojamiento sin Docker

pnpm install
pnpm run build
pnpm run start:public

Variables de Entorno (Modo Público)

Variable	Valor por Defecto	Descripción
MODE	http	Establecer a public para modo alojado
PORT	3000	Puerto del servidor
CORS_ORIGINS	(sin establecer)	Orígenes permitidos separados por comas. Sin establecer o * permite todos los orígenes
RATE_LIMIT_MCP	60	Solicitudes/min al endpoint MCP por IP
RATE_LIMIT_API	30	Solicitudes/min al endpoint API por IP
BODY_SIZE_LIMIT	1mb	Tamaño máximo del cuerpo de la solicitud

Notas de Despliegue

Para producción en mcp.klever.org:

• Despliega el contenedor Docker detrás de un proxy inverso (nginx/Caddy/balanceador de carga en la nube) para terminación TLS
• Asegúrate de que el proxy pase el encabezado mcp-session-id y soporte SSE (deshabilita el buffering de respuesta)
• Una sola instancia es suficiente ya que el servidor es de solo lectura con una base de conocimiento en memoria
• Considera Cloudflare para protección DDoS (SSE es compatible)

Uso

Carga de la Base de Conocimiento

El servidor carga automáticamente la base de conocimiento de Klever según tu tipo de almacenamiento:

Almacenamiento en Memoria (Predeterminado)

• El conocimiento se carga automáticamente cuando el servidor se inicia
• No es necesario ejecutar pnpm run ingest por separado
• Los datos solo existen mientras el servidor está en ejecución
• Ideal para desarrollo y pruebas

Almacenamiento Redis

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

# Then start the server
pnpm run dev

• El conocimiento persiste en la base de datos Redis
• Sobrevive a reinicios del servidor
• Ideal para uso en producción

Esto cargará:

• Plantillas y ejemplos de contratos inteligentes
• Reglas de anotación y mejores prácticas
• Patrones de mapeo de almacenamiento y comparaciones
• Scripts de despliegue y consulta
• Errores comunes y soluciones
• Patrones de prueba
• Documentación de referencia de la API

Ejecutar como Servidor HTTP

# Development mode
pnpm run dev

# Production mode
pnpm run build && pnpm start

La API HTTP estará disponible en http://localhost:3000/api

Ejecutar como Servidor MCP

MODE=mcp pnpm start

Úsalo con cualquier cliente compatible con MCP.

Endpoints de la API

POST /api/context

Ingerir nuevo contexto en el sistema.

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

Recuperar contexto específico por ID.

POST /api/context/query

Consultar contextos con filtros.

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

PUT /api/context/:id

Actualizar contexto existente.

DELETE /api/context/:id

Eliminar contexto.

GET /api/context/:id/similar

Encontrar contextos similares.

POST /api/context/batch

Ingesta por lotes de múltiples contextos.

Herramientas MCP

Al ejecutarse como servidor MCP, las siguientes herramientas están disponibles:

• query_context: Buscar contexto relevante de desarrollo Klever
• add_context: Añadir nuevo contexto a la base de conocimiento
• get_context: Recuperar contexto específico por ID
• find_similar: Encontrar contextos similares a un contexto dado
• get_knowledge_stats: Obtener estadísticas sobre la base de conocimiento
• init_klever_project: Inicializar un nuevo proyecto de contrato inteligente Klever con scripts auxiliares
• enhance_with_context: Mejorar automáticamente consultas con contexto relevante de Klever VM

Tipos de Contexto

• code_example: Fragmentos de código funcionales y ejemplos (código de contrato inteligente Rust)
• best_practice: Patrones y prácticas recomendadas
• security_tip: Consideraciones de seguridad y advertencias
• optimization: Técnicas de optimización de rendimiento
• documentation: Documentación general y guías
• error_pattern: Errores comunes y soluciones
• deployment_tool: Scripts de despliegue y utilidades (scripts bash, herramientas)
• runtime_behavior: Explicaciones de comportamiento en tiempo de ejecución

Base de Conocimiento Precargada

El servidor MCP incluye una base de conocimiento integral con más de 95 entradas organizadas en 11 categorías:

Patrones Críticos

• Manejo de pagos y operaciones con tokens
• Conversiones decimales y cálculos
• Emisión de eventos y reglas de parámetros
• Uso de herramientas CLI y mejores prácticas

Patrones de Contrato y Ejemplos

• Plantillas de estructura básica de contrato
• Implementación completa de juego de lotería
• Contrato de staking con recompensas
• Patrones de comunicación entre contratos
• Patrones de acceso a almacenamiento remoto
• Módulos auxiliares de mapeo de tokens

Herramientas de Desarrollo

• Koperator: Referencia completa de CLI con codificación de argumentos
• KSC: Comandos de construcción y configuración de proyecto
• Scripts de despliegue, actualización y consulta
• Herramientas interactivas de gestión de contratos
• Biblioteca de utilidades comunes (bech32, gestión de red)

Almacenamiento y Optimización

• Guía de selección de mapeo de almacenamiento con comparaciones de rendimiento
• Patrones de organización de espacios de nombres
• Endpoints de vista para consultas eficientes
• Técnicas de optimización de gas
• Patrones OptionalValue vs Option

Mejores Prácticas y Seguridad

• Patrones de validación de entrada
• Estrategias de manejo de errores
• Uso de módulos admin y pause
• Patrones de control de acceso
• Errores comunes y soluciones

Ingesta de Contratos

Usa las utilidades de ingesta integradas para analizar e importar contratos 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();

Desarrollo

# 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

Validación de Contratos

El servidor puede validar automáticamente contratos Klever y detectar problemas:

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

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

Las comprobaciones de validación incluyen:

• Formato de anotación de eventos (comillas dobles, camelCase)
• Parámetros de API de tipo Managed
• Validación de dirección cero en transferencias
• Selección óptima de mapeo de almacenamiento
• Convenciones de nomenclatura de módulos

Casos de Uso de Ejemplo

1. Asistente de Desarrollo de Contratos Inteligentes

Integra con tu IDE para proporcionar sugerencias contextuales para el desarrollo de contratos Klever.

2. Herramienta de Revisión de Código

Verifica automáticamente los contratos contra las mejores prácticas y patrones de seguridad.

3. Plataforma de Aprendizaje

Proporciona ejemplos y explicaciones para desarrolladores que aprenden desarrollo Klever.

4. Generador de Documentación

Extrae y organiza la documentación del contrato automáticamente.

Especificaciones del Proyecto y Ejemplos

Para ejemplos completos de implementación de proyectos y especificaciones, consulta:

• Plantilla de Especificación de Proyecto - Una plantilla para rellenar y especificar proyectos de contratos inteligentes Klever. Guía a los asistentes de IA a través del descubrimiento de conocimiento MCP, seguimiento de tareas e implementación por fases. Incluye un ejemplo KleverDice.

Inicialización de Proyecto

El servidor MCP incluye una potente herramienta de inicialización de proyecto que crea un nuevo proyecto de contrato inteligente Klever con todos los scripts auxiliares necesarios.

Usando la Herramienta init_klever_project

Cuando estés conectado a través de MCP, usa la herramienta init_klever_project:

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

Parámetros:

• name (requerido): El nombre de tu contrato
• template (opcional): Plantilla a usar (por defecto: "empty")
• noMove (opcional): Si es true, mantiene el proyecto en un subdirectorio (por defecto: false)

Scripts Auxiliares Generados

La herramienta crea los siguientes scripts en el directorio scripts/:

• build.sh: Construye el contrato inteligente
• deploy.sh: Despliega en la testnet de Klever con detección automática de artefactos del contrato
• upgrade.sh: Actualiza un contrato existente (detecta automáticamente desde history.json)
• query.sh: Consulta endpoints del contrato con codificación/decodificación adecuada
• test.sh: Ejecuta pruebas del contrato
• interact.sh: Muestra ejemplos de uso y comandos disponibles

Flujo de Trabajo de Ejemplo

1. Inicializar proyecto:

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

2. Construir contrato:

   ./scripts/build.sh
   

3. Desplegar en testnet:

   ./scripts/deploy.sh
   

4. Consultar contrato:

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

5. Actualizar contrato:

   ./scripts/upgrade.sh
   

Todo el historial de despliegue se rastrea en output/history.json para fácil referencia.

Mejora Automática de Contexto

El servidor MCP puede mejorar automáticamente las consultas con contexto relevante de Klever VM. Esto asegura que tu cliente MCP siempre tenga acceso a la información más relevante.

Usando la Mejora de Contexto

Usa la herramienta enhance_with_context para añadir automáticamente contexto relevante a cualquier consulta:

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

Esto hará lo siguiente:

1. Extraer palabras clave relevantes de la consulta
2. Buscar en la base de conocimiento contextos coincidentes
3. Devolver una consulta mejorada con el contexto incluido
4. Proporcionar metadatos sobre lo que se encontró

Patrón de Integración

Para clientes MCP que quieran verificar siempre el contexto Klever primero:

// 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 función de mejora de contexto enriquece automáticamente las consultas con conocimiento relevante de Klever VM de la base de conocimiento integral.

Ejemplos de Integración

Extensión de 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'
  })
});

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

Contribuciones

¡Las contribuciones son bienvenidas! Por favor:

1. Haz un fork del repositorio
2. Crea una rama de funcionalidad
3. Realiza tus cambios
4. Añade pruebas
5. Envía una solicitud de extracción

Licencia

Licencia MIT - consulta el archivo LICENSE para más detalles

Agradecimientos

• Inspirado por Context7 by Upstash
• Construido para la Klever Blockchain
• Utiliza el Klever VM SDK (Rust)