Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
package com.powercess.mbrain.capability

import android.content.ClipData
import android.content.ClipboardManager
import android.content.Context
import android.net.ConnectivityManager
import android.os.Build
import io.droidmcp.core.*

/** Capabilities implemented by the MBrain process without Shizuku or Root. */
object AppCapabilityTools {
fun all(context: Context): List<McpTool> = listOf(clipboardGet(context), clipboardSet(context), networkStatus(context))

private fun clipboardGet(context: Context) = object : McpTool {
override val name = "clipboard_get"
override val description = "Read the current clipboard through the normal Android ClipboardManager API."
override val annotations = ToolAnnotations(readOnlyHint = true)
override val parameters = emptyList<ToolParameter>()
override suspend fun execute(params: Map<String, Any>): ToolResult = try {
val manager = context.getSystemService(ClipboardManager::class.java)
val clip = manager?.primaryClip
val text = clip?.takeIf { it.itemCount > 0 }?.getItemAt(0)?.coerceToText(context)?.toString()
ToolResult.success(mapOf("available" to (text != null), "text" to (text ?: ""), "source" to "app"))
} catch (error: SecurityException) {
ToolResult.success(mapOf("available" to false, "text" to "", "source" to "app", "reason" to "system_denied"))
}
}

private fun clipboardSet(context: Context) = object : McpTool {
override val name = "clipboard_set"
override val description = "Set the current clipboard through the normal Android ClipboardManager API."
override val annotations = ToolAnnotations(destructiveHint = true)
override val parameters = listOf(ToolParameter("value", "Clipboard text", ParameterType.STRING, true))
override suspend fun execute(params: Map<String, Any>): ToolResult = try {
val value = params["value"] as? String ?: return ToolResult.error("value is required")
require(value.length <= 16000 && '\u0000' !in value) { "Text too long or contains NUL" }
context.getSystemService(ClipboardManager::class.java)?.setPrimaryClip(ClipData.newPlainText("MBrain", value))
ToolResult.success(mapOf("ok" to true, "source" to "app"))
} catch (error: SecurityException) { ToolResult.error("clipboard_denied", "System denied clipboard write") }
}

private fun networkStatus(context: Context) = object : McpTool {
override val name = "net_status"
override val description = "Read active network transport through ConnectivityManager."
override val annotations = ToolAnnotations(readOnlyHint = true)
override val parameters = emptyList<ToolParameter>()
override suspend fun execute(params: Map<String, Any>): ToolResult {
val manager = context.getSystemService(ConnectivityManager::class.java)
val network = manager?.activeNetwork
val caps = network?.let { manager.getNetworkCapabilities(it) }
return ToolResult.success(mapOf("available" to (network != null), "validated" to (caps?.hasCapability(android.net.NetworkCapabilities.NET_CAPABILITY_VALIDATED) == true),
"wifi" to (caps?.hasTransport(android.net.NetworkCapabilities.TRANSPORT_WIFI) == true), "cellular" to (caps?.hasTransport(android.net.NetworkCapabilities.TRANSPORT_CELLULAR) == true),
"vpn" to (caps?.hasTransport(android.net.NetworkCapabilities.TRANSPORT_VPN) == true), "api" to Build.VERSION.SDK_INT, "source" to "app"))
}
}
}
12 changes: 12 additions & 0 deletions app/src/main/kotlin/com/powercess/mbrain/gateway/GatewayRuntime.kt
Original file line number Diff line number Diff line change
Expand Up @@ -210,6 +210,7 @@ object GatewayRuntime {
}
private fun localTools(): List<McpTool> = buildList {
val capabilityProviders = mutableMapOf<ProviderKind, MutableMap<String, McpTool>>()
capabilityProviders[ProviderKind.APP] = AppCapabilityTools.all(context).associateBy { it.name }.toMutableMap()
addAll(DeviceTools.all(context))
if (config.value.appsEnabled) addAll(AppsTools.all(context))
listOf(ExecutionMode.ROOT, ExecutionMode.SHIZUKU).forEach { mode ->
Expand Down Expand Up @@ -247,6 +248,17 @@ object GatewayRuntime {
CapabilityDefinition("net_diagnose", "Diagnose DNS and TCP connectivity", "read", listOf(ProviderKind.APP, ProviderKind.SHIZUKU, ProviderKind.ROOT)),
)
addAll(CapabilityDispatcher(definitions, capabilityProviders).tools())
add(object : McpTool {
override val name = "capabilities_list"
override val description = "List stable MBrain capabilities and their currently available providers."
override val annotations = ToolAnnotations(readOnlyHint = true)
override val parameters = emptyList<ToolParameter>()
override suspend fun execute(params: Map<String, Any>): ToolResult = ToolResult.success(mapOf("capabilities" to definitions.map { definition ->
mapOf("id" to definition.id, "risk" to definition.risk,
"providers" to definition.providers.map { it.name.lowercase() },
"available_providers" to definition.providers.filter { capabilityProviders[it]?.containsKey(definition.id) == true }.map { it.name.lowercase() })
}))
})
}
private fun refreshTools() {
val current = server ?: return
Expand Down
19 changes: 18 additions & 1 deletion docs/capability-packs.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,21 @@
# 手机操作与应用诊断

启用 Root 或 Shizuku 后,在工具目录中选择对应来源。下表省略 `root_` / `shizuku_` 前缀,例如完整名称为 `shizuku_ui_dump`。工具不需要单独启用无障碍服务,也不依赖 AutoX.js。
统一能力工具不要求默认开启 Root 或 Shizuku;调度器会优先选择普通 App Provider,再按声明顺序选择特殊权限、Shizuku 或 Root。原始 `root_` / `shizuku_` 工具仍然保留,例如完整名称为 `shizuku_ui_dump`。工具不需要单独启用无障碍服务,也不依赖 AutoX.js。

## 能力与 Provider

MBrain 将“能力”与“执行通道”分开。MCP 使用稳定的能力名,例如 `clipboard_get`、`ui_dump` 和 `net_status`;每项能力可以有多个 Provider。统一能力支持可选的 `provider` 参数,默认值为 `auto`:

```text
clipboard_get(provider=auto)
→ AppProvider(Android ClipboardManager)
→ ShizukuProvider
→ RootProvider
```

也可以明确指定 `provider=app`、`provider=shizuku` 或 `provider=root`。指定 Provider 不可用时返回 `provider_unavailable`,不会悄悄改用其他通道。`shizuku_exec`、`root_exec` 及带前缀的旧工具是原始通道入口,不经过自动调度。

`capabilities_list` 返回能力 ID、风险等级、声明的 Provider 和当前可用 Provider,便于 MCP 客户端在调用前判断条件。当前普通 App Provider 已覆盖剪贴板读写和网络状态;手机控件树、输入注入、日志、AppOps、进程资源和网络诊断仍由 Shizuku/Root Provider 提供。

## 手机操作

Expand Down Expand Up @@ -50,6 +65,8 @@ AppOps 默认针对当前 Android 用户;`default` 恢复该项的平台默认

固定 Java 辅助入口打包在 APK 中,经现有高权限执行器启动 `app_process`,只接受上述固定操作和 JSON 参数,不接受任意代码。UI 操作在两个后端之间串行执行;连接时保留已有无障碍服务,完成后断开。沿用现有命令超时、输出上限与能力关闭行为。

Provider 调度只负责选择已注册的同一能力实现,不改变底层执行器的参数校验、超时、审计和能力开关。高权限 Provider 失败不会自动升级到 Root;需要 Root 时必须显式启用并选择 `provider=root`。

## 验证

应用单元测试覆盖参数边界、字面量 Unicode 参数传递、辅助进程错误、结果解码、日志过滤、AppOps 读回及进程匹配。
Expand Down
Loading