forkfeed-mcp 1.0.16 → 1.3.0

package/dist/index.js

@@ -1,12 +1,15 @@
 #!/usr/bin/env node
 import { mkdir, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { join, basename } from 'node:path';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 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 } 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 || '';
 // ── Manifest schemas ──────────────────────────────────────────────────
@@ -14,7 +17,7 @@ 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(),
+    imageSrc: z.string().min(1, 'Fork imageSrc is required'),
     feedIds: z.array(z.string().min(1)).min(1, 'Fork must reference at least one feed'),
     actionLabel: z.string().optional(),
     actionUrl: z.string().optional(),
@@ -23,7 +26,7 @@ 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(),
+    imageSrc: z.string().min(1, 'Feed imageSrc is required'),
     mode: z.string(),
     scrollDirection: z.string(),
     engagement: z.boolean().optional(),
@@ -40,14 +43,13 @@ const contentBlockSchema = z.discriminatedUnion('type', [
     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_SOCIAL'), name: z.string().min(1), subtitle: z.string().optional(), 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('FULL_IMAGE'), imageSrc: z.string().min(1, 'FULL_IMAGE requires imageSrc'), title: z.string().optional(), subtitle: z.string().max(200, 'FULL_IMAGE subtitle max 200 chars').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({
@@ -96,76 +98,334 @@ function authHeaders() {
         Authorization: `Bearer ${TOKEN}`,
     };
 }
-// ── MCP Server ─────────────────────────────────────────────────────────
-const server = new McpServer({
-    name: 'forkfeed',
-    version: '1.0.0',
-});
-// ── Tool: forkfeed_guide ───────────────────────────────────────────────
-server.tool('forkfeed_guide', 'Get the complete guide for generating forkfeed content from GitHub commits. Call this first to learn the format before generating content.', {}, async () => ({
-    content: [{ type: 'text', text: GUIDE_CONTENT }],
-}));
-// ── 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',
-        '',
-        '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.url}`),
-        '',
-        '## Background Images',
-        '',
-        ...bgs.map((i) => `${i.id} | ${i.name} | ${i.tags} | ${i.url}`),
-    ];
-    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
-        .object({
-        forks: z.array(z.any()),
-        feeds: z.array(z.any()),
-        cards: z.array(z.any()),
-    })
-        .describe('The complete manifest with forks, feeds, and cards arrays'),
-}, async ({ manifest }) => {
-    if (!TOKEN) {
+// ── Git helpers ───────────────────────────────────────────────────────
+async function gitExec(args, cwd) {
+    try {
+        const { stdout } = await execFileAsync('git', args, {
+            cwd,
+            maxBuffer: 5 * 1024 * 1024,
+            timeout: 15_000,
+        });
+        return stdout;
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === 'ENOENT')
+            throw new Error('git command not found. Ensure git is installed and in PATH.');
+        if (e.killed)
+            throw new Error('git command timed out after 15s.');
+        throw new Error(e.stderr?.trim() || e.message || 'git command failed');
+    }
+}
+async function isGitRepo(cwd) {
+    try {
+        await gitExec(['rev-parse', '--is-inside-work-tree'], cwd);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function getRepoInfo(cwd) {
+    try {
+        const url = (await gitExec(['remote', 'get-url', 'origin'], cwd)).trim();
+        const m = url.match(/github\.com[/:]([^/]+)\/([^/.]+)/);
+        if (m)
+            return { owner: m[1], repo: m[2], isLocal: false };
+    }
+    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${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(SEP);
+        return { sha, shortSha, message, author, date: date?.slice(0, 10) || '' };
+    });
+}
+function truncateDiff(diff, maxLinesPerFile = 200) {
+    const fileDiffs = diff.split(/^(?=diff --git )/m);
+    return fileDiffs.map((fd) => {
+        if (/^Binary files/.test(fd) || fd.includes('Binary files')) {
+            const path = fd.match(/diff --git a\/(.+?) b\//)?.[1] || 'unknown';
+            return `Binary file: ${path} (skipped)`;
+        }
+        const lines = fd.split('\n');
+        if (lines.length <= maxLinesPerFile)
+            return fd;
+        return lines.slice(0, maxLinesPerFile).join('\n') + `\n... [truncated, ${lines.length - maxLinesPerFile} more lines]`;
+    }).join('\n');
+}
+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(['diff', `${sha}^..${sha}`, '--stat'], cwd),
+        gitExec(['diff', `${sha}^..${sha}`, '-U3'], cwd),
+    ]);
+    const [fullSha, shortSha, message, author, date] = meta.trim().split('|');
+    return {
+        sha: fullSha,
+        shortSha,
+        message,
+        author,
+        date: date?.slice(0, 10) || '',
+        stats: stats.trim(),
+        diff: truncateDiff(diff),
+    };
+}
+const TAG_KEYWORDS = {
+    debug: ['fix', 'bug', 'patch', 'hotfix', 'error', 'crash', 'test', 'spec'],
+    deploy: ['deploy', 'release', 'ci', 'cd', 'docker', 'build', 'publish', 'pipeline'],
+    disaster: ['break', 'crash', 'fail', 'revert', 'rollback', 'incident', 'down'],
+    git: ['merge', 'conflict', 'branch', 'rebase', 'cherry-pick'],
+    hype: ['feat', 'feature', 'add', 'new', 'launch', 'ship', 'initial'],
+    victory: ['complete', 'finish', 'done', 'success', 'milestone'],
+    language: ['typescript', 'javascript', 'python', 'rust', 'go', 'java'],
+    general: ['refactor', 'clean', 'update', 'chore', 'docs', 'style'],
+    sarcastic: ['hack', 'workaround', 'todo', 'fixme', 'wtf'],
+    workplace: ['meeting', 'standup', 'review', 'sprint'],
+    lifestyle: ['config', 'setup', 'env', 'tooling'],
+};
+const PATH_TAGS = [
+    [/\.(test|spec)\.[jt]sx?$/, 'debug'],
+    [/\.github\/workflows|Dockerfile|docker|\.ci|Jenkinsfile/, 'deploy'],
+    [/\.env|config/, 'lifestyle'],
+];
+function detectTags(message, filePaths) {
+    const tags = new Set();
+    const lower = message.toLowerCase();
+    for (const [tag, keywords] of Object.entries(TAG_KEYWORDS)) {
+        if (keywords.some((kw) => lower.includes(kw)))
+            tags.add(tag);
+    }
+    for (const fp of filePaths) {
+        for (const [re, tag] of PATH_TAGS) {
+            if (re.test(fp))
+                tags.add(tag);
+        }
+    }
+    if (tags.size === 0)
+        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
+];
+function assignBackgrounds(_tags) {
+    const used = new Set();
+    return BG_PREFS.map((prefs) => {
+        const pick = prefs.find((bg) => !used.has(bg)) || prefs[0];
+        used.add(pick);
+        return pick;
+    });
+}
+function filterImagesByTags(tags) {
+    const tagSet = new Set(tags);
+    function score(entry) {
+        return entry.tags.split(',').map((t) => t.trim()).filter((t) => tagSet.has(t)).length;
+    }
+    const scenes = IMAGE_CATALOG
+        .filter((i) => i.id.startsWith('img'))
+        .map((i) => ({ ...i, score: score(i) }))
+        .sort((a, b) => b.score - a.score)
+        .slice(0, 30)
+        .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}`);
+    return { scenes, backgrounds };
+}
+async function fetchStatusData() {
+    const res = await fetch(`${APP_SERVER_URL}/api/content/status`, {
+        headers: authHeaders(),
+        signal: AbortSignal.timeout(10_000),
+    });
+    const data = await res.json();
+    if (!res.ok)
+        throw new Error(`Status check failed (${res.status}): ${data.error || JSON.stringify(data)}`);
+    return data;
+}
+// ── Cover titles (fixed per card index) ──────────────────────────────
+const COVERS = [
+    { title: "Explain Like I'm 5", subtitle: "Hopefully now you'll understand what you pushed" },
+    { title: "The Roast", subtitle: "Your code had it coming" },
+    { title: "Commit Message, Decoded", subtitle: "What you wrote vs what you meant vs what actually happened" },
+    { title: "The LinkedIn Post", subtitle: "Mass cringe, freshly generated" },
+    { title: "Statistics", subtitle: "The numbers don't lie, but they do judge" },
+    { title: "Learning Moment", subtitle: "Something useful buried in your chaos" },
+    { title: "Alternatives", subtitle: "What you could have done instead" },
+    { title: "Quiz", subtitle: "Let's see if you even understand your own code" },
+];
+// ── Simplified block inference ───────────────────────────────────────
+function inferBlock(block) {
+    if ('question' in block) {
         return {
-            content: [
-                {
-                    type: 'text',
-                    text: 'Error: FORKFEED_TOKEN not set. Get your API token from forkfeed.link/admin/user/token and add it to your .mcp.json env.',
-                },
-            ],
-            isError: true,
+            type: 'CONTENT_QUIZ',
+            question: block.question,
+            options: block.options,
+            ...(block.explanation != null ? { explanation: block.explanation } : {}),
         };
     }
-    // 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');
+    if ('name' in block && 'avatar' in block) {
+        const avatar = block.avatar;
         return {
-            content: [{ type: 'text', text: `Manifest validation failed:\n${issues}\n\nFix the issues above and try again.` }],
-            isError: true,
+            type: 'CONTENT_SOCIAL',
+            name: block.name,
+            avatarSrc: avatar.startsWith('http') ? avatar : resolveImageId(avatar),
+            source: block.source,
+            ...(block.subtitle != null ? { subtitle: block.subtitle } : {}),
         };
     }
-    const crossErr = crossValidate(parsed.data);
-    if (crossErr) {
+    if ('label' in block && 'action' in block && 'target' in block) {
         return {
-            content: [{ type: 'text', text: `Manifest cross-reference errors:\n${crossErr}\n\nFix the issues above and try again.` }],
+            type: 'CONTENT_BUTTON',
+            label: block.label,
+            action: block.action,
+            target: block.target,
+        };
+    }
+    if ('img' in block) {
+        return {
+            type: 'CONTENT_IMAGE',
+            imageSrc: resolveImageId(block.img),
+            sizing: (block.sizing || 'wide'),
+        };
+    }
+    if ('code' in block) {
+        return {
+            type: 'CONTENT_CODE',
+            code: block.code,
+            ...(block.lang != null ? { language: block.lang } : {}),
+        };
+    }
+    if ('subtext' in block) {
+        return { type: 'CONTENT_SUBTEXT', text: block.subtext };
+    }
+    if ('title' in block) {
+        return { type: 'CONTENT_TITLE', title: block.title };
+    }
+    if ('text' in block) {
+        return { type: 'CONTENT_TEXT', text: block.text };
+    }
+    throw new Error(`Cannot infer block type from fields: ${Object.keys(block).join(', ')}`);
+}
+// ── Build input schema ───────────────────────────────────────────────
+const buildInputSchema = z.object({
+    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),
+    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 ─────────────────────────────────────────────────
+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 = 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: [...existingFeedIds, feedId],
+        ...(actionUrl ? { actionLabel: 'View on GitHub', actionUrl } : {}),
+    };
+    const feed = {
+        _id: feedId,
+        title: input.feedTitle,
+        description: input.feedDescription,
+        imageSrc: coverUrls[0],
+        mode: 'sequential',
+        scrollDirection: 'vertical',
+        engagement: true,
+    };
+    const cards = input.cards.map((card, i) => {
+        const coverVariant = {
+            type: 'FULL_IMAGE',
+            imageSrc: coverUrls[i],
+            title: COVERS[i].title,
+            subtitle: COVERS[i].subtitle,
+        };
+        const detailVariants = card.variants.map((v) => ({
+            type: 'CONTENT',
+            backgroundSrc: bgUrls[i],
+            blocks: v.blocks.map((b) => inferBlock(b)),
+        }));
+        return {
+            _id: crypto.randomUUID(),
+            feedId,
+            order: i,
+            variants: [coverVariant, ...detailVariants],
+        };
+    });
+    return { forks: [fork], feeds: [feed], cards };
+}
+async function pushManifestToServer(manifest) {
+    if (!TOKEN) {
+        return {
+            content: [{ type: 'text', text: 'Error: FORKFEED_TOKEN not set. Get your API token from forkfeed.link/admin/user/token and add it to your .mcp.json env.' }],
             isError: true,
         };
     }
-    // Save manifest locally before uploading (best-effort, doesn't block push)
+    // Save manifest locally (best-effort)
     const forkId = manifest.forks?.[0]?._id;
     const filename = `${forkId || `manifest-${Date.now()}`}.json`;
     const dir = join(process.cwd(), 'forkfeed');
@@ -183,43 +443,31 @@ server.tool('forkfeed_push', 'Push a generated manifest (forks, feeds, cards) to
             method: 'POST',
             headers: authHeaders(),
             body: JSON.stringify({ manifest }),
+            signal: AbortSignal.timeout(15_000),
         });
         const data = await res.json();
         if (!res.ok) {
             return {
-                content: [
-                    {
-                        type: 'text',
-                        text: `Push failed (${res.status}): ${data.error || JSON.stringify(data)}`,
-                    },
-                ],
+                content: [{ type: 'text', text: `Push failed (${res.status}): ${data.error || JSON.stringify(data)}` }],
                 isError: true,
             };
         }
         const forkSummary = data.forks
             ?.map((f) => `  - ${f.title} (${f.feeds} feeds)`)
             .join('\n');
-        // Generate QR code for the first fork's deep link
         let qrBlock = '';
         if (forkId) {
             const url = `https://forkfeed.link/fork/${forkId}`;
             try {
                 const qr = await QRCode.toString(url, { type: 'utf8', errorCorrectionLevel: 'L' });
-                qrBlock = [
-                    '',
-                    'Scan to open in forkfeed:',
-                    '',
-                    qr,
-                    url,
-                ].join('\n');
+                qrBlock = ['', 'Scan to open in forkfeed:', '', qr, url].join('\n');
             }
             catch {
                 qrBlock = `\nLink: ${url}`;
             }
         }
         return {
-            content: [
-                {
+            content: [{
                     type: 'text',
                     text: [
                         'Content pushed successfully!',
@@ -235,21 +483,192 @@ server.tool('forkfeed_push', 'Push a generated manifest (forks, feeds, cards) to
                         'To make it public, change visibility in the app (requires admin approval).',
                         qrBlock,
                     ].join('\n'),
-                },
-            ],
+                }],
         };
     }
     catch (err) {
         return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Push failed: ${err instanceof Error ? err.message : String(err)}`,
-                },
-            ],
+            content: [{ type: 'text', text: `Push failed: ${err instanceof Error ? err.message : String(err)}` }],
+            isError: true,
+        };
+    }
+}
+// ── MCP Server ─────────────────────────────────────────────────────────
+const server = new McpServer({
+    name: 'forkfeed',
+    version: '1.0.0',
+});
+// ── Tool: forkfeed_guide ───────────────────────────────────────────────
+server.tool('forkfeed_guide', 'Get the complete guide for generating forkfeed content from GitHub commits. Call this first to learn the format before generating content.', {}, async () => ({
+    content: [{ type: 'text', text: GUIDE_CONTENT }],
+}));
+// ── Tool: forkfeed_commits ─────────────────────────────────────────────
+server.tool('forkfeed_commits', 'Read git commits from the current repo. Without sha: lists recent commits with published status. With sha: returns structured commit details + pre-filtered images for content generation.', {
+    sha: z.string().optional().describe('Full or short SHA to analyze in detail. Omit to list recent commits.'),
+    cwd: z.string().optional().describe('Working directory. Defaults to process.cwd().'),
+}, async ({ sha, cwd: inputCwd }) => {
+    const cwd = inputCwd || process.cwd();
+    if (!(await isGitRepo(cwd))) {
+        return { content: [{ type: 'text', text: 'Not in a git repo. Navigate to a git repository first.' }], isError: true };
+    }
+    const repoInfo = await getRepoInfo(cwd);
+    const repoLabel = repoInfo.owner ? `${repoInfo.owner}/${repoInfo.repo}` : `local/${repoInfo.repo}`;
+    // ── List mode ──
+    if (!sha) {
+        let commits;
+        try {
+            commits = await getCommitList(cwd);
+        }
+        catch (err) {
+            return { content: [{ type: 'text', text: `Failed to read git log: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+        }
+        if (commits.length === 0) {
+            return { content: [{ type: 'text', text: 'No commits found in this repository.' }] };
+        }
+        // Fetch published status (best-effort)
+        let publishedShas = new Set();
+        let existingFeedIds = [];
+        let statusWarning = '';
+        if (TOKEN) {
+            try {
+                const status = await fetchStatusData();
+                existingFeedIds = (status.feeds || []).map((f) => f.externalFeedId);
+                for (const feedId of existingFeedIds) {
+                    const parts = feedId.split('-');
+                    const feedSha = parts[parts.length - 1];
+                    if (feedSha)
+                        publishedShas.add(feedSha);
+                }
+            }
+            catch {
+                statusWarning = '\nNote: could not check published status (network error or token issue).';
+            }
+        }
+        const lines = [
+            `Repo: ${repoLabel}`,
+            '',
+            '| # | SHA | Message | Author | Date | Published |',
+            '|---|-----|---------|--------|------|-----------|',
+        ];
+        for (let i = 0; i < commits.length; i++) {
+            const c = commits[i];
+            const pub = publishedShas.has(c.shortSha) ? 'yes' : '';
+            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(', ')}`);
+        }
+        if (statusWarning)
+            lines.push(statusWarning);
+        return { content: [{ type: 'text', text: lines.join('\n') }] };
+    }
+    // ── Detail mode ──
+    let detail;
+    try {
+        detail = await getCommitDetail(cwd, sha);
+    }
+    catch (err) {
+        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 tags = detectTags(detail.message, filePaths);
+    const images = filterImagesByTags(tags);
+    const lines = [
+        `## Commit: ${detail.shortSha} - ${detail.message}`,
+        `Author: ${detail.author} | Date: ${detail.date}`,
+        `Repo: ${repoLabel}`,
+        repoInfo.owner ? `GitHub: https://github.com/${repoInfo.owner}/${repoInfo.repo}` : '',
+        '',
+        '## File Stats',
+        detail.stats,
+        '',
+        '## Diff',
+        detail.diff,
+        '',
+        `## Suggested Images (tags: ${tags.join(', ')})`,
+        '',
+        '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_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
+        .object({
+        forks: z.array(z.any()),
+        feeds: z.array(z.any()),
+        cards: z.array(z.any()),
+    })
+        .describe('The complete manifest with forks, feeds, and cards arrays'),
+}, async ({ manifest }) => {
+    // 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,
+        };
+    }
+    return pushManifestToServer(parsed.data);
+});
+// ── Tool: forkfeed_build ──────────────────────────────────────────────
+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 = await buildManifest(content);
+    }
+    catch (err) {
+        return {
+            content: [{ type: 'text', text: `Build failed: ${err instanceof Error ? err.message : String(err)}` }],
+            isError: true,
+        };
+    }
+    // Validate the assembled manifest
+    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: `Built manifest failed validation:\n${issues}` }],
+            isError: true,
+        };
+    }
+    const crossErr = crossValidate(parsed.data);
+    if (crossErr) {
+        return {
+            content: [{ type: 'text', text: `Built manifest cross-reference errors:\n${crossErr}` }],
             isError: true,
         };
     }
+    if (shouldPush) {
+        return pushManifestToServer(parsed.data);
+    }
+    // Return the manifest for review
+    return {
+        content: [{ type: 'text', text: `Manifest built successfully (${manifest.cards.length} cards). Review below, then call forkfeed_push to publish.\n\n${JSON.stringify(manifest, null, 2)}` }],
+    };
 });
 // ── Tool: forkfeed_status ──────────────────────────────────────────────
 server.tool('forkfeed_status', 'Check your current forkfeed content: which forks and feeds you have published.', {}, async () => {
@@ -265,27 +684,13 @@ server.tool('forkfeed_status', 'Check your current forkfeed content: which forks
         };
     }
     try {
-        const res = await fetch(`${APP_SERVER_URL}/api/content/status`, {
-            headers: authHeaders(),
-        });
-        const data = await res.json();
-        if (!res.ok) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: `Status check failed (${res.status}): ${data.error || JSON.stringify(data)}`,
-                    },
-                ],
-                isError: true,
-            };
-        }
+        const data = await fetchStatusData();
         if (!data.forks?.length) {
             return {
                 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.',
                     },
                 ],
             };
@@ -327,13 +732,13 @@ 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**, **forkfeed_images**, and **forkfeed_status** to load the guide, image catalog, and existing content.
-2. 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.
-3. Fetch the commit diff and stats via git.
-4. Generate the complete manifest JSON directly. Do NOT use any scripts, tools, or commands to generate UUIDs or content. Generate everything (card UUIDs, all text, all JSON) purely in your response. Include ALL existing feed IDs in the fork's feedIds array (see "Incremental updates" in guide). Output the full manifest as a single JSON block.
-5. Call **forkfeed_push** with the complete manifest.
+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. 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. Load the guide, images, and status, then detect the repo.`,
+Start now.`,
             },
         },
     ],