Klever VM MCP Server

官方

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

文档

Klever MCP 服务器

一个专为 Klever 区块链智能合约开发定制的模型上下文协议（MCP）服务器。该服务器维护并提供上下文知识，包括代码模式、最佳实践以及运行时行为，供使用 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

主要改进

存储层
- 为 InMemoryStorage 添加内存限制以防止 OOM
- 优化 Redis 查询以避免 O(N) KEYS 命令
- 为 Redis 操作添加原子事务
- 改进错误处理和验证
API 安全
- 为所有端点添加输入验证
- 批量操作大小限制
- 适当的错误响应，不泄露内部信息
- 环境感知的错误消息
类型安全
- 集中式模式验证
- 选项的适当 TypeScript 接口
- 存储数据的运行时验证
性能
- 使用 Redis MGET 进行批量操作
- 基于索引的查询而非全扫描
- 优化的计数操作

安装

克隆仓库：

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

安装依赖：

pnpm install

复制环境配置：

cp .env.example .env

安装 Klever SDK 工具（交易所需）：

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

构建项目：

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 服务器可以作为公共共享服务托管，允许任何开发者无需本地运行即可连接。

连接到公共服务器

# 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）和基于 shell 的工具（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`	每个 IP 的 MCP 端点请求数/分钟
`RATE_LIMIT_API`	`30`	每个 IP 的 API 端点请求数/分钟
`BODY_SIZE_LIMIT`	`1mb`	最大请求体大小

部署说明

对于 mcp.klever.org 的生产环境：

在反向代理（nginx/Caddy/云负载均衡器）后部署 Docker 容器以进行 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、网络管理）

存储与优化

存储映射器选择指南及性能比较
命名空间组织模式
用于高效查询的视图端点
Gas 优化技术
OptionalValue 与 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

验证检查包括：

事件注解格式（双引号、驼峰命名）
托管类型 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：显示使用示例和可用命令

示例工作流

初始化项目：

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

构建合约：
```
./scripts/build.sh
```
部署到测试网：
```
./scripts/deploy.sh
```

查询合约：

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

升级合约：
```
./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
  }
}

这将：

从查询中提取相关关键词
在知识库中搜索匹配的上下文
返回包含上下文的增强查询
提供有关找到内容的元数据

集成模式

对于希望始终首先检查 Klever 上下文的 MCP 客户端：

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

贡献

欢迎贡献！请按以下步骤操作：

Fork 本仓库
创建一个功能分支
进行你的修改
添加测试
提交 Pull Request

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件

致谢

灵感来源于 Context7 by Upstash
为 Klever 区块链构建
使用 Klever VM SDK (Rust)