forkfeed-mcp 1.2.0 → 1.3.1

package/dist/guide-content.js

@@ -14,7 +14,7 @@ Turn GitHub commits into swipeable card content. One fork per repo, one feed per
 
 1. Call **forkfeed_guide** and **forkfeed_commits()** in parallel
 2. Show commits table, ask which ONE to process
-3. Call **forkfeed_commits(sha)** to get diff, stats, and pre-filtered images
+3. Call **forkfeed_commits(sha)** to get diff, stats, and suggested scene images
 4. Generate simplified content JSON (see format below)
 5. Call **forkfeed_build** with the content (push defaults to true)
 
@@ -22,26 +22,19 @@ Turn GitHub commits into swipeable card content. One fork per repo, one feed per
 
 ## Simplified content format (for forkfeed_build)
 
-The builder handles UUIDs, full image URLs, cover variants, type wrappers, feedId/order, and fork/feed boilerplate. You only provide creative content.
+The builder auto-detects repo info (owner, repo, GitHub URL), auto-assigns card backgrounds, and fetches existing feed IDs from the server. You only provide creative content.
 
 \`\`\`json
 {
-  "owner": "owner-or-local",
-  "repo": "repo-name",
-  "sha": "7char",
+  "sha": "7char-sha",
   "feedTitle": "Max 60 chars headline",
   "feedDescription": "Mon DD: one-line impact summary",
   "forkTitle": "Project Name",
   "forkDescription": "What the project IS",
-  "actionUrl": "https://github.com/owner/repo",
-  "existingFeedIds": [],
-  "images": {
-    "bg": ["bg10", "bg11", "bg20", "bg25", "bg9", "bg12", "bg30", "bg18"]
-  },
   "cards": [
     {
       "variants": [
-        { "blocks": [{ "img": "img47", "sizing": "wide" }, { "title": "Section heading" }, { "text": "Paragraph content..." }] },
+        { "blocks": [{ "img": "img47" }, { "title": "Section heading" }, { "text": "Paragraph content..." }] },
         { "blocks": [{ "title": "Another section" }, { "text": "More content..." }] }
       ]
     }
@@ -49,6 +42,8 @@ The builder handles UUIDs, full image URLs, cover variants, type wrappers, feedI
 }
 \`\`\`
 
+Only 5 fields + cards. Everything else is auto-populated.
+
 ### Block types (inferred from fields)
 
 | Write this | Becomes | Notes |
@@ -59,19 +54,27 @@ The builder handles UUIDs, full image URLs, cover variants, type wrappers, feedI
 | \`{ "text": "Paragraph..." }\` | CONTENT_TEXT | 50-200 words, use \\\\n\\\\n for breaks |
 | \`{ "code": "const x = 1", "lang": "typescript" }\` | CONTENT_CODE | Real code from diff, 5-20 lines, strip +/- prefixes |
 | \`{ "subtext": "Pro tip..." }\` | CONTENT_SUBTEXT | Aside or protip |
-| \`{ "name": "Chad", "subtitle": "10x Engineer", "avatar": "img98", "source": "linkedin" }\` | CONTENT_SOCIAL | Cards 2-3 only. source: x, linkedin, threads, etc. |
+| \`{ "name": "Chad", "subtitle": "10x Engineer", "avatar": "img98", "source": "linkedin" }\` | CONTENT_SOCIAL | Cards 2-3 only. avatar can be image ID or URL. source: x, linkedin, threads, etc. |
 | \`{ "question": "What does X do?", "options": [{"label": "A", "correct": false}, {"label": "B", "correct": true}], "explanation": "Because..." }\` | CONTENT_QUIZ | Card 7 only. 4 options recommended, min 2, one correct, always include explanation |
 | \`{ "label": "Google it", "action": "url", "target": "https://google.com/search?q=topic" }\` | CONTENT_BUTTON | Card 5 only, MUST be last block in every detail variant |
 
 ### What the builder does automatically
+- Detects repo owner/name from git remote
+- Generates fork/feed IDs from convention (tfip-{owner}-{repo}-{sha})
+- Constructs GitHub action URL
+- Fetches existing feed IDs from server (for incremental updates)
+- Assigns 8 unique card backgrounds from preference table + commit tags
 - Generates UUID v4 for each card ID
 - Resolves short image IDs (img47, bg10) to full CDN URLs
 - Adds FULL_IMAGE cover variant with fixed title/subtitle per card type
-- Sets backgroundSrc on all CONTENT variants from images.bg[cardIndex]
-- Sets feedId and order on each card
-- Builds fork and feed objects with correct IDs and metadata
+- Sets backgroundSrc, feedId, and order on each card
 - Validates the assembled manifest before pushing
 
+### Optional overrides
+- \`bgOverride\`: array of 8 background IDs to override auto-assignment
+- \`coverOverride\`: array of 8 cover image IDs (defaults to backgrounds)
+- \`cwd\`: working directory if not process.cwd()
+
 ---
 
 ## The 8 cards
@@ -104,7 +107,7 @@ Each card = array of detail variants (cover is auto-generated). Provide 1+ varia
 ## Key rules
 
 - Exactly 8 cards in the cards array (one per section above)
-- images.bg must have 8 unique background IDs
+- Use short image IDs from forkfeed_commits output (img47, not full URLs)
 - 12-20 unique scene images (img*) across the feed, no duplicate within same card
 - Cards 0-5: code must be REAL from the diff (never fabricated)
 - Card 6: synthesized code IS allowed
@@ -115,32 +118,13 @@ Each card = array of detail variants (cover is auto-generated). Provide 1+ varia
 - No em dashes, smart quotes, or non-ASCII characters
 - Feed title max 60 chars
 
-### Images
-
-Images are pre-filtered by **forkfeed_commits(sha)**. Pick from the suggested list.
-
-**BG preferences:** ELI5: bg10/bg27 | Roast: bg11/bg1 | Decoded: bg20/bg11 | LinkedIn: bg25/bg24 | Stats: bg9/bg3 | Learning: match tech | Alts: bg25/bg30 | Quiz: bg18/bg5
-
 ### Tone
 Casual, cheeky, technically accurate. Use "you," contractions, short paragraphs, occasional swearing. Humor is the default.
 
 ### Incremental updates
-**forkfeed_commits()** (list mode) shows which commits have published feeds and lists existing feed IDs.
+**forkfeed_commits()** (list mode) shows which commits have published feeds. The builder auto-fetches existing feed IDs, so you don't need to track them.
 
-- **New commit**: Include ALL existing feed IDs in existingFeedIds. Missing old IDs causes deletion.
+- **New commit**: Just generate content. The builder handles feed ID preservation.
 - **Existing commit**: Warn the user. Only regenerate if they confirm.
 - **One commit per run**: Never process multiple commits at once.
-
----
-
-## Advanced: direct push with full manifest (forkfeed_push)
-
-If you need full control, you can build the manifest manually and use forkfeed_push directly. The full manifest requires:
-- Fork/feed objects with all fields (mode, scrollDirection, engagement, etc.)
-- FULL_IMAGE cover variant[0] per card with fixed titles/subtitles
-- CONTENT variants with type field, full image URLs, backgroundSrc
-- UUID v4 card IDs, feedId and order on each card
-
-ID conventions: Fork: \`tfip-{owner}-{repo}\`, Feed: \`tfip-{owner}-{repo}-{7char-sha}\`, Card: UUID v4
-All IDs must match \`/^[a-z0-9-]+$/\` (except card UUIDs).
 `.trim();

package/dist/index.js

@@ -8,7 +8,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { z } from 'zod';
 import QRCode from 'qrcode';
 import { GUIDE_CONTENT } from './guide-content.js';
-import { IMAGE_CATALOG, IMAGE_BASE_URL, resolveImageId } from './image-catalog.js';
+import { IMAGE_CATALOG, resolveImageId } from './image-catalog.js';
 const execFileAsync = promisify(execFile);
 const APP_SERVER_URL = (process.env.APP_SERVER_URL || 'https://api.forkfeed.link').replace(/\/+$/, '');
 const TOKEN = process.env.FORKFEED_TOKEN || '';
@@ -136,11 +136,12 @@ async function getRepoInfo(cwd) {
     catch { /* no remote */ }
     return { owner: null, repo: basename(cwd), isLocal: true };
 }
+const SEP = '\x1e'; // ASCII record separator (safe in commit messages)
 async function getCommitList(cwd, count = 15) {
-    const fmt = '%H|%h|%s|%an|%aI|%P';
+    const fmt = `%H${SEP}%h${SEP}%s${SEP}%an${SEP}%aI`;
     const raw = await gitExec(['log', '--no-merges', `-${count}`, `--format=${fmt}`], cwd);
     return raw.trim().split('\n').filter(Boolean).map((line) => {
-        const [sha, shortSha, message, author, date] = line.split('|');
+        const [sha, shortSha, message, author, date] = line.split(SEP);
         return { sha, shortSha, message, author, date: date?.slice(0, 10) || '' };
     });
 }
@@ -159,11 +160,11 @@ function truncateDiff(diff, maxLinesPerFile = 200) {
 }
 async function getCommitDetail(cwd, sha) {
     const [meta, stats, diff] = await Promise.all([
-        gitExec(['show', sha, '--format=%H|%h|%s|%an|%aI', '--no-patch'], cwd),
+        gitExec(['show', sha, `--format=%H${SEP}%h${SEP}%s${SEP}%an${SEP}%aI`, '--no-patch'], cwd),
         gitExec(['diff', `${sha}^..${sha}`, '--stat'], cwd),
         gitExec(['diff', `${sha}^..${sha}`, '-U3'], cwd),
     ]);
-    const [fullSha, shortSha, message, author, date] = meta.trim().split('|');
+    const [fullSha, shortSha, message, author, date] = meta.trim().split(SEP);
     return {
         sha: fullSha,
         shortSha,
@@ -209,6 +210,48 @@ function detectTags(message, filePaths) {
         tags.add('general');
     return [...tags];
 }
+function parseFilePathsFromStats(stats) {
+    const matches = stats.match(/^\s*(.+?)\s+\|/gm) || [];
+    return matches.map((m) => m.trim().replace(/\s+\|$/, ''));
+}
+const BG_PREFS = [
+    ['bg10', 'bg27'], // 0: ELI5
+    ['bg11', 'bg1'], // 1: Roast
+    ['bg20', 'bg11'], // 2: Decoded
+    ['bg25', 'bg24'], // 3: LinkedIn
+    ['bg9', 'bg3'], // 4: Stats
+    ['bg12', 'bg13', 'bg14', 'bg15', 'bg17'], // 5: Learning (tech-match)
+    ['bg25', 'bg30'], // 6: Alternatives
+    ['bg18', 'bg5'], // 7: Quiz
+];
+// Map language tags to preferred Learning card (index 5) backgrounds
+const LANG_BG = {
+    javascript: 'bg12', typescript: 'bg12',
+    python: 'bg13',
+    rust: 'bg14',
+    deploy: 'bg15',
+    // bg17 = Frontend (fallback for language tag without specific match)
+};
+function assignBackgrounds(tags) {
+    const used = new Set();
+    // For card 5 (Learning), reorder prefs based on detected language tags
+    const learningPrefs = [...BG_PREFS[5]];
+    for (const tag of tags) {
+        const preferred = LANG_BG[tag];
+        if (preferred && learningPrefs.includes(preferred)) {
+            // Move matched bg to front
+            learningPrefs.splice(learningPrefs.indexOf(preferred), 1);
+            learningPrefs.unshift(preferred);
+            break;
+        }
+    }
+    return BG_PREFS.map((prefs, i) => {
+        const candidates = i === 5 ? learningPrefs : prefs;
+        const pick = candidates.find((bg) => !used.has(bg)) || candidates[0];
+        used.add(pick);
+        return pick;
+    });
+}
 function filterImagesByTags(tags) {
     const tagSet = new Set(tags);
     function score(entry) {
@@ -219,13 +262,13 @@ function filterImagesByTags(tags) {
         .map((i) => ({ ...i, score: score(i) }))
         .sort((a, b) => b.score - a.score)
         .slice(0, 30)
-        .map((i) => `${i.id} | ${i.name} | ${i.tags} | ${IMAGE_BASE_URL}${i.file}`);
+        .map((i) => `${i.id} | ${i.name} | ${i.tags}`);
     const backgrounds = IMAGE_CATALOG
         .filter((i) => i.id.startsWith('bg'))
         .map((i) => ({ ...i, score: score(i) }))
         .sort((a, b) => b.score - a.score)
         .slice(0, 10)
-        .map((i) => `${i.id} | ${i.name} | ${i.tags} | ${IMAGE_BASE_URL}${i.file}`);
+        .map((i) => `${i.id} | ${i.name} | ${i.tags}`);
     return { scenes, backgrounds };
 }
 async function fetchStatusData() {
@@ -260,10 +303,11 @@ function inferBlock(block) {
         };
     }
     if ('name' in block && 'avatar' in block) {
+        const avatar = block.avatar;
         return {
             type: 'CONTENT_SOCIAL',
             name: block.name,
-            avatarSrc: resolveImageId(block.avatar),
+            avatarSrc: avatar.startsWith('http') ? avatar : resolveImageId(avatar),
             source: block.source,
             ...(block.subtitle != null ? { subtitle: block.subtitle } : {}),
         };
@@ -277,9 +321,10 @@ function inferBlock(block) {
         };
     }
     if ('img' in block) {
+        const img = block.img;
         return {
             type: 'CONTENT_IMAGE',
-            imageSrc: resolveImageId(block.img),
+            imageSrc: img.startsWith('http') ? img : resolveImageId(img),
             sizing: (block.sizing || 'wide'),
         };
     }
@@ -303,41 +348,66 @@ function inferBlock(block) {
 }
 // ── Build input schema ───────────────────────────────────────────────
 const buildInputSchema = z.object({
-    owner: z.string().min(1),
-    repo: z.string().min(1),
     sha: z.string().min(1),
     feedTitle: z.string().min(1).max(60),
     feedDescription: z.string().min(1),
     forkTitle: z.string().min(1),
     forkDescription: z.string().min(1),
-    actionUrl: z.string().optional(),
-    existingFeedIds: z.array(z.string()).optional(),
-    images: z.object({
-        bg: z.array(z.string()).length(8),
-        cover: z.array(z.string()).length(8).optional(),
-    }),
     cards: z.array(z.object({
         variants: z.array(z.object({
             blocks: z.array(z.record(z.string(), z.unknown())).min(1),
         })).min(1),
     })).length(8),
+    cwd: z.string().optional().describe('Working directory (defaults to process.cwd())'),
+    bgOverride: z.array(z.string()).length(8).optional().describe('Override auto-assigned background IDs'),
+    coverOverride: z.array(z.string()).length(8).optional().describe('Override cover image IDs (defaults to backgrounds)'),
 });
 // ── Manifest builder ─────────────────────────────────────────────────
-function buildManifest(input) {
-    const forkId = `tfip-${input.owner}-${input.repo}`;
-    const feedId = `tfip-${input.owner}-${input.repo}-${input.sha.slice(0, 7)}`;
+async function buildManifest(input) {
+    const cwd = input.cwd || process.cwd();
+    // Auto-detect repo info
+    const repoInfo = await getRepoInfo(cwd);
+    const owner = repoInfo.owner || 'local';
+    const repo = repoInfo.repo;
+    const sha7 = input.sha.slice(0, 7);
+    const forkId = `tfip-${owner}-${repo}`;
+    const feedId = `tfip-${owner}-${repo}-${sha7}`;
+    // Auto-assign backgrounds (or use override)
+    let bgs;
+    if (input.bgOverride) {
+        bgs = input.bgOverride;
+    }
+    else {
+        const meta = await gitExec(['show', input.sha, '--format=%s', '--no-patch'], cwd);
+        const statOutput = await gitExec(['diff', `${input.sha}^..${input.sha}`, '--stat'], cwd);
+        const filePaths = parseFilePathsFromStats(statOutput);
+        const tags = detectTags(meta.trim(), filePaths);
+        bgs = assignBackgrounds(tags);
+    }
+    // Auto-fetch existing feed IDs (best-effort)
+    let existingFeedIds = [];
+    if (TOKEN) {
+        try {
+            const status = await fetchStatusData();
+            existingFeedIds = (status.feeds || []).map((f) => f.externalFeedId);
+        }
+        catch { /* best-effort */ }
+    }
     // Resolve image IDs
-    const bgUrls = input.images.bg.map(resolveImageId);
-    const coverUrls = input.images.cover
-        ? input.images.cover.map(resolveImageId)
+    const bgUrls = bgs.map(resolveImageId);
+    const coverUrls = input.coverOverride
+        ? input.coverOverride.map(resolveImageId)
         : bgUrls;
+    const actionUrl = repoInfo.owner
+        ? `https://github.com/${repoInfo.owner}/${repoInfo.repo}`
+        : undefined;
     const fork = {
         _id: forkId,
         title: input.forkTitle,
         description: input.forkDescription,
         imageSrc: coverUrls[0],
-        feedIds: [...(input.existingFeedIds || []), feedId],
-        ...(input.actionUrl ? { actionLabel: 'View on GitHub', actionUrl: input.actionUrl } : {}),
+        feedIds: [...existingFeedIds, feedId],
+        ...(actionUrl ? { actionLabel: 'View on GitHub', actionUrl } : {}),
     };
     const feed = {
         _id: feedId,
@@ -507,7 +577,7 @@ server.tool('forkfeed_commits', 'Read git commits from the current repo. Without
             lines.push(`| ${i + 1} | ${c.shortSha} | ${c.message.slice(0, 60)} | ${c.author} | ${c.date} | ${pub} |`);
         }
         if (existingFeedIds.length > 0) {
-            lines.push('', `Existing feed IDs (include ALL in fork.feedIds): ${existingFeedIds.join(', ')}`);
+            lines.push('', `Published feeds: ${existingFeedIds.length} (builder auto-includes them)`);
         }
         if (statusWarning)
             lines.push(statusWarning);
@@ -522,8 +592,7 @@ server.tool('forkfeed_commits', 'Read git commits from the current repo. Without
         return { content: [{ type: 'text', text: `Failed to read commit ${sha}: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
     }
     // Extract file paths from stats for tag detection
-    const filePathMatches = detail.stats.match(/^\s*(.+?)\s+\|/gm) || [];
-    const filePaths = filePathMatches.map((m) => m.trim().replace(/\s+\|$/, ''));
+    const filePaths = parseFilePathsFromStats(detail.stats);
     const tags = detectTags(detail.message, filePaths);
     const images = filterImagesByTags(tags);
     const lines = [
@@ -538,40 +607,13 @@ server.tool('forkfeed_commits', 'Read git commits from the current repo. Without
         '## Diff',
         detail.diff,
         '',
-        `## Suggested Images (tags: ${tags.join(', ')})`,
+        `## Suggested Scene Images (tags: ${tags.join(', ')})`,
+        'Use short IDs (e.g. img47) in card blocks. Backgrounds are auto-assigned by the builder.',
         '',
-        'Scene images (for covers + inline):',
         ...images.scenes,
-        '',
-        'Background images (for card backgrounds):',
-        ...images.backgrounds,
     ].filter(Boolean);
     return { content: [{ type: 'text', text: lines.join('\n') }] };
 });
-// ── Tool: forkfeed_images ──────────────────────────────────────────────
-server.tool('forkfeed_images', 'Get the IT Scenes image catalog (200 scene images + 30 backgrounds). Use this to pick images that match your content by tags and name. Call after forkfeed_guide.', {}, async () => {
-    const scenes = IMAGE_CATALOG.filter((i) => i.id.startsWith('img'));
-    const bgs = IMAGE_CATALOG.filter((i) => i.id.startsWith('bg'));
-    const lines = [
-        '# IT Scenes Image Catalog',
-        '',
-        `Base URL: ${IMAGE_BASE_URL}`,
-        'Prepend base URL to all filenames below to get the full image URL.',
-        '',
-        'Match images to content by tags and name. Use img* for covers and inline images, bg* for card backgrounds.',
-        '',
-        'Tags: deploy, git, disaster, debug, hype, victory, beginner, language, lifestyle, workplace, sarcastic, general',
-        '',
-        '## Scene Images (covers + inline)',
-        '',
-        ...scenes.map((i) => `${i.id} | ${i.name} | ${i.tags} | ${i.file}`),
-        '',
-        '## Background Images',
-        '',
-        ...bgs.map((i) => `${i.id} | ${i.name} | ${i.tags} | ${i.file}`),
-    ];
-    return { content: [{ type: 'text', text: lines.join('\n') }] };
-});
 // ── Tool: forkfeed_push ────────────────────────────────────────────────
 server.tool('forkfeed_push', 'Push a generated manifest (forks, feeds, cards) to forkfeed. The manifest JSON must conform to the structure described in forkfeed_guide.', {
     manifest: z
@@ -603,15 +645,15 @@ server.tool('forkfeed_push', 'Push a generated manifest (forks, feeds, cards) to
     return pushManifestToServer(parsed.data);
 });
 // ── Tool: forkfeed_build ──────────────────────────────────────────────
-server.tool('forkfeed_build', 'Build a forkfeed manifest from simplified content and push it. Generates UUIDs, resolves image IDs to URLs, adds cover variants automatically. Use this instead of forkfeed_push for faster content creation.', {
-    content: buildInputSchema.describe('Simplified content: repo info, image IDs, and creative card content only'),
+server.tool('forkfeed_build', 'Build a forkfeed manifest from simplified content and push it. Auto-detects repo info, assigns backgrounds, fetches existing feeds. Use this instead of forkfeed_push.', {
+    content: buildInputSchema.describe('Simplified content: sha, titles, descriptions, and 8 cards with blocks'),
     push: z.boolean().optional().describe('Push immediately after building (default: true)'),
 }, async ({ content, push }) => {
     const shouldPush = push !== false;
     // Build the full manifest from simplified input
     let manifest;
     try {
-        manifest = buildManifest(content);
+        manifest = await buildManifest(content);
     }
     catch (err) {
         return {
@@ -665,7 +707,7 @@ server.tool('forkfeed_status', 'Check your current forkfeed content: which forks
                 content: [
                     {
                         type: 'text',
-                        text: 'No forks published yet. Use forkfeed_guide to learn how to generate content, then push it with forkfeed_push.',
+                        text: 'No forks published yet. Use forkfeed_guide to learn how to generate content, then push it with forkfeed_build.',
                     },
                 ],
             };
@@ -708,9 +750,9 @@ server.prompt('forkfeed', 'Turn GitHub commits into swipeable forkfeed content.
                 text: `Turn the commits in this repo into forkfeed content. Follow these steps exactly:
 
 1. Call **forkfeed_guide** and **forkfeed_commits()** in parallel (no arguments for commits = list mode).
-2. Show the commits table from forkfeed_commits. It already indicates which commits have published feeds and lists existing feed IDs. Ask which ONE commit to process. One commit at a time, never more. Do NOT ask about image style.
-3. Call **forkfeed_commits** with the selected commit SHA. This returns the diff, file stats, and pre-filtered images. Do NOT call forkfeed_images separately, do NOT run git commands yourself.
-4. Generate the simplified content JSON as documented in the guide. Use short image IDs (img47, bg10), not full URLs. Do NOT generate UUIDs, cover variants, type wrappers, or fork/feed boilerplate. The builder handles all of that. Include ALL existing feed IDs (listed in step 1 output) in existingFeedIds.
+2. Show the commits table from forkfeed_commits. It already indicates which commits have published feeds. Ask which ONE commit to process. One commit at a time, never more. Do NOT ask about image style.
+3. Call **forkfeed_commits** with the selected commit SHA. This returns the diff, file stats, and suggested scene images. Do NOT run git commands yourself.
+4. Generate the simplified content JSON: sha, feedTitle, feedDescription, forkTitle, forkDescription, and 8 cards with blocks. Use short image IDs (img47) for inline images. Do NOT provide owner, repo, backgrounds, existingFeedIds, UUIDs, covers, or type wrappers. The builder auto-detects and generates all of that.
 5. Call **forkfeed_build** with the simplified content (push defaults to true).
 
 Start now.`,

package/package.json

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