MCP Klever Vm

🚀 Klever MCP 服务器

Klever MCP 服务器是一款专门为 Klever 区块链智能合约开发设计的模型上下文协议（MCP）服务器。它为使用 Klever VM SDK 的开发者维护并提供包括代码模式、最佳实践和运行时行为等在内的上下文知识。

🚀 快速开始

你可以通过 npx 立即安装并运行该服务器，无需克隆仓库：

npx -y @klever/mcp-server

或者连接到托管的公共服务器：

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

有关客户端特定的配置，请参阅 MCP 客户端集成。

✨ 主要特性

• 🚀 三种模式运行：可作为 HTTP API 服务器、MCP 标准输入输出服务器或公共托管的 MCP 服务器运行。
• 💾 灵活的存储方式：支持内存或 Redis 后端存储。
• 🔍 智能上下文检索：可按类型、标签或合约类型进行查询。
• 📝 自动模式提取：解析 Klever 合约以提取示例和模式。
• 🎯 相关性排序：对上下文进行智能评分和排序。
• 🔄 实时更新：可实时添加和更新上下文。
• 🛡️ 类型安全：完全使用 TypeScript 并通过 Zod 进行验证。
• 📚 全面的知识库：预加载了 Klever VM 模式、最佳实践和示例。
• 🔧 合约验证：自动检测常见问题和反模式。
• 🚀 部署脚本：提供用于合约部署、升级和查询的即用型脚本。

📦 安装指南

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

💻 使用示例

基础用法

# 通过 npx 安装（推荐）
claude mcp add klever-vm -- npx -y @klever/mcp-server

# 或者连接到公共托管服务器
claude mcp add -t http klever-vm https://mcp.klever.org/mcp

高级用法

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

📚 详细文档

架构

mcp-klever-vm/
├── src/
│   ├── api/          # 带有验证的 HTTP API 路由
│   ├── context/      # 上下文管理服务层
│   ├── mcp/          # MCP 协议服务器实现
│   ├── parsers/      # Klever 合约解析器和验证器
│   ├── storage/      # 存储后端（内存/Redis）
│   │   ├── memory.ts # 带有大小限制的内存存储
│   │   └── redis.ts  # 具有优化查询的 Redis 存储
│   ├── types/        # TypeScript 类型定义
│   ├── utils/        # 实用工具和摄取工具
│   └── knowledge/    # 模块化知识库（95+ 条目）
│       ├── core/     # 核心概念和导入
│       ├── storage/  # 存储模式和映射器
│       ├── events/   # 事件处理和规则
│       ├── tokens/   # 代币操作和小数
│       ├── modules/  # 内置模块（管理员、暂停）
│       ├── tools/    # CLI 工具（koperator, ksc）
│       ├── scripts/  # 辅助脚本
│       ├── examples/ # 完整的合约示例
│       ├── errors/   # 错误模式
│       ├── best-practices/ # 优化和验证
│       └── documentation/  # API 参考
├── tests/            # 测试文件
└── docs/             # 文档

主要改进

1. 存储层
   • 为内存存储添加了内存限制，以防止内存溢出。
   • 优化了 Redis 查询，避免使用 O(N) 的 KEYS 命令。
   • 为 Redis 操作添加了原子事务。
   • 改进了错误处理和验证。
2. API 安全
   • 为所有端点添加了输入验证。
   • 限制了批量操作的大小。
   • 提供了适当的错误响应，不泄露内部信息。
   • 提供了与环境相关的错误消息。
3. 类型安全
   • 集中化了模式验证。
   • 为选项提供了适当的 TypeScript 接口。
   • 对存储的数据进行运行时验证。
4. 性能
   • 使用 Redis MGET 进行批量操作。
   • 使用基于索引的查询代替全量扫描。
   • 优化了计数操作。

配置

编辑 .env 文件以配置服务器：

# 服务器模式 (http, mcp, 或 public)
MODE=http

# HTTP 服务器端口 (仅适用于 http 模式)
PORT=3000

# 存储后端 (memory 或 redis)
STORAGE_TYPE=memory

# 内存存储的最大上下文数量 (默认: 10000)
MEMORY_MAX_SIZE=10000

# Redis URL (仅当 STORAGE_TYPE=redis 时)
REDIS_URL=redis://localhost:6379

# 节点环境 (development 或 production)
NODE_ENV=development

MCP 客户端集成

Claude Code

# 通过 npx 添加（推荐）
claude mcp add klever-vm -- npx -y @klever/mcp-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 服务器可以作为公共共享服务进行托管，允许任何开发者无需在本地运行即可连接。

连接到公共服务器

# 永久添加（用户级别）
claude mcp add -t http klever-vm https://mcp.klever.org/mcp

# 仅为当前项目添加
claude mcp add -t http -s project klever-vm https://mcp.klever.org/mcp

可用工具（公共模式）

公共服务器为安全起见，仅公开了一部分只读工具：

写操作（add_context）和基于 shell 的工具（init_klever_project、add_helper_scripts）在公共模式下被禁用。

使用 Docker 进行自托管

# 构建并运行
docker build -t mcp-klever-vm .
docker run -p 3000:3000 mcp-klever-vm

# 或者使用 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

环境变量（公共模式）

部署注意事项

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

• 在反向代理（nginx/Caddy/云负载均衡器）后面部署 Docker 容器以进行 TLS 终止。
• 确保代理传递 mcp-session-id 头并支持 SSE（禁用响应缓冲）。
• 由于服务器是只读的且使用内存知识库，单个实例就足够了。
• 考虑使用 Cloudflare 进行 DDoS 保护（支持 SSE）。

使用方法

知识库加载

服务器会根据你的存储类型自动加载 Klever 知识库：

内存存储（默认）

• 服务器启动时会自动加载知识。
• 无需单独运行 pnpm run ingest。
• 数据仅在服务器运行时存在。
• 最适合开发和测试。

Redis 存储

# 首先，摄取知识库（一次性操作）
pnpm run ingest

# 然后启动服务器
pnpm run dev

• 知识会持久保存在 Redis 数据库中。
• 服务器重启后数据仍然存在。
• 最适合生产环境使用。

这将加载：

• 智能合约模板和示例
• 注释规则和最佳实践
• 存储映射器模式和比较
• 部署和查询脚本
• 常见错误和解决方案
• 测试模式
• API 参考文档

作为 HTTP 服务器运行

# 开发模式
pnpm run dev

# 生产模式
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、网络管理）

存储与优化

• 存储映射器选择指南和性能比较
• 命名空间组织模式
• 高效查询的视图端点
• 燃气优化技术
• 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);

// 摄取单个合约
await ingester.ingestContract('./path/to/contract.rs', 'AuthorName');

// 摄取整个目录
await ingester.ingestDirectory('./contracts', 'AuthorName');

// 添加常见模式
await ingester.ingestCommonPatterns();

开发

# 运行测试
pnpm test

# 代码检查
pnpm run lint

# 代码格式化
pnpm run format

# 监听模式
pnpm run dev

# 摄取/更新知识库
pnpm run ingest

合约验证

服务器可以自动验证 Klever 合约并检测问题：

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

const issues = KleverValidator.validateContract(contractCode);
// 返回检测到的问题数组及建议

验证检查包括：

• 事件注释格式（双引号、驼峰命名法）
• 托管类型 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. 初始化项目：

# 通过 MCP 工具
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 客户端：

// 始终增强与 Klever 相关的查询
if (query.match(/klever|kvm|smart contract|endpoint/i)) {
  const enhanced = await callTool('enhance_with_context', { query });
  // 使用 enhanced.enhancedQuery 进行处理
}

上下文增强功能会自动使用综合知识库中相关的 Klever VM 知识丰富查询。

集成示例

VS Code 扩展

// 查询代币转账示例
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 工具

# 使用 curl 添加上下文
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"]
    }
  }'

🔧 技术细节

存储层

在存储层方面，为了防止内存存储出现内存溢出问题，添加了内存限制。同时，对 Redis 查询进行了优化，避免使用复杂度为 O(N) 的 KEYS 命令，并且为 Redis 操作添加了原子事务，还改进了错误处理和验证机制，提高了存储操作的稳定性和效率。

API 安全

API 安全上，为所有端点添加了输入验证，限制了批量操作的大小，确保不会因大量请求或异常输入导致系统崩溃。提供了适当的错误响应，避免泄露内部信息，并且错误消息会根据不同的环境进行调整，增强了系统的安全性和可维护性。

类型安全

类型安全方面，采用了集中化的模式验证，为选项提供了合适的 TypeScript 接口，并且对存储的数据进行运行时验证，保证了数据的准确性和一致性，减少了因类型错误导致的潜在问题。

性能优化

性能优化上，使用 Redis MGET 进行批量操作，提高了数据获取的效率。采用基于索引的查询代替全量扫描，减少了查询时间。同时，对计数操作进行了优化，提升了系统整体的响应速度。

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

致谢

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