Klever VM MCP Server

chính thức

MCP server for [Klever](https://klever.org) blockchain smart contract development, on-chain data exploration, and VM interaction. Public remote server available at `https://mcp.klever.org/mcp`.

GitHub

Tài liệu

Klever VM MCP Server

Máy chủ Model Context Protocol (MCP) được thiết kế riêng cho phát triển hợp đồng thông minh trên blockchain Klever. Máy chủ này duy trì và phục vụ kiến thức ngữ cảnh bao gồm các mẫu mã, thực tiễn tốt nhất và hành vi thời gian chạy cho các nhà phát triển làm việc với Klever VM SDK.

Tính năng

🚀 Hoạt động ba chế độ: Chạy dưới dạng máy chủ HTTP API, máy chủ MCP stdio hoặc máy chủ MCP được lưu trữ công khai
💾 Lưu trữ linh hoạt: Hỗ trợ phụ trợ trong bộ nhớ hoặc Redis
🔍 Truy xuất ngữ cảnh thông minh: Truy vấn theo loại, thẻ hoặc loại hợp đồng
📝 Trích xuất mẫu tự động: Phân tích cú pháp hợp đồng Klever để trích xuất ví dụ và mẫu
🎯 Xếp hạng mức độ liên quan: Chấm điểm và xếp hạng ngữ cảnh thông minh
🔄 Cập nhật trực tiếp: Thêm và cập nhật ngữ cảnh theo thời gian thực
🛡️ An toàn kiểu: TypeScript đầy đủ với xác thực Zod
📚 Cơ sở kiến thức toàn diện: Được tải sẵn các mẫu, thực tiễn tốt nhất và ví dụ của Klever VM
🔧 Xác thực hợp đồng: Tự động phát hiện các vấn đề phổ biến và phản mẫu
🚀 Tập lệnh triển khai: Các tập lệnh sẵn sàng sử dụng để triển khai, nâng cấp và truy vấn hợp đồng

Bắt đầu nhanh

Cài đặt và chạy ngay lập tức qua npx — không cần sao chép:

npx -y @klever/mcp-server

Hoặc kết nối với máy chủ công khai được lưu trữ:

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

Xem Tích hợp MCP Client để biết cấu hình cụ thể cho từng client.

Kiến trúc

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

Các cải tiến chính đã thực hiện

Lớp lưu trữ
- Đã thêm giới hạn bộ nhớ để ngăn OOM trong InMemoryStorage
- Tối ưu hóa truy vấn Redis để tránh lệnh KEYS O(N)
- Đã thêm giao dịch nguyên tử cho các thao tác Redis
- Cải thiện xử lý lỗi và xác thực
Bảo mật API
- Đã thêm xác thực đầu vào cho tất cả các điểm cuối
- Giới hạn kích thước thao tác hàng loạt
- Phản hồi lỗi phù hợp mà không làm rò rỉ nội bộ
- Thông báo lỗi nhận biết môi trường
An toàn kiểu
- Xác thực lược đồ tập trung
- Giao diện TypeScript phù hợp cho các tùy chọn
- Xác thực thời gian chạy của dữ liệu đã lưu trữ
Hiệu suất
- Thao tác hàng loạt sử dụng Redis MGET
- Truy vấn dựa trên chỉ mục thay vì quét toàn bộ
- Tối ưu hóa thao tác đếm

Cài đặt

Sao chép kho lưu trữ:

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

Cài đặt các phụ thuộc:

pnpm install

Sao chép cấu hình môi trường:

cp .env.example .env

Cài đặt công cụ Klever SDK (cần thiết cho giao dịch):

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

Xây dựng dự án:

pnpm run build

Cấu hình

Chỉnh sửa tệp .env để cấu hình máy chủ:

# 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

Tích hợp MCP Client

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

Thêm vào claude_desktop_config.json của bạn:

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

Để thiết lập chi tiết, xem Hướng dẫn cài đặt Claude Desktop.

Cursor

Thêm vào cài đặt Cursor MCP của bạn (.cursor/mcp.json):

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

VS Code (GitHub Copilot)

Thêm vào .vscode/mcp.json trong dự án của bạn:

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

Để thiết lập chi tiết, xem Hướng dẫn cài đặt VS Code.

Máy chủ MCP công khai

Klever MCP Server có thể được lưu trữ dưới dạng dịch vụ chia sẻ công khai, cho phép bất kỳ nhà phát triển nào kết nối mà không cần chạy cục bộ.

Kết nối với máy chủ công khai

# 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

Công cụ khả dụng (Chế độ công khai)

Máy chủ công khai chỉ hiển thị một tập hợp con công cụ chỉ đọc vì lý do bảo mật:

Công cụ	Mô tả
`query_context`	Tìm kiếm cơ sở kiến thức Klever VM
`get_context`	Truy xuất ngữ cảnh cụ thể theo ID
`find_similar`	Tìm ngữ cảnh tương tự với ngữ cảnh đã cho
`get_knowledge_stats`	Nhận thống kê cơ sở kiến thức
`enhance_with_context`	Nâng cao truy vấn với ngữ cảnh Klever VM liên quan

Các thao tác ghi (add_context) và công cụ dựa trên shell (init_klever_project, add_helper_scripts) bị vô hiệu hóa ở chế độ công khai.

Tự lưu trữ với 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

Sau đó kết nối:

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

Tự lưu trữ không cần Docker

pnpm install
pnpm run build
pnpm run start:public

Biến môi trường (Chế độ công khai)

Biến	Mặc định	Mô tả
`MODE`	`http`	Đặt thành `public` cho chế độ lưu trữ
`PORT`	`3000`	Cổng máy chủ
`CORS_ORIGINS`	(chưa đặt)	Nguồn gốc được phép phân cách bằng dấu phẩy. Chưa đặt hoặc `*` cho phép tất cả nguồn gốc
`RATE_LIMIT_MCP`	`60`	Yêu cầu điểm cuối MCP mỗi phút trên mỗi IP
`RATE_LIMIT_API`	`30`	Yêu cầu điểm cuối API mỗi phút trên mỗi IP
`BODY_SIZE_LIMIT`	`1mb`	Kích thước tối đa thân yêu cầu

Ghi chú triển khai

Đối với sản xuất tại mcp.klever.org:

Triển khai container Docker phía sau proxy ngược (nginx/Caddy/cloud LB) để kết thúc TLS
Đảm bảo proxy chuyển tiếp tiêu đề mcp-session-id và hỗ trợ SSE (vô hiệu hóa đệm phản hồi)
Một phiên bản duy nhất là đủ vì máy chủ chỉ đọc với cơ sở kiến thức trong bộ nhớ
Cân nhắc Cloudflare để bảo vệ DDoS (SSE được hỗ trợ)

Sử dụng

Tải cơ sở kiến thức

Máy chủ tự động tải cơ sở kiến thức Klever dựa trên loại lưu trữ của bạn:

Lưu trữ bộ nhớ (Mặc định)

Kiến thức được tự động tải khi máy chủ khởi động
Không cần chạy pnpm run ingest riêng biệt
Dữ liệu chỉ tồn tại khi máy chủ đang chạy
Tốt nhất cho phát triển và kiểm thử

Lưu trữ Redis

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

# Then start the server
pnpm run dev

Kiến thức tồn tại lâu dài trong cơ sở dữ liệu Redis
Tồn tại qua các lần khởi động lại máy chủ
Tốt nhất cho sử dụng sản xuất

Điều này sẽ tải:

Mẫu và ví dụ hợp đồng thông minh
Quy tắc chú thích và thực tiễn tốt nhất
Mẫu ánh xạ lưu trữ và so sánh
Tập lệnh triển khai và truy vấn
Lỗi phổ biến và giải pháp
Mẫu kiểm thử
Tài liệu tham khảo API

Chạy dưới dạng máy chủ HTTP

# Development mode
pnpm run dev

# Production mode
pnpm run build && pnpm start

API HTTP sẽ khả dụng tại http://localhost:3000/api

Chạy dưới dạng máy chủ MCP

MODE=mcp pnpm start

Sử dụng với bất kỳ client tương thích MCP nào.

Điểm cuối API

POST `/api/context`

Nhập ngữ cảnh mới vào hệ thống.

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

Truy xuất ngữ cảnh cụ thể theo ID.

POST `/api/context/query`

Truy vấn ngữ cảnh với bộ lọc.

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

PUT `/api/context/:id`

Cập nhật ngữ cảnh hiện có.

DELETE `/api/context/:id`

Xóa ngữ cảnh.

GET `/api/context/:id/similar`

Tìm ngữ cảnh tương tự.

POST `/api/context/batch`

Nhập hàng loạt nhiều ngữ cảnh.

Công cụ MCP

Khi chạy dưới dạng máy chủ MCP, các công cụ sau khả dụng:

query_context: Tìm kiếm ngữ cảnh phát triển Klever liên quan
add_context: Thêm ngữ cảnh mới vào cơ sở kiến thức
get_context: Truy xuất ngữ cảnh cụ thể theo ID
find_similar: Tìm ngữ cảnh tương tự với ngữ cảnh đã cho
get_knowledge_stats: Nhận thống kê về cơ sở kiến thức
init_klever_project: Khởi tạo dự án hợp đồng thông minh Klever mới với các tập lệnh trợ giúp
enhance_with_context: Tự động nâng cao truy vấn với ngữ cảnh Klever VM liên quan

Loại ngữ cảnh

code_example: Đoạn mã và ví dụ đang hoạt động (mã hợp đồng thông minh Rust)
best_practice: Mẫu và thực tiễn được khuyến nghị
security_tip: Cân nhắc bảo mật và cảnh báo
optimization: Kỹ thuật tối ưu hóa hiệu suất
documentation: Tài liệu và hướng dẫn chung
error_pattern: Lỗi phổ biến và giải pháp
deployment_tool: Tập lệnh triển khai và tiện ích (tập lệnh bash, công cụ)
runtime_behavior: Giải thích hành vi thời gian chạy

Cơ sở kiến thức được tải sẵn

Máy chủ MCP bao gồm cơ sở kiến thức toàn diện với hơn 95 mục được tổ chức thành 11 danh mục:

Mẫu quan trọng

Xử lý thanh toán và thao tác token
Chuyển đổi thập phân và tính toán
Quy tắc phát sự kiện và tham số
Sử dụng công cụ CLI và thực tiễn tốt nhất

Mẫu hợp đồng & Ví dụ

Mẫu cấu trúc hợp đồng cơ bản
Triển khai trò chơi xổ số hoàn chỉnh
Hợp đồng staking với phần thưởng
Mẫu giao tiếp liên hợp đồng
Mẫu truy cập lưu trữ từ xa
Mô-đun trợ giúp ánh xạ token

Công cụ phát triển

Koperator: Tham chiếu CLI đầy đủ với mã hóa đối số
KSC: Lệnh xây dựng và thiết lập dự án
Tập lệnh triển khai, nâng cấp và truy vấn
Công cụ quản lý hợp đồng tương tác
Thư viện tiện ích chung (bech32, quản lý mạng)

Lưu trữ & Tối ưu hóa

Hướng dẫn chọn ánh xạ lưu trữ với so sánh hiệu suất
Mẫu tổ chức không gian tên
Điểm cuối xem để truy vấn hiệu quả
Kỹ thuật tối ưu hóa gas
Mẫu OptionalValue vs Option

Thực tiễn tốt nhất & Bảo mật

Mẫu xác thực đầu vào
Chiến lược xử lý lỗi
Sử dụng mô-đun quản trị và tạm dừng
Mẫu kiểm soát truy cập
Lỗi phổ biến và giải pháp

Nhập hợp đồng

Sử dụng tiện ích nhập tích hợp để phân tích cú pháp và nhập hợp đồng 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();

Phát triển

# 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

Xác thực hợp đồng

Máy chủ có thể tự động xác thực hợp đồng Klever và phát hiện vấn đề:

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

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

Kiểm tra xác thực bao gồm:

Định dạng chú thích sự kiện (dấu ngoặc kép, camelCase)
Tham số API kiểu được quản lý
Xác thực địa chỉ zero trong chuyển khoản
Lựa chọn ánh xạ lưu trữ tối ưu
Quy ước đặt tên mô-đun

Trường hợp sử dụng ví dụ

1. Trợ lý phát triển hợp đồng thông minh

Tích hợp với IDE của bạn để cung cấp gợi ý nhận biết ngữ cảnh cho phát triển hợp đồng Klever.

2. Công cụ xem xét mã

Tự động kiểm tra hợp đồng dựa trên thực tiễn tốt nhất và mẫu bảo mật.

3. Nền tảng học tập

Cung cấp ví dụ và giải thích cho nhà phát triển học phát triển Klever.

4. Trình tạo tài liệu

Trích xuất và tổ chức tài liệu hợp đồng tự động.

Đặc tả dự án và Ví dụ

Để biết ví dụ và đặc tả triển khai dự án hoàn chỉnh, xem:

Mẫu đặc tả dự án - Mẫu điền vào để đặc tả dự án hợp đồng thông minh Klever. Hướng dẫn trợ lý AI thông qua khám phá kiến thức MCP, theo dõi nhiệm vụ và triển khai theo giai đoạn. Bao gồm ví dụ KleverDice.

Khởi tạo dự án

Máy chủ MCP bao gồm công cụ khởi tạo dự án mạnh mẽ tạo dự án hợp đồng thông minh Klever mới với tất cả các tập lệnh trợ giúp cần thiết.

Sử dụng công cụ init_klever_project

Khi kết nối qua MCP, sử dụng công cụ init_klever_project:

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

Tham số:

name (bắt buộc): Tên hợp đồng của bạn
template (tùy chọn): Mẫu để sử dụng (mặc định: "empty")
noMove (tùy chọn): Nếu true, giữ dự án trong thư mục con (mặc định: false)

Tập lệnh trợ giúp được tạo

Công cụ tạo các tập lệnh sau trong thư mục scripts/:

build.sh: Xây dựng hợp đồng thông minh
deploy.sh: Triển khai lên Klever testnet với tự động phát hiện artifact hợp đồng
upgrade.sh: Nâng cấp hợp đồng hiện có (tự động phát hiện từ history.json)
query.sh: Truy vấn điểm cuối hợp đồng với mã hóa/giải mã phù hợp
test.sh: Chạy kiểm thử hợp đồng
interact.sh: Hiển thị ví dụ sử dụng và lệnh khả dụng

Quy trình làm việc ví dụ

Khởi tạo dự án:

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

Xây dựng hợp đồng:
```
./scripts/build.sh
```
Triển khai lên testnet:
```
./scripts/deploy.sh
```

Truy vấn hợp đồng:

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

Nâng cấp hợp đồng:
```
./scripts/upgrade.sh
```

Tất cả lịch sử triển khai được theo dõi trong output/history.json để tham khảo dễ dàng.

Tự động nâng cao ngữ cảnh

Máy chủ MCP có thể tự động nâng cao truy vấn với ngữ cảnh Klever VM liên quan. Điều này đảm bảo client MCP của bạn luôn có quyền truy cập vào thông tin liên quan nhất.

Sử dụng nâng cao ngữ cảnh

Sử dụng công cụ enhance_with_context để tự động thêm ngữ cảnh liên quan vào bất kỳ truy vấn nào:

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

Điều này sẽ:

Trích xuất từ khóa liên quan từ truy vấn
Tìm kiếm cơ sở kiến thức cho ngữ cảnh phù hợp
Trả về truy vấn nâng cao với ngữ cảnh được bao gồm
Cung cấp siêu dữ liệu về những gì đã tìm thấy

Mẫu tích hợp

Đối với client MCP muốn luôn kiểm tra ngữ cảnh Klever trước:

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

Tính năng nâng cao ngữ cảnh tự động làm giàu truy vấn với kiến thức Klever VM liên quan từ cơ sở kiến thức toàn diện.

Ví dụ tích hợp

Tiện ích mở rộng 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'
  })
});

Công cụ 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"]
    }
  }'

Đóng góp

Các đóng góp đều được hoan nghênh! Vui lòng:

Fork kho lưu trữ
Tạo một nhánh tính năng
Thực hiện các thay đổi của bạn
Thêm các bài kiểm thử
Gửi một pull request

Giấy phép

Giấy phép MIT - xem tệp LICENSE để biết chi tiết

Lời cảm ơn

Lấy cảm hứng từ Context7 by Upstash
Được xây dựng cho Klever Blockchain
Sử dụng Klever VM SDK (Rust)

Klever VM MCP Server

Tài liệu

Klever VM MCP Server

Tính năng

Bắt đầu nhanh

Kiến trúc

Các cải tiến chính đã thực hiện

Cài đặt

Cấu hình

Tích hợp MCP Client

Claude Code

Claude Desktop

Cursor

VS Code (GitHub Copilot)

Máy chủ MCP công khai

Kết nối với máy chủ công khai

Công cụ khả dụng (Chế độ công khai)

Tự lưu trữ với Docker

Tự lưu trữ không cần Docker

Biến môi trường (Chế độ công khai)

Ghi chú triển khai

Sử dụng

Tải cơ sở kiến thức

Lưu trữ bộ nhớ (Mặc định)

Lưu trữ Redis

Chạy dưới dạng máy chủ HTTP

Chạy dưới dạng máy chủ MCP

Điểm cuối API

POST /api/context

GET /api/context/:id

POST /api/context/query

PUT /api/context/:id

DELETE /api/context/:id

GET /api/context/:id/similar

POST /api/context/batch

Công cụ MCP

Loại ngữ cảnh

Cơ sở kiến thức được tải sẵn

Mẫu quan trọng

Mẫu hợp đồng & Ví dụ

Công cụ phát triển

Lưu trữ & Tối ưu hóa

Thực tiễn tốt nhất & Bảo mật

Nhập hợp đồng

Phát triển

Xác thực hợp đồng

Trường hợp sử dụng ví dụ

1. Trợ lý phát triển hợp đồng thông minh

2. Công cụ xem xét mã

3. Nền tảng học tập

4. Trình tạo tài liệu

Đặc tả dự án và Ví dụ

Khởi tạo dự án

Sử dụng công cụ init_klever_project

Tập lệnh trợ giúp được tạo

Quy trình làm việc ví dụ

Tự động nâng cao ngữ cảnh

Sử dụng nâng cao ngữ cảnh

Mẫu tích hợp

Ví dụ tích hợp

Tiện ích mở rộng VS Code

Công cụ CLI

Đóng góp

Giấy phép

Lời cảm ơn

POST `/api/context`

GET `/api/context/:id`

POST `/api/context/query`

PUT `/api/context/:id`

DELETE `/api/context/:id`

GET `/api/context/:id/similar`

POST `/api/context/batch`