prepublish-mcp 1.0.2 → 1.0.3

package/README.md

@@ -1,172 +1,103 @@
 # prepublish-mcp
 
-Audit a YouTube script **before** you record it, from inside your AI client.
+Tooling around the hosted PrePublish MCP server. The server itself is **not** in this package. It lives in the web app and is served at `https://prepublish.ai/mcp`.
 
-Prepublish is a remote MCP server. It reads a draft that does not exist as a
-video yet and returns hook, structure and pacing scores, the passages most
-likely to lose viewers, an inauthentic-content check, a YouTube policy
-pre-flight that cites YouTube's own published pages, and a words-to-runtime
-calculator built on measured speaking rates.
-
-Every other YouTube MCP server fetches the transcript of a video that is
-already published. This one reads the script you have not filmed.
-
-Free, anonymous, no API key, no account.
-
-## Install
-
-**Claude Code**, one command:
-
-```bash
-claude mcp add --transport http prepublish https://mcp.prepublish.ai
-```
-
-**Cursor, VS Code, Windsurf, Claude Code project scope**, or anything that
-reads an `mcpServers` object:
-
-```json
-{
-  "mcpServers": {
-    "prepublish": {
-      "type": "http",
-      "url": "https://mcp.prepublish.ai"
-    }
-  }
-}
-```
+| Path | What it is |
+| --- | --- |
+| `prepublish-fe/app/mcp/route.ts` | The live endpoint. Streamable HTTP, stateless, anonymous-friendly |
+| `prepublish-fe/lib/mcp/protocol.ts` | JSON-RPC / MCP core |
+| `prepublish-fe/lib/mcp/tools.ts` | The six tools and their descriptions |
+| `prepublish-fe/lib/mcp/limits.ts` | Daily spend cap and per-caller burst limits |
+| `prepublish-fe/app/mcp-server/` | Public documentation page |
+| `prepublish-mcp/src/bridge.ts` | stdio bridge for clients that cannot use a remote server |
+| `prepublish-mcp/test/` | Conformance suite driven by the official MCP SDK client |
+| `prepublish-mcp/server.json` | Registry entry for `ai.prepublish/script-audit` |
 
-**Claude Desktop**: add a custom connector under Customize, then Connectors,
-and paste `https://mcp.prepublish.ai`.
+One source of truth for tools: the app. The bridge fetches its tool list from the hosted server at startup, so adding a tool needs no release here.
 
-**Codex CLI**, `~/.codex/config.toml`:
+## Why the server is hand-rolled rather than SDK-hosted
 
-```toml
-[mcp_servers.prepublish]
-url = "https://mcp.prepublish.ai"
-```
+`@modelcontextprotocol/sdk`'s `StreamableHTTPServerTransport` speaks Node's `IncomingMessage`/`ServerResponse`; a Next App Router route handler speaks Web `Request`/`Response`. Shimming one onto the other is more code, and more fragile code, than answering the five JSON-RPC methods a tools-only server needs. Conformance is not taken on trust: `test/conformance.test.ts` drives the endpoint with the official SDK **client** over Streamable HTTP, so the wire format is checked against the reference implementation.
 
-**Clients that can only launch a command** use the stdio bridge in this
-repository. It needs Node 20 or newer and forwards to the same endpoint:
-
-```json
-{
-  "mcpServers": {
-    "prepublish": {
-      "command": "npx",
-      "args": ["-y", "prepublish-mcp"]
-    }
-  }
-}
-```
-
-Agents installing this on a user's behalf should read
-[`llms-install.md`](./llms-install.md).
-
-### Check it worked
-
-Ask for a runtime estimate: *"Use prepublish to convert 1500 words into a
-runtime range."* `script_runtime` is local arithmetic, never rate limited, and
-returns three estimates. If that answers, the connection is good.
+Supported protocol revisions: `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05`. A client asking for a supported revision gets it back; anything else negotiates down to the newest we implement.
 
 ## Tools
 
-| Tool | Cost | What it returns |
+| Tool | Cost | Purpose |
 | --- | --- | --- |
-| `audit_script` | AI-backed | Full audit of a finished draft: hook, structure and pacing scores, an attention-risk map naming the passages most likely to lose viewers, and a rewrite. Returns the analysis and its id |
-| `get_audit` | free | Collect an earlier audit by `analysis_id` |
-| `audit_hook` | AI-backed | Per-sentence attention pull across the opening, curiosity gap, payoff distance, a grade, and rewritten alternatives |
-| `check_authenticity` | AI-backed | Reused, templated or mass-produced content risk, with the quotes that fired each signal |
-| `policy_preflight` | AI-backed | Which YouTube policy families a script touches, each citing YouTube's own page |
-| `script_runtime` | free, local | Words to runtime and runtime to a word budget, at 160, 181 and 201 words per minute measured across 349 videos |
+| `audit_script` | AI-backed | Full audit of a finished draft. Scores, attention-risk map, per-passage rewrites. Polls to completion, then returns the analysis and its id |
+| `get_audit` | free | Collect an audit by `analysis_id` |
+| `audit_hook` | AI-backed | Per-sentence attention pull, curiosity gap, payoff distance, grade, rewrites |
+| `check_authenticity` | AI-backed | Reused / templated / mass-produced content risk with quotes and remediation |
+| `policy_preflight` | AI-backed | YouTube advertiser and monetisation policy exposure, each category citing YouTube's own page. Quoted passages are the paid half |
+| `script_runtime` | free, local | Words ↔ runtime from measured speaking rates (160 / 181 / 201 wpm across 349 videos) |
 
-`audit_script` asks for an email address, because the full audit is released by
-email. The other five do not.
+Every AI-backed response carries the same `notice`: the check is text-only, it maps relative attention risk inside an unrecorded script, and it does not measure or predict published YouTube retention. That sentence is repeated to the user by the model, so it is in the tool descriptions as well as the payloads.
 
-### What it does not do
+Failures return the next action rather than a stack trace: `402` asks the user for an email, `401`/`403` points at the plan, `429` says the allowance is spent and not to retry, `503` says try later.
 
-Every AI-backed response carries the same notice, and it is worth stating here
-too. These checks are text-only. They map relative attention risk inside an
-unrecorded script. They do not measure or predict the retention a published
-video will get, and no output here is a forecast of views, watch time or
-revenue.
+## ChatGPT app (MCP Apps UI)
 
-Nothing fetches a video, a transcript or a channel. Every tool reads text you
-pass it.
+Listed in the ChatGPT plugin directory since 2026-10-17 at `https://chatgpt.com/plugins/plugin_asdk_app_6aba148dbb6c81918fbc261b405c0c1c`; the package source is `ops/chatgpt-app/plugin-src/`. OpenAI rescans this endpoint daily, and a changed tool descriptor is held until it passes automated checks, so edits to `tools.ts` descriptions are reviewed, not instant.
 
-## Limits
+Two tools render their result as an inline report rather than text: `audit_script` and `get_audit`. The widget is one HTML document, served as `ui://prepublish/audit-v2.html` and under each retired URI in `AUDIT_WIDGET_LEGACY_URIS` (ChatGPT caches the view by URI, and a held descriptor update still names the old one), exported as `AUDIT_WIDGET_URI` from `prepublish-fe/lib/mcp/ui/audit-widget.ts` and served by `resources/read` as `text/html;profile=mcp-app`. The tool descriptor links it with `_meta.ui.resourceUri` and the ChatGPT compatibility alias `_meta["openai/outputTemplate"]`, and marks it widget accessible. A client that does not implement MCP Apps ignores those keys and keeps the text and structured payload it already received.
 
-The free tier is published live at `GET https://mcp.prepublish.ai`, which
-returns a machine-readable server card with the current day's usage.
+The resource declares no CSP domains, so the host applies its restrictive defaults, plus a redirect allowance for `https://prepublish.ai` (the same report in the browser), display modes `inline` and `fullscreen`, and clipboard write for the copy button. `structuredContent` is a projection of the backend audit, not the backend body: the scores, the relative attention-risk map, the improvements, the locked count and the policy pre-flight summary, with internal ids, timestamps and processing metadata dropped. The six tools, their inputs and their text output are unchanged for every other client.
 
-| Limit | Default |
-| --- | --- |
-| AI-backed calls per UTC day, across the whole endpoint | 100 |
-| AI-backed calls per caller per 10 minutes | 6 |
+A ChatGPT call carries `_meta["openai/subject"]`, an anonymized per-user id. The endpoint hashes it and uses `mcp:oai:` plus the first 32 hex characters of the digest as the caller key, so the existing per-caller window applies per ChatGPT user and no new environment variable is introduced. A presented bearer token still wins over the subject, and a call without one falls back to the forwarded caller address, then the session id, then a random per-call key. Reports returned to a ChatGPT caller link to `?source=chatgpt-app`, which keeps those arrivals separable from other MCP callers in Umami.
 
-`script_runtime` is local arithmetic and never counts against either.
+## Limits
 
-A bearer token in `PREPUBLISH_TOKEN` raises the limits without changing the
-tool list.
+Set on the web app, visible at `GET https://prepublish.ai/mcp`:
 
-When the daily cap is reached the tool returns an error that tells the model
-not to retry and names the web alternative for that day. Failures return the
-next action rather than a stack trace.
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `MCP_DAILY_CALL_CAP` | `100` | AI-backed calls per UTC day across the whole endpoint. Anonymous callers only |
+| `MCP_CALLER_CALL_LIMIT` | `6` | AI-backed anonymous calls per caller per 10 minutes |
+| `MCP_AUTHED_CALLER_LIMIT` | `30` | AI-backed calls per authenticated caller per 10 minutes |
 
-## Transport and protocol
+The counters are in-process. One web container, small numbers, and a restart resets a counter rather than wrongly blocking someone. Move them to Valkey if the app ever runs replicas.
 
-Streamable HTTP, stateless. Supported revisions: `2025-11-25`, `2025-06-18`,
-`2025-03-26`, `2024-11-05`. A client asking for a supported revision gets it
-back; anything else negotiates to the newest one implemented, and the
-negotiated revision is reported identically in the response header and in the
-`initialize` result.
+The backend's own limiter keys on client IP, and every MCP call reaches it from the web container's single IP, which is exactly why the per-caller limit exists here. A call carrying an API key is attributable to one account, and the backend already enforces that account's plan quota, so it is exempt from the shared daily cap and bounded by the wider window instead. `used_today` on the server card counts anonymous calls only.
 
-The endpoint validates the `Origin` header. Requests without one, which is
-every non-browser client, are always served. A browser origin that is not
-`prepublish.ai` is refused with 403, as the transport specification requires.
-An unsupported `MCP-Protocol-Version` header is a 400.
+## Local development
 
-Aliases: `https://prepublish.ai/mcp` and `https://mcp.prepublish.ai/mcp` serve
-the same handler.
+```bash
+# 1. run the app (serves /mcp)
+cd ../prepublish-fe && npm run build && npm run start -- --port 4910
 
-## Development
+# 2. conformance suite against it
+cd ../prepublish-mcp && npm install && npm run build && npm test
+```
 
-The server itself lives in the Prepublish web application, not in this
-repository. What is here is the stdio bridge and the conformance suite that
-holds the hosted endpoint to the specification.
+`npm test` covers the handshake, tool discovery, schema shape, both directions of `script_runtime`, unknown-tool errors, the server card, batching rejection, notification handling, protocol negotiation in both directions, and the stdio bridge round trip. One AI-backed test is skipped unless `MCP_TEST_BILLABLE=1`, because a real call costs money and writes a row.
+
+Verify a deployment:
 
 ```bash
-npm install
-npm run build
-MCP_URL=https://mcp.prepublish.ai npm test
+MCP_URL=https://prepublish.ai/mcp npm run test:conformance
 ```
 
-The suite drives the endpoint with the official MCP SDK **client** over
-Streamable HTTP, so the wire format is checked against the reference
-implementation rather than against our own assumptions. It covers the
-handshake, tool discovery, schema shape, both directions of `script_runtime`,
-unknown-tool errors, the server card, batching rejection, notification
-handling, protocol negotiation in both directions, Origin validation, protocol
-version validation, and the stdio bridge round trip.
-
-One AI-backed test is skipped unless `MCP_TEST_BILLABLE=1`, because a real call
-costs money and writes a row.
+## The bridge
 
-`PREPUBLISH_MCP_URL` overrides the upstream endpoint for the bridge. The bridge
-adds and hides nothing: a test asserts its tool list equals the hosted one, so
-adding a tool on the server needs no release here.
+For clients that require a local stdio command:
 
-## Registry
+```json
+{
+  "mcpServers": {
+    "prepublish": { "command": "npx", "args": ["-y", "prepublish-mcp"] }
+  }
+}
+```
 
-Published to the official MCP registry as `ai.prepublish/script-audit`, a
-remote-only entry under the DNS-verified `ai.prepublish` namespace. See
-[`server.json`](./server.json).
+`PREPUBLISH_MCP_URL` overrides the upstream endpoint; `PREPUBLISH_TOKEN` forwards a bearer token, and a `pp_live_...` API key works there. The bridge adds and hides nothing: a test asserts its tool list equals the hosted one.
 
-## Links
+## Registry
 
-- Documentation: <https://prepublish.ai/mcp-server>
-- Privacy: <https://prepublish.ai/privacy>
-- Contact: <https://prepublish.ai/contact>
+`server.json` claims the DNS-verified namespace `ai.prepublish/script-audit` with a remote-only entry. Two ways to prove the domain, both documented in `ops/mcp/launch-2026-09-10.md`: a DNS TXT record, or the `MCP_REGISTRY_PUBLIC_KEY` environment variable, which makes `https://prepublish.ai/.well-known/mcp-registry-auth` serve the same value. The route 404s until that variable is set, so an unconfigured deployment cannot advertise a half-finished claim.
 
-## License
+## Known gaps
 
-MIT. See [LICENSE](./LICENSE).
+- **Protocol revision lag.** The revision in force is `2026-07-28`; this server implements up to `2025-11-25`, which the SDK also treats as latest. Newer clients are required to handle older dialects. Revisit when the SDK ships `2026-07-28`.
+- **API keys shipped; OAuth 2.1 has not.** Create a `pp_live_...` key at `https://prepublish.ai/dashboard` and send it as `Authorization: Bearer`; the call resolves to that account, skips the shared anonymous cap and counts against the account's plan quota. An existing magic-link JWT still works. OAuth remains the missing piece, and verified-directory status is what it costs.
+- **Path, not subdomain.** `mcp.prepublish.ai` needs a DNS record and a Dokploy service; when it exists, only the URL in `server.json`, the docs page and the card change.

package/dist/bridge.js

@@ -29,24 +29,7 @@ await upstream.connect(new StreamableHTTPClientTransport(new URL(remoteUrl), {
     requestInit: token ? { headers: { authorization: `Bearer ${token}` } } : undefined,
 }));
 const { tools } = await upstream.listTools();
-// The bridge is a pass-through, so it must present the upstream server's own
-// identity rather than a stub of its own. Without this, a client installed
-// through the bridge sees a server with no title, no description and no
-// website, and a catalogue that scans it scores the metadata as missing.
-// getServerVersion() returns the upstream Implementation object, which carries
-// title, description, websiteUrl and icons on revision 2025-11-25.
-const upstreamInfo = upstream.getServerVersion();
-const local = new Server({
-    name: upstreamInfo?.name ?? 'prepublish',
-    version: upstreamInfo?.version ?? '1.0.0',
-    ...(upstreamInfo?.title ? { title: upstreamInfo.title } : {}),
-    ...(upstreamInfo?.description ? { description: upstreamInfo.description } : {}),
-    ...(upstreamInfo?.websiteUrl ? { websiteUrl: upstreamInfo.websiteUrl } : {}),
-    ...(upstreamInfo?.icons ? { icons: upstreamInfo.icons } : {}),
-}, {
-    capabilities: { tools: { listChanged: false } },
-    ...(upstream.getInstructions() ? { instructions: upstream.getInstructions() } : {}),
-});
+const local = new Server({ name: 'prepublish', version: '1.0.0' }, { capabilities: { tools: { listChanged: false } } });
 local.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
 local.setRequestHandler(CallToolRequestSchema, async (request) => upstream.callTool({ name: request.params.name, arguments: request.params.arguments ?? {} }));
 process.stderr.write(`prepublish-mcp bridge ready: upstream=${remoteUrl} tools=${tools.length} auth=${token ? 'bearer' : 'anonymous'}\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prepublish-mcp",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "stdio bridge to the hosted PrePublish MCP server: audit a YouTube script before recording from any MCP client",
   "keywords": [
     "mcp",
@@ -14,7 +14,7 @@
   ],
   "homepage": "https://prepublish.ai/mcp-server",
   "bugs": {
-    "url": "https://github.com/prepublish/prepublish-mcp/issues"
+    "url": "https://prepublish.ai/contact"
   },
   "license": "MIT",
   "author": "PrePublish (https://prepublish.ai)",
@@ -41,15 +41,11 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.30.0"
+    "@modelcontextprotocol/sdk": "1.32.1"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
     "tsx": "^4.0.0",
     "typescript": "^5.0.0"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/prepublish/prepublish-mcp"
   }
 }

package/server.json

@@ -3,7 +3,7 @@
   "name": "ai.prepublish/script-audit",
   "title": "PrePublish - YouTube script QA",
   "description": "Audit a YouTube script before recording: hook, pacing, drop-off risk, copy-paste rewrites.",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "websiteUrl": "https://prepublish.ai/mcp-server",
   "remotes": [
     {