用于OpenGL Android开发和自动化的MCP

一个用于AI编码代理（Claude Code、Cursor等）的MCP服务器，用于测试整个UI绘制在单个不透明OpenGL/Vulkan/Metal表面内的Android应用——Cocos2d-x、Unity、Unreal、原始OpenGL、libGDX及类似引擎。

它解决的问题

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——它们执行操作、短暂等待、截图、询问视觉提供程序，并返回一个简短答案，全部作为一次工具调用。多步测试场景最终每个有意义的检查大约花费一个代理轮次，而不是三四个。

普通的screenshot_ask（仅观察，无操作）和廉价的非视觉工具（type_text、press_key、logcat_grep）也可用于测试流程中不需要此模式的部分。

工具

只要所需信息已经在日志行中（崩溃、你自己的调试输出、网络错误），就优先使用logcat_grep而不是视觉调用——它免费且精确，而视觉调用两者都不是。

检查动画：record_and_ask

单帧工具无法告诉你某物是否正确动画（力量指示器是否平滑脉动，标签是否飞起并淡出，精灵是否弹回起始位置）。record_and_ask执行一个可选操作（点击或滑动，或两者都不），等待waitMs（与tap_and_ask/swipe_and_ask中的waitMs含义相同——在首帧之前让UI开始反应的时间），然后按intervalMs间隔捕获frameCount张截图，并返回每帧一个简短答案——调用代理在一次工具调用中获得时间线，而不是自己编排N次单独的截图+询问往返。

为什么每帧一次视觉调用，而不是将所有帧捆绑在一次调用中。 Runware的imageCaption被证明接受一个未记录的inputImages数组（复数），与文档化的单个inputImage并列——已直接针对API测试。对于恰好2张图像，它工作正常（同一请求中的前后对比返回正确且连贯）。在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)

需要adb在PATH中（或在.env中设置ADB_PATH），以及一个运行中/已连接的设备或模拟器。如果连接了多个，请设置ADB_DEVICE_SERIAL（参见adb devices）。

注册到Claude Code

在项目根目录添加.mcp.json（此文件通常是项目本地的且被git忽略，因为它通常指向特定机器的路径或包含特定机器的环境覆盖）：

{
  "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密钥和模型目录——这直接与Runware通信，而不是通过OpenRouter。

• 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开发