Extentos MCP

Serveur MCP

Serveur MCP

Le serveur MCP Extentos (@extentos/mcp-server\) est un package npm qu’un agent IA (Claude Code, Cursor, Windsurf, Cline) installe une fois, puis utilise pour ajouter des fonctionnalités de lunettes connectées Meta Ray-Ban à une application native iOS ou Android. Il expose un ensemble restreint d’outils déterministes répartis en 10 catégories — découverte, génération, configuration de l’agent, identifiants, analytique, guidage, validation, simulation, préparation pour la production et documentation — ainsi qu’une CLI pour la liaison de compte, le consentement télémétrique et les vérifications de mise à jour. Ceci est le manuel d’utilisation de l’agent.

Le serveur MCP est le moyen par lequel un agent IA — Claude Code, Cursor, Windsurf, Cline ou tout hôte compatible avec le Model Context Protocol — pilote Extentos. L’agent invoque des outils déterministes ; le serveur informe l’agent sur les capacités exposées par les lunettes, renvoie des patterns de code SDK canoniques en Kotlin et Swift, échafaude le projet, orchestre les sessions du simulateur et interroge les traces de débogage. Le serveur lui-même ne possède aucun outil de planification — les agents sont de meilleurs planificateurs que des ensembles d’expressions régulières. Les outils sont des primitives typées que l’agent compose séquentiellement.

Cette page est la page d’accueil de la section — ce qu’est le serveur, un aperçu des outils, le flux canonique piloté par l’agent, les paramètres de configuration, la CLI et le fonctionnement du modèle d’authentification. Les sous-pages couvrent chaque sujet en détail.

Installation

claude mcp add extentos -- npx -y @extentos/mcp-server@latest

Pour les hôtes autres que Claude Code, consultez l’invite de l’agent ou les chemins d’installation JSON manuels. La référence d’installation complète se trouve dans /docs/mcp-server/install.

Les outils, par catégorie

Le serveur expose une surface d’outils déterministes (vérifiée dans mcp-server/src/tools/definitions.ts), organisée en 10 catégories. Les catégories constituent la carte mentale de l’agent ; un agent qui comprend à quelle catégorie appartient un outil peut décider quand l’appeler. Le catalogue complet et toujours à jour est la référence des outils générée.

1. Découverte et référence du SDK (4 outils)

Les premiers appels dans toute nouvelle tâche. Peu coûteux, tous locaux, sans effets de bord.

Outil	Rôle
getPlatformInfo	Renvoie le catalogue statique de la plateforme — version de la bibliothèque, liste des capacités du SDK exposées par les lunettes, niveaux par fournisseur. Toujours le bon premier appel.
getCapabilityGuide	Utilisation minimale par fonctionnalité en Kotlin + Swift — forme de l’appel, arguments de configuration, pièges à éviter. À associer avec getPlatformInfo (qui nomme les fonctionnalités) pour indiquer à l’agent comment invoquer chacune d’elles.
getCodeExample	Compositions canoniques complètes dans les deux langages. Commencez par assistant_agent_loop (le flux canonique d’assistant vocal de la Phase 4) et agent_driven_e2e_full_loop (le test E2E piloté par l’agent). Couvre également voice_qa_assistant, barge_in_speak, photo_describe_voice, live_transcription_ui, voice_notes, connection_page_setup, byok_anthropic, display_browse_detail, display_media_gallery et video_frames_ml. Inspirez-vous de ces exemples pour écrire le code des gestionnaires. La liste complète énumérée est générée dans /docs/reference/mcp-tools.
getMigrationGuide	Pour les applications déjà construites sur le DAT brut de Meta — renvoie une correspondance entre vos symboles DAT existants et les primitives Extentos qui les remplacent, ainsi qu’un plan de basculement ordonné.

2. Mise en place et génération

Outil	Rôle
generateConnectionModule	Échafaudage en une étape — module d’amorçage, câblage Gradle/SPM, dépendances, permissions, manifeste. Flux en deux appels : le premier appel sans placement renvoie une question demandant où ExtentosConnectionPage doit résider ; le second appel avec le placement choisi renvoie l’ensemble complet des fichiers.
getConnectionPageConfig / setConnectionPageConfig	Lire / écrire la configuration de la page de connexion propre au projet (jetons de thème + visibilité des sections) détenue par le tableau de bord/serveur.
regenerateConnectionPageFile / adoptConnectionPageFile	Synchroniser le fichier extentos.connection-page.json validé avec la configuration du serveur — regénérer (serveur→fichier) ou adopter (fichier→serveur).

Après l’échafaudage, l’agent écrit ses propres classes de gestionnaire en s’appuyant sur les primitives du SDK exposées par getCapabilityGuide / getCodeExample. Le code du gestionnaire est la surface de création du client — il n’y a pas d’étape initSpec ou de peuplement de DSL.

3. Configuration et utilisation de l’agent (5 outils)

Portée du compte — nécessitent un compte lié et sont contrôlés par projet via l’octroi d’accès MCP (Lecture+Écriture par défaut).

Outil	Rôle
getAssistantConfig / setAssistantConfig	Lire ou modifier les paramètres de l’assistant gérés par le tableau de bord pour un projet — le modèle OpenAI Realtime, la voix, le modèle de mémoire (compaction) et le mode de mémoire intra-session. set est une mise à jour partielle, valide chaque valeur par rapport au catalogue et indique l’impact sur le coût d’un changement de modèle.
listProjectSounds / addProjectSound	Lister ou téléverser la bibliothèque de sons nommés d’un projet — fichiers MP3/M4A/AAC/WAV de moins de 1 Mo que le code de l’application joue avec glasses.audio.playSound(name) (iOS aujourd’hui ; la prise en charge de la lecture sur Android est imminente) — le tableau de bord peut également en choisir un comme son de réveil. Contrôlé par l’octroi assistant_config.sounds.
getGatewayUsage	Lire l’utilisation de la passerelle gérée du projet + le coût exact sur une fenêtre récente — nombre de jetons et prix catalogue en USD issus du registre de facturation, ventilés par modèle. Métadonnées uniquement, jamais de transcriptions ni de contenu.

4. Identifiants (2 outils)

Portée du compte + contrôlés par projet. Écriture sans connaissance — le secret ne transite jamais par l’agent.

Outil	Rôle
getCredentialStatus	Lire si la clé API OpenAI (BYOK) et l’identité de build Meta DAT d’un projet sont définies — une indication masquée + la date de mise à jour uniquement, jamais la valeur.
setCredential	Démarrer la saisie d’un identifiant en mode écriture sans connaissance — renvoie un lien vers le tableau de bord où le propriétaire connecté colle le secret directement dans le coffre-fort chiffré. Ne prend aucun argument de secret, par conception.

5. Analytique (1 outil)

Outil

Rôle

getProjectAnalytics

Lire les analytiques de production d’un projet — télémétrie agrégée provenant des installations livrées sur l’App Store / le Play Store (événements, installations actives, par événement / jour / fournisseur / plateforme). Métadonnées uniquement, portée du compte, vérification de propriété, contrôlé par l’octroi Analytics. Vide jusqu’à ce que l’application soit livrée et envoie des événements attestés en production (utilisez getEventLog pour le flux de développement/simulation en direct).

6. Guidage d’implémentation (2 outils)

Outils de quête secondaire que l’agent appelle pendant la composition.

Outil	Ce qu'il fait
getVoiceCommandGuidance	Analyse les propositions de phrases d'activation / commandes pour détecter les problèmes UX (collisions, ambiguïté, mots difficiles à reconnaître, conflits avec les mots d'activation Meta) avant de les câbler dans un consommateur glasses.audio.transcriptions().
getPermissions	Déduit les permissions de plateforme exactes, les exigences Meta DAT et les besoins de service de premier plan à partir de la liste des capacités. À exécuter lors de l'ajout ou de la suppression d'une primitive de votre gestionnaire.

7. Validation (2 outils)

Portes de vérification de la justesse. À exécuter après des modifications structurelles (nouvelle capacité déclarée, dépendance mise à jour, manifeste modifié).

Outil	Ce qu'il fait
inspectIntegration	Instantané du projet en lecture seule — manifeste, hachages des fichiers générés, liste des dépendances, configuration de la page de connexion. À exécuter avant les modifications manuelles pour comprendre l'état actuel.
validateIntegration	Vérification de la justesse de l'ensemble du projet — manifeste, fichiers générés, dépendance déclarée, les permissions couvrent les capacités déclarées, les appels d'amorçage ExtentosGlasses.create(...), les versions de la chaîne d'outils, les indications de service de premier plan pour les flux de capture continue. La porte de pré-test.

8. Simulation

Provisionner et exploiter des sessions de simulateur basées sur le navigateur, ainsi que les outils de test pilotés par agent qui bouclent la boucle de bout en bout sans intervention humaine.

Outil	Ce qu'il fait
createSimulatorSession	Obtenir ou créer une session en mode navigateur sur extentos.com/s. Renvoie la simulation sauvegardée pour ce projet si elle existe (statut : "resumed"), ou en crée une nouvelle (statut : "active"). Attache automatiquement l'application en cours d'exécution via le pont local lorsqu'elle est accessible ; sinon, émet un extrait BuildConfig.EXTENTOS_SESSION_URL (Android) ou une charge utile extentos.session.plist (iOS). Passez resetFresh: true pour renouveler le sessionId et repartir de zéro.
ensureSimulatorBrowser	Ouvrir + confirmer un onglet de navigateur de simulateur connecté — la condition préalable pour les flux de caméra et d'injection.
completeAuthLink	Après que createSimulatorSession renvoie le statut : "auth_required" (une installation anonyme doit être liée pour créer des sessions), interroge le backend jusqu'à ce que l'utilisateur termine l'inscription, puis persiste le jeton porteur dans ~/.extentos/auth.json.
getEventLog	Récupérer les traces d'événements structurées d'une session. Valeurs de filtre : all (aucun filtre) plus les sept catégories errors, voice, camera, display, ai, lifecycle, custom — une catégorie par événement, errors absorbant les événements de sévérité≥warn quelle que soit la modalité. Plus cursor, follow, limit pour la portée au niveau des traces. L'outil de débogage principal.
getSimulatorStatus	Lire l'état actuel d'une session en direct — phase, matériel prêt, rôles attachés, flux de capacités actifs, valeurs actuelles des bascules.
injectTranscript / injectAssistantUtterance / assertToolCalled	Piloter une phrase d'activation ou un tour d'assistant, puis vérifier quel outil le modèle a appelé — la boucle E2E pilotée par agent, sans intervention humaine.
injectHardwareButton	Appuyer sur le bouton de capture matériel simulé des lunettes — appuyer met en pause/reprend un flux de caméra en direct, maintenir l'arrête — afin que l'agent puisse exercer les gestes de confidentialité du porteur (et tester le CaptureError.StreamPaused résultant) sans intervention humaine.
setSimVideo / setSimDevice	Injecter une vidéo de test dans la caméra simulée ; changer le modèle d'appareil simulé (par exemple rayban_display pour exercer le chemin d'affichage).
getDisplayState / injectInput	Lire l'arborescence d'affichage actuellement rendue + piloter l'entrée d'affichage (sélectionner / naviguer / retour).

9. Production (2 outils)

Vérifications préalables à la livraison.

Outil	Ce qu'il fait
getProductionChecklist	Liste de contrôle personnalisée de préparation à la production basée sur les capacités déclarées + les noms des gestionnaires — câblage des informations d'identification, audit des permissions, exigences de service de premier plan (lorsque la capture continue est utilisée), suppression de l'URL du simulateur des versions de publication, préparation de la fiche de la boutique d'applications.
getCredentialGuide	Configuration étape par étape des informations d'identification pour les fournisseurs d'IA de production — anthropic, openai, google_cloud_vision, google_translate, google_gemini, deepl, azure_cognitive, aws_bedrock, huggingface, ou personnalisé — plus l'enregistrement Meta DAT.

10. Documentation & recherche (1 outil)

Outil

Ce qu'il fait

searchDocs

Rechercher dans la documentation Extentos par sujet ou mot-clé. Pour les assistants vocaux, lisez d'abord assistant_runtime ; conversation_runtime est l'environnement d'exécution obsolète de la Phase 3 (référence de migration uniquement). Autres sujets alignés : voice_integration, agent_e2e_testing, managed_gateway, conversation_memory, display, plus l'ensemble conceptuel stable — getting_started, custom_handlers (le document canonique de composition du SDK), simulator_browser_mode, event_log_schema, toggles, library_api, permissions, multi_platform_projects. Les identifiants de sujet sont stables ; l'entrée de l'outil en direct fait autorité.

Référence complète par outil avec schémas d'entrée, formes de réponse et exemples concrets : /docs/mcp-server/tools.

Le flux canonique piloté par agent

Dans un nouveau projet, l'agent invoque les outils dans cet ordre :

1. getPlatformInfo({ sections: ["version", "capabilities"], glasses: "meta_rayban" })
2. getCodeExample({ pattern: "assistant_agent_loop" })  // Phase-4 voice assistant; or whatever pattern fits
3. getCapabilityGuide({ feature: "<each primitive the handler will use>" })
4. generateConnectionModule({ platform, glasses, appPackage })
   → returns "needs_placement" question
5. generateConnectionModule({ ... placement: "<chosen>" })
   → writes scaffold files (ExtentosBootstrap, manifest, etc.)
6. <agent writes handler class(es)> against the SDK primitives
   <agent updates extentos.manifest.json's `capabilities` array>
7. validateIntegration()
   → ✓ all good (or returns structured errors to fix)
8. createSimulatorSession({ glasses })
   → returns sessionId; auto-opens browser at extentos.com/s/<id>
   → if running app is reachable via local bridge, it auto-attaches
9. <developer interacts with the simulator; capability events flow into the backend>
10. getEventLog({ sessionId, filter: "errors" })  → debug
    getSimulatorStatus({ sessionId })             → status

Pour l'itération : modifier le code du gestionnaire → reconstruire + réinstaller → l'application s'attache automatiquement à la même session de simulateur (pas de recréation, l'URL est stable). Avant la livraison : getProductionChecklist et getCredentialGuide.

Configuration

Le serveur MCP lit ces variables d'environnement (vérifiées dans mcp-server/src/) :

Variable	Valeur par défaut	Rôle
EXTENTOS_BACKEND_URL	Backend de production	Surcharge l'URL du backend (tools/util/backendClient.ts). Pour le développement local d'Extentos lui-même.
EXTENTOS_CONFIG_DIR	~/.extentos	Surcharge le répertoire config/auth (telemetry/consent.ts).
EXTENTOS_TELEMETRY	non défini (consentement par défaut)	Mettre à 0 pour refuser la télémétrie sans exécuter la commande CLI de consentement.
EXTENTOS_NO_AUTO_OPEN	non défini	Mettre à 1 pour désactiver l'ouverture automatique du navigateur lors de la création d'une session simulateur (utile dans les environnements sans interface graphique).

Référence complète de configuration : /docs/mcp-server/configuration.

Sous-commandes CLI

Exécuter npx @extentos/mcp-server@latest sans argument démarre le serveur MCP via stdio (le chemin utilisé par l'agent). Avec une sous-commande, il agit comme une CLI développeur :

Sous-commande	Rôle
login	Lie cette installation à un compte Extentos via le flux device-code (proactif — utile avant la première session simulateur, ou après une déconnexion pour se re-lier).
logout	Efface ~/.extentos/auth.json. L'installation revient au niveau anonyme ; le prochain appel de session simulateur redéclenchera le flux device-code.
whoami	Pas encore implémenté (stub Phase-0). Affichera l'installId, l'accountId (si lié), le niveau, l'expiration de l'authentification.
setup	Prépare l'environnement de build local — vérifie le PAT GitHub Packages (read:packages) requis par les artefacts Meta DAT transitifs, ainsi que les autres prérequis de dépendances.
accept-privacy	Enregistre le consentement à la confidentialité (active l'envoi de télémétrie).
decline-privacy	Enregistre le refus de confidentialité (désactive l'envoi de télémétrie).
status	Affiche l'état du consentement, l'ID d'installation, le compte lié, les versions MCP/bibliothèque.
update	Vérifie les mises à jour du serveur MCP (sans effet sur les installations npx @latest).

Référence complète CLI : /docs/mcp-server/auth.

Modèle d'authentification

Le serveur MCP est anonyme d'abord. La découverte, les guides de capacités, les exemples de code, la validation, la recherche dans la documentation, la simulation sur l'appareil et les tests sur matériel réel fonctionnent tous sans jamais se connecter. Trois choses lient un compte gratuit : la création de sessions simulateur navigateur (createSimulatorSession, HTTP 402), l'étape de scaffold generateConnectionModule (elle crée votre clé de projet liée au compte — même flux device-code 402 ; le premier appel informatif est anonyme), et les outils de projet liés au compte (configuration de l'assistant, identifiants, écriture de la page de connexion, analytique — HTTP 401).

Le flux device-code : le premier appel protégé retourne status: "auth_required" avec une URL de vérification. L'agent appelle completeAuthLink pour interroger le backend ; le développeur s'inscrit avec un compte gratuit par email uniquement à l'URL (Google ou email + mot de passe, sans paiement) ; le backend émet un jeton ; l'appel d'outil original réessaie automatiquement. Après liaison, les sessions simulateur sont illimitées.

Les outils, la génération de code, la validation, le SDK et le simulateur navigateur d'Extentos sont gratuits — il n'y a pas de frais par poste ou d'abonnement pour construire et livrer. La seule surface qui mesure l'utilisation est la passerelle IA gérée derrière l'assistant vocal Phase-4. Modèle d'authentification complet : /docs/mcp-server/auth ; tarification : /docs/resources/pricing.

Confidentialité et télémétrie

Au premier lancement, le serveur MCP injecte un avis de confidentialité unique dans la réponse. La télémétrie est anonyme (étiquetée avec installId, pas de code source ni de données personnelles) et est acceptée par défaut en continuant — même modèle que Vercel CLI, Astro, Vite. Refusez à tout moment :

npx @extentos/mcp-server@latest decline-privacy
# or
EXTENTOS_TELEMETRY=0 (env var, persistent for the shell)

Le contenu de l'avis de confidentialité se trouve dans mcp-server/src/index.ts (constante PRIVACY_NOTICE). L'avis est affiché une fois par installation via claimFirstPrivacyNotice — ne se répète jamais.

Hôtes MCP compatibles

Vérifié pour fonctionner avec :

• Claude Code — cible principale. Installation en une ligne via claude mcp add.
• Cursor — configuration JSON dans ~/.cursor/mcp.json.
• Windsurf — configuration JSON dans ~/.codeium/windsurf/mcp_config.json.
• Cline — configuration JSON dans les paramètres MCP de Cline.
• Tout hôte compatible MCP — insérez le bloc JSON standard mcpServers.extentos.

Le serveur MCP parle le protocole MCP standard via stdio (@modelcontextprotocol/sdk) ; aucun chemin de code spécifique à l'hôte n'existe côté serveur. Étapes d'installation par hôte : /docs/mcp-server/agents.

Le pont local — boucle dev auto-liaison

Au démarrage du serveur, il ouvre un écouteur HTTP 127.0.0.1:31337/whoami (mcp-server/src/localBridge.ts). La bibliothèque Extentos sur l'application du développeur sonde ce point de terminaison à l'exécution pour apprendre le installId de son hôte MCP. Le résultat : chaque appel createSimulatorSession de l'agent attache automatiquement l'application en cours d'exécution à la nouvelle session — pas de reconstruction, pas de collage d'URL.

Chemins d'accès :

• Émulateur Android : http://10.0.2.2:31337/whoami (alias NAT de bouclage hôte)
• Simulateur iOS : http://localhost:31337/whoami (partage l'espace de noms réseau de l'hôte)
• Téléphone Android physique via USB : adb reverse tcp:31337 tcp:31337 une fois, puis localhost:31337 depuis l'appareil
• Téléphone cellulaire ou agent hébergé dans le cloud : la sonde expire. L'agent utilise alors le chemin d'intégration par URL — createSimulatorSession retourne un extrait BuildConfig.EXTENTOS_SESSION_URL (Android) ou une charge utile extentos.session.plist (iOS) que le développeur colle, puis reconstruit l'application une fois. Moins élégant que l'auto-liaison mais fonctionne sur toute topologie.

Lié à 127.0.0.1 uniquement. Le installId n'est pas un secret — c'est la même valeur que le MCP envoie à api.extentos.com à chaque appel d'outil. Aucune authentification nécessaire à cette couche.

Si le port 31337 est utilisé (rare ; une autre instance MCP déjà en cours d'exécution), le démarrage enregistre un avertissement et continue. L'auto-liaison échoue silencieusement pour cette session ; le développeur utilise le chemin d'intégration par URL jusqu'à ce que le port se libère.

Statut

• Paquet : @extentos/mcp-server sur npm (licence MIT)
• Moteurs : Node.js 20+
• Pré-1.0 — les API peuvent changer entre les versions mineures jusqu'à ce que la boucle de test matériel soit fermée. Épinglez une version exacte si vous avez besoin de reproductibilité entre les sessions.

Connexes

• Démarrage rapide avec un agent IA — installez le serveur et parcourez une vraie boucle de développement
• Référence des outils — API complète par outil
• Configuration — variables d'environnement, fichiers de configuration, paramètres d'installation
• Authentification — flux device-code, liaison de compte, commandes CLI d'authentification
• Agents pris en charge — instructions d'installation par hôte
• Architecture — comment le serveur MCP s'intègre dans le système Extentos plus large
• Transport vs simulation d'application — ce que fait réellement le simulateur que le MCP négocie

Connexes

Démarrage rapide avec un agent IA

Installez le serveur MCP Extentos et laissez votre agent IA intégrer des capacités de lunettes connectées Meta Ray-Ban dans une application native iOS ou Android. Gratuit pour commencer.

Architecture

Comment Extentos s'assemble — agent IA, serveur MCP, SDK natif Kotlin/Swift, trois transports (Meta DAT, simulateur navigateur, simulateur local en mémoire), et le backend.

Transport vs simulation d'application

Le Mock Device Kit de Meta simule la couche de transport ; Extentos simule la couche applicative — voix, capture photo et l'expérience de port. Les deux comptent.

Installer le serveur MCP

Comment installer le serveur MCP Extentos (@extentos/mcp-server) dans n'importe quel agent de codage IA compatible MCP — Claude Code, Cursor, Windsurf, Cline, et autres. Commandes d'installation par hôte, emplacements des fichiers de configuration, extraits JSON copiables, étapes de redémarrage et de vérification, épinglage de version, mise à jour, dépannage des erreurs courantes et instructions de désinstallation. Chemins d'installation vérifiés pour chaque hôte pris en charge.

Référence des outils

Le serveur MCP Extentos expose un ensemble restreint d'outils déterministes dans des catégories déterministes — découverte + référence SDK, génération, guidage, validation, simulation, production, configuration de l'agent et recherche. Référence par outil couvrant les paramètres d'entrée, les formes de réponse, quand appeler chaque outil et des exemples concrets. Vérifié à partir des définitions d'outils réelles et des implémentations de gestionnaires dans @extentos/mcp-server.

Configuration

Configurez @extentos/mcp-server — variables d'environnement, les fichiers d'état ~/.extentos (id d'installation, authentification, consentement) et le fournisseur par défaut.

Authentification

Comment fonctionne l'authentification Extentos. La découverte, le guidage, la validation et la recherche s'exécutent sans compte ; un compte gratuit (lié via le flux OAuth 2.0 device-code) débloque les sessions simulateur navigateur, l'étape de scaffold et les outils de projet liés au compte. Aucun paiement.

Agents pris en charge

Différences par hôte pour les agents de codage IA qui exécutent Extentos — Claude Code, Cursor, Windsurf, Cline, intégrés à l'IDE. Portée, couverture multiplateforme, prise en charge MCP.

Lunettes connectées Apple

Lunettes connectées Apple pour les développeurs tiers — accès SDK, modèle d'application, distribution, capacités & IA, et sa place dans le paysage des lunettes connectées de 2026.

Installer le serveur MCP