Klever VM MCP Server

Klever MCP 伺服器

一個專為 Klever 區塊鏈智能合約開發量身打造的模型上下文協定 (MCP) 伺服器。此伺服器維護並提供上下文知識，包括程式碼模式、最佳實務以及執行期行為，供使用 Klever VM SDK 的開發者參考。

功能特色

• 🚀 三模式運作：可作為 HTTP API 伺服器、MCP stdio 伺服器或公開託管的 MCP 伺服器執行
• 💾 彈性儲存：支援記憶體內或 Redis 後端
• 🔍 智慧上下文檢索：按類型、標籤或合約類型查詢
• 📝 自動模式擷取：解析 Klever 合約以擷取範例和模式
• 🎯 相關性排名：智慧評分與上下文排名
• 🔄 即時更新：即時新增和更新上下文
• 🛡️ 型別安全：完整的 TypeScript 搭配 Zod 驗證
• 📚 全面的知識庫：預先載入 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
   • 最佳化 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 檔案以設定伺服器：

# 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) 和基於 shell 的工具 (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 的生產環境：

• 在反向代理（nginx/Caddy/雲端負載平衡器）後方部署 Docker 容器以進行 TLS 終止
• 確保代理傳遞 mcp-session-id 標頭並支援 SSE（停用回應緩衝）
• 由於伺服器是唯讀且使用記憶體內知識庫，單一執行個體即足夠
• 考慮使用 Cloudflare 進行 DDoS 防護（支援 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 伺服器包含一個全面的知識庫，擁有 95 個以上的條目，分為 11 個類別：

關鍵模式

• 付款處理和代幣操作
• 十進位轉換和計算
• 事件發射和參數規則
• CLI 工具使用和最佳實務

合約模式與範例

• 基本合約結構範本
• 完整的樂透遊戲實作
• 附帶獎勵的質押合約
• 跨合約通訊模式
• 遠端儲存存取模式
• 代幣對應器輔助模組

開發工具

• Koperator：包含引數編碼的完整 CLI 參考
• KSC：建置指令和專案設定
• 部署、升級和查詢腳本
• 互動式合約管理工具
• 常用工具庫（bech32、網路管理）

儲存與最佳化

• 附帶效能比較的儲存對應器選擇指南
• 命名空間組織模式
• 用於高效查詢的視圖端點
• Gas 最佳化技術
• 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);

// 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）
• 受控型別 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. 初始化專案：

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

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

貢獻

歡迎貢獻！請按照以下步驟：

1. Fork 此儲存庫
2. 建立功能分支
3. 進行你的修改
4. 加入測試
5. 提交 Pull Request

授權條款

MIT 授權條款 - 詳情請參閱 LICENSE 檔案

致謝

• 靈感來自 Upstash 的 Context7
• 為 Klever 區塊鏈 打造
• 使用 Klever VM SDK (Rust)