✨ 드로이드마인드 🤖

모델 컨텍스트 프로토콜을 통해 AI로 안드로이드 기기를 제어하세요

DroidMind는 AI 어시스턴트와 안드로이드 기기를 연결하는 강력한 다리 역할을 하며, 자연어를 통해 제어, 디버깅 및 시스템 분석을 지원합니다. DroidMind는 모델 컨텍스트 프로토콜(MCP)을 구현하여 AI 모델이 ADB를 통해 안전하고 체계적인 방식으로 안드로이드 기기와 직접 상호 작용할 수 있도록 지원합니다. DroidMind를 에이전트 코딩 워크플로의 일부로 사용하면 어시스턴트가 루프 내에서 기기를 직접 빌드하고 디버깅할 수 있습니다.

💫 특징

• 📱 장치 제어 - USB 또는 TCP/IP를 통해 장치에 연결하고, 셸 명령을 실행하고, 재부팅합니다.
• 📊 시스템 분석 - 장치 속성 검사, 하드웨어 정보 보기, 시스템 로그 분석
• 🔍 파일 시스템 액세스 - 디렉토리 내용을 탐색하고 장치의 파일을 관리합니다.
• 📷 시각적 진단 - 분석 및 디버깅을 위해 장치 스크린샷을 캡처합니다.
• 📦 앱 관리 - 연결된 기기에서 앱 설치, 제거, 시작, 중지 및 데이터 삭제
• 🔄 다중 장치 지원 - 연결된 여러 장치를 제어하고 전환하세요
• 👆 UI 자동화 - 탭, 스와이프, 텍스트 입력, 키 누름을 통해 장치와 상호 작용합니다.
• 🔍 앱 검사 - 앱 매니페스트, 공유 기본 설정 및 앱별 로그 보기
• 🔒 보안 프레임워크 - 포괄적인 명령 검증으로 장치 보호
• 💬 MCP 통합 - Claude, Cursor, Cline 등과 원활하게 연결

🚀 설치

지엑스피1

📋 필수 조건

• Python 3.13 이상
• USB 디버깅이 활성화된 Android 기기
• ADB(Android Debug Bridge)가 설치되고 PATH에 있음
• UV 패키지 관리자(종속성 관리에 권장)
• 네트워크 제어를 위해: TCP/IP를 통한 ADB가 활성화된 Android 기기

🔮 빠른 시작

DroidMind 서버를 실행하세요

MCP를 통해 AI 어시스턴트를 연결하기 위해 DroidMind를 서버로 실행하세요.

AI 어시스턴트와 함께 사용

1. SSE 모드에서 DroidMind를 시작하세요:
   droidmind --transport sse
2. MCP 프로토콜 URI를 사용하여 AI 어시스턴트를 연결합니다.
   sse://localhost:4256/sse
3. 이제 AI가 자연어로 안드로이드 기기를 제어할 수 있습니다!

🛠️ 사용 가능한 MCP 리소스 및 도구

자원

• devices://list - 연결된 모든 장치 나열
• device://{serial}/properties - 자세한 장치 속성을 가져옵니다.
• logs://{serial}/logcat - 장치에서 최근 로그를 가져옵니다.
• logs://{serial}/anr - 애플리케이션 응답 없음(ANR) 추적 가져오기
• logs://{serial}/crashes - 애플리케이션 충돌 로그 가져오기
• logs://{serial}/battery - 배터리 통계 및 기록을 가져옵니다.
• logs://{serial}/app/{package} - 애플리케이션별 로그 가져오기
• fs://{serial}/list/{path} - 장치의 디렉토리 내용을 나열합니다.
• fs://{serial}/read/{path} - 장치에서 파일 내용을 읽습니다.
• fs://{serial}/stats/{path} - 자세한 파일/디렉토리 통계를 가져옵니다.
• app://{serial}/{package}/manifest - AndroidManifest.xml 내용 가져오기
• app://{serial}/{package}/data - 앱의 데이터 디렉토리에 있는 파일 나열
• app://{serial}/{package}/shared_prefs - 앱의 공유 기본 설정 가져오기

도구

• devicelist - 연결된 모든 Android 기기 나열
• device_properties - 특정 장치의 자세한 속성을 가져옵니다.
• device_logcat - 장치에서 최근 logcat 출력을 가져옵니다.
• list_directory - 장치의 디렉토리 내용 나열
• connect_device - TCP/IP를 통해 장치에 연결
• disconnect_device - Android 기기에서 연결 해제
• shell_command - 장치에서 셸 명령을 실행합니다.
• install_app - 기기에 APK 설치
• uninstall_app - 기기에서 앱 제거
• start_app - 기기에서 앱 시작
• stop_app - 기기에서 앱을 강제로 중지합니다.
• clear_app_data - 앱 데이터 및 캐시 지우기
• list_packages - 장치에 설치된 패키지 목록
• get_app_manifest - 앱의 AndroidManifest.xml 내용을 가져옵니다.
• get_app_permissions - 앱에서 요청한 권한 가져오기
• get_app_activities - 앱에 정의된 활동 가져오기
• get_app_info - 앱에 대한 자세한 정보를 가져옵니다.
• reboot_device - 장치를 재부팅합니다(일반, 복구 또는 부트로더).
• screenshot - 기기에서 스크린샷 가져오기
• capture_bugreport - 장치에서 포괄적인 버그 보고서를 생성합니다.
• dump_heap - 메모리 분석을 위해 실행 중인 프로세스에서 힙 덤프를 생성합니다.
• push_file - 장치에 파일 업로드
• pull_file - 장치에서 파일을 다운로드합니다.
• delete_file - 장치에서 파일이나 디렉토리를 삭제합니다.
• create_directory - 장치에 디렉토리를 생성합니다
• file_exists - 장치에 파일이 있는지 확인합니다.
• read_file - 장치의 파일 내용을 읽습니다.
• write_file - 장치의 파일에 텍스트 콘텐츠를 씁니다.
• file_stats - 파일이나 디렉토리에 대한 자세한 정보를 가져옵니다.
• tap - 특정 좌표에서 장치 화면을 탭합니다.
• swipe - 화면의 한 지점에서 다른 지점으로 스와이프 제스처를 수행합니다.
• input_text - 키보드에서 입력하는 것처럼 장치에 텍스트를 입력합니다.
• press_key - 하드웨어 또는 소프트웨어 키(예: HOME, BACK, VOLUME)를 누릅니다.
• start_intent - Android 인텐트를 사용하여 앱 활동 시작

📊 AI Assistant 쿼리 예시

DroidMind에 연결된 AI 비서를 사용하여 다음 쿼리를 시도해 보세요.

• "연결된 모든 Android 기기를 나열하고 해당 속성을 보여주세요"
• "192.168.1.100에서 내 휴대폰에 연결하여 배터리 상태를 확인하세요"
• "Pixel의 스크린샷을 찍어서 현재 화면에 무엇이 있는지 보여주세요"
• "내 기기의 사용 가능한 저장 공간을 확인하세요"
• "내 기기의 ANR 추적 및 충돌 로그를 보여주세요"
• "최근 로그를 보고 오류가 있는지 알려주세요"
• "내 기기에 이 APK 파일을 설치하고 성공했는지 알려주세요"
• "내 휴대폰에 설치된 모든 앱 목록을 보여줘"
• "내 기기를 복구 모드로 재부팅하세요"
• "내 휴대폰은 어떤 안드로이드 버전을 사용하고 있나요?"
• "내 기기가 루팅되었는지 확인하고 보안 패치 수준을 알려주세요"
• "com.android.settings에 대한 매니페스트 파일을 보여주세요"
• "내 앱의 공유 환경 설정 확인"
• "좌표 500,1000에 있는 설정 아이콘을 탭하세요"
• "화면 상단에서 아래로 살짝 밀어 알림 창을 엽니다."
• "현재 텍스트 필드에 내 비밀번호를 입력하세요"
• "홈 화면으로 돌아가려면 뒤로가기 버튼을 세 번 누르세요"
• "com.android.settings 패키지를 시작하여 설정 앱을 엽니다."

🔒 보안 기능

DroidMind에는 AI 도우미가 풍부한 표현력을 발휘할 수 있도록 하는 동시에 기기를 보호하는 포괄적인 보안 프레임워크가 포함되어 있습니다.

• 명령 검증 : 모든 셸 명령은 안전한 명령 허용 목록에 대해 검증됩니다.
• 위험 평가 : 명령은 위험 수준(안전, 낮음, 보통, 높음, 중요)별로 분류됩니다.
• 명령 살균 : 명령 주입 공격을 방지하기 위해 입력이 살균됩니다.
• 보호된 경로 : 시스템 디렉토리와 중요 경로는 수정으로부터 보호됩니다.
• 종합 로깅 : 모든 명령은 감사를 위해 위험 수준과 함께 로깅됩니다.
• 의심스러운 패턴 감지 : 잠재적으로 위험한 패턴이 있는 명령이 차단됩니다.
• ADB 명령 보안 : 적절한 비동기 검증을 통한 ADB 특정 명령에 대한 특별 처리

보안 시스템은 파괴적인 행위를 방지하는 동시에 일반적인 작업은 허용할 수 있도록 설계되었습니다. 고위험 명령은 실행 전에 사용자에게 경고를 표시하며, 중요한 작업은 명시적인 재정의 없이 완전히 차단됩니다.

💻 개발

DroidMind는 종속성 관리 및 개발 워크플로에 UV를 사용합니다. UV는 빠르고 안정적인 Python 패키지 관리자이자 리졸버입니다.

🤝 기여하기

기여를 환영합니다! 풀 리퀘스트를 제출해 주세요.

1. 저장소를 포크하세요
2. 기능 브랜치를 생성합니다( git checkout -b feature/amazing-feature )
3. UV로 개발 환경 설정하기
4. 변경 사항을 만드세요
5. 테스트 실행 및 린팅
6. 변경 사항을 커밋하세요( git commit -m 'Add some amazing feature' )
7. 브랜치에 푸시( git push origin feature/amazing-feature )
8. 풀 리퀘스트 열기

📝 라이센스

이 프로젝트는 Apache 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 LICENSE 파일을 참조하세요.

Stefanie Jane이 만들었습니다 🌠

DroidMind가 유용하다면 Monster Ultra Violet을 사주세요 ⚡️