Sensact

Sensact

Sensact 是一个托管于 Supabase 的 remote MCP 设备平台。

其目标是让 Codex 或 Claude 等 LLM 客户端通过标准 MCP 服务发现并调用用户自有设备上的功能，同时由 Supabase Auth 提供 OAuth 2.1 授权流程，并由 Postgres + Realtime + Storage 提供控制平面。

MCP Registry 预览

Sensact 已为官方 MCP Registry 做好准备，是一项「仅远程」公开预览服务。

• Registry 名称：io.github.sensact-agents/sensact
• Registry 元数据文件：server.json
• 规范仓库：https://github.com/sensact-agents/Sensact
• 公开预览 MCP URL：https://helavgrvwipmdvyejfom.supabase.co/functions/v1/mcp
• 公开预览受保护资源元数据：https://helavgrvwipmdvyejfom.supabase.co/functions/v1/mcp/.well-known/oauth-protected-resource
• 公开预览授权服务器元数据：https://helavgrvwipmdvyejfom.supabase.co/auth/v1/.well-known/oauth-authorization-server

当前范围

v1 专注于一次性调用设备功能：

• 列出已通过身份验证的用户可见的设备
• 检查设备功能
• 通过任务调用简单的设备功能
• 返回结构化结果或制品引用

v1 参考功能：

• vision.camera_capture
• contacts.find_contact
• vision.screen_capture

后续阶段计划：

• v2：用于实时音视频的 WebRTC 媒体会话
• v3：高级操作和实时推理编排

仓库结构

• docs
  • 产品、架构、数据模型、MCP API、Supabase 架构、授权同意、运行时设计
• schemas/mcp
  • JSON Schema 契约和 MCP 工具注册元数据
• services/mcp-service
  • 用于 MCP 工具定义和服务端结构的共享 TypeScript 包
• services/oauth-consent-app
  • 为 / 和 /oauth/consent 提供的浏览器身份验证与授权同意 UI，适用于 Supabase OAuth 服务
• supabase
  • Edge Function MCP 网关、迁移、配置、种子数据

不包含在此仓库快照中的内容：

• mediapipe
  • 作为嵌套上游仓库而被忽略

关键文档

• sensact-app-product-design.md
• sensact-system-architecture.md
• sensact-mcp-api.md
• sensact-supabase-schema.md
• sensact-oauth-consent.md

当前实现状态

此仓库中已实现：

• 位于 supabase/functions/mcp 的 Supabase Edge Function MCP 网关
• 用于远程 MCP OAuth 的受保护资源元数据和 WWW-Authenticate 质询
• list_devices、list_device_capabilities、invoke_device_capability、get_artifact
• 用于核心注册表、功能、执行、制品和 RLS 设置的 Supabase SQL 迁移
• 支持 Google 登录、魔法链接备用验证方式和 Supabase Auth OAuth 授权同意 UI 的浏览器身份验证应用

已知限制：

• 尚未接入真实设备运行时，因此设备发现依赖外部设备注册
• invoke_device_capability 需要实际的设备运行时来接收任务并写入结果
• 生产环境中，授权同意应用应由 https://www.sensactagent.com/oauth/consent 提供服务

先决条件

• Node.js 20+
• npm
• Supabase CLI
• 一个满足以下条件的 Supabase 项目：
  • 已启用 OAuth 服务端
  • 已启用动态 OAuth 应用注册
  • 此仓库已关联到该项目，或已针对该项目进行配置

本地开发

1. MCP 共享包

cd /Users/luolingfeng/Sensact/services/mcp-service
npm install
npm run typecheck

2. Web 身份验证应用

cd /Users/luolingfeng/Sensact/services/oauth-consent-app
cp .env.example .env

设置：

• VITE_SUPABASE_URL
• VITE_SUPABASE_ANON_KEY

然后运行：

npm install
npm run dev

在本地开发时，Web 身份验证应用运行于：

http://127.0.0.1:3000/
http://127.0.0.1:3000/oauth/consent

生产环境 Web 身份验证 URL：

https://www.sensactagent.com/
https://www.sensactagent.com/oauth/consent

3. Supabase 架构和函数部署

推送迁移：

cd /Users/luolingfeng/Sensact
supabase db push --linked --yes

部署 MCP 函数：

cd /Users/luolingfeng/Sensact
supabase functions deploy mcp --project-ref <project-ref> --use-api --no-verify-jwt

--no-verify-jwt 是有意设置的。网关必须为远程 MCP 发现返回自己的 401 + WWW-Authenticate 挑战。

MCP 端点

公开预览服务 URL：

https://helavgrvwipmdvyejfom.supabase.co/functions/v1/mcp

公开预览受保护资源元数据：

https://helavgrvwipmdvyejfom.supabase.co/functions/v1/mcp/.well-known/oauth-protected-resource

公开预览授权服务器元数据：

https://helavgrvwipmdvyejfom.supabase.co/auth/v1/.well-known/oauth-authorization-server

部署模板：

https://<project-ref>.supabase.co/functions/v1/mcp
https://<project-ref>.supabase.co/functions/v1/mcp/.well-known/oauth-protected-resource
https://<project-ref>.supabase.co/auth/v1/.well-known/oauth-authorization-server

与 MCP 客户端搭配使用

注册表查询：

curl "https://registry.modelcontextprotocol.io/v0/servers?search=io.github.sensact-agents/sensact"

Codex 的备用安装方式：

codex mcp add sensact --url https://helavgrvwipmdvyejfom.supabase.co/functions/v1/mcp

通过 Supabase OAuth 登录：

codex mcp login sensact

检查状态：

codex mcp list
codex mcp get sensact

Claude Code 的备用安装方式：

claude mcp add --transport http sensact https://helavgrvwipmdvyejfom.supabase.co/functions/v1/mcp

发布到 MCP 注册表

此仓库通过 GitHub Actions OIDC，从 Git 标签发布到官方 MCP 注册表。

创建并推送发布标签：

git tag vX.Y.Z
git push origin vX.Y.Z

.github/workflows/publish-mcp.yml 中的工作流将：

• 运行仓库级别的发布测试
• 对 services/mcp-service 进行类型检查
• 测试并构建 services/oauth-consent-app
• 对公开预览 MCP 端点进行冒烟测试
• 根据 $schema 验证 server.json
• 将推送的标签版本写入 server.json
• 使用 mcp-publisher login github-oidc 进行身份验证
• 将 io.github.sensact-agents/sensact 发布到注册表

发布后，验证公开条目：

curl "https://registry.modelcontextprotocol.io/v0/servers?search=io.github.sensact-agents/sensact"

验证命令

授权应用：

cd /Users/luolingfeng/Sensact/services/oauth-consent-app
npm test
npm run build

MCP 共享包：

cd /Users/luolingfeng/Sensact/services/mcp-service
npm run typecheck

注册表发布资源：

cd /Users/luolingfeng/Sensact
node --test scripts/registry-publication.test.mjs
node scripts/validate-server-json.mjs
node scripts/smoke-test-remote-mcp.mjs

远程 MCP 发现：

curl -i https://helavgrvwipmdvyejfom.supabase.co/functions/v1/mcp
curl -i https://helavgrvwipmdvyejfom.supabase.co/functions/v1/mcp/.well-known/oauth-protected-resource
curl -i https://helavgrvwipmdvyejfom.supabase.co/auth/v1/.well-known/oauth-authorization-server

Git

当前仓库初始化信息：

• 提交：d394e5b
• 标签：v0.1.0