@neopress/mcp 1.3.0 → 1.4.0

package/README.md

@@ -39,23 +39,72 @@ Endpoints:
 
 | Method | Path                                      | Purpose                         |
 | ------ | ----------------------------------------- | ------------------------------- |
-| `POST` | `/mcp`                                    | MCP Streamable HTTP endpoint    |
-| `GET`  | `/.well-known/oauth-protected-resource/mcp` | OAuth protected resource metadata |
-| `GET`  | `/.well-known/oauth-authorization-server` | OAuth authorization server metadata |
-| `POST` | `/oauth/register`                         | Dynamic public client registration |
-| `GET`  | `/oauth/authorize`                        | Supabase OAuth PKCE redirect    |
-| `POST` | `/oauth/token`                            | Supabase PKCE/refresh proxy     |
+| `POST` | `/mcp`                                    | MCP Streamable HTTP endpoint (OAuth bearer required) |
+| `GET`  | `/.well-known/oauth-protected-resource/mcp` | RFC 9728 protected resource metadata (also served at `/.well-known/oauth-protected-resource`) |
 | `GET`  | `/healthz`                                | Liveness probe                  |
 | `GET`  | `/readyz`                                 | Readiness probe                 |
 
-Remote MCP requires OAuth bearer tokens for `/mcp`. It exposes dynamic client
-registration and PKCE token exchange for clients that support remote MCP OAuth.
-The access token is then used against the Neopress first-party `/api/v1` API,
-so tenant membership remains enforced by the app API.
+The server is a pure Resource Server (RS-only): the OAuth 2.1 Authorization
+Server is Supabase Auth. Clients discover it from `authorization_servers` in
+the protected resource metadata and run dynamic client registration
+(`/auth/v1/oauth/clients/register`), authorization, and token exchange against
+Supabase directly — this server hosts no OAuth routes of its own.
+Unauthenticated `/mcp` requests get a 401 with a `WWW-Authenticate:
+Bearer resource_metadata="..."` pointer. The resource metadata deliberately
+omits `scopes_supported`: clients echo advertised scopes into their authorize
+request, and Supabase rejects custom scopes.
+
+Bearer tokens are verified live against Supabase (`GET /auth/v1/user`), so a
+global logout invalidates them immediately. The access token is then used
+against the Neopress first-party `/api/v1` API, so tenant membership remains
+enforced by the app API.
+
+### OAuth consent flow
+
+Consent is delegated by Supabase to the Neopress app (Authorization Path
+`https://app.neopress.ai/oauth/consent`, configured in the Supabase dashboard):
+
+1. Client registers via Supabase DCR, then starts
+   `GET {SUPABASE_URL}/auth/v1/oauth/authorize` (PKCE, S256).
+2. Supabase redirects the browser to the app consent page with
+   `?authorization_id={id}`.
+3. The consent page (session-gated on the app origin) fetches the pending
+   authorization from `GET {SUPABASE_URL}/auth/v1/oauth/authorizations/{id}`
+   using the anon `apikey` plus the signed-in user's access token, and shows
+   the client name, account, and a static access description. If the
+   authorization was already approved, Supabase returns only `{redirect_url}`
+   and the page redirects immediately.
+4. Approve/deny posts to `POST .../oauth/authorizations/{id}/consent` with
+   `{"action":"approve"|"deny"}`; the browser follows the returned
+   `redirect_url` back to the client (deny carries `error=access_denied`).
+5. The client exchanges the code at the Supabase token endpoint. The MCP
+   server only ever sees the resulting bearer token.
 
 Remote MCP disables `neopress_asset_upload_file` because a hosted server cannot
-read the client's local filesystem. Use `neopress_asset_register` for public
-URLs, or use local stdio MCP for local file uploads.
+read the client's local filesystem. Two remote-native paths cover the same
+ground without pushing file bytes through the model's context:
+
+| You have | Tool | What happens |
+| --- | --- | --- |
+| The bytes, and outbound network of your own | `neopress_asset_presign` → your own PUT → `neopress_asset_register` | You upload straight to storage; nothing crosses the conversation, so size and count are free |
+| A public URL | `neopress_asset_import_url` | The server fetches it and stores our own copy, then registers it |
+| The bytes, but no outbound network | `neopress_asset_upload_base64` | Bytes ride inside the tool call, over the connection your host already has |
+
+`neopress_asset_upload_base64` is a deliberate fallback, not a default. Inline
+bytes pass through the model's context (~90K tokens per MB), so it is capped at
+1MB decoded and should only be used where the presign PUT is refused — a
+sandbox whose egress runs through a domain allowlist, for instance. The cap is
+enforced on decoded bytes, since capping the base64 string would let ~33% more
+through.
+
+`neopress_asset_register` on its own only records an external URL — the image
+breaks if the source moves. Prefer `neopress_asset_import_url` unless you
+deliberately want to reference someone else's host.
+
+`neopress_asset_import_url` fetches a caller-supplied URL server-side, so it
+resolves and range-checks every hop (including redirects) against private and
+link-local space before connecting, and caps the body at 50MB while streaming.
+See `src/asset-import.ts`.
 
 ## Environment
 
@@ -64,11 +113,11 @@ URLs, or use local stdio MCP for local file uploads.
 | `PORT` | `4002` | Remote HTTP listen port |
 | `HOST` | `0.0.0.0` | Remote HTTP listen host |
 | `NEOPRESS_BASE_URL` | `https://app.neopress.ai` | Neopress API base URL |
-| `NEOPRESS_MCP_PUBLIC_URL` | request-derived | Public issuer/resource origin |
+| `NEOPRESS_MCP_PUBLIC_URL` | request-derived in dev | Public resource origin for the protected resource metadata and 401 pointer; required when `NODE_ENV=production` |
+| `UPSTASH_REDIS_REST_URL` | unset (in-memory store) | Upstash Redis for the active site selection store; required together with the token when `NODE_ENV=production` so selections persist across restarts and instances |
+| `UPSTASH_REDIS_REST_TOKEN` | unset (in-memory store) | See `UPSTASH_REDIS_REST_URL` |
 | `NEOPRESS_MCP_CORS_ORIGINS` | local dev origins | Comma-separated allowlist or `*` |
-| `NEOPRESS_MCP_OAUTH_PROVIDER` | `google` | Supabase OAuth provider |
-| `NEOPRESS_MCP_OAUTH_CLIENT_SECRET` | generated at boot in non-production | Stable HMAC secret for signed dynamic client IDs; required when `NODE_ENV=production` |
-| `NEOPRESS_SUPABASE_URL` | Neopress Supabase project | Supabase Auth base URL |
+| `NEOPRESS_SUPABASE_URL` | Neopress Supabase project | Supabase Auth base URL (authorization server issuer origin) |
 | `NEOPRESS_SUPABASE_ANON_KEY` | Neopress anon key | Supabase Auth anon key |
 | `NEOPRESS_MCP_AUTH_MODE` | `oauth` | `none` is dev/test only and rejected in production |
 
@@ -86,7 +135,6 @@ docker run --rm -p 8080:8080 \
 Deploy through Artifact Registry / Cloud Run:
 
 ```bash
-export NEOPRESS_MCP_OAUTH_CLIENT_SECRET="$(openssl rand -base64 32)"
 export NEOPRESS_MCP_PUBLIC_URL="https://mcp.neopress.ai"
 pnpm deploy:mcp
 ```
@@ -94,6 +142,22 @@ pnpm deploy:mcp
 The deploy script defaults to project `inblog-ver-2`, region `us-west1`,
 repository `neopress`, and service `neopress-mcp-server`.
 
+### CI deploy
+
+`.github/workflows/deploy-mcp.yml` deploys automatically on pushes to `main`
+that change the MCP Docker build closure (`packages/mcp`, `packages/sdk`,
+`packages/shared`, `packages/analytics-core`, lockfile/workspace config),
+detected via turbo affected; `workflow_dispatch` always deploys. The job runs
+typecheck/lint, then `pnpm predeploy:mcp` (agent contract gate), authenticates
+with Workload Identity Federation, and executes
+`packages/mcp/scripts/deploy-cloud-run.sh`.
+
+The deploy step maps GitHub secrets `UPSTASH_REDIS_REST_URL`,
+`UPSTASH_REDIS_REST_TOKEN` and repository var `NEOPRESS_MCP_PUBLIC_URL` into
+the Cloud Run service environment. Supabase OAuth Server settings (toggle,
+DCR, Authorization Path) are configured in the Supabase dashboard per the
+human runbook in `docs/plan/2026-07-28-remote-mcp-supabase-as-swap.md`.
+
 ## Official Client Drafts
 
 Submission-ready drafts live under `integrations/`:
@@ -113,4 +177,4 @@ pnpm dlx @anthropic-ai/mcpb pack packages/mcp/dist/mcpb/neopress
 ```
 
 Do not submit the remote connector drafts until the production MCP origin,
-legal/support URLs, review workspace, and real client OAuth scans are verified.
+support URL, review workspace, and real client OAuth scans are verified.