# SME Library MCP

A free, **open-source** [MCP](https://modelcontextprotocol.io) server for creating, searching,
and sharing **Subject Matter Expert profiles** that AI agents can consult. Anyone can connect
their agent, pull vetted experts from the shared library, maintain private experts in their own
workspace, and contribute good ones back through a moderated promotion pipeline — or self-host
the entire stack.

Licensed under the [MIT License](./LICENSE). Contributions welcome.

Runs on **Vercel** (Next.js + Streamable HTTP transport) with a **Supabase** backend.
New here? Read the **[User Guide](./docs/USER_GUIDE.md)** — how it all works plus a complete
reference for every SME field and its value ranges (also served in-app at `/guide`).
See [ARCHITECTURE.md](./ARCHITECTURE.md) for the full design and roadmap, and
[docs/SME_MCP_Implementation_Checklist.pdf](./docs/SME_MCP_Implementation_Checklist.pdf) for the
step-by-step deployment runbook (regenerable from `docs/implementation-checklist.html`).

## Tools

| Tool | Scope | What it does |
|---|---|---|
| `search_smes` | read | Full-text + tag + expertise search across library and workspace |
| `list_smes` | read | Browse library / workspace SMEs, ranked by quality |
| `get_sme` | read | Fetch one full profile |
| `create_sme` | write | Author a new workspace SME (versioned from v1) |
| `import_smes` | write | Bulk-import up to 200 SME profiles; invalid rows reported and skipped |
| `export_smes` | read | Export workspace SMEs as an import-ready JSON payload |
| `update_sme` | write | Edit a workspace SME; every edit snapshots version history |
| `archive_sme` | write | Soft-delete (reversible) |
| `clone_sme` | write | Copy a library SME into your workspace as an editable private copy |
| `generate_sme` | write | AI-generate a profile — dedups against the library first; quota-limited |
| `record_feedback` | write | Score a SME's session performance; drives the smoothed quality score |
| `propose_promotion` | write | Nominate a workspace SME for the shared library (auto-gated + moderated) |
| `review_promotion` | admin | Approve/reject the promotion queue |

## Setup

### 1. Supabase

Create a project, then apply the migration:

```bash
supabase link --project-ref <ref>
supabase db push                    # applies supabase/migrations/*.sql
supabase functions deploy embed     # optional: enables semantic/hybrid search
```

The `embed` edge function runs the built-in gte-small model. It's optional — without it,
search falls back to keyword FTS automatically.

### 2. Get an API key

**Self-service (recommended):** visit `/dashboard`, create an account (Supabase Auth), and
mint a key. First login auto-creates your workspace. Requires `SUPABASE_ANON_KEY` to be set and
email auth enabled in the Supabase project.

**Operator / CLI:** for admin keys or scripted provisioning:

```bash
SUPABASE_URL=... SUPABASE_SERVICE_ROLE_KEY=... \
  node scripts/create-key.mjs --workspace "My Team"            # read,write key
  node scripts/create-key.mjs --workspace "Ops" --admin        # admin key
```

Either way the plaintext key (`sme_live_...`) is shown once; only its SHA-256 hash is stored.

### 3. Deploy to Vercel

```bash
vercel deploy
```

Set env vars in the Vercel project: `SUPABASE_URL`, `SUPABASE_SERVICE_ROLE_KEY`,
`SUPABASE_ANON_KEY` (powers the dashboard), `ANTHROPIC_API_KEY`, and `CRON_SECRET` (protects
the daily `/api/cron/maintenance` job that recomputes quality scores, prunes rate-limit
windows, and backfills embeddings). Also set `NEXT_PUBLIC_BASE_URL` to your canonical site URL
and `ADMIN_EMAILS` (comma-separated) to bootstrap admin access.

### 3b. Email (confirmations & password resets)

Auth emails are sent by **Supabase**, not this app. If new accounts don't receive validation
emails, it's a Supabase config issue — most often that **custom SMTP isn't configured** (the
built-in sender is rate-limited to a few per hour, for testing only). In the Supabase dashboard:
configure **Authentication → Emails → SMTP Settings** (Resend/Postmark/SendGrid/SES), enable
**Confirm email** under Providers → Email, and add your site + `…/auth/callback` to the
**URL Configuration** allow-list.

### 4. Connect a client

```bash
claude mcp add --transport http sme-library \
  https://<deployment>/api/mcp \
  --header "Authorization: Bearer sme_live_..."
```

Works with Claude Code, claude.ai custom connectors, and any Streamable-HTTP MCP client.

### Local development

```bash
cp .env.example .env      # fill in Supabase + Anthropic
npm install
npm run dev               # HTTP server on :3000 (endpoint: /api/mcp)
SME_API_KEY=sme_live_... npm run stdio   # or stdio transport for local clients
```

## Security model

- API keys are **hashed at rest** (SHA-256) and passed only in the `Authorization` header —
  the credential never appears in tool arguments or the model's context.
- Every key maps to one workspace with scopes (`read`, `write`, `promote`, `admin`) and a
  rate-limit tier; per-key fixed-window limits are enforced in Postgres.
- Supabase RLS is enabled deny-all on every table as defense-in-depth; only the server's
  service-role client can read or write.
- All writes land in `audit_log`.