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 接線、相依性、權限、manifest。兩次呼叫流程：第一次呼叫不含 `placement` 會回傳一個問題，詢問 `ExtentosConnectionPage` 應放置何處；第二次呼叫帶入所選位置則回傳完整檔案集。
`getConnectionPageConfig` / `setConnectionPageConfig`	讀取／寫入每個專案的連線頁面設定（主題 token + 區段可見性），由儀表板／伺服器持有。
`regenerateConnectionPageFile` / `adoptConnectionPageFile`	將已提交的 `extentos.connection-page.json` 與伺服器設定同步——重新生成（伺服器→檔案）或採用（檔案→伺服器）。

搭建完成後，代理會針對 getCapabilityGuide / getCodeExample 所暴露的 SDK 基本單元撰寫自己的處理器類別。處理器程式碼是客戶的創作介面——沒有 initSpec 或 DSL 填充步驟。

3. 代理設定與使用（5 個工具）

帳戶範圍——需要已連結的帳戶，並依專案由 MCP 存取授權（預設為讀取+寫入）控管。

工具	功能
`getAssistantConfig` / `setAssistantConfig`	讀取或變更專案的儀表板管理助理設定——OpenAI Realtime 模型、語音、記憶（壓縮）模型，以及工作階段內記憶模式。`set` 是部分更新，會針對目錄驗證每個值，並反映模型變更的成本影響。
`getGatewayUsage`	讀取專案的受管閘道使用量 + 近期時間範圍內的確切成本——來自帳單分類帳的 token 計數與美元列表價格，依模型細分。僅限中繼資料，絕不含逐字稿或內容。

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 個工具）

正確性閘門。在結構變更後執行（宣告新能力、相依性升級、manifest 編輯）。

工具	功能
`inspectIntegration`	唯讀專案快照——manifest、生成檔案雜湊、相依性清單、連線頁面設定。在手動編輯前執行以了解目前狀態。
`validateIntegration`	全專案正確性檢查——manifest、生成檔案、已宣告相依性、權限涵蓋已宣告能力、引導呼叫 `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 token 持久化到 `~/.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 穩定；即時工具輸入為權威來源。

完整的逐工具參考，含輸入 schema、回應形狀與實作範例：/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 伺服器（也就是 agent 所使用的路徑）。若帶有子命令，則會作為開發者 CLI 使用：

子命令	功能
`login`	透過 device-code 流程將此安裝連結至 Extentos 帳號（主動式操作 — 在首次模擬器工作階段之前，或於 `logout` 之後重新連結時相當實用）。
`logout`	清除 `~/.extentos/auth.json`。安裝會回到匿名層級；下一次模擬器工作階段呼叫會重新觸發 device-code 流程。
`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 device-code 流程；資訊性的首次呼叫是匿名的），以及帳號範圍的專案工具（助理設定、憑證、連線頁面寫入、分析 — HTTP 401）。

Device-code 流程：第一次受限制的呼叫會回傳 status: "auth_required"，其中包含驗證 URL。Agent 呼叫 completeAuthLink 來輪詢後端；開發者在該 URL 以免費的純電子郵件帳號註冊（Google 或電子郵件＋密碼，無需付款）；後端發行 token；原始工具呼叫會自動重試。連結之後，模擬器工作階段即無限制。

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（@modelcontextprotocol/sdk）使用標準 MCP 協定；伺服器端沒有主機特定的程式碼路徑。各主機的安裝步驟：/docs/mcp-server/agents。

本機橋接 — 自動綁定開發迴圈

伺服器啟動時，會開啟一個 127.0.0.1:31337/whoami HTTP 監聽器（mcp-server/src/localBridge.ts）。開發者應用程式中的 Extentos 函式庫會在執行時期探查此端點，以得知其主機 MCP 的 installId。結果是：agent 的每一次 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
行動網路手機或雲端託管 agent： 探查會逾時。Agent 改用 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 可能在次要版本之間變動，直到硬體測試迴圈關閉為止。若需要跨工作階段的可重現性，請固定到確切版本。