Android MCP Toolkit

🚀 Android MCP Toolkit for AI Agents

本項目是一個小型的MCP服務器，集成了三款實用工具，旨在為AI智能體提供便捷的安卓開發支持：

• 快速將SVG轉換為Android VectorDrawable（支持緩存、文件或內聯方式）。
• 具備包名、進程ID和標籤過濾功能的adb logcat讀取器，可快速進行崩潰排查。
• 翻譯長度差異估算器，能在佈局崩潰前標記出有風險的長度變化。

🚀 快速開始

• 執行 npm install 安裝依賴。
• 運行 npm run build 進行構建。
• 啟動標準輸入輸出MCP服務器：node dist/index.js

通過npx運行

全局運行：npx android-mcp-toolkit

在Cursor中使用（MCP配置）

將以下內容添加到你的Cursor設置JSON文件中：

{
  "mcpServers": {
    "android-mcp-toolkit": {
      "command": "npx",
      "args": [
        "-y",
        "android-mcp-toolkit"
      ]
    }
  }
}

使用npx調用會下載已發佈的包，無需指定本地路徑。

通過Cursor深度鏈接快速安裝：

• cursor://anysphere.cursor-deeplink/mcp/install?name=android-mcp-toolkit&config=eyJjb21tYW5kIjoibnB4IC15IGFuZHJvaWQtbWNwLXRvb2xraXQifQ%3D%3D

✨ 主要特性

填補安卓開發與AI生態的鴻溝

使命：引領原生安卓進入AI智能體時代

當AI生態系統被以Web為先的工具主導時，安卓開發常常顯得滯後。這個MCP服務器正是為彌合這一差距而打造的橋樑，它能將AI智能體與安卓工具鏈直接相連。

⚡ 零摩擦資產轉換：無需啟動Android Studio，即可即時將SVG轉換為VectorDrawable。

🔍 直接診斷訪問：支持智能體即時提取、過濾和分析adb logcat流（可按包名、進程ID或標籤進行過濾）。

🤖 智能體原生架構：提供結構化、可腳本化的輸出，便於大語言模型（LLMs）高效解析和處理。

🚀 可擴展性設計：為未來的功能擴展奠定了堅實基礎，如位圖處理工具和資產驗證功能。

搭配使用思路

• Figma MCP：從設計稿中提取SVGs，使用 convert-svg-to-android-drawable 工具生成XML文件，用於安卓資源。
• 調試：在應用運行時，通過 read-adb-logcat 工具，結合包名或標籤，無需離開MCP客戶端即可捕獲崩潰信息和過濾後的日誌。

工具預覽

SVG轉VectorDrawable

• Figma請求 → SVG提取
  
• 單旗幟轉換預覽
  
• 批量旗幟對比審查
  
• 通過MCP批量運行（控制檯）
  

ADB logcat工具

• 崩潰捕獲提示（輸入 + 過濾器）
  
• 響應預覽（彙總的logcat）
  

📦 安裝指南

依賴安裝與構建

• 執行 npm install 安裝所需依賴。
• 運行 npm run build 進行項目構建。
• 啟動標準輸入輸出MCP服務器：node dist/index.js

通過npx運行

全局運行：npx android-mcp-toolkit

在Cursor中配置使用

將以下配置添加到Cursor設置JSON文件：

{
  "mcpServers": {
    "android-mcp-toolkit": {
      "command": "npx",
      "args": [
        "-y",
        "android-mcp-toolkit"
      ]
    }
  }
}

通過Cursor深度鏈接快速安裝：

• cursor://anysphere.cursor-deeplink/mcp/install?name=android-mcp-toolkit&config=eyJjb21tYW5kIjoibnB4IC15IGFuZHJvaWQtbWNwLXRvb2xraXQifQ%3D%3D

💻 使用示例

SVG轉VectorDrawable示例

• 輸入SVG文件：sample_svg.svg
• 輸出VectorDrawable文件：examples/sample_svg.xml

📚 詳細文檔

當前工具介紹

convert-svg-to-android-drawable

• 輸入參數：
  • svg（內聯SVG）或 svgPath（SVG文件路徑）。
  • 可選參數：outputPath（輸出路徑）、floatPrecision（浮點精度，默認值為2）、fillBlack（是否填充黑色，默認值為false）、xmlTag（是否添加XML標籤，默認值為false）、tint（著色）、cache（是否使用緩存，默認值為true）。
• 輸出結果：返回VectorDrawable格式的XML文本；若提供了 outputPath，還會將結果寫入磁盤。
• 性能優化：採用LRU緩存（32個條目），以SVG和選項作為鍵，支持會話內快速複用。
• 轉換器：使用 vendor/svg2vectordrawable 中的分支版本，修復了 rgb()/rgba()、hsl()/hsla() 和命名顏色的問題。上游許可證：vendor/svg2vectordrawable/LICENSE（MIT）。

manage-logcat

• 輸入參數：
  • action：操作類型，可選值為 read（默認）、crash、anr 或 clear。
  • packageName：可選，通過 adb shell pidof 解析進程ID。
  • pid：可選，顯式指定進程ID。
  • tag：可選，按標籤過濾（如 MyApp）。
  • priority：日誌級別，可選值為 V、D、I、W、E、F、S（默認值為 V）。
  • maxLines：尾部日誌行數（默認值為200，最大值為2000）。
  • timeoutMs：超時時間（默認值為5000）。
• 操作行為：
  • read：獲取logcat尾部日誌。
  • crash：獲取 logcat -b crash 日誌。
  • anr：獲取最近的ActivityManager ANR日誌和 /data/anr/traces.txt 的尾部內容。
  • clear：清除logcat緩衝區。

get-current-activity

• 輸入參數：timeoutMs（默認值為 5000，最大值為 15000）。
• 操作行為：檢查 dumpsys window 命令輸出，查找當前聚焦的應用或窗口，用於驗證應用狀態。

dump-ui-hierarchy

• 輸入參數：timeoutMs（默認值為10000）。
• 操作行為：通過 uiautomator 捕獲當前UI佈局的XML結構。

take-screenshot

• 輸入參數：outputPath（必需）、timeoutMs。
• 操作行為：將設備屏幕截圖保存到本地文件。

inject-input

• 輸入參數：
  • command：操作命令，可選值為 tap、text、swipe、keyevent、back、home。
  • args：參數數組。
  • timeoutMs。
• 可選參數：elementId 或 elementText（用於查找元素中心並點擊）。
• 操作行為：模擬用戶交互，適用於測試流程。

estimate-text-length-difference

• 輸入參數：
  • sourceText：原始文本。
  • translatedText：待比較的翻譯文本。
  • tolerancePercent（默認值為 30，最大值為 500）。
• 操作行為：計算兩個字符串的字符長度，計算長度變化百分比，並報告是否超過容忍度，有助於發現可能導致佈局崩潰的翻譯長度問題。

未來規劃（計劃中）

• 為安卓資產添加更多的MCP工具（如批量轉換、驗證、優化工具）。
• 為常見的安卓Drawable和模板提供可選的資源提示。

📄 許可證

文檔未提及相關內容，暫不提供。

🔧 技術細節

傳輸方式

通過 @modelcontextprotocol/sdk 進行標準輸入輸出傳輸。

依賴管理

基礎依賴保持精簡，所有用於SVG轉換的必要組件均已打包或包含在內。

📞 聯繫我們

如有任何問題或建議，請通過以下郵箱聯繫我們：nam.nv205106@gmail.com