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 コントラクトを解析してサンプルとパターンを抽出
🎯 関連性ランキング: コンテキストのインテリジェントなスコアリングとランキング
🔄 ライブアップデート: コンテキストのリアルタイム追加と更新
🛡️ 型安全性: Zod 検証付きの完全な TypeScript
📚 包括的なナレッジベース: 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 を防ぐためのメモリ制限を追加
- O(N) KEYS コマンドを回避するための Redis クエリの最適化
- 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) とシェルベースのツール (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 での本番環境向け:

TLS 終端のためにリバースプロキシ (nginx/Caddy/クラウド LB) の背後に Docker コンテナをデプロイ
プロキシが mcp-session-id ヘッダーを渡し、SSE をサポートすることを確認 (レスポンスバッファリングを無効化)
サーバーはインメモリナレッジベースの読み取り専用であるため、単一インスタンスで十分
DDoS 保護に Cloudflare を検討 (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 サーバーには、11 のカテゴリに分類された 95 以上のエントリを含む包括的なナレッジベースが含まれています:

重要なパターン

支払い処理とトークン操作
小数点変換と計算
イベント発行とパラメータルール
CLI ツールの使用法とベストプラクティス

コントラクトパターンとサンプル

基本的なコントラクト構造テンプレート
完全な宝くじゲームの実装
報酬付きステーキングコントラクト
クロスコントラクト通信パターン
リモートストレージアクセスパターン
トークンマッパーヘルパーモジュール

開発ツール

Koperator: 引数エンコーディングを含む完全な CLI リファレンス
KSC: ビルドコマンドとプロジェクトセットアップ
デプロイ、アップグレード、クエリスクリプト
インタラクティブなコントラクト管理ツール
共通ユーティリティライブラリ (bech32、ネットワーク管理)

ストレージと最適化

パフォーマンス比較付きのストレージマッパー選択ガイド
名前空間編成パターン
効率的なクエリのためのビューエンドポイント
ガス最適化テクニック
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

検証チェックには以下が含まれます:

イベントアノテーション形式 (ダブルクォート、camelCase)
Managed 型 API パラメータ
転送時のゼロアドレス検証
最適なストレージマッパーの選択
モジュール命名規則

使用例

1. スマートコントラクト開発アシスタント

IDE と統合して、Klever コントラクト開発のためのコンテキスト認識型の提案を提供します。

2. コードレビューツール

ベストプラクティスとセキュリティパターンに対してコントラクトを自動チェックします。

3. 学習プラットフォーム

Klever 開発を学ぶ開発者向けにサンプルと説明を提供します。

4. ドキュメントジェネレーター

コントラクトドキュメントを自動的に抽出して整理します。

プロジェクト仕様とサンプル

完全なプロジェクト実装例と仕様については、以下を参照してください:

プロジェクト仕様テンプレート - Klever スマートコントラクトプロジェクトを指定するための穴埋めテンプレート。MCP ナレッジ発見、タスク追跡、フェーズ実装を通じて AI アシスタントをガイドします。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"]
    }
  }'

貢献

貢献を歓迎します！以下の手順でお願いします：

リポジトリをフォークする
フィーチャーブランチを作成する
変更を加える
テストを追加する
プルリクエストを送信する

ライセンス

MITライセンス - 詳細はLICENSEファイルを参照

謝辞

Context7 by Upstash に触発されました
Klever Blockchain のために構築
Klever VM SDK (Rust) を使用