appium-mcp 1.93.0 → 1.94.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,3 +1,9 @@
1
+ ## [1.94.0](https://github.com/appium/appium-mcp/compare/v1.93.0...v1.94.0) (2026-09-10)
2
+
3
+ ### Features
4
+
5
+ * load plugins from the command line ([#525](https://github.com/appium/appium-mcp/issues/525)) ([5eb1b99](https://github.com/appium/appium-mcp/commit/5eb1b9930836a85ba9ea2fd786e234d35a28e6e0))
6
+
1
7
  ## [1.93.0](https://github.com/appium/appium-mcp/compare/v1.92.14...v1.93.0) (2026-09-07)
2
8
 
3
9
  ### Features
package/README.md CHANGED
@@ -488,6 +488,41 @@ Treat this setting as an additional deployment safeguard. Network-level controls
488
488
 
489
489
  ## 🔌 Plugin API
490
490
 
491
+ ### Load plugins from the command line
492
+
493
+ Pass `--plugin` to start the standard server with a plugin, without writing a server bootstrap module. Repeat the option to load multiple plugins in order; both `--plugin <module>` and `--plugin=<module>` work with stdio and `--httpStream`:
494
+
495
+ ```bash
496
+ appium-mcp --plugin ./checkout-plugin.mjs --plugin=@acme/appium-mcp-plugin
497
+ ```
498
+
499
+ Each module must **default-export** either an `AppiumMcpPlugin` object or a plugin class whose constructor takes no arguments. For example, save this as `checkout-plugin.mjs`:
500
+
501
+ ```javascript
502
+ export default class CheckoutPlugin {
503
+ name = 'checkout-plugin';
504
+ version = '1.0.0';
505
+
506
+ register(registry) {
507
+ registry.addTool({
508
+ name: 'checkout_status',
509
+ description: 'Return the checkout integration status.',
510
+ execute: async () => ({content: [{type: 'text', text: 'Checkout plugin ready'}]}),
511
+ });
512
+ }
513
+ }
514
+ ```
515
+
516
+ Use an exported object (for example, `export default new CheckoutPlugin(options)`) when a plugin needs constructor options. TypeScript plugins must be compiled to JavaScript before loading.
517
+
518
+ Relative paths and installed package names resolve from the working directory where `appium-mcp` is launched. Package names use Node's CommonJS resolution (`createRequire(...).resolve()`), including `require` or `default` export conditions and legacy `main` entries. Packages exposing only an `import` export must be loaded through an explicit file path (for example, `--plugin ./node_modules/my-plugin/plugin.mjs`) or a `file:` URL. Loading still uses dynamic `import()`, so ESM plugin files, including those with top-level `await`, remain supported.
519
+
520
+ Absolute paths and `file:` URLs are also accepted; absolute paths are recommended in MCP client configurations because the client's working directory can vary. The CLI does not install packages: install package plugins in that working directory first.
521
+
522
+ Plugins execute in the server process, so load only trusted files and packages and keep plugin logs on stderr when using stdio. A missing module or invalid plugin export stops startup with an error instead of silently omitting the plugin. The optional documentation plugin, when enabled, is registered before CLI plugins. The existing duplicate-name and lifecycle rules below apply.
523
+
524
+ ### Compose a server programmatically
525
+
491
526
  Use `appium-mcp/core` to compose the default Appium MCP server with custom business logic without maintaining a fork. Plugins can register MCP tools, prompts, resources, and resource templates, and can wrap tool execution with lifecycle hooks. Call hooks are tool-only: prompts, resources, and resource templates are registered with FastMCP but are not wrapped by `beforeCall` or `afterCall`.
492
527
 
493
528
  `createAppiumMcpServer({ policy })` can also hide nonmatching tools and resources from MCP discovery. The factory is async, so await it before starting the returned server. Policy rules are regular expressions matched against tool and resource names exactly as registered. The policy is applied at registration time to both single and batch registration methods. Resource policy matches the resource `name` only; resources or resource templates without a string `name` cannot match a non-empty `allowResources` list.
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAEA,wBAAsB,MAAM,CAAC,IAAI,GAAE,MAAM,EAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAYlF"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAGA,wBAAsB,MAAM,CAAC,IAAI,GAAE,MAAM,EAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAYlF"}
package/dist/cli/index.js CHANGED
@@ -1,4 +1,5 @@
1
1
  import log, { configureStdioTransportLogging } from '../logger.js';
2
+ import { loadCliPlugins } from './plugins.js';
2
3
  export async function runCli(args = process.argv.slice(2)) {
3
4
  const command = args[0];
4
5
  if (command === '--help' || command === '-h' || command === 'help') {
@@ -16,6 +17,7 @@ function printHelp() {
16
17
  Options:
17
18
  --httpStream Start with httpStream transport
18
19
  --port=<port> Port for httpStream transport (default: 8080)
20
+ --plugin=<module> Load a plugin from a local path or installed package (repeatable)
19
21
  --help Show this help message`);
20
22
  }
21
23
  async function startServer(args) {
@@ -23,7 +25,9 @@ async function startServer(args) {
23
25
  const port = args.find((arg) => arg.startsWith('--port='))?.split('=')[1] || '8080';
24
26
  log.info('Starting MCP Appium MCP Server...');
25
27
  try {
26
- const { default: server } = await import('../server.js');
28
+ const plugins = await loadCliPlugins(args);
29
+ const { default: createDefaultServer } = await import('../server.js');
30
+ const server = await createDefaultServer(plugins);
27
31
  if (useHttpStream) {
28
32
  await server.start({
29
33
  transportType: 'httpStream',
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA,OAAO,GAAG,EAAE,EAAC,8BAA8B,EAAC,MAAM,cAAc,CAAC;AAEjE,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,OAAiB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACjE,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACxB,IAAI,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QACnE,SAAS,EAAE,CAAC;QACZ,OAAO;IACT,CAAC;IAED,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;QACnC,8BAA8B,EAAE,CAAC;IACnC,CAAC;IAED,MAAM,WAAW,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,SAAS,SAAS;IAChB,GAAG,CAAC,IAAI,CAAC;;;;;uCAK4B,CAAC,CAAC;AACzC,CAAC;AAED,KAAK,UAAU,WAAW,CAAC,IAAc;IACvC,MAAM,aAAa,GAAG,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;IACpD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC;IAEpF,GAAG,CAAC,IAAI,CAAC,mCAAmC,CAAC,CAAC;IAE9C,IAAI,CAAC;QACH,MAAM,EAAC,OAAO,EAAE,MAAM,EAAC,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC,CAAC;QAEvD,IAAI,aAAa,EAAE,CAAC;YAClB,MAAM,MAAM,CAAC,KAAK,CAAC;gBACjB,aAAa,EAAE,YAAY;gBAC3B,UAAU,EAAE;oBACV,QAAQ,EAAE,MAAM;oBAChB,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC;iBACzB;aACF,CAAC,CAAC;YAEH,GAAG,CAAC,IAAI,CAAC,gEAAgE,IAAI,MAAM,CAAC,CAAC;YACrF,GAAG,CAAC,IAAI,CAAC,mCAAmC,CAAC,CAAC;QAChD,CAAC;aAAM,CAAC;YACN,MAAM,MAAM,CAAC,KAAK,CAAC;gBACjB,aAAa,EAAE,OAAO;aACvB,CAAC,CAAC;YAEH,GAAG,CAAC,IAAI,CAAC,qCAAqC,CAAC,CAAC;YAChD,GAAG,CAAC,IAAI,CAAC,mCAAmC,CAAC,CAAC;QAChD,CAAC;IACH,CAAC;IAAC,OAAO,KAAU,EAAE,CAAC;QACpB,GAAG,CAAC,KAAK,CAAC,wBAAwB,EAAE,KAAK,CAAC,CAAC;QAC3C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA,OAAO,GAAG,EAAE,EAAC,8BAA8B,EAAC,MAAM,cAAc,CAAC;AACjE,OAAO,EAAC,cAAc,EAAC,MAAM,cAAc,CAAC;AAE5C,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,OAAiB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACjE,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACxB,IAAI,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QACnE,SAAS,EAAE,CAAC;QACZ,OAAO;IACT,CAAC;IAED,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;QACnC,8BAA8B,EAAE,CAAC;IACnC,CAAC;IAED,MAAM,WAAW,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,SAAS,SAAS;IAChB,GAAG,CAAC,IAAI,CAAC;;;;;;uCAM4B,CAAC,CAAC;AACzC,CAAC;AAED,KAAK,UAAU,WAAW,CAAC,IAAc;IACvC,MAAM,aAAa,GAAG,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;IACpD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC;IAEpF,GAAG,CAAC,IAAI,CAAC,mCAAmC,CAAC,CAAC;IAE9C,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,IAAI,CAAC,CAAC;QAC3C,MAAM,EAAC,OAAO,EAAE,mBAAmB,EAAC,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC,CAAC;QACpE,MAAM,MAAM,GAAG,MAAM,mBAAmB,CAAC,OAAO,CAAC,CAAC;QAElD,IAAI,aAAa,EAAE,CAAC;YAClB,MAAM,MAAM,CAAC,KAAK,CAAC;gBACjB,aAAa,EAAE,YAAY;gBAC3B,UAAU,EAAE;oBACV,QAAQ,EAAE,MAAM;oBAChB,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC;iBACzB;aACF,CAAC,CAAC;YAEH,GAAG,CAAC,IAAI,CAAC,gEAAgE,IAAI,MAAM,CAAC,CAAC;YACrF,GAAG,CAAC,IAAI,CAAC,mCAAmC,CAAC,CAAC;QAChD,CAAC;aAAM,CAAC;YACN,MAAM,MAAM,CAAC,KAAK,CAAC;gBACjB,aAAa,EAAE,OAAO;aACvB,CAAC,CAAC;YAEH,GAAG,CAAC,IAAI,CAAC,qCAAqC,CAAC,CAAC;YAChD,GAAG,CAAC,IAAI,CAAC,mCAAmC,CAAC,CAAC;QAChD,CAAC;IACH,CAAC;IAAC,OAAO,KAAU,EAAE,CAAC;QACpB,GAAG,CAAC,KAAK,CAAC,wBAAwB,EAAE,KAAK,CAAC,CAAC;QAC3C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC"}
@@ -0,0 +1,4 @@
1
+ import type { AppiumMcpPlugin } from '../core.js';
2
+ /** Load explicitly requested plugins in command-line order, relative to the caller. */
3
+ export declare function loadCliPlugins(args: string[], cwd?: string): Promise<AppiumMcpPlugin[]>;
4
+ //# sourceMappingURL=plugins.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"plugins.d.ts","sourceRoot":"","sources":["../../src/cli/plugins.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,YAAY,CAAC;AAEhD,uFAAuF;AACvF,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,SAAgB,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAuCpG"}
@@ -0,0 +1,60 @@
1
+ import { createRequire } from 'node:module';
2
+ import { isAbsolute, resolve as resolvePath } from 'node:path';
3
+ import { pathToFileURL } from 'node:url';
4
+ /** Load explicitly requested plugins in command-line order, relative to the caller. */
5
+ export async function loadCliPlugins(args, cwd = process.cwd()) {
6
+ const specifiers = [];
7
+ for (let index = 0; index < args.length; index++) {
8
+ const arg = args[index];
9
+ if (arg !== '--plugin' && !arg.startsWith('--plugin=')) {
10
+ continue;
11
+ }
12
+ const specifier = arg === '--plugin' ? args[++index] : arg.slice('--plugin='.length);
13
+ if (!specifier?.trim() || specifier.startsWith('--')) {
14
+ throw new Error('--plugin requires a module path or an installed package name.');
15
+ }
16
+ specifiers.push(specifier);
17
+ }
18
+ const plugins = [];
19
+ const requireFromCwd = createRequire(resolvePath(cwd, 'package.json'));
20
+ for (const specifier of specifiers) {
21
+ try {
22
+ const moduleSpecifier = isAbsolute(specifier) || specifier.startsWith('.')
23
+ ? resolvePath(cwd, specifier)
24
+ : URL.canParse(specifier)
25
+ ? new URL(specifier).href
26
+ : requireFromCwd.resolve(specifier);
27
+ const moduleURL = isAbsolute(moduleSpecifier) ? pathToFileURL(moduleSpecifier).href : moduleSpecifier;
28
+ if (!moduleURL.startsWith('file:')) {
29
+ throw new Error('Only local files and installed packages are supported.');
30
+ }
31
+ const module = (await import(moduleURL));
32
+ const exported = module.default;
33
+ const plugin = typeof exported === 'function' ? new exported() : exported;
34
+ assertPlugin(plugin);
35
+ plugins.push(plugin);
36
+ }
37
+ catch (error) {
38
+ const message = error instanceof Error ? error.message : String(error);
39
+ throw new Error(`Failed to load plugin "${specifier}": ${message}`, { cause: error });
40
+ }
41
+ }
42
+ return plugins;
43
+ }
44
+ function assertPlugin(plugin) {
45
+ if (typeof plugin !== 'object' || plugin === null) {
46
+ throw new Error('The default export must be an AppiumMcpPlugin object or a class with a no-argument constructor.');
47
+ }
48
+ const candidate = plugin;
49
+ for (const field of ['name', 'version']) {
50
+ if (typeof candidate[field] !== 'string' || !candidate[field].trim()) {
51
+ throw new Error(`The plugin must have a non-empty string "${field}".`);
52
+ }
53
+ }
54
+ for (const hook of ['initialize', 'register', 'beforeCall', 'afterCall', 'destroy']) {
55
+ if (candidate[hook] !== undefined && typeof candidate[hook] !== 'function') {
56
+ throw new Error(`Plugin "${candidate.name}" has an invalid "${hook}" hook; expected a function.`);
57
+ }
58
+ }
59
+ }
60
+ //# sourceMappingURL=plugins.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"plugins.js","sourceRoot":"","sources":["../../src/cli/plugins.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,aAAa,EAAC,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAC,UAAU,EAAE,OAAO,IAAI,WAAW,EAAC,MAAM,WAAW,CAAC;AAC7D,OAAO,EAAC,aAAa,EAAC,MAAM,UAAU,CAAC;AAIvC,uFAAuF;AACvF,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,IAAc,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE;IACtE,MAAM,UAAU,GAAa,EAAE,CAAC;IAChC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;QACjD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;QACxB,IAAI,GAAG,KAAK,UAAU,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;YACvD,SAAS;QACX,CAAC;QACD,MAAM,SAAS,GAAG,GAAG,KAAK,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QACrF,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YACrD,MAAM,IAAI,KAAK,CAAC,+DAA+D,CAAC,CAAC;QACnF,CAAC;QACD,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC7B,CAAC;IAED,MAAM,OAAO,GAAsB,EAAE,CAAC;IACtC,MAAM,cAAc,GAAG,aAAa,CAAC,WAAW,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC,CAAC;IACvE,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,CAAC;YACH,MAAM,eAAe,GACnB,UAAU,CAAC,SAAS,CAAC,IAAI,SAAS,CAAC,UAAU,CAAC,GAAG,CAAC;gBAChD,CAAC,CAAC,WAAW,CAAC,GAAG,EAAE,SAAS,CAAC;gBAC7B,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,SAAS,CAAC;oBACvB,CAAC,CAAC,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC,IAAI;oBACzB,CAAC,CAAC,cAAc,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;YAC1C,MAAM,SAAS,GAAG,UAAU,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,eAAe,CAAC;YACtG,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;gBACnC,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;YAC5E,CAAC;YACD,MAAM,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,SAAS,CAAC,CAAwB,CAAC;YAChE,MAAM,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC;YAChC,MAAM,MAAM,GAAG,OAAO,QAAQ,KAAK,UAAU,CAAC,CAAC,CAAC,IAAK,QAA8B,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC;YACjG,YAAY,CAAC,MAAM,CAAC,CAAC;YACrB,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACvB,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACvE,MAAM,IAAI,KAAK,CAAC,0BAA0B,SAAS,MAAM,OAAO,EAAE,EAAE,EAAC,KAAK,EAAE,KAAK,EAAC,CAAC,CAAC;QACtF,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,YAAY,CAAC,MAAe;IACnC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QAClD,MAAM,IAAI,KAAK,CAAC,iGAAiG,CAAC,CAAC;IACrH,CAAC;IACD,MAAM,SAAS,GAAG,MAAiC,CAAC;IACpD,KAAK,MAAM,KAAK,IAAI,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,CAAC;QACxC,IAAI,OAAO,SAAS,CAAC,KAAK,CAAC,KAAK,QAAQ,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;YACrE,MAAM,IAAI,KAAK,CAAC,4CAA4C,KAAK,IAAI,CAAC,CAAC;QACzE,CAAC;IACH,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,CAAC,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,SAAS,CAAC,EAAE,CAAC;QACpF,IAAI,SAAS,CAAC,IAAI,CAAC,KAAK,SAAS,IAAI,OAAO,SAAS,CAAC,IAAI,CAAC,KAAK,UAAU,EAAE,CAAC;YAC3E,MAAM,IAAI,KAAK,CAAC,WAAW,SAAS,CAAC,IAAI,qBAAqB,IAAI,8BAA8B,CAAC,CAAC;QACpG,CAAC;IACH,CAAC;AACH,CAAC"}
package/dist/server.d.ts CHANGED
@@ -1,3 +1,3 @@
1
- declare const server: import("fastmcp").FastMCP<import("fastmcp").FastMCPSessionAuth>;
2
- export default server;
1
+ import type { AppiumMcpPlugin } from './core.js';
2
+ export default function createDefaultServer(additionalPlugins?: AppiumMcpPlugin[]): Promise<import("fastmcp").FastMCP<import("fastmcp").FastMCPSessionAuth>>;
3
3
  //# sourceMappingURL=server.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAgBA,QAAA,MAAM,MAAM,iEAAyC,CAAC;AACtD,eAAe,MAAM,CAAC"}
1
+ {"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,WAAW,CAAC;AAI/C,wBAA8B,mBAAmB,CAAC,iBAAiB,GAAE,eAAe,EAAO,4EAc1F"}
package/dist/server.js CHANGED
@@ -1,15 +1,16 @@
1
1
  import { createAppiumMcpServer } from './create-server.js';
2
2
  import { isDocumentationEnabled, loadDocumentationPlugin } from './documentation.js';
3
- const plugins = [];
4
- // Documentation tools (RAG docs query + skills) are opt-in. They live in a
5
- // separate package only installed when the user sets
6
- // APPIUM_MCP_DOCS_ENABLED. See ./documentation.ts for the full contract.
7
- if (isDocumentationEnabled()) {
8
- const documentationPlugin = await loadDocumentationPlugin();
9
- if (documentationPlugin) {
10
- plugins.push(documentationPlugin);
3
+ export default async function createDefaultServer(additionalPlugins = []) {
4
+ const plugins = [];
5
+ // Documentation tools (RAG docs query + skills) are opt-in. They live in a
6
+ // separate package only installed when the user sets
7
+ // APPIUM_MCP_DOCS_ENABLED. See ./documentation.ts for the full contract.
8
+ if (isDocumentationEnabled()) {
9
+ const documentationPlugin = await loadDocumentationPlugin();
10
+ if (documentationPlugin) {
11
+ plugins.push(documentationPlugin);
12
+ }
11
13
  }
14
+ return await createAppiumMcpServer({ plugins: [...plugins, ...additionalPlugins] });
12
15
  }
13
- const server = await createAppiumMcpServer({ plugins });
14
- export default server;
15
16
  //# sourceMappingURL=server.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,qBAAqB,EAAC,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAC,sBAAsB,EAAE,uBAAuB,EAAC,MAAM,oBAAoB,CAAC;AAEnF,MAAM,OAAO,GAAsB,EAAE,CAAC;AAEtC,2EAA2E;AAC3E,qDAAqD;AACrD,yEAAyE;AACzE,IAAI,sBAAsB,EAAE,EAAE,CAAC;IAC7B,MAAM,mBAAmB,GAAG,MAAM,uBAAuB,EAAE,CAAC;IAC5D,IAAI,mBAAmB,EAAE,CAAC;QACxB,OAAO,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;IACpC,CAAC;AACH,CAAC;AAED,MAAM,MAAM,GAAG,MAAM,qBAAqB,CAAC,EAAC,OAAO,EAAC,CAAC,CAAC;AACtD,eAAe,MAAM,CAAC"}
1
+ {"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,qBAAqB,EAAC,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAC,sBAAsB,EAAE,uBAAuB,EAAC,MAAM,oBAAoB,CAAC;AAEnF,MAAM,CAAC,OAAO,CAAC,KAAK,UAAU,mBAAmB,CAAC,oBAAuC,EAAE;IACzF,MAAM,OAAO,GAAsB,EAAE,CAAC;IAEtC,2EAA2E;IAC3E,qDAAqD;IACrD,yEAAyE;IACzE,IAAI,sBAAsB,EAAE,EAAE,CAAC;QAC7B,MAAM,mBAAmB,GAAG,MAAM,uBAAuB,EAAE,CAAC;QAC5D,IAAI,mBAAmB,EAAE,CAAC;YACxB,OAAO,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;QACpC,CAAC;IACH,CAAC;IAED,OAAO,MAAM,qBAAqB,CAAC,EAAC,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,GAAG,iBAAiB,CAAC,EAAC,CAAC,CAAC;AACpF,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "appium-mcp",
3
- "version": "1.93.0",
3
+ "version": "1.94.0",
4
4
  "description": "Intelligent MCP server providing AI assistants with powerful tools and resources for Appium mobile automation",
5
5
  "bugs": {
6
6
  "url": "https://github.com/appium/appium-mcp/issues"
package/server.json CHANGED
@@ -3,12 +3,12 @@
3
3
  "name": "io.github.appium/appium-mcp",
4
4
  "title": "MCP Appium - Mobile Development and Automation Server",
5
5
  "description": "MCP server for Appium mobile automation on iOS and Android devices with test creation tools.",
6
- "version": "1.93.0",
6
+ "version": "1.94.0",
7
7
  "packages": [
8
8
  {
9
9
  "registryType": "npm",
10
10
  "identifier": "appium-mcp",
11
- "version": "1.93.0",
11
+ "version": "1.94.0",
12
12
  "transport": {
13
13
  "type": "stdio"
14
14
  }
package/src/cli/index.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  import log, {configureStdioTransportLogging} from '../logger.js';
2
+ import {loadCliPlugins} from './plugins.js';
2
3
 
3
4
  export async function runCli(args: string[] = process.argv.slice(2)): Promise<void> {
4
5
  const command = args[0];
@@ -20,6 +21,7 @@ function printHelp(): void {
20
21
  Options:
21
22
  --httpStream Start with httpStream transport
22
23
  --port=<port> Port for httpStream transport (default: 8080)
24
+ --plugin=<module> Load a plugin from a local path or installed package (repeatable)
23
25
  --help Show this help message`);
24
26
  }
25
27
 
@@ -30,7 +32,9 @@ async function startServer(args: string[]): Promise<void> {
30
32
  log.info('Starting MCP Appium MCP Server...');
31
33
 
32
34
  try {
33
- const {default: server} = await import('../server.js');
35
+ const plugins = await loadCliPlugins(args);
36
+ const {default: createDefaultServer} = await import('../server.js');
37
+ const server = await createDefaultServer(plugins);
34
38
 
35
39
  if (useHttpStream) {
36
40
  await server.start({
@@ -0,0 +1,64 @@
1
+ import {createRequire} from 'node:module';
2
+ import {isAbsolute, resolve as resolvePath} from 'node:path';
3
+ import {pathToFileURL} from 'node:url';
4
+
5
+ import type {AppiumMcpPlugin} from '../core.js';
6
+
7
+ /** Load explicitly requested plugins in command-line order, relative to the caller. */
8
+ export async function loadCliPlugins(args: string[], cwd = process.cwd()): Promise<AppiumMcpPlugin[]> {
9
+ const specifiers: string[] = [];
10
+ for (let index = 0; index < args.length; index++) {
11
+ const arg = args[index];
12
+ if (arg !== '--plugin' && !arg.startsWith('--plugin=')) {
13
+ continue;
14
+ }
15
+ const specifier = arg === '--plugin' ? args[++index] : arg.slice('--plugin='.length);
16
+ if (!specifier?.trim() || specifier.startsWith('--')) {
17
+ throw new Error('--plugin requires a module path or an installed package name.');
18
+ }
19
+ specifiers.push(specifier);
20
+ }
21
+
22
+ const plugins: AppiumMcpPlugin[] = [];
23
+ const requireFromCwd = createRequire(resolvePath(cwd, 'package.json'));
24
+ for (const specifier of specifiers) {
25
+ try {
26
+ const moduleSpecifier =
27
+ isAbsolute(specifier) || specifier.startsWith('.')
28
+ ? resolvePath(cwd, specifier)
29
+ : URL.canParse(specifier)
30
+ ? new URL(specifier).href
31
+ : requireFromCwd.resolve(specifier);
32
+ const moduleURL = isAbsolute(moduleSpecifier) ? pathToFileURL(moduleSpecifier).href : moduleSpecifier;
33
+ if (!moduleURL.startsWith('file:')) {
34
+ throw new Error('Only local files and installed packages are supported.');
35
+ }
36
+ const module = (await import(moduleURL)) as {default?: unknown};
37
+ const exported = module.default;
38
+ const plugin = typeof exported === 'function' ? new (exported as new () => unknown)() : exported;
39
+ assertPlugin(plugin);
40
+ plugins.push(plugin);
41
+ } catch (error: unknown) {
42
+ const message = error instanceof Error ? error.message : String(error);
43
+ throw new Error(`Failed to load plugin "${specifier}": ${message}`, {cause: error});
44
+ }
45
+ }
46
+ return plugins;
47
+ }
48
+
49
+ function assertPlugin(plugin: unknown): asserts plugin is AppiumMcpPlugin {
50
+ if (typeof plugin !== 'object' || plugin === null) {
51
+ throw new Error('The default export must be an AppiumMcpPlugin object or a class with a no-argument constructor.');
52
+ }
53
+ const candidate = plugin as Record<string, unknown>;
54
+ for (const field of ['name', 'version']) {
55
+ if (typeof candidate[field] !== 'string' || !candidate[field].trim()) {
56
+ throw new Error(`The plugin must have a non-empty string "${field}".`);
57
+ }
58
+ }
59
+ for (const hook of ['initialize', 'register', 'beforeCall', 'afterCall', 'destroy']) {
60
+ if (candidate[hook] !== undefined && typeof candidate[hook] !== 'function') {
61
+ throw new Error(`Plugin "${candidate.name}" has an invalid "${hook}" hook; expected a function.`);
62
+ }
63
+ }
64
+ }
package/src/server.ts CHANGED
@@ -2,17 +2,18 @@ import type {AppiumMcpPlugin} from './core.js';
2
2
  import {createAppiumMcpServer} from './create-server.js';
3
3
  import {isDocumentationEnabled, loadDocumentationPlugin} from './documentation.js';
4
4
 
5
- const plugins: AppiumMcpPlugin[] = [];
5
+ export default async function createDefaultServer(additionalPlugins: AppiumMcpPlugin[] = []) {
6
+ const plugins: AppiumMcpPlugin[] = [];
6
7
 
7
- // Documentation tools (RAG docs query + skills) are opt-in. They live in a
8
- // separate package only installed when the user sets
9
- // APPIUM_MCP_DOCS_ENABLED. See ./documentation.ts for the full contract.
10
- if (isDocumentationEnabled()) {
11
- const documentationPlugin = await loadDocumentationPlugin();
12
- if (documentationPlugin) {
13
- plugins.push(documentationPlugin);
8
+ // Documentation tools (RAG docs query + skills) are opt-in. They live in a
9
+ // separate package only installed when the user sets
10
+ // APPIUM_MCP_DOCS_ENABLED. See ./documentation.ts for the full contract.
11
+ if (isDocumentationEnabled()) {
12
+ const documentationPlugin = await loadDocumentationPlugin();
13
+ if (documentationPlugin) {
14
+ plugins.push(documentationPlugin);
15
+ }
14
16
  }
15
- }
16
17
 
17
- const server = await createAppiumMcpServer({plugins});
18
- export default server;
18
+ return await createAppiumMcpServer({plugins: [...plugins, ...additionalPlugins]});
19
+ }