# Mobile FreeCode

**`mobile-freecode`** is an [MCP](https://modelcontextprotocol.io) server that lets
any MCP client (Claude Code, Claude Desktop, the FreeCode desktop app, …)
**discover and control an Android phone** running the **FreeCode Agent** app over
your local network.

> **Direction of control:** this server runs on your **desktop** and drives the
> **phone**. The phone is the device being controlled; the desktop is the
> controller. There is no reverse channel — the phone never drives the desktop.

The phone runs a lightweight WebSocket gateway (port `8765`); this server finds
it on the LAN, pairs with it once, and then routes tool calls to the phone's
native capabilities (accessibility tree, taps / swipes / text, screenshots, and
a live screen stream).

## Tools

| Tool | Purpose |
| --- | --- |
| `list_devices` | List discovered / paired phones on the network. |
| `get_device` | Details + capabilities + current foreground app for one device. |
| `pair` | Pair with a device (enter the code shown on the phone, or generate one). |
| `unpair` | Remove a device's trust. |
| `call` | Run a native tool on the phone (`computer.tap`, `screen.dump`, `device.info`, …). |
| `batch` | Run one tool across several phones at once. |
| `screenshot` | Capture the current screen (MediaProjection when active, else accessibility). |
| `screen_stream` | Start/stop a live screen stream; the first frame is returned as an image. |

The full device-tool reference (every `computer.*` / `screen.*` / `device.*` /
`app.*` tool, its parameters and return shape) is in
[`docs/MOBILE_MCP_TOOLS.md`](docs/MOBILE_MCP_TOOLS.md).

## Requirements

- Node.js ≥ 18.
- The **FreeCode Agent** app installed on the Android phone, its accessibility
  service enabled, notifications allowed, and the phone on the **same Wi‑Fi** as
  the computer running this server.

## What this repo ships

This repository distributes the **compiled connector** (`dist/`) — the ready-to-run
MCP server — not the TypeScript source. Clone it, install the two runtime
dependencies, and run:

```bash
git clone https://github.com/zunairvf-sys/MCP-Mobile-FreeCode.git
cd MCP-Mobile-FreeCode
npm install          # pulls @modelcontextprotocol/sdk + ws
node dist/index.js   # speaks MCP over stdio
```

### Wire it into an MCP client

Add an entry to your client's MCP config (here, `.mcp.json`):

```json
{
  "mcpServers": {
    "mobile-freecode": {
      "command": "node",
      "args": ["/absolute/path/to/MCP-Mobile-FreeCode/dist/index.js"]
    }
  }
}
```

Paired devices and this host's identity are stored per-user in
`~/.freecode/` (`mobile-paired.json`, `mobile-host.json`) so every client that
runs this server shares the same trust store.

## License

Licensed under the **Apache License, Version 2.0**. See [`LICENSE`](LICENSE) and
[`NOTICE`](NOTICE).

## Trademarks

The Apache-2.0 license covers the **code**. It does **not** grant any right to
the **names or brand**. "FreeCode", "FreeCode Agent", and "Mobile FreeCode", and
their logos, are trademarks of the project author. You may fork and redistribute
this code under the Apache-2.0 terms, but you may **not**:

- ship your fork under the "FreeCode" / "FreeCode Agent" name or logo,
- represent your build as the official FreeCode app, or
- reuse the FreeCode Agent Android package id or AdMob/publisher identifiers.

If you distribute a modified version, give it your own name.