mcp-klever-vm

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

主要改进

1. 存储层

   • 为 InMemoryStorage 添加内存限制，避免 OOM
   • 优化 Redis 查询，避免使用 O(N) KEYS 命令
   • 为 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 服务可以托管为公共共享服务，让任何开发者都能连接，而无需在本地运行。

连接到公共服务

# 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 上投入生产使用：

• 将 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、网络管理）

存储与优化

• 存储映射器选择指南，包含性能对比
• 命名空间组织模式
• 用于高效查询的视图端点
• Gas 优化技巧
• OptionalValue 与 Option 模式

最佳实践与安全

• 输入验证模式
• 错误处理策略
• 管理和暂停模块的用法
• 访问控制模式
• 常见错误及解决方案

导入合约

使用内置的导入工具解析和导入 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

验证检查包括：

• 事件注解格式（双引号、驼峰命名）
• Managed 类型 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. 提供有关搜索结果的元数据

集成模式

对于希望始终先检查 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"]
    }
  }'

贡献

欢迎贡献！请：

1. Fork 此仓库
2. 创建功能分支
3. 进行更改
4. 添加测试
5. 提交拉取请求

许可证

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

致谢

• 灵感来自 Context7 by Upstash
• 为 Klever Blockchain 构建
• 使用 Klever VM SDK (Rust)