forkfeed-mcp 1.0.12 → 1.0.14

package/dist/guide-content.js

@@ -205,11 +205,51 @@ Always call **forkfeed_status** before generating content. It lists published fe
 - **Existing commit**: Warn the user that this commit already has a feed. Only regenerate if they confirm. The old cards will be replaced.
 - **One commit per run**: Never process multiple commits at once. If the user wants more, they run the command again.
 
+### Parallel card generation
+
+Generate all 8 cards simultaneously using the Agent tool. This is critical for speed.
+
+**Planning phase** (main context, before launching agents):
+1. Assign images upfront: pick 8 unique covers (img*), 8 unique backgrounds (bg*), and split the remaining scene images into 8 non-overlapping pools for inline CONTENT_IMAGE use per card.
+2. Pre-generate 8 card UUIDs via \`node -e "..."\`.
+3. Output the skeleton (fork, feed, image assignments, UUIDs) so it's visible.
+
+**Agent prompts** (launch ALL 8 in a single message):
+Each agent generates exactly one card. The agent prompt must include:
+- Card number and section name (e.g., "Card 1: The roast")
+- The section rules from this guide: variant count range, block pattern, tone
+- The full commit diff and stats
+- Assigned cover imageSrc (img*), backgroundSrc (bg*), and the pool of available inline images for this card
+- The card UUID (\`_id\`) and feed ID (\`feedId\`)
+- "Return ONLY the raw JSON card object, no markdown, no explanation"
+
+Example agent prompt structure:
+\`\`\`
+Generate Card 2 (Commit message, decoded) for forkfeed.
+
+Card JSON structure: { "_id": "{uuid}", "feedId": "{feedId}", "order": 2, "variants": [...] }
+
+Rules: 2-4 detail variants. Pattern: SOCIAL -> TITLE -> TEXT -> optional CODE. Escalating absurdity.
+Personas: "What you meant" (source: "x"), "Corporate speak" (source: "linkedin").
+
+Cover: { "type": "FULL_IMAGE", "imageSrc": "{assigned-cover}", "title": "...", "subtitle": "..." }
+Background for all CONTENT variants: "{assigned-bg}"
+Available inline images: {pool}
+
+Commit diff:
+{diff}
+
+Return ONLY the JSON object. No markdown fences, no explanation.
+\`\`\`
+
+**Assembly** (main context, after agents complete):
+Collect 8 card JSONs, combine with fork and feed into the manifest, validate against the checklist, and push.
+
 ---
 
 ## Phase 4: Push
 
-After generating the manifest JSON, call the **forkfeed_push** tool with it:
+After assembling the manifest, call the **forkfeed_push** tool with it:
 \`\`\`
 forkfeed_push({ manifest: { forks: [...], feeds: [...], cards: [...] } })
 \`\`\`

package/dist/index.js

@@ -9,6 +9,86 @@ import { GUIDE_CONTENT } from './guide-content.js';
 import { IMAGE_CATALOG } from './image-catalog.js';
 const APP_SERVER_URL = (process.env.APP_SERVER_URL || 'https://api.forkfeed.link').replace(/\/+$/, '');
 const TOKEN = process.env.FORKFEED_TOKEN || '';
+// ── Manifest schemas ──────────────────────────────────────────────────
+const forkSchema = z.object({
+    _id: z.string().min(1, 'Fork _id is required'),
+    title: z.string().min(1, 'Fork title is required'),
+    description: z.string(),
+    imageSrc: z.string(),
+    feedIds: z.array(z.string().min(1)).min(1, 'Fork must reference at least one feed'),
+    actionLabel: z.string().optional(),
+    actionUrl: z.string().optional(),
+}).passthrough();
+const feedSchema = z.object({
+    _id: z.string().min(1, 'Feed _id is required'),
+    title: z.string().min(1, 'Feed title is required').max(60, 'Feed title max 60 chars'),
+    description: z.string().optional(),
+    imageSrc: z.string(),
+    mode: z.string(),
+    scrollDirection: z.string(),
+    engagement: z.boolean().optional(),
+}).passthrough();
+const sizingEnum = z.enum(['automatic', 'wide', 'portrait', 'square', 'small_portrait']);
+const socialSourceEnum = z.enum(['x', 'linkedin', 'instagram', 'facebook', 'threads', 'bluesky']);
+const buttonActionEnum = z.enum(['url', 'fork', 'feed', 'user']);
+const quizOptionSchema = z.object({
+    label: z.string().min(1),
+    correct: z.boolean(),
+}).passthrough();
+const contentBlockSchema = z.discriminatedUnion('type', [
+    z.object({ type: z.literal('CONTENT_IMAGE'), imageSrc: z.string().min(1), sizing: sizingEnum }).passthrough(),
+    z.object({ type: z.literal('CONTENT_TITLE'), title: z.string().min(1) }).passthrough(),
+    z.object({ type: z.literal('CONTENT_TEXT'), text: z.string().min(1) }).passthrough(),
+    z.object({ type: z.literal('CONTENT_CODE'), code: z.string().min(1), language: z.string().optional() }).passthrough(),
+    z.object({ type: z.literal('CONTENT_SOCIAL'), name: z.string().min(1), avatarSrc: z.string(), source: socialSourceEnum }).passthrough(),
+    z.object({ type: z.literal('CONTENT_SUBTEXT'), text: z.string().min(1) }).passthrough(),
+    z.object({ type: z.literal('CONTENT_QUIZ'), question: z.string().min(1), options: z.array(quizOptionSchema).min(2), explanation: z.string().optional() }).passthrough(),
+    z.object({ type: z.literal('CONTENT_BUTTON'), label: z.string().min(1), action: buttonActionEnum, target: z.string().min(1) }).passthrough(),
+]);
+const variantSchema = z.discriminatedUnion('type', [
+    z.object({ type: z.literal('FULL_IMAGE'), imageSrc: z.string().min(1, 'FULL_IMAGE requires imageSrc'), title: z.string().optional(), subtitle: z.string().optional() }).passthrough(),
+    z.object({ type: z.literal('FULL_VIDEO'), videoSrc: z.string().min(1), title: z.string().optional() }).passthrough(),
+    z.object({ type: z.literal('CONTENT'), blocks: z.array(contentBlockSchema).min(1, 'CONTENT variant needs at least one block'), backgroundSrc: z.string().optional() }).passthrough(),
+]);
+const cardSchema = z.object({
+    _id: z.string().min(1, 'Card _id is required'),
+    feedId: z.string().min(1, 'Card feedId is required'),
+    order: z.number().int().min(0),
+    variants: z.array(variantSchema).min(2, 'Card needs at least 2 variants (cover + detail)'),
+}).passthrough();
+const manifestSchema = z.object({
+    forks: z.array(forkSchema).min(1, 'Manifest must have at least one fork'),
+    feeds: z.array(feedSchema).min(1, 'Manifest must have at least one feed'),
+    cards: z.array(cardSchema).min(1, 'Manifest must have at least one card'),
+});
+/** Cross-reference checks that Zod can't express. Returns error string or null. */
+function crossValidate(manifest) {
+    const feedIds = new Set(manifest.feeds.map((f) => f._id));
+    const errors = [];
+    for (const fork of manifest.forks) {
+        for (const fid of fork.feedIds) {
+            if (!feedIds.has(fid))
+                errors.push(`Fork "${fork._id}" references feed "${fid}" which is not in feeds array`);
+        }
+    }
+    for (const card of manifest.cards) {
+        if (!feedIds.has(card.feedId))
+            errors.push(`Card "${card._id}" references feed "${card.feedId}" which is not in feeds array`);
+        for (let vi = 0; vi < card.variants.length; vi++) {
+            const v = card.variants[vi];
+            if (v.type !== 'CONTENT')
+                continue;
+            for (const block of v.blocks) {
+                if (block.type === 'CONTENT_QUIZ') {
+                    const hasCorrect = block.options.some((o) => o.correct === true);
+                    if (!hasCorrect)
+                        errors.push(`Card "${card._id}" variants[${vi}]: CONTENT_QUIZ must have at least one correct option`);
+                }
+            }
+        }
+    }
+    return errors.length > 0 ? errors.join('\n') : null;
+}
 // ── Helpers ────────────────────────────────────────────────────────────
 function authHeaders() {
     return {
@@ -67,6 +147,24 @@ server.tool('forkfeed_push', 'Push a generated manifest (forks, feeds, cards) to
             isError: true,
         };
     }
+    // Validate manifest structure before pushing
+    const parsed = manifestSchema.safeParse(manifest);
+    if (!parsed.success) {
+        const issues = parsed.error.issues
+            .map((i) => `  ${i.path.join('.')}: ${i.message}`)
+            .join('\n');
+        return {
+            content: [{ type: 'text', text: `Manifest validation failed:\n${issues}\n\nFix the issues above and try again.` }],
+            isError: true,
+        };
+    }
+    const crossErr = crossValidate(parsed.data);
+    if (crossErr) {
+        return {
+            content: [{ type: 'text', text: `Manifest cross-reference errors:\n${crossErr}\n\nFix the issues above and try again.` }],
+            isError: true,
+        };
+    }
     // Save manifest locally before uploading (best-effort, doesn't block push)
     const forkId = manifest.forks?.[0]?._id;
     const filename = `${forkId || `manifest-${Date.now()}`}.json`;
@@ -229,17 +327,25 @@ server.prompt('forkfeed', 'Turn GitHub commits into swipeable forkfeed content.
                 type: 'text',
                 text: `Turn the commits in this repo into forkfeed content. Follow these steps exactly:
 
-1. Call **forkfeed_guide** to get the full content generation guide. Read it carefully.
-2. Call **forkfeed_images** to get the IT Scenes image catalog (200 scenes + 30 backgrounds).
-3. Call **forkfeed_status** to check for existing content. Note which feeds (commits) are already published.
-4. Detect the current repo from the working directory. Use git to get commit data.
-5. Ask which ONE commit to process (default: latest). Only one commit at a time, never more. Do NOT ask about image style (always use IT Scenes). Show a table of recent commits with a column indicating whether each already has a published feed (match the 7-char SHA from forkfeed_status feed IDs against the commit SHAs). If the user selects a commit that already has a feed, warn and ask for confirmation before regenerating.
-6. Fetch the diff, analyze it, and generate the 8-card manifest following the guide exactly. Include ALL existing feed IDs in the fork's feedIds array (see "Incremental updates" in the guide).
-7. Match images from the catalog to card content by tags and semantic similarity.
-8. Validate the manifest against the checklist in the guide.
-9. Call **forkfeed_push** with the complete manifest to publish it.
+1. Call **forkfeed_guide** and **forkfeed_images** in parallel to load the content guide and image catalog.
+2. Call **forkfeed_status** to check for existing content.
+3. Detect the repo from the working directory. Show recent commits in a table with a column indicating whether each already has a published feed (match 7-char SHA from status feed IDs). Ask which ONE commit to process (default: latest). One commit at a time, never more. Do NOT ask about image style.
+4. Fetch the commit diff and stats via git.
+5. Plan the manifest skeleton (output this before generating cards):
+   - Fork: ID, title, description, imageSrc
+   - Feed: ID, title, description, imageSrc, mode: "sequential", scrollDirection: "vertical", engagement: true
+   - Assign 8 unique cover images (img*) and 8 unique backgrounds (bg*) to cards 0-7
+   - Pre-generate 8 card UUIDs
+   - Split remaining scene images into 8 non-overlapping pools for inline CONTENT_IMAGE use
+   - Include ALL existing feed IDs in the fork's feedIds array (see "Incremental updates" in guide)
+6. Generate all 8 cards IN PARALLEL using the Agent tool. Launch ALL 8 agents in a SINGLE message.
+   Each agent prompt must include: the card number, section type and rules (from the guide), the full commit diff, assigned cover/background/inline images, the card UUID, and the feed ID.
+   Each agent must return ONLY the raw card JSON object: { "_id": "...", "feedId": "...", "order": N, "variants": [...] }
+   See "Parallel card generation" in the guide for details.
+7. Assemble the full manifest from the skeleton + 8 card JSON results. Validate against the checklist.
+8. Call **forkfeed_push** with the complete manifest.
 
-Start now. Detect the repo and check for existing content.`,
+Start now. Load the guide and images in parallel, then detect the repo.`,
             },
         },
     ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forkfeed-mcp",
-  "version": "1.0.12",
+  "version": "1.0.14",
   "description": "MCP server for pushing GitHub commits to forkfeed",
   "type": "module",
   "bin": {