From c1c720ab9e286f0b5d17b1e17a8df22c2a389e54 Mon Sep 17 00:00:00 2001 From: CN059 Date: Wed, 30 Sep 2026 09:56:42 +0800 Subject: [PATCH] docs: add English SEO README and translations --- README.fr.md | 186 ++++++++++++++++++++++++++++++++++++++++++++++ README.ja.md | 186 ++++++++++++++++++++++++++++++++++++++++++++++ README.md | 173 +++++++++++++++++++++--------------------- README.zh_CN.md | 193 +++++++++++++++++++++++++++++++++++++++++++++++ README.zh_TW.md | 194 ++++++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 849 insertions(+), 83 deletions(-) create mode 100644 README.fr.md create mode 100644 README.ja.md create mode 100644 README.zh_CN.md create mode 100644 README.zh_TW.md diff --git a/README.fr.md b/README.fr.md new file mode 100644 index 0000000..d4b7479 --- /dev/null +++ b/README.fr.md @@ -0,0 +1,186 @@ +
+ +Logo MBrain + +# MBrain + +**Une passerelle MCP Android pour les agents IA.** + +Informations sur l’appareil · Gestion des applications · Fichiers · Root / Shizuku · Agrégation MCP + +

+ Android 9.0 ou version ultérieure + MCP HTTP + Dernière version +

+ +[简体中文](README.zh_CN.md) | [繁體中文](README.zh_TW.md) | [English](README.md) | **Français** | [日本語](README.ja.md) + +[Démarrage rapide](#démarrage-rapide) · [Connexion d’un agent](#connecter-un-agent-ia) · [Services MCP](#ajouter-des-services-mcp) · [FAQ](#faq) · [Signaler un problème](https://github.com/powercess/mbrain/issues) + +
+ +--- + +MBrain est une passerelle Android pour le Model Context Protocol (MCP). Elle permet aux agents IA de consulter l’état du téléphone, de gérer les applications, de manipuler les fichiers et d’exécuter des commandes. Elle regroupe aussi des services MCP supplémentaires derrière un point d’accès unique. Choisissez les capacités à activer sur votre téléphone et arrêtez la passerelle à tout moment. + +## Aperçu + + + + + + + + +
AccueilCapacitésParamètres
Accueil : outils, services et commande de la passerelleGestion des capacités Root, Shizuku et applicationsParamètres de connexion, apparence et historique
+ +Captures de l’application. Les outils disponibles dépendent des capacités activées et des services connectés. Thèmes clair, sombre et système disponibles. + +## Fonctionnalités + +| Capacité | Utilisation | +| --- | --- | +| **Informations sur l’appareil** | Consulter les caractéristiques, la batterie, le stockage et le réseau | +| **Gestion des applications** | Lister, examiner et lancer les applications ; les accès privilégiés permettent aussi leur installation, désinstallation et arrêt | +| **Commandes et fichiers** | Exécuter des commandes via Root ou Shizuku ; parcourir, lire, écrire, copier et déplacer des fichiers | +| **Agrégation MCP** | Connecter des services HTTP MCP locaux ou gérer des processus stdio MCP | +| **Point d’accès unique** | Rechercher les outils, consulter leur description, copier les paramètres de connexion et voir l’historique récent | +| **Accès distant** | Utiliser le client frpc intégré pour exposer MBrain ou d’autres services du téléphone via des tunnels TCP | + +- **Activation à la demande :** Root et Shizuku disposent de commutateurs et de vérifications d’autorisation séparés. +- **Contrôle immédiat :** démarrez ou arrêtez la passerelle depuis l’accueil ou arrêtez-la depuis la notification persistante. +- **Services personnalisés :** renseignez vos propres noms et configurations, sans dépendre d’une application tierce particulière. + +## Démarrage rapide + +### 1. Installer MBrain + +Nécessite **Android 9.0 ou une version ultérieure**. + +Téléchargez `mbrain-v-universal.apk` depuis [GitHub Releases](https://github.com/powercess/mbrain/releases/latest) et installez-le sur votre appareil Android. L’APK universel prend en charge ARM64, ARM32, x86_64 et x86. + +Chaque publication comprend des notes de version et un fichier de sommes de contrôle `SHA256SUMS.txt`. Pour compiler l’application et utiliser les variantes de développement, consultez le [guide de développement](docs/development.md) (chinois simplifié). + +### 2. Choisir les capacités + +Ouvrez l’onglet **Capacités** : + +- Les informations sur l’appareil ne nécessitent pas Root. +- Activez la gestion des applications selon vos besoins. +- Pour les opérations privilégiées, activez **Root** ou **Shizuku** et accordez les autorisations demandées. + +Root nécessite un appareil rooté et une autorisation accordée à **MBrain lui-même**. Pour Shizuku, installez et démarrez [Shizuku](https://shizuku.rikka.app/). Les deux accès peuvent être activés séparément. + +### 3. Démarrer la passerelle + +Depuis **Accueil**, appuyez sur le bouton de démarrage en bas à droite. Une fois la passerelle en cours d’exécution, ouvrez les **coordonnées et identifiants de connexion** pour copier l’URL MCP et le jeton Bearer. + +## Connecter un agent IA + +Ajoutez un service dans un client prenant en charge **MCP sur HTTP et l’authentification Bearer** : + +| Paramètre | Valeur | +| --- | --- | +| Nom | `MBrain`, ou un nom personnalisé | +| URL MCP | `http://127.0.0.1:8765/mcp` | +| Authentification | Jeton Bearer | +| Jeton | À copier depuis la page des identifiants dans MBrain | + +Pour une configuration par en-tête HTTP : + +```http +Authorization: Bearer +``` + +Les **clients sur le même téléphone** utilisent directement cette adresse. Les **clients sur ordinateur** nécessitent une connexion ADB et une redirection de port : + +```bash +adb forward tcp:8765 tcp:8765 +``` + +Si le port par défaut est occupé, MBrain en choisit un disponible. Utilisez l’adresse et la commande ADB affichées dans l’application. Le jeton est chiffré sur l’appareil, conservé après redémarrage et réinitialisable depuis la page des identifiants. + +Commencez par une requête en lecture seule : + +> Vérifie le niveau de batterie et l’espace de stockage disponible sur ce téléphone. + +## Ajouter des services MCP + +Ouvrez **MCP → Ajouter un service**, puis choisissez : + +| Type | Usage | Configuration | +| --- | --- | --- | +| **Service HTTP** | Une autre application ou un processus exécute déjà le service sur le téléphone | Nom, URL locale, jeton facultatif | +| **Processus géré** | MBrain démarre et gère un service stdio MCP | Nom, exécutable, arguments séparés, identité d’exécution | + +Enregistrez, puis sélectionnez **Connecter le service** dans ses détails. Ses outils rejoignent le catalogue et deviennent accessibles via la même URL MCP. + +Les services HTTP doivent actuellement utiliser une adresse de bouclage. Préparez les exécutables et les environnements nécessaires sur l’appareil avant d’ajouter un processus géré : MBrain n’inclut ni Node.js ni Python. + +## Accès distant + +Le client **frpc** intégré peut rediriger MBrain ou d’autres services du téléphone via un serveur **frps** que vous hébergez. Dans **Paramètres → Accès distant → Configurer le serveur**, saisissez l’adresse, le port et le jeton, puis ajoutez des tunnels TCP. + +Tous les tunnels partagent une configuration de serveur. Chacun dispose de commandes indépendantes de démarrage, d’arrêt et de nouvelle tentative. Les tunnels MCP suivent le cycle de vie de la passerelle ; les tunnels personnalisés fonctionnent indépendamment. Seule la redirection TCP de base est prise en charge. Consultez le [guide d’accès distant](docs/remote-access.md) (chinois simplifié). + +## Autorisations et sécurité + +- La passerelle écoute uniquement sur l’interface de bouclage du téléphone. Utilisez ADB depuis un ordinateur et les tunnels configurés pour l’accès distant. +- Tout client disposant du jeton peut appeler **tous les outils activés**. Les autorisations par client ne sont pas encore prises en charge. +- Les outils Root et Shizuku peuvent modifier réellement l’appareil. Connectez uniquement des clients de confiance et gardez le jeton privé. +- Choisissez les capacités sur le téléphone et arrêtez la passerelle lorsque l’accès n’est plus nécessaire. + +## FAQ + +
+Puis-je utiliser MBrain sans Root ? + +Oui. Les informations sur l’appareil, la consultation et le lancement ordinaires d’applications ainsi que les services HTTP MCP locaux ne nécessitent pas Root. Shizuku offre un autre accès privilégié, dont les possibilités dépendent de son mode de démarrage. + +
+ +
+Pourquoi mon client ne se connecte-t-il pas ? + +Vérifiez que la passerelle fonctionne et que le jeton correspond à celui affiché dans l’application. Sur ordinateur, vérifiez la redirection ADB du port réel. La passerelle écoute uniquement sur l’interface de bouclage ; l’accès distant nécessite un tunnel TCP configuré. + +
+ +
+Pourquoi un outil est-il absent ? + +La liste dépend des capacités activées, des autorisations et des services connectés. Vérifiez les onglets Capacités et MCP, puis actualisez les outils dans votre client. + +
+ +
+Que se passe-t-il lorsque j’arrête la passerelle ? + +MBrain n’accepte plus de requêtes, déconnecte les services MCP externes et termine les processus enfants directement gérés. La passerelle ne démarre pas automatiquement au démarrage du téléphone. L’historique reste uniquement en mémoire. + +
+ +## Contribuer + +Les signalements, suggestions, améliorations de documentation et contributions de code sont les bienvenus. Utilisez les [modèles de tickets](https://github.com/powercess/mbrain/issues/new/choose) en précisant la version et les étapes de reproduction. Masquez les jetons et les informations privées dans les captures et journaux. + +Le [guide de contribution](CONTRIBUTING.md) (anglais) décrit l’installation, la compilation, les vérifications et les pull requests. Créez une branche dédiée à partir du dernier `dev` et ciblez `dev` pour votre pull request. Le [guide de développement](docs/development.md) (chinois simplifié) détaille les tests sur appareil. + +## Remerciements + +- [droid-mcp](https://github.com/stixez/droid-mcp) : base Android MCP utilisée par MBrain, avec conservation de sa [licence Apache-2.0](vendor/droid-mcp/LICENSE) et de son [historique de provenance](vendor/droid-mcp/UPSTREAM.md). +- [Shizuku](https://github.com/RikkaApps/Shizuku) et [libsu](https://github.com/topjohnwu/libsu) : accès privilégiés Android. +- [RikkaHub](https://github.com/rikkahub/rikkahub) : référence pour les listes de paramètres et les interactions. + +## Star History + +Si MBrain vous est utile, vous pouvez soutenir le projet avec une étoile. + + + + + Évolution des étoiles GitHub de MBrain + + +Graphique fourni par Star History. diff --git a/README.ja.md b/README.ja.md new file mode 100644 index 0000000..dacf7d6 --- /dev/null +++ b/README.ja.md @@ -0,0 +1,186 @@ +
+ +MBrain ロゴ + +# MBrain + +**AI エージェントから Android の機能を利用できる MCP ゲートウェイ。** + +端末情報 · アプリ管理 · ファイル操作 · Root / Shizuku · MCP サービスの集約 + +

+ Android 9.0 以降 + HTTP MCP + 最新リリース +

+ +[简体中文](README.zh_CN.md) | [繁體中文](README.zh_TW.md) | [English](README.md) | [Français](README.fr.md) | **日本語** + +[クイックスタート](#クイックスタート) · [エージェントの接続](#ai-エージェントを接続する) · [MCP サービスの追加](#mcp-サービスを追加する) · [よくある質問](#よくある質問) · [問題を報告](https://github.com/powercess/mbrain/issues) + +
+ +--- + +MBrain は、Android 上で動作する Model Context Protocol(MCP)ゲートウェイです。AI エージェントは、単一のエンドポイントを通じて端末情報の取得、アプリ管理、ファイル操作、コマンド実行、外部 MCP サービスの利用を行えます。公開する機能は端末側で選択でき、ゲートウェイはいつでも停止できます。 + +## スクリーンショット + + + + + + + + +
ホーム機能管理設定
ホーム:ツール、サービス、ゲートウェイの起動と停止Root、Shizuku、アプリ管理の機能設定接続情報、外観、実行履歴の設定
+ +実際のアプリ画面です。利用可能なツールは、有効な機能と接続済みサービスによって変わります。ライト、ダーク、システムに合わせるテーマに対応しています。 + +## 主な機能 + +| 機能 | 内容 | +| --- | --- | +| **端末情報** | 端末の詳細、バッテリー、ストレージ、ネットワークの状態を取得 | +| **アプリ管理** | アプリの一覧・詳細の取得と起動。特権アクセスではインストール、アンインストール、停止も可能 | +| **コマンドとファイル** | Root または Shizuku でコマンドを実行し、ファイルの参照、読み書き、コピー、移動を実施 | +| **MCP サービスの集約** | 端末内の HTTP MCP サービスを接続、または stdio MCP プロセスを起動・管理 | +| **単一の接続先** | ツールの検索、説明の確認、接続情報のコピー、最近の実行履歴の確認 | +| **リモートアクセス** | 内蔵 frpc で TCP トンネルを作成し、MBrain や端末内の別サービスへ接続 | + +- **必要な機能だけ有効化:** Root と Shizuku は個別のスイッチと権限確認を備えています。 +- **すぐに停止:** ホームから起動・停止でき、常駐通知からも停止できます。 +- **任意のサービスを追加:** サービス名と設定を指定でき、特定のサードパーティーアプリに依存しません。 + +## クイックスタート + +### 1. MBrain をインストールする + +**Android 9.0 以降**が必要です。 + +[GitHub Releases](https://github.com/powercess/mbrain/releases/latest) から最新の `mbrain-v-universal.apk` をダウンロードし、Android 端末にインストールしてください。ユニバーサル APK は ARM64、ARM32、x86_64、x86 に対応しています。 + +リリースには変更内容とチェックサムファイル `SHA256SUMS.txt` が含まれます。ソースからのビルドや開発版については、[開発ガイド](docs/development.md)(簡体字中国語)をご覧ください。 + +### 2. 公開する機能を選ぶ + +下部の**機能**タブを開きます。 + +- 端末情報の取得には Root は不要です。 +- 必要に応じてアプリ管理を有効にします。 +- 特権操作には **Root** または **Shizuku** を有効にし、権限を許可します。 + +Root を使うには、端末が root 化されており、**MBrain 自体**に権限が付与されている必要があります。Shizuku を使う場合は、先に [Shizuku](https://shizuku.rikka.app/) をインストールして起動してください。両方を同時に有効にする必要はありません。 + +### 3. ゲートウェイを起動する + +**ホーム**の右下にある起動ボタンを押します。起動後、**接続先と認証情報**を開き、MCP URL と Bearer トークンをコピーします。 + +## AI エージェントを接続する + +**HTTP MCP と Bearer 認証**に対応したクライアントでサービスを追加します。 + +| 項目 | 値 | +| --- | --- | +| 名前 | `MBrain`、または任意の名前 | +| MCP URL | `http://127.0.0.1:8765/mcp` | +| 認証方式 | Bearer トークン | +| トークン | MBrain の認証情報画面からコピー | + +HTTP ヘッダーで認証を設定する場合: + +```http +Authorization: Bearer +``` + +**同じ端末上のクライアント**は、この URL をそのまま使えます。**パソコン上のクライアント**は、ADB で端末に接続してポートを転送します。 + +```bash +adb forward tcp:8765 tcp:8765 +``` + +既定のポートが使用中の場合は、空いているポートが選択されます。アプリ内に表示される実際の URL と ADB コマンドを使用してください。トークンは端末上で暗号化して保存され、再起動後も維持されます。認証情報画面からリセットできます。 + +まずは読み取り専用の簡単なリクエストを試してください。 + +> この端末のバッテリー残量とストレージの空き容量を確認してください。 + +## MCP サービスを追加する + +**MCP → サービスを追加**で接続方式を選びます。 + +| 方式 | 用途 | 設定項目 | +| --- | --- | --- | +| **HTTP サービス** | 端末上の別アプリやプロセスですでにサービスが動作している場合 | 名前、ローカル URL、任意のトークン | +| **管理対象プロセス** | MBrain が stdio MCP サービスを起動・管理する場合 | 名前、実行ファイル、個別の引数、実行ユーザー | + +保存後、詳細画面で**サービスに接続**を選択します。接続が成功すると、そのサービスのツールがゲートウェイの一覧に追加され、同じ MCP エンドポイントから利用できます。 + +HTTP サービスは現在、ループバックアドレスのみ対応しています。管理対象プロセスに必要な実行ファイルやランタイムは、事前に端末に用意してください。MBrain に Node.js や Python は含まれていません。 + +## リモートアクセス + +内蔵 **frpc** クライアントを使い、自分で運用する **frps** サーバー経由で MBrain や端末内の別サービスに接続できます。**設定 → リモートアクセス → サーバー設定**でアドレス、ポート、トークンを入力し、TCP トンネルを追加します。 + +すべてのトンネルは同じサーバー設定を共有します。トンネルごとに起動、停止、再試行が可能です。MCP トンネルはゲートウェイの起動・停止に連動し、カスタムサービスのトンネルは独立して動作します。現在は基本的な TCP 転送のみ対応しています。[リモートアクセスガイド](docs/remote-access.md)(簡体字中国語)で設定例と動作を確認できます。 + +## 権限とセキュリティ + +- ゲートウェイは端末のループバックインターフェースだけで待ち受けます。パソコンからは ADB 転送、遠隔地からは設定済みトンネルを利用します。 +- Bearer トークンを持つクライアントは、**有効なすべてのツール**を呼び出せます。クライアントごとの権限設定には未対応です。 +- Root や Shizuku のツールは端末を実際に変更できます。信頼できるクライアントだけを接続し、トークンを共有しないでください。 +- 公開する機能は端末で選び、不要になったらゲートウェイを停止してください。 + +## よくある質問 + +
+Root なしでも使えますか? + +はい。端末情報の取得、通常のアプリ情報の取得・起動、ローカル HTTP MCP サービスの接続には Root は不要です。特権操作には Shizuku も使えますが、操作できる範囲は起動方法によって異なります。 + +
+ +
+クライアントが接続できません。 + +ゲートウェイが起動していることと、認証情報画面のトークンを使っていることを確認してください。パソコンからの場合は、実際のポートへの ADB 転送も確認します。待ち受けはループバックのみのため、リモート接続には設定済みの TCP トンネルが必要です。 + +
+ +
+必要なツールが見つかりません。 + +ツール一覧は、機能スイッチ、権限、外部サービスの接続状態で変わります。機能タブと MCP タブを確認し、クライアント側で一覧を更新してください。 + +
+ +
+ゲートウェイを停止するとどうなりますか? + +リクエストの受付と外部 MCP サービスへの接続を停止し、直接管理している子プロセスを終了します。端末の起動時にゲートウェイが自動起動することはありません。実行履歴は現在、メモリ内だけに保持されます。 + +
+ +## コントリビューション + +不具合報告、機能提案、ドキュメント改善、コードの貢献を歓迎します。[Issue テンプレート](https://github.com/powercess/mbrain/issues/new/choose)を使い、バージョンと再現手順を記載してください。スクリーンショットやログからトークンと個人情報を取り除いてください。 + +環境構築、ビルド、検証、プルリクエストの流れは[貢献ガイド](CONTRIBUTING.md)(英語)を参照してください。最新の `dev` から専用ブランチを作り、プルリクエストの対象は `dev` にしてください。端末でのテストは[開発ガイド](docs/development.md)(簡体字中国語)に記載しています。 + +## 謝辞 + +- [droid-mcp](https://github.com/stixez/droid-mcp):MBrain が使用する Android MCP の基盤。[Apache-2.0 ライセンス](vendor/droid-mcp/LICENSE)と[由来の記録](vendor/droid-mcp/UPSTREAM.md)を保持しています。 +- [Shizuku](https://github.com/RikkaApps/Shizuku) と [libsu](https://github.com/topjohnwu/libsu):Android の特権アクセス。 +- [RikkaHub](https://github.com/rikkahub/rikkahub):設定リストと操作設計の参考。 + +## Star History + +MBrain が役に立ったら、ぜひスターで応援してください。 + + + + + MBrain の GitHub スター数の推移 + + +グラフ提供:Star History。 diff --git a/README.md b/README.md index e0ca0c3..81be4c2 100644 --- a/README.md +++ b/README.md @@ -4,180 +4,187 @@ # MBrain -**让 AI Agent 调用你的 Android 手机能力。** +**An Android MCP gateway for AI agent device control.** -设备信息 · 应用管理 · 文件操作 · Root / Shizuku · MCP 服务聚合 +Device information · App management · File operations · Root / Shizuku · MCP service aggregation

- Android 9.0 及以上 + Android 9.0 or later HTTP MCP - 最新版本 + Latest release

-[快速上手](#快速上手) · [连接 Agent](#连接-agent) · [接入 MCP 服务](#接入-mcp-服务) · [常见问题](#常见问题) · [反馈问题](https://github.com/powercess/mbrain/issues) +[简体中文](README.zh_CN.md) | [繁體中文](README.zh_TW.md) | **English** | [Français](README.fr.md) | [日本語](README.ja.md) + +[Quick start](#quick-start) · [Connect an agent](#connect-an-ai-agent) · [Add MCP services](#add-mcp-services) · [FAQ](#faq) · [Report an issue](https://github.com/powercess/mbrain/issues) --- -MBrain 是运行在 Android 上的 MCP 网关。它把手机自身的能力和你接入的 MCP 服务汇集到一个入口,让支持 MCP 的 AI 客户端读取设备状态、管理应用、操作文件或执行命令。你可以在手机上选择开放哪些能力,并随时停止服务。 +MBrain is an Android gateway for the Model Context Protocol (MCP) that lets AI agents access device information, manage apps, operate files, execute commands, and connect to additional MCP services through one unified endpoint. Enable only the capabilities you need and stop the gateway at any time. -## 界面预览 +## Screenshots - - - + + + - - - + + +
首页能力管理设置HomeCapabilitiesSettings
首页:工具与服务概览,右下角悬浮启停按钮能力管理:按需启用 Root、Shizuku 和应用管理设置:连接凭据、外观和运行记录Home screen with tools, services, and gateway controlCapability management for Root, Shizuku, and appsSettings for credentials, appearance, and runtime logs
-应用实际运行截图。可用工具数量取决于已启用能力和接入服务;支持浅色、深色及跟随系统。 +Screenshots from the running app. Available tools depend on enabled capabilities and connected services. Light, dark, and system themes are supported. -## 可以做什么 +## Features -| 能力 | 用途 | +| Capability | What it provides | | --- | --- | -| **读取设备状态** | 查看设备信息、电量、存储空间和网络状态 | -| **管理应用** | 查看应用列表与详情、启动应用;高权限通道还可安装、卸载和停止应用 | -| **执行命令与操作文件** | 通过 Root 或 Shizuku 执行命令,浏览、读取、写入、复制和移动文件 | -| **接入其他 MCP 服务** | 添加手机本机的 HTTP MCP 服务,或由 MBrain 启动和管理 stdio MCP 进程 | -| **统一管理与连接** | 一个 MCP 地址提供工具目录,支持搜索工具、查看说明、复制连接信息和查看近期运行记录 | -| **内网穿透** | 内置 frpc,统一配置一台服务器,多条基础 TCP 隧道转发 MBrain 或手机其他服务 | +| **Device information** | Read device details, battery, storage, and network status | +| **App management** | List, inspect, and launch apps; privileged channels can also install, uninstall, and stop apps | +| **Commands and files** | Run commands through Root or Shizuku and browse, read, write, copy, or move files | +| **MCP service aggregation** | Add local HTTP MCP services or let MBrain manage stdio MCP processes | +| **One endpoint** | Expose one searchable tool catalog with connection details and recent run history | +| **Remote access** | Use the built-in frpc client to forward MBrain or other phone services through TCP tunnels | -- **按需启用**:Root 和 Shizuku 各用一个开关,打开时自动检查并申请权限。 -- **随时停止**:首页右下角一键启停,也可从前台通知停止网关。 -- **服务自由添加**:填写自己的服务名称与配置,不绑定特定第三方应用。 +- **Opt-in capabilities:** Root and Shizuku have separate switches and permission checks. +- **One-tap control:** Start or stop the gateway from Home or the foreground notification. +- **Bring your own services:** Add service names and configurations without being tied to a specific third-party app. -## 快速上手 +## Quick start -### 1. 安装 MBrain +### 1. Install MBrain -需要 **Android 9.0 或更高版本**。 +Requires **Android 9.0 or later**. -从 [GitHub Releases](https://github.com/powercess/mbrain/releases/latest) 下载最新版本的 `mbrain-v版本号-universal.apk`,在 Android 设备上打开并安装。通用安装包覆盖 ARM64、ARM32、x86_64 和 x86,无需挑选架构。 +Download the latest `mbrain-v-universal.apk` from [GitHub Releases](https://github.com/powercess/mbrain/releases/latest) and install it on your Android device. The universal APK supports ARM64, ARM32, x86_64, and x86. -发行页面提供更新说明和 `SHA256SUMS.txt` 校验文件。自行构建及开发测试版说明见[开发指南](docs/development.md)。 +Releases include notes and a `SHA256SUMS.txt` checksum file. See the [development guide](docs/development.md) for local builds and development variants. -### 2. 选择需要开放的能力 +### 2. Choose capabilities -打开底部的 **能力** 页面: +Open the **Capabilities** tab: -- 设备信息不需要 Root。 -- 按需启用应用管理。 -- 需要高权限操作时,进入 **Root** 或 **Shizuku**,打开启用开关,并完成授权。 +- Device information does not require Root. +- Enable app management when needed. +- For privileged operations, enable **Root** or **Shizuku** and complete authorization. -使用 Root 需要设备具备 Root 能力,并允许 **MBrain 本身**获取权限。使用 Shizuku 则需先安装并启动 [Shizuku](https://shizuku.rikka.app/)。两种通道可以分别启用,不需要同时开启。 +Root requires a rooted device and permission granted to **MBrain itself**. Shizuku requires [Shizuku](https://shizuku.rikka.app/) to be installed and running. The two channels can be enabled independently. -### 3. 启动网关 +### 3. Start the gateway -回到 **首页**,点击右下角的启动按钮。显示“运行中”后,打开 **连接地址与凭据**,获取 MCP 地址和 Bearer Token。 +Return to **Home**, tap the start button, then open **Connection details and credentials** to copy the MCP URL and Bearer token. -## 连接 Agent +## Connect an AI agent -在支持 **HTTP MCP 和 Bearer 认证**的客户端中添加服务: +Add MBrain to a client that supports **HTTP MCP and Bearer authentication**: -| 配置项 | 填写内容 | +| Setting | Value | | --- | --- | -| 名称 | `MBrain`,也可自行命名 | -| MCP 地址 | `http://127.0.0.1:8765/mcp` | -| 认证方式 | Bearer Token | -| Token | 从 MBrain 的“连接地址与凭据”页面复制 | +| Name | `MBrain`, or a name of your choice | +| MCP URL | `http://127.0.0.1:8765/mcp` | +| Authentication | Bearer token | +| Token | Copy from the app's connection credentials page | -如果客户端通过请求头配置认证,填写: +For clients configured through request headers: ```http -Authorization: Bearer <从 MBrain 复制的 Token> +Authorization: Bearer ``` -**同一台手机上的客户端**可以直接使用上述地址。 - -**电脑上的客户端**需要先通过 ADB 连接手机,再转发端口: +**Clients on the same phone** can use the URL directly. **Desktop clients** need an ADB connection and port forwarding: ```bash adb forward tcp:8765 tcp:8765 ``` -默认端口被占用时,网关会自动使用空闲端口。请以“连接地址与凭据”中的实际地址及“使用说明”中的 ADB 命令为准。Token 加密保存在设备上,重启后保持不变;可在凭据页重置。 +If the default port is occupied, MBrain chooses an available port. Use the actual URL and ADB command shown in the app. The token is encrypted on the device, persists across restarts, and can be reset from the credentials page. + +Try a simple read-only request: -**远程客户端**可在“设置 → 内网穿透”配置一台自建 frps,再添加 TCP 隧道。每条隧道独立启停与重试;MCP 隧道跟随网关,自定义服务隧道独立运行。具体见[内网穿透指南](docs/remote-access.md)。 +> Check this phone's battery level and available storage. -连接后可以先让 Agent 执行一个简单的只读请求: +## Add MCP services -> 查看这台手机的电量和剩余存储空间。 +Open **MCP → Add service** and choose a connection type: -> **权限说明**:当前持有 Token 的客户端可以调用全部已启用工具,尚不支持为不同客户端单独分配权限。Root / Shizuku 工具能够执行实际修改,请只连接可信客户端,不要分享 Token。 +| Type | Use case | Configuration | +| --- | --- | --- | +| **HTTP service** | Another app or process already runs the service on the phone | Name, local URL, optional token | +| **Managed process** | MBrain starts and manages a stdio MCP process | Name, executable, individual arguments, execution identity | -## 接入 MCP 服务 +Save the configuration and select **Connect service** in its details. Connected tools join the gateway's catalog and are available through the same MCP endpoint. -需要从公网连接时,可进入 **设置 → 内网穿透 → 配置服务器** 填写 frps 地址、端口和 Token。当前仅支持基础 TCP 转发,所有隧道共用一台服务器。配置示例与运行规则见[内网穿透指南](docs/remote-access.md)。 +HTTP services currently require loopback addresses. Prepare executables and runtimes on the device before adding managed processes; MBrain does not bundle Node.js or Python. -进入 **MCP → 添加服务**,选择连接方式: +## Remote access -| 方式 | 适用情况 | 需要填写 | -| --- | --- | --- | -| **HTTP 服务** | 服务已经由手机上的其他应用或进程启动 | 名称、本机服务地址、可选 Token | -| **托管进程** | 希望由 MBrain 启动并管理 stdio MCP 服务 | 名称、程序、逐项启动参数、执行身份 | +The built-in **frpc** client can forward MBrain or other phone services through a self-hosted **frps** server. Open **Settings → Remote access → Configure server**, enter the server address, port, and token, then add TCP tunnels. + +All tunnels share one server configuration. Each tunnel has independent start, stop, and retry controls. MCP tunnels follow the gateway lifecycle; custom service tunnels run independently. Only basic TCP forwarding is supported. See the [remote access guide](docs/remote-access.md) (Simplified Chinese) for configuration and operating rules. -保存配置后,在服务详情中点击 **连接服务**。成功连接后,该服务的工具会加入 MBrain 的工具目录,Agent 可以通过同一个入口调用。 +## Permissions and security -HTTP 服务目前只支持回环地址。托管进程所需的程序和运行环境需要事先在设备上准备好,MBrain 不内置 Node.js 或 Python。 +- The gateway listens only on the phone's loopback interface. Desktop access uses ADB forwarding; remote access uses configured tunnels. +- Any client with the Bearer token can call **all enabled tools**. Per-client permissions are not currently supported. +- Root and Shizuku tools can make real changes to the device. Connect trusted clients and keep the token private. +- Choose capabilities on the phone and stop the gateway whenever access is no longer needed. -## 常见问题 +## FAQ
-没有 Root,能使用吗? +Can I use MBrain without Root? -可以。设备信息、普通应用查询与启动、本机 HTTP MCP 接入不依赖 Root。需要更高权限时,可以使用 Shizuku;实际操作范围取决于它的启动方式。 +Yes. Device information, ordinary app queries and launching, and local HTTP MCP services do not require Root. Shizuku provides another channel for privileged operations; its capabilities depend on how it was started.
-为什么客户端连接不上? +Why can't my client connect? -先确认首页显示“运行中”,并使用凭据页中的 Token。电脑连接时还需确认实际端口的 ADB 转发成功。网关仅监听手机回环地址;远程访问通过已配置的 TCP 隧道连接。 +Check that the gateway is running and the token matches the credentials page. For desktop access, verify ADB forwarding for the actual port. The gateway listens only on loopback; remote connections require a configured TCP tunnel.
-为什么找不到某个工具? +Why is a tool missing? -工具数量随能力开关、权限状态和外部服务连接情况变化。先在能力页检查开关,再到 MCP 页检查服务状态,最后在客户端重新获取工具列表。 +Available tools depend on capability switches, permissions, and external service connections. Check Capabilities and MCP service status, then refresh the tool list in your client.
-停止服务后会发生什么? +What happens when I stop the gateway? -网关停止接收请求,断开外部 MCP 连接,并清理直接托管的子进程。应用不会在开机后自动启动网关;运行记录目前仅保留在内存中。 +MBrain stops accepting requests, disconnects external MCP services, and cleans up directly managed child processes. It does not automatically start the gateway at boot. Run history is currently kept only in memory.
-## 反馈与参与 +## Contributing -遇到问题或有功能建议,欢迎通过 [Issue 模板](https://github.com/powercess/mbrain/issues/new/choose)反馈。描述问题时请附上版本和复现步骤;截图或日志中请隐去 Token 与私人信息。 +Bug reports, feature suggestions, documentation improvements, and code contributions are welcome. Use the [issue templates](https://github.com/powercess/mbrain/issues/new/choose) and include the app version and reproduction steps. Remove tokens and private information from screenshots and logs. -Contributions through bug reports, documentation improvements, and code are welcome. Read the [contributing guide](CONTRIBUTING.md) for local setup, building and running the app, validation, and the pull request workflow. Start each contribution on a dedicated branch based on the latest `dev` and target `dev` in your pull request. For detailed device testing, see the [development guide](docs/development.md). +Read the [contributing guide](CONTRIBUTING.md) for setup, building, validation, and the pull request workflow. Start from the latest `dev` on a dedicated branch and target `dev` in your pull request. The [development guide](docs/development.md) (Simplified Chinese) covers device testing. -## 致谢 +## Acknowledgements -- [droid-mcp](https://github.com/stixez/droid-mcp):MBrain 使用的 Android MCP 基座,保留其 [Apache-2.0 许可证](vendor/droid-mcp/LICENSE)和[来源记录](vendor/droid-mcp/UPSTREAM.md)。 -- [Shizuku](https://github.com/RikkaApps/Shizuku) 与 [libsu](https://github.com/topjohnwu/libsu):Android 高权限能力接入。 -- [RikkaHub](https://github.com/rikkahub/rikkahub):设置列表与交互设计参考。 +- [droid-mcp](https://github.com/stixez/droid-mcp): the Android MCP foundation used by MBrain, with its [Apache-2.0 license](vendor/droid-mcp/LICENSE) and [upstream record](vendor/droid-mcp/UPSTREAM.md) retained. +- [Shizuku](https://github.com/RikkaApps/Shizuku) and [libsu](https://github.com/topjohnwu/libsu): Android privileged access. +- [RikkaHub](https://github.com/rikkahub/rikkahub): settings list and interaction design reference. ## Star History -如果 MBrain 对你有帮助,欢迎点一个 Star。 +If MBrain is useful to you, consider giving it a star. - MBrain 的 GitHub Star 增长趋势 + MBrain GitHub star history -Star 趋势由 Star History 提供。 +Chart provided by Star History. diff --git a/README.zh_CN.md b/README.zh_CN.md new file mode 100644 index 0000000..8d3e730 --- /dev/null +++ b/README.zh_CN.md @@ -0,0 +1,193 @@ +
+ +MBrain Logo + +# MBrain + +**让 AI Agent 调用你的 Android 手机能力。** + +设备信息 · 应用管理 · 文件操作 · Root / Shizuku · MCP 服务聚合 + +

+ Android 9.0 及以上 + HTTP MCP + 最新版本 +

+ +**简体中文** | [繁體中文](README.zh_TW.md) | [English](README.md) | [Français](README.fr.md) | [日本語](README.ja.md) + +[快速上手](#快速上手) · [连接 Agent](#连接-agent) · [接入 MCP 服务](#接入-mcp-服务) · [常见问题](#常见问题) · [反馈问题](https://github.com/powercess/mbrain/issues) + +
+ +--- + +MBrain 是运行在 Android 上的 Model Context Protocol(MCP)网关。它把手机自身的能力和你接入的 MCP 服务汇集到一个入口,让支持 MCP 的 AI 客户端读取设备状态、管理应用、操作文件或执行命令。你可以在手机上选择开放哪些能力,并随时停止服务。 + +## 界面预览 + + + + + + + + + + + + +
首页能力管理设置
首页:工具与服务概览,右下角悬浮启停按钮能力管理:按需启用 Root、Shizuku 和应用管理设置:连接凭据、外观和运行记录
+ +应用实际运行截图。可用工具数量取决于已启用能力和接入服务;支持浅色、深色及跟随系统。 + +## 可以做什么 + +| 能力 | 用途 | +| --- | --- | +| **读取设备状态** | 查看设备信息、电量、存储空间和网络状态 | +| **管理应用** | 查看应用列表与详情、启动应用;高权限通道还可安装、卸载和停止应用 | +| **执行命令与操作文件** | 通过 Root 或 Shizuku 执行命令,浏览、读取、写入、复制和移动文件 | +| **接入其他 MCP 服务** | 添加手机本机的 HTTP MCP 服务,或由 MBrain 启动和管理 stdio MCP 进程 | +| **统一管理与连接** | 一个 MCP 地址提供工具目录,支持搜索工具、查看说明、复制连接信息和查看近期运行记录 | +| **内网穿透** | 内置 frpc,统一配置一台服务器,多条基础 TCP 隧道转发 MBrain 或手机其他服务 | + +- **按需启用**:Root 和 Shizuku 各用一个开关,打开时自动检查并申请权限。 +- **随时停止**:首页右下角一键启停,也可从前台通知停止网关。 +- **服务自由添加**:填写自己的服务名称与配置,不绑定特定第三方应用。 + +## 快速上手 + +### 1. 安装 MBrain + +需要 **Android 9.0 或更高版本**。 + +从 [GitHub Releases](https://github.com/powercess/mbrain/releases/latest) 下载最新版本的 `mbrain-v版本号-universal.apk`,在 Android 设备上打开并安装。通用安装包覆盖 ARM64、ARM32、x86_64 和 x86,无需挑选架构。 + +发行页面提供更新说明和 `SHA256SUMS.txt` 校验文件。自行构建及开发测试版说明见[开发指南](docs/development.md)。 + +### 2. 选择需要开放的能力 + +打开底部的 **能力** 页面: + +- 设备信息不需要 Root。 +- 按需启用应用管理。 +- 需要高权限操作时,进入 **Root** 或 **Shizuku**,打开启用开关,并完成授权。 + +使用 Root 需要设备具备 Root 能力,并允许 **MBrain 本身**获取权限。使用 Shizuku 则需先安装并启动 [Shizuku](https://shizuku.rikka.app/)。两种通道可以分别启用,不需要同时开启。 + +### 3. 启动网关 + +回到 **首页**,点击右下角的启动按钮。显示“运行中”后,打开 **连接地址与凭据**,获取 MCP 地址和 Bearer Token。 + +## 连接 Agent + +在支持 **HTTP MCP 和 Bearer 认证**的客户端中添加服务: + +| 配置项 | 填写内容 | +| --- | --- | +| 名称 | `MBrain`,也可自行命名 | +| MCP 地址 | `http://127.0.0.1:8765/mcp` | +| 认证方式 | Bearer Token | +| Token | 从 MBrain 的“连接地址与凭据”页面复制 | + +如果客户端通过请求头配置认证,填写: + +```http +Authorization: Bearer <从 MBrain 复制的 Token> +``` + +**同一台手机上的客户端**可以直接使用上述地址。 + +**电脑上的客户端**需要先通过 ADB 连接手机,再转发端口: + +```bash +adb forward tcp:8765 tcp:8765 +``` + +默认端口被占用时,网关会自动使用空闲端口。请以“连接地址与凭据”中的实际地址及“使用说明”中的 ADB 命令为准。Token 加密保存在设备上,重启后保持不变;可在凭据页重置。 + +连接后可以先让 Agent 执行一个简单的只读请求: + +> 查看这台手机的电量和剩余存储空间。 + +## 接入 MCP 服务 + +进入 **MCP → 添加服务**,选择连接方式: + +| 方式 | 适用情况 | 需要填写 | +| --- | --- | --- | +| **HTTP 服务** | 服务已经由手机上的其他应用或进程启动 | 名称、本机服务地址、可选 Token | +| **托管进程** | 希望由 MBrain 启动并管理 stdio MCP 服务 | 名称、程序、逐项启动参数、执行身份 | + +保存配置后,在服务详情中点击 **连接服务**。成功连接后,该服务的工具会加入 MBrain 的工具目录,Agent 可以通过同一个入口调用。 + +HTTP 服务目前只支持回环地址。托管进程所需的程序和运行环境需要事先在设备上准备好,MBrain 不内置 Node.js 或 Python。 + +## 远程访问 + +内置 **frpc** 客户端,可通过自建 **frps** 服务器转发 MBrain 或手机上的其他服务。进入 **设置 → 内网穿透 → 配置服务器**,填写服务器地址、端口和 Token,再添加 TCP 隧道。 + +当前仅支持基础 TCP 转发,所有隧道共用一台服务器。每条隧道独立启停与重试;MCP 隧道跟随网关,自定义服务隧道独立运行。配置示例与运行规则见[内网穿透指南](docs/remote-access.md)。 + +## 权限与安全 + +- 网关仅监听手机回环地址。电脑通过 ADB 转发连接,远程访问通过已配置的隧道连接。 +- 持有 Bearer Token 的客户端可以调用**全部已启用工具**,尚不支持为不同客户端单独分配权限。 +- Root / Shizuku 工具能够执行实际修改,请只连接可信客户端,不要分享 Token。 +- 在手机上选择开放的能力,不再需要时随时停止网关。 + +## 常见问题 + +
+没有 Root,能使用吗? + +可以。设备信息、普通应用查询与启动、本机 HTTP MCP 接入不依赖 Root。需要更高权限时,可以使用 Shizuku;实际操作范围取决于它的启动方式。 + +
+ +
+为什么客户端连接不上? + +先确认首页显示“运行中”,并使用凭据页中的 Token。电脑连接时还需确认实际端口的 ADB 转发成功。网关仅监听手机回环地址;远程访问通过已配置的 TCP 隧道连接。 + +
+ +
+为什么找不到某个工具? + +工具数量随能力开关、权限状态和外部服务连接情况变化。先在能力页检查开关,再到 MCP 页检查服务状态,最后在客户端重新获取工具列表。 + +
+ +
+停止服务后会发生什么? + +网关停止接收请求,断开外部 MCP 连接,并清理直接托管的子进程。应用不会在开机后自动启动网关;运行记录目前仅保留在内存中。 + +
+ +## 反馈与参与 + +遇到问题或有功能建议,欢迎通过 [Issue 模板](https://github.com/powercess/mbrain/issues/new/choose)反馈。描述问题时请附上版本和复现步骤;截图或日志中请隐去 Token 与私人信息。 + +欢迎提交问题报告、改进文档或贡献代码。请阅读[贡献指南](CONTRIBUTING.md)(英文),了解本地环境、构建运行、验证及拉取请求流程。基于最新 `dev` 创建独立分支,并将拉取请求提交到 `dev`。详细设备测试步骤见[开发指南](docs/development.md)。 + +## 致谢 + +- [droid-mcp](https://github.com/stixez/droid-mcp):MBrain 使用的 Android MCP 基座,保留其 [Apache-2.0 许可证](vendor/droid-mcp/LICENSE)和[来源记录](vendor/droid-mcp/UPSTREAM.md)。 +- [Shizuku](https://github.com/RikkaApps/Shizuku) 与 [libsu](https://github.com/topjohnwu/libsu):Android 高权限能力接入。 +- [RikkaHub](https://github.com/rikkahub/rikkahub):设置列表与交互设计参考。 + +## Star History + +如果 MBrain 对你有帮助,欢迎点一个 Star。 + + + + + MBrain 的 GitHub Star 增长趋势 + + +Star 趋势由 Star History 提供。 + diff --git a/README.zh_TW.md b/README.zh_TW.md new file mode 100644 index 0000000..e782211 --- /dev/null +++ b/README.zh_TW.md @@ -0,0 +1,194 @@ +
+ +MBrain Logo + +# MBrain + +**讓 AI Agent 調用你的 Android 手機能力。** + +設備資訊 · 應用管理 · 檔案操作 · Root / Shizuku · MCP 服務聚合 + +

+ Android 9.0 及以上 + HTTP MCP + 最新版本 +

+ +[简体中文](README.zh_CN.md) | **繁體中文** | [English](README.md) | [Français](README.fr.md) | [日本語](README.ja.md) + +[快速上手](#快速上手) · [連接 Agent](#連接-agent) · [接入 MCP 服務](#接入-mcp-服務) · [常見問題](#常見問題) · [反饋問題](https://github.com/powercess/mbrain/issues) + +
+ +--- + +MBrain 是執行在 Android 上的 Model Context Protocol(MCP)閘道。它把手機自身的能力和你接入的 MCP 服務匯集到一個入口,讓支持 MCP 的 AI 用戶端讀取設備狀態、管理應用、操作檔案或執行命令。你可以在手機上選擇開放哪些能力,并隨時停止服務。 + +## 界面預覽 + + + + + + + + + + + + +
首頁能力管理設定
首頁:工具與服務概覽,右下角懸浮啟停按鈕能力管理:按需啟用 Root、Shizuku 和應用管理設定:連接憑據、外觀和執行記錄
+ +應用實際執行截圖。可用工具數量取決于已啟用能力和接入服務;支持淺色、深色及跟隨系統。 + +## 可以做什么 + +| 能力 | 用途 | +| --- | --- | +| **讀取設備狀態** | 查看設備資訊、電量、儲存空間和網絡狀態 | +| **管理應用** | 查看應用列表與詳情、啟動應用;高權限通道還可安裝、卸載和停止應用 | +| **執行命令與操作檔案** | 通過 Root 或 Shizuku 執行命令,瀏覽、讀取、寫入、復制和移動檔案 | +| **接入其他 MCP 服務** | 添加手機本機的 HTTP MCP 服務,或由 MBrain 啟動和管理 stdio MCP 程序 | +| **統一管理與連接** | 一個 MCP 地址提供工具目錄,支持搜索工具、查看說明、復制連接資訊和查看近期執行記錄 | +| **內網穿透** | 內置 frpc,統一設定一臺伺服器,多條基礎 TCP 隧道轉發 MBrain 或手機其他服務 | + +- **按需啟用**:Root 和 Shizuku 各用一個開關,打開時自動檢查并申請權限。 +- **隨時停止**:首頁右下角一鍵啟停,也可從前臺通知停止閘道。 +- **服務自由添加**:填寫自己的服務名稱與設定,不綁定特定第三方應用。 + +## 快速上手 + +### 1. 安裝 MBrain + +需要 **Android 9.0 或更高版本**。 + +從 [GitHub Releases](https://github.com/powercess/mbrain/releases/latest) 下載最新版本的 `mbrain-v版本號-universal.apk`,在 Android 設備上打開并安裝。通用安裝包覆蓋 ARM64、ARM32、x86_64 和 x86,無需挑選架構。 + +發行頁面提供更新說明和 `SHA256SUMS.txt` 校驗檔案。自行構建及開發測試版說明見[開發指南](docs/development.md)。 + +### 2. 選擇需要開放的能力 + +打開底部的 **能力** 頁面: + +- 設備資訊不需要 Root。 +- 按需啟用應用管理。 +- 需要高權限操作時,進入 **Root** 或 **Shizuku**,打開啟用開關,并完成授權。 + +使用 Root 需要設備具備 Root 能力,并允許 **MBrain 本身**獲取權限。使用 Shizuku 則需先安裝并啟動 [Shizuku](https://shizuku.rikka.app/)。兩種通道可以分別啟用,不需要同時開啟。 + +### 3. 啟動閘道 + +回到 **首頁**,點擊右下角的啟動按鈕。顯示“執行中”后,打開 **連接地址與憑據**,獲取 MCP 地址和 Bearer Token。 + +## 連接 Agent + +在支持 **HTTP MCP 和 Bearer 認證**的用戶端中添加服務: + +| 設定項 | 填寫內容 | +| --- | --- | +| 名稱 | `MBrain`,也可自行命名 | +| MCP 地址 | `http://127.0.0.1:8765/mcp` | +| 認證方式 | Bearer Token | +| Token | 從 MBrain 的“連接地址與憑據”頁面復制 | + +如果用戶端通過請求頭設定認證,填寫: + +```http +Authorization: Bearer <從 MBrain 復制的 Token> +``` + +**同一臺手機上的用戶端**可以直接使用上述地址。 + +**電腦上的用戶端**需要先通過 ADB 連接手機,再轉發連接埠: + +```bash +adb forward tcp:8765 tcp:8765 +``` + +默認連接埠被占用時,閘道會自動使用空閑連接埠。請以“連接地址與憑據”中的實際地址及“使用說明”中的 ADB 命令為準。Token 加密保存在設備上,重啟后保持不變;可在憑據頁重置。 + +連接后可以先讓 Agent 執行一個簡單的只讀請求: + +> 查看這臺手機的電量和剩余儲存空間。 + +## 接入 MCP 服務 + +進入 **MCP → 添加服務**,選擇連接方式: + +| 方式 | 適用情況 | 需要填寫 | +| --- | --- | --- | +| **HTTP 服務** | 服務已經由手機上的其他應用或程序啟動 | 名稱、本機服務地址、可選 Token | +| **托管程序** | 希望由 MBrain 啟動并管理 stdio MCP 服務 | 名稱、程序、逐項啟動參數、執行身份 | + +保存設定后,在服務詳情中點擊 **連接服務**。成功連接后,該服務的工具會加入 MBrain 的工具目錄,Agent 可以通過同一個入口調用。 + +HTTP 服務目前只支持回環地址。托管程序所需的程序和執行環境需要事先在設備上準備好,MBrain 不內置 Node.js 或 Python。 + +## 遠程訪問 + +內置 **frpc** 用戶端,可通過自建 **frps** 伺服器轉發 MBrain 或手機上的其他服務。進入 **設定 → 內網穿透 → 設定伺服器**,填寫伺服器地址、連接埠和 Token,再添加 TCP 隧道。 + +當前僅支持基礎 TCP 轉發,所有隧道共用一臺伺服器。每條隧道獨立啟停與重試;MCP 隧道跟隨閘道,自定義服務隧道獨立執行。設定示例與執行規則見[內網穿透指南](docs/remote-access.md)。 + +## 權限與安全 + +- 閘道僅監聽手機回環地址。電腦通過 ADB 轉發連接,遠程訪問通過已設定的隧道連接。 +- 持有 Bearer Token 的用戶端可以調用**全部已啟用工具**,尚不支持為不同用戶端單獨分配權限。 +- Root / Shizuku 工具能夠執行實際修改,請只連接可信用戶端,不要分享 Token。 +- 在手機上選擇開放的能力,不再需要時隨時停止閘道。 + +## 常見問題 + +
+沒有 Root,能使用嗎? + +可以。設備資訊、普通應用查詢與啟動、本機 HTTP MCP 接入不依賴 Root。需要更高權限時,可以使用 Shizuku;實際操作范圍取決于它的啟動方式。 + +
+ +
+為什么用戶端連接不上? + +先確認首頁顯示“執行中”,并使用憑據頁中的 Token。電腦連接時還需確認實際連接埠的 ADB 轉發成功。閘道僅監聽手機回環地址;遠程訪問通過已設定的 TCP 隧道連接。 + +
+ +
+為什么找不到某個工具? + +工具數量隨能力開關、權限狀態和外部服務連接情況變化。先在能力頁檢查開關,再到 MCP 頁檢查服務狀態,最后在用戶端重新獲取工具列表。 + +
+ +
+停止服務后會發生什么? + +閘道停止接收請求,斷開外部 MCP 連接,并清理直接托管的子程序。應用不會在開機后自動啟動閘道;執行記錄目前僅保留在記憶體中。 + +
+ +## 反饋與參與 + +遇到問題或有功能建議,歡迎通過 [Issue 模板](https://github.com/powercess/mbrain/issues/new/choose)反饋。描述問題時請附上版本和復現步驟;截圖或日志中請隱去 Token 與私人資訊。 + +歡迎提交問題報告、改進文檔或貢獻代碼。請閱讀[貢獻指南](CONTRIBUTING.md)(英文),了解本地環境、構建執行、驗證及拉取請求流程。基于最新 `dev` 創建獨立分支,并將拉取請求提交到 `dev`。詳細設備測試步驟見[開發指南](docs/development.md)。 + +## 致謝 + +- [droid-mcp](https://github.com/stixez/droid-mcp):MBrain 使用的 Android MCP 基座,保留其 [Apache-2.0 許可證](vendor/droid-mcp/LICENSE)和[來源記錄](vendor/droid-mcp/UPSTREAM.md)。 +- [Shizuku](https://github.com/RikkaApps/Shizuku) 與 [libsu](https://github.com/topjohnwu/libsu):Android 高權限能力接入。 +- [RikkaHub](https://github.com/rikkahub/rikkahub):設定列表與交互設計參考。 + +## Star History + +如果 MBrain 對你有幫助,歡迎點一個 Star。 + + + + + MBrain 的 GitHub Star 增長趨勢 + + +Star 趨勢由 Star History 提供。 + +