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, 네트워크 관리)

스토리지 및 최적화

성능 비교가 포함된 스토리지 매퍼 선택 가이드
네임스페이스 구성 패턴
효율적인 쿼리를 위한 View 엔드포인트
가스 최적화 기법
OptionalValue vs 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 type 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 파일을 참조하세요

감사의 말

Upstash의 Context7에서 영감을 받았습니다
Klever 블록체인을 위해 제작되었습니다
Klever VM SDK (Rust)를 사용합니다