Extentos MCP

MCP-сервер

MCP-сервер

MCP-сервер Extentos (@extentos/mcp-server\) — это npm-пакет, который AI-агент (Claude Code, Cursor, Windsurf, Cline) устанавливает один раз и затем использует для добавления возможностей умных очков Meta Ray-Ban в нативные приложения iOS или Android. Он предоставляет компактный набор детерминированных инструментов по 10 категориям — обнаружение, генерация, конфигурация агента, учетные данные, аналитика, руководство, валидация, симуляция, готовность к продакшену и документация — плюс CLI для привязки аккаунта, согласия на телеметрию и проверки обновлений. Это руководство по эксплуатации для агента.

MCP-сервер — это то, как AI-агент — Claude Code, Cursor, Windsurf, Cline или любой хост, совместимый с Model Context Protocol — управляет Extentos. Агент вызывает детерминированные инструменты; сервер информирует агента о возможностях очков, возвращает канонические шаблоны кода SDK на Kotlin и Swift, создает каркас проекта, управляет сессиями симулятора и запрашивает трассировки отладки. Сам сервер не имеет инструмента планирования — агенты планируют лучше, чем наборы регулярных выражений. Инструменты — это типизированные примитивы, которые агент комбинирует последовательно.

Эта страница — целевая страница раздела: что такое сервер, обзор инструментов, канонический процесс, управляемый агентом, параметры конфигурации, CLI и как работает модель аутентификации. Подстраницы подробно описывают каждый аспект.

Установка

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

Для хостов, отличных от Claude Code, смотрите промпт агента или пути ручной установки JSON. Полное руководство по установке: /docs/mcp-server/install.

Инструменты по категориям

Сервер предоставляет детерминированную поверхность инструментов (проверено в mcp-server/src/tools/definitions.ts), организованную по 10 категориям. Категории — это ментальная карта агента; агент, понимающий, к какой категории относится инструмент, может решить, когда его вызывать. Всегда актуальный полный каталог — это сгенерированный справочник инструментов.

1. Обнаружение и справочник SDK (3 инструмента)

Первые вызовы в любой новой задаче. Быстрые, полностью локальные, без побочных эффектов.

Инструмент	Что делает
getPlatformInfo	Возвращает статический каталог платформы — версию библиотеки, список возможностей SDK, предоставляемых очками, уровни для каждого производителя. Всегда правильный первый вызов.
getCapabilityGuide	Минимальное использование для каждой функции на Kotlin + Swift — форма вызова, аргументы конфигурации, подводные камни. Работает в паре с getPlatformInfo (который называет функции), чтобы сообщить агенту, как вызывать каждую.
getCodeExample	Полные канонические композиции на обоих языках. Начните с assistant_agent_loop (канонический поток голосового ассистента Фазы 4) и agent_driven_e2e_full_loop (сквозной тест, управляемый агентом). Также охватывает 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 и video_frames_ml. Используйте их как основу при написании кода обработчика. Полный перечень генерируется в /docs/reference/mcp-tools.

2. Настройка и генерация

Инструмент	Что делает
generateConnectionModule	Одноразовое создание каркаса — модуль начальной загрузки, подключение Gradle/SPM, зависимости, разрешения, манифест. Процесс из двух вызовов: первый вызов без размещения возвращает вопрос о том, где должен находиться ExtentosConnectionPage; второй вызов с выбранным размещением возвращает полный набор файлов.
getConnectionPageConfig / setConnectionPageConfig	Чтение / запись конфигурации страницы подключения для конкретного проекта (токены тем + видимость разделов), хранящейся на дашборде/сервере.
regenerateConnectionPageFile / adoptConnectionPageFile	Синхронизация зафиксированного extentos.connection-page.json с конфигурацией сервера — regenerate (сервер→файл) или adopt (файл→сервер).

После создания каркаса агент пишет свои собственные классы-обработчики, используя примитивы SDK, предоставляемые getCapabilityGuide / getCodeExample. Код обработчика — это область авторской работы клиента — здесь нет шага initSpec или заполнения DSL.

3. Конфигурация и использование агента (3 инструмента)

Привязаны к аккаунту — требуют привязанного аккаунта и ограничены для каждого проекта грантом доступа MCP (по умолчанию Чтение+Запись).

Инструмент	Что делает
getAssistantConfig / setAssistantConfig	Чтение или изменение управляемых дашбордом настроек ассистента проекта — модель OpenAI Realtime, голос, модель памяти (сжатия) и режим памяти в рамках сессии. set — это частичное обновление, проверяет каждое значение по каталогу и отображает влияние на стоимость при смене модели.
getGatewayUsage	Чтение использования управляемого шлюза проекта + точная стоимость за последний период — количество токенов и стоимость по прейскуранту в USD из платежного реестра, с разбивкой по моделям. Только метаданные, никогда не расшифровки или контент.

4. Учетные данные (2 инструмента)

Привязаны к аккаунту + ограничены для каждого проекта. Запись без знания — секрет никогда не проходит через агента.

Инструмент	Что делает
getCredentialStatus	Чтение того, установлены ли ключ API OpenAI проекта (BYOK) и идентификатор сборки Meta DAT — только маскированная подсказка + время обновления, никогда не значение.
setCredential	Запуск ввода учетных данных в режиме записи без знания — возвращает ссылку на дашборд, где авторизованный владелец вставляет секрет прямо в зашифрованное хранилище. По замыслу не принимает аргумент с секретом.

5. Аналитика (1 инструмент)

Инструмент

Что делает

getProjectAnalytics

Чтение продакшен-аналитики проекта — агрегированная телеметрия из установок, опубликованных в App Store / Play Store (события, активные установки, по событию / дню / производителю / платформе). Только метаданные, привязана к аккаунту, с проверкой владельца, ограничена грантом Аналитики. Пуста, пока приложение не опубликовано и не отправляет подтвержденные продакшен-события (для живого потока разработки/симуляции используйте getEventLog).

6. Руководство по реализации (2 инструмента)

Вспомогательные инструменты, которые агент вызывает в процессе композиции.

Инструмент	Что делает
getVoiceCommandGuidance	Анализ предлагаемых фраз пробуждения / команд на предмет UX-проблем (коллизии, двусмысленность, труднораспознаваемые слова, конфликты с wake-словами Meta) перед подключением их к потребителю glasses.audio.transcriptions().
getPermissions	Определение точных разрешений платформы, требований Meta DAT и потребностей в foreground-сервисах на основе списка возможностей. Запускайте при добавлении или удалении примитива из вашего обработчика.

7. Валидация (2 инструмента)

Шлюзы корректности. Запускайте после структурных изменений (объявление новой возможности, обновление зависимости, редактирование манифеста).

Инструмент	Что он делает
inspectIntegration	Снимок проекта только для чтения — манифест, хеши сгенерированных файлов, список зависимостей, конфигурация страницы подключения. Запускайте перед ручными правками, чтобы понять текущее состояние.
validateIntegration	Проверка корректности всего проекта — манифест, сгенерированные файлы, объявленная зависимость, разрешения покрывают заявленные возможности, bootstrap вызывает ExtentosGlasses.create(...), версии инструментария, подсказки foreground-сервиса для потоков непрерывной записи. Предтестовый шлюз.

8. Симуляция

Предоставление и управление сессиями симулятора на основе браузера, а также инструменты тестирования на основе агентов, замыкающие сквозной цикл без участия человека.

Инструмент	Что он делает
createSimulatorSession	Получить или создать сессию в режиме браузера на extentos.com/s. Возвращает сохранённую симуляцию для этого проекта, если она существует (статус: "resumed"), или создаёт новую (статус: "active"). Автоматически подключает запущенное приложение через локальный мост, если оно доступно; в противном случае выдаёт фрагмент BuildConfig.EXTENTOS_SESSION_URL (Android) или пейлоад extentos.session.plist (iOS). Передайте resetFresh: true, чтобы сменить sessionId для чистого старта.
ensureSimulatorBrowser	Открыть + подтвердить подключённую вкладку браузера симулятора — предусловие для потоков камеры и инжекта.
completeAuthLink	После того как createSimulatorSession возвращает статус: "auth_required" (анонимной установке нужно привязаться к созданным сессиям), опрашивает бэкенд, пока пользователь не завершит регистрацию, затем сохраняет токен-носитель в ~/.extentos/auth.json.
getEventLog	Получить структурированные трассировки событий из сессии. Значения фильтра: all (без фильтра) плюс семь категорий errors, voice, camera, display, ai, lifecycle, custom — по одной категории на событие, при этом errors поглощает события с severity≥warn независимо от модальности. Плюс cursor, follow, limit для охвата на уровне трассировки. Основной инструмент отладки.
getSimulatorStatus	Прочитать текущее состояние активной сессии — фаза, готовность оборудования, подключённые роли, активные потоки возможностей, текущие значения переключателей.
injectTranscript / injectAssistantUtterance / assertToolCalled	Инициировать пробуждающую фразу или реплику ассистента, затем проверить, какой инструмент вызвала модель — сквозной цикл на основе агентов, без участия человека.
setSimVideo / setSimDevice	Передать тестовое видео в симулированную камеру; переключить модель симулируемого устройства (например, rayban_display для проверки пути отображения).
getDisplayState / injectInput	Прочитать текущее отрисованное дерево отображения + управлять вводом отображения (выбор / навигация / назад).

9. Продакшен (2 инструмента)

Предотгрузочные проверки.

Инструмент	Что он делает
getProductionChecklist	Персонализированный чек-лист готовности к продакшену на основе заявленных возможностей + имён обработчиков — подключение учётных данных, аудит разрешений, требования к foreground-сервису (при использовании непрерывной записи), удаление URL симулятора из релизных сборок, готовность к публикации в сторе.
getCredentialGuide	Пошаговая настройка учётных данных для продакшен-провайдеров ИИ — anthropic, openai, google_cloud_vision, google_translate, google_gemini, deepl, azure_cognitive, aws_bedrock, huggingface или custom — плюс регистрация Meta DAT.

10. Документация и поиск (1 инструмент)

Инструмент

Что он делает

searchDocs

Поиск в документации Extentos по теме или ключевому слову. Для голосовых ассистентов сначала читайте assistant_runtime; conversation_runtime — это устаревшая среда выполнения Фазы 3 (только для справки по миграции). Другие связанные темы: voice_integration, agent_e2e_testing, managed_gateway, conversation_memory, display, а также стабильный концептуальный набор — getting_started, custom_handlers (канонический документ по композиции SDK), simulator_browser_mode, event_log_schema, toggles, library_api, permissions, multi_platform_projects. Идентификаторы тем стабильны; авторитетным является ввод в работающем инструменте.

Полный поинструментный справочник со схемами ввода, форматами ответов и проработанными примерами: /docs/mcp-server/tools.

Канонический поток на основе агента

В новом проекте агент вызывает инструменты в следующем порядке:

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

Для итерации: редактирование кода обработчика → пересборка + переустановка → приложение автоматически подключается к той же сессии симулятора (без пересоздания, URL стабилен). Перед отправкой: getProductionChecklist и getCredentialGuide.

Конфигурация

MCP-сервер считывает следующие переменные окружения (проверяются в mcp-server/src/):

Переменная	По умолчанию	Что она делает
EXTENTOS_BACKEND_URL	Продакшен-бэкенд	Переопределить URL бэкенда (tools/util/backendClient.ts). Для локальной разработки самого Extentos.
EXTENTOS_CONFIG_DIR	~/.extentos	Переопределить директорию конфигурации/аутентификации (telemetry/consent.ts).
EXTENTOS_TELEMETRY	не задано (согласие по умолчанию)	Установите в 0, чтобы отказаться от телеметрии без запуска команды согласия CLI.
EXTENTOS_NO_AUTO_OPEN	не задано	Установите в 1, чтобы отключить автоматическое открытие браузера при создании сессии симулятора (полезно в средах без графического интерфейса).

Полный справочник по конфигурации: /docs/mcp-server/configuration.

Подкоманды CLI

Запуск npx @extentos/mcp-server@latest без аргументов запускает MCP-сервер через stdio (путь, используемый агентом). С подкомандой он действует как CLI разработчика:

Подкоманда	Что делает
login	Привязывает эту установку к аккаунту Extentos через поток device-code (проактивно — полезно перед первым сеансом симулятора или после выхода для повторной привязки).
logout	Очищает ~/.extentos/auth.json. Установка возвращается на анонимный уровень; следующий вызов сеанса симулятора снова запустит поток device-code.
whoami	Пока не реализовано (заглушка Фазы-0). Будет выводить installId, accountId (если привязан), уровень, срок действия аутентификации.
setup	Предварительная проверка локального окружения сборки — проверяет GitHub Packages PAT (read:packages), необходимый для транзитивных артефактов Meta DAT, а также другие зависимости.
accept-privacy	Записывает согласие на конфиденциальность (включает загрузку телеметрии).
decline-privacy	Записывает отказ от конфиденциальности (отключает загрузку телеметрии).
status	Выводит состояние согласия, ID установки, привязанный аккаунт, версии MCP/библиотек.
update	Проверяет обновления MCP-сервера (ничего не делает при установках через npx @latest).

Полная справка по CLI: /docs/mcp-server/auth.

Модель аутентификации

MCP-сервер работает по принципу сначала анонимность. Обнаружение, руководства по возможностям, примеры кода, валидация, поиск по документации, симуляция на устройстве и тестирование на реальном оборудовании — всё работает без входа в систему. Три вещи привязывают бесплатный аккаунт: создание сессий браузерного симулятора (createSimulatorSession, HTTP 402), шаг скаффолдинга generateConnectionModule (он создает ключ проекта, привязанный к аккаунту — тот же поток device-code с кодом 402; первый информационный вызов анонимен), и инструменты проекта с областью действия аккаунта (конфигурация ассистента, учетные данные, запись страниц подключения, аналитика — HTTP 401).

Поток device-code: первый защищенный вызов возвращает status: "auth_required" с URL-адресом для верификации. Агент вызывает completeAuthLink для опроса бэкенда; разработчик регистрируется с бесплатным аккаунтом только по email на этом URL (Google или email + пароль, без оплаты); бэкенд выдает токен; исходный вызов инструмента автоматически повторяется. После привязки сеансы симулятора не ограничены.

Инструменты Extentos, генерация кода, валидация, SDK и браузерный симулятор бесплатны — плата за место или подписка для сборки и поставки отсутствует. Единственная поверхность, где использование измеряется, — это управляемый AI-шлюз за голосовым ассистентом Фазы-4. Полная модель аутентификации: /docs/mcp-server/auth; цены: /docs/resources/pricing.

Конфиденциальность и телеметрия

При первом запуске MCP-сервер вставляет одноразовое уведомление о конфиденциальности в ответ. Телеметрия анонимна (помечена installId, без исходного кода или персональных данных) и по умолчанию отклоняется продолжением работы — та же модель, что и в Vercel CLI, Astro, Vite. Отказаться можно в любое время:

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

Содержимое уведомления о конфиденциальности находится в mcp-server/src/index.ts (константа PRIVACY_NOTICE). Уведомление показывается один раз для каждой установки через claimFirstPrivacyNotice — никогда не повторяется.

Совместимые MCP-хосты

Проверена работа с:

• Claude Code — основная цель. Установка одной строкой через claude mcp add.
• Cursor — JSON-конфигурация в ~/.cursor/mcp.json.
• Windsurf — JSON-конфигурация в ~/.codeium/windsurf/mcp_config.json.
• Cline — JSON-конфигурация в настройках MCP Cline.
• Любой MCP-совместимый хост — вставьте стандартный блок JSON mcpServers.extentos.

MCP-сервер использует стандартный протокол MCP через stdio (@modelcontextprotocol/sdk); на стороне сервера нет кода, специфичного для хоста. Инструкции по установке для каждого хоста: /docs/mcp-server/agents.

Локальный мост — цикл авто-привязки

При запуске сервер открывает HTTP-слушатель 127.0.0.1:31337/whoami (mcp-server/src/localBridge.ts). Библиотека Extentos в приложении разработчика обращается к этой конечной точке во время выполнения, чтобы узнать installId своего хост-MCP. Результат: каждый вызов createSimulatorSession от агента автоматически присоединяет запущенное приложение к новому сеансу — без пересборки, без вставки URL.

Пути доступа:

• Эмулятор Android: http://10.0.2.2:31337/whoami (NAT-псевдоним host-loopback)
• Симулятор iOS: http://localhost:31337/whoami (разделяет сетевое пространство имен хоста)
• Физический телефон Android через USB: adb reverse tcp:31337 tcp:31337 один раз, затем localhost:31337 с устройства
• Сотовый телефон или облачный агент: опрос завершается тайм-аутом. Вместо этого агент использует путь с внедрением URL — createSimulatorSession возвращает фрагмент BuildConfig.EXTENTOS_SESSION_URL (Android) или полезную нагрузку extentos.session.plist (iOS), который разработчик вставляет, а затем пересобирает приложение один раз. Менее элегантно, чем авто-привязка, но работает в любой топологии.

Привязывается только к 127.0.0.1. installId не является секретом — это то же значение, которое MCP отправляет в api.extentos.com при каждом вызове инструмента. Аутентификация на этом уровне не требуется.

Если порт 31337 занят (редко; уже запущен другой экземпляр MCP), при запуске выводится предупреждение, и работа продолжается. Авто-привязка для этого сеанса молча завершается ошибкой; разработчик использует путь с внедрением URL, пока порт не освободится.

Статус

• Пакет: @extentos/mcp-server на npm (лицензия MIT)
• Движки: Node.js 20+
• До версии 1.0 — API могут меняться между минорными версиями до замыкания цикла тестирования на оборудовании. Закрепите точную версию, если вам нужна воспроизводимость между сеансами.

Связанное

• Быстрый старт с AI-агентом — установите сервер и пройдите реальный цикл разработки
• Справка по инструментам — полный API для каждого инструмента
• Конфигурация — переменные окружения, файлы конфигурации, настройки времени установки
• Аутентификация — поток device-code, привязка аккаунта, CLI-команды аутентификации
• Поддерживаемые агенты — инструкции по установке для каждого хоста
• Архитектура — как MCP-сервер вписывается в более широкую систему Extentos
• Транспорт против симуляции приложения — что на самом деле делает симулятор, управляемый MCP

Связанное

Быстрый старт с AI-агентом

Установите MCP-сервер Extentos и позвольте вашему AI-агенту внедрить возможности умных очков Meta Ray-Ban в нативное приложение для iOS или Android. Бесплатно для начала.

Архитектура

Как Extentos сочетает в себе — AI-агент, MCP-сервер, нативный SDK Kotlin/Swift, три транспорта (Meta DAT, браузерный сим, локальный сим в памяти) и бэкенд.

Транспорт против симуляции приложения

Mock Device Kit от Meta симулирует транспортный уровень; Extentos симулирует уровень приложения — голос, захват фото и опыт ношения. И то, и другое важно.

Установка MCP-сервера

Как установить MCP-сервер Extentos (@extentos/mcp-server) в любой MCP-совместимый AI-агент для кодинга — Claude Code, Cursor, Windsurf, Cline и другие. Команды установки для каждого хоста, расположение файлов конфигурации, готовые к копированию фрагменты JSON, шаги перезапуска и проверки, закрепление версии, обновление, устранение распространенных ошибок и инструкции по удалению. Проверенные пути установки для каждого поддерживаемого хоста.

Справка по инструментам

MCP-сервер Extentos предоставляет компактный набор детерминированных инструментов по детерминированным категориям — обнаружение + справка по SDK, генерация, руководство, валидация, симуляция, продакшен, конфигурация агента и поиск. Справка по каждому инструменту, охватывающая входные параметры, формы ответов, когда вызывать каждый инструмент и проработанные примеры. Проверено на основе реальных определений инструментов и реализаций обработчиков в @extentos/mcp-server.

Конфигурация

Настройка @extentos/mcp-server — переменные окружения, файлы состояния ~/.extentos (id установки, аутентификация, согласие) и поставщик по умолчанию.

Аутентификация

Как работает аутентификация Extentos. Почти всё работает без аккаунта; только браузерному симулятору требуется вход через поток OAuth 2.0 device-code. Без оплаты.

Поддерживаемые агенты

Различия для каждого хоста AI-агентов по кодингу, которые запускают Extentos — Claude Code, Cursor, Windsurf, Cline, встроенные в IDE. Область применения, кроссплатформенный охват, поддержка MCP.

Умные очки Apple

Умные очки Apple для сторонних разработчиков — доступ к SDK, модель приложения, распространение, возможности и ИИ, и их место в ландшафте умных очков 2026 года.

Установка MCP-сервера