droid-mcp: Instructions file for Claude Code

droid-mcp

Android MCP SDK: 160 phone capabilities as tools, across 53 modules, for on-device LLMs (in-process calls) and desktop MCP clients (HTTP server on the phone).

Quick Reference

• Language: Kotlin 2.4, Android SDK 28+ (compile/target 36), Gradle 9.8, AGP 9 (built-in Kotlin — modules don't apply kotlin.android)
• Build: ./gradlew assembleDebug | Test: ./gradlew :droid-mcp-core:test
• Opt-in modules (not in :droid-mcp-all, they pull third-party deps): shizuku, root (shell tools), audit (Room), tls (BouncyCastle), server-service
• Checks before committing: ./gradlew assembleDebug testDebugUnitTest apiCheck lintDebug (CI runs the same)

Key Conventions

• Every tool implements McpTool interface: name, description, parameters, suspend fun execute()
• description is what a model reads to pick a tool: one or two plain sentences that start with a verb, say what comes back, and name the sibling tool to use instead when two overlap (e.g. tap vs find_and_tap). Leave out Android API names unless the model needs them; descriptions aren't part of the frozen wire contract
• Every tool declares outputSchema = OutputSchema.obj { ... } matching exactly what execute() returns on success: nullable = true for values that can be null, optional = true for keys only sometimes present, and no entry for a key passed to withImage() (it isn't in structuredContent)
• Every module has a provider object (e.g. CalendarTools) with all(context), requiredPermissions(), hasPermissions(context)
• Modules with browsable data also expose resources(...): a ResourceProvider that checks its own permissions, returns empty / null instead of throwing, and sets requiredTools to the tool serving the same data so gating that tool hides the resource too (media, files, contacts, calendar)
• Limit params: (params["limit"] as? Number)?.toInt()?.coerceIn(1, 100) ?: 10, declared with minimum = 1.0, maximum = 100.0 so the schema advertises the clamp
• Fixed-choice params declare enumValues; numeric clamps declare minimum/maximum — keep them identical to what execute() enforces
• ContentResolver queries: use ?.use { cursor -> }, NO LIMIT/OFFSET in sortOrder (handle in cursor loop)
• File access: sandboxed via PathValidator — external storage only
• Shared module logic lives in io.droidmcp.core.support (ActivityLaunch.canStartActivity, SqlLike.escape, StrictDates.parse, CalendarSupport.findWritableCalendarId, UsageAccess.isGranted, AppLabels, CompletionSupport.upcomingDates) — use these instead of module-local copies
• Tool calls run on Dispatchers.IO (enforced by ToolRegistry.executeTool, with a per-call timeout — default 5 min, Builder.toolTimeout()), never main thread
• No fully qualified names inline — use proper imports
• Long-running tools call reportProgress(done, total, message) (no-op when nobody listens); tools needing user input can call elicit(message, schema) (returns null when unsupported)