Mobile MCP: let AI agents drive your iOS and Android apps. MCP server for simulators, emulators and real devices. Works with Claude Code, Codex, Cursor and any MCP client.
TypeScript agentandroidandroid-automationappium-alternativeclaude-codecodexcursoremulatoriosios-automationmcpmcp-servermobilemobile-automationmobile-testingreal-devicesimulatorskills
import path from "node:path";
import os from "node:os";
import fs from "node:fs";
import { randomBytes } from "node:crypto";
import { ActionableError } from "./robot";
export function validatePackageName(packageName: string): void {
// iOS bundle identifiers (which flow through this same "packageName" parameter
// for launch/terminate) are allowed to contain hyphens per Apple's CFBundleIdentifier
// format, e.g. "com.some-company.app".
if (!/^[a-zA-Z0-9._-]+$/.test(packageName)) {
throw new ActionableError(`Invalid package name: "${packageName}"`);
}
}
export function validateLocale(locale: string): void {
if (!/^[a-zA-Z0-9,\- ]+$/.test(locale)) {
throw new ActionableError(`Invalid locale: "${locale}"`);
}
}
// a url scheme per RFC 3986 section 3.1: a letter, then letters, digits, "+", "-" or "."
const URL_SCHEME = /^[a-zA-Z][a-zA-Z0-9+.-]*:/;
// url schemes are case-insensitive, but android matches an intent's scheme
// case-sensitively, so HTTPS://example.com would find no browser
export function withLowercaseScheme(url: string): string {
return url.replace(URL_SCHEME, scheme => scheme.toLowerCase());
}
function resolveRoot(root: string): string {
const resolved = path.resolve(root);
try {
return fs.realpathSync(resolved);
} catch {
return resolved;
}
}
// the filesystem root, the home directory, or anything above it would make
// almost every file the user owns writable, so it is never an implicit root
function isTooBroadToAllow(dir: string): boolean {
const resolvedDir = resolveRoot(dir);
const home = resolveRoot(os.homedir());
return resolvedDir === home || isPathUnderRoot(home, resolvedDir);
}
function getAllowedRoots(): string[] {
const roots = [os.tmpdir()];
if (!isTooBroadToAllow(process.cwd())) {
roots.push(process.cwd());
}
// macOS /tmp is a symlink to /private/tmp, add both to be safe
if (process.platform === "darwin") {
roots.push("/tmp");
roots.push("/private/tmp");
}
// Resolve symlinks so roots line up with resolveWithSymlinks() below. On macOS,
// os.tmpdir() itself lives under /var/folders/..., and /var is a symlink to
// /private/var, so without this the real temp directory never matches here.
return roots.map(resolveRoot);
}
function isPathUnderRoot(filePath: string, root: string): boolean {
const relative = path.relative(root, filePath);
if (relative === "") {
return false;
}
if (path.isAbsolute(relative)) {
return false;
}
if (relative.startsWith("..")) {
return false;
}
return true;
}
export function validateFileExtension(filePath: string, allowedExtensions: string[], toolName: string): void {
const ext = path.extname(filePath).toLowerCase();
if (!allowedExtensions.includes(ext)) {
throw new ActionableError(`${toolName} requires a ${allowedExtensions.join(", ")} file extension, got: "${ext || "(none)"}"`);
}
}
// windows follows up to 63 reparse points per path, linux 40 and macos 32;
// anything longer is rejected rather than handed to the write
const MAX_SYMLINK_HOPS = 64;
// Walk `filePath` to the real location a write would land on, following a
// symlink in EVERY component - not just the parent directory. Resolving only the
// parent let a symlink at, or before, the final component redirect the write
// while the check still saw an in-root path: a single final-component link was
// covered, but a chain whose intermediate link sits inside an allowed root and
// whose final target is dangling (the file a write would create) was not, so the
// write escaped. Follow each hop to its target until a component that either
// exists as a real file or does not exist at all, and hand that to the root check.
function resolveWithSymlinks(filePath: string): string {
let current = path.resolve(filePath);
// bound the walk so a symlink cycle cannot spin forever
for (let hops = 0; hops < MAX_SYMLINK_HOPS; hops++) {
const dir = path.dirname(current);
const filename = path.basename(current);
// resolve the containing directory first (it may be a symlink itself,
// e.g. /tmp and /var on macOS) so it lines up with the allowed roots
let realDir: string;
try {
realDir = fs.realpathSync(dir);
} catch {
realDir = dir;
}
const candidate = path.join(realDir, filename);
let stat: fs.Stats;
try {
stat = fs.lstatSync(candidate);
} catch {
// nothing there yet, it will be created at `candidate`
return candidate;
}
if (!stat.isSymbolicLink()) {
return candidate;
}
// follow the link to its target - which may itself be a link, or may not
// exist yet (exactly where a write would create the file) - and resolve again
current = path.resolve(realDir, fs.readlinkSync(candidate));
}
throw new ActionableError(`"${filePath}" has too many levels of symbolic links.`);
}
export function validateOutputPath(filePath: string): void {
const resolved = resolveWithSymlinks(filePath);
const allowedRoots = getAllowedRoots();
const isWindows = process.platform === "win32";
const isAllowed = allowedRoots.some(root => {
if (isWindows) {
return isPathUnderRoot(resolved.toLowerCase(), root.toLowerCase());
}
return isPathUnderRoot(resolved, root);
});
if (!isAllowed) {
const dir = path.dirname(resolved);
throw new ActionableError(
`"${dir}" is not in the list of allowed directories. Allowed directories: ${allowedRoots.join(", ")}.`
);
}
}
// a sibling of `to` with an unguessable name, created with O_EXCL ("wx"), so a
// file or link planted there makes the write fail instead of redirecting it
function partialPathFor(to: string): string {
return path.join(path.dirname(to), `.${path.basename(to)}.${randomBytes(8).toString("hex")}.partial`);
}
// write next to `filePath` and rename over it: rename replaces whatever sits at
// `filePath` (a symlink, a hard link, a regular file) instead of writing through
// it, so a link can never point the write at another file
export function writeOutputFile(filePath: string, data: string | Buffer): void {
const partial = partialPathFor(filePath);
const existing = fs.lstatSync(filePath, { throwIfNoEntry: false });
try {
// 0600 while half-written; a link at `filePath` is replaced, so only a
// regular file there passes its mode on to the new file
fs.writeFileSync(partial, data, { flag: "wx", mode: 0o600 });
if (existing?.isFile()) {
fs.chmodSync(partial, existing.mode & 0o777);
}
fs.renameSync(partial, filePath);
} catch (error) {
fs.rmSync(partial, { force: true });
throw error;
}
}
// a fresh 0700 directory nobody else can plant a symlink in, for files written
// by mobilecli rather than by us
export function createPrivateOutputPath(filename: string): string {
const dir = fs.mkdtempSync(path.join(os.tmpdir(), "mobile-mcp-"));
return path.join(dir, filename);
}
// rename replaces a symlink at `to` instead of following it. Across filesystems
// rename fails with EXDEV, so copy next to `to` first (COPYFILE_EXCL refuses an
// existing path) and rename that over `to`, keeping `to` intact if the copy fails
export function moveOutputFile(from: string, to: string): void {
try {
fs.renameSync(from, to);
return;
} catch (error: any) {
if (error.code !== "EXDEV") {
throw error;
}
}
const partial = partialPathFor(to);
try {
fs.copyFileSync(from, partial, fs.constants.COPYFILE_EXCL);
fs.renameSync(partial, to);
} catch (error) {
fs.rmSync(partial, { force: true });
throw error;
}
fs.rmSync(from);
}
// moves a finished recording from its private directory to the requested
// output; returns an error message when that fails, so stop can report it
export function finishRecording(recordingPath: string, outputPath: string): string | undefined {
if (!fs.existsSync(recordingPath)) {
return "mobilecli did not produce a recording";
}
if (recordingPath === outputPath) {
return undefined;
}
try {
validateOutputPath(outputPath);
moveOutputFile(recordingPath, outputPath);
} catch (error: any) {
// keep the private directory, the recording is still in it
return error.message;
}
fs.rmSync(path.dirname(recordingPath), { recursive: true, force: true });
return undefined;
}