Klever VM MCP Server

Klever VM MCP Server

Um servidor Model Context Protocol (MCP) adaptado para desenvolvimento de smart contracts na blockchain Klever. Este servidor mantém e fornece conhecimento contextual, incluindo padrões de código, melhores práticas e comportamento em tempo de execução para desenvolvedores que trabalham com o SDK da Klever VM.

Funcionalidades

• 🚀 Operação em Modo Triplo: Execute como servidor HTTP API, servidor MCP stdio ou servidor MCP público hospedado
• 💾 Armazenamento Flexível: Suporte a backend em memória ou Redis
• 🔍 Recuperação Inteligente de Contexto: Consulta por tipo, tags ou tipo de contrato
• 📝 Extração Automática de Padrões: Analisa contratos Klever para extrair exemplos e padrões
• 🎯 Classificação por Relevância: Pontuação e classificação inteligente de contexto
• 🔄 Atualizações em Tempo Real: Adicione e atualize contexto em tempo real
• 🛡️ Segurança de Tipos: TypeScript completo com validação Zod
• 📚 Base de Conhecimento Abrangente: Pré-carregada com padrões, melhores práticas e exemplos da Klever VM
• 🔧 Validação de Contratos: Detecção automática de problemas comuns e antipadrões
• 🚀 Scripts de Deploy: Scripts prontos para uso em deploy, atualização e consulta de contratos

Início Rápido

Instale e execute instantaneamente via npx — sem necessidade de clonar:

npx -y @klever/mcp-server

Ou conecte-se ao servidor público hospedado:

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

Consulte Integração com Cliente MCP para configuração específica do cliente.

Arquitetura

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

Principais Melhorias Realizadas

1. Camada de Armazenamento

   • Adicionados limites de memória para evitar OOM no InMemoryStorage
   • Consultas Redis otimizadas para evitar comando KEYS O(N)
   • Adicionadas transações atômicas para operações Redis
   • Tratamento de erros e validação aprimorados

2. Segurança da API

   • Adicionada validação de entrada para todos os endpoints
   • Limites de tamanho para operações em lote
   • Respostas de erro adequadas sem vazar informações internas
   • Mensagens de erro sensíveis ao ambiente

3. Segurança de Tipos

   • Validação de esquema centralizada
   • Interfaces TypeScript adequadas para opções
   • Validação em tempo de execução dos dados armazenados

4. Desempenho

   • Operações em lote usando Redis MGET
   • Consultas baseadas em índice em vez de varreduras completas
   • Operações de contagem otimizadas

Instalação

1. Clone o repositório:

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

2. Instale as dependências:

pnpm install

3. Copie a configuração de ambiente:

cp .env.example .env

4. Instale as ferramentas do SDK Klever (necessário para transações):

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

5. Compile o projeto:

pnpm run build

Configuração

Edite o arquivo .env para configurar o 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

Integração com 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

Adicione ao seu claude_desktop_config.json:

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

Para configuração detalhada, consulte o Guia de Instalação do Claude Desktop.

Cursor

Adicione às configurações MCP do Cursor (.cursor/mcp.json):

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

VS Code (GitHub Copilot)

Adicione ao .vscode/mcp.json no seu projeto:

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

Para configuração detalhada, consulte o Guia de Instalação do VS Code.

Servidor MCP Público

O Klever MCP Server pode ser hospedado como um serviço público compartilhado, permitindo que qualquer desenvolvedor se conecte sem executá-lo localmente.

Conectando ao 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

Ferramentas Disponíveis (Modo Público)

O servidor público expõe um subconjunto de ferramentas somente leitura por segurança:

Ferramenta	Descrição
query_context	Pesquisar a base de conhecimento da Klever VM
get_context	Recuperar um contexto específico por ID
find_similar	Encontrar contextos semelhantes a um determinado contexto
get_knowledge_stats	Obter estatísticas da base de conhecimento
enhance_with_context	Aprimorar consultas com contexto relevante da Klever VM

Operações de escrita (add_context) e ferramentas baseadas em shell (init_klever_project, add_helper_scripts) estão desabilitadas no modo público.

Auto-hospedagem com 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

Em seguida, conecte:

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

Auto-hospedagem sem Docker

pnpm install
pnpm run build
pnpm run start:public

Variáveis de Ambiente (Modo Público)

Variável	Padrão	Descrição
MODE	http	Defina como public para modo hospedado
PORT	3000	Porta do servidor
CORS_ORIGINS	(não definido)	Origens permitidas separadas por vírgula. Não definido ou * permite todas as origens
RATE_LIMIT_MCP	60	Requisições/min por IP para endpoint MCP
RATE_LIMIT_API	30	Requisições/min por IP para endpoint API
BODY_SIZE_LIMIT	1mb	Tamanho máximo do corpo da requisição

Notas de Deploy

Para produção em mcp.klever.org:

• Implante o contêiner Docker atrás de um proxy reverso (nginx/Caddy/cloud LB) para terminação TLS
• Certifique-se de que o proxy passa o cabeçalho mcp-session-id e suporta SSE (desabilite o buffer de resposta)
• Uma única instância é suficiente, pois o servidor é somente leitura com base de conhecimento em memória
• Considere o Cloudflare para proteção DDoS (SSE é suportado)

Uso

Carregamento da Base de Conhecimento

O servidor carrega automaticamente a base de conhecimento Klever com base no seu tipo de armazenamento:

Armazenamento em Memória (Padrão)

• O conhecimento é carregado automaticamente quando o servidor inicia
• Não é necessário executar pnpm run ingest separadamente
• Os dados existem apenas enquanto o servidor está em execução
• Melhor para desenvolvimento e testes

Armazenamento Redis

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

# Then start the server
pnpm run dev

• O conhecimento persiste no banco de dados Redis
• Sobrevive a reinicializações do servidor
• Melhor para uso em produção

Isso carregará:

• Modelos e exemplos de smart contracts
• Regras de anotação e melhores práticas
• Padrões de mapeador de armazenamento e comparações
• Scripts de deploy e consulta
• Erros comuns e soluções
• Padrões de teste
• Documentação de referência da API

Executando como Servidor HTTP

# Development mode
pnpm run dev

# Production mode
pnpm run build && pnpm start

A API HTTP estará disponível em http://localhost:3000/api

Executando como Servidor MCP

MODE=mcp pnpm start

Use com qualquer cliente compatível com MCP.

Endpoints da API

POST /api/context

Ingerir novo contexto no 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 com filtros.

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

PUT /api/context/:id

Atualizar contexto existente.

DELETE /api/context/:id

Excluir contexto.

GET /api/context/:id/similar

Encontrar contextos semelhantes.

POST /api/context/batch

Ingestão em lote de múltiplos contextos.

Ferramentas MCP

Ao executar como servidor MCP, as seguintes ferramentas estão disponíveis:

• query_context: Pesquisar contexto relevante de desenvolvimento Klever
• add_context: Adicionar novo contexto à base de conhecimento
• get_context: Recuperar contexto específico por ID
• find_similar: Encontrar contextos semelhantes a um determinado contexto
• get_knowledge_stats: Obter estatísticas sobre a base de conhecimento
• init_klever_project: Inicializar um novo projeto de smart contract Klever com scripts auxiliares
• enhance_with_context: Aprimorar automaticamente consultas com contexto relevante da Klever VM

Tipos de Contexto

• code_example: Trechos de código funcionais e exemplos (código de smart contract Rust)
• best_practice: Padrões e práticas recomendadas
• security_tip: Considerações de segurança e avisos
• optimization: Técnicas de otimização de desempenho
• documentation: Documentação geral e guias
• error_pattern: Erros comuns e soluções
• deployment_tool: Scripts de deploy e utilitários (scripts bash, ferramentas)
• runtime_behavior: Explicações de comportamento em tempo de execução

Base de Conhecimento Pré-carregada

O servidor MCP inclui uma base de conhecimento abrangente com mais de 95 entradas organizadas em 11 categorias:

Padrões Críticos

• Manipulação de pagamentos e operações com tokens
• Conversões decimais e cálculos
• Emissão de eventos e regras de parâmetros
• Uso de ferramentas CLI e melhores práticas

Padrões de Contrato e Exemplos

• Modelos básicos de estrutura de contrato
• Implementação completa de jogo de loteria
• Contrato de staking com recompensas
• Padrões de comunicação entre contratos
• Padrões de acesso a armazenamento remoto
• Módulos auxiliares de mapeador de tokens

Ferramentas de Desenvolvimento

• Koperator: Referência completa da CLI com codificação de argumentos
• KSC: Comandos de build e configuração de projeto
• Scripts de deploy, atualização e consulta
• Ferramentas interativas de gerenciamento de contratos
• Biblioteca de utilitários comuns (bech32, gerenciamento de rede)

Armazenamento e Otimização

• Guia de seleção de mapeador de armazenamento com comparações de desempenho
• Padrões de organização de namespace
• Endpoints de visualização para consultas eficientes
• Técnicas de otimização de gas
• Padrões OptionalValue vs Option

Melhores Práticas e Segurança

• Padrões de validação de entrada
• Estratégias de tratamento de erros
• Uso de módulos admin e pause
• Padrões de controle de acesso
• Erros comuns e soluções

Ingestão de Contratos

Use os utilitários de ingestão integrados para analisar 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();

Desenvolvimento

# 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

Validação de Contratos

O servidor pode validar automaticamente contratos Klever e detectar problemas:

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

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

As verificações de validação incluem:

• Formato de anotação de eventos (aspas duplas, camelCase)
• Parâmetros de API de tipos gerenciados
• Validação de endereço zero em transferências
• Seleção ideal de mapeador de armazenamento
• Convenções de nomenclatura de módulos

Casos de Uso de Exemplo

1. Assistente de Desenvolvimento de Smart Contracts

Integre com seu IDE para fornecer sugestões sensíveis ao contexto para desenvolvimento de contratos Klever.

2. Ferramenta de Revisão de Código

Verifique automaticamente contratos em relação às melhores práticas e padrões de segurança.

3. Plataforma de Aprendizado

Forneça exemplos e explicações para desenvolvedores aprendendo desenvolvimento Klever.

4. Gerador de Documentação

Extraia e organize a documentação do contrato automaticamente.

Especificações do Projeto e Exemplos

Para exemplos completos de implementação de projeto e especificações, consulte:

• Modelo de Especificação de Projeto - Um modelo para preencher ao especificar projetos de smart contract Klever. Orienta assistentes de IA através da descoberta de conhecimento MCP, rastreamento de tarefas e implementação em fases. Inclui um exemplo KleverDice.

Inicialização de Projeto

O servidor MCP inclui uma poderosa ferramenta de inicialização de projeto que cria um novo projeto de smart contract Klever com todos os scripts auxiliares necessários.

Usando a Ferramenta init_klever_project

Quando conectado via MCP, use a ferramenta init_klever_project:

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

Parâmetros:

• name (obrigatório): O nome do seu contrato
• template (opcional): Modelo a ser usado (padrão: "empty")
• noMove (opcional): Se true, mantém o projeto em subdiretório (padrão: false)

Scripts Auxiliares Gerados

A ferramenta cria os seguintes scripts no diretório scripts/:

• build.sh: Compila o smart contract
• deploy.sh: Implanta na testnet Klever com detecção automática de artefatos do contrato
• upgrade.sh: Atualiza contrato existente (detecta automaticamente do history.json)
• query.sh: Consulta endpoints do contrato com codificação/decodificação adequada
• test.sh: Executa testes do contrato
• interact.sh: Mostra exemplos de uso e comandos disponíveis

Fluxo de Trabalho de Exemplo

1. Inicializar projeto:

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

2. Compilar contrato:

   ./scripts/build.sh
   

3. Implantar na testnet:

   ./scripts/deploy.sh
   

4. Consultar contrato:

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

5. Atualizar contrato:

   ./scripts/upgrade.sh
   

Todo o histórico de deploy é rastreado em output/history.json para fácil referência.

Aprimoramento Automático de Contexto

O servidor MCP pode aprimorar automaticamente consultas com contexto relevante da Klever VM. Isso garante que seu cliente MCP sempre tenha acesso às informações mais relevantes.

Usando Aprimoramento de Contexto

Use a ferramenta enhance_with_context para adicionar automaticamente contexto relevante a qualquer consulta:

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

Isso irá:

1. Extrair palavras-chave relevantes da consulta
2. Pesquisar na base de conhecimento por contextos correspondentes
3. Retornar uma consulta aprimorada com contexto incluído
4. Fornecer metadados sobre o que foi encontrado

Padrão de Integração

Para clientes MCP que desejam sempre verificar o contexto Klever primeiro:

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

O recurso de aprimoramento de contexto enriquece automaticamente as consultas com conhecimento relevante da Klever VM da base de conhecimento abrangente.

Exemplos de Integração

Extensão 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'
  })
});

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

Contribuindo

Contribuições são bem-vindas! Por favor:

1. Faça um fork do repositório
2. Crie uma branch de funcionalidade
3. Faça suas alterações
4. Adicione testes
5. Envie um pull request

Licença

Licença MIT - veja o arquivo LICENSE para detalhes

Agradecimentos

• Inspirado pelo Context7 da Upstash
• Construído para a Klever Blockchain
• Utiliza o Klever VM SDK (Rust)