Space Context

Space Context MCP 服务

一个远程 MCP 服务，可让 Claude、ChatGPT、Codex、Cursor、VS Code 或任何 MCP 客户端访问你的 Space Context 空间。助手可以列出空间、搜索空间、按章节或整页读取空间、向空间提问、比较扫描结果并展示照片证据。每个条目、问题和关键位置都会说明第二次独立检查是否在自己的照片中发现了它（已验证、未确认或来自旁白），这样助手就知道哪些内容可以直接陈述，哪些需要谨慎措辞。如果你允许，它还可以为你扫描空间。

https://mcp.spacecontext.app/mcp

它通过 Streamable HTTP 使用 MCP，并通过 OAuth 2.1（动态客户端注册和客户端 ID 元数据文档）进行授权。它在 @cloudflare/workers-oauth-provider 后面以无状态方式运行（来自 agents 的 createMcpHandler，MCP SDK v2）。此软件包未发布到 npm。请使用上述托管服务，或自行部署。

连接助手

客户端	操作方法
Claude (claude.ai, Desktop)	设置 → 连接器 → 添加自定义连接器，粘贴 URL，然后点击连接
Claude Code	claude mcp add --transport http --scope user spacecontext https://mcp.spacecontext.app/mcp，然后选择 /mcp → 验证身份
Codex	codex mcp add spacecontext --url https://mcp.spacecontext.app/mcp，然后运行 codex mcp login spacecontext
ChatGPT	设置 → 应用与连接器 → 高级 → 开发者模式，然后使用 URL 和 OAuth 创建连接器
Cursor	在 ~/.cursor/mcp.json 的 mcpServers 下添加 "spacecontext": { "url": "https://mcp.spacecontext.app/mcp" }，然后在 Cursor 的 MCP 设置中点击登录
VS Code	code --add-mcp '{"name":"spacecontext","type":"http","url":"https://mcp.spacecontext.app/mcp"}'（或在工作区的 .vscode/mcp.json 中配置 servers），然后选择 MCP: 列出服务 → 启动并登录

你无需粘贴密钥。连接流程如下：

1. 助手会打开 Space Context 页面。使用与 iPhone 应用相同的账户，通过 Apple、Google 登录，或使用发送到邮箱的验证码登录。
2. 你可以选择是否允许助手查看敏感值（Wi-Fi 密码、门锁和警报代码、解说内容），以及是否允许它为你扫描空间。默认情况下，这两项权限都不开启。扫描需要你的账户中留有一张银行卡（在控制台中添加，不会扣费）：如果没有银行卡，页面会提供只读连接选项，或者提示你添加银行卡后再试。
3. 服务会为此连接单独创建一个 API 密钥，并在控制台中列为 MCP · <assistant>。该密钥的权限范围为 spaces:read 和 scans:read，如果你勾选了相应选项，还会包括 spaces:sensitive 和 scans:write。

在控制台中撤销该密钥即可结束连接，之后助手会要求你重新登录。再次连接同一个助手时，新的密钥会取代旧密钥。助手可以查看你的实时空间，包括使用 iPhone 应用扫描的空间。应用中的空间经过敏感值筛查后即可读取：首次读取时会启动筛查，该过程需要一两分钟。完整指南：连接助手。

工具

读取工具，每次连接均可用（标注为只读且幂等）：

工具
list_spaces	空间及其最新扫描结果，每页 50 条
search_spaces	在所有空间或某一个空间中，查找最能回答问题的记录，支持任意语言
get_space	按版块（区域、物品、问题、关键位置、说明、事实、问答、覆盖范围）获取一个空间，可选择附带证据
get_space_markdown	将整个空间作为一个 Markdown 页面返回，方便一次调用加载为上下文
ask_space	返回带引文的简短答案，或 documented: false
list_scans, compare_scans	获取扫描历史，以及两个扫描之间的变化，并附上两次扫描的证据
get_evidence_photo	获取记录背后的原始视频帧，作为图片
get_scan_status, follow_scan	查看扫描进度；follow_scan 会等待事件流并报告进度
wallet	余额、剩余免费扫描次数、单次扫描价格
capture_checklist	扫描前，查看某类空间（公寓、汽车、船只、家电等）需要拍摄的内容

这些工具仅在用户勾选了 let it scan spaces 的连接上可用。其他连接调用这些工具时，API 会返回 INSUFFICIENT_SCOPE：

工具
check_frame	检查照片是否可用，以及照片展示了哪些关键位置（使用 space_type 时，返回该类型及相应区域的关键位置）；不会存储或收费
create_scan	声明要扫描现有或新空间，并返回上传说明
upload_frame	通过服务端发送一张帧扫描图片，密钥由服务端保管
start_scan	启动扫描并收费：先使用免费扫描次数，然后从余额中扣除 $1.00；扫描失败时退款
cancel_scan	取消尚未开始的扫描；不会收费

资源： spacecontext://spaces（空间列表，JSON）和 spacecontext://spaces/{space_id}（以 Markdown 格式呈现的空间）。提示词： check_out_report（比较两次扫描并撰写报告，将已确认的变化与可能缺失的内容分开说明）和 where_is（查找一件物品，并提供其所在区域和证据照片）。

没有任何工具会访问开放网络。空间内容会作为数据返回，而非指令：服务端说明中明确如此，每个包含空间内容的结果里也都有一条 note。登录前，位于 /.well-known/mcp/server-card.json 的服务端卡片会列出工具、资源和提示词。参数和结果：MCP 工具。

自行部署

该服务是一个 Cloudflare Worker，会与 Space Context API 通信（…/v1，且 API_V1_ENABLED = "true"）。它通过 API 自身的登录端点为用户登录，并为每个连接创建一个 API 密钥。它保存的所有数据都存储在 KV 中：OAuth 客户端、授权和令牌（授权中包含连接的 API 密钥，并由 OAuth 库加密），以及进行中的登录（保存十分钟，并使用只有用户浏览器持有的密钥加密）。

1. 安装并构建 SDK（服务会导入它），在仓库根目录运行：

npm install
npm run build -w @spacecontext/sdk

2. 创建 KV 命名空间，用于存储 OAuth 客户端、授权和令牌，并将其 ID 填入 wrangler.jsonc 中的 kv_namespaces。此步骤及接下来的步骤都在 packages/mcp 中运行：

cd packages/mcp
npx wrangler kv namespace create OAUTH_KV

3. 在 wrangler.jsonc 中设置配置（name、routes 中的自定义域名，以及 vars）：

API_BASE_URL	API 的基础 URL，例如 https://api.spacecontext.app/v1
PUBLIC_URL	此服务的源地址。它用于标识受保护资源（/.well-known/oauth-protected-resource/mcp），也是同意表单接受 POST 请求的唯一源地址
GOOGLE_WEB_CLIENT_ID	可选：用于“使用 Google 继续”的 Google Web OAuth 客户端
APPLE_SERVICES_ID	可选：用于“使用 Apple 登录”的 Services ID
BACKEND（services）	可选：指向 API Worker 的服务绑定。通过此绑定，API 可以获取每位用户自己的 IP 地址，用于速率限制和登录保护。若不设置，服务会通过互联网调用 API_BASE_URL，所有用户都会共用 Worker 的 IP 地址。如果 API 不是你账户中的 Worker，请移除此项

4. 添加 Google 登录所需的密钥：

npx wrangler secret put GOOGLE_WEB_CLIENT_SECRET

5. 在提供商处注册回调 URL：

• Google：将 ${PUBLIC_URL}/authorize/google/callback 添加为 Web OAuth 客户端的授权重定向 URI。
• Apple：将 ${PUBLIC_URL}/authorize/apple/callback 添加为 Services ID 的返回 URL。

如果未同时设置 GOOGLE_WEB_CLIENT_ID 和密钥，则不会显示 Google 按钮；Apple 也是如此，未设置 APPLE_SERVICES_ID 时不会显示 Apple 按钮。始终提供邮箱登录。API 会使用自身配置的 Web 客户端 ID 和 Services ID 验证 Google 和 Apple 令牌，因此请使用与 API 配置相同的值。

6. 部署：

npm run deploy     # wrangler deploy of the top-level environment

请在 wrangler.jsonc 中保留以下设置：

• global_fetch_strictly_public 保持启用。服务会从客户端指定的 URL 获取客户端元数据文档，因此普通 fetch 绝不能访问私有地址。API 通过 BACKEND 绑定访问。
• 关闭 workers_dev 和 preview_urls 后，服务只会在其自定义域名上响应。
• ratelimits 将每个客户端 IP 的注册次数（/register）限制为每分钟 10 次，登录页面请求次数（/authorize…）限制为每分钟 60 次，超出后返回 429 和 Retry-After: 60。速率限制不会由环境继承，且每个 namespace_id 在你的 Cloudflare 账户中必须唯一。如果没有绑定（例如在 dev 中），则不会进行限制。
• 访问令牌的有效期为一小时。授权在最后一次刷新后的 90 天内有效。动态注册的客户端在 180 天内没有令牌请求后会被删除。

wrangler.jsonc 还定义了 dev（本地环境，见下文）和 staging（Space Context 自己的预发布部署）。

开发

npm run dev -w @spacecontext/mcp     # http://localhost:8788, against an API on 127.0.0.1:8787
npm test -w @spacecontext/mcp        # the full OAuth flow and MCP calls in workerd, against a fake API

此仓库不包含 API。测试不需要 API：它们会针对一个模拟 API 执行注册、PKCE、同意、令牌和真实 MCP 调用。dev 环境未设置 Google 或 Apple 客户端，因此本地登录使用通过邮件发送的验证码。添加工具前，请阅读 CONTRIBUTING.md：任何会写入数据或消耗资源的工具都必须受 scans:write 保护，并如实标注。

MIT © Finikos S.r.l.