androidviewclient 24.0.0__tar.gz → 25.0.0__tar.gz

androidviewclient-25.0.0/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.4
+Name: androidviewclient
+Version: 25.0.0
+Summary: AndroidViewClient is a 100% pure python library and tools
+Home-page: https://github.com/dtmilano/AndroidViewClient/
+Author: Diego Torres Milano
+Author-email: dtmilano@gmail.com
+License: Apache
+Keywords: android uiautomator viewclient monkeyrunner test automation mcp
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+License-File: LICENSE
+Requires-Dist: setuptools
+Requires-Dist: requests
+Requires-Dist: numpy
+Requires-Dist: matplotlib
+Requires-Dist: culebratester-client>=2.0.73
+Requires-Dist: mcp>=0.9.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: hypothesis>=6.0.0; extra == "dev"
+Requires-Dist: responses>=0.23.0; extra == "dev"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary

{androidviewclient-24.0.0 → androidviewclient-25.0.0}/README.md

@@ -39,6 +39,81 @@ pip3 install androidviewclient --upgrade
 ```
 Or check the wiki for more alternatives.
 
+# AI-Powered Testing with MCP
+
+**NEW!** AndroidViewClient now includes a Model Context Protocol (MCP) server that enables AI assistants like Kiro to interact with Android devices through natural language.
+
+## Quick Start with MCP
+
+1. **Install with MCP support:**
+   ```bash
+   pip3 install androidviewclient --upgrade
+   ```
+
+2. **Start CulebraTester2 on your device:**
+   
+   Check the details at [How to run CulebraTester2 ?](https://github.com/dtmilano/CulebraTester2-public?tab=readme-ov-file#how-to-run-culebratester2-)
+   
+
+4. **Configure your AI assistant:**
+   
+   Add to `.kiro/settings/mcp.json` or `~/.kiro/settings/mcp.json`:
+   ```json
+   {
+     "mcpServers": {
+       "culebratester2": {
+         "command": "culebra-mcp",
+         "env": {
+           "CULEBRATESTER2_URL": "http://localhost:9987"
+         }
+       }
+     }
+   }
+   ```
+
+5. **Start testing with natural language:**
+   - "Get the device screen size"
+   - "Launch the Calculator app"
+   - "Find the button with text Submit and click it"
+   - "Take a screenshot"
+   - "Swipe up to scroll"
+
+## MCP Tools Available
+
+The MCP server provides 20 tools for Android automation:
+
+**Element-based interactions:**
+- Find elements by text or resource ID
+- Click, long-click, enter text, clear text
+- Navigate with back/home buttons
+- Launch applications
+
+**Coordinate-based interactions:**
+- Click/long-click at coordinates
+- Swipe gestures
+
+**Device actions:**
+- Wake/sleep device
+- Get current app
+- Force stop apps
+- Take screenshots
+
+## Configuration
+
+For detailed MCP configuration options, see the [MCP Configuration Guide](docs/MCP_CONFIGURATION.md).
+
+Quick reference:
+- **User-level config** (kiro-cli): `~/.kiro/settings/mcp.json`
+- **Workspace config** (Kiro IDE): `.kiro/settings/mcp.json`
+- **Examples:** `examples/mcp_config.json`
+- **Usage examples:** `examples/test_calculator_mcp.py`
+
+## Environment Variables
+
+- `CULEBRATESTER2_URL`: Base URL for CulebraTester2 (default: `http://localhost:9987`)
+- `CULEBRATESTER2_TIMEOUT`: HTTP timeout in seconds (default: `30`)
+- `CULEBRATESTER2_DEBUG`: Enable debug logging (`1`, `true`, or `yes`)
+
 # Want to learn more?
 
 > 🚀 Check [Examples](https://github.com/dtmilano/AndroidViewClient/wiki/Resources#examples) and [Screencasts and videos](https://github.com/dtmilano/AndroidViewClient/wiki/Resources#screencasts-and-videos) page to see it in action.

{androidviewclient-24.0.0 → androidviewclient-25.0.0}/setup.py

@@ -3,14 +3,14 @@
 from setuptools import setup, find_packages
 
 setup(name='androidviewclient',
-      version='24.0.0',
+      version='25.0.0',
       description='''AndroidViewClient is a 100% pure python library and tools
         that simplifies test script creation providing higher level
         operations and the ability of obtaining the tree of Views present at
         any given moment on the device or emulator screen.
         ''',
       license='Apache',
-      keywords='android uiautomator viewclient monkeyrunner test automation',
+      keywords='android uiautomator viewclient monkeyrunner test automation mcp',
       author='Diego Torres Milano',
       author_email='dtmilano@gmail.com',
       url='https://github.com/dtmilano/AndroidViewClient/',
@@ -18,9 +18,34 @@ setup(name='androidviewclient',
       package_dir={'': 'src'},
       package_data={'': ['*.png']},
       include_package_data=True,
-      scripts=['tools/culebra', 'tools/dump'],
+      scripts=['tools/culebra', 'tools/dump', 'tools/culebra-mcp'],
+      entry_points={
+          'console_scripts': [
+              'culebra-mcp=com.dtmilano.android.mcp.server:main',
+          ],
+      },
+      python_requires='>=3.9',
       classifiers=['Development Status :: 5 - Production/Stable',
                    'Intended Audience :: Developers',
-                   'License :: OSI Approved :: Apache Software License'],
-      install_requires=['setuptools', 'requests', 'numpy', 'matplotlib', 'culebratester-client >= 2.0.70'],
+                   'License :: OSI Approved :: Apache Software License',
+                   'Programming Language :: Python :: 3.9',
+                   'Programming Language :: Python :: 3.10',
+                   'Programming Language :: Python :: 3.11',
+                   'Programming Language :: Python :: 3.12'],
+      install_requires=[
+          'setuptools',
+          'requests',
+          'numpy',
+          'matplotlib',
+          'culebratester-client >= 2.0.73',
+          'mcp >= 0.9.0',
+      ],
+      extras_require={
+          'dev': [
+              'pytest >= 7.0.0',
+              'pytest-asyncio >= 0.21.0',
+              'hypothesis >= 6.0.0',
+              'responses >= 0.23.0',
+          ],
+      },
       )

androidviewclient-25.0.0/src/androidviewclient.egg-info/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.4
+Name: androidviewclient
+Version: 25.0.0
+Summary: AndroidViewClient is a 100% pure python library and tools
+Home-page: https://github.com/dtmilano/AndroidViewClient/
+Author: Diego Torres Milano
+Author-email: dtmilano@gmail.com
+License: Apache
+Keywords: android uiautomator viewclient monkeyrunner test automation mcp
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+License-File: LICENSE
+Requires-Dist: setuptools
+Requires-Dist: requests
+Requires-Dist: numpy
+Requires-Dist: matplotlib
+Requires-Dist: culebratester-client>=2.0.73
+Requires-Dist: mcp>=0.9.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: hypothesis>=6.0.0; extra == "dev"
+Requires-Dist: responses>=0.23.0; extra == "dev"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary

{androidviewclient-24.0.0 → androidviewclient-25.0.0}/src/androidviewclient.egg-info/SOURCES.txt

@@ -4,6 +4,7 @@ setup.py
 src/androidviewclient.egg-info/PKG-INFO
 src/androidviewclient.egg-info/SOURCES.txt
 src/androidviewclient.egg-info/dependency_links.txt
+src/androidviewclient.egg-info/entry_points.txt
 src/androidviewclient.egg-info/requires.txt
 src/androidviewclient.egg-info/top_level.txt
 src/com/__init__.py
@@ -25,6 +26,10 @@ src/com/dtmilano/android/adb/androidkeymap.py
 src/com/dtmilano/android/adb/dumpsys.py
 src/com/dtmilano/android/kato/__init__.py
 src/com/dtmilano/android/kato/kato.py
+src/com/dtmilano/android/mcp/__init__.py
+src/com/dtmilano/android/mcp/object_store.py
+src/com/dtmilano/android/mcp/server.py
+src/com/dtmilano/android/mcp/tools.py
 src/com/dtmilano/android/robotframework/__init__.py
 src/com/dtmilano/android/robotframework/viewclientwrapper.py
 src/com/dtmilano/android/uiautomator/__init__.py
@@ -42,4 +47,5 @@ src/share/pixmaps/plugins/android/lib/device-art-resources/samsung_s4/port_back.
 src/share/pixmaps/plugins/android/lib/device-art-resources/samsung_s4/port_fore.png
 src/share/pixmaps/plugins/android/lib/device-art-resources/samsung_s4/port_shadow.png
 tools/culebra
+tools/culebra-mcp
 tools/dump

androidviewclient-25.0.0/src/androidviewclient.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+culebra-mcp = com.dtmilano.android.mcp.server:main

androidviewclient-25.0.0/src/androidviewclient.egg-info/requires.txt

@@ -0,0 +1,12 @@
+setuptools
+requests
+numpy
+matplotlib
+culebratester-client>=2.0.73
+mcp>=0.9.0
+
+[dev]
+pytest>=7.0.0
+pytest-asyncio>=0.21.0
+hypothesis>=6.0.0
+responses>=0.23.0

{androidviewclient-24.0.0 → androidviewclient-25.0.0}/src/com/dtmilano/android/adb/adbclient.py

@@ -27,7 +27,7 @@ from typing import Optional
 
 from com.dtmilano.android.adb.dumpsys import Dumpsys
 
-__version__ = '24.0.0'
+__version__ = '25.0.0'
 
 import sys
 import warnings

{androidviewclient-24.0.0 → androidviewclient-25.0.0}/src/com/dtmilano/android/adb/dumpsys.py

@@ -23,7 +23,7 @@ import re
 import sys
 from _warnings import warn
 
-__version__ = '24.0.0'
+__version__ = '25.0.0'
 
 DEBUG = False
 

{androidviewclient-24.0.0 → androidviewclient-25.0.0}/src/com/dtmilano/android/code_generator.py

@@ -3,7 +3,7 @@ import textwrap
 from abc import ABC
 from datetime import date
 
-__version__ = '24.0.0'
+__version__ = '25.0.0'
 
 from typing import TextIO, Union, Dict, List
 

{androidviewclient-24.0.0 → androidviewclient-25.0.0}/src/com/dtmilano/android/common.py

@@ -20,7 +20,7 @@ limitations under the License.
 
 from __future__ import print_function
 
-__version__ = '24.0.0'
+__version__ = '25.0.0'
 
 import ast
 import os

{androidviewclient-24.0.0 → androidviewclient-25.0.0}/src/com/dtmilano/android/concertina.py

@@ -22,7 +22,7 @@ import json
 import random
 
 __author__ = 'diego'
-__version__ = '24.0.0'
+__version__ = '25.0.0'
 
 DEBUG = True
 

{androidviewclient-24.0.0 → androidviewclient-25.0.0}/src/com/dtmilano/android/controlpanel.py

@@ -20,7 +20,7 @@
     '''
 import platform
 
-__version__ = '24.0.0'
+__version__ = '25.0.0'
 
 import tkinter
 import tkinter.ttk

{androidviewclient-24.0.0 → androidviewclient-25.0.0}/src/com/dtmilano/android/culebron.py

@@ -38,7 +38,7 @@ from com.dtmilano.android.keyevent import KEY_EVENT
 from com.dtmilano.android.uiautomator.uiautomatorhelper import UiAutomatorHelper
 from com.dtmilano.android.viewclient import ViewClient, View, VERSION_SDK_PROPERTY
 
-__version__ = '24.0.0'
+__version__ = '25.0.0'
 
 import sys
 import threading
@@ -240,13 +240,8 @@ On Ubuntu install
 
    $ sudo apt-get install python-imaging python-imaging-tk
 
-On OSX install
+On macOS install
 
-   $ brew install homebrew/python/pillow
-
-or, preferred since El Capitan
-
-   $ sudo easy_install pip
    $ sudo pip install pillow
 
 ''')

androidviewclient-25.0.0/src/com/dtmilano/android/mcp/__init__.py

@@ -0,0 +1,33 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+AndroidViewClient MCP Server Module
+
+This module provides a Model Context Protocol (MCP) server that exposes
+CulebraTester2 functionality to AI assistants, enabling AI-powered Android
+test automation.
+
+The MCP server acts as a bridge between MCP-compatible AI tools (like Kiro)
+and Android devices running the CulebraTester2 service.
+
+Example usage:
+    # Start the MCP server
+    $ culebra-mcp
+
+    # Or with custom URL
+    $ culebra-mcp --url http://192.168.1.100:9987
+
+For more information, see:
+    https://github.com/dtmilano/AndroidViewClient/
+"""
+
+__version__ = '25.0.0'
+__author__ = 'Diego Torres Milano'
+__email__ = 'dtmilano@gmail.com'
+
+__all__ = [
+    'server',
+    'client',
+    'object_store',
+    'tools',
+]

androidviewclient-25.0.0/src/com/dtmilano/android/mcp/object_store.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Object Store for MCP Server
+
+This module provides an in-memory storage mechanism for UI element references
+returned by CulebraTester2 find operations. The object store allows MCP tools
+to cache and reuse object identifiers across multiple operations.
+
+Copyright (C) 2012-2024  Diego Torres Milano
+Created on 2024-12-20 by Culebra
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
+from typing import Dict, Any, Optional
+
+__version__ = '25.0.0'
+
+
+class ObjectStore:
+    """
+    In-memory storage for UI element references.
+    
+    The ObjectStore maintains a mapping between object IDs (returned by
+    CulebraTester2) and metadata about those objects (such as the selector
+    used to find them). This allows MCP tools to validate object IDs before
+    performing operations and to retrieve information about cached objects.
+    
+    Example:
+        >>> store = ObjectStore()
+        >>> store.store(123, {"selector": {"text": "Login"}, "type": "text"})
+        >>> store.exists(123)
+        True
+        >>> store.get(123)
+        {'selector': {'text': 'Login'}, 'type': 'text'}
+        >>> store.remove(123)
+        >>> store.exists(123)
+        False
+    """
+    
+    def __init__(self):
+        """Initialize an empty object store."""
+        self._objects: Dict[int, Dict[str, Any]] = {}
+    
+    def store(self, oid: int, metadata: Dict[str, Any]) -> None:
+        """
+        Store an object reference with associated metadata.
+        
+        Args:
+            oid: The object ID returned by CulebraTester2
+            metadata: Dictionary containing information about the object,
+                     typically including the selector used to find it
+        
+        Example:
+            >>> store.store(456, {
+            ...     "selector": {"resourceId": "com.example:id/button"},
+            ...     "type": "resourceId"
+            ... })
+        """
+        self._objects[oid] = metadata
+    
+    def get(self, oid: int) -> Optional[Dict[str, Any]]:
+        """
+        Retrieve metadata for a stored object.
+        
+        Args:
+            oid: The object ID to look up
+        
+        Returns:
+            Dictionary containing the object's metadata, or None if the
+            object ID is not found in the store
+        
+        Example:
+            >>> metadata = store.get(456)
+            >>> if metadata:
+            ...     print(metadata['selector'])
+            {'resourceId': 'com.example:id/button'}
+        """
+        return self._objects.get(oid)
+    
+    def exists(self, oid: int) -> bool:
+        """
+        Check if an object ID exists in the store.
+        
+        Args:
+            oid: The object ID to check
+        
+        Returns:
+            True if the object ID exists, False otherwise
+        
+        Example:
+            >>> if store.exists(456):
+            ...     print("Object found")
+            Object found
+        """
+        return oid in self._objects
+    
+    def remove(self, oid: int) -> None:
+        """
+        Remove an object from the store.
+        
+        This method is idempotent - removing a non-existent object ID
+        does not raise an error.
+        
+        Args:
+            oid: The object ID to remove
+        
+        Example:
+            >>> store.remove(456)
+            >>> store.exists(456)
+            False
+        """
+        if oid in self._objects:
+            del self._objects[oid]
+    
+    def clear(self) -> None:
+        """
+        Clear all objects from the store.
+        
+        This removes all cached object references, effectively resetting
+        the store to its initial empty state.
+        
+        Example:
+            >>> store.clear()
+            >>> len(store._objects)
+            0
+        """
+        self._objects.clear()

androidviewclient-25.0.0/src/com/dtmilano/android/mcp/server.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+MCP Server Core for CulebraTester2
+
+This module implements the main MCP server that exposes CulebraTester2
+functionality to AI assistants via the Model Context Protocol.
+
+Copyright (C) 2012-2024  Diego Torres Milano
+Created on 2024-12-20 by Culebra
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
+import os
+import sys
+import logging
+from mcp.server import FastMCP
+
+from culebratester_client import ApiClient, Configuration
+from culebratester_client.api import DefaultApi
+from com.dtmilano.android.mcp.object_store import ObjectStore
+
+__version__ = '25.0.0'
+
+# Configure logging
+DEBUG = os.environ.get('CULEBRATESTER2_DEBUG', '').lower() in ('1', 'true', 'yes')
+logging.basicConfig(
+    level=logging.DEBUG if DEBUG else logging.INFO,
+    format='[%(asctime)s] %(levelname)s [%(name)s] %(message)s',
+    stream=sys.stderr
+)
+logger = logging.getLogger('culebratester2-mcp')
+
+# Get configuration from environment variables
+BASE_URL = os.environ.get('CULEBRATESTER2_URL', 'http://localhost:9987')
+TIMEOUT = int(os.environ.get('CULEBRATESTER2_TIMEOUT', '30'))
+
+logger.info("Starting CulebraTester2 MCP Server")
+logger.info("  Base URL: {}".format(BASE_URL))
+logger.info("  Timeout: {}s".format(TIMEOUT))
+logger.info("  Debug mode: {}".format(DEBUG))
+
+# Create FastMCP server instance
+mcp = FastMCP(
+    name="culebratester2-mcp-server",
+    instructions="MCP server for Android UI automation using CulebraTester2. "
+                 "Provides tools to interact with Android devices through the CulebraTester2 backend."
+)
+
+# Initialize official CulebraTester2 client
+# Note: The official client's OpenAPI spec doesn't include /v2 prefix in paths,
+# so we add it to the host URL
+configuration = Configuration()
+configuration.host = "{}/v2".format(BASE_URL)
+api_client = ApiClient(configuration)
+api_client.rest_client.pool_manager.connection_pool_kw['timeout'] = TIMEOUT
+client = DefaultApi(api_client)
+
+# Initialize object store (shared across all tool calls)
+objectStore = ObjectStore()
+
+
+def validateConnection():
+    """Validate connection to CulebraTester2 server."""
+    try:
+        logger.debug("Validating connection to CulebraTester2...")
+        # Use the info endpoint to check service health and version
+        info = client.culebra_info_get()
+        logger.info("Connected to CulebraTester2 at {}".format(BASE_URL))
+        logger.info("  Version: {} (code: {})".format(
+            info.version_name if hasattr(info, 'version_name') else 'unknown',
+            info.version_code if hasattr(info, 'version_code') else 'unknown'
+        ))
+        print("Connected to CulebraTester2 at {}".format(BASE_URL), file=sys.stderr)
+        print("  Version: {} (code: {})".format(
+            info.version_name if hasattr(info, 'version_name') else 'unknown',
+            info.version_code if hasattr(info, 'version_code') else 'unknown'
+        ), file=sys.stderr)
+        return True
+    except Exception as e:
+        logger.error("Could not connect to CulebraTester2 at {}: {}".format(BASE_URL, e))
+        print("Warning: Could not connect to CulebraTester2 at {}: {}".format(BASE_URL, e), file=sys.stderr)
+        print("Server will start but tools may fail until connection is established.", file=sys.stderr)
+        return False
+
+
+# Import tools after mcp instance is created (tools will register themselves)
+from com.dtmilano.android.mcp import tools  # noqa: F401, E402
+
+
+def main():
+    """Main entry point for the MCP server."""
+    logger.info("Initializing MCP server...")
+    validateConnection()
+    logger.info("MCP server ready, starting event loop...")
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()