金大哥 - mcp-klever-vm MCP 详情

article

README

🚀 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 模式、最佳实践和示例。
🔧 合约验证：自动检测常见问题和反模式。
🚀 部署脚本：提供用于合约部署、升级和查询的即用型脚本。

📦 安装指南

克隆仓库：

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

💻 使用示例

基础用法

# 通过 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/             # 文档

主要改进

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

可用工具（公共模式）

公共服务器为安全起见，仅公开了一部分只读工具： | 工具 | 描述 | |------|-------------| | 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 进行自托管

# 构建并运行
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

环境变量（公共模式）

| 变量 | 默认值 | 描述 | |----------|---------|-------------| | 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 存储

# 首先，摄取知识库（一次性操作）
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：显示使用示例和可用命令

示例工作流程

初始化项目：

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

// 始终增强与 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)