{"_id":"openreality-mcp","_rev":"7-ca50f3e1a6ebd6aa152d831ef356e1a6","name":"openreality-mcp","dist-tags":{"latest":"0.4.0"},"versions":{"0.1.0":{"name":"openreality-mcp","version":"0.1.0","keywords":["mcp","modelcontextprotocol","claude","3d","slam","robotics","openreality"],"license":"BSD-2-Clause","_id":"openreality-mcp@0.1.0","maintainers":[{"name":"galoiz","email":"galois77777@gmail.com"}],"homepage":"https://open-reality.io/mcp","bin":{"openreality-mcp":"dist/cli.js"},"dist":{"shasum":"1d0e1b02aa28637e4fd058bb3678bf96c08c2629","tarball":"https://registry.npmjs.org/openreality-mcp/-/openreality-mcp-0.1.0.tgz","fileCount":5,"integrity":"sha512-v3SI5vxn2YlIv9TT+ygh9SYSbV8namocqcge2QR1JVgRqbmEkDXSiOMQAB1LMHBqg42ygyFfdf4IV2FE7S2QLg==","signatures":[{"sig":"MEQCIBVImOKjQeTV8soWR7S6EL+nzZaycqKohUlAuGRoqPTYAiAmddh1uZCib+Vh5BHFW+9YUFVwG07Zo8lExoB20axn5Q==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":442550},"type":"module","engines":{"node":">=20"},"scripts":{"test":"npm run build && vitest run","build":"tsup","simulator":"npm run build && node dist/cli.js simulator","typecheck":"tsc --noEmit"},"_npmUser":{"name":"galoiz","email":"galois77777@gmail.com"},"_npmVersion":"10.8.2","description":"Open Reality OS as MCP tools — drive scan upload, reconstruction, scene query, scene agents, and robot-training exports from Claude Code / Claude desktop.","directories":{},"_nodeVersion":"20.20.2","dependencies":{"zod":"^3.25.76","@modelcontextprotocol/sdk":"^1.30.0"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.3.5","vitest":"^2.0.0","typescript":"6.0.3","@types/node":"^20.17.0","@reality/protocol":"file:../../packages/protocol"},"_npmOperationalInternal":{"tmp":"tmp/openreality-mcp_0.1.0_1786466048927_0.5090948033375844","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"openreality-mcp","version":"0.1.1","keywords":["mcp","modelcontextprotocol","claude","3d","slam","robotics","openreality"],"license":"BSD-2-Clause","_id":"openreality-mcp@0.1.1","maintainers":[{"name":"galoiz","email":"galois77777@gmail.com"}],"homepage":"https://open-reality.io/mcp","bin":{"openreality-mcp":"dist/cli.js"},"dist":{"shasum":"e4f38c4b31b0b258e0c337e8fd666bff80518ec7","tarball":"https://registry.npmjs.org/openreality-mcp/-/openreality-mcp-0.1.1.tgz","fileCount":5,"integrity":"sha512-zjvn4H4HBtNXdDIwmuizbT6aNiIkNOs/TPdY9qOaxjCZWGoZYYv8CcZOYQZP+HutxriQxbWgkLsqist3hUF97Q==","signatures":[{"sig":"MEYCIQCR9ktefSfDlZt9ZItAcmLrBuOY9Qmz/7J7UISCOJ7n5wIhALdNrvzFnKQnlABF4qqFijOTfAr7Lp/D2hEY0ki4OtYI","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":442954},"type":"module","engines":{"node":">=20"},"scripts":{"test":"npm run build && vitest run","build":"tsup","simulator":"npm run build && node dist/cli.js simulator","typecheck":"tsc --noEmit"},"_npmUser":{"name":"galoiz","email":"galois77777@gmail.com"},"_npmVersion":"10.8.2","description":"Open Reality OS as MCP tools — drive scan upload, reconstruction, scene query, scene agents, and robot-training exports from Claude Code / Claude desktop.","directories":{},"_nodeVersion":"20.20.2","dependencies":{"zod":"^3.25.76","@modelcontextprotocol/sdk":"^1.30.0"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.3.5","vitest":"^2.0.0","typescript":"6.0.3","@types/node":"^20.17.0","@reality/protocol":"file:../../packages/protocol"},"_npmOperationalInternal":{"tmp":"tmp/openreality-mcp_0.1.1_1786467324301_0.8730567120645005","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"openreality-mcp","version":"0.2.0","keywords":["mcp","modelcontextprotocol","claude","3d","slam","robotics","openreality"],"license":"BSD-2-Clause","_id":"openreality-mcp@0.2.0","maintainers":[{"name":"galoiz","email":"galois77777@gmail.com"}],"homepage":"https://open-reality.io/mcp","bin":{"openreality-mcp":"dist/cli.js"},"dist":{"shasum":"701727d07a5d68965a13a8ab8de78d9f3ef762b0","tarball":"https://registry.npmjs.org/openreality-mcp/-/openreality-mcp-0.2.0.tgz","fileCount":5,"integrity":"sha512-LaVmTWjT+R/qPiaUIOawUdgOSXQue9dTWz2MH1nz2Nq8q+PXDpIobHTk7AoHg6nEGd4/TFi054PK+AOa4LoPOw==","signatures":[{"sig":"MEUCIFwpesm+X34BW82jH98gXqdJ2AK/gUzzKbmsp/4zXndfAiEAsrlvqhTm7+WdQ9DOeuHAnqusE16XqzWbhva7lk1ltDo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":449639},"type":"module","engines":{"node":">=20"},"scripts":{"test":"npm run build && vitest run","build":"tsup","simulator":"npm run build && node dist/cli.js simulator","typecheck":"tsc --noEmit"},"_npmUser":{"name":"galoiz","email":"galois77777@gmail.com"},"_npmVersion":"10.8.2","description":"Open Reality OS as MCP tools — drive scan upload, reconstruction, scene query, scene agents, and robot-training exports from Claude Code / Claude desktop.","directories":{},"_nodeVersion":"20.20.2","dependencies":{"zod":"^3.25.76","@modelcontextprotocol/sdk":"^1.30.0"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.3.5","vitest":"^2.0.0","typescript":"6.0.3","@types/node":"^20.17.0","@reality/protocol":"file:../../packages/protocol"},"_npmOperationalInternal":{"tmp":"tmp/openreality-mcp_0.2.0_1786490273651_0.9941200110803421","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"openreality-mcp","version":"0.2.1","keywords":["mcp","modelcontextprotocol","claude","codex","cursor","3d","slam","robotics","openreality"],"license":"BSD-2-Clause","_id":"openreality-mcp@0.2.1","maintainers":[{"name":"galoiz","email":"galois77777@gmail.com"}],"homepage":"https://open-reality.io/mcp","bin":{"openreality-mcp":"dist/cli.js"},"dist":{"shasum":"232a9849aae6e106cc0c817297467bfc7e032b2a","tarball":"https://registry.npmjs.org/openreality-mcp/-/openreality-mcp-0.2.1.tgz","fileCount":5,"integrity":"sha512-lKmbUwv1PQl6j1xpGSyDpCs6Ce0qTkyReBrTcSmxDwL5hzPutuy95R/CyyhHI8Sqimzuo2s1Fl9svoVlfxlONw==","signatures":[{"sig":"MEUCIHbzKfXyEoWExGo0agkwSQaUH/OBMnWd1vIC6dFk6WYDAiEAy2VuwF7OVbeECx2sbiuFDg/v94J7YLAWvo7r3MX/9eg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":457352},"type":"module","engines":{"node":">=20"},"gitHead":"023cdfc7bc4ecb1b7d05dec332824fda09e62284","scripts":{"test":"npm run build && vitest run","build":"tsup","simulator":"npm run build && node dist/cli.js simulator","typecheck":"tsc --noEmit"},"_npmUser":{"name":"galoiz","email":"galois77777@gmail.com"},"_npmVersion":"11.4.1","description":"Open Reality OS as MCP tools — drive scan upload, reconstruction, scene query, scene agents, and robot-training exports from Claude Code, Claude desktop, Codex, or Cursor.","directories":{},"_nodeVersion":"23.11.0","dependencies":{"zod":"^3.25.76","@modelcontextprotocol/sdk":"^1.30.0"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.3.5","vitest":"^2.0.0","typescript":"6.0.3","@types/node":"^20.17.0","@reality/protocol":"file:../../packages/protocol"},"_npmOperationalInternal":{"tmp":"tmp/openreality-mcp_0.2.1_1787108538548_0.5323824276545475","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"openreality-mcp","version":"0.3.0","keywords":["mcp","modelcontextprotocol","claude","codex","cursor","cordis","3d","slam","robotics","openreality"],"license":"BSD-2-Clause","_id":"openreality-mcp@0.3.0","maintainers":[{"name":"galoiz","email":"galois77777@gmail.com"}],"homepage":"https://open-reality.io/mcp","bugs":{"url":"https://github.com/reality-opened/openreality-mcp/issues"},"bin":{"openreality-mcp":"dist/cli.js"},"dist":{"shasum":"e55a3d962793019fceda48df4805a9389dec66e7","tarball":"https://registry.npmjs.org/openreality-mcp/-/openreality-mcp-0.3.0.tgz","fileCount":6,"integrity":"sha512-83EMe9LsgUIHftluZiJueo/pqV93Fzkv/9WFJK3uHnpKUxpUHAWhOWZXf0NiCqi45CTlIUIFBZhWSIHU3dE6HQ==","signatures":[{"sig":"MEYCIQCtbGpMV+VYBnPj5OzXTl/oMcsJr5TQogvmuK0zAlCoUwIhAN5mY4PblY0MHChcp3lcly4o3D9vVvn+HWoKpM4HUXo/","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":483587},"type":"module","engines":{"node":">=20"},"gitHead":"a518eda2b0fa1cdad31926f89db5cbd903a03ea9","scripts":{"test":"npm run build && vitest run","build":"tsup","simulator":"npm run build && node dist/cli.js simulator","typecheck":"tsc --noEmit","prepublishOnly":"npm run typecheck && npm run build"},"_npmUser":{"name":"galoiz","email":"galois77777@gmail.com"},"repository":{"url":"git+https://github.com/reality-opened/openreality-mcp.git","type":"git"},"_npmVersion":"11.19.0","description":"Open Reality OS as MCP tools: drive scan upload, reconstruction, scene query, scene agents, and robot-training exports from Claude Code, Claude desktop, Codex, or Cursor.","directories":{},"_nodeVersion":"24.20.0","allowScripts":{"esbuild@0.21.5":true,"esbuild@0.27.7":true},"dependencies":{"zod":"^3.25.76","cordis":"^4.0.0-rc.9","@modelcontextprotocol/sdk":"^1.30.0"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.3.5","vitest":"^2.0.0","typescript":"6.0.3","@types/node":"^20.17.0","@reality/protocol":"file:./vendor/protocol"},"_npmOperationalInternal":{"tmp":"tmp/openreality-mcp_0.3.0_1788295471854_0.12097598851414393","host":"s3://npm-registry-packages-npm-production"}},"0.3.1":{"name":"openreality-mcp","version":"0.3.1","keywords":["mcp","modelcontextprotocol","claude","codex","cursor","cordis","3d","slam","robotics","lerobot","3d-reconstruction","claude-code","openreality"],"license":"BSD-2-Clause","_id":"openreality-mcp@0.3.1","maintainers":[{"name":"galoiz","email":"galois77777@gmail.com"}],"homepage":"https://open-reality.io/mcp","bugs":{"url":"https://github.com/reality-opened/openreality/issues"},"bin":{"openreality-mcp":"dist/cli.js"},"dist":{"shasum":"8c51d8d25d5b417d51851f3397e0c869bb7566dd","tarball":"https://registry.npmjs.org/openreality-mcp/-/openreality-mcp-0.3.1.tgz","fileCount":6,"integrity":"sha512-Kuat59745ssXo3uUEdoARfnLcrs7Bi8MG96mAyiDC9PS9U9Nvv6QHecqTMZnsT04vCw6gP5TyWQ0XPJk/nlrfQ==","signatures":[{"sig":"MEUCIAZhqPRs9XfkqWsTbigq/qY32Wn1fw8cOOpBhglHgdJ3AiEAl9UD5gDjUGQJv3Olv5XKf/MaBvz6qifKSlaFpXtlYIc=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":491005},"type":"module","engines":{"node":">=20"},"gitHead":"4d93d5f5b75166a43f0fd64b7d44acc12a56907f","mcpName":"io.github.reality-opened/openreality-mcp","scripts":{"test":"npm run build && vitest run","build":"tsup","simulator":"npm run build && node dist/cli.js simulator","typecheck":"tsc --noEmit","build:mcpb":"bash scripts/build-mcpb.sh","prepublishOnly":"npm run typecheck && npm run build"},"_npmUser":{"name":"galoiz","email":"galois77777@gmail.com"},"repository":{"url":"git+https://github.com/reality-opened/openreality.git","type":"git","directory":"mcp"},"_npmVersion":"11.4.1","description":"Open Reality OS as MCP tools: drive scan upload, reconstruction, scene query, scene agents, and robot-training exports from Claude Code, Claude desktop, Codex, or Cursor.","directories":{},"_nodeVersion":"23.11.0","allowScripts":{"esbuild@0.21.5":true,"esbuild@0.27.7":true},"dependencies":{"zod":"^3.25.76","cordis":"^4.0.0-rc.9","@modelcontextprotocol/sdk":"^1.30.0"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.3.5","vitest":"^2.0.0","typescript":"6.0.3","@types/node":"^20.17.0","@reality/protocol":"file:./vendor/protocol"},"_npmOperationalInternal":{"tmp":"tmp/openreality-mcp_0.3.1_1788465645399_0.33998525908118493","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"_id":"openreality-mcp@0.4.0","bin":{"openreality-mcp":"dist/cli.js"},"bugs":{"url":"https://github.com/reality-opened/openreality/issues"},"dist":{"shasum":"b43e2b49f3a3b76fc5aef99f8c5be2336d27d716","tarball":"https://registry.npmjs.org/openreality-mcp/-/openreality-mcp-0.4.0.tgz","fileCount":6,"integrity":"sha512-t+WrjR0qCGzJkSO3Kz0WUxhkb7F6uNgmi2tMZgrlQSViqCIcKkRNXh5oKhSJjPlb8FumvsjKHA0x3Cv0KrBWOw==","signatures":[{"sig":"MEUCIGQfVxnsVCCrf/b91bsaEoeHrQJqp48Itk8okHcQF333AiEA9rPW4xt+qJd4Qe3v4e1y+ywsNRcfinEfG71fNaU+W8I=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCICDTgMfgOE8q3QMNtIxMspHUs3x+YhWFM6shhCF4Gt6jAiBNXNIIzgBW087HfmkZt29OzoqfmKDbyJkCSkhigvVl5g=="}],"unpackedSize":521542},"name":"openreality-mcp","type":"module","engines":{"node":">=20"},"gitHead":"e1fc76df512836f0c63c7bfbec9ea25462d79b5e","license":"BSD-2-Clause","mcpName":"io.github.reality-opened/openreality-mcp","scripts":{"test":"npm run build && vitest run","build":"tsup","simulator":"npm run build && node dist/cli.js simulator","typecheck":"tsc --noEmit","build:mcpb":"bash scripts/build-mcpb.sh","prepublishOnly":"npm run typecheck && npm run build"},"version":"0.4.0","_npmUser":{"name":"galoiz","email":"galois77777@gmail.com"},"homepage":"https://open-reality.io/mcp","keywords":["mcp","modelcontextprotocol","claude","codex","cursor","cordis","3d","slam","robotics","lerobot","3d-reconstruction","claude-code","openreality"],"repository":{"url":"git+https://github.com/reality-opened/openreality.git","type":"git","directory":"mcp"},"_npmVersion":"11.4.1","description":"Open Reality OS as MCP tools: drive scan upload, reconstruction, scene query, scene agents, and robot-training exports from Claude Code, Claude desktop, Codex, or Cursor.","directories":{},"maintainers":[{"name":"galoiz","email":"galois77777@gmail.com"}],"_nodeVersion":"23.11.0","allowScripts":{"esbuild@0.21.5":true,"esbuild@0.27.7":true},"dependencies":{"zod":"^3.25.76","cordis":"^4.0.0-rc.9","@modelcontextprotocol/sdk":"^1.30.0"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.3.5","vitest":"^2.0.0","typescript":"6.0.3","@types/node":"^20.17.0","@reality/protocol":"file:./vendor/protocol"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/openreality-mcp_0.4.0_1792533317053_0.5802555308691615"}}},"time":{"created":"2026-08-11T16:34:08.557Z","modified":"2026-10-20T21:55:17.363Z","0.1.0":"2026-08-11T16:34:09.098Z","0.1.1":"2026-08-11T16:55:24.449Z","0.2.0":"2026-08-11T23:17:53.814Z","0.2.1":"2026-08-19T03:02:18.694Z","0.3.0":"2026-09-01T20:44:31.993Z","0.3.1":"2026-09-03T20:00:45.635Z","0.4.0":"2026-10-20T21:55:17.167Z"},"bugs":{"url":"https://github.com/reality-opened/openreality/issues"},"license":"BSD-2-Clause","homepage":"https://open-reality.io/mcp","keywords":["mcp","modelcontextprotocol","claude","codex","cursor","cordis","3d","slam","robotics","lerobot","3d-reconstruction","claude-code","openreality"],"repository":{"url":"git+https://github.com/reality-opened/openreality.git","type":"git","directory":"mcp"},"description":"Open Reality OS as MCP tools: drive scan upload, reconstruction, scene query, scene agents, and robot-training exports from Claude Code, Claude desktop, Codex, or Cursor.","maintainers":[{"name":"galoiz","email":"galois77777@gmail.com"}],"readme":"# openreality-mcp\n\n**Open Reality OS as MCP tools.** Drive the whole OS from Claude Code, Claude\ndesktop, or any MCP client: upload scans into your account, follow\nreconstruction jobs, sync scenes down as context, measure, plan paths, run the\nscene agents, and pull robot-training exports (`openreality` /\n`groot_lerobot_v2` / `isaac_usd` / `mujoco_mjcf`) to disk.\n\n```bash\nnpm install -g openreality-mcp   # or run it ad hoc with npx\n```\n\nThis is a **thin typed client of the deployed broker**: the same REST contract\nthe OS web client speaks (the vendored [`@reality/protocol`](vendor/protocol)\nis the single source of truth for routes and payload shapes). No orchestration,\nguardrails, or storage logic is duplicated here.\n\n## What runs where\n\n- **The MCP server always runs on your machine**: a stdio process started by\n  your client. Credentials and fetched artifacts stay local.\n- **Every tool call is a REST call to an Open Reality broker**\n  (`OPENREALITY_URL`). Reconstruction, scene agents, storage, and exports\n  execute there; real use needs an account (`openreality-mcp login`).\n- **Fully offline development works without an account**:\n  `openreality-mcp simulator` fakes the whole workflow with fixture data (see\n  below). It does not reconstruct anything.\n- The broker contract is plain REST, so `OPENREALITY_URL` can point at any\n  deployment that speaks it, **including your own**: the broker\n  ([`../server`](../server)) and the SLAM library ([`../core`](../core)) live\n  in this repo and are self-hostable (your own GPU box, or your own Modal\n  account). Self-hosted stacks are non-commercial by upstream model licensing;\n  see [`../server/docs/self-hosting.md`](../server/docs/self-hosting.md).\n\n## Install: Claude Code\n\n```bash\nclaude mcp add --scope user openreality -- npx -y openreality-mcp serve\n```\n\n`--scope user` registers the server for every project on your machine. Drop\nthe flag to register it for the current folder only (Claude Code's default).\n\nor in a project `.mcp.json` (see [`.mcp.json.example`](.mcp.json.example)):\n\n```json\n{\n  \"mcpServers\": {\n    \"openreality\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"openreality-mcp\", \"serve\"]\n    }\n  }\n}\n```\n\nOptionally install the skill so Claude knows the workflow + honesty doctrine:\ncopy `skills/openreality/` into `~/.claude/skills/` (or your project's\n`.claude/skills/`).\n\nOr install both at once as a **Claude Code plugin** (this repo is a plugin\nmarketplace: [`.claude-plugin/marketplace.json`](../.claude-plugin/marketplace.json)\nat the repo root, plugin manifest in [`.claude-plugin/plugin.json`](.claude-plugin/plugin.json)):\n\n```\n/plugin marketplace add reality-opened/openreality\n/plugin install openreality@openreality\n```\n\n## Install: Claude desktop\n\n**One-click extension (no terminal):** download `openreality-mcp-<version>.mcpb`\nfrom the [latest release](https://github.com/reality-opened/openreality/releases/latest)\nand double-click it, or drag it into the Claude desktop window. The extension's\nsettings panel takes an optional server URL (for self-hosters) and an optional\nAPI token. The bundle is built from this package by `npm run build:mcpb`\n([`scripts/build-mcpb.sh`](scripts/build-mcpb.sh), manifest in\n[`manifest.json`](manifest.json)).\n\n**Or by hand:** add to `claude_desktop_config.json` (Settings → Developer → Edit Config):\n\n```json\n{\n  \"mcpServers\": {\n    \"openreality\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"openreality-mcp\", \"serve\"]\n    }\n  }\n}\n```\n\n## Install: Codex\n\n```bash\ncodex mcp add openreality -- npx -y openreality-mcp serve\n```\n\nor in `~/.codex/config.toml` (the Codex IDE extension reads the same file;\nverified against codex-cli 0.146.0):\n\n```toml\n[mcp_servers.openreality]\ncommand = \"npx\"\nargs = [\"-y\", \"openreality-mcp\", \"serve\"]\n```\n\nManage with `codex mcp list` / `codex mcp get openreality` / `codex mcp remove openreality`.\n\n## Install: Cursor\n\nOne-click: [Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=openreality&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm9wZW5yZWFsaXR5LW1jcCIsInNlcnZlIl19)\n(the deeplink carries the base64 of the server config below).\n\nOr add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project):\n\n```json\n{\n  \"mcpServers\": {\n    \"openreality\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"openreality-mcp\", \"serve\"]\n    }\n  }\n}\n```\n\nSign-in is shared: `npx -y openreality-mcp login` once, and every client that starts\nthe server picks up the stored credentials.\n\n## Sign in\n\nThe broker authenticates with a durable **API key** (`ork_...`, opaque,\nrevocable server-side, minted once via a browser login; no expiry, no\nrolling). The older broker session-token flow (12 h, auto-rolled at half-life)\nstill works as a fallback for brokers that predate API keys.\n\n```bash\nopenreality-mcp login\n# opens your browser to sign in, then mints and stores a durable ork_ API key.\n# Headless / no browser? The URL is always printed too; open it anywhere.\n```\n\nCredentials land in `~/.config/openreality/credentials.json` (0600).\nAlternatively set `OPENREALITY_TOKEN` in the environment; this also accepts an\n`ork_...` key directly. The broker URL defaults to the deployed app; override\nwith `OPENREALITY_URL`. The browser hand-off page defaults to\n`https://open-reality.io`; override with `OPENREALITY_LOGIN_URL`.\n\nAlready have a token (an `ork_...` key, or a short-lived sign-in token from\nyour deployment's `/os` page `#token=…` hash)?\n\n```bash\nopenreality-mcp login --token <token>\n```\n\nManage keys with `openreality-mcp keys list` / `openreality-mcp keys revoke\n<key_id>`; `openreality-mcp whoami` sanity-checks the stored credential. A\nrevoked or unknown key answers every request with a clear \"run `login` again\"\nerror; it never loops retrying.\n\n## Architecture: an all-plugin [cordis](https://github.com/cordiverse/cordis) app\n\nThe server is assembled from cordis plugins around two services; nothing\nregisters anything globally.\n\n```\nsrc/services/broker.ts   ctx.broker: resolved config + credential session + typed HTTP client\nsrc/services/mcp.ts      ctx.mcp:     the MCP server; effect-scoped tool/resource registration\nsrc/plugins/workspace.ts   workspace_* tools     (inject: ['mcp', 'broker'])\nsrc/plugins/scene.ts       scene_* tools\nsrc/plugins/agent.ts       agent_* tools\nsrc/plugins/export.ts      export_* / artifact_* tools\nsrc/plugins/resources.ts   openreality:// resources\nsrc/app.ts               the composition (createApp), and nothing else\n```\n\nThe rules this buys, mechanically enforced by the framework:\n\n- **Registrations are reversible effects.** Every tool/resource goes through\n  `ctx.effect()` with the SDK handle's `remove()` as the disposer: disposing a\n  namespace fiber removes exactly its tools from the live server, remounting\n  restores them (proven in `test/cordis.test.ts`).\n- **Load order is service requirements, not boot sequencing.** A tool namespace\n  declares `inject: ['mcp', 'broker']` and stays pending until those services\n  exist.\n- **Misconfiguration fails loud at mount.** Service configs are validated\n  (Standard Schema via zod) when the plugin loads, not on the first tool call.\n- **Compositions are data.** `createApp()` mounts the full surface; embedders\n  and tests mount any subset on a fresh `Context`.\n\n## Develop against the simulator (no backend needed)\n\n```bash\nopenreality-mcp simulator --port 8973\n# then in another shell / your MCP config:\nOPENREALITY_URL=http://127.0.0.1:8973 OPENREALITY_TOKEN=sim-token openreality-mcp serve\n```\n\nThe simulator is a dependency-free mock broker whose responses are typechecked\nagainst `@reality/protocol` and contract-tested with the protocol's own guards\n(`test/simulator.contract.test.ts`). It simulates the honesty doctrine too:\nun-anchored scenes measure in `relative` units, the Isaac export is\nmetric-gated, one agent run per scene (409), replays are $0. It also implements\nthe durable API-key routes against the same `ork_...` wire contract as the real\nbroker. [`examples/transcript.md`](examples/transcript.md) is a full recorded\nsession.\n\n## Tool surface (42 tools)\n\n| Namespace | Tools |\n|---|---|\n| `workspace_*` | list_scenes (sync cursor), upload_video, upload_recording, upload_splat (inline + chunked), job_status, job_wait |\n| `scene_*` | card, list_objects, measure_distance, measure_angle, plan_path, planes, ground_frame, ground_frame_fit, anchor, keyframe_image, synthetic_views, synthetic_view_image, lod, lod_build, imported_objects, imported_objects_run, object_complete, object_variants, segment, job_status, job_wait, share, share_access (who opened a share link, visits, returns, questions) |\n| `agent_*` | annotate, replay, pilot, chat (waits + renders the event transcript), run_events, runs |\n| `export_*` / `artifact_*` | export_manifest, export_prepare, export_status, export_mujoco, artifact_fetch, artifact_fetch_splat, artifact_fetch_cloud |\n\nResources: `openreality://scenes` (index) and `openreality://scene/{scan_id}`\n(context card), @-mentionable in Claude Code.\n\nDesign rules: artifacts are written to disk\n(`~/.config/openreality/artifacts/...`), never into context; honesty fields\n(`units`, `scale_source`, `provenance`, `degraded`) pass through verbatim;\nserver refusals (409/422 with typed bodies) surface as structured tool errors.\n\n## Build & test\n\n```bash\nnpm install\nnpm run build        # tsup → dist/cli.js (vendored protocol bundled in)\nnpm run typecheck\nnpm test             # builds + runs unit, contract, cordis-lifecycle, and stdio e2e\n                     # suites; regenerates examples/transcript.md against the simulator\n```\n\n## Privacy policy\n\nThis section is the privacy policy for the `openreality-mcp` package and the\nClaude desktop extension built from it. It is written so that a person with no\ntechnical background can read it.\n\n**What runs where.** The MCP server is a small program that runs on your own\ncomputer, started by your AI assistant. It does not run on our servers. It has\nno analytics, no telemetry, and no crash reporting: nothing is sent anywhere\nunless a tool call needs it.\n\n**Data collection.** The program sends data only to the Open Reality server it\nis configured to talk to: the hosted service at `open-reality.io` (operated by\nreality-opened) by default, or your own self-hosted server if you set\n`OPENREALITY_URL`. What it sends is exactly the content of the tool calls your\nassistant makes: video files, splat files, or robot recordings you ask it to\nupload; scene identifiers; measurement points; questions for the scene agent.\nIt does not read files you did not ask it to upload.\n\n**Usage and storage on your computer.** Your sign-in credential is stored in\n`~/.config/openreality/credentials.json` (readable only by your user account).\nDownloaded artifacts (point clouds, splats, export bundles) are written under\n`~/.config/openreality/artifacts/`. A small sync cursor (which scene ids this\nmachine has already listed) is kept next to them. Delete these folders to\nremove everything the program stored.\n\n**Usage and storage on the hosted service.** Uploads become scenes in your Open\nReality account and stay there so your assistant can query them later. The\nscene agent's conversations are recorded as event logs so they can be replayed\nwithout cost. Data is retained until you delete the scene or the account.\n\n**Third-party sharing.** The hosted service uses infrastructure providers to\nprocess your data (GPU compute for reconstruction, model providers for the\nscene agent and segmentation). They process data on our behalf under their\nterms and do not receive it for their own use. We do not sell your data and do\nnot share it with advertisers. Share links you mint are read-only and single\nscene; the `scene_share_access` tool lets you see who used them.\n\n**Data retention.** Local files stay until you delete them. Hosted scenes stay\nuntil you delete them or ask us to. Revoke a sign-in key at any time with\n`openreality-mcp keys revoke <key_id>`.\n\n**Contact.** Open an issue at\n[github.com/reality-opened/openreality/issues](https://github.com/reality-opened/openreality/issues)\nor use the contact address published at [open-reality.io](https://open-reality.io).\n\n## License\n\n[BSD-2-Clause](LICENSE).\n","readmeFilename":"README.md"}