appium-mcp 1.84.2 → 1.85.1

package/src/telemetry/attributes.ts

@@ -0,0 +1,104 @@
+/**
+ * Helpers for deciding whether telemetry is enabled and for building safe span
+ * attributes. This file intentionally exposes only low-cardinality metadata and
+ * filtered input names so spans do not capture secrets, screenshots, page
+ * source XML, prompts, or other user payloads.
+ */
+
+import { isTruthyEnvValue } from '../utils/env.js';
+import { isSensitiveKey } from '../utils/sensitive.js';
+import { getSessionId } from '../session-store.js';
+
+const MAX_ATTRIBUTE_VALUE_LENGTH = 2048;
+
+/**
+ * Determines whether telemetry is enabled based on the APPIUM_MCP_OTEL_ENABLED environment variable.
+ * Recognizes "1", "true", "yes", and "on" (case-insensitive) as true values.
+ * Defaults to false if the variable is not set or has an unrecognized value.
+ * @returns True if telemetry is enabled, false otherwise.
+ */
+export function isTelemetryEnabled(): boolean {
+  return isTruthyEnvValue(process.env.APPIUM_MCP_OTEL_ENABLED);
+}
+
+/**
+ * Determines whether including argument values in telemetry attributes is enabled based on the APPIUM_MCP_OTEL_INCLUDE_ARGUMENT_VALUES environment variable.
+ * Recognizes "1", "true", "yes", and "on" (case-insensitive) as true values.
+ * Defaults to false if the variable is not set or has an unrecognized value.
+ * When false, argument values will not be included in telemetry attributes, even for non-sensitive keys.
+ * When true, non-sensitive argument values will be included in telemetry attributes, while sensitive keys will still be excluded.
+ * @see safeInputValueAttributes for how argument values are included in attributes when this is enabled.
+ * @returns
+ */
+export function isArgumentValueTelemetryEnabled(): boolean {
+  return isTruthyEnvValue(process.env.APPIUM_MCP_OTEL_INCLUDE_ARGUMENT_VALUES);
+}
+
+/**
+ * Safely converts a value to a string, number, or boolean for use as a telemetry attribute.
+ * If the value is already a string, number, or boolean, it is returned as-is.
+ * If the value is null or undefined, an empty string is returned.
+ * Otherwise, the value is converted to a string.
+ * @param value The value to convert.
+ * @returns The safe attribute value.
+ */
+export function safeAttributeValue(value: unknown): string | number | boolean {
+  if (
+    typeof value === 'string' ||
+    typeof value === 'number' ||
+    typeof value === 'boolean'
+  ) {
+    return value;
+  }
+
+  if (value == null) {
+    return '';
+  }
+
+  try {
+    const serialized = JSON.stringify(value, (key, val) =>
+      key && isSensitiveKey(key) ? '[REDACTED]' : val
+    );
+    return truncateAttributeValue(serialized ?? String(value));
+  } catch {
+    return truncateAttributeValue(String(value));
+  }
+}
+
+/**
+ * Safely extracts the session ID from the given arguments.
+ * Falls back to the active session ID when no string argument sessionId exists.
+ * @param args The arguments object potentially containing a sessionId.
+ * @returns The session ID if present and valid, otherwise undefined.
+ */
+export function safeSessionId(args: unknown): string | undefined {
+  if (args && typeof args === 'object' && 'sessionId' in args) {
+    const sessionId = (args as { sessionId?: unknown }).sessionId;
+    if (typeof sessionId === 'string' && sessionId.length > 0) {
+      return sessionId;
+    }
+  }
+
+  return getSessionId() ?? undefined;
+}
+
+/**
+ * Safely extracts the input keys from the given arguments, excluding sensitive keys.
+ * @param args The arguments object potentially containing input keys.
+ * @returns An array of safe input keys.
+ */
+export function safeInputKeys(args: unknown): string[] {
+  if (!args || typeof args !== 'object' || Array.isArray(args)) {
+    return [];
+  }
+
+  return Object.keys(args)
+    .filter((key) => !isSensitiveKey(key))
+    .sort();
+}
+
+function truncateAttributeValue(value: string): string {
+  return value.length > MAX_ATTRIBUTE_VALUE_LENGTH
+    ? `${value.slice(0, MAX_ATTRIBUTE_VALUE_LENGTH)}...`
+    : value;
+}

package/src/telemetry/init.ts

@@ -0,0 +1,77 @@
+/**
+ * OpenTelemetry SDK bootstrap for the appium-mcp CLI. Initialization is opt-in
+ * via APPIUM_MCP_OTEL_ENABLED so normal server startup keeps the default no-op
+ * OpenTelemetry provider and avoids exporter setup unless tracing is requested.
+ */
+
+import log from '../logger.js';
+import { isTelemetryEnabled } from './attributes.js';
+
+let sdkStarted = false;
+let shutdownRegistered = false;
+let sdk: { start(): void; shutdown(): Promise<void> } | undefined;
+
+/**
+ * Initializes the OpenTelemetry SDK if telemetry is enabled and not already started.
+ * This function is idempotent and safe to call multiple times; the SDK will only
+ * be initialized once.
+ * @returns
+ */
+export async function initializeOpenTelemetry(): Promise<void> {
+  if (!isTelemetryEnabled() || sdkStarted) {
+    return;
+  }
+
+  const [{ NodeSDK }, { OTLPTraceExporter }] = await Promise.all([
+    import('@opentelemetry/sdk-node'),
+    import('@opentelemetry/exporter-trace-otlp-http'),
+  ]);
+
+  const nodeSdk = new NodeSDK({
+    traceExporter: new OTLPTraceExporter(),
+  });
+
+  sdk = nodeSdk;
+  nodeSdk.start();
+  sdkStarted = true;
+  registerShutdown();
+  log.info('OpenTelemetry tracing enabled for appium-mcp.');
+}
+
+/**
+ * Shuts down the OpenTelemetry SDK if it was started. This is typically called during process shutdown to ensure
+ * that all telemetry data is flushed properly. This function is idempotent and safe to call multiple times.
+ * @returns
+ */
+export async function shutdownOpenTelemetry(): Promise<void> {
+  if (!sdkStarted || !sdk) {
+    return;
+  }
+
+  try {
+    await sdk.shutdown();
+  } finally {
+    sdk = undefined;
+    sdkStarted = false;
+  }
+}
+
+function registerShutdown(): void {
+  if (shutdownRegistered) {
+    return;
+  }
+
+  shutdownRegistered = true;
+
+  const shutdown = async () => {
+    try {
+      await shutdownOpenTelemetry();
+    } catch (error) {
+      log.error('Error shutting down OpenTelemetry SDK:', error);
+    }
+  };
+
+  process.once('beforeExit', () => {
+    void shutdown();
+  });
+}

package/src/telemetry/tracer.ts

@@ -0,0 +1,75 @@
+/**
+ * Shared tracer helpers for appium-mcp instrumentation. Tool, prompt, and
+ * resource wrappers use this module so span creation, exception recording, and
+ * disabled-telemetry behavior stay consistent across MCP operation types.
+ */
+
+import {
+  context,
+  SpanKind,
+  SpanStatusCode,
+  trace,
+  type Attributes,
+} from '@opentelemetry/api';
+
+import { isTelemetryEnabled } from './attributes.js';
+
+const TRACER_NAME = 'appium-mcp';
+
+/**
+ * Gets the OpenTelemetry tracer for appium-mcp. This is used by tool, prompt,
+ * and resource wrappers to create spans with a consistent name and configuration.
+ * @returns The OpenTelemetry tracer for appium-mcp.
+ */
+export function getAppiumMcpTracer() {
+  return trace.getTracer(TRACER_NAME);
+}
+
+/**
+ * Gets the currently active OpenTelemetry span from the context. This is used by
+ * tool, prompt, and resource wrappers to add attributes or record exceptions on the
+ * active span without needing to pass the span object through multiple layers of calls.
+ * @returns The currently active OpenTelemetry span, or undefined if there is no active span.
+ */
+export function getActiveSpan() {
+  return trace.getActiveSpan();
+}
+
+/**
+ * Runs the given asynchronous operation within a new OpenTelemetry span with the specified name and attributes.
+ * If telemetry is not enabled, the operation is run without creating a span.
+ * If the operation throws an error, the error is recorded on the span and re-thrown.
+ * @param name The name of the span.
+ * @param attributes The attributes to set on the span.
+ * @param operation The asynchronous operation to run within the span.
+ * @returns The result of the asynchronous operation.
+ */
+export async function withSpan<T>(
+  name: string,
+  attributes: Attributes,
+  operation: () => Promise<T>
+): Promise<T> {
+  if (!isTelemetryEnabled()) {
+    return operation();
+  }
+
+  const span = getAppiumMcpTracer().startSpan(name, {
+    attributes,
+    kind: SpanKind.INTERNAL,
+  });
+
+  try {
+    return await context.with(trace.setSpan(context.active(), span), operation);
+  } catch (error) {
+    span.recordException(error as Error);
+    span.setStatus({
+      code: SpanStatusCode.ERROR,
+      message: error instanceof Error ? error.message : String(error),
+    });
+    throw error;
+  } finally {
+    span.end();
+  }
+}
+
+export { SpanStatusCode };

package/src/telemetry/wrapOperations.ts

@@ -0,0 +1,245 @@
+/**
+ * FastMCP operation wrappers that create spans around registered MCP handlers.
+ * Installing these wrappers before built-in and plugin registration covers
+ * tools, prompts, resources, and resource templates without changing handler
+ * return values or recording sensitive request/response payloads.
+ */
+
+import type { FastMCP } from 'fastmcp';
+
+import {
+  isArgumentValueTelemetryEnabled,
+  safeAttributeValue,
+  safeInputKeys,
+  safeSessionId,
+} from './attributes.js';
+import { getActiveSpan, SpanStatusCode, withSpan } from './tracer.js';
+import { isSensitiveKey } from '../utils/sensitive.js';
+
+type ToolDef = Parameters<FastMCP['addTool']>[0];
+type PromptDef = Parameters<FastMCP['addPrompt']>[0];
+type ResourceDef = Parameters<FastMCP['addResource']>[0];
+type ResourceTemplateDef = Parameters<FastMCP['addResourceTemplate']>[0];
+
+type ToolExecute = NonNullable<ToolDef['execute']>;
+type PromptLoad = NonNullable<PromptDef['load']>;
+type ResourceLoad = NonNullable<ResourceDef['load']>;
+type ResourceTemplateLoad = NonNullable<ResourceTemplateDef['load']>;
+
+/**
+ * Installs telemetry wrappers on the given FastMCP server instance. This should be
+ * called early in the server setup process, before registering any tools, prompts,
+ * or resources, to ensure that all operations are wrapped with OpenTelemetry spans.
+ * Each span will be named according to the operation type and include attributes
+ * such as tool name, prompt name, resource URI, session ID, and input keys, while
+ * avoiding any sensitive information.
+ * @param server The FastMCP server instance on which to install telemetry wrappers.
+ */
+export function installTelemetryWrappers(server: FastMCP): void {
+  const originalAddTool = server.addTool.bind(server) as FastMCP['addTool'];
+
+  server.addTool = ((toolDef: ToolDef) =>
+    originalAddTool(wrapToolWithTelemetry(toolDef))) as FastMCP['addTool'];
+
+  if (typeof server.addPrompt === 'function') {
+    const originalAddPrompt = server.addPrompt.bind(
+      server
+    ) as FastMCP['addPrompt'];
+    server.addPrompt = ((promptDef: PromptDef) =>
+      originalAddPrompt(
+        wrapPromptWithTelemetry(promptDef)
+      )) as FastMCP['addPrompt'];
+  }
+
+  if (typeof server.addResource === 'function') {
+    const originalAddResource = server.addResource.bind(
+      server
+    ) as FastMCP['addResource'];
+    server.addResource = ((resourceDef: ResourceDef) =>
+      originalAddResource(
+        wrapResourceWithTelemetry(resourceDef)
+      )) as FastMCP['addResource'];
+  }
+
+  if (typeof server.addResourceTemplate === 'function') {
+    const originalAddResourceTemplate = server.addResourceTemplate.bind(
+      server
+    ) as FastMCP['addResourceTemplate'];
+    server.addResourceTemplate = ((resourceTemplateDef: ResourceTemplateDef) =>
+      originalAddResourceTemplate(
+        wrapResourceTemplateWithTelemetry(resourceTemplateDef)
+      )) as FastMCP['addResourceTemplate'];
+  }
+}
+
+/**
+ * Wraps a tool definition with telemetry spans around its execute function.
+ * The span will be named "tools/call {toolName}" and include attributes for the tool name,
+ * session ID (if available), and input keys. If the tool execution results in an error,
+ * the span status will be set to error and an attribute will indicate that the result is an error.
+ * @param toolDef The original tool definition to wrap.
+ * @returns A new tool definition with telemetry spans around the execute function.
+ */
+export function wrapToolWithTelemetry(toolDef: ToolDef): ToolDef {
+  const execute = toolDef.execute as ToolExecute | undefined;
+  if (!execute) {
+    return toolDef;
+  }
+
+  const toolName = toolDef.name ?? 'unknown_tool';
+
+  return {
+    ...toolDef,
+    execute: async (args, context) =>
+      withSpan(
+        `tools/call ${toolName}`,
+        toolAttributes(toolName, args),
+        async () => {
+          const result = await execute(args, context);
+          if (isErrorResult(result)) {
+            getActiveSpan()?.setStatus({ code: SpanStatusCode.ERROR });
+            getActiveSpan()?.setAttribute('mcp.tool.result.is_error', true);
+          }
+          return result;
+        }
+      ),
+  };
+}
+
+export function safeInputValueAttributes(
+  args: unknown
+): Record<string, string | number | boolean | string[]> {
+  if (!isArgumentValueTelemetryEnabled()) {
+    return {};
+  }
+  if (!args || typeof args !== 'object' || Array.isArray(args)) {
+    return {};
+  }
+
+  const attributes: Record<string, string | number | boolean | string[]> = {};
+
+  for (const [key, value] of Object.entries(args)) {
+    // do not include sensitive keys as attributes, and avoid logging large strings or buffers
+    if (isSensitiveKey(key)) {
+      continue;
+    }
+    attributes[`mcp.input.value.${key}`] = safeAttributeValue(value);
+  }
+
+  return attributes;
+}
+
+/**
+ * Wraps a prompt definition with telemetry spans around its load function.
+ * The span will be named "prompts/get {promptName}" and include attributes for the prompt name
+ * and input keys. If the prompt load results in an error, the span status will be set to error
+ * and an attribute will indicate that the result is an error.
+ * @param promptDef The original prompt definition to wrap.
+ * @returns A new prompt definition with telemetry spans around the load function.
+ */
+function wrapPromptWithTelemetry(promptDef: PromptDef): PromptDef {
+  const load = promptDef.load as PromptLoad | undefined;
+  if (!load) {
+    return promptDef;
+  }
+
+  const promptName = promptDef.name ?? 'unknown_prompt';
+
+  return {
+    ...promptDef,
+    load: async (args, auth) =>
+      withSpan(
+        `prompts/get ${promptName}`,
+        {
+          'mcp.prompt.name': promptName,
+          ...inputAttributes(args),
+        },
+        () => load(args, auth)
+      ),
+  };
+}
+
+function wrapResourceWithTelemetry(resourceDef: ResourceDef): ResourceDef {
+  const load = resourceDef.load as ResourceLoad | undefined;
+  if (!load) {
+    return resourceDef;
+  }
+
+  const uri = resourceDef.uri ?? 'unknown_resource';
+
+  return {
+    ...resourceDef,
+    load: async () =>
+      withSpan(
+        'resources/read',
+        {
+          'mcp.resource.uri': uri,
+        },
+        () => load()
+      ),
+  };
+}
+
+function wrapResourceTemplateWithTelemetry(
+  resourceTemplateDef: ResourceTemplateDef
+): ResourceTemplateDef {
+  const load = resourceTemplateDef.load as ResourceTemplateLoad | undefined;
+  if (!load) {
+    return resourceTemplateDef;
+  }
+
+  const uriTemplate =
+    resourceTemplateDef.uriTemplate?.toString() ?? 'unknown_resource_template';
+
+  return {
+    ...resourceTemplateDef,
+    load: async (args, auth) =>
+      withSpan(
+        'resources/read',
+        {
+          'mcp.resource.uri_template': uriTemplate,
+          ...inputAttributes(args),
+        },
+        () => load(args, auth)
+      ),
+  };
+}
+
+function toolAttributes(toolName: string, args: unknown) {
+  const attributes: Record<string, string | string[]> = {
+    'mcp.tool.name': toolName,
+  };
+
+  const sessionId = safeSessionId(args);
+  if (sessionId) {
+    attributes['appium.session.id'] = sessionId;
+  }
+
+  return {
+    ...attributes,
+    ...inputAttributes(args),
+  };
+}
+
+function inputAttributes(
+  args: unknown
+): Record<string, string | number | boolean | string[]> {
+  return {
+    ...inputKeyAttributes(args),
+    ...safeInputValueAttributes(args),
+  };
+}
+
+function inputKeyAttributes(args: unknown): Record<string, string[]> {
+  const inputKeys = safeInputKeys(args);
+  return inputKeys.length > 0 ? { 'mcp.input.keys': inputKeys } : {};
+}
+
+function isErrorResult(result: unknown): boolean {
+  return (
+    !!result &&
+    typeof result === 'object' &&
+    'isError' in result &&
+    (result as { isError?: unknown }).isError === true
+  );
+}

package/src/tools/index.ts

@@ -14,6 +14,7 @@
  */
 import type { ContentResult, FastMCP } from 'fastmcp';
 import log from '../logger.js';
+import { isSensitiveKey } from '../utils/sensitive.js';
 import session from './session/session.js';
 import generateLocators from './test-generation/locators.js';
 import selectDevice from './session/select-device.js';
@@ -59,16 +60,6 @@ export default function registerTools(server: FastMCP): void {
     if (typeof originalExecute !== 'function') {
       return originalAddTool(toolDef);
     }
-    const SENSITIVE_KEYS = [
-      'password',
-      'token',
-      'accesstoken',
-      'authorization',
-      'apikey',
-      'secret',
-      'clientsecret',
-      'remoteserverurl',
-    ];
     const redactArgs = (obj: unknown): unknown => {
       if (obj === undefined || obj === null) {
         return obj;
@@ -76,10 +67,7 @@ export default function registerTools(server: FastMCP): void {
       try {
         return JSON.parse(
           JSON.stringify(obj, (key, value) => {
-            if (
-              key &&
-              SENSITIVE_KEYS.some((k) => key.toLowerCase().includes(k))
-            ) {
+            if (key && isSensitiveKey(key)) {
               return '[REDACTED]';
             }
             // Avoid logging extremely large buffers/strings

package/src/tools/session/session.ts

@@ -93,16 +93,21 @@ export default function session(server: FastMCP): void {
     execute: async (args: z.infer<typeof schema>): Promise<any> => {
       try {
         // Parse capabilities: some LLMs (e.g. Gemini) pass a JSON string instead of an object.
-        const parsedCapabilities: Record<string, any> | undefined = (() => {
-          if (typeof args.capabilities === 'string') {
-            try {
-              return JSON.parse(args.capabilities) as Record<string, any>;
-            } catch {
-              return undefined;
-            }
+        let parsedCapabilities: Record<string, any> | undefined;
+        if (typeof args.capabilities === 'string') {
+          try {
+            parsedCapabilities = JSON.parse(args.capabilities) as Record<
+              string,
+              any
+            >;
+          } catch (err: unknown) {
+            return errorResult(
+              `Invalid capabilities JSON: ${toolErrorMessage(err)}`
+            );
           }
-          return args.capabilities;
-        })();
+        } else {
+          parsedCapabilities = args.capabilities;
+        }
 
         if (args.action === 'create') {
           if (!args.platform) {

package/src/utils/env.ts

@@ -0,0 +1,5 @@
+const TRUE_VALUES = new Set(['1', 'true', 'yes', 'on']);
+
+export function isTruthyEnvValue(value: string | undefined): boolean {
+  return TRUE_VALUES.has(value?.trim().toLowerCase() ?? '');
+}

package/src/utils/sensitive.ts

@@ -0,0 +1,30 @@
+const SENSITIVE_KEY_PARTS = [
+  'api_key',
+  'apikey',
+  'authorization',
+  'client_secret',
+  'clientsecret',
+  'credential',
+  'password',
+  'remote_server_url',
+  'remoteserverurl',
+  'secret',
+  'token',
+];
+
+/**
+ * Determines if a given key is considered sensitive based on whether it includes any of the defined sensitive key parts.
+ * The check is case-insensitive and ignores non-alphanumeric characters, so keys like "API-Key", "client secret", or "remote_server_url" would all be correctly identified as sensitive.
+ * @param key The key to check for sensitivity.
+ * @returns True if the key is considered sensitive, false otherwise.
+ */
+export function isSensitiveKey(key: string): boolean {
+  const normalized = normalizeKey(key);
+  return SENSITIVE_KEY_PARTS.some((part) =>
+    normalized.includes(normalizeKey(part))
+  );
+}
+
+function normalizeKey(key: string): string {
+  return key.replace(/[^a-zA-Z0-9]/g, '').toLowerCase();
+}