PASTE-1994 stdio↔HTTP MCP bridge with OAuth

[qubblr]

Summary

@pasteapp/mcp is a stateless stdio↔HTTP MCP bridge. AI tools spawn it via `npx -y @pasteapp/mcp`; it discovers Paste's loopback URL, runs OAuth, and forwards JSON-RPC frames between an stdio MCP client and Paste's HTTP `/mcp` endpoint.

[Claude Desktop / Cursor / Codex / …] ── stdio ──> @pasteapp/mcp ── HTTP+OAuth ──> Paste.app on 127.0.0.1

Paired with paste-repo #2594 which materializes `mcpPort` in UserDefaults on every MCP server bind so the discovery key is always present.

Architecture

• `discover.ts` — reads `mcpPort` from Paste's UserDefaults via `defaults read`, probing the App Store sandbox container plist and the Direct/Setapp plist in parallel.
• `oauth/client.ts` — thin `OAuthClientProvider` adapter on top of `@modelcontextprotocol/sdk`'s `auth()`. The SDK does metadata discovery (RFC 9728 + RFC 8414 + OIDC fallback), DCR (RFC 7591), PKCE (RFC 7636), the `resource` indicator (RFC 8707), and refresh-token rotation. We provide the cache, the browser launcher, and the loopback callback listener. Short-circuits to the cached access token before invoking `auth()` since Paste issues long-lived tokens without refresh; transport's 401 retry triggers a re-auth when one actually goes stale.
• `oauth/callback.ts` — one-shot HTTP listener on a random loopback port. Generates per-flow `state` and validates it server-side, rejecting favicon probes, scans, and forged callbacks with the wrong state. `shutdown()` force-closes keep-alive sockets so the flow can't hang.
• `oauth/store.ts` — atomic, mode-0600 JSON cache keyed to `serverURL` (writes via tmp+rename with a per-call random suffix; corrupt JSON treated as absent). Stores SDK shapes (`OAuthTokens`, `OAuthClientInformationMixed`, transient `codeVerifier` that's wiped on `saveTokens`).
• `transport.ts` — POSTs each NDJSON line with `Authorization: Bearer`, captures `Mcp-Session-Id`, splits SSE per the WHATWG spec (LF/CR/CRLF terminators, multi-`data:` concatenation, BOM stripping, leading-SPACE strip, comments ignored), caps response bodies, and on 401 invalidates the token cache and retries the same frame exactly once. Exits cleanly when stdout is destroyed (no `ERR_UNHANDLED_ERROR` when the host process dies).
• `fallback.ts` — when discovery returns no port, serves a minimal MCP server with one `paste_status` tool plus an `instructions` field telling the user to start Paste.

Defensive choices worth flagging:

• `assertLoopbackHTTPURL` in `BridgeProvider.redirectToAuthorization` refuses any `authorization_endpoint` that isn't HTTP(S) on loopback — the AS metadata is attacker-influenceable if the discovered port has been hijacked.
• Cache mismatch on `serverURL` drops the cached state rather than overwriting, so a future caller that multiplexes flows can't graft one server's tokens onto another's.
• PKCE `code_verifier` is wiped from disk in the same write that lands the tokens.

Tests

54 vitest tests across 6 files. Coverage targets the bug classes that turned up across three review rounds:

• Token-store atomicity, mode-0600, corrupt-JSON resilience
• Callback-server state filtering (DoS resistance), keep-alive shutdown (no hang), timeout
• SSE WHATWG edge cases (CR, LF, CRLF, multi-line `data:`, BOM, comments)
• 401 retry exactly once (not three), stdout-destroyed early exit
• Full OAuth flow against a mock server; cache reuse vs. URL-mismatch invalidation; `invalidate()` → real re-auth; verifier wiped after exchange
• Loopback URL guard for the browser opener

CI runs `build` + `test` on Node 20.

Release

`@pasteapp/mcp` is not published yet. Publish only after pasteapp/paste#2594 ships in a Paste release, so the discovery key is present in users' UserDefaults when the npm package becomes available.

```bash
npm publish --access public
```

Test plan

• `npm run build` clean, shebang preserved, bin executable
• `npm test` — 54 tests pass
• Smoke against running Paste: `npm link` + `claude mcp add paste -- paste-mcp`; first run opens browser for OAuth consent, second run uses cached token (~1s)
• After paste-repo PR ships: end-to-end against Paste 6.6 from Claude Desktop, Cursor, Codex
• `npm publish --access public` once verified

[linear]

PASTE-1994 Publish @pasteapp/mcp — stdio→HTTP bridge as npm package

Ship a thin stdio MCP bridge as an npm package so every major AI client (Claude Desktop, Claude Code, Cursor, ChatGPT Desktop) can connect to the running Paste app with a single config line.

Why this exists

Paste hosts its MCP server as HTTP on loopback, which is the right transport for cross-client reach but doesn't plug into Claude Desktop's one-click Extensions gallery or ecosystem-standard stdio flows. A tiny npm-distributed bridge closes that gap without compromising the in-app architecture.

Pattern precedent: NotePlan ships the same way (@noteplanco/noteplan-mcp) and supports every major client.

What the bridge does

[Any MCP client] ──stdio──> pasteapp/mcp ──HTTP──> Paste.app (127.0.0.1)

• Launched as a subprocess by the client, speaks stdio MCP
• Reads Paste's URL + bearer token from a known file that Paste writes when AI Tools is enabled (e.g., ~/Library/Application Support/com.pasteapp.Paste/mcp-endpoint.json, mode 0600)
• Forwards every MCP JSON-RPC message over HTTP to Paste
• If Paste isn't running / AI Tools is off / file missing, surface a single tool that returns a helpful message: "Start Paste and enable AI Tools in Settings"
• Stateless, thin, ~150 lines. No tool logic of its own.

Endpoint file format

Written by Paste when AI Tools is enabled, deleted when disabled:

{
  "url": "http://127.0.0.1:39725/mcp",
  "token": "…"
}

File permissions must be 0600 (user-only).

Package

• Name: @pasteapp/mcp
• Language: Node (TypeScript). Matches ecosystem convention (npx runnable).
• License: MIT
• Repository: separate public repo — https://github.com/pasteapp/paste-mcp (linked from pasteapp.io)
• Single entry point: npx pasteapp/mcp

Install instructions to document

Per client, in Help Center:

Client	Install
Claude Desktop	Config file: command: npx, args: ["-y", "@pasteapp/mcp"]
Claude Code	claude mcp add paste -- npx -y pasteapp/mcp
Cursor	Edit ~/.cursor/mcp.json with same command
ChatGPT Desktop	Settings → Advanced → Edit MCP Config

The Paste settings pane's "Connect an AI app" buttons should write this same config automatically — no user-visible difference between manual and one-click install.

Scope

• Implement the bridge
• Publish to npm (npmjs.com) under the @pasteapp org
• Create the public repo with README + install-per-client examples
• Update Paste's Help Center articles to reference the bridge
• Update the settings pane's "Connect an AI app" buttons to use this command

Out of scope (separate issues)

• MCPB wrapping for Claude Desktop Extensions gallery
• Community directory submissions
• Anthropic outreach re: Remote Connectors Directory

Review in Linear