API 인터페이스 명세서 & 프로토콜 규격
npm SDK 내보내기, MCP 프로토콜 동작, HTTP/WebSocket 브리지 (AMV-MCP-Hub)
요약
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입니다.