# 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](/Users/luolingfeng/Sensact/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](/Users/luolingfeng/Sensact/docs)
  - Product, architecture, data model, MCP API, Supabase schema, consent, runtime design
- [schemas/mcp](/Users/luolingfeng/Sensact/schemas/mcp)
  - JSON Schema contracts and MCP tool registration metadata
- [services/mcp-service](/Users/luolingfeng/Sensact/services/mcp-service)
  - Shared TypeScript package for MCP tool definitions and server-side structure
- [services/oauth-consent-app](/Users/luolingfeng/Sensact/services/oauth-consent-app)
  - Browser auth + consent UI for the Supabase OAuth server at `/` and `/oauth/consent`
- [supabase](/Users/luolingfeng/Sensact/supabase)
  - Edge Function MCP gateway, migrations, config, seed

Not part of this repository snapshot:

- [mediapipe](/Users/luolingfeng/Sensact/mediapipe)
  - ignored as a nested upstream repository

## Key Documents

- [sensact-app-product-design.md](/Users/luolingfeng/Sensact/docs/sensact-app-product-design.md)
- [sensact-system-architecture.md](/Users/luolingfeng/Sensact/docs/sensact-system-architecture.md)
- [sensact-mcp-api.md](/Users/luolingfeng/Sensact/docs/sensact-mcp-api.md)
- [sensact-supabase-schema.md](/Users/luolingfeng/Sensact/docs/sensact-supabase-schema.md)
- [sensact-oauth-consent.md](/Users/luolingfeng/Sensact/docs/sensact-oauth-consent.md)

## Current Implementation Status

Implemented in this repository:

- `Supabase Edge Function` MCP gateway at [supabase/functions/mcp](/Users/luolingfeng/Sensact/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
```

Log in through Supabase OAuth:

```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](/Users/luolingfeng/Sensact/.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`