android-mock-location-mcp 0.1.0

package/README.md

@@ -0,0 +1,210 @@
+# MCP Server — android-mock-location-mcp
+
+MCP server that exposes 8 tools for controlling Android device GPS location. Connects to an Android agent app over TCP (via ADB port forwarding) and supports geocoding and street-level routing through configurable providers.
+
+See the [root README](../README.md) for project overview and quick start.
+
+## Installation
+
+**npx (no install):**
+```bash
+npx android-mock-location-mcp
+```
+
+**Global install:**
+```bash
+npm install -g android-mock-location-mcp
+android-mock-location-mcp
+```
+
+**Build from source:**
+```bash
+cd server
+npm install
+npm run build
+npm start
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `PROVIDER` | Provider for geocoding + routing: `osm` (default), `google`, `mapbox` | No (defaults to `osm`) |
+| `GOOGLE_API_KEY` | Google Geocoding + Routes API key | When `PROVIDER=google` |
+| `MAPBOX_ACCESS_TOKEN` | Mapbox Geocoding + Directions access token | When `PROVIDER=mapbox` |
+
+Set environment variables in your MCP client configuration. See [root README](../README.md#provider-configuration) for client config examples.
+
+### Providers
+
+| `PROVIDER` | Geocoding Service | Routing Service | Profiles Supported | API Key | Cost |
+|------------|-------------------|-----------------|-------------------|---------|------|
+| `osm` (default) | Nominatim (OpenStreetMap) | OSRM | `car` only* | None | Free (rate-limited) |
+| `google` | Google Geocoding API | Google Routes API | `car`, `foot`, `bike` | `GOOGLE_API_KEY` | Paid (free tier) |
+| `mapbox` | Mapbox Geocoding | Mapbox Directions | `car`, `foot`, `bike` | `MAPBOX_ACCESS_TOKEN` | Paid (free tier) |
+
+**\*OSRM limitation:** The public OSRM demo server (`router.project-osrm.org`) only supports the `car` profile. Requesting `foot` or `bike` silently returns a driving route. For walking/cycling routing, use `google` or `mapbox`.
+
+**Nominatim rate limit:** The OSM Nominatim API is rate-limited to 1 request per second. When using the `osm` provider, the server hints the AI to resolve place names to coordinates itself and pass `lat`/`lng` directly.
+
+## Tool Reference
+
+### `geo_list_devices`
+
+List connected Android devices via ADB.
+
+No parameters.
+
+---
+
+### `geo_connect_device`
+
+Connect to an Android device for mock location control. Sets up ADB port forwarding and opens a TCP socket.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `deviceId` | string | yes | Device serial from `geo_list_devices`, e.g. `emulator-5554` |
+
+---
+
+### `geo_set_location`
+
+Set device GPS to coordinates or any place name/address. Geocodes place names via the configured provider.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `lat` | number | no | — | Latitude (-90 to 90) |
+| `lng` | number | no | — | Longitude (-180 to 180) |
+| `place` | string | no | — | Place name or address, e.g. `'Times Square'`, `'Tokyo Station'` |
+| `accuracy` | number | no | `3` | GPS accuracy in meters |
+
+Provide either `place` or both `lat`/`lng`.
+
+---
+
+### `geo_simulate_route`
+
+Simulate movement along a route between two points at a given speed. Routes follow real streets via the configured routing provider. Falls back to straight-line if the provider fails.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `from` | string | no | — | Starting place name or address |
+| `to` | string | no | — | Destination place name or address |
+| `fromLat` | number | no | — | Starting latitude |
+| `fromLng` | number | no | — | Starting longitude |
+| `toLat` | number | no | — | Destination latitude |
+| `toLng` | number | no | — | Destination longitude |
+| `speedKmh` | number | no | `60` | Speed in km/h |
+| `trafficMultiplier` | number | no | `1.0` | Traffic slowdown factor (e.g. `1.5` = 50% slower) |
+| `profile` | enum | no | `car` | Routing profile: `car`, `foot`, or `bike` |
+
+Provide either `from`/`to` (place names) or `fromLat`/`fromLng`/`toLat`/`toLng` (coordinates) for each endpoint.
+
+#### Routing Profiles
+
+| Profile | Use for | Routes on |
+|---------|---------|-----------|
+| `car` (default) | Driving simulation | Roads, highways |
+| `foot` | Walking simulation | Sidewalks, pedestrian paths |
+| `bike` | Cycling simulation | Bike lanes, roads |
+
+The AI should select `profile` based on user intent (e.g. "walk to" → `foot`, "drive to" → `car`).
+
+---
+
+### `geo_simulate_jitter`
+
+Simulate GPS noise/jitter at a location for testing accuracy handling.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `lat` | number | no | — | Center latitude |
+| `lng` | number | no | — | Center longitude |
+| `place` | string | no | — | Center place name or address |
+| `radiusMeters` | number | no | `10` | Jitter radius in meters |
+| `pattern` | enum | no | `random` | Jitter pattern: `random`, `drift`, `urban_canyon` |
+| `durationSeconds` | number | no | `30` | Duration in seconds |
+
+Provide either `place` or both `lat`/`lng`.
+
+#### Jitter Patterns
+
+| Pattern | Behavior |
+|---------|----------|
+| `random` | Uniform random distribution within radius |
+| `drift` | Gradual movement in one direction |
+| `urban_canyon` | Alternating accurate (3m) and inaccurate (50-80m) fixes, simulating tall buildings |
+
+---
+
+### `geo_test_geofence`
+
+Test geofence enter/exit/bounce behavior at a location.
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `lat` | number | no | — | Geofence center latitude |
+| `lng` | number | no | — | Geofence center longitude |
+| `place` | string | no | — | Geofence center place name or address |
+| `radiusMeters` | number | no | `100` | Geofence radius in meters |
+| `action` | enum | no | `enter` | Geofence action: `enter`, `exit`, `bounce` |
+| `bounceCount` | number | no | `3` | Number of boundary crossings (for `bounce` action) |
+
+Provide either `place` or both `lat`/`lng`.
+
+#### Geofence Actions
+
+| Action | Behavior |
+|--------|----------|
+| `enter` | Move from outside to inside the geofence |
+| `exit` | Move from inside to outside the geofence |
+| `bounce` | Cross the boundary `bounceCount` times |
+
+---
+
+### `geo_stop`
+
+Stop any active location simulation.
+
+No parameters.
+
+---
+
+### `geo_get_status`
+
+Get current connection and simulation status.
+
+No parameters.
+
+## Source Structure
+
+| File | Purpose |
+|------|---------|
+| `src/index.ts` | MCP server setup, all 8 tool definitions with Zod schemas |
+| `src/device.ts` | ADB commands (`execFileSync`), TCP socket to agent, request/response matching |
+| `src/geocode.ts` | Geocoding providers: Nominatim, Google, Mapbox |
+| `src/routing.ts` | Routing providers: OSRM, Google Routes API, Mapbox Directions |
+| `src/geo-math.ts` | Haversine distance, forward bearing calculation |
+| `src/fetch-utils.ts` | Shared `fetchWithTimeout` helper |
+
+## Development
+
+```bash
+npm install       # Install dependencies
+npm run build     # Compile TypeScript
+npm run dev       # Watch mode (recompile on change)
+npm start         # Run the server
+```
+
+The server communicates via stdio (MCP protocol). To test interactively, use the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector).
+
+## Adding a New Provider
+
+Both `src/geocode.ts` and `src/routing.ts` use the same pattern:
+
+1. Implement the `GeocodeProvider` type (in `geocode.ts`) and/or `RoutingProvider` type (in `routing.ts`)
+2. Add a case to `selectProvider()` in the respective file
+3. Validate required env vars in the `selectProvider()` switch case
+4. Document the new env var in this README and in `CLAUDE.md`

package/dist/device.d.ts

@@ -0,0 +1,10 @@
+/** Register a callback invoked when the device socket disconnects. */
+export declare function onDisconnect(cb: () => void): void;
+export declare function getConnectedDeviceId(): string | null;
+export declare function isConnected(): boolean;
+/** List connected ADB devices. Returns raw `adb devices -l` output. */
+export declare function listDevices(): string;
+/** Send a JSON command to the agent and await the response (5s timeout). */
+export declare function sendCommand(command: Record<string, unknown>): Promise<unknown>;
+/** Set up ADB port forwarding and open a TCP socket to the agent. */
+export declare function connectToDevice(deviceId: string): void;

package/dist/device.js

@@ -0,0 +1,154 @@
+// ── ADB + socket communication with Android agent ───────────────────────────
+import * as net from "node:net";
+import { execFileSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+// ── State ────────────────────────────────────────────────────────────────────
+let socket = null;
+let connectedDeviceId = null;
+let socketBuffer = "";
+let autoReconnectAttempted = false;
+let reconnectTimer = null;
+const pendingRequests = new Map();
+let disconnectCallback = null;
+// ── Public API ───────────────────────────────────────────────────────────────
+/** Register a callback invoked when the device socket disconnects. */
+export function onDisconnect(cb) {
+    disconnectCallback = cb;
+}
+export function getConnectedDeviceId() {
+    return connectedDeviceId;
+}
+export function isConnected() {
+    return socket !== null && !socket.destroyed;
+}
+/** List connected ADB devices. Returns raw `adb devices -l` output. */
+export function listDevices() {
+    return execFileSync("adb", ["devices", "-l"], { encoding: "utf-8" });
+}
+/** Send a JSON command to the agent and await the response (5s timeout). */
+export function sendCommand(command) {
+    const sock = socket;
+    if (!sock || sock.destroyed) {
+        return Promise.reject(new Error("Not connected to device. Troubleshooting: " +
+            "(1) Call geo_connect_device with the device serial from geo_list_devices. " +
+            "(2) Verify the GeoMCP Agent service is running in the app (green indicator). " +
+            "(3) Check adb port forwarding: run `adb forward tcp:5005 tcp:5005`."));
+    }
+    const id = randomUUID();
+    const msg = { ...command, id };
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            pendingRequests.delete(id);
+            reject(new Error("Command timed out (5s). Troubleshooting: " +
+                "(1) Verify the GeoMCP Agent service is running in the app (green indicator). " +
+                "(2) Restart adb port forwarding: `adb forward tcp:5005 tcp:5005`. " +
+                "(3) Check agent logs: `adb logcat -s GeoMCP`."));
+        }, 5000);
+        pendingRequests.set(id, { resolve, reject, timer });
+        try {
+            sock.write(JSON.stringify(msg) + "\n");
+        }
+        catch (err) {
+            clearTimeout(timer);
+            pendingRequests.delete(id);
+            reject(err instanceof Error ? err : new Error(String(err)));
+        }
+    });
+}
+/** Set up ADB port forwarding and open a TCP socket to the agent. */
+export function connectToDevice(deviceId) {
+    // Cancel any pending auto-reconnect so it doesn't clobber this connection
+    if (reconnectTimer !== null) {
+        clearTimeout(reconnectTimer);
+        reconnectTimer = null;
+    }
+    // User-initiated connections reset the reconnect guard so the next
+    // unexpected disconnect is eligible for one automatic retry.
+    autoReconnectAttempted = false;
+    openSocket(deviceId);
+}
+/**
+ * Core connection logic shared by public connectToDevice and the internal
+ * auto-reconnect path.  Does NOT touch autoReconnectAttempted — callers
+ * decide whether the guard should be reset.
+ */
+function openSocket(deviceId) {
+    if (!/^[a-zA-Z0-9._:\-]+$/.test(deviceId)) {
+        throw new Error(`Invalid device ID: ${deviceId}`);
+    }
+    try {
+        execFileSync("adb", ["-s", deviceId, "forward", "tcp:5005", "tcp:5005"], { encoding: "utf-8" });
+    }
+    catch (err) {
+        throw new Error(`Failed to set up adb port forwarding for ${deviceId}: ${err.message}`);
+    }
+    if (socket && !socket.destroyed) {
+        socket.destroy();
+    }
+    const sock = new net.Socket();
+    socket = sock;
+    connectedDeviceId = deviceId;
+    setupSocketHandlers(sock);
+    sock.connect({ host: "127.0.0.1", port: 5005 });
+}
+// ── Internal ─────────────────────────────────────────────────────────────────
+function setupSocketHandlers(sock) {
+    socketBuffer = "";
+    sock.on("data", (data) => {
+        socketBuffer += data.toString();
+        const lines = socketBuffer.split("\n");
+        socketBuffer = lines.pop(); // keep incomplete last chunk
+        for (const line of lines) {
+            if (!line.trim())
+                continue;
+            try {
+                const parsed = JSON.parse(line);
+                const id = parsed.id;
+                if (id && pendingRequests.has(id)) {
+                    const entry = pendingRequests.get(id);
+                    clearTimeout(entry.timer);
+                    entry.resolve(parsed);
+                    pendingRequests.delete(id);
+                }
+            }
+            catch {
+                // ignore unparseable lines
+            }
+        }
+    });
+    const cleanup = () => {
+        if (socket !== sock)
+            return; // only clean up if this socket is still current
+        const previousDeviceId = connectedDeviceId;
+        for (const [id, entry] of pendingRequests) {
+            clearTimeout(entry.timer);
+            entry.reject(new Error("Socket closed. The device may have disconnected. " +
+                "Auto-reconnect will be attempted once. If it fails, call geo_connect_device again."));
+            pendingRequests.delete(id);
+        }
+        socket = null;
+        connectedDeviceId = null;
+        disconnectCallback?.();
+        // Auto-reconnect once — avoid infinite retry loop on persistent failures.
+        // Uses openSocket (not connectToDevice) so autoReconnectAttempted stays
+        // true, preventing further retries if this attempt also fails.
+        if (previousDeviceId && !autoReconnectAttempted) {
+            autoReconnectAttempted = true;
+            reconnectTimer = setTimeout(() => {
+                reconnectTimer = null;
+                try {
+                    openSocket(previousDeviceId);
+                }
+                catch (err) {
+                    console.error(`Auto-reconnect failed for ${previousDeviceId}: ${err instanceof Error ? err.message : err}`);
+                }
+            }, 1000);
+        }
+    };
+    sock.on("error", (err) => {
+        console.error(`Socket error: ${err.message}`);
+        cleanup();
+    });
+    sock.on("close", cleanup);
+}
+//# sourceMappingURL=device.js.map

package/dist/device.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"device.js","sourceRoot":"","sources":["../src/device.ts"],"names":[],"mappings":"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"}

package/dist/fetch-utils.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Fetch with an AbortController-based timeout.
+ * Rejects with an AbortError if the request exceeds timeoutMs.
+ */
+export declare function fetchWithTimeout(url: string, init: RequestInit, timeoutMs: number): Promise<Response>;

package/dist/fetch-utils.js

@@ -0,0 +1,16 @@
+// ── Fetch utilities ──────────────────────────────────────────────────────────
+/**
+ * Fetch with an AbortController-based timeout.
+ * Rejects with an AbortError if the request exceeds timeoutMs.
+ */
+export async function fetchWithTimeout(url, init, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetch(url, { ...init, signal: controller.signal });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=fetch-utils.js.map

package/dist/fetch-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-utils.js","sourceRoot":"","sources":["../src/fetch-utils.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAEhF;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,GAAW,EAAE,IAAiB,EAAE,SAAiB;IACtF,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAC;IAC9D,IAAI,CAAC;QACH,OAAO,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC;IAClE,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;AACH,CAAC"}

package/dist/geo-math.d.ts

@@ -0,0 +1,4 @@
+/** Haversine distance between two points in meters. */
+export declare function haversineDistance(lat1: number, lng1: number, lat2: number, lng2: number): number;
+/** Forward azimuth (bearing) in degrees 0-360 from point 1 to point 2. */
+export declare function computeBearing(lat1: number, lng1: number, lat2: number, lng2: number): number;

package/dist/geo-math.js

@@ -0,0 +1,20 @@
+// ── Geographic math utilities ────────────────────────────────────────────────
+const R = 6_371_000; // Earth radius in meters
+const toRad = (d) => (d * Math.PI) / 180;
+const toDeg = (r) => (r * 180) / Math.PI;
+/** Haversine distance between two points in meters. */
+export function haversineDistance(lat1, lng1, lat2, lng2) {
+    const dLat = toRad(lat2 - lat1);
+    const dLng = toRad(lng2 - lng1);
+    const a = Math.sin(dLat / 2) ** 2 + Math.cos(toRad(lat1)) * Math.cos(toRad(lat2)) * Math.sin(dLng / 2) ** 2;
+    return R * 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+}
+/** Forward azimuth (bearing) in degrees 0-360 from point 1 to point 2. */
+export function computeBearing(lat1, lng1, lat2, lng2) {
+    const dLng = toRad(lng2 - lng1);
+    const y = Math.sin(dLng) * Math.cos(toRad(lat2));
+    const x = Math.cos(toRad(lat1)) * Math.sin(toRad(lat2)) -
+        Math.sin(toRad(lat1)) * Math.cos(toRad(lat2)) * Math.cos(dLng);
+    return (toDeg(Math.atan2(y, x)) + 360) % 360;
+}
+//# sourceMappingURL=geo-math.js.map

package/dist/geo-math.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"geo-math.js","sourceRoot":"","sources":["../src/geo-math.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAEhF,MAAM,CAAC,GAAG,SAAS,CAAC,CAAC,yBAAyB;AAC9C,MAAM,KAAK,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC;AACjD,MAAM,KAAK,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC;AAEjD,uDAAuD;AACvD,MAAM,UAAU,iBAAiB,CAAC,IAAY,EAAE,IAAY,EAAE,IAAY,EAAE,IAAY;IACtF,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;IAChC,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;IAChC,MAAM,CAAC,GACL,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;IACpG,OAAO,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAC5D,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,IAAY,EAAE,IAAY,EAAE,IAAY;IACnF,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;IAChC,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;IACjD,MAAM,CAAC,GACL,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC7C,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACjE,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;AAC/C,CAAC"}

package/dist/geocode.d.ts

@@ -0,0 +1,7 @@
+export interface GeocodeResult {
+    lat: number;
+    lng: number;
+    displayName: string;
+}
+export type GeocodeProvider = (place: string) => Promise<GeocodeResult | null>;
+export declare function geocodePlace(place: string): Promise<GeocodeResult | null>;

package/dist/geocode.js

@@ -0,0 +1,101 @@
+// ── Geocoding ────────────────────────────────────────────────────────────────
+//
+// The active geocoding provider is selected via the PROVIDER environment variable:
+//
+// All providers use a 10-second fetch timeout to prevent indefinite hangs.
+//
+//   PROVIDER=osm      → Nominatim (default, free, no API key)
+//   PROVIDER=google   → Google Geocoding API (requires GOOGLE_API_KEY)
+//   PROVIDER=mapbox   → Mapbox Geocoding (requires MAPBOX_ACCESS_TOKEN)
+//
+// To add a new provider, implement the GeocodeProvider signature and add a
+// case to selectProvider().
+import { fetchWithTimeout } from "./fetch-utils.js";
+// ── Nominatim (OpenStreetMap) ────────────────────────────────────────────────
+const nominatimGeocode = async (place) => {
+    const url = `https://nominatim.openstreetmap.org/search?${new URLSearchParams({
+        q: place,
+        format: "json",
+        limit: "1",
+    })}`;
+    const res = await fetchWithTimeout(url, {
+        headers: { "User-Agent": "android-mock-location-mcp/0.1.0" },
+    }, 10_000);
+    if (!res.ok)
+        return null;
+    const data = (await res.json());
+    if (data.length === 0)
+        return null;
+    return { lat: parseFloat(data[0].lat), lng: parseFloat(data[0].lon), displayName: data[0].display_name };
+};
+// ── Google Geocoding API ─────────────────────────────────────────────────────
+const googleGeocode = async (place) => {
+    const apiKey = process.env.GOOGLE_API_KEY; // Validated by selectProvider()
+    const url = `https://maps.googleapis.com/maps/api/geocode/json?${new URLSearchParams({
+        address: place,
+        key: apiKey,
+    })}`;
+    const res = await fetchWithTimeout(url, {}, 10_000);
+    if (!res.ok)
+        return null;
+    const data = (await res.json());
+    if (data.status !== "OK" || !data.results?.length)
+        return null;
+    const result = data.results[0];
+    return {
+        lat: result.geometry.location.lat,
+        lng: result.geometry.location.lng,
+        displayName: result.formatted_address,
+    };
+};
+// ── Mapbox Geocoding API ─────────────────────────────────────────────────────
+const mapboxGeocode = async (place) => {
+    const token = process.env.MAPBOX_ACCESS_TOKEN; // Validated by selectProvider()
+    const url = `https://api.mapbox.com/geocoding/v5/mapbox.places/${encodeURIComponent(place)}.json?` +
+        new URLSearchParams({ access_token: token, limit: "1" });
+    const res = await fetchWithTimeout(url, {
+        headers: { "User-Agent": "android-mock-location-mcp/0.1.0" },
+    }, 10_000);
+    if (!res.ok)
+        return null;
+    const data = (await res.json());
+    if (!data.features?.length)
+        return null;
+    const feature = data.features[0];
+    return {
+        lat: feature.center[1],
+        lng: feature.center[0],
+        displayName: feature.place_name,
+    };
+};
+// ── Provider Selection ───────────────────────────────────────────────────────
+// To switch providers, set PROVIDER env var to "osm", "google", or "mapbox".
+function selectProvider() {
+    const name = (process.env.PROVIDER ?? "osm").toLowerCase();
+    switch (name) {
+        case "google": {
+            if (!process.env.GOOGLE_API_KEY) {
+                throw new Error("PROVIDER=google requires GOOGLE_API_KEY environment variable");
+            }
+            return googleGeocode;
+        }
+        case "mapbox": {
+            if (!process.env.MAPBOX_ACCESS_TOKEN) {
+                throw new Error("PROVIDER=mapbox requires MAPBOX_ACCESS_TOKEN environment variable");
+            }
+            return mapboxGeocode;
+        }
+        default:
+            return nominatimGeocode;
+    }
+}
+const activeProvider = selectProvider();
+export async function geocodePlace(place) {
+    try {
+        return await activeProvider(place);
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=geocode.js.map

package/dist/geocode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"geocode.js","sourceRoot":"","sources":["../src/geocode.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};