Specter MCP

Instructions

Implementation Reference

• src/tools/navigation/deep-link-navigate.ts:70-109 (handler)

  The core handler function `deepLinkNavigate` that validates input arguments and delegates to platform-specific deep link navigation functions.

  export async function deepLinkNavigate(args: DeepLinkNavigateArgs): Promise<DeepLinkResult> {
    const {
      uri,
      platform,
      deviceId,
      packageName,
      bundleId,
      waitAfterMs = 1000,
      extras,
      timeoutMs = 15000,
    } = args;
  
    // Validate platform
    if (!isPlatform(platform)) {
      throw Errors.invalidArguments(`Invalid platform: ${platform}. Must be 'android' or 'ios'`);
    }
  
    // Validate URI
    if (!uri || uri.trim().length === 0) {
      throw Errors.invalidArguments('URI is required');
    }
  
    // Route to platform-specific handler
    if (platform === 'android') {
      return navigateAndroid(uri, {
        deviceId,
        packageName,
        extras,
        timeoutMs,
        waitAfterMs,
      });
    } else {
      return navigateIOS(uri, {
        deviceId,
        bundleId,
        timeoutMs,
        waitAfterMs,
      });
    }
  }

• src/tools/navigation/deep-link-navigate.ts:22-43 (schema)

  TypeScript interface defining the input arguments (schema) for the `deep_link_navigate` tool.

  export interface DeepLinkNavigateArgs {
    /** Deep link URI to navigate to */
    uri: string;
    /** Target platform */
    platform: string;
    /** Device ID (optional, uses first available) */
    deviceId?: string;
    /** Package name for Android (helps target specific app) */
    packageName?: string;
    /** Bundle ID for iOS (helps target specific app) */
    bundleId?: string;
    /** Wait time after navigation in milliseconds */
    waitAfterMs?: number;
    /** Intent extras for Android deep links */
    extras?: Array<{
      type: 'string' | 'int' | 'boolean';
      key: string;
      value: string | number | boolean;
    }>;
    /** Timeout in milliseconds */
    timeoutMs?: number;
  }

• src/tools/navigation/deep-link-navigate.ts:259-315 (registration)

  Tool registration function that registers `deep_link_navigate` with the global tool registry, including JSON schema and wrapped handler.

  export function registerDeepLinkNavigateTool(): void {
    getToolRegistry().register(
      'deep_link_navigate',
      {
        description:
          'Navigate to a specific screen in the app using a deep link or Universal Link. ' +
          'Supports custom URL schemes (myapp://path) and HTTPS URLs for App Links/Universal Links.',
        inputSchema: createInputSchema(
          {
            uri: {
              type: 'string',
              description:
                'Deep link URI to navigate to (e.g., myapp://home/profile or https://example.com/app/products/123)',
            },
            platform: {
              type: 'string',
              enum: ['android', 'ios'],
              description: 'Target platform',
            },
            deviceId: {
              type: 'string',
              description:
                'Device ID (optional, uses first available). For Android: emulator-5554. For iOS: UDID or "booted"',
            },
            packageName: {
              type: 'string',
              description: 'Android package name to target specific app (e.g., com.example.myapp)',
            },
            bundleId: {
              type: 'string',
              description: 'iOS bundle ID to target specific app (e.g., com.example.myapp)',
            },
            waitAfterMs: {
              type: 'number',
              description: 'Time to wait after navigation in milliseconds (default: 1000)',
            },
            extras: {
              type: 'array',
              description: 'Android intent extras to pass with the deep link',
            },
            timeoutMs: {
              type: 'number',
              description: 'Timeout in milliseconds (default: 15000)',
            },
          },
          ['uri', 'platform']
        ),
      },
      async (args) => {
        const result = await deepLinkNavigate(args as unknown as DeepLinkNavigateArgs);
        return {
          ...result,
          formattedOutput: formatNavigationResult(result),
        };
      }
    );
  }

• src/tools/register.ts:161-163 (registration)

  Global invocation of the tool registration during server startup in `registerAllTools()`.

  const { registerDeepLinkNavigateTool } = await import('./navigation/deep-link-navigate.js');
  
  registerDeepLinkNavigateTool();

• src/tools/navigation/deep-link-navigate.ts:172-211 (helper)

  Platform-specific helper for iOS deep link navigation (similar Android helper exists).

  async function navigateIOS(
    uri: string,
    options: {
      deviceId?: string;
      bundleId?: string;
      timeoutMs: number;
      waitAfterMs: number;
    }
  ): Promise<DeepLinkResult> {
    const startTime = Date.now();
  
    // Validate URI format
    if (!isValidIOSUri(uri)) {
      return {
        success: false,
        platform: 'ios',
        uri,
        error: 'Invalid URI format. Must be scheme://path or https://domain/path',
        durationMs: Date.now() - startTime,
      };
    }
  
    // Open deep link
    const result = await openIOSDeepLink(uri, {
      deviceId: options.deviceId || 'booted',
      timeoutMs: options.timeoutMs,
      waitAfterMs: options.waitAfterMs,
    });
  
    return {
      success: result.success,
      platform: 'ios',
      uri: result.uri,
      deviceId: result.deviceId,
      deviceName: result.deviceName,
      details: result.details,
      error: result.error,
      durationMs: Date.now() - startTime,
    };
  }