payload-mcp-toolkit 0.2.0

package/dist/types.d.ts

@@ -0,0 +1,118 @@
+/** Draft behavior per collection */
+export type DraftBehavior = 'always-draft' | 'always-publish';
+/** Configuration for the content toolkit plugin */
+export interface ContentToolkitOptions {
+    /** Base URL of the site (used for preview URLs). e.g. "https://example.com" */
+    siteUrl: string;
+    /** Secret used for preview URL authentication */
+    previewSecret: string;
+    /**
+     * Per-collection URL path prefix used when constructing preview URLs.
+     * Keys are collection slugs; values are the path segment placed before the doc slug.
+     * Use an empty string for collections that live at the site root (e.g. pages).
+     *
+     * Example:
+     *   {
+     *     posts: '/blog',
+     *     products: '/shop',
+     *     pages: '',
+     *   }
+     *
+     * Collections without an entry default to `/{slug}`.
+     */
+    previewPaths?: Record<string, string>;
+    /**
+     * Explicit list of block slugs that should be treated as **section** blocks
+     * (top-level layout containers). Any block not in this list is treated as
+     * a **leaf** block (composable inside a section's `blocks` field).
+     *
+     * When omitted, the toolkit falls back to a heuristic: blocks that contain
+     * a nested `blocks`-type field are sections, all others are leaves. This
+     * heuristic mis-classifies "fixed" sections (sections with no nested blocks
+     * but their own standalone fields, e.g. a CTA banner). Pass this option
+     * to disambiguate.
+     *
+     * Example: `['hero', 'fullWidth', 'twoColumn', 'ctaBanner']`
+     */
+    sectionBlockSlugs?: string[];
+    /** Site-specific domain prompts that teach the AI business vocabulary */
+    domainPrompts?: DomainPrompt[];
+    /** Per-collection draft behavior overrides (keyed by collection slug) */
+    draftBehavior?: Record<string, DraftBehavior>;
+    /** Media upload configuration */
+    mediaUpload?: {
+        /** Maximum file size in bytes (default: 10MB) */
+        maxFileSize?: number;
+        /** Media collection slug (default: 'media') */
+        collectionSlug?: string;
+    };
+    /** Collections to exclude from MCP exposure */
+    excludeCollections?: string[];
+    /** Globals to exclude from MCP exposure */
+    excludeGlobals?: string[];
+}
+/** A domain prompt that teaches the AI site-specific vocabulary */
+export interface DomainPrompt {
+    /** Unique name for the prompt */
+    name: string;
+    /** Display title */
+    title: string;
+    /** Description of what this prompt teaches */
+    description: string;
+    /** The prompt content */
+    content: string;
+}
+/** Introspected field metadata */
+export interface FieldSchema {
+    name: string;
+    type: string;
+    required?: boolean;
+    hasMany?: boolean;
+    relationTo?: string | string[];
+    options?: Array<{
+        label: string;
+        value: string;
+    }>;
+    fields?: FieldSchema[];
+    maxRows?: number;
+}
+/** Introspected collection metadata */
+export interface CollectionSchema {
+    slug: string;
+    fields: FieldSchema[];
+    hasDrafts: boolean;
+    hasLivePreview: boolean;
+    relationships: Array<{
+        fieldName: string;
+        relationTo: string | string[];
+        hasMany: boolean;
+    }>;
+    searchableFields: string[];
+}
+/** Block nesting classification */
+export type BlockNestingType = 'composable' | 'constrained' | 'fixed';
+/** Introspected section block metadata */
+export interface SectionBlockSchema {
+    slug: string;
+    nestingType: BlockNestingType;
+    acceptedLeafSlugs: string[];
+    maxRows?: number;
+    fields: FieldSchema[];
+}
+/** Introspected leaf block metadata */
+export interface LeafBlockSchema {
+    slug: string;
+    fields: FieldSchema[];
+}
+/** Complete block catalog */
+export interface BlockCatalog {
+    sections: SectionBlockSchema[];
+    leaves: LeafBlockSchema[];
+}
+/** Relationship edge in the collection graph */
+export interface RelationshipEdge {
+    fromCollection: string;
+    fieldName: string;
+    toCollection: string | string[];
+    hasMany: boolean;
+}

package/dist/types.js

@@ -0,0 +1,3 @@
+/** Relationship edge in the collection graph */ export { };
+
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts"],"sourcesContent":["import type { CollectionConfig, Block, Config, GlobalConfig } from 'payload'\n\n/** Draft behavior per collection */\nexport type DraftBehavior = 'always-draft' | 'always-publish'\n\n/** Configuration for the content toolkit plugin */\nexport interface ContentToolkitOptions {\n  /** Base URL of the site (used for preview URLs). e.g. \"https://example.com\" */\n  siteUrl: string\n\n  /** Secret used for preview URL authentication */\n  previewSecret: string\n\n  /**\n   * Per-collection URL path prefix used when constructing preview URLs.\n   * Keys are collection slugs; values are the path segment placed before the doc slug.\n   * Use an empty string for collections that live at the site root (e.g. pages).\n   *\n   * Example:\n   *   {\n   *     posts: '/blog',\n   *     products: '/shop',\n   *     pages: '',\n   *   }\n   *\n   * Collections without an entry default to `/{slug}`.\n   */\n  previewPaths?: Record<string, string>\n\n  /**\n   * Explicit list of block slugs that should be treated as **section** blocks\n   * (top-level layout containers). Any block not in this list is treated as\n   * a **leaf** block (composable inside a section's `blocks` field).\n   *\n   * When omitted, the toolkit falls back to a heuristic: blocks that contain\n   * a nested `blocks`-type field are sections, all others are leaves. This\n   * heuristic mis-classifies \"fixed\" sections (sections with no nested blocks\n   * but their own standalone fields, e.g. a CTA banner). Pass this option\n   * to disambiguate.\n   *\n   * Example: `['hero', 'fullWidth', 'twoColumn', 'ctaBanner']`\n   */\n  sectionBlockSlugs?: string[]\n\n  /** Site-specific domain prompts that teach the AI business vocabulary */\n  domainPrompts?: DomainPrompt[]\n\n  /** Per-collection draft behavior overrides (keyed by collection slug) */\n  draftBehavior?: Record<string, DraftBehavior>\n\n  /** Media upload configuration */\n  mediaUpload?: {\n    /** Maximum file size in bytes (default: 10MB) */\n    maxFileSize?: number\n    /** Media collection slug (default: 'media') */\n    collectionSlug?: string\n  }\n\n  /** Collections to exclude from MCP exposure */\n  excludeCollections?: string[]\n\n  /** Globals to exclude from MCP exposure */\n  excludeGlobals?: string[]\n}\n\n/** A domain prompt that teaches the AI site-specific vocabulary */\nexport interface DomainPrompt {\n  /** Unique name for the prompt */\n  name: string\n  /** Display title */\n  title: string\n  /** Description of what this prompt teaches */\n  description: string\n  /** The prompt content */\n  content: string\n}\n\n/** Introspected field metadata */\nexport interface FieldSchema {\n  name: string\n  type: string\n  required?: boolean\n  hasMany?: boolean\n  relationTo?: string | string[]\n  options?: Array<{ label: string; value: string }>\n  fields?: FieldSchema[]\n  maxRows?: number\n}\n\n/** Introspected collection metadata */\nexport interface CollectionSchema {\n  slug: string\n  fields: FieldSchema[]\n  hasDrafts: boolean\n  hasLivePreview: boolean\n  relationships: Array<{ fieldName: string; relationTo: string | string[]; hasMany: boolean }>\n  searchableFields: string[]\n}\n\n/** Block nesting classification */\nexport type BlockNestingType = 'composable' | 'constrained' | 'fixed'\n\n/** Introspected section block metadata */\nexport interface SectionBlockSchema {\n  slug: string\n  nestingType: BlockNestingType\n  acceptedLeafSlugs: string[]\n  maxRows?: number\n  fields: FieldSchema[]\n}\n\n/** Introspected leaf block metadata */\nexport interface LeafBlockSchema {\n  slug: string\n  fields: FieldSchema[]\n}\n\n/** Complete block catalog */\nexport interface BlockCatalog {\n  sections: SectionBlockSchema[]\n  leaves: LeafBlockSchema[]\n}\n\n/** Relationship edge in the collection graph */\nexport interface RelationshipEdge {\n  fromCollection: string\n  fieldName: string\n  toCollection: string | string[]\n  hasMany: boolean\n}\n"],"names":[],"mappings":"AA2HA,8CAA8C,GAC9C,WAKC"}

package/dist/url-validator.d.ts

@@ -0,0 +1,36 @@
+import { Buffer } from 'node:buffer';
+interface ValidatedFetchResult {
+    buffer: Buffer;
+    contentType: string;
+    filename: string;
+}
+/**
+ * Check whether an IP address falls within a private/reserved range.
+ *
+ * Blocks (IPv4): 0.0.0.0/8, 10.0.0.0/8, 100.64.0.0/10 (CGNAT),
+ * 127.0.0.0/8, 169.254.0.0/16 (link-local + AWS metadata),
+ * 172.16.0.0/12, 192.168.0.0/16.
+ *
+ * Blocks (IPv6): ::1 (loopback, in any expanded form), fc00::/7
+ * (unique local), fe80::/10 (link-local), and any IPv4-mapped or
+ * IPv4-compatible address whose embedded IPv4 falls in a blocked range.
+ */
+export declare function isPrivateIp(ip: string): boolean;
+/**
+ * Validate a URL for SSRF safety and fetch its contents.
+ *
+ * - HTTPS-only scheme validation
+ * - DNS resolution pre-check to block private/reserved IPs
+ * - Manual redirect following with IP re-validation at each hop
+ * - 10-second timeout
+ *
+ * NOTE: Small TOCTOU gap between DNS resolution and the actual TCP
+ * connection (DNS rebinding). A future improvement could use a custom
+ * http.Agent with a `lookup` override to validate IPs at connection time.
+ */
+export declare function validateAndFetchUrl(url: string, options?: {
+    maxRedirects?: number;
+    timeoutMs?: number;
+    maxBytes?: number;
+}): Promise<ValidatedFetchResult>;
+export {};

package/dist/url-validator.js

@@ -0,0 +1,222 @@
+import dns from 'node:dns';
+import { Buffer } from 'node:buffer';
+const MAX_REDIRECTS = 3;
+const FETCH_TIMEOUT_MS = 10_000;
+const DEFAULT_MAX_BYTES = 50 * 1024 * 1024 // 50MB hard ceiling — caller may pass a tighter cap.
+;
+/**
+ * Check whether an IP address falls within a private/reserved range.
+ *
+ * Blocks (IPv4): 0.0.0.0/8, 10.0.0.0/8, 100.64.0.0/10 (CGNAT),
+ * 127.0.0.0/8, 169.254.0.0/16 (link-local + AWS metadata),
+ * 172.16.0.0/12, 192.168.0.0/16.
+ *
+ * Blocks (IPv6): ::1 (loopback, in any expanded form), fc00::/7
+ * (unique local), fe80::/10 (link-local), and any IPv4-mapped or
+ * IPv4-compatible address whose embedded IPv4 falls in a blocked range.
+ */ export function isPrivateIp(ip) {
+    if (ip.includes(':')) return isPrivateIpV6(ip);
+    return isPrivateIpV4(ip);
+}
+function isPrivateIpV4(ip) {
+    const parts = ip.split('.');
+    if (parts.length !== 4) return false;
+    const [a, b] = parts.map(Number);
+    if (parts.some((p)=>Number.isNaN(Number(p)))) return false;
+    if (a === 0) return true // 0.0.0.0/8
+    ;
+    if (a === 10) return true // 10.0.0.0/8
+    ;
+    if (a === 100 && b >= 64 && b <= 127) return true // 100.64.0.0/10 — CGNAT
+    ;
+    if (a === 127) return true // 127.0.0.0/8
+    ;
+    if (a === 169 && b === 254) return true // 169.254.0.0/16
+    ;
+    if (a === 172 && b >= 16 && b <= 31) return true // 172.16.0.0/12
+    ;
+    if (a === 192 && b === 168) return true // 192.168.0.0/16
+    ;
+    return false;
+}
+function isPrivateIpV6(ip) {
+    const normalized = ip.toLowerCase();
+    // IPv4-mapped (::ffff:1.2.3.4) and IPv4-compatible (::1.2.3.4) — extract
+    // the embedded v4 and run the v4 checks against it.
+    const mappedMatch = normalized.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+    if (mappedMatch) return isPrivateIpV4(mappedMatch[1]);
+    const compatMatch = normalized.match(/^::(\d+\.\d+\.\d+\.\d+)$/);
+    if (compatMatch) return isPrivateIpV4(compatMatch[1]);
+    // Expand to full 8-group form so loopback/link-local checks aren't
+    // defeated by alternate notations (`0:0:0:0:0:0:0:1`, `0000:...:0001`).
+    const groups = expandIpV6(normalized);
+    if (!groups) return false;
+    // Loopback ::1
+    if (groups.every((g, i)=>i < 7 ? g === 0 : g === 1)) return true;
+    const first = groups[0];
+    // fc00::/7 — unique local (fc00–fdff)
+    if ((first & 0xfe00) === 0xfc00) return true;
+    // fe80::/10 — link-local
+    if ((first & 0xffc0) === 0xfe80) return true;
+    return false;
+}
+/**
+ * Expand a textual IPv6 address into 8 numeric groups. Returns null if
+ * the address isn't a recognisable v6 string (we err toward "not private"
+ * for unparseable input — DNS already gave us a real address, this guards
+ * notation variance, not malicious DNS payloads).
+ */ function expandIpV6(ip) {
+    if (ip.includes('.')) return null // mapped/compat handled above
+    ;
+    const halves = ip.split('::');
+    if (halves.length > 2) return null;
+    const parse = (segment)=>{
+        if (segment === '') return [];
+        const out = [];
+        for (const piece of segment.split(':')){
+            if (!/^[0-9a-f]{1,4}$/.test(piece)) return null;
+            out.push(parseInt(piece, 16));
+        }
+        return out;
+    };
+    if (halves.length === 1) {
+        const parts = parse(ip);
+        return parts && parts.length === 8 ? parts : null;
+    }
+    const head = parse(halves[0]);
+    const tail = parse(halves[1]);
+    if (!head || !tail) return null;
+    const fillCount = 8 - head.length - tail.length;
+    if (fillCount < 0) return null;
+    return [
+        ...head,
+        ...new Array(fillCount).fill(0),
+        ...tail
+    ];
+}
+/**
+ * Validate a URL for SSRF safety and fetch its contents.
+ *
+ * - HTTPS-only scheme validation
+ * - DNS resolution pre-check to block private/reserved IPs
+ * - Manual redirect following with IP re-validation at each hop
+ * - 10-second timeout
+ *
+ * NOTE: Small TOCTOU gap between DNS resolution and the actual TCP
+ * connection (DNS rebinding). A future improvement could use a custom
+ * http.Agent with a `lookup` override to validate IPs at connection time.
+ */ export async function validateAndFetchUrl(url, options) {
+    const maxRedirects = options?.maxRedirects ?? MAX_REDIRECTS;
+    const timeoutMs = options?.timeoutMs ?? FETCH_TIMEOUT_MS;
+    const maxBytes = options?.maxBytes ?? DEFAULT_MAX_BYTES;
+    let currentUrl = url;
+    let redirectCount = 0;
+    while(true){
+        const parsed = new URL(currentUrl);
+        if (parsed.protocol !== 'https:') {
+            throw new Error(`Only HTTPS URLs are allowed. Received: ${parsed.protocol}`);
+        }
+        const hostname = parsed.hostname;
+        const { address } = await dns.promises.lookup(hostname);
+        if (isPrivateIp(address)) {
+            throw new Error(`SSRF blocked: hostname "${hostname}" resolves to private IP ${address}. ` + 'Only public internet addresses are allowed.');
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(()=>controller.abort(), timeoutMs);
+        let response;
+        try {
+            response = await fetch(currentUrl, {
+                redirect: 'manual',
+                signal: controller.signal,
+                headers: {
+                    'User-Agent': 'payload-mcp-toolkit/0.1'
+                }
+            });
+        } catch (error) {
+            clearTimeout(timer);
+            if (error instanceof DOMException && error.name === 'AbortError') {
+                throw new Error(`Request timed out after ${timeoutMs}ms fetching ${currentUrl}`);
+            }
+            throw error;
+        } finally{
+            clearTimeout(timer);
+        }
+        if (response.status >= 300 && response.status < 400) {
+            const location = response.headers.get('location');
+            if (!location) {
+                throw new Error(`Redirect response (${response.status}) missing Location header.`);
+            }
+            redirectCount++;
+            if (redirectCount > maxRedirects) {
+                throw new Error(`Too many redirects (max ${maxRedirects}). Last URL: ${currentUrl}`);
+            }
+            currentUrl = new URL(location, currentUrl).href;
+            continue;
+        }
+        if (!response.ok) {
+            throw new Error(`Failed to fetch ${currentUrl}: HTTP ${response.status} ${response.statusText}`);
+        }
+        const contentType = response.headers.get('content-type')?.split(';')[0]?.trim() ?? '';
+        // Reject early if the server advertises a body larger than maxBytes.
+        const declaredLength = response.headers.get('content-length');
+        if (declaredLength !== null) {
+            const length = Number(declaredLength);
+            if (Number.isFinite(length) && length > maxBytes) {
+                throw new Error(`Response body exceeds ${maxBytes} bytes (Content-Length: ${length}).`);
+            }
+        }
+        // Stream the body, enforcing the cap as we go so a server that lies
+        // (or omits) Content-Length cannot exhaust memory.
+        const buffer = await readBodyWithLimit(response, maxBytes, currentUrl);
+        const filename = deriveFilename(parsed.pathname, contentType);
+        return {
+            buffer,
+            contentType,
+            filename
+        };
+    }
+}
+async function readBodyWithLimit(response, maxBytes, url) {
+    if (!response.body) return Buffer.alloc(0);
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        while(true){
+            const { done, value } = await reader.read();
+            if (done) break;
+            total += value.byteLength;
+            if (total > maxBytes) {
+                throw new Error(`Response body from ${url} exceeded ${maxBytes} bytes during streaming.`);
+            }
+            chunks.push(value);
+        }
+    } finally{
+        try {
+            reader.releaseLock();
+        } catch  {
+        // Reader already released after the stream errored; nothing to do.
+        }
+    }
+    return Buffer.concat(chunks, total);
+}
+/**
+ * Derive a safe filename from a URL path segment, falling back to a
+ * UUID-based name using the Content-Type for the extension.
+ */ function deriveFilename(pathname, contentType) {
+    const lastSegment = pathname.split('/').filter(Boolean).pop() ?? '';
+    const cleaned = lastSegment.replace(/[?#].*/g, '').replace(/\.\./g, '').replace(/[/\\]/g, '');
+    if (cleaned && cleaned.includes('.') && cleaned.length <= 200) {
+        return cleaned;
+    }
+    const extMap = {
+        'image/jpeg': '.jpg',
+        'image/png': '.png',
+        'image/webp': '.webp',
+        'image/gif': '.gif'
+    };
+    const ext = extMap[contentType] ?? '.bin';
+    return `${crypto.randomUUID()}${ext}`;
+}
+
+//# sourceMappingURL=url-validator.js.map

package/dist/url-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/url-validator.ts"],"sourcesContent":["import dns from 'node:dns'\nimport { Buffer } from 'node:buffer'\n\nconst MAX_REDIRECTS = 3\nconst FETCH_TIMEOUT_MS = 10_000\n\ninterface ValidatedFetchResult {\n  buffer: Buffer\n  contentType: string\n  filename: string\n}\n\nconst DEFAULT_MAX_BYTES = 50 * 1024 * 1024 // 50MB hard ceiling — caller may pass a tighter cap.\n\n/**\n * Check whether an IP address falls within a private/reserved range.\n *\n * Blocks (IPv4): 0.0.0.0/8, 10.0.0.0/8, 100.64.0.0/10 (CGNAT),\n * 127.0.0.0/8, 169.254.0.0/16 (link-local + AWS metadata),\n * 172.16.0.0/12, 192.168.0.0/16.\n *\n * Blocks (IPv6): ::1 (loopback, in any expanded form), fc00::/7\n * (unique local), fe80::/10 (link-local), and any IPv4-mapped or\n * IPv4-compatible address whose embedded IPv4 falls in a blocked range.\n */\nexport function isPrivateIp(ip: string): boolean {\n  if (ip.includes(':')) return isPrivateIpV6(ip)\n  return isPrivateIpV4(ip)\n}\n\nfunction isPrivateIpV4(ip: string): boolean {\n  const parts = ip.split('.')\n  if (parts.length !== 4) return false\n  const [a, b] = parts.map(Number)\n  if (parts.some((p) => Number.isNaN(Number(p)))) return false\n\n  if (a === 0) return true // 0.0.0.0/8\n  if (a === 10) return true // 10.0.0.0/8\n  if (a === 100 && b >= 64 && b <= 127) return true // 100.64.0.0/10 — CGNAT\n  if (a === 127) return true // 127.0.0.0/8\n  if (a === 169 && b === 254) return true // 169.254.0.0/16\n  if (a === 172 && b >= 16 && b <= 31) return true // 172.16.0.0/12\n  if (a === 192 && b === 168) return true // 192.168.0.0/16\n\n  return false\n}\n\nfunction isPrivateIpV6(ip: string): boolean {\n  const normalized = ip.toLowerCase()\n\n  // IPv4-mapped (::ffff:1.2.3.4) and IPv4-compatible (::1.2.3.4) — extract\n  // the embedded v4 and run the v4 checks against it.\n  const mappedMatch = normalized.match(/^::ffff:(\\d+\\.\\d+\\.\\d+\\.\\d+)$/)\n  if (mappedMatch) return isPrivateIpV4(mappedMatch[1]!)\n  const compatMatch = normalized.match(/^::(\\d+\\.\\d+\\.\\d+\\.\\d+)$/)\n  if (compatMatch) return isPrivateIpV4(compatMatch[1]!)\n\n  // Expand to full 8-group form so loopback/link-local checks aren't\n  // defeated by alternate notations (`0:0:0:0:0:0:0:1`, `0000:...:0001`).\n  const groups = expandIpV6(normalized)\n  if (!groups) return false\n\n  // Loopback ::1\n  if (groups.every((g, i) => (i < 7 ? g === 0 : g === 1))) return true\n\n  const first = groups[0]!\n  // fc00::/7 — unique local (fc00–fdff)\n  if ((first & 0xfe00) === 0xfc00) return true\n  // fe80::/10 — link-local\n  if ((first & 0xffc0) === 0xfe80) return true\n\n  return false\n}\n\n/**\n * Expand a textual IPv6 address into 8 numeric groups. Returns null if\n * the address isn't a recognisable v6 string (we err toward \"not private\"\n * for unparseable input — DNS already gave us a real address, this guards\n * notation variance, not malicious DNS payloads).\n */\nfunction expandIpV6(ip: string): number[] | null {\n  if (ip.includes('.')) return null // mapped/compat handled above\n  const halves = ip.split('::')\n  if (halves.length > 2) return null\n\n  const parse = (segment: string): number[] | null => {\n    if (segment === '') return []\n    const out: number[] = []\n    for (const piece of segment.split(':')) {\n      if (!/^[0-9a-f]{1,4}$/.test(piece)) return null\n      out.push(parseInt(piece, 16))\n    }\n    return out\n  }\n\n  if (halves.length === 1) {\n    const parts = parse(ip)\n    return parts && parts.length === 8 ? parts : null\n  }\n\n  const head = parse(halves[0]!)\n  const tail = parse(halves[1]!)\n  if (!head || !tail) return null\n  const fillCount = 8 - head.length - tail.length\n  if (fillCount < 0) return null\n  return [...head, ...new Array(fillCount).fill(0), ...tail]\n}\n\n/**\n * Validate a URL for SSRF safety and fetch its contents.\n *\n * - HTTPS-only scheme validation\n * - DNS resolution pre-check to block private/reserved IPs\n * - Manual redirect following with IP re-validation at each hop\n * - 10-second timeout\n *\n * NOTE: Small TOCTOU gap between DNS resolution and the actual TCP\n * connection (DNS rebinding). A future improvement could use a custom\n * http.Agent with a `lookup` override to validate IPs at connection time.\n */\nexport async function validateAndFetchUrl(\n  url: string,\n  options?: { maxRedirects?: number; timeoutMs?: number; maxBytes?: number },\n): Promise<ValidatedFetchResult> {\n  const maxRedirects = options?.maxRedirects ?? MAX_REDIRECTS\n  const timeoutMs = options?.timeoutMs ?? FETCH_TIMEOUT_MS\n  const maxBytes = options?.maxBytes ?? DEFAULT_MAX_BYTES\n\n  let currentUrl = url\n  let redirectCount = 0\n\n  while (true) {\n    const parsed = new URL(currentUrl)\n\n    if (parsed.protocol !== 'https:') {\n      throw new Error(`Only HTTPS URLs are allowed. Received: ${parsed.protocol}`)\n    }\n\n    const hostname = parsed.hostname\n    const { address } = await dns.promises.lookup(hostname)\n\n    if (isPrivateIp(address)) {\n      throw new Error(\n        `SSRF blocked: hostname \"${hostname}\" resolves to private IP ${address}. ` +\n          'Only public internet addresses are allowed.',\n      )\n    }\n\n    const controller = new AbortController()\n    const timer = setTimeout(() => controller.abort(), timeoutMs)\n\n    let response: Response\n    try {\n      response = await fetch(currentUrl, {\n        redirect: 'manual',\n        signal: controller.signal,\n        headers: { 'User-Agent': 'payload-mcp-toolkit/0.1' },\n      })\n    } catch (error) {\n      clearTimeout(timer)\n      if (error instanceof DOMException && error.name === 'AbortError') {\n        throw new Error(`Request timed out after ${timeoutMs}ms fetching ${currentUrl}`)\n      }\n      throw error\n    } finally {\n      clearTimeout(timer)\n    }\n\n    if (response.status >= 300 && response.status < 400) {\n      const location = response.headers.get('location')\n      if (!location) {\n        throw new Error(`Redirect response (${response.status}) missing Location header.`)\n      }\n\n      redirectCount++\n      if (redirectCount > maxRedirects) {\n        throw new Error(`Too many redirects (max ${maxRedirects}). Last URL: ${currentUrl}`)\n      }\n\n      currentUrl = new URL(location, currentUrl).href\n      continue\n    }\n\n    if (!response.ok) {\n      throw new Error(`Failed to fetch ${currentUrl}: HTTP ${response.status} ${response.statusText}`)\n    }\n\n    const contentType = response.headers.get('content-type')?.split(';')[0]?.trim() ?? ''\n\n    // Reject early if the server advertises a body larger than maxBytes.\n    const declaredLength = response.headers.get('content-length')\n    if (declaredLength !== null) {\n      const length = Number(declaredLength)\n      if (Number.isFinite(length) && length > maxBytes) {\n        throw new Error(\n          `Response body exceeds ${maxBytes} bytes (Content-Length: ${length}).`,\n        )\n      }\n    }\n\n    // Stream the body, enforcing the cap as we go so a server that lies\n    // (or omits) Content-Length cannot exhaust memory.\n    const buffer = await readBodyWithLimit(response, maxBytes, currentUrl)\n    const filename = deriveFilename(parsed.pathname, contentType)\n\n    return { buffer, contentType, filename }\n  }\n}\n\nasync function readBodyWithLimit(\n  response: Response,\n  maxBytes: number,\n  url: string,\n): Promise<Buffer> {\n  if (!response.body) return Buffer.alloc(0)\n  const reader = response.body.getReader()\n  const chunks: Uint8Array[] = []\n  let total = 0\n  try {\n    while (true) {\n      const { done, value } = await reader.read()\n      if (done) break\n      total += value.byteLength\n      if (total > maxBytes) {\n        throw new Error(`Response body from ${url} exceeded ${maxBytes} bytes during streaming.`)\n      }\n      chunks.push(value)\n    }\n  } finally {\n    try {\n      reader.releaseLock()\n    } catch {\n      // Reader already released after the stream errored; nothing to do.\n    }\n  }\n  return Buffer.concat(chunks, total)\n}\n\n/**\n * Derive a safe filename from a URL path segment, falling back to a\n * UUID-based name using the Content-Type for the extension.\n */\nfunction deriveFilename(pathname: string, contentType: string): string {\n  const lastSegment = pathname.split('/').filter(Boolean).pop() ?? ''\n\n  const cleaned = lastSegment\n    .replace(/[?#].*/g, '')\n    .replace(/\\.\\./g, '')\n    .replace(/[/\\\\]/g, '')\n\n  if (cleaned && cleaned.includes('.') && cleaned.length <= 200) {\n    return cleaned\n  }\n\n  const extMap: Record<string, string> = {\n    'image/jpeg': '.jpg',\n    'image/png': '.png',\n    'image/webp': '.webp',\n    'image/gif': '.gif',\n  }\n  const ext = extMap[contentType] ?? '.bin'\n  return `${crypto.randomUUID()}${ext}`\n}\n"],"names":["dns","Buffer","MAX_REDIRECTS","FETCH_TIMEOUT_MS","DEFAULT_MAX_BYTES","isPrivateIp","ip","includes","isPrivateIpV6","isPrivateIpV4","parts","split","length","a","b","map","Number","some","p","isNaN","normalized","toLowerCase","mappedMatch","match","compatMatch","groups","expandIpV6","every","g","i","first","halves","parse","segment","out","piece","test","push","parseInt","head","tail","fillCount","Array","fill","validateAndFetchUrl","url","options","maxRedirects","timeoutMs","maxBytes","currentUrl","redirectCount","parsed","URL","protocol","Error","hostname","address","promises","lookup","controller","AbortController","timer","setTimeout","abort","response","fetch","redirect","signal","headers","error","clearTimeout","DOMException","name","status","location","get","href","ok","statusText","contentType","trim","declaredLength","isFinite","buffer","readBodyWithLimit","filename","deriveFilename","pathname","body","alloc","reader","getReader","chunks","total","done","value","read","byteLength","releaseLock","concat","lastSegment","filter","Boolean","pop","cleaned","replace","extMap","ext","crypto","randomUUID"],"mappings":"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"}

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "payload-mcp-toolkit",
+  "version": "0.2.0",
+  "description": "Schema-aware MCP toolkit for Payload CMS — wraps the official @payloadcms/plugin-mcp with introspected prompts, resources, draft workflow, and AI-friendly tools so non-technical editors can manage content via AI chat.",
+  "license": "MIT",
+  "author": "jon8800",
+  "homepage": "https://github.com/jon8800/payload-mcp-toolkit#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jon8800/payload-mcp-toolkit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jon8800/payload-mcp-toolkit/issues"
+  },
+  "type": "module",
+  "keywords": [
+    "payload",
+    "payload-plugin",
+    "payloadcms",
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "cms",
+    "content-management"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "@payloadcms/plugin-mcp": "^3.0.0",
+    "payload": "^3.0.0",
+    "zod": "^3.0.0"
+  },
+  "devDependencies": {
+    "@payloadcms/db-sqlite": "3.82.1",
+    "@payloadcms/next": "3.82.1",
+    "@payloadcms/plugin-mcp": "3.82.1",
+    "@payloadcms/richtext-lexical": "3.82.1",
+    "@payloadcms/ui": "3.82.1",
+    "@swc/cli": "0.6.0",
+    "@types/node": "22.19.9",
+    "@types/react": "19.2.14",
+    "@types/react-dom": "19.2.3",
+    "copyfiles": "2.4.1",
+    "cross-env": "^7.0.3",
+    "graphql": "^16.8.1",
+    "next": "16.2.3",
+    "payload": "3.82.1",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "rimraf": "^5.0.5",
+    "sharp": "0.34.2",
+    "typescript": "5.7.3",
+    "vite-tsconfig-paths": "6.0.5",
+    "vitest": "4.0.18",
+    "zod": "^3.23.8"
+  },
+  "engines": {
+    "node": "^18.20.2 || >=20.9.0",
+    "pnpm": "^9 || ^10"
+  },
+  "scripts": {
+    "build": "pnpm copyfiles && pnpm build:types && pnpm build:swc",
+    "build:swc": "swc ./src -d ./dist --config-file .swcrc --strip-leading-paths",
+    "build:types": "tsc -p tsconfig.build.json",
+    "clean": "rimraf dist",
+    "copyfiles": "copyfiles -u 1 \"src/**/*.{html,css,scss,svg,json}\" dist/",
+    "dev": "next dev dev --turbo",
+    "dev:generate-importmap": "cd dev && cross-env PAYLOAD_CONFIG_PATH=./payload.config.ts payload generate:importmap",
+    "dev:generate-types": "cd dev && cross-env PAYLOAD_CONFIG_PATH=./payload.config.ts payload generate:types",
+    "dev:payload": "cd dev && cross-env PAYLOAD_CONFIG_PATH=./payload.config.ts payload",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}