How hyperb1iss/droidmind works
Project type and purpose
• DroidMind is an open-source Python tool (library + server/CLI) that acts as a bridge between AI assistants (via the Model Context Protocol, MCP) and Android devices (via ADB). Its purpose is to expose device-management and automation capabilities over a network interface (SSE, CLI).
File structure
• Top-level module droidmind/ contains:
• server.py – MCP server entrypoint
• console.py – CLI interactive shell
• adb.py – low-level ADB wrapper
• devices.py – represents and manages device connections
• filesystem.py, packages.py, prompts.py, security.py, log.py, context.py – core services (FS access, package inspection, prompt templates, security validation, logging, shared context)
• tools/ – plugin-style modules (app_management, device_management, diagnostics, file_operations, logs, media, shell, ui)
• tests/ covers unit tests by component.
• docs/, CI/CD config, pyproject.toml for build and dependencies, LICENSE, README.md.
README
• Describes the MCP resources and tool commands.
• Shows how to start the SSE server (droidmind --transport sse).
• Lists features (device control, system analysis, file system, UI automation, security, MCP integration).
• No front-end or database; purely network protocol + device interface.
Main components and relationships
a. Client Layer
• AI Assistant (external) – speaks MCP over SSE or STDIO
• CLI/Console – human interactive shell (falls back to same internals)
b. Protocol Layer
• server.py – HTTP/SSE server hosting MCP endpoint
• MCP request/response dispatcher
c. Core Services
• context.py – request context, authentication, session state
• security.py – command risk assessment & validation
• log.py – audit logging of commands and risk levels
d. Device Interface
• adb.py – invokes ADB subprocess (USB / TCP)
• devices.py – tracks connected device objects and metadata
e. Feature Plugins (Tools)
• tools/*.py – high-level operations built on ADB + core services (app management, UI automation, file ops, logs, media, diagnostics)
f. External Systems
• ADB daemon (on host)
• Android device(s)
• Optional: UV package manager (for dev workflow)
• GitHub Actions (CI/CD)
Architectural patterns & design principles
• Modular “plugin” architecture: new tool modules drop into tools/.
• Layered design: Protocol → Core Services → Device Interface → External devices.
• Single responsibility: each module focuses on one domain.
• Security by design: all commands flow through security.py and log.py.
• Context propagation: context.py carries session data across calls.
4. Core Services – cluster of rectangles: Context, Security, Logging
• AI Assistant → (MCP/SSE) → MCP Server
• CLI → internal API → MCP Server
• MCP Server → Core Services (Context, Security, Logging)
• MCP Server → Tool Plugins → ADB Wrapper → ADB Daemon → Android Device(s)
• Responses flow back up: Device → ADB → Tools → Server → Client.
• “SSE / HTTP” between client and server
• “run_adb_command(cmd)” between plugins and ADB wrapper
Key focus
• Every core package (context, security, log, adb, each tools/*) appears once.
• Flow from AI assistant → server → device and back.
• Security validation path and logging path for audit.
• Do not over-complicate: keep layers distinct and minimal.
• Extensibility by marking the plugin boundary.
• External dependencies (ADB, Android devices, UV, GitHub Actions) to complete the picture.