Extentos MCP

官方

Extentos是一个多供应商开发平台，用于为现有的iOS和Android应用添加智能眼镜功能。最简单的类比是智能眼镜领域的Stripe。

访问 extentos.com

你可以用 Extentos MCP 做什么？

发现平台能力和 SDK 功能 — 在编写任何代码之前，调用 getPlatformInfo 获取 Meta Ray-Ban 能力的完整目录、库版本和供应商层级。
获取规范代码示例和使用指南 — 使用 getCodeExample 和 getCapabilityGuide 获取语音助手、显示交互、转录及其他 SDK 原语的 Kotlin/Swift 模式。
搭建完整的连接模块 — 运行 generateConnectionModule 将 Gradle/SPM 配置、权限、清单条目以及 Extentos 连接页面引导到原生项目中。
在测试前验证项目正确性 — 调用 validateIntegration 检查清单声明、依赖版本、权限覆盖范围以及针对已声明能力的引导调用。
配置并驱动模拟器会话 — 调用 createSimulatorSession 创建基于浏览器的会话，然后使用 injectTranscript、assertToolCalled 和 getEventLog 运行无需人工参与的代理驱动端到端测试。
审计生产就绪状态 — 在发布前运行 getProductionChecklist 和 getCredentialGuide，验证凭据配置、前台服务要求以及商店上架准备情况。

文档

MCP 服务器

Extentos MCP 服务器 (@extentos/mcp-server\) 是一个 npm 包，AI 代理（Claude Code、Cursor、Windsurf、Cline）只需安装一次，即可用于为原生 iOS 或 Android 应用添加 Meta Ray-Ban 智能眼镜功能。它提供了一组紧凑的确定性工具，涵盖 10 个类别——发现、生成、代理配置、凭据、分析、指导、验证、模拟、生产就绪和文档——外加一个用于账户关联、遥测同意和更新检查的 CLI。本文档是代理的操作手册。

MCP 服务器是 AI 代理（Claude Code、Cursor、Windsurf、Cline 或任何兼容模型上下文协议的主机）操作 Extentos 的方式。代理调用确定性工具；服务器会告知代理眼镜所具备的功能，返回 Kotlin 和 Swift 的规范 SDK 代码模式，搭建项目脚手架，代理模拟器会话，并查询调试跟踪。服务器本身没有规划工具——代理是比正则表达式包更好的规划者。工具是代理按顺序组合的类型化原语。

本页是章节概览——介绍服务器是什么、工具一览、规范的代理驱动流程、配置选项、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（第四阶段规范语音助手流程）和 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 连接、依赖项、权限、清单。两次调用流程：第一次调用不带 placement 参数，返回一个问题，询问 ExtentosConnectionPage 应放在何处；第二次调用带上所选位置，返回完整的文件集。
getConnectionPageConfig / setConnectionPageConfig	读取/写入仪表板/服务器持有的每个项目的连接页面配置（主题标记 + 部分可见性）。
regenerateConnectionPageFile / adoptConnectionPageFile	将已提交的 extentos.connection-page.json 与服务器配置同步——重新生成（服务器→文件）或采用（文件→服务器）。

搭建脚手架后，代理会根据 getCapabilityGuide / getCodeExample 提供的 SDK 原语编写自己的处理程序类。处理程序代码是客户的创作界面——没有 initSpec 或 DSL 填充步骤。

3. 代理配置和使用（3 个工具）

账户范围——需要关联账户，并按项目由 MCP 访问授权（默认读写）控制。

工具	功能
getAssistantConfig / setAssistantConfig	读取或更改项目仪表板管理的助手设置——OpenAI Realtime 模型、语音、记忆（压缩）模型以及会话内记忆模式。set 是部分更新，会根据目录验证每个值，并反馈模型更改的成本影响。
getGatewayUsage	读取项目托管网关在最近一段时间内的使用情况和确切成本——来自计费账本的令牌计数和标价美元，按模型细分。仅元数据，绝不包含转录文本或内容。

4. 凭据（2 个工具）

账户范围 + 按项目控制。写入而不知——密钥绝不经过代理。

工具	功能
getCredentialStatus	读取项目的 OpenAI API 密钥（BYOK）和 Meta DAT 构建身份是否已设置——仅返回掩码提示和更新时间，绝不包含值。
setCredential	启动凭据的“写入而不知”录入——返回一个仪表板链接，已登录的所有者可将密钥直接粘贴到加密保管库中。设计上不接受任何密钥参数。

5. 分析（1 个工具）

工具	功能
getProjectAnalytics	读取项目的生产分析数据——来自已发布的 App Store / Play Store 安装的聚合遥测数据（事件、活跃安装数，按事件/天/供应商/平台分类）。仅元数据，账户范围，所有权检查，由分析授权控制。在应用发布并发送生产验证事件之前为空（使用 getEventLog 获取实时开发/模拟流）。

6. 实现指导（2 个工具）

代理在编写代码过程中调用的辅助工具。

工具	功能
getVoiceCommandGuidance	在将唤醒/命令短语接入 glasses.audio.transcriptions() 消费者之前，分析提议的短语是否存在用户体验问题（冲突、歧义、难以识别的词、Meta 唤醒词冲突）。
getPermissions	从功能列表中推导出确切的平台权限、Meta DAT 要求以及前台服务需求。在向处理程序添加或移除原语时运行。

7. 验证（2 个工具）

正确性检查。在结构更改（声明新功能、升级依赖项、编辑清单）后运行。

工具	功能
inspectIntegration	只读项目快照 — 清单、生成文件哈希、依赖列表、连接页面配置。在手动编辑前运行，以了解当前状态。
validateIntegration	全项目正确性检查 — 清单、生成文件、依赖声明、权限覆盖已声明能力、引导调用 ExtentosGlasses.create(...)、工具链版本、用于连续捕获流程的前台服务提示。预测试关卡。

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 吸收严重性≥warn 的事件，无论其模态如何。外加 cursor、follow、limit 用于跟踪级别范围。主要的调试工具。
getSimulatorStatus	读取实时会话的当前状态 — 阶段、硬件就绪、附加角色、活跃能力流、当前开关值。
injectTranscript / injectAssistantUtterance / assertToolCalled	驱动唤醒词或助手轮次，然后断言模型调用了哪个工具 — 代理驱动的端到端循环，无需人工。
setSimVideo / setSimDevice	将测试视频导入模拟摄像头；切换模拟设备型号（例如 rayban_display 以测试显示路径）。
getDisplayState / injectInput	读取当前渲染的显示树 + 驱动显示输入（选择/导航/返回）。

9. 生产环境（2 个工具）

发布前检查。

工具	功能
getProductionChecklist	基于已声明能力和处理程序名称的个性化生产就绪清单 — 凭证连接、权限审计、前台服务要求（使用连续捕获时）、从发布版本中移除模拟器 URL、应用商店列表就绪情况。
getCredentialGuide	为生产环境 AI 提供商逐步设置凭证 — 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 是已弃用的 Phase-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。主题 ID 是稳定的；实时工具输入是权威的。

包含输入模式、响应形式和完整示例的完整工具参考：/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 服务器（代理使用的路径）。带有子命令时，它充当开发者 CLI：

子命令	功能描述
login	通过设备码流程将此安装关联到 Extentos 账户（主动操作 — 在首次模拟器会话之前使用，或在注销后重新关联时使用）。
logout	清除 ~/.extentos/auth.json。安装将恢复为匿名层级；下次模拟器会话调用将重新触发设备码流程。
whoami	尚未实现（Phase-0 存根）。将打印 installId、accountId（如果已关联）、层级、认证过期时间。
setup	预检本地构建环境 — 检查传递性 Meta DAT 工件所需的 GitHub Packages PAT（read:packages），以及其他依赖项先决条件。
accept-privacy	记录隐私同意（启用遥测上传）。
decline-privacy	记录隐私拒绝（禁用遥测上传）。
status	打印同意状态、安装 ID、关联账户、MCP/库版本。
update	检查 MCP 服务器更新（对于 npx @latest 安装为无操作）。

完整 CLI 参考：/docs/mcp-server/auth。

认证模型

MCP 服务器是匿名优先的。发现、能力指南、代码示例、验证、文档搜索、设备端模拟和真实硬件测试均无需登录即可使用。关联免费账户涉及三件事：创建浏览器模拟器会话（createSimulatorSession，HTTP 402）、generateConnectionModule 脚手架步骤（它会创建您账户绑定的项目密钥 — 同样的 402 设备码流程；首次信息性调用是匿名的），以及账户范围的项目工具（助手配置、凭据、连接页面写入、分析 — HTTP 401）。

设备码流程：首次受控调用返回 status: "auth_required" 并附带验证 URL。代理调用 completeAuthLink 轮询后端；开发者在 URL 处使用免费仅需邮箱的账户注册（Google 或邮箱 + 密码，无需付款）；后端颁发令牌；原始工具调用自动重试。关联后，模拟器会话无限制。

Extentos 的工具、代码生成、验证、SDK 和浏览器模拟器都是免费的 — 构建和交付没有按席位或订阅费用。唯一计量使用量的部分是 Phase-4 语音助手背后的托管 AI 网关。完整认证模型：/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 — ~/.cursor/mcp.json 中的 JSON 配置。
Windsurf — ~/.codeium/windsurf/mcp_config.json 中的 JSON 配置。
Cline — Cline 的 MCP 设置中的 JSON 配置。
任何兼容 MCP 的主机 — 放入标准的 mcpServers.extentos JSON 块即可。

MCP 服务器通过 stdio（@modelcontextprotocol/sdk）使用标准 MCP 协议通信；服务器端不存在特定于主机的代码路径。各主机安装步骤：/docs/mcp-server/agents。

本地桥接 — 自动绑定开发循环

服务器启动时，会打开一个 127.0.0.1:31337/whoami HTTP 监听器（mcp-server/src/localBridge.ts）。开发者应用中的 Extentos 库在运行时探测此端点，以获取其主机 MCP 的 installId。结果是：代理发出的每个 createSimulatorSession 调用都会自动将正在运行的应用附加到新会话 — 无需重建，无需粘贴 URL。

可达路径：

Android 模拟器： http://10.0.2.2:31337/whoami（主机环回 NAT 别名）
iOS 模拟器： http://localhost:31337/whoami（共享主机网络命名空间）
通过 USB 连接的物理 Android 手机： 一次 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 嵌入路径，直到端口释放。

状态

包： npm 上的 @extentos/mcp-server（MIT 许可证）
引擎： Node.js 20+
Pre-1.0 — 在硬件测试循环关闭之前，API 可能在次要版本之间变动。如果需要跨会话的可重现性，请固定到确切版本。