OpenGL Android 개발 및 자동화를 위한 MCP

AI 코딩 에이전트(Claude Code, Cursor 등)가 전체 UI가 단일 불투명 OpenGL/Vulkan/Metal 표면 내부에 그려지는 Android 앱(Cocos2d-x, Unity, Unreal, 원시 OpenGL, libGDX 및 유사 엔진)을 테스트할 수 있게 해주는 MCP 서버입니다.

이 서버가 해결하는 문제

adb shell uiautomator dump 및 모든 접근성 트리 기반 자동화 도구(대부분의 MCP 모바일 자동화 서버 포함)는 네이티브 Android 뷰 계층(버튼, 라벨, 텍스트 및 좌표)을 검사하여 작동합니다. 이는 네이티브 뷰로 구성된 일반적인 Android UI에는 훌륭하게 작동합니다.

하지만 전체 UI를 하나의 GLSurfaceView 내부에 텍스처로 렌더링하는 게임이나 앱에는 작동하지 않습니다. 접근성 트리의 관점에서 보면 화면에는 자식, 라벨, 내부 좌표가 전혀 없는 단 하나의 불투명 뷰만 존재합니다. 검사할 것이 없습니다. 화면은 실제로 얼마나 많은 UI가 있든 관계없이 블랙박스입니다.

남은 유일한 실제 관찰 채널은 스크린샷입니다. 이 서버는 이를 가끔 사용하는 폴백이 아니라 일반적인 경우로 삼아 구축되었습니다.

mobile-mcp와의 차이점

mobile-next/mobile-mcp는 범용 MCP 모바일 자동화 서버이며, 일반 네이티브 앱에는 좋은 기본 선택입니다. 접근성 트리를 우선 사용하고(빠르고 저렴하며 비전 모델이나 이미지 토큰이 필요 없음), 트리가 필요한 정보를 제공하지 못할 때만 스크린샷 + 좌표로 폴백합니다.

OpenGL 캔버스 앱의 경우 이 폴백은 가끔 발생하는 것이 아니라 매번 작동하는 유일한 경로입니다. mobile-mcp-opengl은 이 특정 경우를 위해 구축되었으며, 그 결과 두 가지 다른 설계 선택을 합니다:

1. 접근성 트리 시도를 전혀 하지 않습니다. 시도해도 이 앱에서는 항상 비어 있으므로 얻을 이득이 없습니다. 따라서 여기의 모든 도구는 바로 스크린샷 + 비전으로 진행합니다.

2. 비전 분석은 호출 에이전트를 실행하는 모델이 아니라 플러그 가능한 별도 공급자(아래 참조)를 통해 진행됩니다. 게임에 대한 기능 QA 루프는 세션당 수백 번의 스크린샷 검사에 쉽게 도달할 수 있습니다. 이 모든 것을 기본 코딩 에이전트의 자체 비전으로 라우팅하면 실제 비용과 실제 코딩 작업에 사용하고 싶은 토큰/컨텍스트가 모두 소모됩니다. 여기서 스크린샷 바이트는 호출 에이전트의 컨텍스트에 전혀 들어가지 않습니다. 공급자의 짧은 텍스트 답변만 들어갑니다.

Related MCP server: Android-MCP

별도의 기본 도구가 아닌 결합된 액션+관찰 도구를 사용하는 이유

단순한 설계는 tap, screenshot, ask를 세 개의 별도 도구로 노출합니다. 그러면 호출 에이전트가 모든 상호작용에 대해 다단계 루프를 조율해야 합니다: 탭 → 스크린샷 촬영 → 비전 단계에 전달 → 결과 읽기 → 다음 작업 결정. 각각은 별도의 도구 호출이자 별도의 턴입니다. 실제 테스트 로직 대신 조정에 토큰을 소모하고, 에이전트가 단계를 빠뜨리거나 순서를 잘못 지정하거나 호출 사이에 오래된 상태에 대해 추론할 가능성이 더 커집니다.

대신 이 서버는 결합된 도구(tap_and_ask, swipe_and_ask, long_press_and_ask)를 노출합니다. 이 도구들은 액션을 수행하고, 잠시 기다린 후, 스크린샷을 찍고, 비전 공급자에게 질문하고, 하나의 짧은 답변을 반환합니다. 모두 단일 도구 호출로 처리됩니다. 다단계 테스트 시나리오는 의미 있는 검사당 대략 한 번의 에이전트 턴이 소요되며, 3~4턴이 아닙니다.

일반 screenshot_ask(액션 없이 관찰만) 및 저렴한 비비전 도구(type_text, press_key, logcat_grep)도 테스트 흐름에서 이 패턴이 필요하지 않은 부분에 사용할 수 있습니다.

도구

필요한 것이 이미 로그 라인(크래시, 자체 디버그 출력, 네트워크 오류)에 있다면 비전 호출보다 logcat_grep을 선호하세요. 무료이고 정확하며, 비전 호출은 둘 다 아닙니다.

애니메이션 확인: record_and_ask

단일 프레임 도구는 무언가가 애니메이션되는지 여부를 알 수 없습니다(강도 표시기가 부드럽게 맥동하는지, 라벨이 위로 날아가며 사라지는지, 스프라이트가 시작 위치로 튕겨 돌아오는지). record_and_ask는 하나의 선택적 액션(탭 또는 스와이프, 또는 둘 다 아님)을 수행하고, waitMs(첫 프레임 전에 UI가 반응하기 시작할 시간 — tap_and_ask/swipe_and_ask의 waitMs와 같은 의미)를 기다린 후, intervalMs 간격으로 frameCount개의 스크린샷을 캡처하고, 각 프레임에 대해 하나의 짧은 답변을 반환합니다. 호출 에이전트는 N개의 별도 스크린샷+질문 왕복을 직접 조율하는 대신 한 번의 도구 호출로 타임라인을 얻습니다.

모든 프레임을 하나의 호출로 묶는 대신 프레임당 하나의 비전 호출을 사용하는 이유. Runware의 imageCaption은 문서화된 단일 inputImage와 함께 문서화되지 않은 inputImages 배열(복수)을 허용하는 것으로 밝혀졌습니다. API에 직접 테스트했습니다. 정확히 2개의 이미지(같은 요청 내 before/after 비교)에서는 깔끔하게 작동했습니다. 한 요청에 3개 이상의 이미지가 있으면 해당 배열 매개변수와 수동으로 합성한 나란히 붙인 "필름스트립" 이미지 모두 테스트에서 잘리거나 잘못된 답변을 생성했습니다. 작은 7B 비전 모델은 한 번의 호출에서 결합된 시각+명령 부하가 일정 수준을 넘으면 일관성을 잃는 것으로 보입니다. 순차적 단일 이미지 호출(이 도구의 접근 방식)은 테스트한 모든 프레임 수에서 안정적이었고, 비용이 크게 증가하지도 않습니다. 비용은 호출 수보다 응답 길이(아래 참조)에 의해 지배되므로, N개의 짧은 순차 답변은 하나의 긴 다중 이미지 답변과 비슷하거나 더 저렴합니다. 자체 공급자가 다중 이미지 요청을 더 안정적으로 처리한다면 이는 분명히 최적화할 부분입니다. "자체 모델 사용"을 참조하세요.

설정

git clone <this repo>
cd mobile-mcp-opengl
npm install
cp .env.example .env
# edit .env: at minimum set RUNWARE_API_KEY (or switch VISION_PROVIDER, see below)

PATH에 adb가 필요하거나(또는 .env에 ADB_PATH 설정), 실행 중/연결된 기기 또는 에뮬레이터가 필요합니다. 둘 이상이 연결된 경우 ADB_DEVICE_SERIAL을 설정하세요(adb devices 참조).

Claude Code에 등록

프로젝트 루트에 .mcp.json을 추가하세요(이 파일은 일반적으로 프로젝트 로컬이며 git-ignored입니다. 일반적으로 머신별 경로를 가리키거나 머신별 환경 변수 재정의를 보유하기 때문입니다):

{
  "mcpServers": {
    "mobile-opengl": {
      "command": "node",
      "args": ["/absolute/path/to/mobile-mcp-opengl/src/server.js"]
    }
  }
}

Claude Code는 이 파일을 프로젝트에 대해 자동으로 인식합니다. 서버는 모든 구성에 대해 자체 .env(이 저장소의 package.json 옆)를 읽습니다. 호출 에이전트는 API 키를 알거나 전달할 필요가 없습니다.

비용 모델 — 긴 QA 세션을 실행하기 전에 읽어보세요

비용을 결정하는 것은 이미지 크기가 아니라 응답 길이입니다. 이는 기본 Runware/Qwen2.5-VL-7B-Instruct 공급자에 대해 경험적으로 측정되었습니다. 강제로 한 단어 답변을 요구한 동일한 질문은 360×360에서 1600×2400(레티나급)까지 모든 이미지 크기에서 동일한 비용($0.0006)이 들었습니다. 동일한 1024×1024 이미지에 개방형 "이것을 설명하세요" 프롬프트는 $0.0013–0.0019가 들었습니다. 이는 이미지가 더 커서가 아니라 모델이 더 긴 답변을 작성했기 때문에 2~3배 더 비쌌습니다.

실용적 의미:

• 보내기 전에 스크린샷을 다운샘플링하지 마세요. 이 공급자에게는 비용을 의미 있게 줄이지 않으며, 필요할 수 있는 세부 정보를 잃게 됩니다.

• 항상 짧은 답변을 강제하도록 질문을 구성하세요: 예/아니요, 숫자, 짧은 라벨, 몇 개의 필드가 있는 작은 JSON 객체. 이 서버의 모든 도구는 자동으로 짧은 답변 지침을 추가하지만, 모호한 개방형 질문("무엇이 보이나요?")은 특정 질문("오류 대화상자가 보이나요? 예/아니요")보다 모델이 더 긴 답변을 하도록 유도할 수 있습니다.

잘 구성된 짧은 질문의 경우 호출당 약 $0.0006이며, 500회 호출 QA 세션은 약 $0.30입니다. 동일한 양의 개방형 "화면 설명" 질문은 2~3배 더 비쌀 수 있습니다.

내장 지출 가드레일

모든 비전 호출은 .vision-log.jsonl(JSONL, 호출당 하나의 항목: 타임스탬프, 질문, 답변, 비용)에 기록됩니다. 이 로그 위에는 두 가지 독립적인 보호 장치가 있으며, 둘 다 공급자에 구애받지 않습니다(공급자가 보고하는 costUsd를 기반으로 작동):

• 호출당 경고 (VISION_ALERT_USD, 기본 $0.0015): 단일 호출이 이 값을 초과하면 도구 응답에 [COST ALERT] 메모가 포함되어 모델이 짧은 답변 지침을 무시했을 가능성이 있음을 알려줍니다. 이는 조용히 넘어갈 것이 아니라 질문을 다시 구성하라는 신호입니다.

• 일일 상한 (VISION_SESSION_CAP_USD, 기본 $2.00): 오늘의 누적 기록 지출이 이 값에 도달하면 이후의 모든 비전 호출은 (공급자에 도달하기 전에) 완전히 거부됩니다. 상한을 올리거나 날짜가 바뀔 때까지입니다. 이는 경고가 아니라 폭주 루프에 대한 하드 스톱입니다.

vision_spend_report를 호출하여 기기나 비전 호출 없이 오늘의 총액을 확인하세요.

공급자가 비용을 보고할 수 없는 경우(아래 openai-compatible 참조), 해당 공급자의 호출은 costUsd: null로 기록되며 경고를 트리거하거나 상한에 포함되지 않습니다. 가드레일은 가시성이 없는 지출을 보호할 수 없습니다.

자체 모델 사용

비전 분석은 src/providers/visionProvider.js를 통해 진행되며, .env의 VISION_PROVIDER에서 이름으로 공급자를 선택합니다. 두 가지가 내장되어 있습니다:

• runware (기본값) — Runware.ai의 imageCaption 작업에 직접 연결하며, 기본적으로 Qwen2.5-VL-7B-Instruct(AIR id runware:152@2)를 사용합니다. Runware와 OpenRouter는 별도의 API 키와 모델 카탈로그를 가진 두 개의 별도 서비스입니다. 이 서버는 OpenRouter를 통하지 않고 Runware에 직접 연결합니다.

• openai-compatible — OpenAI 채팅 완성 비전 형식(image_url 콘텐츠 부분)을 말하는 모든 것에 대한 일반 공급자입니다. OpenRouter, 비전 모델을 실행하는 로컬 Ollama/LM Studio 서버, Groq, Together.ai 또는 기타 호환 엔드포인트에서 작동합니다. .env에서 OPENAI_COMPATIBLE_BASE_URL, OPENAI_COMPATIBLE_API_KEY, OPENAI_COMPATIBLE_MODEL을 구성하세요. 대부분의 OpenAI 호환 API는 고정 달러 비용 대신 토큰 사용량을 보고합니다. 이 공급자가 costUsd를 추정하도록 하려면 OPENAI_COMPATIBLE_PRICE_PER_1M_INPUT/_OUTPUT을 설정하세요(그렇지 않으면 위 메모에 따라 이 공급자에 대해 비용 추적/가드레일이 비활성화됩니다).

완전히 사용자 정의 공급자(자체 호스팅 모델, 완전히 다른 API 형태)를 추가하려면 src/providers/openaiCompatibleProvider.js를 시작점으로 복사하고 다음을 구현하세요:

async function ask(imageBuffer, mimeType, question) {
  // return { text: string, costUsd: number | null }
}
module.exports = { ask };

그리고 src/providers/visionProvider.js의 loadProvider()에 이름으로 등록하세요.

라이선스

MIT

Kinect.PRO 개발