# @extentos/mcp-server

MCP server for building Meta-glasses apps with Claude Code and other MCP-aware coding agents. Exposes a tight set of deterministic tools that prime the agent on what the glasses can do, return canonical SDK code patterns in Kotlin and Swift, scaffold a fresh project, and drive a browser-based simulator for testing without physical hardware.

The library itself is a pure Kotlin/Swift SDK — your handler code subscribes to capability primitives like `glasses.audio.transcriptions()`, `glasses.camera.capturePhoto()`, and `glasses.audio.speak()` directly. There is no spec runtime, no DSL, no manifest dispatch — the MCP server's job is to help an AI agent compose against the SDK quickly and correctly.

## Install

Register the server with Claude Code (or any MCP host) in one line:

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

Restart Claude Code. `/mcp` should list `extentos` with all tools available.

Prerequisites: Node.js 20+ on `PATH`. That's it — `npx` fetches the package on first run and caches it.

## Getting started (for the agent)

The agent plans composition itself. Start with discovery, then scaffold, then write handler code.

**Discovery (read these first; cheap, all local):**

- `getPlatformInfo({ sections: ["version", "capabilities"], glasses: "meta_rayban" })` — what SDK features the glasses expose (`transcription_incremental`, `capture_photo`, `speak`, `record_audio`, …).
- `getCapabilityGuide(feature)` — per-feature minimal Kotlin + Swift snippet + gotchas. Read for each capability you plan to use.
- `getCodeExample(pattern)` — full canonical compositions. Start with `assistant_agent_loop` (the canonical voice-assistant flow) and `agent_driven_e2e_full_loop` (the agent-driven E2E test); the legacy compositions (voice Q&A, barge-in, photo + vision LLM + speak, live transcription UI, voice notes, connection-page bootstrap) are there too. Peel from these when writing your handler.
- `searchDocs({ topic: "getting_started" })` — index of conceptual topics covering the connection state model, toggles, permissions, simulator behaviour, multi-platform projects, etc.

**Generation sequence (deterministic):**

1. `generateConnectionModule({ platform, glasses, appPackage })` — one-shot scaffold (bootstrap module, Gradle/SPM wiring, manifest, permissions). Returns a placement question the first time — surface it; the dev chooses where `ExtentosConnectionPage` should live.
2. Write your handler classes — subscribe to SDK primitives from your `Application` (Android) or `@main App` (iOS) using the patterns from `getCodeExample`.
3. Update the manifest's `capabilities` array with the SDK feature names your handler uses.
4. `validateIntegration` — pre-test correctness gate. Re-run after structural changes.
5. `createSimulatorSession` — provision a browser-hosted glasses surrogate.

**Iteration:** rebuild + reinstall your app — the simulator picks up the new binary automatically thanks to auto-bind; the session URL is stable.

**Debugging:** `getEventLog`, `getSimulatorStatus`. **Ship-readiness:** `getProductionChecklist`. **Credentials:** `getCredentialGuide` (BYOK providers + Meta DAT registration).

## Features

- **Account required for browser-simulator sessions and the account-scoped tools** (managed-gateway usage, credentials, assistant config, analytics, connection-page publish). First `createSimulatorSession` call triggers the device-code flow — your agent surfaces a verification URL, you sign in once (Google or email, no payment), and simulator sessions are then unlimited. Discovery, scaffolding, and validation tools work without an account.
- **Persistent simulations (get-or-create).** `createSimulatorSession` returns the saved sim for `(account, project, platform)` if one already exists (`status: "resumed"`); first call from a project mints a new one (`status: "active"`). Saved sims live indefinitely on your account dashboard at https://extentos.com/s — Reset rotates the ID for a clean slate (`resetFresh: true` does the same from a tool call); Delete removes it. No 24-hour lifetime cap; sessions that go unused enter `idle` state and resume the moment the host app reconnects.
- **Auto-bind dev loop.** Once the library is in your app, the MCP and library coordinate via a `127.0.0.1:31337/whoami` localhost bridge. The running app auto-attaches to the saved sim on cold launch — no rebuild, no URL paste, no typed code in the happy path. Works on Android and iOS.
- **Browser simulator surrogate.** Camera, mic, hardware alerts, notifications, replay — all browser-side; no physical glasses needed for the bulk of the dev loop. The simulator runs the same library code as production with only the transport swapped.

## Platforms

- **Android** — primary target. The library is published to Maven Central (`com.extentos:glasses` + `com.extentos:glasses-ui`) — it resolves from the default `mavenCentral()` repo, no extra setup.
- **iOS** — the Swift package is published from [`github.com/extentos/swift-glasses`](https://github.com/extentos/swift-glasses): add it with `.package(url: "https://github.com/extentos/swift-glasses", from: "1.7.0")` (products `GlassesCore` + `GlassesUI`). Both SDKs publish in lockstep. The same MCP tool surface and generated artifacts apply (`extentos.session.plist` instead of `buildConfigField`), and auto-bind works on iOS too.

## Status

The MCP server is pre-1.0 (0.x) — APIs may shift between minor versions until the hardware test loop closes. The Android library line is 1.x on Maven Central. If you need reproducibility across sessions, pin to a specific version from the package's [npm page](https://www.npmjs.com/package/@extentos/mcp-server) instead of `@latest`.

## License

MIT — see [LICENSE](https://github.com/extentos/mcp-server/blob/main/LICENSE). Issues and feedback: [github.com/extentos/mcp-server](https://github.com/extentos/mcp-server/issues).