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)