Extentos MCP

官方

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

你可以用 Extentos MCP 做什么？

搭建智能眼镜应用脚手架 — 让您的智能体运行 generateConnectionModule，一次性完成 iOS/Android 模块的 Gradle/SPM 配置、权限和清单文件引导。
获取规范代码模式 — 使用 getCodeExample 获取语音助手、实时转录、照片描述及其他 SDK 能力的完整 Kotlin/Swift 实现。
验证集成正确性 — 在测试前运行 validateIntegration 检查清单、权限、依赖和引导调用，及早发现问题。
驱动模拟器会话 — 使用 createSimulatorSession 创建并操作基于浏览器的会话，注入转录文本或硬件按钮，并断言工具调用以进行智能体驱动的端到端测试。
通过事件追踪调试 — 通过 getEventLog 获取结构化日志，按错误、语音、摄像头、显示或 AI 过滤，以诊断实时会话中的问题。
检查生产就绪状态 — 运行 getProductionChecklist 获取个性化的发布前审计，涵盖凭据、权限和应用商店上架要求。

文档

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 或任何 Model Context Protocol 兼容主机——操作 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 参考（4 个工具）

任何新任务中的首次调用。廉价、全部本地、无副作用。

工具	功能
`getPlatformInfo`	返回静态平台目录——库版本、眼镜暴露的 SDK 能力列表、各供应商层级。始终是正确的首次调用。
`getCapabilityGuide`	每个功能的 Kotlin + Swift 最小用法——调用形状、配置参数、注意事项。与 `getPlatformInfo`（命名功能）配对，告诉代理如何调用每个功能。
`getCodeExample`	两种语言的完整规范组合。从 `assistant_agent_loop`（Phase-4 规范语音助手流程）和 `agent_driven_e2e_full_loop`（代理驱动的 E2E 测试）开始。还涵盖 `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。
`getMigrationGuide`	对于已基于原始 Meta DAT 构建的应用——返回以现有 DAT 符号为键的映射，指向替换它们的 Extentos 原语，外加有序的切换计划。

2. 设置和生成

工具	功能
`generateConnectionModule`	一键脚手架——引导模块、Gradle/SPM 接线、依赖、权限、清单。两次调用流程：第一次调用不带 `placement` 返回一个问题，询问 `ExtentosConnectionPage` 应放在哪里；第二次调用带所选位置返回完整文件集。
`getConnectionPageConfig` / `setConnectionPageConfig`	读取 / 写入仪表板/服务器持有的每项目连接页面配置（主题令牌 + 章节可见性）。
`regenerateConnectionPageFile` / `adoptConnectionPageFile`	将提交的 `extentos.connection-page.json` 与服务器配置同步——重新生成（服务器→文件）或采用（文件→服务器）。

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

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

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

工具	功能
`getAssistantConfig` / `setAssistantConfig`	读取或更改项目的仪表板管理的助手设置——OpenAI Realtime 模型、语音、记忆（压缩）模型以及会话内记忆模式。`set` 是部分更新，根据目录验证每个值，并回显模型更改的成本影响。
`getGatewayUsage`	读取项目的托管网关使用量 + 最近窗口内的精确成本——来自计费账本的令牌计数和列表价美元，按模型细分。仅元数据，绝无转录或内容。

4. 凭据（2 个工具）

账户范围 + 按项目门控。不知情写入——秘密绝不经过代理。

工具	功能
`getCredentialStatus`	读取项目的 Meta DAT 构建身份是否已设置——仅掩码提示 + 更新时间，绝无值。
`setCredential`	开始凭据的不知情写入——返回一个仪表板链接，已登录的所有者将秘密直接粘贴到加密保险库中。设计上不接受秘密参数。

5. 分析（1 个工具）

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

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

代理在组合期间调用的支线工具。

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

7. 验证（2 个工具）

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

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

8. 模拟

配置和操作基于浏览器的模拟器会话，外加无需人工即可闭环端到端的代理驱动测试工具。

工具	功能
`createSimulatorSession`	在 extentos.com/s 获取或创建浏览器模式会话。如果存在则返回此项目的已保存模拟（`status: "resumed"`），否则铸造新会话（`status: "active"`）。通过本地桥接在可达时自动附加运行中的应用；否则发出 `BuildConfig.EXTENTOS_SESSION_URL` 片段（Android）或 `extentos.session.plist` 负载（iOS）。轮换 sessionId 是 `deleteSimulatorSession` 然后铸造——没有强制刷新标志。
`ensureSimulatorBrowser`	打开 + 确认已连接的模拟器浏览器标签——相机和注入流程的前提条件。
`completeAuthLink`	在 `createSimulatorSession` 返回 `status: "auth_required"`（匿名安装需要链接以铸造会话）后，轮询后端直到用户完成注册，然后将 bearer 令牌持久化到 `~/.extentos/auth.json`。
`getEventLog`	从会话获取结构化事件跟踪。过滤值：`all`（无过滤）加上七个芯片 `errors`、`voice`、`camera`、`display`、`ai`、`lifecycle`、`custom`——每个事件一个芯片，`errors` 吸收严重性≥警告，无论模态如何。外加 `cursor`、`follow`、`limit` 用于跟踪级范围。主要调试工具。
`getSimulatorStatus`	读取实时会话的当前状态——阶段、硬件就绪、附加角色、活跃能力流、当前切换值。
`injectTranscript` / `injectAssistantUtterance` / `assertToolCalled`	驱动唤醒短语或助手回合，然后断言模型调用了哪个工具——代理驱动的 E2E 循环，无需人工。
`injectHardwareButton`	按下模拟眼镜的硬件拍摄按钮——点击暂停/恢复实时相机流，按住停止——让代理无需人工即可练习佩戴者的隐私手势（并测试产生的 `CaptureError.StreamPaused`）。
`setSimVideo` / `setSimDevice`	将测试视频管道输入模拟相机；切换模拟设备型号（例如 `rayban_display` 以练习显示路径）。
`getDisplayState` / `injectInput`	读取当前渲染的显示树 + 驱动显示输入（`select` / `navigate` / `back`）。

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。其他对齐主题：voice_integration、agent_e2e_testing、managed_gateway、conversation_memory、display，外加稳定的概念集——getting_started、custom_handlers（规范 SDK 组合文档）、simulator_browser_mode、simulator_session_lifecycle、event_log_schema、toggles、library_api、permissions、multi_platform_projects。主题 ID 稳定；实时工具输入是权威的。

工具	功能
`searchDocs`	按主题或关键词搜索 Extentos 文档。对于语音助手，先阅读 `assistant_runtime`。其他对齐主题：`voice_integration`、`agent_e2e_testing`、`managed_gateway`、`conversation_memory`、`display`，外加稳定的概念集——`getting_started`、`custom_handlers`（规范 SDK 组合文档）、`simulator_browser_mode`、`simulator_session_lifecycle`、`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 子命令

Running npx @extentos/mcp-server@latest 时不带参数，将通过 stdio 启动 MCP 服务器（即代理使用的路径）。带子命令时，它充当开发者 CLI：

子命令	功能
`login`	通过设备码流程将此安装链接到 Extentos 账户（主动操作——在首次模拟器会话之前或 `logout` 之后重新链接时很有用）。
`logout`	清除 `~/.extentos/auth.json`。安装恢复到匿名层级；下一次模拟器会话调用将重新触发设备码流程。
`whoami`	尚未实现（Phase-0 占位）。将打印 `installId`、`accountId`（如果已链接）、层级、认证过期时间。
`setup`	预检本地构建环境——检查 Meta DAT 工件所需的 GitHub Packages PAT（`read:packages`），适用于依赖 `com.extentos:glasses-meta` 的应用，以及其他依赖前提条件。
`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 — JSON 配置位于 ~/.cursor/mcp.json。
Windsurf — JSON 配置位于 ~/.codeium/windsurf/mcp_config.json。
Cline — JSON 配置位于 Cline 的 MCP 设置中。
任何兼容 MCP 的主机 — 放入标准 mcpServers.extentos JSON 块即可。

MCP 服务器通过 stdio 使用标准 MCP 协议（@modelcontextprotocol/sdk）；服务器端没有主机特定代码路径。各主机安装步骤：/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 烘焙路径，直到端口释放。

状态

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