appium-mcp 1.71.6 → 1.72.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [1.72.0](https://github.com/appium/appium-mcp/compare/v1.71.6...v1.72.0) (2026-05-01)
+
+### Features
+
+* add APPIUM_MCP_ON_CLIENT_DISCONNECT toggle ([#306](https://github.com/appium/appium-mcp/issues/306)) ([b77cae4](https://github.com/appium/appium-mcp/commit/b77cae4fe6753599f4c04cfedbb6e1b362c23ed2))
+
 ## [1.71.6](https://github.com/appium/appium-mcp/compare/v1.71.5...v1.71.6) (2026-05-01)
 
 ### Bug Fixes

package/README.md

@@ -143,6 +143,7 @@ This will automatically configure the MCP server for use with Claude Code. Make
 | `CAPABILITIES_CONFIG` | Optional | Absolute path to a `capabilities.json` file with per-platform capability presets |
 | `SCREENSHOTS_DIR` | Optional | Directory where screenshots and screen recordings are saved. Defaults to the current working directory |
 | `NO_UI` | Optional | Set to `true` or `1` to disable HTML UI components — faster responses, fewer tokens. See [NO_UI Mode](#no_ui-mode) |
+| `APPIUM_MCP_ON_CLIENT_DISCONNECT` | Optional | Session cleanup when the MCP client disconnects: `delete_all` (default) deletes **MCP-owned** Appium sessions (`safeDeleteAllSessions`); `skip` keeps those sessions across disconnects (e.g. HTTP/stream clients that reconnect). Attached/remote sessions are not removed by this path. See [MCP disconnect behavior](#mcp-disconnect-behavior). |
 | `APPIUM_MCP_WDA_APP_PATH` | Optional | Absolute path to a pre-extracted `WebDriverAgentRunner-Runner.app` bundle. When set, `prepare_ios_simulator` skips all GitHub downloads and uses this bundle directly — useful in environments where external downloads are blocked |
 | `REMOTE_SERVER_URL_ALLOW_REGEX` | Optional | Regex pattern that remote Appium server URLs must match. Defaults to `^https?://` |
 | `AI_VISION_API_BASE_URL` | Required for AI Vision | Base URL of the OpenAI-compatible vision model API |
@@ -321,6 +322,14 @@ The following tools return lightweight text-only responses when NO_UI is enabled
 - ✅ Scripted automation where human interaction is not needed
 - ❌ Interactive debugging and exploration (keep UI enabled for better experience)
 
+#### MCP disconnect behavior
+
+By default (`APPIUM_MCP_ON_CLIENT_DISCONNECT` unset or `delete_all`), when the **MCP client disconnects**, this server **deletes every MCP-owned Appium session** (the same sessions `safeDeleteAllSessions` targets) so embedded drivers are not left running after a short-lived assistant run. **Attached** sessions (`ownership=attached`) are unchanged by this teardown.
+
+HTTP and streamable MCP clients may **disconnect briefly** (reconnect, reload, proxy). If that tears down drivers you still need, set `APPIUM_MCP_ON_CLIENT_DISCONNECT` to `skip` in your MCP server `env` (same pattern as `NO_UI` above). With `skip`, sessions **survive** disconnect until you call `appium_session_management` with `action=delete`, or you stop the Appium server / process.
+
+**Tradeoff:** `skip` can leave **orphaned sessions** on your Appium server if nothing cleans up — use it when disconnect is not the same as “automation finished.”
+
 ## 🎯 Available Tools
 
 MCP Appium provides a comprehensive set of tools organized into the following categories:

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAMlC,QAAA,MAAM,MAAM,+CAKV,CAAC;AAgCH,eAAe,MAAM,CAAC"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AA0BlC,QAAA,MAAM,MAAM,+CAKV,CAAC;AA2CH,eAAe,MAAM,CAAC"}

package/dist/server.js

@@ -3,6 +3,21 @@ import registerTools from './tools/index.js';
 import registerResources from './resources/index.js';
 import { listSessions, safeDeleteAllSessions } from './session-store.js';
 import log from './logger.js';
+/**
+ * MCP disconnect policy for Appium sessions tracked by this server.
+ * - delete_all (default): end every owned session when the MCP client disconnects (avoids leaked drivers).
+ * - skip: keep sessions across disconnects — needed for flaky HTTP/stream clients that reconnect briefly.
+ */
+function disconnectSessionPolicyFromEnv() {
+    const raw = process.env.APPIUM_MCP_ON_CLIENT_DISCONNECT?.trim().toLowerCase();
+    if (raw === 'skip') {
+        return 'skip';
+    }
+    if (raw !== 'delete_all') {
+        log.warn(`APPIUM_MCP_ON_CLIENT_DISCONNECT="${raw}" is not recognized (expected delete_all or skip); defaulting to delete_all`);
+    }
+    return 'delete_all';
+}
 const server = new FastMCP({
     name: 'MCP Appium',
     version: '1.0.0',
@@ -16,7 +31,13 @@ server.on('connect', (event) => {
 });
 server.on('disconnect', async (event) => {
     log.info('Client disconnected:', event.session);
+    const policy = disconnectSessionPolicyFromEnv();
     const ownedSessions = listSessions().filter((session) => session.ownership === 'owned');
+    if (ownedSessions.length > 0 && policy === 'skip') {
+        log.info(`${ownedSessions.length} owned session(s) retained after MCP disconnect ` +
+            '(APPIUM_MCP_ON_CLIENT_DISCONNECT=skip). Delete explicitly via appium_session_management (action=delete) when finished.');
+        return;
+    }
     if (ownedSessions.length > 0) {
         try {
             log.info(`${ownedSessions.length} owned session(s) detected on disconnect, cleaning up...`);

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,aAAa,MAAM,kBAAkB,CAAC;AAC7C,OAAO,iBAAiB,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,GAAG,MAAM,aAAa,CAAC;AAE9B,MAAM,MAAM,GAAG,IAAI,OAAO,CAAC;IACzB,IAAI,EAAE,YAAY;IAClB,OAAO,EAAE,OAAO;IAChB,YAAY,EACV,mPAAmP;CACtP,CAAC,CAAC;AAEH,iBAAiB,CAAC,MAAM,CAAC,CAAC;AAC1B,aAAa,CAAC,MAAM,CAAC,CAAC;AAEtB,oDAAoD;AACpD,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,EAAE;IAC7B,GAAG,CAAC,IAAI,CAAC,mBAAmB,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;AAC/C,CAAC,CAAC,CAAC;AAEH,MAAM,CAAC,EAAE,CAAC,YAAY,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;IACtC,GAAG,CAAC,IAAI,CAAC,sBAAsB,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IAChD,MAAM,aAAa,GAAG,YAAY,EAAE,CAAC,MAAM,CACzC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,SAAS,KAAK,OAAO,CAC3C,CAAC;IACF,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7B,IAAI,CAAC;YACH,GAAG,CAAC,IAAI,CACN,GAAG,aAAa,CAAC,MAAM,0DAA0D,CAClF,CAAC;YACF,MAAM,YAAY,GAAG,MAAM,qBAAqB,EAAE,CAAC;YACnD,GAAG,CAAC,IAAI,CACN,GAAG,YAAY,oDAAoD,CACpE,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,GAAG,CAAC,KAAK,CAAC,0CAA0C,EAAE,KAAK,CAAC,CAAC;QAC/D,CAAC;IACH,CAAC;SAAM,CAAC;QACN,GAAG,CAAC,IAAI,CAAC,8CAA8C,CAAC,CAAC;IAC3D,CAAC;AACH,CAAC,CAAC,CAAC;AAEH,eAAe,MAAM,CAAC"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,aAAa,MAAM,kBAAkB,CAAC;AAC7C,OAAO,iBAAiB,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,GAAG,MAAM,aAAa,CAAC;AAI9B;;;;GAIG;AACH,SAAS,8BAA8B;IACrC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,+BAA+B,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC9E,IAAI,GAAG,KAAK,MAAM,EAAE,CAAC;QACnB,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,IAAI,GAAG,KAAK,YAAY,EAAE,CAAC;QACzB,GAAG,CAAC,IAAI,CACN,oCAAoC,GAAG,6EAA6E,CACrH,CAAC;IACJ,CAAC;IACD,OAAO,YAAY,CAAC;AACtB,CAAC;AAED,MAAM,MAAM,GAAG,IAAI,OAAO,CAAC;IACzB,IAAI,EAAE,YAAY;IAClB,OAAO,EAAE,OAAO;IAChB,YAAY,EACV,mPAAmP;CACtP,CAAC,CAAC;AAEH,iBAAiB,CAAC,MAAM,CAAC,CAAC;AAC1B,aAAa,CAAC,MAAM,CAAC,CAAC;AAEtB,oDAAoD;AACpD,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,EAAE;IAC7B,GAAG,CAAC,IAAI,CAAC,mBAAmB,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;AAC/C,CAAC,CAAC,CAAC;AAEH,MAAM,CAAC,EAAE,CAAC,YAAY,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;IACtC,GAAG,CAAC,IAAI,CAAC,sBAAsB,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IAChD,MAAM,MAAM,GAAG,8BAA8B,EAAE,CAAC;IAEhD,MAAM,aAAa,GAAG,YAAY,EAAE,CAAC,MAAM,CACzC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,SAAS,KAAK,OAAO,CAC3C,CAAC;IAEF,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;QAClD,GAAG,CAAC,IAAI,CACN,GAAG,aAAa,CAAC,MAAM,kDAAkD;YACvE,wHAAwH,CAC3H,CAAC;QACF,OAAO;IACT,CAAC;IAED,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7B,IAAI,CAAC;YACH,GAAG,CAAC,IAAI,CACN,GAAG,aAAa,CAAC,MAAM,0DAA0D,CAClF,CAAC;YACF,MAAM,YAAY,GAAG,MAAM,qBAAqB,EAAE,CAAC;YACnD,GAAG,CAAC,IAAI,CACN,GAAG,YAAY,oDAAoD,CACpE,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,GAAG,CAAC,KAAK,CAAC,0CAA0C,EAAE,KAAK,CAAC,CAAC;QAC/D,CAAC;IACH,CAAC;SAAM,CAAC;QACN,GAAG,CAAC,IAAI,CAAC,8CAA8C,CAAC,CAAC;IAC3D,CAAC;AACH,CAAC,CAAC,CAAC;AAEH,eAAe,MAAM,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "appium-mcp",
   "mcpName": "io.github.appium/appium-mcp",
-  "version": "1.71.6",
+  "version": "1.72.0",
   "type": "module",
   "repository": {
     "type": "git",

package/server.json

@@ -3,12 +3,12 @@
   "name": "io.github.appium/appium-mcp",
   "title": "MCP Appium - Mobile Development and Automation Server",
   "description": "MCP server for Appium mobile automation on iOS and Android devices with test creation tools.",
-  "version": "1.71.6",
+  "version": "1.72.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "appium-mcp",
-      "version": "1.71.6",
+      "version": "1.72.0",
       "transport": {
         "type": "stdio"
       }

package/src/server.ts

@@ -4,6 +4,26 @@ import registerResources from './resources/index.js';
 import { listSessions, safeDeleteAllSessions } from './session-store.js';
 import log from './logger.js';
 
+type DisconnectSessionPolicy = 'delete_all' | 'skip';
+
+/**
+ * MCP disconnect policy for Appium sessions tracked by this server.
+ * - delete_all (default): end every owned session when the MCP client disconnects (avoids leaked drivers).
+ * - skip: keep sessions across disconnects — needed for flaky HTTP/stream clients that reconnect briefly.
+ */
+function disconnectSessionPolicyFromEnv(): DisconnectSessionPolicy {
+  const raw = process.env.APPIUM_MCP_ON_CLIENT_DISCONNECT?.trim().toLowerCase();
+  if (raw === 'skip') {
+    return 'skip';
+  }
+  if (raw !== 'delete_all') {
+    log.warn(
+      `APPIUM_MCP_ON_CLIENT_DISCONNECT="${raw}" is not recognized (expected delete_all or skip); defaulting to delete_all`
+    );
+  }
+  return 'delete_all';
+}
+
 const server = new FastMCP({
   name: 'MCP Appium',
   version: '1.0.0',
@@ -21,9 +41,20 @@ server.on('connect', (event) => {
 
 server.on('disconnect', async (event) => {
   log.info('Client disconnected:', event.session);
+  const policy = disconnectSessionPolicyFromEnv();
+
   const ownedSessions = listSessions().filter(
     (session) => session.ownership === 'owned'
   );
+
+  if (ownedSessions.length > 0 && policy === 'skip') {
+    log.info(
+      `${ownedSessions.length} owned session(s) retained after MCP disconnect ` +
+        '(APPIUM_MCP_ON_CLIENT_DISCONNECT=skip). Delete explicitly via appium_session_management (action=delete) when finished.'
+    );
+    return;
+  }
+
   if (ownedSessions.length > 0) {
     try {
       log.info(