payload-mcp-toolkit 0.2.0

package/dist/__tests__/url-validator.test.js

@@ -0,0 +1,326 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import dns from 'node:dns';
+import { isPrivateIp, validateAndFetchUrl } from '../url-validator';
+// ─── isPrivateIp — pure unit tests ────────────────────────────────
+describe('isPrivateIp', ()=>{
+    describe('IPv4 — blocked ranges', ()=>{
+        it.each([
+            [
+                '10.0.0.1',
+                '10.0.0.0/8'
+            ],
+            [
+                '10.255.255.255',
+                '10.0.0.0/8 upper'
+            ],
+            [
+                '172.16.0.1',
+                '172.16.0.0/12 lower'
+            ],
+            [
+                '172.20.5.5',
+                '172.16.0.0/12 mid'
+            ],
+            [
+                '172.31.255.255',
+                '172.16.0.0/12 upper'
+            ],
+            [
+                '192.168.1.1',
+                '192.168.0.0/16'
+            ],
+            [
+                '127.0.0.1',
+                '127.0.0.0/8 loopback'
+            ],
+            [
+                '127.255.255.255',
+                '127.0.0.0/8 upper'
+            ],
+            [
+                '169.254.169.254',
+                '169.254.0.0/16 — AWS metadata'
+            ],
+            [
+                '0.0.0.0',
+                'unspecified — 0.0.0.0/8'
+            ],
+            [
+                '0.0.0.1',
+                '0.0.0.0/8 not just :0'
+            ],
+            [
+                '0.255.255.255',
+                '0.0.0.0/8 upper'
+            ],
+            [
+                '100.64.0.0',
+                '100.64.0.0/10 — CGNAT lower'
+            ],
+            [
+                '100.100.50.50',
+                '100.64.0.0/10 — CGNAT mid'
+            ],
+            [
+                '100.127.255.255',
+                '100.64.0.0/10 — CGNAT upper'
+            ]
+        ])('blocks %s (%s)', (ip)=>{
+            expect(isPrivateIp(ip)).toBe(true);
+        });
+    });
+    describe('IPv4 — public (allowed)', ()=>{
+        it.each([
+            [
+                '8.8.8.8'
+            ],
+            [
+                '1.1.1.1'
+            ],
+            [
+                '172.15.0.1'
+            ],
+            [
+                '172.32.0.1'
+            ],
+            [
+                '11.0.0.1'
+            ],
+            [
+                '192.169.1.1'
+            ],
+            [
+                '126.255.255.255'
+            ],
+            [
+                '128.0.0.1'
+            ],
+            [
+                '100.63.255.255'
+            ],
+            [
+                '100.128.0.0'
+            ],
+            [
+                '1.0.0.1'
+            ]
+        ])('allows %s', (ip)=>{
+            expect(isPrivateIp(ip)).toBe(false);
+        });
+    });
+    describe('IPv6 — blocked ranges', ()=>{
+        it.each([
+            [
+                '::1',
+                'loopback shorthand'
+            ],
+            [
+                '0:0:0:0:0:0:0:1',
+                'loopback expanded'
+            ],
+            [
+                '0000:0000:0000:0000:0000:0000:0000:0001',
+                'loopback fully expanded'
+            ],
+            [
+                'fc00::1',
+                'unique local fc'
+            ],
+            [
+                'fd12:3456:789a::1',
+                'unique local fd'
+            ],
+            [
+                'fe80::1',
+                'link-local'
+            ],
+            [
+                'FE80::1',
+                'link-local case-insensitive'
+            ],
+            [
+                'febf::1',
+                'link-local upper boundary fe80::/10'
+            ],
+            [
+                '::ffff:127.0.0.1',
+                'IPv4-mapped loopback'
+            ],
+            [
+                '::ffff:10.0.0.1',
+                'IPv4-mapped private 10/8'
+            ],
+            [
+                '::ffff:169.254.169.254',
+                'IPv4-mapped AWS metadata'
+            ],
+            [
+                '::ffff:100.64.0.1',
+                'IPv4-mapped CGNAT'
+            ],
+            [
+                '::127.0.0.1',
+                'IPv4-compat loopback'
+            ]
+        ])('blocks %s (%s)', (ip)=>{
+            expect(isPrivateIp(ip)).toBe(true);
+        });
+    });
+    describe('IPv6 — public (allowed)', ()=>{
+        it.each([
+            [
+                '2001:4860:4860::8888'
+            ],
+            [
+                '2606:4700:4700::1111'
+            ],
+            [
+                'ff00::1'
+            ],
+            [
+                '::ffff:8.8.8.8'
+            ],
+            [
+                'fec0::1'
+            ]
+        ])('allows %s', (ip)=>{
+            expect(isPrivateIp(ip)).toBe(false);
+        });
+    });
+});
+// ─── validateAndFetchUrl — integration with mocked DNS + fetch ────
+describe('validateAndFetchUrl', ()=>{
+    const originalFetch = globalThis.fetch;
+    let dnsLookupSpy;
+    beforeEach(()=>{
+        dnsLookupSpy = vi.spyOn(dns.promises, 'lookup');
+    });
+    afterEach(()=>{
+        vi.restoreAllMocks();
+        globalThis.fetch = originalFetch;
+    });
+    function mockDns(address, family = 4) {
+        dnsLookupSpy.mockResolvedValue({
+            address,
+            family
+        });
+    }
+    function mockFetch(impl) {
+        globalThis.fetch = vi.fn((url)=>Promise.resolve(impl(String(url))));
+    }
+    it('rejects non-HTTPS schemes', async ()=>{
+        await expect(validateAndFetchUrl('http://example.com/x.png')).rejects.toThrow(/HTTPS/);
+    });
+    it('rejects when DNS resolves to a private IPv4 (SSRF)', async ()=>{
+        mockDns('10.0.0.5');
+        await expect(validateAndFetchUrl('https://attacker.example/x.png')).rejects.toThrow(/SSRF blocked/);
+    });
+    it('rejects when DNS resolves to AWS metadata IP (SSRF)', async ()=>{
+        mockDns('169.254.169.254');
+        await expect(validateAndFetchUrl('https://metadata.example/x.png')).rejects.toThrow(/SSRF blocked/);
+    });
+    it('rejects when DNS resolves to ::1 (SSRF)', async ()=>{
+        mockDns('::1', 6);
+        await expect(validateAndFetchUrl('https://localhost.example/x.png')).rejects.toThrow(/SSRF blocked/);
+    });
+    it('fetches successfully when DNS resolves to a public IP', async ()=>{
+        mockDns('8.8.8.8');
+        mockFetch(()=>new Response(new Uint8Array([
+                1,
+                2,
+                3
+            ]), {
+                status: 200,
+                headers: {
+                    'content-type': 'image/png'
+                }
+            }));
+        const result = await validateAndFetchUrl('https://example.com/cat.png');
+        expect(result.contentType).toBe('image/png');
+        expect(result.filename).toBe('cat.png');
+        expect(result.buffer.length).toBe(3);
+    });
+    it('follows redirects and re-validates the redirect target', async ()=>{
+        let call = 0;
+        // First lookup: public. Second lookup (after redirect): private → must block.
+        dnsLookupSpy.mockImplementation(async ()=>{
+            call++;
+            return {
+                address: call === 1 ? '8.8.8.8' : '127.0.0.1',
+                family: 4
+            };
+        });
+        mockFetch((url)=>{
+            if (url === 'https://example.com/start') {
+                return new Response(null, {
+                    status: 302,
+                    headers: {
+                        location: 'https://internal.example/secret'
+                    }
+                });
+            }
+            throw new Error(`should not reach ${url} — redirect target must be blocked`);
+        });
+        await expect(validateAndFetchUrl('https://example.com/start')).rejects.toThrow(/SSRF blocked/);
+        expect(call).toBe(2);
+    });
+    it('caps redirect chains at maxRedirects', async ()=>{
+        mockDns('8.8.8.8');
+        mockFetch((url)=>new Response(null, {
+                status: 302,
+                headers: {
+                    location: url + '/again'
+                }
+            }));
+        await expect(validateAndFetchUrl('https://example.com/loop', {
+            maxRedirects: 2
+        })).rejects.toThrow(/Too many redirects/);
+    });
+    it('errors when a redirect response has no Location header', async ()=>{
+        mockDns('8.8.8.8');
+        mockFetch(()=>new Response(null, {
+                status: 302
+            }));
+        await expect(validateAndFetchUrl('https://example.com/x.png')).rejects.toThrow(/Location header/);
+    });
+    it('surfaces non-OK HTTP responses', async ()=>{
+        mockDns('8.8.8.8');
+        mockFetch(()=>new Response(null, {
+                status: 404,
+                statusText: 'Not Found'
+            }));
+        await expect(validateAndFetchUrl('https://example.com/x.png')).rejects.toThrow(/404/);
+    });
+    it('derives a UUID filename when the URL path has no extension', async ()=>{
+        mockDns('8.8.8.8');
+        mockFetch(()=>new Response(new Uint8Array([
+                0
+            ]), {
+                status: 200,
+                headers: {
+                    'content-type': 'image/jpeg'
+                }
+            }));
+        const result = await validateAndFetchUrl('https://example.com/no-extension');
+        expect(result.filename).toMatch(/\.jpg$/);
+        expect(result.filename).not.toBe('no-extension');
+    });
+    it('strips path traversal segments from derived filenames', async ()=>{
+        mockDns('8.8.8.8');
+        mockFetch(()=>new Response(new Uint8Array([
+                0
+            ]), {
+                status: 200,
+                headers: {
+                    'content-type': 'image/png'
+                }
+            }));
+        const result = await validateAndFetchUrl('https://example.com/foo/..%2Fevil.png');
+        // URL parser decodes %2F into /, so lastSegment ends up "..evil.png" after .. strip
+        expect(result.filename).not.toContain('..');
+        expect(result.filename).not.toContain('/');
+        expect(result.filename).not.toContain('\\');
+    });
+});
+
+//# sourceMappingURL=url-validator.test.js.map

package/dist/__tests__/url-validator.test.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/__tests__/url-validator.test.ts"],"sourcesContent":["import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'\nimport dns from 'node:dns'\nimport { isPrivateIp, validateAndFetchUrl } from '../url-validator'\n\n// ─── isPrivateIp — pure unit tests ────────────────────────────────\n\ndescribe('isPrivateIp', () => {\n  describe('IPv4 — blocked ranges', () => {\n    it.each([\n      ['10.0.0.1', '10.0.0.0/8'],\n      ['10.255.255.255', '10.0.0.0/8 upper'],\n      ['172.16.0.1', '172.16.0.0/12 lower'],\n      ['172.20.5.5', '172.16.0.0/12 mid'],\n      ['172.31.255.255', '172.16.0.0/12 upper'],\n      ['192.168.1.1', '192.168.0.0/16'],\n      ['127.0.0.1', '127.0.0.0/8 loopback'],\n      ['127.255.255.255', '127.0.0.0/8 upper'],\n      ['169.254.169.254', '169.254.0.0/16 — AWS metadata'],\n      ['0.0.0.0', 'unspecified — 0.0.0.0/8'],\n      ['0.0.0.1', '0.0.0.0/8 not just :0'],\n      ['0.255.255.255', '0.0.0.0/8 upper'],\n      ['100.64.0.0', '100.64.0.0/10 — CGNAT lower'],\n      ['100.100.50.50', '100.64.0.0/10 — CGNAT mid'],\n      ['100.127.255.255', '100.64.0.0/10 — CGNAT upper'],\n    ])('blocks %s (%s)', (ip) => {\n      expect(isPrivateIp(ip)).toBe(true)\n    })\n  })\n\n  describe('IPv4 — public (allowed)', () => {\n    it.each([\n      ['8.8.8.8'],\n      ['1.1.1.1'],\n      ['172.15.0.1'], // just outside 172.16/12\n      ['172.32.0.1'], // just outside 172.16/12\n      ['11.0.0.1'],\n      ['192.169.1.1'], // not 192.168\n      ['126.255.255.255'],\n      ['128.0.0.1'],\n      ['100.63.255.255'], // just below CGNAT\n      ['100.128.0.0'], // just above CGNAT\n      ['1.0.0.1'], // outside 0.0.0.0/8\n    ])('allows %s', (ip) => {\n      expect(isPrivateIp(ip)).toBe(false)\n    })\n  })\n\n  describe('IPv6 — blocked ranges', () => {\n    it.each([\n      ['::1', 'loopback shorthand'],\n      ['0:0:0:0:0:0:0:1', 'loopback expanded'],\n      ['0000:0000:0000:0000:0000:0000:0000:0001', 'loopback fully expanded'],\n      ['fc00::1', 'unique local fc'],\n      ['fd12:3456:789a::1', 'unique local fd'],\n      ['fe80::1', 'link-local'],\n      ['FE80::1', 'link-local case-insensitive'],\n      ['febf::1', 'link-local upper boundary fe80::/10'],\n      ['::ffff:127.0.0.1', 'IPv4-mapped loopback'],\n      ['::ffff:10.0.0.1', 'IPv4-mapped private 10/8'],\n      ['::ffff:169.254.169.254', 'IPv4-mapped AWS metadata'],\n      ['::ffff:100.64.0.1', 'IPv4-mapped CGNAT'],\n      ['::127.0.0.1', 'IPv4-compat loopback'],\n    ])('blocks %s (%s)', (ip) => {\n      expect(isPrivateIp(ip)).toBe(true)\n    })\n  })\n\n  describe('IPv6 — public (allowed)', () => {\n    it.each([\n      ['2001:4860:4860::8888'], // Google DNS\n      ['2606:4700:4700::1111'], // Cloudflare DNS\n      ['ff00::1'], // multicast — not in our private blocklist\n      ['::ffff:8.8.8.8'], // IPv4-mapped public\n      ['fec0::1'], // outside fe80::/10 (deprecated site-local, but not our match)\n    ])('allows %s', (ip) => {\n      expect(isPrivateIp(ip)).toBe(false)\n    })\n  })\n})\n\n// ─── validateAndFetchUrl — integration with mocked DNS + fetch ────\n\ndescribe('validateAndFetchUrl', () => {\n  const originalFetch = globalThis.fetch\n  let dnsLookupSpy: ReturnType<typeof vi.spyOn>\n\n  beforeEach(() => {\n    dnsLookupSpy = vi.spyOn(dns.promises, 'lookup')\n  })\n\n  afterEach(() => {\n    vi.restoreAllMocks()\n    globalThis.fetch = originalFetch\n  })\n\n  function mockDns(address: string, family: 4 | 6 = 4) {\n    dnsLookupSpy.mockResolvedValue({ address, family } as any)\n  }\n\n  function mockFetch(impl: (url: string) => Promise<Response> | Response) {\n    globalThis.fetch = vi.fn(((url: any) => Promise.resolve(impl(String(url)))) as any) as any\n  }\n\n  it('rejects non-HTTPS schemes', async () => {\n    await expect(validateAndFetchUrl('http://example.com/x.png')).rejects.toThrow(/HTTPS/)\n  })\n\n  it('rejects when DNS resolves to a private IPv4 (SSRF)', async () => {\n    mockDns('10.0.0.5')\n    await expect(validateAndFetchUrl('https://attacker.example/x.png')).rejects.toThrow(\n      /SSRF blocked/,\n    )\n  })\n\n  it('rejects when DNS resolves to AWS metadata IP (SSRF)', async () => {\n    mockDns('169.254.169.254')\n    await expect(validateAndFetchUrl('https://metadata.example/x.png')).rejects.toThrow(\n      /SSRF blocked/,\n    )\n  })\n\n  it('rejects when DNS resolves to ::1 (SSRF)', async () => {\n    mockDns('::1', 6)\n    await expect(validateAndFetchUrl('https://localhost.example/x.png')).rejects.toThrow(\n      /SSRF blocked/,\n    )\n  })\n\n  it('fetches successfully when DNS resolves to a public IP', async () => {\n    mockDns('8.8.8.8')\n    mockFetch(\n      () =>\n        new Response(new Uint8Array([1, 2, 3]), {\n          status: 200,\n          headers: { 'content-type': 'image/png' },\n        }),\n    )\n\n    const result = await validateAndFetchUrl('https://example.com/cat.png')\n    expect(result.contentType).toBe('image/png')\n    expect(result.filename).toBe('cat.png')\n    expect(result.buffer.length).toBe(3)\n  })\n\n  it('follows redirects and re-validates the redirect target', async () => {\n    let call = 0\n    // First lookup: public. Second lookup (after redirect): private → must block.\n    dnsLookupSpy.mockImplementation(async () => {\n      call++\n      return { address: call === 1 ? '8.8.8.8' : '127.0.0.1', family: 4 } as any\n    })\n\n    mockFetch((url) => {\n      if (url === 'https://example.com/start') {\n        return new Response(null, {\n          status: 302,\n          headers: { location: 'https://internal.example/secret' },\n        })\n      }\n      throw new Error(`should not reach ${url} — redirect target must be blocked`)\n    })\n\n    await expect(validateAndFetchUrl('https://example.com/start')).rejects.toThrow(\n      /SSRF blocked/,\n    )\n    expect(call).toBe(2)\n  })\n\n  it('caps redirect chains at maxRedirects', async () => {\n    mockDns('8.8.8.8')\n    mockFetch(\n      (url) =>\n        new Response(null, {\n          status: 302,\n          headers: { location: url + '/again' },\n        }),\n    )\n\n    await expect(\n      validateAndFetchUrl('https://example.com/loop', { maxRedirects: 2 }),\n    ).rejects.toThrow(/Too many redirects/)\n  })\n\n  it('errors when a redirect response has no Location header', async () => {\n    mockDns('8.8.8.8')\n    mockFetch(() => new Response(null, { status: 302 }))\n\n    await expect(validateAndFetchUrl('https://example.com/x.png')).rejects.toThrow(\n      /Location header/,\n    )\n  })\n\n  it('surfaces non-OK HTTP responses', async () => {\n    mockDns('8.8.8.8')\n    mockFetch(() => new Response(null, { status: 404, statusText: 'Not Found' }))\n\n    await expect(validateAndFetchUrl('https://example.com/x.png')).rejects.toThrow(/404/)\n  })\n\n  it('derives a UUID filename when the URL path has no extension', async () => {\n    mockDns('8.8.8.8')\n    mockFetch(\n      () =>\n        new Response(new Uint8Array([0]), {\n          status: 200,\n          headers: { 'content-type': 'image/jpeg' },\n        }),\n    )\n\n    const result = await validateAndFetchUrl('https://example.com/no-extension')\n    expect(result.filename).toMatch(/\\.jpg$/)\n    expect(result.filename).not.toBe('no-extension')\n  })\n\n  it('strips path traversal segments from derived filenames', async () => {\n    mockDns('8.8.8.8')\n    mockFetch(\n      () =>\n        new Response(new Uint8Array([0]), {\n          status: 200,\n          headers: { 'content-type': 'image/png' },\n        }),\n    )\n\n    const result = await validateAndFetchUrl('https://example.com/foo/..%2Fevil.png')\n    // URL parser decodes %2F into /, so lastSegment ends up \"..evil.png\" after .. strip\n    expect(result.filename).not.toContain('..')\n    expect(result.filename).not.toContain('/')\n    expect(result.filename).not.toContain('\\\\')\n  })\n})\n"],"names":["describe","it","expect","vi","beforeEach","afterEach","dns","isPrivateIp","validateAndFetchUrl","each","ip","toBe","originalFetch","globalThis","fetch","dnsLookupSpy","spyOn","promises","restoreAllMocks","mockDns","address","family","mockResolvedValue","mockFetch","impl","fn","url","Promise","resolve","String","rejects","toThrow","Response","Uint8Array","status","headers","result","contentType","filename","buffer","length","call","mockImplementation","location","Error","maxRedirects","statusText","toMatch","not","toContain"],"mappings":"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"}

package/dist/draft-workflow.d.ts

@@ -0,0 +1,60 @@
+import type { CollectionConfig, PayloadRequest } from 'payload';
+import type { DraftBehavior } from './types';
+/** MCP response shape used by overrideResponse */
+interface McpResponse {
+    content: Array<{
+        text: string;
+        type: string;
+    }>;
+}
+/** Per-collection MCP config with enabled operations and optional overrideResponse */
+interface McpCollectionConfig {
+    description: string;
+    enabled: {
+        create: boolean;
+        delete: boolean;
+        find: boolean;
+        update: boolean;
+    };
+    overrideResponse?: (response: McpResponse, doc: Record<string, unknown>, req: PayloadRequest) => McpResponse;
+}
+interface GenerateOptions {
+    /** Base site URL for preview links */
+    siteUrl: string;
+    /** Preview authentication secret */
+    previewSecret: string;
+    /**
+     * Per-collection URL path prefix used when constructing preview URLs.
+     * Defaults to `/{slug}` for collections not in the map.
+     */
+    previewPaths?: Record<string, string>;
+    /** Per-collection draft behavior overrides */
+    draftBehavior?: Record<string, DraftBehavior>;
+    /** Collection slugs to exclude from MCP */
+    excludeCollections?: string[];
+}
+/**
+ * Determines the draft behavior for a collection based on its config and user overrides.
+ *
+ * - If the collection has no `versions.drafts`: always 'publish' regardless of override
+ * - If the user specified an override: use that override
+ * - Default: 'always-draft' for draft-enabled collections, 'publish' for others
+ */
+export declare function getDraftBehavior(collection: CollectionConfig, options?: {
+    draftBehavior?: Record<string, DraftBehavior>;
+}): 'always-draft' | 'always-publish' | 'publish';
+/**
+ * Generates the mcpCollections config object for the official mcpPlugin.
+ *
+ * For each collection:
+ * - Determines enabled CRUD operations based on draft behavior
+ * - For 'always-draft' collections: disables raw `update` to force clients through publishDraft tool
+ * - Generates `overrideResponse` that appends preview URLs for draft documents
+ *
+ * @returns A record of collection slug to MCP collection config, plus the set of draft collection slugs
+ */
+export declare function generateMcpCollectionConfigs(collections: CollectionConfig[], options: GenerateOptions): {
+    mcpCollections: Record<string, McpCollectionConfig>;
+    draftCollections: Set<string>;
+};
+export {};

package/dist/draft-workflow.js

@@ -0,0 +1,93 @@
+/**
+ * Determines the draft behavior for a collection based on its config and user overrides.
+ *
+ * - If the collection has no `versions.drafts`: always 'publish' regardless of override
+ * - If the user specified an override: use that override
+ * - Default: 'always-draft' for draft-enabled collections, 'publish' for others
+ */ export function getDraftBehavior(collection, options) {
+    const hasDrafts = typeof collection.versions === 'object' && collection.versions !== null && 'drafts' in collection.versions && Boolean(collection.versions.drafts);
+    if (!hasDrafts) return 'publish';
+    const override = options?.draftBehavior?.[collection.slug];
+    if (override) return override;
+    return 'always-draft';
+}
+/**
+ * Builds a preview URL for a draft document.
+ *
+ * Path is `${siteUrl}/next/preview?...`. Path prefix per collection comes
+ * from `previewPaths`, defaulting to `/{collectionSlug}` when not configured.
+ */ function buildPreviewUrl(doc, collectionSlug, siteUrl, previewSecret, previewPaths) {
+    const slug = doc.slug || '';
+    const prefix = previewPaths?.[collectionSlug] ?? `/${collectionSlug}`;
+    const path = `${prefix}/${slug}`;
+    const params = new URLSearchParams({
+        slug,
+        collection: collectionSlug,
+        path,
+        previewSecret
+    });
+    return `${siteUrl}/next/preview?${params.toString()}`;
+}
+/**
+ * Creates an overrideResponse function for a draft-enabled collection.
+ * When a document has `_status === 'draft'`, appends a preview URL to the response.
+ */ function createOverrideResponse(collectionSlug, siteUrl, previewSecret, previewPaths) {
+    return (response, doc)=>{
+        if (doc._status !== 'draft') return response;
+        const previewUrl = buildPreviewUrl(doc, collectionSlug, siteUrl, previewSecret, previewPaths);
+        return {
+            content: [
+                ...response.content,
+                {
+                    type: 'text',
+                    text: `\n📋 This document is a draft. Preview it here: ${previewUrl}`
+                }
+            ]
+        };
+    };
+}
+/**
+ * Generates the mcpCollections config object for the official mcpPlugin.
+ *
+ * For each collection:
+ * - Determines enabled CRUD operations based on draft behavior
+ * - For 'always-draft' collections: disables raw `update` to force clients through publishDraft tool
+ * - Generates `overrideResponse` that appends preview URLs for draft documents
+ *
+ * @returns A record of collection slug to MCP collection config, plus the set of draft collection slugs
+ */ export function generateMcpCollectionConfigs(collections, options) {
+    const mcpCollections = {};
+    const draftCollections = new Set();
+    const excludeSlugs = new Set([
+        'users',
+        'payload-mcp-api-keys',
+        ...options.excludeCollections ?? []
+    ]);
+    for (const collection of collections){
+        if (excludeSlugs.has(collection.slug)) continue;
+        const behavior = getDraftBehavior(collection, options);
+        if (behavior !== 'publish') {
+            draftCollections.add(collection.slug);
+        }
+        const enabled = {
+            find: true,
+            create: true,
+            update: behavior !== 'always-draft',
+            delete: true
+        };
+        const config = {
+            description: `Manage ${collection.slug} content`,
+            enabled
+        };
+        if (draftCollections.has(collection.slug)) {
+            config.overrideResponse = createOverrideResponse(collection.slug, options.siteUrl, options.previewSecret, options.previewPaths);
+        }
+        mcpCollections[collection.slug] = config;
+    }
+    return {
+        mcpCollections,
+        draftCollections
+    };
+}
+
+//# sourceMappingURL=draft-workflow.js.map

package/dist/draft-workflow.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/draft-workflow.ts"],"sourcesContent":["import type { CollectionConfig, PayloadRequest } from 'payload'\nimport type { DraftBehavior } from './types'\n\n/** MCP response shape used by overrideResponse */\ninterface McpResponse {\n  content: Array<{ text: string; type: string }>\n}\n\n/** Per-collection MCP config with enabled operations and optional overrideResponse */\ninterface McpCollectionConfig {\n  description: string\n  enabled: {\n    create: boolean\n    delete: boolean\n    find: boolean\n    update: boolean\n  }\n  overrideResponse?: (\n    response: McpResponse,\n    doc: Record<string, unknown>,\n    req: PayloadRequest,\n  ) => McpResponse\n}\n\ninterface GenerateOptions {\n  /** Base site URL for preview links */\n  siteUrl: string\n  /** Preview authentication secret */\n  previewSecret: string\n  /**\n   * Per-collection URL path prefix used when constructing preview URLs.\n   * Defaults to `/{slug}` for collections not in the map.\n   */\n  previewPaths?: Record<string, string>\n  /** Per-collection draft behavior overrides */\n  draftBehavior?: Record<string, DraftBehavior>\n  /** Collection slugs to exclude from MCP */\n  excludeCollections?: string[]\n}\n\n/**\n * Determines the draft behavior for a collection based on its config and user overrides.\n *\n * - If the collection has no `versions.drafts`: always 'publish' regardless of override\n * - If the user specified an override: use that override\n * - Default: 'always-draft' for draft-enabled collections, 'publish' for others\n */\nexport function getDraftBehavior(\n  collection: CollectionConfig,\n  options?: { draftBehavior?: Record<string, DraftBehavior> },\n): 'always-draft' | 'always-publish' | 'publish' {\n  const hasDrafts =\n    typeof collection.versions === 'object' &&\n    collection.versions !== null &&\n    'drafts' in collection.versions &&\n    Boolean(collection.versions.drafts)\n\n  if (!hasDrafts) return 'publish'\n\n  const override = options?.draftBehavior?.[collection.slug]\n  if (override) return override\n\n  return 'always-draft'\n}\n\n/**\n * Builds a preview URL for a draft document.\n *\n * Path is `${siteUrl}/next/preview?...`. Path prefix per collection comes\n * from `previewPaths`, defaulting to `/{collectionSlug}` when not configured.\n */\nfunction buildPreviewUrl(\n  doc: Record<string, unknown>,\n  collectionSlug: string,\n  siteUrl: string,\n  previewSecret: string,\n  previewPaths?: Record<string, string>,\n): string {\n  const slug = (doc.slug as string) || ''\n  const prefix = previewPaths?.[collectionSlug] ?? `/${collectionSlug}`\n  const path = `${prefix}/${slug}`\n\n  const params = new URLSearchParams({\n    slug,\n    collection: collectionSlug,\n    path,\n    previewSecret,\n  })\n\n  return `${siteUrl}/next/preview?${params.toString()}`\n}\n\n/**\n * Creates an overrideResponse function for a draft-enabled collection.\n * When a document has `_status === 'draft'`, appends a preview URL to the response.\n */\nfunction createOverrideResponse(\n  collectionSlug: string,\n  siteUrl: string,\n  previewSecret: string,\n  previewPaths?: Record<string, string>,\n): McpCollectionConfig['overrideResponse'] {\n  return (response: McpResponse, doc: Record<string, unknown>): McpResponse => {\n    if (doc._status !== 'draft') return response\n\n    const previewUrl = buildPreviewUrl(doc, collectionSlug, siteUrl, previewSecret, previewPaths)\n\n    return {\n      content: [\n        ...response.content,\n        {\n          type: 'text',\n          text: `\\n📋 This document is a draft. Preview it here: ${previewUrl}`,\n        },\n      ],\n    }\n  }\n}\n\n/**\n * Generates the mcpCollections config object for the official mcpPlugin.\n *\n * For each collection:\n * - Determines enabled CRUD operations based on draft behavior\n * - For 'always-draft' collections: disables raw `update` to force clients through publishDraft tool\n * - Generates `overrideResponse` that appends preview URLs for draft documents\n *\n * @returns A record of collection slug to MCP collection config, plus the set of draft collection slugs\n */\nexport function generateMcpCollectionConfigs(\n  collections: CollectionConfig[],\n  options: GenerateOptions,\n): {\n  mcpCollections: Record<string, McpCollectionConfig>\n  draftCollections: Set<string>\n} {\n  const mcpCollections: Record<string, McpCollectionConfig> = {}\n  const draftCollections = new Set<string>()\n\n  const excludeSlugs = new Set([\n    'users',\n    'payload-mcp-api-keys',\n    ...(options.excludeCollections ?? []),\n  ])\n\n  for (const collection of collections) {\n    if (excludeSlugs.has(collection.slug)) continue\n\n    const behavior = getDraftBehavior(collection, options)\n\n    if (behavior !== 'publish') {\n      draftCollections.add(collection.slug)\n    }\n\n    const enabled = {\n      find: true,\n      create: true,\n      update: behavior !== 'always-draft',\n      delete: true,\n    }\n\n    const config: McpCollectionConfig = {\n      description: `Manage ${collection.slug} content`,\n      enabled,\n    }\n\n    if (draftCollections.has(collection.slug)) {\n      config.overrideResponse = createOverrideResponse(\n        collection.slug,\n        options.siteUrl,\n        options.previewSecret,\n        options.previewPaths,\n      )\n    }\n\n    mcpCollections[collection.slug] = config\n  }\n\n  return { mcpCollections, draftCollections }\n}\n"],"names":["getDraftBehavior","collection","options","hasDrafts","versions","Boolean","drafts","override","draftBehavior","slug","buildPreviewUrl","doc","collectionSlug","siteUrl","previewSecret","previewPaths","prefix","path","params","URLSearchParams","toString","createOverrideResponse","response","_status","previewUrl","content","type","text","generateMcpCollectionConfigs","collections","mcpCollections","draftCollections","Set","excludeSlugs","excludeCollections","has","behavior","add","enabled","find","create","update","delete","config","description","overrideResponse"],"mappings":"AAwCA;;;;;;CAMC,GACD,OAAO,SAASA,iBACdC,UAA4B,EAC5BC,OAA2D;IAE3D,MAAMC,YACJ,OAAOF,WAAWG,QAAQ,KAAK,YAC/BH,WAAWG,QAAQ,KAAK,QACxB,YAAYH,WAAWG,QAAQ,IAC/BC,QAAQJ,WAAWG,QAAQ,CAACE,MAAM;IAEpC,IAAI,CAACH,WAAW,OAAO;IAEvB,MAAMI,WAAWL,SAASM,eAAe,CAACP,WAAWQ,IAAI,CAAC;IAC1D,IAAIF,UAAU,OAAOA;IAErB,OAAO;AACT;AAEA;;;;;CAKC,GACD,SAASG,gBACPC,GAA4B,EAC5BC,cAAsB,EACtBC,OAAe,EACfC,aAAqB,EACrBC,YAAqC;IAErC,MAAMN,OAAO,AAACE,IAAIF,IAAI,IAAe;IACrC,MAAMO,SAASD,cAAc,CAACH,eAAe,IAAI,CAAC,CAAC,EAAEA,gBAAgB;IACrE,MAAMK,OAAO,GAAGD,OAAO,CAAC,EAAEP,MAAM;IAEhC,MAAMS,SAAS,IAAIC,gBAAgB;QACjCV;QACAR,YAAYW;QACZK;QACAH;IACF;IAEA,OAAO,GAAGD,QAAQ,cAAc,EAAEK,OAAOE,QAAQ,IAAI;AACvD;AAEA;;;CAGC,GACD,SAASC,uBACPT,cAAsB,EACtBC,OAAe,EACfC,aAAqB,EACrBC,YAAqC;IAErC,OAAO,CAACO,UAAuBX;QAC7B,IAAIA,IAAIY,OAAO,KAAK,SAAS,OAAOD;QAEpC,MAAME,aAAad,gBAAgBC,KAAKC,gBAAgBC,SAASC,eAAeC;QAEhF,OAAO;YACLU,SAAS;mBACJH,SAASG,OAAO;gBACnB;oBACEC,MAAM;oBACNC,MAAM,CAAC,gDAAgD,EAAEH,YAAY;gBACvE;aACD;QACH;IACF;AACF;AAEA;;;;;;;;;CASC,GACD,OAAO,SAASI,6BACdC,WAA+B,EAC/B3B,OAAwB;IAKxB,MAAM4B,iBAAsD,CAAC;IAC7D,MAAMC,mBAAmB,IAAIC;IAE7B,MAAMC,eAAe,IAAID,IAAI;QAC3B;QACA;WACI9B,QAAQgC,kBAAkB,IAAI,EAAE;KACrC;IAED,KAAK,MAAMjC,cAAc4B,YAAa;QACpC,IAAII,aAAaE,GAAG,CAAClC,WAAWQ,IAAI,GAAG;QAEvC,MAAM2B,WAAWpC,iBAAiBC,YAAYC;QAE9C,IAAIkC,aAAa,WAAW;YAC1BL,iBAAiBM,GAAG,CAACpC,WAAWQ,IAAI;QACtC;QAEA,MAAM6B,UAAU;YACdC,MAAM;YACNC,QAAQ;YACRC,QAAQL,aAAa;YACrBM,QAAQ;QACV;QAEA,MAAMC,SAA8B;YAClCC,aAAa,CAAC,OAAO,EAAE3C,WAAWQ,IAAI,CAAC,QAAQ,CAAC;YAChD6B;QACF;QAEA,IAAIP,iBAAiBI,GAAG,CAAClC,WAAWQ,IAAI,GAAG;YACzCkC,OAAOE,gBAAgB,GAAGxB,uBACxBpB,WAAWQ,IAAI,EACfP,QAAQW,OAAO,EACfX,QAAQY,aAAa,EACrBZ,QAAQa,YAAY;QAExB;QAEAe,cAAc,CAAC7B,WAAWQ,IAAI,CAAC,GAAGkC;IACpC;IAEA,OAAO;QAAEb;QAAgBC;IAAiB;AAC5C"}

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+import type { Plugin } from 'payload';
+import type { ContentToolkitOptions } from './types';
+/**
+ * Payload MCP Toolkit
+ *
+ * A wrapper plugin that introspects the Payload config and generates
+ * domain-aware MCP tools, prompts, and resources for AI content management.
+ *
+ * Usage in payload.config.ts:
+ * ```ts
+ * import { contentToolkitPlugin } from 'payload-mcp-toolkit'
+ *
+ * plugins: [
+ *   contentToolkitPlugin({
+ *     siteUrl: process.env.SITE_URL!,
+ *     previewSecret: process.env.PREVIEW_SECRET!,
+ *     previewPaths: { posts: '/blog', pages: '' },
+ *     draftBehavior: { pages: 'always-draft' },
+ *   }),
+ * ]
+ * ```
+ */
+export declare function contentToolkitPlugin(options: ContentToolkitOptions): Plugin;
+export type { ContentToolkitOptions, DomainPrompt, DraftBehavior, CollectionSchema, BlockCatalog, SectionBlockSchema, LeafBlockSchema, RelationshipEdge, FieldSchema, } from './types';