mcp-klever-vm

Klever MCP サーバー

Klever ブロックチェーンのスマートコントラクト開発に特化した Model Context Protocol (MCP) サーバーです。このサーバーは、Klever VM SDK を使用する開発者向けに、コードパターン、ベストプラクティス、ランタイム動作などのコンテキスト知識を保持し提供します。

機能

• 🚀 3 つのモードで動作: 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

主な改善点

1. ストレージレイヤー

   • InMemoryStorage で OOM を防ぐためのメモリ制限を追加
   • O(N) の KEYS コマンドを避けるために Redis クエリを最適化
   • 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) およびシェルベースのツール (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	API エンドポイントリクエスト数/分
BODY_SIZE_LIMIT	1mb	リクエストボディの最大サイズ

デプロイに関する注意事項

mcp.klever.org での本番運用について:

• TLS 終端のために、リバースプロキシ (nginx/Caddy/クラウド LB) の背後に Docker コンテナをデプロイします
• プロキシが mcp-session ヘッダーを転送し、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: 使用例と利用可能なコマンドを表示します

ワークフローの例

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'
  })
});

コマンドラインツール

# 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. リポジトリをフォークする
2. フィーチャーブランチを作成する
3. 変更を加える
4. テストを追加する
5. プルリクエストを送信する

ライセンス

MIT ライセンス - 詳細は LICENSE ファイルをご覧ください

謝辞

• Context7 by Upstash にインスパイアされました
• Klever Blockchain 向けに構築されました
• Klever VM SDK (Rust) を使用しています