prepublish-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PrePublish (prepublish.ai)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,93 @@
+# prepublish-mcp
+
+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`.
+
+| 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 limit |
+| `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` |
+
+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.
+
+## Why the server is hand-rolled rather than SDK-hosted
+
+`@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.
+
+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 | Purpose |
+| --- | --- | --- |
+| `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) |
+
+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.
+
+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.
+
+## Limits
+
+Set on the web app, visible at `GET https://prepublish.ai/mcp`:
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `MCP_DAILY_CALL_CAP` | `100` | AI-backed calls per UTC day across the whole endpoint |
+| `MCP_CALLER_CALL_LIMIT` | `6` | AI-backed calls per caller per 10 minutes |
+
+Both 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.
+
+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.
+
+## Local development
+
+```bash
+# 1. run the app (serves /mcp)
+cd ../prepublish-fe && npm run build && npm run start -- --port 4910
+
+# 2. conformance suite against it
+cd ../prepublish-mcp && npm install && npm run build && npm test
+```
+
+`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
+MCP_URL=https://prepublish.ai/mcp npm run test:conformance
+```
+
+## The bridge
+
+For clients that require a local stdio command:
+
+```json
+{
+  "mcpServers": {
+    "prepublish": { "command": "npx", "args": ["-y", "prepublish-mcp"] }
+  }
+}
+```
+
+`PREPUBLISH_MCP_URL` overrides the upstream endpoint; `PREPUBLISH_TOKEN` forwards a bearer token. The bridge adds and hides nothing — a test asserts its tool list equals the hosted one.
+
+## Registry
+
+`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.
+
+## Known gaps
+
+- **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`.
+- **No OAuth 2.1.** Anonymous plus optional bearer token. OAuth is only needed for per-user identity and verified-directory status.
+- **No per-user API keys.** Authenticated use means an existing magic-link JWT. Real API keys are the prerequisite for selling MCP access.
+- **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.d.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * stdio bridge to the hosted PrePublish MCP server.
+ *
+ * The tools themselves live in the web app and are served over Streamable HTTP
+ * at https://prepublish.ai/mcp. That is the single source of truth: this process
+ * adds no tools of its own, it forwards. It exists for clients that can only
+ * speak stdio to a local command (Claude Desktop bundles, some editors and
+ * local agent runtimes), so those users are not left out while a remote
+ * connector is unavailable to them.
+ *
+ * The tool list is fetched from the remote server at startup, so adding a tool
+ * in the app requires no release here.
+ *
+ * Usage:
+ *   npx prepublish-mcp                       # bridges to https://mcp.prepublish.ai
+ *   PREPUBLISH_MCP_URL=... npx prepublish-mcp # bridges to another deployment
+ *   PREPUBLISH_TOKEN=...  npx prepublish-mcp  # forwards a bearer token upstream
+ */
+export {};

package/dist/bridge.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+/**
+ * stdio bridge to the hosted PrePublish MCP server.
+ *
+ * The tools themselves live in the web app and are served over Streamable HTTP
+ * at https://prepublish.ai/mcp. That is the single source of truth: this process
+ * adds no tools of its own, it forwards. It exists for clients that can only
+ * speak stdio to a local command (Claude Desktop bundles, some editors and
+ * local agent runtimes), so those users are not left out while a remote
+ * connector is unavailable to them.
+ *
+ * The tool list is fetched from the remote server at startup, so adding a tool
+ * in the app requires no release here.
+ *
+ * Usage:
+ *   npx prepublish-mcp                       # bridges to https://mcp.prepublish.ai
+ *   PREPUBLISH_MCP_URL=... npx prepublish-mcp # bridges to another deployment
+ *   PREPUBLISH_TOKEN=...  npx prepublish-mcp  # forwards a bearer token upstream
+ */
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+const remoteUrl = process.env.PREPUBLISH_MCP_URL ?? 'https://mcp.prepublish.ai';
+const token = process.env.PREPUBLISH_TOKEN;
+const upstream = new Client({ name: 'prepublish-stdio-bridge', version: '1.0.0' });
+await upstream.connect(new StreamableHTTPClientTransport(new URL(remoteUrl), {
+    requestInit: token ? { headers: { authorization: `Bearer ${token}` } } : undefined,
+}));
+const { tools } = await upstream.listTools();
+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`);
+await local.connect(new StdioServerTransport());
+//# sourceMappingURL=bridge.js.map

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "prepublish-mcp",
+  "version": "1.0.0",
+  "description": "stdio bridge to the hosted PrePublish MCP server: audit a YouTube script before recording from any MCP client",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "youtube",
+    "script",
+    "retention",
+    "prepublish",
+    "claude",
+    "llm-tools"
+  ],
+  "homepage": "https://prepublish.ai/mcp-server",
+  "bugs": {
+    "url": "https://prepublish.ai/contact"
+  },
+  "license": "MIT",
+  "author": "PrePublish (https://prepublish.ai)",
+  "type": "module",
+  "bin": {
+    "prepublish-mcp": "dist/bridge.js"
+  },
+  "files": [
+    "dist/bridge.js",
+    "dist/bridge.d.ts",
+    "server.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/bridge.js",
+    "test": "tsx --test test/*.test.ts",
+    "test:conformance": "tsx --test test/conformance.test.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/server.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "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",
+  "websiteUrl": "https://prepublish.ai/mcp-server",
+  "remotes": [
+    {
+      "type": "streamable-http",
+      "url": "https://mcp.prepublish.ai"
+    }
+  ]
+}