API 인터페이스 명세서 & 프로토콜 규격

npm SDK 내보내기, MCP 프로토콜 동작, HTTP/WebSocket 브리지 (AMV-MCP-Hub)

Release: v3.1.3 PyPI Version NPM Version WASI Engine License
요약

amv-mcp-hub는 MCP 클라이언트와 stdio(JSON-RPC 2.0, 줄 단위)로 통신합니다. 아래는 npm 패키지가 실제로 내보내는 API와 MCP 프로토콜 동작입니다. Python 패키지(pip install amv-mcp-hub)는 같은 핵심 도구를 표준 라이브러리로 구현하며 amv_mcp_hub.call_tool / list_tools를 제공합니다.

1. npm SDK 내보내기 (Node.js 18+)

내보내기 시그니처 동작
NodeExecutor new NodeExecutor(opts?)
executeTool(name, args, dynamicTools?) → Promise<{content, isError?}>
MCP 도구 하나를 프로세스 안에서 실행하고 MCP 도구 결과 형식으로 돌려줍니다.
WasiRunner new WasiRunner({ args?, stdin? })
run(wasmBinary) → Promise<{stdout, stderr, exitCode}>
Node 내장 WASI(preview 1)로 WebAssembly 모듈을 실행합니다.
heuristicRouter evaluate(request) → { target, reason } smart_exec가 호스트 실행(HOST_NATIVE)과 WASM 실행(WASM_SANDBOX) 중 경로를 고를 때 쓰는 판정기입니다.
BridgeGateway new BridgeGateway(port?)
start()
stdio MCP 서버와 HTTP/WebSocket 브리지를 기동합니다. CLI amv-mcp-hub가 사용하는 클래스와 같습니다.

2. MCP 프로토콜 동작

항목 동작
initialize프로토콜 개정판 2025-06-18, 2025-03-26, 2024-11-05 중 클라이언트가 요청한 것을 돌려주고, 그 밖에는 최신판을 제시합니다. serverInfo는 amv-mcp-hub와 패키지 버전입니다.
ping빈 결과 {}로 응답합니다.
tools/list, tools/call도구 목록과 실행. 실행 결과는 {content:[{type:"text",text}], isError}입니다.
알림 (notifications/*)응답하지 않습니다.
오류 코드-32700 구문 오류, -32600 잘못된 요청, -32601 지원하지 않는 메서드. 존재하지 않는 도구는 npm 판은 isError 결과, Python 판은 -32602로 응답합니다.

3. HTTP/WebSocket 브리지 (npm 판)

항목 동작
주소기본 127.0.0.1:11553. 다른 프로세스가 쓰고 있으면 다음 빈 포트로 옮기며, stdio는 영향을 받지 않습니다.
인증HTTP API(/mcp, /exec, /config, /api/* 등)와 WebSocket은 게이트웨이 옆 .token 파일의 토큰을 Authorization: Bearer로 요구합니다. 설정의 requireToken:false는 무시되며, 해제는 AMV_HUB_INSECURE_NO_TOKEN=1로만 가능합니다(경고 기록).
콘텐츠 형식POST /mcp, POST /exec는 Content-Type: application/json만 받습니다(415).
셸 시간 제한run_shell_command는 AMV_HUB_SHELL_TIMEOUT_MS(기본 120000) 후 종료됩니다.

4. 유지보수자 전용 도구

tester_*(기기 플릿 제어)는 로컬 ameva-tester 체크아웃(AMEVA_TESTER_DIR)이 있을 때만, 게시 도구(publish_labs_post 등)는 문서 사이트 체크아웃(AMV_DEF_ROOT)이 있을 때만 도구 목록에 나타납니다. 테스터 도구의 기기 인자 이름은 device입니다.