AndroidViewClient

This directory provides examples of untouched files generated by the CulebraTester2-public back-end. These examples demonstrate how the AI generates test scripts and assertions based on user interactions with Android applications.

Key examples include:

• Simple Interaction Tests: culebra-calculator-simple-test.py demonstrates a basic test flow (e.g., interacting with a Calculator app) and shows how the AI generates assert statements.
• Logical Screenshotting: culebra-clock-auto-regexp.py demonstrates how to capture logical screenshots that remain valid even when UI elements (like dates or times) change, by using regular expressions.

The CulebraTester2 MCP server is configured via JSON files that instruct Kiro (IDE or CLI) on how to communicate with the server. There are two configuration levels:

1. Workspace-Level Configuration: Located at .kiro/settings/mcp.json within your project workspace. Use this for project-specific settings or when developing the MCP server itself.
2. User-Level Configuration (Global): Located at ~/.kiro/settings/mcp.json in your home directory. Use this for kiro-cli or when you want the server available across all projects.

Priority: If both files exist, workspace-level settings override user-level settings for that specific workspace.

The MCP server is composed of three main parts:

1. CulebraTester2Client: A wrapper for the CulebraTester2 HTTP API.
2. ObjectStore: An in-memory storage system used to maintain references to UI elements.
3. MCP Tools: 20 specific tool handlers that provide the interface for AI assistants.

All tools follow a consistent JSON response format:

On Success:

{
  "success": true,
  "data": { ... }
}

On Error:

{
  "success": false,
  "error": "Error message"
}

Before using the MCP server, ensure your environment meets the following requirements and be aware of these known behaviors:

Requirements

• CulebraTester2 Version: Requires version v2.0.73 or higher.
• Python Version: Requires Python 3.9+ (specifically for the MCP server component).
• Active Connection: Requires an active CulebraTester2 server running on the target Android device.

Known Limitations

• Element Not Found: If an element cannot be found, the tool returns success: false with an error message. This is expected behavior.
• Error Handling: The server uses ApiException to distinguish between 404 (element not found) and other server errors.

Install the latest version of AndroidViewClient using pip3:

pip3 install androidviewclient --upgrade

To use the Model Context Protocol (MCP) server for AI-powered testing, install the androidviewclient package via pip. This provides the culebra-mcp command used to run the MCP server.

pip3 install androidviewclient --upgrade

The autoApprove list in your configuration allows specific tools to execute without requiring manual user confirmation in Kiro.

Security Recommendation: Only auto-approve read-only tools. Tools that modify device state (clicks, text entry, app management, hardware keys) should require manual approval to prevent unintended actions.

Recommended Safe Tools:

• getDeviceInfo (Screen dimensions)
• dumpUiHierarchy (UI element tree)
• takeScreenshot (Capture screen)
• getCurrentPackage (Current app package name)

{
  "autoApprove": [
    "getDeviceInfo",
    "dumpUiHierarchy",
    "takeScreenshot",
    "getCurrentPackage"
  ]
}

AndroidViewClient includes an MCP server that allows AI assistants (like Kiro) to interact with Android devices using natural language.

To set it up:

1. Install androidviewclient via pip3.
2. Ensure CulebraTester2 is running on your Android device.
3. Configure your AI assistant by adding the culebratester2 server to your MCP settings file (~/.kiro/settings/mcp.json or .kiro/settings/mcp.json).

Once configured, you can use natural language commands like "Launch the Calculator app" or "Find the button with text Submit and click it".

{
  "mcpServers": {
    "culebratester2": {
      "command": "culebra-mcp",
      "env": {
        "CULEBRATESTER2_URL": "http://localhost:9987"
      }
    }
  }
}

Follow these three steps to enable AI assistants to interact with your Android device:

1. Prepare the device: Install the APK and start the instrumentation service, then forward the TCP port.
2. Configure the AI assistant: Add the culebratester2 server configuration to your assistant's MCP settings file (e.g., .kiro/settings/mcp.json).
3. Run tests: Use natural language commands to interact with the device.

Step 1: Device Setup

adb install -r culebratester2.apk
adb shell am instrument -w com.dtmilano.android.culebratester2/.CulebraTester2Instrumentation
adb forward tcp:9987 tcp:9987

Step 2: Assistant Configuration

{
  "mcpServers": {
    "culebratester2": {
      "command": "culebra-mcp",
      "env": {
        "CULEBRATESTER2_URL": "http://localhost:9987"
      }
    }
  }
}

To troubleshoot connection issues, tool calls, or API responses, you can enable debug logging by setting the CULEBRATESTER2_DEBUG environment variable to 1.

Logs are sent to stderr to avoid interfering with the MCP protocol on stdout. Logs include:

• Server startup information
• Connection validation
• Tool calls with parameters
• API responses
• Error details

export CULEBRATESTER2_DEBUG=1

The following environment variables control the behavior of the CulebraTester2 MCP connection:

• CULEBRATESTER2_URL: Base URL for CulebraTester2 (default: http://localhost:9987)
• CULEBRATESTER2_TIMEOUT: HTTP timeout in seconds (default: 30)
• CULEBRATESTER2_DEBUG: Enable debug logging (set to 1, true, or yes)