@next-buildr/payload 0.0.0-stage → 2.0.1

package/dist/mcp/http-backend.js

@@ -0,0 +1,337 @@
+import { defaultTheme, fromManifest, ok, parseDocument, } from '@next-buildr/core';
+import { createDocumentInputSchema, listDocumentsQuerySchema, listMediaQuerySchema, mcpFail, sessionSchema, } from '@next-buildr/mcp';
+import { conflictResponseSchema, createDocumentResponseSchema, DOCUMENT_LIST_PAGE_SIZE, dataSchemaResponseSchema, documentListResponseSchema, documentResponseSchema, errorResponseSchema, invalidResponseSchema, mediaListResponseSchema, publishResponseSchema, saveResponseSchema, sessionResponseSchema, } from '../contract.js';
+const MAX_GATHER_PAGES = 25;
+const RETRY_STATUSES = new Set([429, 502, 503, 504]);
+const seg = (value) => encodeURIComponent(String(value));
+const documentPath = (ref) => `/buildr/documents/${seg(ref.collection)}/${seg(ref.id)}`;
+const diagnostic = (message) => ({
+    code: 'mcp.invalid-input',
+    message,
+    severity: 'error',
+});
+/** Diagnostics for input a Zod schema refused. */
+const zodDiagnostics = (error) => error.issues.map((issue) => ({
+    code: 'mcp.invalid-input',
+    message: issue.message,
+    severity: 'error',
+    path: issue.path.filter((part) => typeof part !== 'symbol'),
+}));
+const invalid = (message, diagnostics = [diagnostic(message)]) => mcpFail({ code: 'invalid', message, diagnostics });
+/**
+ * The `McpBackend` of `@next-buildr/mcp` over the builder API of a site running the Payload plugin
+ * (docs/mcp.md#http-backend). Authenticates with a Payload API key; every response is checked
+ * against the contract and documents with `parseDocument`. Only GETs are retried. The API key is
+ * sent as a header only and is scrubbed from every message this backend produces.
+ */
+export function createPayloadMcpBackend(options) {
+    const base = options.baseUrl.replace(/\/+$/, '');
+    const authHeader = `${options.collection ?? 'users'} API-Key ${options.apiKey}`;
+    const timeoutMs = options.timeoutMs ?? 15_000;
+    const retries = options.retries ?? 2;
+    const sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const theme = options.theme ?? defaultTheme;
+    const siteOrigin = (() => {
+        try {
+            return (options.siteUrl ?? new URL(base).origin).replace(/\/+$/, '');
+        }
+        catch {
+            return '';
+        }
+    })();
+    /** Every message that leaves this module passes here: the key must never show up in one. */
+    const redact = (text) => options.apiKey === '' ? text : text.split(options.apiKey).join('***');
+    const network = (message, retryable) => mcpFail({ code: 'network', message: redact(message), retryable });
+    async function attempt(method, path, init) {
+        const params = new URLSearchParams();
+        for (const [key, value] of Object.entries(init.query ?? {})) {
+            if (value !== undefined)
+                params.set(key, value);
+        }
+        const search = params.toString();
+        const url = `${base}${path}${search === '' ? '' : `?${search}`}`;
+        try {
+            const doFetch = options.fetch ?? globalThis.fetch;
+            const response = await doFetch(url, {
+                method,
+                headers: {
+                    authorization: authHeader,
+                    accept: 'application/json',
+                    ...(init.body === undefined ? {} : { 'content-type': 'application/json' }),
+                },
+                ...(init.body === undefined ? {} : { body: JSON.stringify(init.body) }),
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            const text = await response.text().catch(() => '');
+            let body;
+            if (text !== '') {
+                try {
+                    body = JSON.parse(text);
+                }
+                catch {
+                    body = undefined;
+                }
+            }
+            const retryAfter = Number(response.headers.get('retry-after'));
+            return {
+                status: response.status,
+                body,
+                retryAfter: Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter : undefined,
+            };
+        }
+        catch {
+            // The cause is dropped on purpose: it is not needed to act on and could echo request details.
+            return undefined;
+        }
+    }
+    /** Sends a request; only GETs are retried. `undefined` means the server never answered. */
+    async function send(method, path, init = {}) {
+        const maxRetries = method === 'GET' ? retries : 0;
+        for (let n = 0;; n += 1) {
+            const reply = await attempt(method, path, init);
+            const retryable = reply === undefined || RETRY_STATUSES.has(reply.status);
+            if (!retryable || n >= maxRetries)
+                return reply;
+            const hinted = reply?.retryAfter;
+            await sleep(Math.min(hinted === undefined ? 200 * 2 ** n : hinted * 1000, 5_000));
+        }
+    }
+    const messageOf = (reply, fallback) => {
+        const parsed = errorResponseSchema.safeParse(reply.body);
+        return redact(parsed.success ? parsed.data.error : fallback);
+    };
+    /** The failure of a reply that is not the success the caller expects. */
+    function refusal(reply, what) {
+        if (reply === undefined)
+            return network(`The site could not be reached (${what}).`, true);
+        switch (reply.status) {
+            case 401:
+                return mcpFail({
+                    code: 'forbidden',
+                    message: 'The API key was not accepted. Check the key and that its user has API access enabled.',
+                });
+            case 403:
+                return mcpFail({
+                    code: 'forbidden',
+                    message: messageOf(reply, 'This user may not do that.'),
+                });
+            case 404:
+                return mcpFail({
+                    code: 'not-found',
+                    message: messageOf(reply, `Not found (${what}).`),
+                });
+            case 409: {
+                const parsed = conflictResponseSchema.safeParse(reply.body);
+                if (parsed.success) {
+                    return mcpFail({
+                        code: 'conflict',
+                        message: `The document was changed by somebody else; it is now at revision ${parsed.data.currentRevision}. Reload it and re-apply your changes.`,
+                        currentRevision: parsed.data.currentRevision,
+                    });
+                }
+                return network('The site reported a conflict without a revision.', false);
+            }
+            case 400:
+                return invalid(messageOf(reply, 'The request was not valid.'));
+            case 422: {
+                const parsed = invalidResponseSchema.safeParse(reply.body);
+                if (parsed.success && parsed.data.diagnostics.length > 0) {
+                    return invalid(redact(parsed.data.diagnostics[0]?.message ?? 'The document is not valid.'), parsed.data.diagnostics.map((d) => ({
+                        ...d,
+                        message: redact(d.message),
+                    })));
+                }
+                return invalid(messageOf(reply, 'The document is not valid.'));
+            }
+            case 429:
+                return network(`Too many requests${reply.retryAfter === undefined ? '' : `; retry in ${reply.retryAfter} s`}.`, true);
+            default:
+                return network(`The site answered ${reply.status} (${what}).`, reply.status >= 500);
+        }
+    }
+    /** The body of `reply` when it has `status` and matches `schema`, else a failure. */
+    function expectBody(reply, schema, what, status = 200) {
+        if (reply === undefined || reply.status !== status)
+            return refusal(reply, what);
+        const parsed = schema.safeParse(reply.body);
+        if (!parsed.success) {
+            return network(`The site's answer does not match the builder contract (${what}).`, false);
+        }
+        return ok(parsed.data);
+    }
+    const summaryOf = (doc) => ({
+        ref: doc.ref,
+        title: doc.title,
+        slug: doc.slug,
+        status: doc.status,
+        updatedAt: doc.updatedAt,
+        revision: doc.revision,
+    });
+    /** One server page (20 documents) of one collection. */
+    async function fetchPage(collection, search, page) {
+        const reply = await send('GET', '/buildr/documents', {
+            query: { collection, search, page: String(page) },
+        });
+        return expectBody(reply, documentListResponseSchema, 'listing documents');
+    }
+    async function listDocuments(input) {
+        const query = listDocumentsQuerySchema.safeParse(input ?? {});
+        if (!query.success)
+            return invalid('The query is not valid.', zodDiagnostics(query.error));
+        const { collection, search, status, page, limit } = query.data;
+        const collections = collection === undefined ? [...(options.collections ?? [])] : [collection];
+        if (collections.length === 0)
+            return invalid('Pass a collection to list documents from.');
+        const start = (page - 1) * limit;
+        const finish = (items, total) => ok({ items, page, total, totalPages: Math.ceil(total / limit) });
+        // A status filter or several collections need everything (capped); one collection is windowed.
+        if (collections.length > 1 || status !== undefined) {
+            const all = [];
+            for (const name of collections) {
+                for (let n = 1; n <= MAX_GATHER_PAGES; n += 1) {
+                    const result = await fetchPage(name, search, n);
+                    if (!result.ok) {
+                        if (result.error.code === 'not-found')
+                            break;
+                        return result;
+                    }
+                    all.push(...result.value.items.map(summaryOf));
+                    if (n >= result.value.totalPages)
+                        break;
+                }
+            }
+            const filtered = (status === undefined ? all : all.filter((d) => d.status === status)).sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+            return finish(filtered.slice(start, start + limit), filtered.length);
+        }
+        const name = collections[0];
+        const first = Math.floor(start / DOCUMENT_LIST_PAGE_SIZE) + 1;
+        const last = Math.floor((start + limit - 1) / DOCUMENT_LIST_PAGE_SIZE) + 1;
+        const items = [];
+        let totalPages = 0;
+        let lastCount = 0;
+        let lastSeen = 0;
+        for (let n = first; n <= last; n += 1) {
+            const result = await fetchPage(name, search, n);
+            if (!result.ok) {
+                // A collection the builder does not know has no documents.
+                if (result.error.code === 'not-found')
+                    return finish([], 0);
+                return result;
+            }
+            totalPages = result.value.totalPages;
+            if (n > totalPages)
+                break;
+            items.push(...result.value.items.map(summaryOf));
+            lastSeen = n;
+            lastCount = result.value.items.length;
+            if (n >= totalPages)
+                break;
+        }
+        if (totalPages === 0)
+            return finish([], 0);
+        if (lastSeen !== totalPages) {
+            // The exact total needs the size of the last server page.
+            const tail = await fetchPage(name, search, totalPages);
+            if (!tail.ok)
+                return tail;
+            lastCount = tail.value.items.length;
+        }
+        const total = (totalPages - 1) * DOCUMENT_LIST_PAGE_SIZE + lastCount;
+        const offset = start - (first - 1) * DOCUMENT_LIST_PAGE_SIZE;
+        return finish(items.slice(offset, offset + limit), total);
+    }
+    return {
+        async getSession() {
+            const reply = await send('GET', '/buildr/session');
+            const body = expectBody(reply, sessionResponseSchema, 'reading the session');
+            if (!body.ok)
+                return body;
+            const parsed = sessionSchema.safeParse(body.value);
+            if (!parsed.success) {
+                return network('The session does not match the builder contract.', false);
+            }
+            return ok(parsed.data);
+        },
+        async getManifest() {
+            const reply = await send('GET', '/buildr/manifest');
+            if (reply === undefined || reply.status !== 200) {
+                return refusal(reply, 'reading the manifest');
+            }
+            const manifest = fromManifest(reply.body);
+            if (!manifest.ok)
+                return network('The manifest does not match the builder contract.', false);
+            return ok(manifest.value);
+        },
+        async getTheme() {
+            return ok(theme);
+        },
+        listDocuments,
+        async createDocument(input) {
+            const parsed = createDocumentInputSchema.safeParse(input);
+            if (!parsed.success)
+                return invalid('The input is not valid.', zodDiagnostics(parsed.error));
+            const reply = await send('POST', '/buildr/documents', { body: parsed.data });
+            const body = expectBody(reply, createDocumentResponseSchema, 'creating a document', 201);
+            return body.ok ? ok(summaryOf(body.value)) : body;
+        },
+        async load(ref, loadOptions) {
+            const reply = await send('GET', documentPath(ref), {
+                query: { draft: '1', locale: loadOptions?.locale },
+            });
+            const body = expectBody(reply, documentResponseSchema, 'loading the document');
+            if (!body.ok)
+                return body;
+            const doc = parseDocument(body.value.document);
+            if (!doc.ok)
+                return invalid('The stored document is not valid.', doc.error);
+            const { document: _raw, ...rest } = body.value;
+            const { readOnly, ...fields } = rest;
+            return ok({
+                ...fields,
+                document: doc.value,
+                ...(readOnly === undefined ? {} : { readOnly }),
+            });
+        },
+        async save(ref, doc, baseRevision) {
+            const parsed = parseDocument(doc);
+            if (!parsed.ok)
+                return invalid('The document is not valid.', parsed.error);
+            const reply = await send('PUT', documentPath(ref), {
+                body: { document: parsed.value, baseRevision, autosave: false },
+            });
+            return expectBody(reply, saveResponseSchema, 'saving the document');
+        },
+        async publish(ref, baseRevision) {
+            const reply = await send('POST', `${documentPath(ref)}/publish`, { body: { baseRevision } });
+            return expectBody(reply, publishResponseSchema, 'publishing the document');
+        },
+        async getDataSchema(collection) {
+            const reply = await send('GET', `/buildr/data-schema/${seg(collection)}`);
+            return expectBody(reply, dataSchemaResponseSchema, 'reading the data schema');
+        },
+        async listMedia(input) {
+            const query = listMediaQuerySchema.safeParse(input ?? {});
+            if (!query.success)
+                return invalid('The query is not valid.', zodDiagnostics(query.error));
+            const reply = await send('GET', '/buildr/media', {
+                query: {
+                    search: query.data.search === '' ? undefined : query.data.search,
+                    type: query.data.type,
+                    page: String(query.data.page),
+                },
+            });
+            // A site without a media collection has no media.
+            if (reply?.status === 404)
+                return ok({ items: [], page: query.data.page, totalPages: 0 });
+            return expectBody(reply, mediaListResponseSchema, 'listing media');
+        },
+        async previewUrl(ref) {
+            const reply = await send('GET', documentPath(ref), { query: { draft: '1' } });
+            const body = expectBody(reply, documentResponseSchema, 'resolving the preview');
+            if (!body.ok)
+                return body;
+            const path = body.value.previewPath;
+            return ok(path === null ? null : `${siteOrigin}${path}`);
+        },
+    };
+}

package/dist/mcp/http-backend.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=http-backend.test.d.ts.map

package/dist/mcp/http-backend.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-backend.test.d.ts","sourceRoot":"","sources":["../../src/mcp/http-backend.test.ts"],"names":[],"mappings":""}

package/dist/mcp/http-backend.test.js

@@ -0,0 +1,178 @@
+import { createEmptyDocument } from '@next-buildr/core';
+import { describe, expect, it, vi } from 'vitest';
+import { createPayloadMcpBackend } from './http-backend.js';
+const KEY = 'super-secret-api-key-123';
+const json = (status, body, headers = {}) => new Response(JSON.stringify(body), {
+    status,
+    headers: { 'content-type': 'application/json', ...headers },
+});
+const summary = (id) => ({
+    ref: { collection: 'pages', id: String(id) },
+    title: `Page ${id}`,
+    slug: `page-${id}`,
+    status: 'draft',
+    updatedAt: '2026-01-01T00:00:00.000Z',
+    revision: 0,
+    layoutSource: 'builtin',
+    previewPath: null,
+});
+const ref = { collection: 'pages', id: '1' };
+function setup(handler, o = {}) {
+    const requests = [];
+    const fetch = vi.fn(async (input, init) => {
+        const request = new Request(input, init);
+        requests.push(request);
+        return handler(request);
+    });
+    const backend = createPayloadMcpBackend({
+        baseUrl: 'https://site.test/api/',
+        apiKey: KEY,
+        fetch: fetch,
+        sleep: async () => { },
+        ...o,
+    });
+    return { backend, requests, fetch };
+}
+describe('createPayloadMcpBackend', () => {
+    it('sends the key as an API-Key header and never in the URL', async () => {
+        const { backend, requests } = setup(() => json(200, {
+            user: { id: 1 },
+            permissions: { canEdit: true, canPublish: false, canUnlockTemplates: false },
+            limits: { maxNodes: 10, maxBytes: 10 },
+        }));
+        expect((await backend.getSession()).ok).toBe(true);
+        expect(requests[0]?.headers.get('authorization')).toBe(`users API-Key ${KEY}`);
+        expect(requests[0]?.url).toBe('https://site.test/api/buildr/session');
+        expect(requests[0]?.url).not.toContain(KEY);
+    });
+    it('uses the configured auth collection', async () => {
+        const { backend, requests } = setup(() => json(404, {}), { collection: 'agents' });
+        await backend.getDataSchema('pages');
+        expect(requests[0]?.headers.get('authorization')).toBe(`agents API-Key ${KEY}`);
+    });
+    it('never leaks the key: not from thrown fetch errors, server messages or diagnostics', async () => {
+        const results = [];
+        for (const handler of [
+            () => {
+                throw new Error(`connect failed with Authorization: users API-Key ${KEY}`);
+            },
+            () => json(500, { error: `boom ${KEY}` }),
+            () => json(403, { error: `denied for ${KEY}` }),
+            () => json(400, { error: `bad ${KEY}` }),
+            () => json(404, { error: `missing ${KEY}` }),
+            () => json(422, { diagnostics: [{ code: 'x', message: `no ${KEY}`, severity: 'error' }] }),
+            () => json(401, { error: KEY }),
+            () => new Response(`<html>${KEY}</html>`, { status: 200 }),
+        ]) {
+            const { backend } = setup(handler, { retries: 0 });
+            results.push(await backend.load(ref), await backend.save(ref, createEmptyDocument(), 0));
+        }
+        expect(results.every((r) => !r.ok)).toBe(true);
+        expect(JSON.stringify(results)).not.toContain(KEY);
+    });
+    it('retries GETs with backoff on network errors and 503, then succeeds', async () => {
+        const sleep = vi.fn(async (_ms) => { });
+        let calls = 0;
+        const { backend } = setup(() => {
+            calls += 1;
+            if (calls === 1)
+                throw new Error('reset');
+            if (calls === 2)
+                return json(503, {});
+            return json(200, { items: [], page: 1, totalPages: 0 });
+        }, { sleep, retries: 2 });
+        expect((await backend.listDocuments({ collection: 'pages' })).ok).toBe(true);
+        expect(calls).toBe(3);
+        expect(sleep.mock.calls.map((c) => c[0])).toEqual([200, 400]);
+    });
+    it('reports a retryable network error once retries are exhausted', async () => {
+        const { backend, fetch } = setup(() => json(503, {}), { retries: 1 });
+        const result = await backend.load(ref);
+        expect(fetch).toHaveBeenCalledTimes(2);
+        expect(!result.ok && result.error).toMatchObject({ code: 'network', retryable: true });
+    });
+    it('never retries writes', async () => {
+        const { backend, fetch } = setup(() => json(503, {}), { retries: 3 });
+        await backend.save(ref, createEmptyDocument(), 0);
+        await backend.publish(ref, 0);
+        await backend.createDocument({ collection: 'pages', title: 'x' });
+        expect(fetch).toHaveBeenCalledTimes(3);
+    });
+    it('maps 409 to conflict with the current revision and 429 to a retryable network error', async () => {
+        const conflict = setup(() => json(409, { currentRevision: 7 })).backend;
+        const saved = await conflict.save(ref, createEmptyDocument(), 3);
+        expect(!saved.ok && saved.error).toMatchObject({ code: 'conflict', currentRevision: 7 });
+        const limited = setup(() => json(429, { error: 'slow down' }, { 'retry-after': '7' })).backend;
+        const created = await limited.createDocument({ collection: 'pages', title: 'x' });
+        expect(!created.ok && created.error).toMatchObject({ code: 'network', retryable: true });
+    });
+    it('maps 422 to invalid with the server diagnostics', async () => {
+        const { backend } = setup(() => json(422, {
+            diagnostics: [
+                { code: 'doc.bad', message: 'Bad node.', severity: 'error', path: ['nodes', 'a'] },
+            ],
+        }));
+        const result = await backend.save(ref, createEmptyDocument(), 0);
+        expect(!result.ok && result.error).toMatchObject({
+            code: 'invalid',
+            diagnostics: [{ code: 'doc.bad', path: ['nodes', 'a'] }],
+        });
+    });
+    it('rejects an answer that breaks the contract without retrying', async () => {
+        const { backend, fetch } = setup(() => json(200, { unexpected: true }));
+        const result = await backend.getSession();
+        expect(!result.ok && result.error).toMatchObject({ code: 'network', retryable: false });
+        expect(fetch).toHaveBeenCalledTimes(1);
+    });
+    it('validates input before sending anything', async () => {
+        const { backend, fetch } = setup(() => json(200, {}));
+        expect((await backend.listDocuments({ limit: 0 })).ok).toBe(false);
+        expect((await backend.createDocument({ collection: 'pages', title: '' })).ok).toBe(false);
+        expect((await backend.save(ref, { nonsense: true }, 0)).ok).toBe(false);
+        expect((await backend.listDocuments()).ok).toBe(false); // no collection, none configured
+        expect(fetch).not.toHaveBeenCalled();
+    });
+    it('windows a listing over the 20-per-page server pages and reports the exact total', async () => {
+        const { backend, requests } = setup((request) => {
+            const page = Number(new URL(request.url).searchParams.get('page'));
+            const count = page === 3 ? 5 : 20;
+            const items = Array.from({ length: count }, (_, i) => summary((page - 1) * 20 + i + 1));
+            return json(200, { items, page, totalPages: 3 });
+        });
+        const result = await backend.listDocuments({ collection: 'pages', page: 2, limit: 30 });
+        expect(result.ok && result.value.total).toBe(45);
+        expect(result.ok && result.value.totalPages).toBe(2);
+        expect(result.ok && result.value.items.map((i) => i.ref.id)).toEqual(Array.from({ length: 15 }, (_, i) => String(31 + i)));
+        expect(requests.map((r) => new URL(r.url).searchParams.get('page'))).toEqual(['2', '3']);
+    });
+    it('lists the configured collections when none is given, filtered by status', async () => {
+        const { backend } = setup((request) => {
+            const collection = new URL(request.url).searchParams.get('collection');
+            const draft = { ...summary(collection === 'pages' ? 1 : 2), ref: { collection, id: '1' } };
+            const live = { ...summary(3), status: 'published', ref: { collection, id: '3' } };
+            return json(200, { items: [draft, live], page: 1, totalPages: 1 });
+        }, { collections: ['pages', 'posts'] });
+        const all = await backend.listDocuments();
+        expect(all.ok && all.value.total).toBe(4);
+        const drafts = await backend.listDocuments({ status: 'draft' });
+        expect(drafts.ok && drafts.value.items.every((i) => i.status === 'draft')).toBe(true);
+        expect(drafts.ok && drafts.value.total).toBe(2);
+    });
+    it('builds the preview URL from the site origin', async () => {
+        const { backend } = setup(() => json(200, {
+            ref,
+            title: 'Home',
+            slug: 'home',
+            status: 'draft',
+            updatedAt: 'x',
+            revision: 0,
+            document: createEmptyDocument(),
+            contextRef: 'pages:1',
+            layoutSource: 'document',
+            layoutRef: 'pages:1',
+            previewPath: '/home',
+        }));
+        const url = await backend.previewUrl(ref);
+        expect(url.ok && url.value).toBe('https://site.test/home');
+    });
+});

package/dist/mcp/index.d.ts

@@ -0,0 +1,2 @@
+export { createPayloadMcpBackend, type PayloadMcpBackendOptions } from './http-backend.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/mcp/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,uBAAuB,EAAE,KAAK,wBAAwB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/mcp/index.js

@@ -0,0 +1,2 @@
+// `@next-buildr/payload/mcp`: the HTTP backend of `@next-buildr/mcp` over the builder API (ADR-024, docs/mcp.md).
+export { createPayloadMcpBackend } from './http-backend.js';

package/dist/mcp/route.d.ts

@@ -0,0 +1,63 @@
+import { type RegistryMeta, type Theme } from '@next-buildr/core';
+import { type Payload } from 'payload';
+import { type RateLimiter } from '../plugin/forms/rate-limit.ts';
+/**
+ * `@next-buildr/payload/mcp/route`: the remote MCP server of a site (ADR-024, docs/mcp.md). A Next.js
+ * route handler over the SDK's Streamable HTTP transport in its stateless request/response mode.
+ * It is the only file of `payload/mcp` that may import `payload`.
+ */
+export interface BuildrMcpRouteOptions {
+    /** The Payload instance, or a function that returns it (`() => getPayload({ config })`). */
+    readonly payload: Payload | (() => Promise<Payload>);
+    /** The site's registry; its manifest is served when the plugin was configured without one. */
+    readonly registry: {
+        readonly meta: RegistryMeta;
+    };
+    /** The site's theme (default: the default theme). */
+    readonly theme?: Theme;
+    /** Lets agents call `publish` (they still need `mcp.allowPublish` and `access.publish`). Default false. */
+    readonly allowPublish?: boolean;
+    /**
+     * Origins (besides the site's own and Payload's `csrf` list) that may send a browser `Origin`
+     * header. Clients without an `Origin` header (every MCP client that is not a web page) are unaffected.
+     */
+    readonly allowedOrigins?: readonly string[];
+    /** The builder collections agents may list (default: every collection the plugin extended). */
+    readonly collections?: readonly string[];
+    /** Origin used to build preview URLs (default: the origin of the request). */
+    readonly siteUrl?: string;
+    /** Requests per authenticated user and window (default 120 per minute). */
+    readonly rateLimit?: {
+        readonly limit: number;
+        readonly windowMs: number;
+    };
+    /** Replaces the in-memory limiter (which does not span serverless instances). */
+    readonly rateLimiter?: RateLimiter;
+    /** Idle time after which a user's open documents are dropped (default 30 minutes). */
+    readonly sessionTtlMs?: number;
+    /** Largest accepted request body in bytes (default 1 MB). */
+    readonly maxBodyBytes?: number;
+}
+export interface BuildrMcpRoute {
+    readonly POST: (request: Request) => Promise<Response>;
+    readonly GET: (request: Request) => Promise<Response>;
+    readonly DELETE: (request: Request) => Promise<Response>;
+}
+/**
+ * `createBuildrMcpRoute({ payload, registry })` returns the `POST`/`GET`/`DELETE` handlers of the
+ * MCP endpoint. Mount them at `app/(builder)/api/buildr/mcp/route.ts`.
+ *
+ * - Disabled (`404`) unless the plugin has `mcp.enabled`.
+ * - Only `Authorization: <collection> API-Key <key>` authenticates; cookies are never read (`401`),
+ *   so a browser cannot drive the endpoint cross-site. A browser `Origin` must be the site's own,
+ *   in Payload's `csrf` list or in `allowedOrigins`.
+ * - The tools run against a local backend: the builder API of the same Payload, called in-process
+ *   (no network hop) as the agent user, so Payload's access control, the plugin's `access`, the
+ *   write limits and the revision checks apply exactly as over the network.
+ * - Stateless: each request is one JSON-RPC exchange on a fresh server. Open documents live in a
+ *   per-user session store held by this route (one per `createBuildrMcpRoute` call, never global);
+ *   on serverless platforms it lives as long as the instance does, and an unknown session after a
+ *   cold start is reported to the agent, which reopens the document.
+ */
+export declare function createBuildrMcpRoute(options: BuildrMcpRouteOptions): BuildrMcpRoute;
+//# sourceMappingURL=route.d.ts.map

package/dist/mcp/route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../src/mcp/route.ts"],"names":[],"mappings":"AACA,OAAO,EAAM,KAAK,YAAY,EAAE,KAAK,KAAK,EAAc,MAAM,mBAAmB,CAAC;AAWlF,OAAO,EAAmB,KAAK,OAAO,EAAE,MAAM,SAAS,CAAC;AACxD,OAAO,EAA2B,KAAK,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAG1F;;;;GAIG;AAEH,MAAM,WAAW,qBAAqB;IACpC,4FAA4F;IAC5F,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,CAAC,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;IACrD,8FAA8F;IAC9F,QAAQ,CAAC,QAAQ,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;KAAE,CAAC;IACnD,qDAAqD;IACrD,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IACvB,2GAA2G;IAC3G,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,+FAA+F;IAC/F,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3E,iFAAiF;IACjF,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IACnC,sFAAsF;IACtF,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,6DAA6D;IAC7D,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IACvD,QAAQ,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IACtD,QAAQ,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC1D;AAiCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,cAAc,CAqNnF"}