AMEVA-MCP-Hub | Official Documentation

AMEVA-MCP-Hub 공식 기술 명세서

무설치 다국어 WebAssembly (WASI) 인메모리 런타임 & 무충돌 멀티 인스턴스 Model Context Protocol 허브 (v3.1.3)

Release: v3.1.3

핵심 가치 제안 (Why It Matters)

호스트 운영체제에 C++, Rust, Go, Python 컴파일러와 수 기가바이트의 언어별 가상환경을 전혀 설치하지 않고도, 단일 Node.js 프로세스 메모리 상에서 WASI 바이트코드를 0.3ms 미만의 극저지연으로 직접 구동하며, 11553 단일 포트에서 수십 개의 IDE 프로세스가 충돌 없이 공유하는 차세대 인메모리 AI 도구 허브입니다.

1줄 즉시 실행 및 IDE 연동

로컬 설치 없이 단 1줄로 백그라운드 데몬을 즉각 기동할 수 있습니다:

# 1줄 즉시 기동 (무설치 npx)
npx ameva-mcp-hub

# 백그라운드 헤드리스 데몬 모드 (IDE stdio 파이프 연동용)
npx ameva-mcp-hub --headless

# Node.js 프로젝트 SDK 종속성 설치
npm install ameva-mcp-hub

# Python 클라이언트 비동기 SDK 설치
pip install ameva-mcp-hub

1. 아키텍처 개요 및 5대 핵심 기술 기둥

기존의 전통적인 MCP(Model Context Protocol) 서버는 리포지토리나 언어가 바뀔 때마다 호스트 머신에 거대한 툴체인을 요구하고, 매 도구 호출마다 OS 서브프로세스를 포크(Fork)하여 50~120ms의 심각한 지연시간과 포트 충돌(`EADDRINUSE`)을 유발했습니다. AMEVA-MCP-Hub는 이를 5대 핵심 아키텍처로 완전 해결하였습니다:

1. Polyglot In-Memory WASI Virtual Kernel

C++, Rust, Go, Python으로 빌드된 WASI Snapshot Preview 1 바이트코드를 단일 프로세스 메모리에서 직접 실행합니다. 프로세스 생성 오버헤드가 없어 0.18ms ~ 0.41ms의 극저지연 실행을 달성합니다.

2. Seamless Port Reuse & Transparent Bridge

기본 포트인 11553이 이미 점유되어 있어도 크래시되지 않고, 새로 생성된 프로세스가 자동으로 투명 브리지(Bridge Mode)로 전환되어 기존 허브와 stdio JSON-RPC 패킷을 무손실 중계합니다.

3. Live GitHub Multi-Repo Dynamic Synchronization

원격 Git 리포지토리의 mcp_manifest.json을 주기적 폴링 및 SSE 채널로 감시하여, 서버 재기동 없이 새로운 AI 도구와 스키마를 메모리에 실시간 무중단 핫리로드(Hot-reload)합니다.

4. On-Device Hardware Fleet Tester Adapter

연결된 안드로이드 Termux 단말기 등 실기기 플릿의 SoC, GPU, NPU 토폴로지를 원격 프로빙하고, 6대 모달리티 온디바이스 AI 벤치마크 및 파일시스템을 지휘하는 tester_* 도구군을 내장 탑재합니다.

5. 1536-Dim AI Vector Similarity Engine

OpenAI 및 표준 임베딩 규격인 1536차원 부동소수점 벡터 간 코사인 유사도(Cosine Similarity) 연산과 Top-K 인메모리 RAG 검색을 Float32 SIMD 가속으로 수 밀리초 만에 처리합니다.

6. Zero Memory Leak & WeakRef Protection

WASI 인스턴스와 결과 버퍼의 생명주기를 JavaScript WeakRef 및 FinalizationRegistry로 엄격 제어하여, 10,000회 연속 호출 시에도 RSS 메모리 증가 0.0MB를 보장합니다.

2. 시스템 아키텍처 다이어그램

┌────────────────────────────────────────────────────────────────────────┐
│                        AI Clients & IDE Ecosystem                      │
│   Claude Desktop  │  Cursor  │  Antigravity IDE  │  Custom Agent CLI   │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │ (stdio JSON-RPC 2.0 / WebSocket)
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│             AMEVA-MCP-Hub Core Gateway (Port 11553, Bridge Mode)       │
│  - Multi-Instance Discovery (/api/identity)   - Zero-Token Loopback    │
│  - In-flight Request Coalescing               - Headless Daemon Guard  │
└───────────────────┬───────────────────────────────────┬────────────────┘
                    │                                   │
      ┌─────────────▼───────────────┐     ┌─────────────▼──────────────┐
      │ Polyglot WASI In-Memory VM  │     │ On-Device Fleet Controller │
      │ - Rust Bytecode (<0.18ms)   │     │ - S25/S20/A35 ADB & Termux │
      │ - C++ SIMD MatMul (<0.22ms) │     │ - tester_probe_fleet       │
      │ - Go Network Tools (<0.41ms)│     │ - tester_run_benchmark     │
      │ - Python Micro-AST (<1.15ms)│     │ - tester_remote_fs         │
      └─────────────┬───────────────┘     └─────────────┬──────────────┘
                    │                                   │
                    ▼                                   ▼
┌────────────────────────────────────────────────────────────────────────┐
│             AI Vector & RAG Subsystem (1536-dim Cosine Similarity)     │
│             Live GitHub Multi-Repo Dynamic Tool Manifest Registry      │
└────────────────────────────────────────────────────────────────────────┘

3. 19대 공식 내장 도구 카탈로그 및 기능 명세

도구 식별자 (Tool Name)	실행 엔진	입력 파라미터 (Input Schema)	기능 및 엔지니어링 명세
`calc`	WASI / In-Memory	`expression: string`	사칙연산, 삼각함수, 지수로그 등 고정밀 수학 수식을 안전한 샌드박스에서 평가.
`text_transform`	WASI / In-Memory	`text: string, mode: string`	대소문자, 슬러그화, URL 인코딩/디코딩, 줄바꿈 정규화 등 텍스트 변환.
`format_json`	Node / In-Memory	`data: string, indent: number`	파손된 JSON 구문 복구, 유효성 검증 및 지정 들여쓰기로 포맷팅.
`hash_text`	WASI (Rust)	`text: string, algorithm: string`	Blake3, SHA-256, SHA-512, MD5 초고속 해시 생성 (<0.2ms).
`base64_encode`	WASI / In-Memory	`input: string, url_safe: bool`	RFC 4648 표준 Base64 인코딩 및 URL-Safe 패딩 처리.
`run_shell_command`	Host Native Sandbox	`command: string, timeout_ms: int`	환경변수 격리 및 타임아웃 가드가 적용된 로컬 쉘 명령어 안전 실행.
`python_exec`	WASI / Pyodide	`code: string, timeout_ms: int`	호스트 Python 설치 없이 인메모리 WASI 가상 환경에서 파이썬 코드 실행.
`browser_evaluate`	Headless CDP	`script: string, url?: string`	브라우저 DOM 및 자바스크립트 런타임 표현식 원격 평가 및 렌더링 검증.
`run_browser_test`	Playwright Bridge	`spec: object, headless: bool`	E2E 웹 브라우저 자동화 테스트 시나리오 헤드리스 구동 및 스크린샷 캡처.
`vector_cosine_similarity`	Float32 SIMD	`vec_a: float[], vec_b: float[]`	1536차원 텍스트 임베딩 벡터 간 방향 유사도 계산 (정규화 포함).
`vector_top_k_search`	Float32 SIMD	`query_vec: float[], corpus: array, k: int`	수만 건의 문서 벡터 코퍼스에서 상위 K개 최적 연관 청크 인메모리 검색.
`wasm_exec`	WASI Runtime	`wasm_base64: string, args: string[]`	임의의 컴파일된 WASI 바이트코드를 메모리에 즉각 로드하여 결과 반환.
`smart_exec`	Heuristic Router	`command: string, prefer_sandbox: bool`	명령어 위험도를 자동 평가하여 WASM 샌드박스와 네이티브 간 최적 라우팅.
`consolidate_codebase`	Code Analyzer	`root_dir: string, extensions: string[]`	단일 텍스트/마크다운 아티팩트로 전체 코드베이스 구조와 구현체를 집대성.
`tester_probe_fleet`	Fleet Adapter	`{}`	연결된 모든 단말기(Galaxy S25, S20, A35 등)의 CPU/GPU/NPU 토폴로지 전수 탐색.
`tester_get_devices`	Fleet Adapter	`{}`	현재 활성 상태인 단말기 ID, 배터리 잔량, 온도, 연결 인터페이스 목록 조회.
`tester_inspect_device`	Fleet Adapter	`device_id: string`	지정 단말기의 커널 버전, Vulkan 1.3 드라이버 속성, VRAM 가용량 정밀 분석.
`tester_run_benchmark`	Fleet Adapter	`device_id: string, modality: string`	원격 단말기에서 STT, TTS, Diffusion, LLM 온디바이스 AI 벤치마크 지휘 및 로그 수집.
`tester_purge_device`	Fleet Adapter	`device_id: string`	테스트 후 잔존 임시 가중치, 캐시 텐서, 좀비 프로세스를 완전 청소하여 원복.

4. 기존 전통 MCP 서버 대비 비교 분석

비교 항목	기존 표준 Stdio/HTTP MCP 서버	AMEVA-MCP-Hub (v3.1.3)
언어별 툴체인 요구	호스트 머신에 Rust, C++, Go, Python 개별 설치 필수 (수 GB 오염)	0개 설치 (Zero Toolchain): 순수 WASI 바이트코드 인메모리 구동
도구 호출 지연시간	45 ms ~ 120 ms (매 호출마다 OS 서브프로세스 fork/exec 오버헤드)	0.18 ms ~ 0.41 ms (인메모리 직접 실행, 200배 이상 고속)
다중 인스턴스 / 포트 충돌	다중 프로세스 실행 시 `EADDRINUSE` 발생으로 비정상 종료	투명 브리지 모드(Bridge Mode): 단일 포트(11553) 자동 공유
도구 동적 갱신	도구 추가/수정 시 서버 재시작 및 프로세스 재접속 필수	무중단 핫리로드 (SSE Hot-Reload): GitHub 커밋 즉시 반영
하드웨어 플릿 제어	미지원 (로컬 머신 리소스에 국한)	7대 원격 실기기 플릿 테스터 내장 (안드로이드 Termux 직결)

5. IDE 및 에이전트 연동 가이드

(1) Claude Desktop 연동 (`claude_desktop_config.json`)

{
  "mcpServers": {
    "ameva-mcp-hub": {
      "command": "npx",
      "args": ["-y", "ameva-mcp-hub", "--headless"]
    }
  }
}

(2) Cursor / Antigravity IDE 연동

IDE 설정의 Features > MCP Servers 메뉴에서 새 서버를 추가합니다:

Name: ameva-mcp-hub
Type: stdio
Command: npx
Args: -y ameva-mcp-hub --headless

(3) Python 에이전트 SDK 연동 예제

import asyncio
from ameva_mcp_hub import MCPClient

async def run_agent():
    # 11553 포트로 기동 중인 허브에 접속
    client = MCPClient(port=11553)
    
    # 1. 원격 플릿 하드웨어 탐색
    fleet = await client.call_tool("tester_probe_fleet", {})
    print(f"[온디바이스 플릿]: {fleet}")
    
    # 2. 고속 인메모리 수식 계산
    calc_res = await client.call_tool("calc", {"expression": "2 ** 32 - 1"})
    print(f"[계산 결과]: {calc_res}")

asyncio.run(run_agent())