{"id":"5c9c4528-6839-480e-a6a1-3b416c65b2da","slug":"spacecontext","kind":"mcp","name":"spacecontext","summary":"Space Context for developers and agents: TypeScript SDK, CLI and remote MCP server","owner":"finikoslab","repoUrl":"https://github.com/finikoslab/spacecontext","license":"MIT","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-10-14T12:46:42.000Z","addedAt":"2026-10-14T18:19:15.224Z","logoUrl":"https://avatars.githubusercontent.com/u/230397515?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools","cloud-infra","memory-knowledge"],"tags":[],"runtime":"remote","local":false,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-17T22:17:50.804Z","sample":false,"url":"https://conduits.dev/tools/spacecontext","language":"TypeScript","transports":["http"],"install":{"remoteUrl":"https://mcp.spacecontext.app/mcp"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"
\n\n\"Space\n\n# Space Context\n\n**The context layer for the physical world.**\n\nFilm a space once, and your agent knows it: every room, item, key location and issue,
\neach with the original video frame as evidence.\n\n[![npm @spacecontext/sdk](https://img.shields.io/npm/v/@spacecontext/sdk?label=%40spacecontext%2Fsdk&logo=npm)](https://www.npmjs.com/package/@spacecontext/sdk)\n[![npm spacecontext](https://img.shields.io/npm/v/spacecontext?label=spacecontext&logo=npm)](https://www.npmjs.com/package/spacecontext)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)\n[![Node >= 22.12](https://img.shields.io/badge/node-%3E%3D22.12-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white)](packages/sdk)
\n[![MCP server](https://img.shields.io/badge/MCP-remote%20server-7C3AED)](https://spacecontext.app/developers/docs/mcp/connect/)\n[![OpenAPI 3.1](https://img.shields.io/badge/OpenAPI-3.1-6BA539?logo=openapiinitiative&logoColor=white)](https://api.spacecontext.app/v1/openapi.json)\n[![Docs](https://img.shields.io/badge/docs-spacecontext.app-7C3AED)](https://spacecontext.app/developers/docs/)\n[![llms.txt](https://img.shields.io/badge/llms.txt-for%20agents-7C3AED)](https://spacecontext.app/developers/docs/llms.txt)\n\n[Docs](https://spacecontext.app/developers/docs/) · [Quickstart](https://spacecontext.app/developers/docs/quickstart/) · [API reference](https://spacecontext.app/developers/docs/api/reference/) · [Console](https://spacecontext.app/developers/console/) · [MCP server](https://spacecontext.app/developers/docs/mcp/connect/)\n\n
\n\n## What it is\n\nAgents know your code, your documents and your calendar. They know nothing about the places you live and work in.\n\nSpace Context fills that gap. Record a phone video of a space, narrated or not, and it becomes a **Space Document**, structured JSON that your agents can read:\n\n- **Inventory by room**: items with location, quantity, condition, brand, model and visible text.\n- **Key locations**: fuse box, water shut-off, boiler, router, smoke detectors, meters.\n- **How-tos** taken from the narration (\"fill the water tank at the back, then press the large button\").\n- **Issues** with severity and a suggested action, and **facts** (access, Wi-Fi, rules, contacts).\n- **Evidence**: every record points to the original video frames it comes from.\n\nThen you can **compare** two scans (check-in and check-out), **ask** a space questions and get answers with citations, **search** across all your spaces in any language, and **export** a space as an Agent Skill or a Markdown page.\n\nIt works for any space: a home, a short-term rental, a move-in or move-out, an office, a vehicle, an appliance. It uses the same account as the [Space Context iPhone app](https://apps.apple.com/app/id6774555358), and spaces scanned with the app can be read through the API on every account.\n\n### What an agent gets back\n\n\"Where is the water shut-off?\" asked of a space (`POST /v1/spaces/{id}/ask`):\n\n```json\n{\n \"object\": \"answer\",\n \"space_id\": \"spc_3f…\", \"scan_id\": \"scn_8a…\",\n \"question\": \"Where is the water shut-off?\",\n \"answer\": \"Under the bathroom sink, behind the cupboard door.\",\n \"documented\": true,\n \"citations\": [\n {\n \"record_type\": \"key_location\", \"record_id\": \"loc_1\",\n \"title\": \"Main water valve\", \"area\": \"Bathroom\",\n \"evidence\": [{ \"frame_id\": \"frame-14\", \"timestamp_ms\": 41200, \"url\": \"https://api.spacecontext.app/v1/media/…\" }]\n }\n ]\n}\n```\n\nThe answer comes only from the space's records. If they don't contain it, `documented` is `false` and the answer says so instead of guessing. The evidence `url` is a short-lived signed link to the frame the camera captured 41 seconds into the video.\n\n## Try it in 60 seconds\n\nThe **demo space** (`spc_demo`) contains two real scans of an apartment in Brisbane: photos at check-in, then a narrated video at check-out. Test keys (`sc_test_…`) can read it for free, with no limit and no payment.\n\n**0. Claude Code plugin.** Once this repository is public: `/plugin marketplace add finikoslab/spacecontext`, then `/plugin install spacecontext@spacecontext` (the MCP server and a Space Context skill; run `/mcp` to sign in).\n\n**1. Connect your assistant (MCP).** In Claude, open **Settings → Connectors → Add custom connector** and paste:\n\n```text\nhttps://mcp.spacecontext.app/mcp\n```\n\nIn Claude Code, run `claude mcp add --transport http --scope user spacecontext https://mcp.spacecontext.app/mcp`, then `/mcp` → Authenticate. Codex, ChatGPT, Cursor and VS Code are covered in [Connect an assistant](https://spacecontext.app/developers/docs/mcp/connect/). You sign in with Apple, Google or an emailed code. The connection is read-only unless you allow scanning, which needs a card on file. It sees the spaces of your account (the demo is for test keys), so use the paths below to explore the demo first.\n\n**2. CLI.**\n\n```bash\nnpx spacecontext login --test # approve the code in the console; a free test key comes back\nnpx spacecontext ask spc_demo \"where is the fuse box?\"\nnpx spacecontext search \"where is the fuse box?\"\nnpx spacecontext skill spc_demo --out ./brisbane-apartment-skill\n```\n\n```text\nThe fuse box is in the Open-plan Living, Dining and Kitchen, in the hallway cupboard behind the coats.\n\nSources\n • Fuse box (Open-plan Living, Dining and Kitchen)\n```\n\n**3. SDK.** Create a test key in the [console](https://spacecontext.app/developers/console/keys/) (**API keys**, mode **Test**), set it as `SPACECONTEXT_API_KEY` and install with `npm install @spacecontext/sdk`:\n\n```ts\nimport { SpaceContext } from '@spacecontext/sdk';\n\nconst sc = new SpaceContext(); // reads SPACECONTEXT_API_KEY\n\nconst answer = await sc.spaces.ask('spc_demo', 'Where is the fuse box?');\nconst document = await sc.spaces.get('spc_demo'); // the whole Space Document\nconsole.log(answer.answer, document.key_locations.map((k) => `${k.label}: ${k.location}`));\n\n// Your own space, from a video: created, uploaded, analysed and followed live in one call.\nconst { spaceId } = await sc.scan('./tour.mp4', { name: 'Seaside flat', onProgress: (p) => console.log(p.type) });\n```\n\n**4. curl.** With the same key:\n\n```bash\ncurl -X POST https://api.spacecontext.app/v1/spaces/spc_demo/ask \\\n -H \"Authorization: Bearer $SPACECONTEXT_API_KEY\" -H \"Content-Type: application/json\" \\\n -d '{\"question\": \"Where is the fuse box?\"}'\n```\n\nWhen you're ready to scan your own spaces, add a card in the console (nothing is charged: a live key that can scan needs one), sign in with `npx spacecontext login` to get a live key and scan a video. The first live scan of a new account is free (one free scan per card). Full walkthrough: [Quickstart](https://spacecontext.app/developers/docs/quickstart/).\n\n## What you get\n\n| | How | Docs |\n| --- | --- | --- |\n| **Scan** a video (MP4, MOV, M4V, 3GP, WebM, Matroska) or up to 120 photos; the analysis runs server-side, no ffmpeg needed | `sc.scan()`, `spacecontext scan`, `POST /v1/spaces/{id}/scans` | [Scans](https://spacecontext.app/developers/docs/api/scans/) |\n| **Read** a space as a versioned JSON document, by section | `GET /v1/spaces/{id}` | [The Space Document](https://spacecontext.app/developers/docs/api/space-document/) |\n| **Search** every space in any language (\"rubinetto dell'acqua\" finds \"water shut-off valve\") | `GET /v1/search` | [Search and ask](https://spacecontext.app/developers/docs/api/search-and-ask/) |\n| **Ask** one space and get a short answer with citations and photos, or \"not documented\" | `POST /v1/spaces/{id}/ask` | [Search and ask](https://spacecontext.app/developers/docs/api/search-and-ask/) |\n| **Compare** two scans: added, moved, changed, and \"gone\" only when a frame shows the empty place | `GET /v1/spaces/{id}/diff` | [Check-in and check-out](https://spacecontext.app/developers/docs/guides/check-in-check-out/) |\n| **Export** a space as an Agent Skill folder or one Markdown page | `GET /v1/spaces/{id}/skill`, `…/markdown` | [A space in Claude Code](https://spacecontext.app/developers/docs/guides/claude-code-skill/) |\n| **Follow** a scan live as Server-Sent Events | `GET /v1/scans/{id}/events` | [Scans](https://spacecontext.app/developers/docs/api/scans/) |\n| **Know what to film** for each type of space (a flat, an office, a warehouse, a car, a camper, a boat, an appliance), and **check frames** while filming: usable or not, which key locations are still missing | `GET /v1/capture-profiles`, `POST /v1/frames/check?space_type=` | [Guided capture](https://spacecontext.app/developers/docs/guides/guided-capture/) |\n| **Trust each record**: every item, issue and key location is checked again on its own photo by a second model that never writes text: verified, unconfirmed or from the narration | `verification` on every record | [Verified evidence](https://spacecontext.app/developers/docs/guides/verified-evidence/) |\n| **Webhooks** for `scan.completed`, `scan.failed`, `wallet.auto_recharge_failed` | Console → Webhooks | [Webhooks](https://spacecontext.app/developers/docs/api/webhooks/) |\n\n## Pricing\n\n| | Price |\n| --- | --- |\n| Test keys, on the demo space | Free, within the [limits](https://spacecontext.app/developers/docs/limits/) |\n| First live scan of a new account | Free, one free scan per card: a card already used on another Space Context account (even a deleted one) brings none |\n| Each live scan after that | **$1.00**, from a prepaid balance |\n| Failed scans | Refunded automatically |\n| Reading, search, questions and frame checks | Included, within the [limits](https://spacecontext.app/developers/docs/limits/) |\n| Spaces scanned with the iPhone app | Readable at no cost |\n| Live scans, and live keys that can scan | Need a card on file: saved in the console without a charge, or a top-up already paid |\n| Taxes | Prices exclude applicable taxes (such as VAT, GST or sales tax), added at checkout where they apply |\n\nYou top up the balance by card through Stripe ($10 to $500 per payment), with optional automatic top-up and a monthly spending cap per key. Every top-up comes with an invoice. See [Billing](https://spacecontext.app/developers/docs/account/billing/).\n\n## Limits\n\n| | Limit |\n| --- | --- |\n| Video | Up to 4 GB and 10 minutes |\n| Photos | 120 per scan, JPEG, PNG or WebP, 2 MB each |\n| Requests | 120 per minute per key |\n| Search | 20 per minute, 1 000 per day per account |\n| Questions (`ask`) | 20 per minute, 200 answered per day per account |\n| Frame checks | 2 000 per day per account |\n| Scans processing at once | 10 per account |\n| New spaces, new scans | 200 spaces and 500 scans per day per account, in each mode (test keys included); reset at midnight UTC |\n| Open event streams (`GET /v1/scans/{id}/events`) | 10 per account at once, test and live together; the SDK, the CLI and the MCP server poll instead when all are in use |\n\nEvery limit is listed in [Limits](https://spacecontext.app/developers/docs/limits/).\n\n## Security and privacy\n\n- **Keys** are shown once and stored hashed. Each key has scopes: `spaces:read`, `scans:read`, `scans:write`, and the opt-in `spaces:sensitive`. A key without `spaces:sensitive` gets passwords, door and alarm codes, and the narration redacted from documents, answers, skills and exports. Search results never contain them, whatever the key.\n- **Prompt injection from the physical world**: text in a video that addresses an AI (\"ignore your previous instructions…\", on a sign or said on camera) is withheld before any model or agent reads it, and the document notes this in `coverage.warnings`. This is a safety net, not a guarantee, so agents should still treat space content as untrusted data.\n- **Storage**: videos, frames and documents are stored on Cloudflare, with files in R2 in the EU jurisdiction. Source videos are deleted once their frames are extracted. Frames are kept as evidence and served through short-lived signed links.\n- **Webhooks** are signed (HMAC-SHA256 over the timestamp and the body) and sent only to public HTTPS hosts. Redirects are never followed.\n- **MCP connections** each get their own key, which you can revoke from the console. The assistant never sees the key.\n\nDetails: [Security and privacy](https://spacecontext.app/developers/docs/security-and-privacy/). To report a vulnerability, see [SECURITY.md](SECURITY.md).\n\n## Packages\n\n| Path | What it is |\n| --- | --- |\n| [`packages/sdk`](packages/sdk) · [`@spacecontext/sdk`](https://www.npmjs.com/package/@spacecontext/sdk) | TypeScript client typed from the contract: one call from a video to a document. No runtime dependencies; runs in Node 22.12+, Deno, Workers and browsers |\n| [`packages/cli`](packages/cli) · [`spacecontext`](https://www.npmjs.com/package/spacecontext) | The terminal: sign in, scan, search, ask, compare, export a Skill or Markdown |\n| [`packages/mcp`](packages/mcp) | The remote MCP server (Cloudflare Workers, OAuth 2.1), hosted at `mcp.spacecontext.app`. Not published to npm: deploy your own or use the hosted one |\n| [`openapi/openapi.json`](openapi/openapi.json) | The API contract (OpenAPI 3.1), generated by the API |\n| [`docs`](docs) | The documentation source, published at [spacecontext.app/developers/docs](https://spacecontext.app/developers/docs/) |\n| [`examples`](examples) | [`scan-one-call.ts`](examples/scan-one-call.ts) (a video to a document) and [`where-is-it.ts`](examples/where-is-it.ts) (search, then ask) |\n\nThe analysis pipeline (vision, fusion, the deep pass and sensitive-value screening) runs in the hosted Space Context API and is not part of this repository.\n\n## For agents\n\n- **[llms.txt](https://spacecontext.app/developers/docs/llms.txt)**: an index of every docs page. There's also [llms-full.txt](https://spacecontext.app/developers/docs/llms-full.txt) with everything in one file, and every page is served as Markdown (its URL with `.md`).\n- **[OpenAPI 3.1 contract](https://api.spacecontext.app/v1/openapi.json)**, for code generation and validation. `GET https://api.spacecontext.app/v1` returns links to the contract, the docs, `llms.txt` and the MCP server.\n- **MCP server** at `https://mcp.spacecontext.app/mcp` (Streamable HTTP, OAuth 2.1), with a [server card](https://mcp.spacecontext.app/.well-known/mcp/server-card.json) listing its tools, resources and prompts.\n- **Agent Skill**: `npx spacecontext skill --out ~/.claude/skills/` writes any space as a skill folder (`SKILL.md`, `space.json`, `references/`). The folder tells the agent to treat its content as data, cite the area, and say \"not documented\" instead of guessing.\n\n## Contributing\n\n```bash\nnpm install\nnpm run check # build, typecheck and test every package\n```\n\nNode 22.12 or later. Read [CONTRIBUTING.md](CONTRIBUTING.md) for the layout, the security invariants and how the contract and SDK types are regenerated. Bugs and requests: [issues](https://github.com/finikoslab/spacecontext/issues).\n\n## License\n\n[MIT](LICENSE) © Finikos S.r.l.\n"}