io.github.sensact-agents/sensact

Official

by sensact-agents · TypeScript

Sensact

An authenticated remote MCP server for user-owned devices and one-shot capability invocation.

Authenticated remote MCP server for user-owned devices and capability invocation.

README.md8 KBView on GitHub

Sensact

Sensact is a Supabase-hosted remote MCP device platform.

The goal is to let LLM clients such as Codex or Claude discover and invoke capabilities on user-owned devices through a standard MCP server, while Supabase Auth provides the OAuth 2.1 authorization flow and Postgres + Realtime + Storage provide the control plane.

MCP Registry Preview

Sensact is prepared for the official MCP Registry as a remote-only public preview server.

Registry name: io.github.sensact-agents/sensact
Registry metadata file: server.json
Canonical repository: https://github.com/sensact-agents/Sensact
Public preview MCP URL: https://helavgrvwipmdvyejfom.supabase.co/functions/v1/mcp
Public preview protected resource metadata: https://helavgrvwipmdvyejfom.supabase.co/functions/v1/mcp/.well-known/oauth-protected-resource
Public preview authorization server metadata: https://helavgrvwipmdvyejfom.supabase.co/auth/v1/.well-known/oauth-authorization-server

Current Scope

v1 is focused on one-shot device capability invocation:

list devices visible to the authenticated user
inspect device capabilities
invoke simple device capabilities through jobs
return structured results or artifact references

Reference v1 capabilities:

vision.camera_capture
contacts.find_contact
vision.screen_capture

Planned later phases:

v2: WebRTC media sessions for realtime audio/video
v3: advanced actions and realtime inference orchestration

Repository Layout

docs
- Product, architecture, data model, MCP API, Supabase schema, consent, runtime design
schemas/mcp
- JSON Schema contracts and MCP tool registration metadata
services/mcp-service
- Shared TypeScript package for MCP tool definitions and server-side structure
services/oauth-consent-app
- Browser auth + consent UI for the Supabase OAuth server at / and /oauth/consent
supabase
- Edge Function MCP gateway, migrations, config, seed

Not part of this repository snapshot:

mediapipe
- ignored as a nested upstream repository

Key Documents

Current Implementation Status

Implemented in this repository:

Supabase Edge Function MCP gateway at supabase/functions/mcp
protected resource metadata and WWW-Authenticate challenge for remote MCP OAuth
list_devices, list_device_capabilities, invoke_device_capability, get_artifact
Supabase SQL migrations for core registry, capability, execution, artifact, and RLS setup
browser auth app with Google sign-in, magic-link fallback, and OAuth consent UI for Supabase Auth

Known limitations:

No real device runtime is wired yet, so device discovery depends on external device registration
invoke_device_capability requires an actual device runtime to consume jobs and write results
The consent app should be served from https://www.sensactagent.com/oauth/consent in production

Prerequisites

Node.js 20+
npm
Supabase CLI
a Supabase project with:
- OAuth server enabled
- dynamic OAuth app registration enabled
- this repository linked or configured against that project

Local Development

1. MCP shared package

bash

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

2. Web auth app

bash

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

Set:

VITE_SUPABASE_URL
VITE_SUPABASE_ANON_KEY

Then run:

bash

npm install
npm run dev

For local development the web auth app runs at:

text

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

Production web auth URLs:

text

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

3. Supabase schema and function deployment

Push migrations:

bash

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

Deploy the MCP function:

bash

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

--no-verify-jwt is intentional. The gateway must return its own 401 + WWW-Authenticate challenge for remote MCP discovery.

MCP Endpoints

Public preview server URL:

text

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

Public preview protected resource metadata:

text

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

Public preview authorization server metadata:

text

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

Deployment template:

text

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

Using With MCP Clients

Registry lookup:

bash

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

Fallback install for Codex:

bash

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

bash

codex mcp login sensact

Check status:

bash

codex mcp list
codex mcp get sensact

Fallback install for Claude Code:

bash

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

Publishing To MCP Registry

The repository publishes to the official MCP Registry from Git tags via GitHub Actions OIDC.

Create and push a release tag:

bash

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

The workflow at .github/workflows/publish-mcp.yml will:

run the repository-level publication tests
typecheck services/mcp-service
test and build services/oauth-consent-app
smoke test the public preview MCP endpoint
validate server.json against its $schema
stamp the pushed tag version into server.json
authenticate with mcp-publisher login github-oidc
publish io.github.sensact-agents/sensact to the Registry

After publication, verify the public entry:

bash

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

Verification Commands

Consent app:

bash

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

MCP shared package:

bash

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

Registry publication assets:

bash

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

Remote MCP discovery:

bash

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

Current repository bootstrap:

commit: d394e5b
tag: v0.1.0

Install

claude_desktop_config.json

{
  "mcpServers": {
    "sensact": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://helavgrvwipmdvyejfom.supabase.co/functions/v1/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.