mcp-appium 0.1.0__tar.gz

mcp_appium-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+__pycache__/
+*.py[cod]
+
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+
+# Les capabilities décrivent une application et un appareil précis : elles
+# n'ont rien à faire dans un dépôt public. L'exemple vit dans examples/.
+/appium-caps.json

mcp_appium-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Julien Becheny
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_appium-0.1.0/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.5
+Name: mcp-appium
+Version: 0.1.0
+Summary: Serveur MCP qui donne à un assistant les éléments réels d'une application Appium, au lieu de le laisser les inventer.
+Project-URL: Homepage, https://github.com/julien-becheny/mcp-appium
+Project-URL: Issues, https://github.com/julien-becheny/mcp-appium/issues
+Author: Julien Becheny
+License: MIT
+License-File: LICENSE
+Keywords: android,appium,ios,llm,mcp,mobile-testing,test-automation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: appium-python-client>=3.0.0
+Requires-Dist: lxml>=4.9.0
+Requires-Dist: mcp>=2.0.0
+Requires-Dist: requests>=2.28.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.5.0; extra == 'dev'
+Provides-Extra: image
+Requires-Dist: pillow>=10.0.0; extra == 'image'
+Description-Content-Type: text/markdown
+
+# mcp-appium
+
+Un assistant qui écrit des tests mobiles invente des sélecteurs. Il propose
+`accessibility_id=bouton_valider` parce que c'est ce qu'un développeur aurait
+écrit, et le test échoue parce que l'application expose autre chose.
+
+Ce serveur MCP lui donne **l'écran réel**.
+
+```
+pip install mcp-appium
+```
+
+## Ce qu'il fait
+
+Onze outils, exposés à l'assistant via le Model Context Protocol :
+
+| Outil | Rôle |
+|---|---|
+| `connect_to_session` | Se rattache à une session Appium **déjà ouverte** |
+| `get_page_source` | L'arbre de l'écran, simplifié ou brut |
+| `find_elements` | Recherche par sélecteur ou par texte |
+| `suggest_locators` | Des sélecteurs qui existent, classés par robustesse |
+| `get_element_info` | Attributs, position, état d'un élément |
+| `screenshot` | L'écran, réduit avant envoi |
+| `tap_element` | Clic, avec vérification que l'écran a bougé |
+| `type_text` | Saisie dans un champ |
+| `go_back` | Retour arrière |
+| `get_session_info` | Plateforme, appareil, identifiant de session |
+| `close_session` | Libère l'appareil, **si ce serveur a ouvert la session** |
+
+Android, iOS, iPadOS et Windows.
+
+## Le cas courant : observer une session existante
+
+Un test tourne, il échoue sur un élément. Tu demandes à l'assistant ce que
+l'écran contient vraiment.
+
+```
+connect_to_session()
+```
+
+Sans argument, le serveur cherche une session active sur
+`http://127.0.0.1:4723` et s'y rattache. **Il ne crée rien, ne redémarre rien**,
+et aucune configuration n'est nécessaire.
+
+C'est le mode à privilégier : l'assistant voit exactement ce que le test voit,
+au moment où il le voit.
+
+## Créer une session
+
+Si aucune session n'existe, le serveur peut en ouvrir une. Il lui faut alors des
+capabilities, déclarées dans `appium-caps.json` à la racine de ton projet :
+
+```json
+{
+  "platformName": "Android",
+  "automationName": "UiAutomator2",
+  "appPackage": "com.exemple.app",
+  "appActivity": ".MainActivity"
+}
+```
+
+Les clés sont préfixées par `appium:` automatiquement quand il le faut.
+
+Plusieurs plateformes dans le même fichier :
+
+```json
+{
+  "android": { "platformName": "Android", "automationName": "UiAutomator2", "appPackage": "com.exemple.app" },
+  "ios":     { "platformName": "iOS", "automationName": "XCUITest", "bundleId": "com.exemple.app" }
+}
+```
+
+La variable `MCP_APPIUM_PLATFORM` choisit laquelle. À défaut, la première
+déclarée. Deux autres variables existent : `MCP_APPIUM_CAPS` pour passer le JSON
+directement, et `MCP_APPIUM_CAPS_FILE` pour désigner un autre fichier.
+
+## Déclarer le serveur
+
+Dans VS Code, `.vscode/mcp.json` :
+
+```json
+{
+  "servers": {
+    "appium": {
+      "type": "stdio",
+      "command": "mcp-appium"
+    }
+  }
+}
+```
+
+Le format est le même pour les autres clients MCP : une commande, transport
+standard.
+
+## Le parti pris qui compte : borner les sorties
+
+Un arbre de vue Appium brut dépasse couramment les cinquante mille caractères.
+Envoyé tel quel, il sature la fenêtre de contexte du modèle avant de lui avoir
+appris quoi que ce soit. Pire : ce qui entre dans le contexte y reste, et se
+repaie à chaque échange suivant de la conversation.
+
+Toutes les sorties sont donc plafonnées, et le serveur le dit quand il coupe :
+
+- arbre simplifié à 400 lignes, avec les seuls attributs qui servent à cibler ;
+- source brute à 40 000 caractères ;
+- 15 éléments détaillés au maximum dans une recherche ;
+- captures réduites à 1280 pixels de large.
+
+Un outil d'inspection qui ne borne pas ses sorties est inutilisable en
+conversation, quelle que soit la qualité de ce qu'il expose.
+
+## Deux autres partis pris
+
+**Un tap vérifie son effet.** `tap_element` compare l'écran avant et après, et
+signale explicitement un clic resté sans conséquence. Un élément désactivé ou
+recouvert répond à `click()` sans rien faire : sans cette vérification,
+l'assistant croit avoir avancé et enchaîne dans le vide.
+
+**Une session ne se ferme que si on l'a ouverte.** `close_session` libère
+l'appareil quand le serveur a créé la session, et se contente de s'en détacher
+sinon. Fermer la session d'un test en cours couperait ce test.
+
+**`suggest_locators` classe par robustesse.** L'identifiant d'accessibilité
+d'abord, le XPath sur le texte en dernier, avec la mention qu'il cassera au
+prochain changement de libellé.
+
+## Ce qu'il ne fait pas
+
+Il **n'écrit pas de tests** et n'impose aucun framework. Il expose l'état de
+l'application, l'assistant fait le reste avec les outils que tu utilises déjà.
+
+Il ne dépend d'**aucun service d'IA**. Ni clé d'API, ni compte, ni appel sortant :
+le seul réseau qu'il touche est ton serveur Appium local.
+
+Il ne **remplace pas Appium Inspector** pour l'exploration manuelle. Il sert à
+donner ces informations à un modèle, ce qu'une interface graphique ne sait pas
+faire.
+
+## Licence
+
+MIT.

mcp_appium-0.1.0/README.md

@@ -0,0 +1,142 @@
+# mcp-appium
+
+Un assistant qui écrit des tests mobiles invente des sélecteurs. Il propose
+`accessibility_id=bouton_valider` parce que c'est ce qu'un développeur aurait
+écrit, et le test échoue parce que l'application expose autre chose.
+
+Ce serveur MCP lui donne **l'écran réel**.
+
+```
+pip install mcp-appium
+```
+
+## Ce qu'il fait
+
+Onze outils, exposés à l'assistant via le Model Context Protocol :
+
+| Outil | Rôle |
+|---|---|
+| `connect_to_session` | Se rattache à une session Appium **déjà ouverte** |
+| `get_page_source` | L'arbre de l'écran, simplifié ou brut |
+| `find_elements` | Recherche par sélecteur ou par texte |
+| `suggest_locators` | Des sélecteurs qui existent, classés par robustesse |
+| `get_element_info` | Attributs, position, état d'un élément |
+| `screenshot` | L'écran, réduit avant envoi |
+| `tap_element` | Clic, avec vérification que l'écran a bougé |
+| `type_text` | Saisie dans un champ |
+| `go_back` | Retour arrière |
+| `get_session_info` | Plateforme, appareil, identifiant de session |
+| `close_session` | Libère l'appareil, **si ce serveur a ouvert la session** |
+
+Android, iOS, iPadOS et Windows.
+
+## Le cas courant : observer une session existante
+
+Un test tourne, il échoue sur un élément. Tu demandes à l'assistant ce que
+l'écran contient vraiment.
+
+```
+connect_to_session()
+```
+
+Sans argument, le serveur cherche une session active sur
+`http://127.0.0.1:4723` et s'y rattache. **Il ne crée rien, ne redémarre rien**,
+et aucune configuration n'est nécessaire.
+
+C'est le mode à privilégier : l'assistant voit exactement ce que le test voit,
+au moment où il le voit.
+
+## Créer une session
+
+Si aucune session n'existe, le serveur peut en ouvrir une. Il lui faut alors des
+capabilities, déclarées dans `appium-caps.json` à la racine de ton projet :
+
+```json
+{
+  "platformName": "Android",
+  "automationName": "UiAutomator2",
+  "appPackage": "com.exemple.app",
+  "appActivity": ".MainActivity"
+}
+```
+
+Les clés sont préfixées par `appium:` automatiquement quand il le faut.
+
+Plusieurs plateformes dans le même fichier :
+
+```json
+{
+  "android": { "platformName": "Android", "automationName": "UiAutomator2", "appPackage": "com.exemple.app" },
+  "ios":     { "platformName": "iOS", "automationName": "XCUITest", "bundleId": "com.exemple.app" }
+}
+```
+
+La variable `MCP_APPIUM_PLATFORM` choisit laquelle. À défaut, la première
+déclarée. Deux autres variables existent : `MCP_APPIUM_CAPS` pour passer le JSON
+directement, et `MCP_APPIUM_CAPS_FILE` pour désigner un autre fichier.
+
+## Déclarer le serveur
+
+Dans VS Code, `.vscode/mcp.json` :
+
+```json
+{
+  "servers": {
+    "appium": {
+      "type": "stdio",
+      "command": "mcp-appium"
+    }
+  }
+}
+```
+
+Le format est le même pour les autres clients MCP : une commande, transport
+standard.
+
+## Le parti pris qui compte : borner les sorties
+
+Un arbre de vue Appium brut dépasse couramment les cinquante mille caractères.
+Envoyé tel quel, il sature la fenêtre de contexte du modèle avant de lui avoir
+appris quoi que ce soit. Pire : ce qui entre dans le contexte y reste, et se
+repaie à chaque échange suivant de la conversation.
+
+Toutes les sorties sont donc plafonnées, et le serveur le dit quand il coupe :
+
+- arbre simplifié à 400 lignes, avec les seuls attributs qui servent à cibler ;
+- source brute à 40 000 caractères ;
+- 15 éléments détaillés au maximum dans une recherche ;
+- captures réduites à 1280 pixels de large.
+
+Un outil d'inspection qui ne borne pas ses sorties est inutilisable en
+conversation, quelle que soit la qualité de ce qu'il expose.
+
+## Deux autres partis pris
+
+**Un tap vérifie son effet.** `tap_element` compare l'écran avant et après, et
+signale explicitement un clic resté sans conséquence. Un élément désactivé ou
+recouvert répond à `click()` sans rien faire : sans cette vérification,
+l'assistant croit avoir avancé et enchaîne dans le vide.
+
+**Une session ne se ferme que si on l'a ouverte.** `close_session` libère
+l'appareil quand le serveur a créé la session, et se contente de s'en détacher
+sinon. Fermer la session d'un test en cours couperait ce test.
+
+**`suggest_locators` classe par robustesse.** L'identifiant d'accessibilité
+d'abord, le XPath sur le texte en dernier, avec la mention qu'il cassera au
+prochain changement de libellé.
+
+## Ce qu'il ne fait pas
+
+Il **n'écrit pas de tests** et n'impose aucun framework. Il expose l'état de
+l'application, l'assistant fait le reste avec les outils que tu utilises déjà.
+
+Il ne dépend d'**aucun service d'IA**. Ni clé d'API, ni compte, ni appel sortant :
+le seul réseau qu'il touche est ton serveur Appium local.
+
+Il ne **remplace pas Appium Inspector** pour l'exploration manuelle. Il sert à
+donner ces informations à un modèle, ce qu'une interface graphique ne sait pas
+faire.
+
+## Licence
+
+MIT.

mcp_appium-0.1.0/examples/appium-caps.json

@@ -0,0 +1,23 @@
+{
+  "android": {
+    "platformName": "Android",
+    "automationName": "UiAutomator2",
+    "appPackage": "com.exemple.app",
+    "appActivity": ".MainActivity",
+    "noReset": true,
+    "newCommandTimeout": 300
+  },
+  "ios": {
+    "platformName": "iOS",
+    "automationName": "XCUITest",
+    "bundleId": "com.exemple.app",
+    "udid": "00000000-0000000000000000",
+    "noReset": true,
+    "newCommandTimeout": 300
+  },
+  "windows": {
+    "platformName": "Windows",
+    "automationName": "Windows",
+    "app": "Root"
+  }
+}

mcp_appium-0.1.0/examples/essai_manuel.py

@@ -0,0 +1,51 @@
+"""Essai manuel du serveur contre un Appium réel. Hors suite de tests : il exige
+un appareil connecté et une application installée.
+
+    .venv\\Scripts\\python.exe essai_reel.py
+"""
+
+# Standard library
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent / "src"))
+
+# Local
+from mcp_appium import caps, server
+
+
+def titre(texte: str) -> None:
+    print(f"\n{'=' * 70}\n{texte}\n{'=' * 70}")
+
+
+titre("1. Chargement des capabilities")
+chargees = caps.load()
+print(f"{len(chargees)} capabilities, plateforme = {chargees.get('platformName')}")
+
+titre("2. Connexion")
+print(server.connect_to_session())
+
+titre("3. Session")
+print(server.get_session_info())
+
+titre("4. Arbre de l'ecran, simplifie")
+arbre = server.get_page_source()
+lignes = arbre.splitlines()
+print(f"{len(lignes)} lignes, {len(arbre)} caracteres")
+print("\n".join(lignes[:25]))
+
+titre("5. Suggestions de selecteurs")
+print(server.suggest_locators("E-mail")[:1200])
+
+titre("6. Recherche par texte")
+print(server.find_elements("E-mail")[:900])
+
+titre("7. Recherche par selecteur")
+print(server.find_elements("//android.widget.TextView")[:600])
+
+titre("8. Capture")
+image = server.screenshot()
+print(f"type={type(image).__name__}, {len(image.data)} octets")
+
+titre("9. Fermeture")
+print(server.close_session())

mcp_appium-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mcp-appium"
+version = "0.1.0"
+description = "Serveur MCP qui donne à un assistant les éléments réels d'une application Appium, au lieu de le laisser les inventer."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Julien Becheny" }]
+keywords = ["mcp", "appium", "test-automation", "mobile-testing", "android", "ios", "llm"]
+
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Testing",
+]
+
+dependencies = [
+    # SDK 2 : FastMCP y est devenu MCPServer, l'API 1.x ne convient pas.
+    "mcp>=2.0.0",
+    "Appium-Python-Client>=3.0.0",
+    "lxml>=4.9.0",
+    "requests>=2.28.0",
+]
+
+[project.optional-dependencies]
+# Réduction des captures avant envoi au modèle. Sans Pillow, l'image part
+# en pleine résolution : cela fonctionne, cela coûte plus de contexte.
+image = ["Pillow>=10.0.0"]
+dev = ["pytest>=7.0.0", "ruff>=0.5.0"]
+
+[project.scripts]
+mcp-appium = "mcp_appium.server:main"
+
+[project.urls]
+Homepage = "https://github.com/julien-becheny/mcp-appium"
+Issues = "https://github.com/julien-becheny/mcp-appium/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcp_appium"]
+
+[tool.ruff]
+line-length = 100

mcp_appium-0.1.0/src/mcp_appium/__init__.py

@@ -0,0 +1,8 @@
+"""Serveur MCP donnant à un assistant les éléments réels d'une application Appium.
+
+Volontairement vide : importer ce paquet ne doit pas charger Appium, lxml et le
+protocole MCP. Le serveur vit dans ``mcp_appium.server``, la configuration dans
+``mcp_appium.caps``, qui ne dépend que de la bibliothèque standard.
+"""
+
+__version__ = "0.1.0"

mcp_appium-0.1.0/src/mcp_appium/caps.py

@@ -0,0 +1,95 @@
+"""Chargement des capabilities Appium, pour la création de session.
+
+Le cas courant est le rattachement à une session déjà ouverte : aucune
+capability n'est alors nécessaire. Ce module ne sert qu'au cas inverse,
+quand le serveur doit démarrer la session lui-même.
+
+Trois sources, par ordre de priorité :
+
+1. la variable d'environnement ``MCP_APPIUM_CAPS``, qui contient un objet JSON ;
+2. le fichier désigné par ``MCP_APPIUM_CAPS_FILE`` ;
+3. ``appium-caps.json`` dans le répertoire courant.
+
+Le fichier peut décrire une plateforme unique, ou plusieurs indexées par nom.
+Dans le second cas, ``MCP_APPIUM_PLATFORM`` choisit laquelle, avec repli sur
+la première déclarée.
+"""
+
+# Standard library
+import json
+import os
+from pathlib import Path
+from typing import Optional
+
+DEFAULT_FILENAME = "appium-caps.json"
+
+# Une capability Appium est toujours préfixée, sauf les quelques clés W3C.
+_W3C_KEYS = {"platformName", "browserName", "browserVersion", "acceptInsecureCerts"}
+
+
+class CapabilitiesIntrouvables(RuntimeError):
+    """Aucune capability déclarée : la session ne peut pas être créée."""
+
+
+def _normalise(caps: dict) -> dict:
+    """Préfixe les clés non W3C par ``appium:``, comme l'exige Appium 2."""
+    return {
+        k if (k in _W3C_KEYS or ":" in k) else f"appium:{k}": v
+        for k, v in caps.items()
+    }
+
+
+def _looks_like_multi(data: dict) -> bool:
+    """Un dictionnaire de plateformes ne contient que des dictionnaires."""
+    return bool(data) and all(isinstance(v, dict) for v in data.values())
+
+
+def _select(data: dict, platform: Optional[str]) -> dict:
+    if not _looks_like_multi(data):
+        return data
+
+    if platform and platform in data:
+        return data[platform]
+
+    if platform:
+        connus = ", ".join(sorted(data))
+        raise CapabilitiesIntrouvables(
+            f"Plateforme '{platform}' absente du fichier. Déclarées : {connus}."
+        )
+
+    return next(iter(data.values()))
+
+
+def _read_source() -> tuple[dict, str]:
+    """Rend les capabilities brutes et l'origine, pour les messages d'erreur."""
+    inline = os.environ.get("MCP_APPIUM_CAPS")
+    if inline:
+        return json.loads(inline), "MCP_APPIUM_CAPS"
+
+    declared = os.environ.get("MCP_APPIUM_CAPS_FILE")
+    chemin = Path(declared) if declared else Path.cwd() / DEFAULT_FILENAME
+
+    if not chemin.is_file():
+        raise CapabilitiesIntrouvables(
+            f"Aucune capability trouvée. Attendu : {chemin}, ou la variable "
+            "MCP_APPIUM_CAPS. Le rattachement à une session existante, lui, "
+            "n'en demande aucune."
+        )
+
+    return json.loads(chemin.read_text(encoding="utf-8")), str(chemin)
+
+
+def load(platform: Optional[str] = None) -> dict:
+    """Rend les capabilities prêtes à être passées à Appium.
+
+    Args:
+        platform: nom de la plateforme dans un fichier multi-plateformes.
+            À défaut, la variable ``MCP_APPIUM_PLATFORM`` est consultée.
+    """
+    data, origine = _read_source()
+
+    if not isinstance(data, dict):
+        raise CapabilitiesIntrouvables(f"{origine} ne décrit pas un objet JSON.")
+
+    choisi = platform or os.environ.get("MCP_APPIUM_PLATFORM") or None
+    return _normalise(_select(data, choisi))