mobile-re-mcp 1.2.0__tar.gz

mobile_re_mcp-1.2.0/.gitignore

@@ -0,0 +1,48 @@
+# Build output
+dist/
+
+# Dependencies
+node_modules/
+
+# APK / IPA — never commit binary test files
+*.apk
+*.ipa
+*.aab
+
+# apktool / decompiled output folders
+*_decompiled/
+smali*/
+baksmali*/
+
+# Environment & secrets
+.env
+.env.*
+*.keystore
+*.jks
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Logs
+*.log
+npm-debug.log*
+
+# Claude memory (local only)
+.claude/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+.pytest_cache/
+.ruff_cache/
+python/dist/
+python/build/

mobile_re_mcp-1.2.0/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2025 Serhatcck
+Copyright (c) 2026 FlyPhantomFly
+Copyright (c) 2026 mobile-security-mcp contributors (Python server)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mobile_re_mcp-1.2.0/NOTICE.md

@@ -0,0 +1,4 @@
+# Notice
+The Python server in this package is derived from `mobile-security-mcp` 0.1.4 on PyPI (MIT, by "mobile-security-mcp contributors"). Its public repository could not be found, so the source used here is the published 0.1.4 package. The original declares the MIT license but ships no license file or named copyright holder. The MIT notice is kept in `LICENSE` and the original contributors are credited there.
+Changes from 0.1.4: renamed to `mobile-re-mcp`, argument checks on every tool call, radare2 and ripgrep injection fixes, loopback-only SSE with a token for anything else, loopback-only mitmproxy, private scratch folders instead of `/tmp`, SHA-256 pinned downloads, notes stored in the user data folder, `install_tool` off by default, and the SDK pinned below 2.0.
+This project is not affiliated with or endorsed by the original authors.

mobile_re_mcp-1.2.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.5
+Name: mobile-re-mcp
+Version: 1.2.0
+Summary: Android dynamic analysis MCP server: adb, Frida, mitmproxy, apktool, jadx
+Project-URL: Homepage, https://github.com/FlyPhantomFly/mobile-re-mcp
+Project-URL: Repository, https://github.com/FlyPhantomFly/mobile-re-mcp
+Project-URL: Issues, https://github.com/FlyPhantomFly/mobile-re-mcp/issues
+Project-URL: Changelog, https://github.com/FlyPhantomFly/mobile-re-mcp/blob/master/CHANGELOG.md
+Author: FlyPhantomFly, mobile-security-mcp contributors
+License-Expression: MIT
+License-File: LICENSE
+License-File: NOTICE.md
+Keywords: adb,android,apktool,frida,mcp,mitmproxy,mobile-security,model-context-protocol,pentest,reverse-engineering
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Requires-Python: >=3.11
+Requires-Dist: mcp<2,>=1.30
+Provides-Extra: all
+Requires-Dist: androguard>=3.4.0a1; extra == 'all'
+Requires-Dist: apkid>=2.1.0; extra == 'all'
+Requires-Dist: apkleaks>=2.6.0; extra == 'all'
+Requires-Dist: frida-tools>=12.0.0; extra == 'all'
+Requires-Dist: frida>=16.0.0; extra == 'all'
+Requires-Dist: mitmproxy>=10.0.0; extra == 'all'
+Requires-Dist: quark-engine>=23.0.0; extra == 'all'
+Provides-Extra: analysis
+Requires-Dist: quark-engine>=23.0.0; extra == 'analysis'
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: frida
+Requires-Dist: frida-tools>=12.0.0; extra == 'frida'
+Requires-Dist: frida>=16.0.0; extra == 'frida'
+Provides-Extra: network
+Requires-Dist: mitmproxy>=10.0.0; extra == 'network'
+Provides-Extra: static
+Requires-Dist: androguard>=3.4.0a1; extra == 'static'
+Requires-Dist: apkid>=2.1.0; extra == 'static'
+Requires-Dist: apkleaks>=2.6.0; extra == 'static'
+Description-Content-Type: text/markdown
+
+# mobile-re-mcp (Python)
+The dynamic half of [mobile-re-mcp](https://github.com/FlyPhantomFly/mobile-re-mcp): an MCP server that lets an AI agent drive adb, Frida, mitmproxy, apktool and jadx against a test device. The npm package of the same name does read-only static analysis of APK and IPA files. Use that one first and this one when you need the app running.
+## Install
+```bash
+pip install "mobile-re-mcp[all]"
+```
+The base install is only the MCP server. Extras add the heavy tools: `frida`, `static` (androguard, apkid, apkleaks), `network` (mitmproxy), `analysis` (quark-engine). Missing tools are reported by `check_tools` instead of crashing.
+The command is `mobile-re-mcp-py` so it does not clash with the npm command `mobile-re-mcp`.
+```bash
+claude mcp add mobile-re-py -- mobile-re-mcp-py
+```
+Other clients: command `mobile-re-mcp-py`, no arguments (stdio).
+## Tools
+About 55 tools in six groups: static (apktool, jadx, apkid, apkleaks, androguard), Frida (spawn, attach, inject, memory dump), device (adb, scrcpy), network (mitmproxy, HAR export), patching (smali edits, frida-gadget injection, signing) and native/Flutter/Unity (strings, exports, disassembly, Blutter, Il2CppDumper). `check_tools` shows what is installed.
+## Safe use
+This server can run commands on your phone and your computer, so treat its tools as dangerous.
+- Use stdio. `--transport sse` listens on 127.0.0.1 only. Any other `--host` needs `MOBILE_RE_MCP_TOKEN` and the client must send it as a bearer token.
+- Set `MOBILE_RE_MCP_ALLOWED_DIRS` (`:`-separated) to keep file arguments inside your workspace. Paths into `~/.ssh`, `~/.config/gh`, shell rc files and similar are always refused.
+- Turn tools off with `MOBILE_RE_MCP_DISABLE_TOOLS=adb_shell,adb_push,adb_pull`. Better still, set those tools to ask first in your client.
+- `install_tool` is off unless `MOBILE_RE_MCP_ALLOW_INSTALL=1`. `mobile-re-mcp-py --setup` still downloads the pinned tools into `~/tools` for you.
+- mitmproxy listens on 127.0.0.1 only. Run `adb reverse tcp:8080 tcp:8080` and point the device proxy at 127.0.0.1:8080.
+- Analyze untrusted apps in a VM. Their strings and symbol names end up in the agent's context.
+## Files
+Target notes, captures and scratch files live in `~/.local/share/mobile-re-mcp` (`MOBILE_RE_MCP_HOME` to change). Your own settings go in `~/.config/mobile-re-mcp/config.toml`. Drop your own Frida scripts in `~/.local/share/mobile-re-mcp/frida_scripts`; no scripts ship with the package.
+## Credits
+Derived from `mobile-security-mcp` 0.1.4 (MIT). See NOTICE.md. Licensed MIT.

mobile_re_mcp-1.2.0/README.md

@@ -0,0 +1,26 @@
+# mobile-re-mcp (Python)
+The dynamic half of [mobile-re-mcp](https://github.com/FlyPhantomFly/mobile-re-mcp): an MCP server that lets an AI agent drive adb, Frida, mitmproxy, apktool and jadx against a test device. The npm package of the same name does read-only static analysis of APK and IPA files. Use that one first and this one when you need the app running.
+## Install
+```bash
+pip install "mobile-re-mcp[all]"
+```
+The base install is only the MCP server. Extras add the heavy tools: `frida`, `static` (androguard, apkid, apkleaks), `network` (mitmproxy), `analysis` (quark-engine). Missing tools are reported by `check_tools` instead of crashing.
+The command is `mobile-re-mcp-py` so it does not clash with the npm command `mobile-re-mcp`.
+```bash
+claude mcp add mobile-re-py -- mobile-re-mcp-py
+```
+Other clients: command `mobile-re-mcp-py`, no arguments (stdio).
+## Tools
+About 55 tools in six groups: static (apktool, jadx, apkid, apkleaks, androguard), Frida (spawn, attach, inject, memory dump), device (adb, scrcpy), network (mitmproxy, HAR export), patching (smali edits, frida-gadget injection, signing) and native/Flutter/Unity (strings, exports, disassembly, Blutter, Il2CppDumper). `check_tools` shows what is installed.
+## Safe use
+This server can run commands on your phone and your computer, so treat its tools as dangerous.
+- Use stdio. `--transport sse` listens on 127.0.0.1 only. Any other `--host` needs `MOBILE_RE_MCP_TOKEN` and the client must send it as a bearer token.
+- Set `MOBILE_RE_MCP_ALLOWED_DIRS` (`:`-separated) to keep file arguments inside your workspace. Paths into `~/.ssh`, `~/.config/gh`, shell rc files and similar are always refused.
+- Turn tools off with `MOBILE_RE_MCP_DISABLE_TOOLS=adb_shell,adb_push,adb_pull`. Better still, set those tools to ask first in your client.
+- `install_tool` is off unless `MOBILE_RE_MCP_ALLOW_INSTALL=1`. `mobile-re-mcp-py --setup` still downloads the pinned tools into `~/tools` for you.
+- mitmproxy listens on 127.0.0.1 only. Run `adb reverse tcp:8080 tcp:8080` and point the device proxy at 127.0.0.1:8080.
+- Analyze untrusted apps in a VM. Their strings and symbol names end up in the agent's context.
+## Files
+Target notes, captures and scratch files live in `~/.local/share/mobile-re-mcp` (`MOBILE_RE_MCP_HOME` to change). Your own settings go in `~/.config/mobile-re-mcp/config.toml`. Drop your own Frida scripts in `~/.local/share/mobile-re-mcp/frida_scripts`; no scripts ship with the package.
+## Credits
+Derived from `mobile-security-mcp` 0.1.4 (MIT). See NOTICE.md. Licensed MIT.

mobile_re_mcp-1.2.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mobile-re-mcp"
+version = "1.2.0"
+description = "Android dynamic analysis MCP server: adb, Frida, mitmproxy, apktool, jadx"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE", "NOTICE.md"]
+authors = [{ name = "FlyPhantomFly" }, { name = "mobile-security-mcp contributors" }]
+keywords = ["mcp", "model-context-protocol", "android", "frida", "mobile-security", "reverse-engineering", "pentest", "adb", "apktool", "mitmproxy"]
+classifiers = [
+  "Intended Audience :: Developers",
+  "Intended Audience :: Information Technology",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Security",
+]
+dependencies = ["mcp>=1.30,<2"]
+
+[project.optional-dependencies]
+frida = ["frida>=16.0.0", "frida-tools>=12.0.0"]
+static = ["androguard>=3.4.0a1", "apkid>=2.1.0", "apkleaks>=2.6.0"]
+network = ["mitmproxy>=10.0.0"]
+analysis = ["quark-engine>=23.0.0"]
+all = ["mobile-re-mcp[frida,static,network,analysis]"]
+dev = ["pytest>=8", "ruff>=0.6"]
+
+[project.scripts]
+mobile-re-mcp-py = "mobile_re_mcp.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/FlyPhantomFly/mobile-re-mcp"
+Repository = "https://github.com/FlyPhantomFly/mobile-re-mcp"
+Issues = "https://github.com/FlyPhantomFly/mobile-re-mcp/issues"
+Changelog = "https://github.com/FlyPhantomFly/mobile-re-mcp/blob/master/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mobile_re_mcp"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "LICENSE", "NOTICE.md", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["F", "E9", "B", "S102", "S307", "S602", "S605"]

mobile_re_mcp-1.2.0/src/mobile_re_mcp/__init__.py

@@ -0,0 +1,11 @@
+"""mobile-re-mcp (Python): dynamic Android analysis MCP server.
+
+Derived from mobile-security-mcp 0.1.4 (MIT). See NOTICE.md in the repository.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("mobile-re-mcp")
+except PackageNotFoundError:  # running from a source checkout
+    __version__ = "0+local"

mobile_re_mcp-1.2.0/src/mobile_re_mcp/__main__.py

@@ -0,0 +1,90 @@
+"""
+Entry point for the mobile-re-mcp MCP server.
+
+Usage:
+    python -m mobile_re_mcp           # stdio transport (default)
+    python -m mobile_re_mcp --transport sse --port 8765  # SSE, loopback only
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import logging
+import sys
+
+logger = logging.getLogger(__name__)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="mobile-re-mcp-py",
+        description="Android dynamic analysis MCP server (Python half of mobile-re-mcp)",
+    )
+    p.add_argument(
+        "--transport",
+        choices=["stdio", "sse"],
+        default="stdio",
+        help="Transport to use (default: stdio)",
+    )
+    p.add_argument(
+        "--host",
+        default="127.0.0.1",
+        help="Address for SSE transport (default: 127.0.0.1). Anything else needs MOBILE_RE_MCP_TOKEN.",
+    )
+    p.add_argument(
+        "--port",
+        type=int,
+        default=8765,
+        help="Port for SSE transport (default: 8765)",
+    )
+    p.add_argument(
+        "--log-level",
+        default="WARNING",
+        choices=["DEBUG", "INFO", "WARNING", "ERROR"],
+    )
+    p.add_argument(
+        "--setup",
+        action="store_true",
+        help="Automatically download and install all missing RE tools into ~/tools",
+    )
+    return p
+
+
+def main() -> None:
+    """Main entry point — starts the MCP server."""
+    parser = _build_parser()
+    args = parser.parse_args()
+
+    logging.basicConfig(
+        level=getattr(logging, args.log_level),
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+        stream=sys.stderr,
+    )
+
+    if args.setup:
+        print("[*] Starting zero-touch automated setup...")
+        from mobile_re_mcp.setup.install_tool import install_all_missing_tools
+        install_all_missing_tools()
+        print("[*] Setup complete! You can now start the MCP server.")
+        sys.exit(0)
+
+    from mobile_re_mcp.paths import ensure_tools_on_path
+
+    ensure_tools_on_path()
+
+    # Import here so startup errors surface cleanly
+    from mobile_re_mcp.server import create_server
+
+    server = create_server()
+
+    if args.transport == "stdio":
+        logger.info("Starting mobile-re-mcp over stdio")
+        asyncio.run(server.run_stdio())
+    else:
+        logger.info("Starting mobile-re-mcp SSE on %s:%d", args.host, args.port)
+        asyncio.run(server.run_sse(host=args.host, port=args.port))
+
+
+if __name__ == "__main__":
+    main()

mobile_re_mcp-1.2.0/src/mobile_re_mcp/config.py

@@ -0,0 +1,38 @@
+"""Settings from the packaged defaults, overridden by the user's config file."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from mobile_re_mcp.paths import tools_dir, user_config_path
+
+_DEFAULTS = Path(__file__).parent / "config.toml"
+
+
+def _read(path: Path) -> dict:
+    try:
+        import tomllib
+    except ImportError:  # Python < 3.11 is not supported, kept for safety
+        return {}
+    try:
+        with open(path, "rb") as fh:
+            return tomllib.load(fh)
+    except (FileNotFoundError, PermissionError, ValueError):
+        return {}
+
+
+def load_config() -> dict[str, dict[str, Any]]:
+    merged = _read(_DEFAULTS)
+    for section, values in _read(user_config_path()).items():
+        if isinstance(values, dict):
+            merged.setdefault(section, {}).update(values)
+    return merged
+
+
+def signer_jar() -> Path:
+    """Absolute path to uber-apk-signer. Never resolved against the working directory."""
+    configured = str(load_config().get("signing", {}).get("jar_path", "") or "")
+    if configured and Path(configured).is_absolute():
+        return Path(configured)
+    return tools_dir() / "signing" / "uber-apk-signer.jar"

mobile_re_mcp-1.2.0/src/mobile_re_mcp/config.toml

@@ -0,0 +1,9 @@
+# Defaults only. Put your own settings in ~/.config/mobile-re-mcp/config.toml (or $MOBILE_RE_MCP_CONFIG).
+[signing]
+# Absolute path to uber-apk-signer.jar. Empty uses ~/tools/signing/uber-apk-signer.jar
+jar_path = ""
+# Empty keystore uses uber-apk-signer's built-in debug keystore. Passwords given here show up in the process list.
+keystore_path = ""
+keystore_password = ""
+key_alias = ""
+key_password = ""

mobile_re_mcp-1.2.0/src/mobile_re_mcp/frida_scripts/__init__.py

@@ -0,0 +1 @@
+"""Frida script library package — categorized JS scripts for Android RE."""

mobile_re_mcp-1.2.0/src/mobile_re_mcp/frida_scripts/index.py

@@ -0,0 +1,127 @@
+"""
+frida_scripts/index.py — Script library index and loader.
+
+Provides the script catalogue used by frida_list_scripts() and
+frida_get_script() MCP tools. All scripts live as .js files in this
+same package directory.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+_SCRIPTS_DIR = Path(__file__).parent
+
+
+def _script_dirs() -> list[Path]:
+    """Folders searched for the catalogue's .js files: the user's own first, then the package."""
+    from mobile_re_mcp.paths import data_dir
+
+    return [data_dir() / "frida_scripts", _SCRIPTS_DIR]
+
+
+def _find(file_name: str) -> Path | None:
+    for d in _script_dirs():
+        p = d / file_name
+        if p.is_file():
+            return p
+    return None
+
+# ---------------------------------------------------------------------------
+# Script catalogue
+# ---------------------------------------------------------------------------
+
+SCRIPT_CATALOGUE: list[dict] = [
+    {
+        "name": "ssl_pinning_universal",
+        "file": "ssl_pinning_universal.js",
+        "category": "ssl_pinning",
+        "description": "Universal SSL pinning bypass — OkHttp3/4, TrustKit, Conscrypt, native BoringSSL",
+        "tags": ["ssl", "pinning", "okhttp", "trustkit", "conscrypt", "boring"],
+        "usage": "frida -U -f <package> -l ssl_pinning_universal.js --no-pause",
+    },
+    {
+        "name": "root_detection_bypass",
+        "file": "root_detection_bypass.js",
+        "category": "root_detection",
+        "description": "Comprehensive root detection bypass — File.exists, Runtime.exec, PackageManager, Build props, RootBeer, native libc stat/access",
+        "tags": ["root", "magisk", "supersu", "rootbeer", "libc"],
+        "usage": "frida -U -f <package> -l root_detection_bypass.js --no-pause",
+    },
+    {
+        "name": "frida_detection_bypass",
+        "file": "frida_detection_bypass.js",
+        "category": "frida_detection",
+        "description": "Multi-layer Frida self-detection bypass — /proc/maps, port 27042, dlopen, strstr, debug flag",
+        "tags": ["frida", "anti-detection", "port", "proc", "dlopen"],
+        "usage": "Inject early via frida_spawn; combine with hluda server for RASP-hardened apps",
+    },
+    {
+        "name": "crypto_monitor",
+        "file": "crypto_monitor.js",
+        "category": "crypto",
+        "description": "Monitor all javax.crypto operations — log key material, IV, plaintext, ciphertext, HMAC, hash",
+        "tags": ["crypto", "aes", "hmac", "sha", "key", "iv", "cipher"],
+        "usage": "frida -U -f <package> -l crypto_monitor.js --no-pause",
+    },
+    {
+        "name": "memory_scan",
+        "file": "memory_scan.js",
+        "category": "memory",
+        "description": "Scan all rw- process memory regions for a UTF-8 string or hex byte pattern",
+        "tags": ["memory", "scan", "bytes", "search", "heap"],
+        "usage": "Inject then send config: {type:'config', search_string:'my_secret'} or search_hex:'deadbeef'",
+    },
+    {
+        "name": "method_tracer",
+        "file": "method_tracer.js",
+        "category": "hooks",
+        "description": "Trace all methods (or a specific one) on a Java class — log args and return values",
+        "tags": ["trace", "hook", "java", "class", "method", "args"],
+        "usage": "Inject then send config: {type:'config', class_name:'com.example.Foo', method_name:''}",
+    },
+    {
+        "name": "storage_monitor",
+        "file": "storage_monitor.js",
+        "category": "storage",
+        "description": "Monitor SharedPreferences writes, SQLite queries, FileInputStream/OutputStream, KeyStore",
+        "tags": ["storage", "sharedprefs", "sqlite", "file", "keystore"],
+        "usage": "frida -U -f <package> -l storage_monitor.js --no-pause",
+    },
+    {
+        "name": "network_monitor",
+        "file": "network_monitor.js",
+        "category": "network",
+        "description": "Monitor OkHttp requests/responses, HttpURLConnection, WebView.loadUrl, DNS lookups",
+        "tags": ["network", "http", "okhttp", "webview", "dns", "request"],
+        "usage": "frida -U -f <package> -l network_monitor.js --no-pause",
+    },
+]
+
+_CATALOGUE_BY_NAME: dict[str, dict] = {s["name"]: s for s in SCRIPT_CATALOGUE}
+_CATALOGUE_BY_CATEGORY: dict[str, list[dict]] = {}
+for _s in SCRIPT_CATALOGUE:
+    _CATALOGUE_BY_CATEGORY.setdefault(_s["category"], []).append(_s)
+
+
+def list_scripts(category: str | None = None) -> list[dict]:
+    """Script metadata for scripts that exist on disk, optionally filtered by category."""
+    pool = _CATALOGUE_BY_CATEGORY.get(category.lower(), []) if category else SCRIPT_CATALOGUE
+    return [m for m in pool if _find(m["file"]) is not None]
+
+
+def get_categories() -> list[str]:
+    """Return all categories that have at least one available script."""
+    return sorted({m["category"] for m in list_scripts()})
+
+
+def get_script_content(name: str) -> str | None:
+    """Load and return the JS source for a named script, or None if not found."""
+    path = get_script_path(name)
+    return path.read_text(encoding="utf-8") if path else None
+
+
+def get_script_path(name: str) -> Path | None:
+    """Return the absolute path to a named script file."""
+    meta = _CATALOGUE_BY_NAME.get(name)
+    return _find(meta["file"]) if meta else None

mobile_re_mcp-1.2.0/src/mobile_re_mcp/guard.py

@@ -0,0 +1,132 @@
+"""Argument checks applied to every tool call before a handler runs.
+
+Environment:
+  MOBILE_RE_MCP_ALLOWED_DIRS   os.pathsep-separated folders that file arguments must stay inside
+  MOBILE_RE_MCP_DISABLE_TOOLS  comma-separated tool names to turn off
+  MOBILE_RE_MCP_ALLOW_INSTALL  set to 1 to let the install_tool MCP tool run
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+# Host-side file arguments, by tool argument name.
+PATH_KEYS = {
+    "apk_path", "bundle_path", "capture_path", "gadget_path", "local", "output_apk",
+    "output_dir", "output_path", "path", "record_file", "smali_dir", "so_path",
+}
+# Where each of those is written rather than read.
+WRITE_KEYS = {"local", "output_apk", "output_dir", "output_path", "record_file"}
+# Output files must keep one of these suffixes (tool -> key -> suffixes).
+OUTPUT_SUFFIXES = {
+    "mitm_export_har": {"output_path": {".har", ".json"}},
+    "scrcpy_screenshot": {"output_path": {".png"}},
+    "scrcpy_start": {"record_file": {".mp4", ".mkv"}},
+}
+
+_SYMBOL = re.compile(r"(0x[0-9a-fA-F]{1,16}|[A-Za-z0-9_.@]{1,200})")
+_PACKAGE = re.compile(r"[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*(:[A-Za-z0-9_.]{1,64})?")
+_SERIAL = re.compile(r"[A-Za-z0-9._:\-]{1,100}")
+_REMOTE_PATH = re.compile(r"/[A-Za-z0-9._/\-]{1,200}")
+_ABIS = {"arm64", "arm", "x86_64", "x86", "arm64-v8a", "armeabi-v7a"}
+
+_SENSITIVE_HOME = (
+    ".ssh", ".gnupg", ".aws", ".azure", ".kube", ".docker", ".netrc", ".npmrc", ".pypirc",
+    ".git-credentials", ".config/gh", ".config/opencode", ".config/git", ".claude", ".claude.json",
+    ".bashrc", ".bash_profile", ".bash_login", ".bash_logout", ".profile", ".zshrc", ".zshenv",
+    ".zprofile", ".zlogin", ".config/fish", ".local/share/keyrings",
+)
+
+
+class GuardError(ValueError):
+    """Raised when a tool call is refused."""
+
+
+def _csv(name: str) -> set[str]:
+    return {x.strip() for x in os.environ.get(name, "").split(",") if x.strip()}
+
+
+def disabled_tools() -> set[str]:
+    off = _csv("MOBILE_RE_MCP_DISABLE_TOOLS")
+    if os.environ.get("MOBILE_RE_MCP_ALLOW_INSTALL") != "1":
+        off.add("install_tool")
+    return off
+
+
+def allowed_dirs() -> list[Path]:
+    raw = os.environ.get("MOBILE_RE_MCP_ALLOWED_DIRS", "")
+    return [Path(p).expanduser().resolve() for p in raw.split(os.pathsep) if p.strip()]
+
+
+def _inside(path: Path, base: Path) -> bool:
+    return path == base or base in path.parents
+
+
+def check_path(value: Any, key: str, tool: str) -> None:
+    if not isinstance(value, str) or not value:
+        raise GuardError(f"'{key}' must be a non-empty string")
+    if "\x00" in value:
+        raise GuardError(f"'{key}' contains a NUL byte")
+    if value.startswith("-"):
+        raise GuardError(f"'{key}' must not start with '-'")
+    resolved = Path(value).expanduser().resolve()
+    home = Path.home().resolve()
+    for rel in _SENSITIVE_HOME:
+        if _inside(resolved, home / rel):
+            raise GuardError(f"'{key}' points into a protected location ({rel})")
+    if _inside(resolved, Path("/etc")) and key in WRITE_KEYS:
+        raise GuardError(f"'{key}' may not write into /etc")
+    dirs = allowed_dirs()
+    if dirs and not any(_inside(resolved, d) for d in dirs):
+        raise GuardError(f"'{key}' is outside MOBILE_RE_MCP_ALLOWED_DIRS")
+    suffixes = OUTPUT_SUFFIXES.get(tool, {}).get(key)
+    if suffixes and resolved.suffix.lower() not in suffixes:
+        raise GuardError(f"'{key}' must end with one of: {', '.join(sorted(suffixes))}")
+
+
+def validate(tool: str, args: Any) -> dict:
+    """Return the checked arguments or raise GuardError."""
+    if tool in disabled_tools():
+        raise GuardError(
+            "install_tool is off by default; set MOBILE_RE_MCP_ALLOW_INSTALL=1 to enable it"
+            if tool == "install_tool"
+            else f"tool '{tool}' is disabled by MOBILE_RE_MCP_DISABLE_TOOLS"
+        )
+    if args is None:
+        return {}
+    if not isinstance(args, dict):
+        raise GuardError("arguments must be an object")
+    for key in PATH_KEYS & args.keys():
+        check_path(args[key], key, tool)
+    _match(args, "serial", _SERIAL, "a device serial")
+    _match(args, "package", _PACKAGE, "an Android package name")
+    if tool == "native_disasm":
+        _match(args, "target", _SYMBOL, "a symbol name or 0x offset", required=True)
+    if tool == "frida_server_push":
+        _match(args, "remote_path", _REMOTE_PATH, "an absolute device path")
+        if "abi" in args and args["abi"] not in _ABIS:
+            raise GuardError("'abi' must be one of " + ", ".join(sorted(_ABIS)))
+    for key in ("port",):
+        if key in args:
+            try:
+                port = int(args[key])
+            except (TypeError, ValueError) as exc:
+                raise GuardError("'port' must be an integer") from exc
+            if not 1024 <= port <= 65535:
+                raise GuardError("'port' must be between 1024 and 65535")
+    return args
+
+
+def _match(args: dict, key: str, pattern: re.Pattern, what: str, required: bool = False) -> None:
+    if key not in args:
+        if required:
+            raise GuardError(f"'{key}' is required")
+        return
+    value = args[key]
+    if value in (None, "") and not required:
+        return
+    if not isinstance(value, str) or not pattern.fullmatch(value):
+        raise GuardError(f"'{key}' must be {what}")

mobile_re_mcp-1.2.0/src/mobile_re_mcp/handlers/__init__.py

@@ -0,0 +1 @@
+"""Handlers package — one module per capability domain."""