---
name: add-mobile-module
description: Add or modify an in-process hardware MCP module in the Edison-Watch/mobile Android client, and verify its logic without the Android SDK. Use when adding or editing a *Module under app/.../mcp/, wiring a new *Source, hitting a lint MissingPermission error, or when ./gradlew fails because there is no Android SDK in the sandbox.
---

# Add a mobile hardware MCP module

The mobile app exposes each phone capability as an in-process "MCP server": a
Kotlin module answering MCP JSON-RPC directly (no subprocess). This skill is the
contract + how to verify it in the SDK-less cloud sandbox.

## The module contract

Two files per module, plus a test.

1. **`FooModule.kt`** in `app/src/main/java/ai/sealgate/stdiod/mcp/`
   - A **`FooSource` interface** holding *all* `android.*` access (so module
     logic is pure JVM, testable with a fake source).
   - `class FooModule(private val source: FooSource) : BaseMcpModule()`
     (`BaseMcpModule` + `JsonRpc` live in `LocalMcpModule.kt`).
   - Override `val name` (the server name the backend addresses) and
     `toolDescriptors(): JsonElement` (the `tools/list` array). Dispatch tool
     calls in the body — copy `BatteryModule` (simplest) or `UsbModule`.

2. **`AndroidFoo.kt` / `AndroidFooSource.kt`** — the real `FooSource`
   implementation over the Android APIs. This file is **not** JVM-compilable and
   is excluded from scratch verification (below).

3. **`FooModuleTest.kt`** in `app/src/test/java/ai/sealgate/stdiod/mcp/` — drive
   the module with a fake `FooSource`; assert on the JSON it returns.

Then **register it** in `TunnelService.connect()`:
```kotlin
FooModule(AndroidFooSource(this)),
```
And add a bullet to `README.md`'s module list.

## Hard rules

- **Every precondition failure is in-band**, never a crash and never a JSON-RPC
  error: return `JsonRpc.textToolResult(id, text, isError = true)` (missing
  permission, device not found, adapter off, …). The gateway must always get a
  tool result.
- **Binary payloads travel as hex strings** in tool args/results (see
  `BluetoothModule`/`UsbModule`), not base64, not byte arrays.
- **lint `MissingPermission` is checked per call-site and does NOT follow a
  `try/catch (SecurityException)` up into callers.** A permission-requiring call
  (BLE GATT, `UsbManager`, etc.) must catch `SecurityException` in the *same
  function* that makes the call. If lint fails only on a helper, wrap the
  helper's body in its own try/catch returning an error reason. This is one of
  the few things only the real toolchain (CI) catches — JVM tests won't.
- Async Android callbacks bridge to the synchronous `handle()` with
  latches/timeouts (`CountDownLatch` for GATT) or reader threads +
  `BlockingQueue` (SPP, notifications). Hold live connections in a
  `ConcurrentHashMap` keyed by address/id.

## Verify without the Android SDK

The cloud sandbox has **no Android SDK** (`dl.google.com` is proxy-blocked), so
`./gradlew assembleDebug|lintDebug|testDebugUnitTest` all fail locally. CI is the
real gate. To sanity-check module + test logic *before* pushing, compile just
the pure-JVM slice in a throwaway Gradle project:

```
/tmp/scratch/
  build.gradle.kts        # kotlin("jvm") + kotlin("plugin.serialization")
  settings.gradle.kts
  src/main/kotlin/  <- LocalMcpModule.kt + FooModule.kt   (NOT AndroidFoo*.kt)
  src/test/kotlin/  <- FooModuleTest.kt + a hand-written FakeFooSource
```

- `build.gradle.kts`: `kotlin("jvm")` and `kotlin("plugin.serialization")` at the
  **same version as `kotlin` in `gradle/libs.versions.toml`**; deps
  `kotlinx-serialization-json` (1.7.x is fine) and `junit:junit:4.13.2`.
- Copy in **only** `LocalMcpModule.kt`, your `FooModule.kt`, and the test.
  Exclude every `Android*.kt` — those need the SDK.
- `gradle test`. Green here means the JSON/dispatch logic holds; it does **not**
  cover lint or Android wiring — push and let CI confirm those.

## After push

CI ("Build & unit test") runs `assembleDebug` + `testDebugUnitTest` +
`lintDebug`. Green there is the real pass. Then on a device:
`git pull && ./gradlew installDebug`. The new tools appear in MCP Tester once a
server row of `name` is registered and the tool list refreshed.