android-adb-mcp 0.1.0__tar.gz

android_adb_mcp-0.1.0/.claude/CLAUDE.md

@@ -0,0 +1,105 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+An MCP server exposing Android Debug Bridge (ADB) capabilities as typed, documented
+tools (stdio transport). Full design docs live in-repo — read them before making
+non-trivial changes:
+
+- `../docs/ARCHITECTURE.md` — current-state description: component diagram, boot
+  sequence, core concepts (Backend/Service/Tool/Registry/Policy/Envelope), module
+  layering, repo layout, testing layers, CI/CD. **Read this first.**
+- `../docs/ADR.md` — decision log (17 ADRs). Explains *why* things are shaped this way,
+  including several non-obvious findings (fastmcp docstring-parsing quirks,
+  `docstring_parser` crashing on prose `Raises:` sections, `adb connect`'s exit code
+  being useless, etc.) that are easy to accidentally re-break.
+
+Both are living docs updated in place, not changelogs — treat them as authoritative
+over any summary here.
+
+## Commands
+
+```bash
+uv sync                        # install deps (dev group for testing)
+uv run adb-mcp-server           # run the server (stdio)
+
+uv run pytest                  # meta (Layer 0) + unit (Layer 1) + e2e (Layer 3) tests
+uv run pytest tests/unit/user   # run one module's tests
+uv run pytest -k test_name      # run a single test by name
+
+uv run mypy src                # strict type checking — must pass, no bare Any
+uv run ruff check .            # lint
+uv run mkdocs build --strict   # docs site (fails on broken nav/links)
+```
+
+CI (`../.github/workflows/ci.yml`) runs `ruff check` → `mypy --strict` → `pytest` on
+every push/PR to `main`, plus a strict `mkdocs build` (and `gh-deploy` on merge to
+`main`).
+
+Useful env vars (see `server.py` header and ADR-010):
+
+- `ADB_MCP_BACKEND=fake` — use the deterministic `FakeBackend` instead of a real `adb`
+- `ADB_MCP_ADB_PATH` — explicit path to the `adb` binary
+- `ADB_MCP_TIMEOUT_S` — per-command timeout (default 10s)
+- `ADB_MCP_ALLOW_DESTRUCTIVE=1` — flip default policy posture to also allow
+  `destructive`-category tools
+- `ADB_MCP_LOCAL_ROOT` — host directory `stop_log_session`'s local path must resolve
+  under; no default, that tool refuses to run until this is set
+
+## Architecture (essentials — see `../docs/ARCHITECTURE.md` for the full picture)
+
+- **Layering per module**: `tools.py` (thin, typed, module-level async function,
+  `@category("read"|"write"|"destructive")`) → `service.py` (domain logic: command
+  construction, output parsing, domain exceptions) → `AdbBackend` Protocol
+  (mechanical execution only). Tool functions are never closures — they're
+  module-level so `mkdocstrings` can statically introspect them (ADR-014).
+- **Backend seam**: `AdbBackend` is a `typing.Protocol`. `SubprocessBackend` (real,
+  via `asyncio.create_subprocess_exec`) and `FakeBackend` (deterministic, in-memory,
+  test-only) are the two implementations. Nothing above this line knows which one
+  it's talking to.
+- **Modules are plugins**: discovered via `entry_points` (group `adb_mcp.modules`),
+  declared in `../pyproject.toml`. Built-in modules (`diagnostics`, `device_info`,
+  `connection`, `user`, `logger`) use the exact same mechanism a third-party package
+  would — no special-cased "core module" path.
+- **Registry** (`registry.py`) wires it all together at import time: discovers
+  manifests, asks `PolicyEngine` whether each tool is allowed *before* registering it
+  with `FastMCP` (a denied tool is never exposed to the client at all), wraps allowed
+  tools with the response envelope.
+- **Response envelope**: every tool returns `ToolResponse[T]`
+  (`status`/`message`/`data`/`error`) — always `isError: false` at the MCP level; a
+  domain failure is `status: "error"` in the payload, not a protocol-level error.
+  Module/service code raises typed `AdbError` subclasses; only the registry wrapper
+  builds the envelope.
+- **Policy**: category default posture (`destructive` denied unless
+  `ADB_MCP_ALLOW_DESTRUCTIVE=1`) plus explicit allow/deny lists by tool name,
+  evaluated once at registration time. `local_root` (host filesystem writes) is a
+  separate *call-time* check inside the service, not the policy engine, since it
+  depends on the actual argument value.
+- **No generic shell tool** (ADR-009, deliberate): every operation is a specific,
+  named, parameterized tool. Don't add an `adb_shell(serial, command: str)`-shaped
+  tool.
+
+## Adding a new tool/module
+
+Follow `../docs/ARCHITECTURE.md` §6 and ADR-014 exactly: module-level function in
+`tools.py` (never a closure), service method in `service.py`, `AdbBackend` primitive
+in `backend/protocol.py` only if the operation needs genuinely new mechanical
+execution. Every tool must be fully typed (`mypy --strict`, no bare `Any`) and carry
+a Google-style docstring with Summary/Args/Returns/Example — enforced by
+`../tests/meta/test_tool_contract.py` against the live registry, not a fixed list. Use
+`Error handling:` instead of `Raises:` for prose-style failure descriptions
+(`docstring_parser`/`griffe` both mishandle a non-`ExceptionType: description`
+`Raises:` section — ADR-017). Add fixture `CommandResult`s to `FakeBackend` using
+real, captured `adb`/`pm`/`am`/`dumpsys` output, not hand-invented strings.
+
+## Testing layers
+
+Layer 0 (`../tests/meta`) — registry contract: every registered tool fully typed +
+documented. Layer 1 (`../tests/unit`, per module) — service class against
+`FakeBackend`, no MCP machinery. Layer 3 (`../tests/e2e`) — real `fastmcp.Client`
+against a `Registry`-wired server backed by `FakeBackend`, catching
+registration/schema/serialization bugs the lower layers can't see. Layers 2
+(dual-backend contract tests) and 4 (CI emulator integration) are not yet
+implemented — see `../docs/ARCHITECTURE.md` §9.

android_adb_mcp-0.1.0/.claude/agents/architecture-reviewer.md

@@ -0,0 +1,60 @@
+---
+name: architecture-reviewer
+description: Read-only architecture reviewer for ADB MCP Server module work. Use after implementing or changing a module, or before integrating parallel-agent changes, to check layering, ownership boundaries, MCP API quality, shared-contract leakage, and consistency with ARCHITECTURE.md.
+tools: Read, Grep, Glob
+model: opus
+permissionMode: plan
+effort: high
+---
+
+You are the architecture reviewer for the ADB MCP Server repository.
+
+## Mission
+
+Review proposed or completed work against the repository's documented architecture. `ARCHITECTURE.md` is the authoritative architectural contract. You are advisory and read-only: identify problems and recommend decisions, but do not edit files.
+
+## Review priorities
+
+Review in this order:
+
+1. **Module ownership** — Is the behavior in the correct domain module?
+2. **Layering** — Are MCP tools thin delegates, domain decisions in the service, and mechanical ADB execution behind the backend abstraction?
+3. **Public API semantics** — Does the MCP surface expose user intent/domain concepts rather than mirroring `am`, `pm`, `cmd`, `dumpsys`, or shell syntax?
+4. **Shared-contract discipline** — Did module work unnecessarily change or depend on registry, backend, policy, response/error, server, or shared test infrastructure?
+5. **Typed results** — Are structured domain results used where appropriate instead of leaking raw command output?
+6. **Policy semantics** — Are operations categorized correctly as `read`, `write`, or `destructive`?
+7. **Error boundaries** — Are transport failures, domain failures, and legitimate negative states kept distinct according to project conventions?
+8. **Testing boundaries** — Are tests focused on module behavior without coupling unnecessarily to FastMCP or production ADB execution?
+9. **Parallel integration risk** — Would this change conflict with another independently developed module or force cross-module coordination?
+10. **Scope control** — Are there unrelated refactors or architecture changes hidden inside module work?
+
+## Decision rule
+
+Do not reject a change merely because Android exposes the underlying capability through multiple command families. The project's domain API should remain stable even when its service internally combines `am`, `pm`, `cmd`, or `dumpsys` sources.
+
+When a module needs a shared capability, distinguish between:
+
+- a legitimate missing shared abstraction that should be decided centrally, and
+- a module implementation detail that should remain inside the module service.
+
+Do not design or implement the shared change yourself. State the architectural decision the parent needs to make and explain the tradeoff.
+
+## Severity
+
+Classify findings as:
+
+- **BLOCKER** — violates a core architectural boundary, creates unsafe cross-module coupling, or requires a central contract decision before integration
+- **IMPORTANT** — should be corrected before merge but does not invalidate the overall design
+- **MINOR** — consistency, naming, documentation, or maintainability improvement
+
+Do not manufacture findings. If the implementation fits the architecture, say so.
+
+## Return to parent
+
+Return:
+
+- overall verdict: `APPROVE`, `APPROVE WITH CHANGES`, or `BLOCK`
+- findings grouped by severity
+- the exact architectural boundary involved
+- concrete recommended direction without editing code
+- any central/shared decision the parent must make before integration

android_adb_mcp-0.1.0/.claude/agents/module-implementer.md

@@ -0,0 +1,85 @@
+---
+name: module-implementer
+description: Implements or extends one explicitly assigned adb_mcp domain module and its module-specific tests. Use for parallel work on independent modules such as users, logging, diagnostics, connection, or device_info. Do not use for shared architecture or cross-cutting infrastructure changes.
+tools: Read, Write, Edit, Grep, Glob, Bash
+model: sonnet
+permissionMode: acceptEdits
+effort: high
+---
+
+You are a module implementation engineer for the ADB MCP Server repository.
+
+## Mission
+
+Implement or extend exactly one domain module that the parent assigns to you. Treat the repository's `ARCHITECTURE.md` as the authoritative architectural contract. Inspect existing modules before making changes and follow their established patterns unless the parent explicitly instructs otherwise.
+
+You own module implementation, not project architecture.
+
+## Required boundaries
+
+You may change only:
+
+- `src/adb_mcp/modules/<assigned-module>/**`
+- module-specific unit tests for the assigned module
+- module-specific protocol/e2e tests when they can be added without changing shared fixtures or infrastructure
+
+Do not modify shared or cross-cutting project files, including:
+
+- `src/adb_mcp/backend/**`
+- `src/adb_mcp/registry.py`
+- `src/adb_mcp/server.py`
+- `src/adb_mcp/policy.py`
+- `src/adb_mcp/errors.py`
+- `src/adb_mcp/responses.py`
+- shared test fixtures or test infrastructure
+- `pyproject.toml`, CI configuration, or repository-wide documentation
+
+If the assigned work genuinely requires a shared-contract change, do not make that change. Finish everything that can be completed within the module boundary and report the required shared change to the parent as a blocker or architecture request.
+
+## Architectural rules
+
+Preserve these boundaries:
+
+1. MCP tools are thin, typed, documented module-level functions.
+2. Domain behavior, ADB command construction, parsing, and domain-specific decisions belong in the module service.
+3. Modules access ADB only through the existing backend abstraction; never invoke subprocesses directly.
+4. Public MCP operations represent user intent/domain concepts, not raw Android command ownership such as `am`, `pm`, `cmd`, or `dumpsys`.
+5. Use the project's existing response/error conventions rather than inventing module-specific envelopes.
+6. Respect the existing `read`, `write`, and `destructive` category semantics.
+7. Prefer typed structured results over returning raw shell output unless raw output is explicitly part of the requested API.
+8. Follow existing module naming, manifest, service-factory, typing, documentation, and testing conventions.
+
+## Parallel-work discipline
+
+Assume other agents may be editing other modules at the same time.
+
+- Do not reformat or clean up unrelated files.
+- Do not rename shared symbols.
+- Do not opportunistically refactor neighboring modules.
+- Do not modify another agent's module.
+- Keep edits narrowly scoped to the assigned module.
+
+If the parent did not explicitly identify a module and concrete task, report that the assignment is incomplete rather than choosing work yourself.
+
+## Validation
+
+Run the narrowest relevant checks first, then broader repository checks when practical. Do not change shared configuration merely to make tests pass.
+
+Before finishing, verify:
+
+- the module follows the repository layering
+- public tools are fully typed and documented according to existing project conventions
+- parsing and error behavior have module-level tests
+- no unrelated/shared files were changed
+
+## Return to parent
+
+Return a concise implementation report containing:
+
+- what was implemented
+- files changed
+- tests/checks run and their results
+- any assumptions
+- any shared-contract change or architecture decision needed from the parent
+
+Do not silently solve architecture questions yourself.

android_adb_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,61 @@
+name: CI
+
+"on":
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Lint (ruff)
+        run: uv run ruff check .
+
+      - name: Type check (mypy --strict)
+        run: uv run mypy src
+
+      - name: Test (pytest — meta + unit + e2e)
+        run: uv run pytest
+
+  docs:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --group docs
+
+      - name: Build docs (strict)
+        run: uv run mkdocs build --strict
+
+      - name: Deploy to GitHub Pages
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          uv run mkdocs gh-deploy --force

android_adb_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,27 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

android_adb_mcp-0.1.0/.gitignore

@@ -0,0 +1,65 @@
+# --- Python ---
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# --- Virtual environments ---
+.venv/
+venv/
+env/
+ENV/
+
+# --- Testing / type-checking / linting ---
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.tox/
+.nox/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+*.cover
+
+# --- mkdocs build output (ADR-013) ---
+site/
+
+# --- Local runtime config (never commit real local_root/policy paths — ADR-010) ---
+adb-mcp.toml
+.env
+.env.*
+!.env.example
+
+# --- JetBrains / PyCharm ---
+.idea/
+.mcp.json
+
+# --- VS Code ---
+.vscode/
+
+# --- OS cruft ---
+.DS_Store
+Thumbs.db
+
+# --- Editor swap files ---
+*.swp
+*.swo
+*~

android_adb_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 M. Allaudin
+
+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.

android_adb_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.5
+Name: android-adb-mcp
+Version: 0.1.0
+Summary: MCP server exposing Android Debug Bridge (ADB) capabilities as tools and resources.
+Project-URL: Homepage, https://github.com/allaudin/adb-mcp-server
+Project-URL: Repository, https://github.com/allaudin/adb-mcp-server
+Project-URL: Documentation, https://allaudin.github.io/adb-mcp-server/
+Project-URL: Issues, https://github.com/allaudin/adb-mcp-server/issues
+Author-email: "M. Allaudin" <dev.allaudin@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: adb,android,android-debug-bridge,fastmcp,mcp,model-context-protocol
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.10
+Requires-Dist: fastmcp>=3.0
+Requires-Dist: pydantic>=2.0
+Description-Content-Type: text/markdown
+
+# adb-mcp-server
+
+<!-- mcp-name: io.github.allaudin/adb-mcp-server -->
+
+[![CI](https://github.com/allaudin/adb-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/allaudin/adb-mcp-server/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/android-adb-mcp.svg)](https://pypi.org/project/android-adb-mcp/)
+
+An MCP server exposing Android Debug Bridge (ADB) capabilities as typed, documented
+tools and resources.
+
+**Full documentation: <https://allaudin.github.io/adb-mcp-server/>** — architecture,
+decision log, per-tool reference, and client integration guides.
+
+## Install
+
+```bash
+uvx android-adb-mcp
+# or
+pip install android-adb-mcp
+```
+
+## Quickstart
+
+```bash
+uv sync
+uv run adb-mcp-server
+```
+
+Talks to the `adb` binary on `PATH` by default. For real-device setup, the fake
+backend, environment variables, the full tool list, and integrating with an MCP
+client (Claude Code, Claude Desktop, ...), see the
+[docs site](https://allaudin.github.io/adb-mcp-server/).
+
+## Testing
+
+```bash
+uv run pytest        # meta (Layer 0), unit (Layer 1), and e2e (Layer 3) tests
+uv run mypy src       # strict type checking
+uv run ruff check .   # lint
+uv run mkdocs build --strict   # docs site
+```
+
+## License
+
+[MIT](LICENSE)

android_adb_mcp-0.1.0/README.md

@@ -0,0 +1,45 @@
+# adb-mcp-server
+
+<!-- mcp-name: io.github.allaudin/adb-mcp-server -->
+
+[![CI](https://github.com/allaudin/adb-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/allaudin/adb-mcp-server/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/android-adb-mcp.svg)](https://pypi.org/project/android-adb-mcp/)
+
+An MCP server exposing Android Debug Bridge (ADB) capabilities as typed, documented
+tools and resources.
+
+**Full documentation: <https://allaudin.github.io/adb-mcp-server/>** — architecture,
+decision log, per-tool reference, and client integration guides.
+
+## Install
+
+```bash
+uvx android-adb-mcp
+# or
+pip install android-adb-mcp
+```
+
+## Quickstart
+
+```bash
+uv sync
+uv run adb-mcp-server
+```
+
+Talks to the `adb` binary on `PATH` by default. For real-device setup, the fake
+backend, environment variables, the full tool list, and integrating with an MCP
+client (Claude Code, Claude Desktop, ...), see the
+[docs site](https://allaudin.github.io/adb-mcp-server/).
+
+## Testing
+
+```bash
+uv run pytest        # meta (Layer 0), unit (Layer 1), and e2e (Layer 3) tests
+uv run mypy src       # strict type checking
+uv run ruff check .   # lint
+uv run mkdocs build --strict   # docs site
+```
+
+## License
+
+[MIT](LICENSE)