# WoWSQL MCP (Model Context Protocol)

wowsql-style **HTTP MCP** with **OAuth 2.0 authorization code + PKCE** on the WoWSQL API.

## Packages

| Package | Description |
|--------|-------------|
| [`packages/mcp-server-wowsql`](packages/mcp-server-wowsql) | `@wowsql/mcp-server-wowsql` — HTTP MCP server, `createToolSchemas()` for AI SDK |

## Quick start (self-hosted MCP process)

From the repo root:

```bash
cd mcp
npm install
npm run build
npm start
```

### Authentication (OAuth 2.0 + MCP)

The MCP process is an **OAuth protected resource** (not the authorization server):

1. **`POST /mcp`** requires `Authorization: Bearer <access_token>` unless `MCP_ALLOW_UNAUTHENTICATED=true` (dev only).
2. Missing/invalid tokens get **401** with `WWW-Authenticate: Bearer ... resource_metadata="<url>"` so MCP clients (Cursor, etc.) can start OAuth.
3. **Token validation** calls your API: `GET {WOWSQL_API_BASE}/api/v1/auth/me` with the same Bearer token (must match the JWT issued by WoWSQL OAuth or login).
4. **Discovery**
   - Authorization server metadata (WoWSQL API): `GET {WOWSQL_API_BASE}/.well-known/oauth-authorization-server`
   - Protected resource metadata (this MCP host): `GET /.well-known/oauth-protected-resource/mcp`

**Cursor / Electron:** OAuth metadata is **rewritten** so `authorization_endpoint`, `token_endpoint`, and `registration_endpoint` point at **this MCP host** (e.g. `http://localhost:8787/...`). The MCP process **proxies** those requests to `WOWSQL_API_BASE`, so the IDE does not need a working direct `fetch` to `localhost:8000` for OAuth (which often shows up as `fetch failed`). You still need **FastAPI running** on `WOWSQL_API_BASE` so the proxy can reach it.

If **`MCP_PUBLIC_URL`** is unset, PRM and 401 `resource_metadata` are derived from each request’s **`Host`** (and `X-Forwarded-Proto`), so `http://localhost:8787/mcp` and `http://127.0.0.1:8787/mcp` each get matching metadata. Set **`MCP_PUBLIC_URL`** when the MCP is behind a reverse proxy or you need a single fixed origin in production.

| Variable | Default | Purpose |
|----------|---------|---------|
| `WOWSQL_API_BASE` | `https://api.wowsql.com` | WoWSQL FastAPI base URL (no trailing slash). |
| `WOWSQL_OAUTH_ISSUER_URL` | same as `WOWSQL_API_BASE` | `issuer` advertised in PRM (`authorization_servers`). |
| `MCP_PUBLIC_URL` | unset | If set, fixed public origin (no `/mcp` path) for OAuth PRM + `WWW-Authenticate`; overrides Host-based derivation. |
| `MCP_ALLOW_UNAUTHENTICATED` | unset | If `true`, skips Bearer check (**insecure**; local testing only). |
| `PORT` / `MCP_PORT` | `8787` | MCP HTTP port. |
| `MCP_HOST` | `0.0.0.0` | Bind address. |

**Option A — `.env` / `.env.local` (recommended)**  
Copy `packages/mcp-server-wowsql/.env.example` to `.env` or `.env.local` in that folder. The CLI loads **`.env`**, then **`.env.local`** (overrides), then the process **cwd** `.env`. Use `.env.local` for machine-specific values (e.g. `http://localhost:8000`) without committing them.

```bash
cd mcp/packages/mcp-server-wowsql
cp .env.example .env
# edit .env — set WOWSQL_API_BASE to your API
npm run build   # from mcp root: npm run build -w @wowsql/mcp-server-wowsql
npm start
```

**Option B — shell (no file)**

PowerShell:

```powershell
cd mcp
$env:WOWSQL_API_BASE="http://localhost:8005"
$env:PORT="8787"
npm start
```

bash / zsh:

```bash
cd mcp
export WOWSQL_API_BASE=http://localhost:8005
export PORT=8787
npm start
```

### Endpoints

- **MCP (Streamable HTTP):** `POST http://localhost:8787/mcp` — JSON-RPC body; append query params for scoping. MCP clients (Cursor, etc.) use this.
- **MCP (browser):** `GET http://localhost:8787/mcp` returns **401** with a short “not authorized” page (no public metadata). The protocol is **POST** JSON-RPC with `Authorization: Bearer`.
- **Health:** `GET http://localhost:8787/health`

Example scoped URL for clients:

`http://localhost:8787/mcp?project_ref=<uuid-or-slug>&read_only=true&features=database,docs`

## OAuth (API)

- Metadata: `GET https://api.wowsql.com/.well-known/oauth-authorization-server`
- Authorize (redirect to dashboard): `GET /api/v1/auth/oauth/mcp/authorize`
- Approve (logged-in user): `POST /api/v1/auth/oauth/mcp/approve`
- Token: `POST /api/v1/auth/oauth/mcp/token` (`grant_type=authorization_code` or `refresh_token`)

Dashboard consent UI: `/mcp/oauth` on the app (see `dashboard/app/mcp/oauth/page.tsx`).

## Deploy `mcp.wowsql.com`

1. Run this Node service behind TLS (reverse proxy or platform of your choice).
2. Set `WOWSQL_API_BASE` / `WOWSQL_OAUTH_ISSUER_URL` to **`https://api.wowsql.com`** (not `127.0.0.1:8000/8001`). Blue/green flips change the backend host port; the public hostname always follows the active slot via NPM.
3. Set `MCP_PUBLIC_URL=https://mcp.wowsql.com`.
4. Point DNS `mcp.wowsql.com` to the service; health check: `GET /health`.
5. Ensure CORS and OAuth `redirect_uri` values include your MCP client callbacks (see `oauth_clients` seed + env).

EC2 blue/green: `./deploy/ec2-blue-green.sh mcp` sets those env vars automatically.

## npm publish

```bash
cd mcp/packages/mcp-server-wowsql
npm version patch
npm publish --access public
```

Requires an npm org scope `@wowsql` (or change `name` in `package.json`).