MCP Klever Vm

🚀 Klever MCP Server

Kleverブロックチェーンのスマートコントラクト開発に特化したモデルコンテキストプロトコル（MCP）サーバーです。このサーバーは、Klever VM SDKを使用する開発者に対して、コードパターン、ベストプラクティス、ランタイム動作などのコンテキスト知識を維持および提供します。

✨ 主な機能

• 🚀 3種類のモードで動作：HTTP APIサーバー、MCP標準入出力サーバー、またはパブリックホスト型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ルート
│   ├── 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. ストレージ層
   • 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ファイルを編集してサーバーを設定します。

# サーバーモード (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）とシェルベースのツール（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をサポートすることを確認します（レスポンスのバッファリングを無効にします）。
• サーバーは読み取り専用でメモリ内の知識ベースを持っているため、単一インスタンスで十分です。
• DDoS保護のためにCloudflareを検討してください（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スマートコントラクトプロジェクトを指定するための入力式テンプレートです。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：使用例と利用可能なコマンドを表示します。

サンプルワークフロー

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

コントリビューション

コントリビューションは大歓迎です！以下の手順を踏んでください。

1. リポジトリをフォークします。
2. 機能ブランチを作成します。
3. 変更を加えます。
4. テストを追加します。
5. プルリクエストを送信します。

📄 ライセンス

MITライセンス - 詳細はLICENSEファイルを参照してください。

謝辞

• Context7 by Upstashにインスピレーションを得ています。
• Klever Blockchain向けに構築されています。
• Klever VM SDK (Rust)を使用しています。