androidviewclient 24.1.0__tar.gz → 25.0.1__tar.gz

androidviewclient-25.0.1/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.4
+Name: androidviewclient
+Version: 25.0.1
+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<2,>=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.1.0 → androidviewclient-25.0.1}/README.md

@@ -39,6 +39,92 @@ 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 Claude Code and 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-)
+
+3. **Configure your AI assistant:**
+
+   **Claude Code** — register the server with one command:
+   ```bash
+   claude mcp add culebratester2 --env CULEBRATESTER2_URL=http://localhost:9987 -- culebra-mcp
+   ```
+
+   Or add it to `.mcp.json` in your project root, so everyone who clones the project gets it:
+   ```json
+   {
+     "mcpServers": {
+       "culebratester2": {
+         "command": "culebra-mcp",
+         "env": {
+           "CULEBRATESTER2_URL": "http://localhost:9987"
+         }
+       }
+     }
+   }
+   ```
+
+   **Kiro** — add the same entry to `.kiro/settings/mcp.json` or `~/.kiro/settings/mcp.json`.
+
+4. **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:
+
+| | Claude Code | Kiro |
+|---|---|---|
+| **Project config** | `.mcp.json` (repository root) | `.kiro/settings/mcp.json` |
+| **User config** | `~/.claude.json` (via `claude mcp add --scope user`) | `~/.kiro/settings/mcp.json` |
+| **Tool pre-approval** | `permissions.allow` in `.claude/settings.json` | `autoApprove` in the server entry |
+| **Example** | `examples/mcp_config.json` | `examples/mcp_config_kiro.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-25.0.1/setup.py

@@ -0,0 +1,53 @@
+#!/usr/bin/env python
+
+from setuptools import setup, find_packages
+
+setup(name='androidviewclient',
+      version='25.0.1',
+      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 mcp',
+      author='Diego Torres Milano',
+      author_email='dtmilano@gmail.com',
+      url='https://github.com/dtmilano/AndroidViewClient/',
+      packages=find_packages('src'),
+      package_dir={'': 'src'},
+      package_data={'': ['*.png']},
+      include_package_data=True,
+      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',
+                   '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 2.x renamed FastMCP to MCPServer and changed other APIs;
+          # com.dtmilano.android.mcp.server still uses the v1 API.
+          'mcp >= 0.9.0, < 2',
+      ],
+      extras_require={
+          'dev': [
+              'pytest >= 7.0.0',
+              'pytest-asyncio >= 0.21.0',
+              'hypothesis >= 6.0.0',
+              'responses >= 0.23.0',
+          ],
+      },
+      )

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

@@ -0,0 +1,40 @@
+Metadata-Version: 2.4
+Name: androidviewclient
+Version: 25.0.1
+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<2,>=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.1.0 → androidviewclient-25.0.1}/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.1/src/androidviewclient.egg-info/entry_points.txt

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

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

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

{androidviewclient-24.1.0 → androidviewclient-25.0.1}/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.1.0'
+__version__ = '25.0.1'
 
 import sys
 import warnings

{androidviewclient-24.1.0 → androidviewclient-25.0.1}/src/com/dtmilano/android/adb/dumpsys.py

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

{androidviewclient-24.1.0 → androidviewclient-25.0.1}/src/com/dtmilano/android/code_generator.py

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

{androidviewclient-24.1.0 → androidviewclient-25.0.1}/src/com/dtmilano/android/common.py

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

{androidviewclient-24.1.0 → androidviewclient-25.0.1}/src/com/dtmilano/android/concertina.py

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

{androidviewclient-24.1.0 → androidviewclient-25.0.1}/src/com/dtmilano/android/controlpanel.py

@@ -20,7 +20,7 @@
     '''
 import platform
 
-__version__ = '24.1.0'
+__version__ = '25.0.1'
 
 import tkinter
 import tkinter.ttk

{androidviewclient-24.1.0 → androidviewclient-25.0.1}/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.1.0'
+__version__ = '25.0.1'
 
 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.1/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.1'
+__author__ = 'Diego Torres Milano'
+__email__ = 'dtmilano@gmail.com'
+
+__all__ = [
+    'server',
+    'client',
+    'object_store',
+    'tools',
+]

androidviewclient-25.0.1/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.1'
+
+
+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.1/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.1'
+
+# 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()