@nbakka/mcp-appium 1.0.0

package/README.md

@@ -0,0 +1 @@
+# mcp-appium

package/bin/mcp-appium.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+import MCPClient from "@modelcontextprotocol/sdk/client/mcp.js";
+
+async function main() {
+  const argv = await yargs(hideBin(process.argv))
+    .option("url", {
+      alias: "u",
+      type: "string",
+      demandOption: true,
+      describe: "MCP server base URL",
+    })
+    .command("start_session", "Start Appium session", (yargs) => {
+      yargs
+        .option("platformName", { type: "string", demandOption: true })
+        .option("deviceName", { type: "string", demandOption: true })
+        .option("app", { type: "string" })
+        .option("automationName", { type: "string" });
+    })
+    .command("tap <by> <value>", "Tap element", (yargs) => {
+      yargs.positional("by", { type: "string" }).positional("value", { type: "string" });
+    })
+    .command(
+      "swipe <startX> <startY> <endX> <endY> [duration]",
+      "Swipe gesture",
+      (yargs) => {
+        yargs
+          .positional("startX", { type: "number" })
+          .positional("startY", { type: "number" })
+          .positional("endX", { type: "number" })
+          .positional("endY", { type: "number" })
+          .positional("duration", { type: "number", default: 800 });
+      }
+    )
+    .demandCommand(1, "You must provide a command")
+    .help().argv;
+
+  const client = new MCPClient(argv.url);
+
+  try {
+    const cmd = argv._[0];
+    let result;
+
+    if (cmd === "start_session") {
+      const caps = {
+        platformName: argv.platformName,
+        deviceName: argv.deviceName,
+        app: argv.app,
+        automationName: argv.automationName,
+      };
+      result = await client.callTool("start_session", { capabilities: caps });
+    } else if (cmd === "tap") {
+      result = await client.callTool("tap", { by: argv.by, value: argv.value });
+    } else if (cmd === "swipe") {
+      result = await client.callTool("swipe", {
+        startX: argv.startX,
+        startY: argv.startY,
+        endX: argv.endX,
+        endY: argv.endY,
+        duration: argv.duration,
+      });
+    } else {
+      throw new Error(`Unknown command: ${cmd}`);
+    }
+
+    console.log(result.content.map((c) => c.text).join("\n"));
+  } catch (e) {
+    console.error("Error:", e.message);
+    process.exit(1);
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@nbakka/mcp-appium",
+  "version": "1.0.0",
+  "description": "MCP server for Appium using JSON Wire Protocol",
+  "type": "module",
+  "main": "src/lib/server.js",
+  "bin": {
+    "mcp-appium": "./bin/mcp-appium.js"
+  },
+  "scripts": {
+    "start": "node src/lib/server.js"
+  },
+  "files": [
+    "src",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.7.0",
+    "axios": "^1.4.0",
+    "zod": "^3.22.2",
+    "yargs": "^17.7.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "Your Name <youremail@example.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nbakka/mcp-appium.git"
+  }
+}

package/src/lib/server.js

@@ -0,0 +1,115 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import axios from "axios";
+
+const APPIUM_URL = "http://127.0.0.1:4723/wd/hub";
+
+const server = new McpServer({ name: "MCP Appium JSONWire", version: "1.0.0" });
+
+const state = { sessionId: null };
+
+// Helper to extract element ID
+function extractElementId(element) {
+  return element.ELEMENT || element["element-6066-11e4-a52e-4f735466cecf"];
+}
+
+// Start Session tool
+server.tool(
+  "start_session",
+  "Start Appium session with capabilities",
+  {
+    capabilities: z.object({
+      platformName: z.string(),
+      deviceName: z.string(),
+      app: z.string().optional(),
+      automationName: z.string().optional(),
+    }),
+  },
+  async ({ capabilities }) => {
+    try {
+      const payload = {
+        capabilities: {
+          firstMatch: [{}],
+          alwaysMatch: capabilities,
+        },
+      };
+      const response = await axios.post(`${APPIUM_URL}/session`, payload);
+      state.sessionId = response.data.sessionId;
+      return { content: [{ type: "text", text: `Session started: ${state.sessionId}` }] };
+    } catch (e) {
+      return { content: [{ type: "text", text: `Error starting session: ${e.message}` }] };
+    }
+  }
+);
+
+// Tap tool
+server.tool(
+  "tap",
+  "Tap element by locator",
+  {
+    by: z.enum(["id", "accessibility id", "xpath", "class name", "name"]),
+    value: z.string(),
+  },
+  async ({ by, value }) => {
+    if (!state.sessionId) return { content: [{ type: "text", text: "No active session" }] };
+    try {
+      const findResp = await axios.post(`${APPIUM_URL}/session/${state.sessionId}/element`, { using: by, value });
+      const elementId = extractElementId(findResp.data.value);
+      await axios.post(`${APPIUM_URL}/session/${state.sessionId}/element/${elementId}/click`);
+      return { content: [{ type: "text", text: "Element tapped" }] };
+    } catch (e) {
+      return { content: [{ type: "text", text: `Error tapping element: ${e.message}` }] };
+    }
+  }
+);
+
+// Swipe tool
+server.tool(
+  "swipe",
+  "Swipe from start to end coordinates",
+  {
+    startX: z.number(),
+    startY: z.number(),
+    endX: z.number(),
+    endY: z.number(),
+    duration: z.number().optional(),
+  },
+  async ({ startX, startY, endX, endY, duration = 800 }) => {
+    if (!state.sessionId) return { content: [{ type: "text", text: "No active session" }] };
+    try {
+      const actions = [
+        { action: "press", options: { x: startX, y: startY } },
+        { action: "wait", options: { ms: duration } },
+        { action: "moveTo", options: { x: endX, y: endY } },
+        { action: "release", options: {} },
+      ];
+      await axios.post(`${APPIUM_URL}/session/${state.sessionId}/touch/perform`, { actions });
+      return { content: [{ type: "text", text: `Swiped from (${startX},${startY}) to (${endX},${endY})` }] };
+    } catch (e) {
+      return { content: [{ type: "text", text: `Error swiping: ${e.message}` }] };
+    }
+  }
+);
+
+// Close Session tool
+server.tool(
+  "close_session",
+  "Close the current Appium session",
+  {},
+  async () => {
+    if (!state.sessionId) return { content: [{ type: "text", text: "No active session" }] };
+    try {
+      await axios.delete(`${APPIUM_URL}/session/${state.sessionId}`);
+      const oldSession = state.sessionId;
+      state.sessionId = null;
+      return { content: [{ type: "text", text: `Session ${oldSession} closed` }] };
+    } catch (e) {
+      return { content: [{ type: "text", text: `Error closing session: ${e.message}` }] };
+    }
+  }
+);
+
+// Connect MCP server to stdio
+const transport = new StdioServerTransport();
+await server.connect(transport);