Skip to content

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.

6.7 KB
Raw Blame
#!/usr/bin/env node
import { createMcpExpressApp } from "@modelcontextprotocol/express";
import { toNodeHandler } from "@modelcontextprotocol/node";
import { createMcpHandler } from "@modelcontextprotocol/server";
import { serveStdio } from "@modelcontextprotocol/server/stdio";
import { createMcpServer, getAgentVersion, getSdkVersion } from "./server";
import { error } from "./logger";
import { Request, Response } from "express";
import { program } from "commander";

type InstallOptions = { yes?: boolean };

const logMcpError = (err: Error) => {
	error("Error handling MCP request: " + (err.stack ?? String(err)));
};

const startHttpServer = async (host: string, port: number) => {
	// createMcpExpressApp applies express.json() and Host-header DNS rebinding
	// protection automatically when binding to localhost / 127.0.0.1 / ::1.
	const app = createMcpExpressApp({ host });

	// Migration hint for clients still pointing at the removed SSE transport.
	// Registered before auth so unauthenticated clients see the reason, not a 401.
	app.all("/sse", (_req: Request, res: Response) => {
		res.status(410).json({
			jsonrpc: "2.0",
			error: {
				code: -32000,
				message: "SSE transport removed. mobile-mcp now serves MCP Streamable HTTP at /mcp. See https://github.com/mobile-next/mobile-mcp#streamable-http-server-mode",
			},
			id: null,
		});
	});

	const authToken = process.env.MOBILEMCP_AUTH;
	if (!authToken) {
		error("WARNING: MOBILEMCP_AUTH is not set. The HTTP server will accept unauthenticated connections. Set MOBILEMCP_AUTH to require Bearer token authentication.");
	}

	if (authToken) {
		app.use((req, res, next) => {
			if (req.headers.authorization !== `Bearer ${authToken}`) {
				res.status(401).json({ error: "Unauthorized" });
				return;
			}

			next();
		});
	}

	// createMcpHandler serves both protocol eras from one factory: requests
	// carrying the per-request `_meta` envelope (revision 2026-07-28, answered
	// with `server/discover` and the modern result vocabulary) get a fresh
	// era-marked instance, and legacy `initialize` traffic is served stateless
	// from the same factory — the same per-request model as before.
	// onerror keeps request-handling and transport failures in the application
	// log (the SDK otherwise answers HTTP 500 silently).
	const handler = createMcpHandler(() => createMcpServer(), { onerror: logMcpError });
	const node = toNodeHandler(handler, { onerror: logMcpError });

	app.post("/mcp", (req: Request, res: Response) => {
		void node(req, res, req.body);
	});

	// Stateless mode has no long-lived sessions; GET (SSE stream) and DELETE
	// (session teardown) are not applicable. Return 405 per SDK guidance.
	const methodNotAllowed = (_req: Request, res: Response) => {
		res.status(405).json({
			jsonrpc: "2.0",
			error: {
				code: -32000,
				message: "Method not allowed.",
			},
			id: null,
		});
	};

	app.get("/mcp", methodNotAllowed);
	app.delete("/mcp", methodNotAllowed);

	app.listen(port, host, () => {
		error(`mobile-mcp ${getAgentVersion()} streamable http server listening on http://${host}:${port}/mcp`);
	});
};

const startStdioServer = async () => {
	try {
		// serveStdio owns the transport and the era decision for the
		// connection: a `server/discover` probe (revision 2026-07-28) pins
		// the connection modern, while an `initialize` handshake keeps
		// serving the 2025-era protocol exactly as before. The factory runs
		// lazily on the first message, so a failing createMcpServer() surfaces
		// through onerror rather than the catch below.
		serveStdio(() => createMcpServer(), { onerror: logMcpError });

		// Exit cleanly on termination signals so node flushes pending work
		// (including NODE_V8_COVERAGE output). Node's default SIGINT/SIGTERM
		// handling terminates the process without writing the coverage file,
		// which makes the `test:mcp` report come back all zeros.
		const shutdown = () => {
			process.exit(0);
		};

		process.on("SIGINT", shutdown);
		process.on("SIGTERM", shutdown);

		error(`mobile-mcp ${getAgentVersion()} (mcp sdk ${getSdkVersion()}) server running on stdio`);
	} catch (err: any) {
		console.error("Fatal error in main():", err);
		error("Fatal error in main(): " + JSON.stringify(err.stack));
		process.exit(1);
	}
};

const installIntoDetectedClients = async (options: InstallOptions) => {
	// add-mcp is ESM-only, loaded lazily so a normal server start does not pay for it
	const { agents, detectGlobalAgents, upsertServer } = await import("add-mcp");
	const prompts = await import("@clack/prompts");
	const config = { command: "npx", args: ["-y", "@mobilenext/mobile-mcp@latest"] };
	const detected = await detectGlobalAgents();
	if (detected.length === 0) {
		console.log("No MCP clients detected. See https://github.com/mobile-next/mobile-mcp#installation-and-configuration");
		return;
	}

	// no terminal to draw checkboxes on (e.g. an agent ran us), so behave like --yes
	let selected = detected;
	if (!options.yes && process.stdin.isTTY) {
		const answer = await prompts.multiselect({
			message: "Install mobile-mcp into which clients?",
			options: detected.map(agent => ({ value: agent, label: agents[agent].displayName })),
			initialValues: detected,
			required: false,
		});
		if (prompts.isCancel(answer)) {
			prompts.cancel("Installation cancelled.");
			return;
		}

		selected = answer;
	}

	for (const agent of selected) {
		const result = upsertServer(agent, "mobile-mcp", config);
		if (result.success) {
			console.log(`✓ ${agents[agent].displayName}: ${result.path}`);
		} else {
			console.log(`✗ ${agents[agent].displayName}: ${result.error}`);
			process.exitCode = 1;
		}
	}
};

const startServer = async () => {
	const options = program.opts();

	if (options.listen) {
		const listen = (options.listen as string).trim();
		const lastColon = listen.lastIndexOf(":");
		let host = "localhost";
		let rawPort: string;

		if (lastColon > 0) {
			host = listen.substring(0, lastColon);
			rawPort = listen.substring(lastColon + 1);
		} else {
			rawPort = listen;
		}

		const port = Number.parseInt(rawPort, 10);
		if (!host || !rawPort || !Number.isInteger(port) || port < 1 || port > 65535) {
			error(`Invalid --listen value "${listen}". Expected [host:]port with port 1-65535.`);
			process.exit(1);
		}

		await startHttpServer(host, port);
	} else {
		await startStdioServer();
	}
};

const main = async () => {
	program
		.version(getAgentVersion())
		.option("--listen <listen>", "Start Streamable HTTP server on [host:]port")
		.option("--stdio", "Start stdio server (default)")
		.action(startServer);

	program
		.command("install")
		.description("Add mobile-mcp to the MCP clients detected on this machine")
		.option("-y, --yes", "Install into every detected client without asking")
		.action(installIntoDetectedClients);

	await program.parseAsync(process.argv);
};

main().then();