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 應放置的位置；第二次調用帶有選定的 placement 參數，則回傳完整的檔案集。
getConnectionPageConfig / setConnectionPageConfig	讀取／寫入儀表板／伺服器所持有的每個專案的連接頁面設定（主題標記 + 區塊可見性）。
regenerateConnectionPageFile / adoptConnectionPageFile	將已提交的 extentos.connection-page.json 與伺服器設定同步——regenerate（伺服器→檔案）或 adopt（檔案→伺服器）。

搭建完成後，代理會根據 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() 消費者之前，分析其潛在的 UX 問題（衝突、歧義、難以辨識的詞彙、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"（匿名安裝需要連結以建立工作階段）後，輪詢後端直到使用者完成註冊，然後將 bearer token 保存到 ~/.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 且不帶任何引數，會透過 stdio 啟動 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" 和一個驗證網址。代理程式會呼叫 completeAuthLink 來輪詢後端；開發人員在該網址使用免費的僅電子郵件帳戶註冊（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 使用標準 MCP 協定（@modelcontextprotocol/sdk）；伺服器端不存在主機特定的程式碼路徑。各主機安裝步驟：/docs/mcp-server/agents。

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

當伺服器啟動時，它會開啟一個 127.0.0.1:31337/whoami HTTP 監聽器（mcp-server/src/localBridge.ts）。開發人員應用程式上的 Extentos 函式庫會在執行階段探查此端點，以了解其主機 MCP 的 installId。結果是：來自代理程式的每個 createSimulatorSession 呼叫都會自動將正在執行的應用程式附加到新的工作階段 — 無需重建，無需貼上網址。

可達路徑：

Android 模擬器： http://10.0.2.2:31337/whoami（主機迴路 NAT 別名）
iOS 模擬器： http://localhost:31337/whoami（共享主機網路命名空間）
透過 USB 連接的實體 Android 手機： adb reverse tcp:31337 tcp:31337 一次，然後從裝置 localhost:31337
蜂巢式網路手機或雲端託管的代理程式： 探查逾時。代理程式改為使用網址嵌入路徑 — createSimulatorSession 會傳回開發人員貼上的 BuildConfig.EXTENTOS_SESSION_URL 程式碼片段（Android）或 extentos.session.plist 酬載（iOS），然後重建應用程式一次。不如自動綁定優雅，但在任何拓撲上都能運作。

僅綁定到 127.0.0.1。installId 不是秘密 — 它與 MCP 在每次工具呼叫時傳送給 api.extentos.com 的值相同。此層無需驗證。

如果連接埠 31337 正在使用中（罕見；另一個 MCP 執行個體已在執行），啟動時會記錄一個警告並繼續。該工作階段的自動綁定會靜默失敗；開發人員將使用網址嵌入路徑，直到連接埠釋放。

狀態

套件： npm 上的 @extentos/mcp-server（MIT 授權）
引擎： Node.js 20+
1.0 之前 — API 在硬體測試迴圈關閉之前，可能會在次要版本之間變動。如果您需要跨工作階段的重現性，請釘選到確切的版本。