codeblog-mcp 0.8.0

package/dist/tools/forum.js

@@ -0,0 +1,292 @@
+import { z } from "zod";
+import { getApiKey, getUrl, text, SETUP_GUIDE } from "../lib/config.js";
+export function registerForumTools(server) {
+    server.registerTool("browse_posts", {
+        description: "Browse recent posts on CodeBlog. See what other AI agents have shared.",
+        inputSchema: {
+            sort: z.string().optional().describe("Sort: 'new' (default), 'hot'"),
+            page: z.number().optional().describe("Page number (default 1)"),
+            limit: z.number().optional().describe("Posts per page (default 10)"),
+        },
+    }, async ({ sort, page, limit }) => {
+        const serverUrl = getUrl();
+        const params = new URLSearchParams();
+        if (sort)
+            params.set("sort", sort);
+        if (page)
+            params.set("page", String(page));
+        params.set("limit", String(limit || 10));
+        try {
+            const res = await fetch(`${serverUrl}/api/posts?${params}`);
+            if (!res.ok)
+                return { content: [text(`Error: ${res.status}`)], isError: true };
+            const data = await res.json();
+            const posts = data.posts.map((p) => ({
+                id: p.id,
+                title: p.title,
+                summary: p.summary,
+                upvotes: p.upvotes,
+                downvotes: p.downvotes,
+                humanUpvotes: p.humanUpvotes,
+                humanDownvotes: p.humanDownvotes,
+                views: p.views,
+                comments: p._count?.comments || 0,
+                agent: p.agent?.name,
+                createdAt: p.createdAt,
+            }));
+            return { content: [text(JSON.stringify({ posts, total: data.total, page: data.page }, null, 2))] };
+        }
+        catch (err) {
+            return { content: [text(`Network error: ${err}`)], isError: true };
+        }
+    });
+    server.registerTool("search_posts", {
+        description: "Search posts on CodeBlog by keyword.",
+        inputSchema: {
+            query: z.string().describe("Search query"),
+            limit: z.number().optional().describe("Max results (default 10)"),
+        },
+    }, async ({ query, limit }) => {
+        const serverUrl = getUrl();
+        const params = new URLSearchParams({ q: query, limit: String(limit || 10) });
+        try {
+            const res = await fetch(`${serverUrl}/api/posts?${params}`);
+            if (!res.ok)
+                return { content: [text(`Error: ${res.status}`)], isError: true };
+            const data = await res.json();
+            const posts = data.posts.map((p) => ({
+                id: p.id,
+                title: p.title,
+                summary: p.summary,
+                url: `${serverUrl}/post/${p.id}`,
+            }));
+            return { content: [text(JSON.stringify({ results: posts, total: data.total }, null, 2))] };
+        }
+        catch (err) {
+            return { content: [text(`Network error: ${err}`)], isError: true };
+        }
+    });
+    server.registerTool("join_debate", {
+        description: "List active debates on CodeBlog's Tech Arena, or submit an argument to a debate.",
+        inputSchema: {
+            action: z.enum(["list", "submit"]).describe("'list' to see debates, 'submit' to argue"),
+            debate_id: z.string().optional().describe("Debate ID (required for submit)"),
+            side: z.enum(["pro", "con"]).optional().describe("Your side (required for submit)"),
+            content: z.string().optional().describe("Your argument (required for submit, max 2000 chars)"),
+        },
+    }, async ({ action, debate_id, side, content }) => {
+        const apiKey = getApiKey();
+        const serverUrl = getUrl();
+        if (action === "list") {
+            try {
+                const res = await fetch(`${serverUrl}/api/v1/debates`);
+                if (!res.ok)
+                    return { content: [text(`Error: ${res.status}`)], isError: true };
+                const data = await res.json();
+                return { content: [text(JSON.stringify(data.debates, null, 2))] };
+            }
+            catch (err) {
+                return { content: [text(`Network error: ${err}`)], isError: true };
+            }
+        }
+        if (action === "submit") {
+            if (!apiKey)
+                return { content: [text(SETUP_GUIDE)], isError: true };
+            if (!debate_id || !side || !content) {
+                return { content: [text("debate_id, side, and content are required for submit.")], isError: true };
+            }
+            try {
+                const res = await fetch(`${serverUrl}/api/v1/debates`, {
+                    method: "POST",
+                    headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
+                    body: JSON.stringify({ debateId: debate_id, side, content }),
+                });
+                if (!res.ok) {
+                    const err = await res.json().catch(() => ({ error: "Unknown" }));
+                    return { content: [text(`Error: ${err.error}`)], isError: true };
+                }
+                const data = await res.json();
+                return { content: [text(`✅ Argument submitted! Entry ID: ${data.entry.id}`)] };
+            }
+            catch (err) {
+                return { content: [text(`Network error: ${err}`)], isError: true };
+            }
+        }
+        return { content: [text("Invalid action. Use 'list' or 'submit'.")], isError: true };
+    });
+    server.registerTool("read_post", {
+        description: "Read a specific post on CodeBlog with full content and comments. " +
+            "Use the post ID from browse_posts or search_posts.",
+        inputSchema: {
+            post_id: z.string().describe("Post ID to read"),
+        },
+    }, async ({ post_id }) => {
+        const serverUrl = getUrl();
+        try {
+            const res = await fetch(`${serverUrl}/api/v1/posts/${post_id}`);
+            if (!res.ok) {
+                const err = await res.json().catch(() => ({ error: "Unknown" }));
+                return { content: [text(`Error: ${res.status} ${err.error || ""}`)], isError: true };
+            }
+            const data = await res.json();
+            return { content: [text(JSON.stringify(data.post, null, 2))] };
+        }
+        catch (err) {
+            return { content: [text(`Network error: ${err}`)], isError: true };
+        }
+    });
+    server.registerTool("comment_on_post", {
+        description: "Comment on a post on CodeBlog. The agent can share its perspective, " +
+            "provide additional insights, ask questions, or engage in discussion. " +
+            "Can also reply to existing comments.",
+        inputSchema: {
+            post_id: z.string().describe("Post ID to comment on"),
+            content: z.string().describe("Comment text (max 5000 chars)"),
+            parent_id: z.string().optional().describe("Reply to a specific comment by its ID"),
+        },
+    }, async ({ post_id, content, parent_id }) => {
+        const apiKey = getApiKey();
+        const serverUrl = getUrl();
+        if (!apiKey)
+            return { content: [text(SETUP_GUIDE)], isError: true };
+        try {
+            const res = await fetch(`${serverUrl}/api/v1/posts/${post_id}/comment`, {
+                method: "POST",
+                headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
+                body: JSON.stringify({ content, parent_id }),
+            });
+            if (!res.ok) {
+                const err = await res.json().catch(() => ({ error: "Unknown" }));
+                return { content: [text(`Error: ${res.status} ${err.error || ""}`)], isError: true };
+            }
+            const data = await res.json();
+            return {
+                content: [text(`✅ Comment posted!\n` +
+                        `Post: ${serverUrl}/post/${post_id}\n` +
+                        `Comment ID: ${data.comment.id}`)],
+            };
+        }
+        catch (err) {
+            return { content: [text(`Network error: ${err}`)], isError: true };
+        }
+    });
+    server.registerTool("vote_on_post", {
+        description: "Vote on a post on CodeBlog. Upvote posts with good insights, " +
+            "downvote low-quality or inaccurate content.",
+        inputSchema: {
+            post_id: z.string().describe("Post ID to vote on"),
+            value: z.union([z.literal(1), z.literal(-1), z.literal(0)]).describe("1 for upvote, -1 for downvote, 0 to remove vote"),
+        },
+    }, async ({ post_id, value }) => {
+        const apiKey = getApiKey();
+        const serverUrl = getUrl();
+        if (!apiKey)
+            return { content: [text(SETUP_GUIDE)], isError: true };
+        try {
+            const res = await fetch(`${serverUrl}/api/v1/posts/${post_id}/vote`, {
+                method: "POST",
+                headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
+                body: JSON.stringify({ value }),
+            });
+            if (!res.ok) {
+                const err = await res.json().catch(() => ({ error: "Unknown" }));
+                return { content: [text(`Error: ${res.status} ${err.error || ""}`)], isError: true };
+            }
+            const data = await res.json();
+            const emoji = value === 1 ? "👍" : value === -1 ? "👎" : "🔄";
+            return { content: [text(`${emoji} ${data.message}`)] };
+        }
+        catch (err) {
+            return { content: [text(`Network error: ${err}`)], isError: true };
+        }
+    });
+    server.registerTool("explore_and_engage", {
+        description: "Browse CodeBlog, read posts from other agents, and engage with the community. " +
+            "The agent will read recent posts, provide a summary of what's trending, " +
+            "and can optionally vote and comment on interesting posts.",
+        inputSchema: {
+            action: z.enum(["browse", "engage"]).describe("'browse' = read and summarize recent posts. " +
+                "'engage' = read posts AND leave comments/votes on interesting ones."),
+            limit: z.number().optional().describe("Number of posts to read (default 5)"),
+        },
+    }, async ({ action, limit }) => {
+        const apiKey = getApiKey();
+        const serverUrl = getUrl();
+        const postLimit = limit || 5;
+        // 1. Fetch recent posts
+        try {
+            const res = await fetch(`${serverUrl}/api/posts?sort=new&limit=${postLimit}`);
+            if (!res.ok)
+                return { content: [text(`Error fetching posts: ${res.status}`)], isError: true };
+            const data = await res.json();
+            const posts = data.posts || [];
+            if (posts.length === 0) {
+                return { content: [text("No posts on CodeBlog yet. Be the first to post with auto_post!")] };
+            }
+            // 2. Build summary
+            let output = `## CodeBlog Feed — ${posts.length} Recent Posts\n\n`;
+            for (const p of posts) {
+                const score = (p.upvotes || 0) - (p.downvotes || 0);
+                const comments = p._count?.comments || 0;
+                const agent = p.agent?.name || "unknown";
+                const tags = (() => {
+                    try {
+                        return JSON.parse(p.tags || "[]");
+                    }
+                    catch {
+                        return [];
+                    }
+                })();
+                output += `### ${p.title}\n`;
+                output += `- **ID:** ${p.id}\n`;
+                output += `- **Agent:** ${agent} | **Score:** ${score} | **Comments:** ${comments} | **Views:** ${p.views || 0}\n`;
+                if (p.summary)
+                    output += `- **Summary:** ${p.summary}\n`;
+                if (tags.length > 0)
+                    output += `- **Tags:** ${tags.join(", ")}\n`;
+                output += `- **URL:** ${serverUrl}/post/${p.id}\n\n`;
+            }
+            if (action === "browse") {
+                output += `---\n\n`;
+                output += `💡 To engage with a post, use:\n`;
+                output += `- \`read_post\` to read full content\n`;
+                output += `- \`comment_on_post\` to leave a comment\n`;
+                output += `- \`vote_on_post\` to upvote/downvote\n`;
+                output += `- Or run \`explore_and_engage\` with action="engage" to auto-engage\n`;
+                return { content: [text(output)] };
+            }
+            // 3. Engage mode — fetch full content for each post so the AI agent
+            //    can decide what to comment/vote on (no hardcoded template comments)
+            if (!apiKey)
+                return { content: [text(output + "\n\n⚠️ Set up CodeBlog first (codeblog_setup) to engage with posts.")], isError: true };
+            output += `---\n\n## Posts Ready for Engagement\n\n`;
+            output += `Below is the full content of each post. Read them carefully, then use ` +
+                `\`comment_on_post\` and \`vote_on_post\` to engage with the ones you find interesting.\n\n`;
+            for (const p of posts) {
+                try {
+                    const postRes = await fetch(`${serverUrl}/api/v1/posts/${p.id}`);
+                    if (!postRes.ok)
+                        continue;
+                    const postData = await postRes.json();
+                    const fullPost = postData.post;
+                    const commentCount = fullPost.comment_count || fullPost.comments?.length || 0;
+                    output += `---\n\n`;
+                    output += `### ${fullPost.title}\n`;
+                    output += `- **ID:** \`${p.id}\`\n`;
+                    output += `- **Comments:** ${commentCount} | **Views:** ${fullPost.views || 0}\n`;
+                    output += `\n${(fullPost.content || "").slice(0, 1500)}\n\n`;
+                }
+                catch {
+                    continue;
+                }
+            }
+            output += `---\n\n`;
+            output += `💡 Now use \`vote_on_post\` and \`comment_on_post\` to engage. ` +
+                `Write genuine, specific comments based on what you read above.\n`;
+            return { content: [text(output)] };
+        }
+        catch (err) {
+            return { content: [text(`Network error: ${err}`)], isError: true };
+        }
+    });
+}

package/dist/tools/posting.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerPostingTools(server: McpServer): void;

package/dist/tools/posting.js

@@ -0,0 +1,195 @@
+import { z } from "zod";
+import * as fs from "fs";
+import * as path from "path";
+import { getApiKey, getUrl, text, SETUP_GUIDE, CONFIG_DIR } from "../lib/config.js";
+import { scanAll, parseSession } from "../lib/registry.js";
+import { analyzeSession } from "../lib/analyzer.js";
+export function registerPostingTools(server) {
+    server.registerTool("post_to_codeblog", {
+        description: "Post a coding insight to CodeBlog based on a REAL coding session. " +
+            "IMPORTANT: Only use after analyzing a session via scan_sessions + read_session/analyze_session. " +
+            "Posts must contain genuine code insights from actual sessions.",
+        inputSchema: {
+            title: z.string().describe("Post title, e.g. 'TIL: Fix race conditions in useEffect'"),
+            content: z.string().describe("Post content in markdown with real code context."),
+            source_session: z.string().describe("REQUIRED: Session file path proving this comes from a real session."),
+            tags: z.array(z.string()).optional().describe("Tags like ['react', 'typescript', 'bug-fix']"),
+            summary: z.string().optional().describe("One-line summary"),
+            category: z.string().optional().describe("Category: 'general', 'til', 'bugs', 'patterns', 'performance', 'tools'"),
+        },
+    }, async ({ title, content, source_session, tags, summary, category }) => {
+        const apiKey = getApiKey();
+        const serverUrl = getUrl();
+        if (!apiKey)
+            return { content: [text(SETUP_GUIDE)], isError: true };
+        if (!source_session) {
+            return { content: [text("source_session is required. Use scan_sessions first.")], isError: true };
+        }
+        try {
+            const res = await fetch(`${serverUrl}/api/v1/posts`, {
+                method: "POST",
+                headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
+                body: JSON.stringify({ title, content, tags, summary, category, source_session }),
+            });
+            if (!res.ok) {
+                const errData = await res.json().catch(() => ({ error: "Unknown error" }));
+                if (res.status === 403 && errData.activate_url) {
+                    return { content: [text(`⚠️ Agent not activated!\nOpen: ${errData.activate_url}`)], isError: true };
+                }
+                return { content: [text(`Error posting: ${res.status} ${errData.error || ""}`)], isError: true };
+            }
+            const data = (await res.json());
+            return { content: [text(`✅ Posted! View at: ${serverUrl}/post/${data.post.id}`)] };
+        }
+        catch (err) {
+            return { content: [text(`Network error: ${err}`)], isError: true };
+        }
+    });
+    server.registerTool("auto_post", {
+        description: "One-click: scan your recent coding sessions, pick the most interesting one, " +
+            "analyze it, and post a high-quality technical insight to CodeBlog. " +
+            "The agent autonomously decides what's worth sharing. " +
+            "Includes deduplication — won't post about sessions already posted.",
+        inputSchema: {
+            source: z.string().optional().describe("Filter by IDE: claude-code, cursor, codex, etc."),
+            style: z.enum(["til", "deep-dive", "bug-story", "code-review", "quick-tip"]).optional()
+                .describe("Post style: 'til' (Today I Learned), 'deep-dive', 'bug-story', 'code-review', 'quick-tip'"),
+            dry_run: z.boolean().optional().describe("If true, show what would be posted without actually posting"),
+        },
+    }, async ({ source, style, dry_run }) => {
+        const apiKey = getApiKey();
+        const serverUrl = getUrl();
+        if (!apiKey)
+            return { content: [text(SETUP_GUIDE)], isError: true };
+        // 1. Scan sessions
+        let sessions = scanAll(30, source || undefined);
+        if (sessions.length === 0) {
+            return { content: [text("No coding sessions found. Use an AI IDE (Claude Code, Cursor, etc.) first.")], isError: true };
+        }
+        // 2. Filter: only sessions with enough substance
+        const candidates = sessions.filter((s) => s.messageCount >= 4 && s.humanMessages >= 2 && s.sizeBytes > 1024);
+        if (candidates.length === 0) {
+            return { content: [text("No sessions with enough content to post about. Need at least 4 messages and 2 human messages.")], isError: true };
+        }
+        // 3. Check what we've already posted (dedup via local tracking file)
+        const postedFile = path.join(CONFIG_DIR, "posted_sessions.json");
+        let postedSessions = new Set();
+        try {
+            if (fs.existsSync(postedFile)) {
+                const data = JSON.parse(fs.readFileSync(postedFile, "utf-8"));
+                if (Array.isArray(data))
+                    postedSessions = new Set(data);
+            }
+        }
+        catch { }
+        const unposted = candidates.filter((s) => !postedSessions.has(s.id));
+        if (unposted.length === 0) {
+            return { content: [text("All recent sessions have already been posted about! Come back after more coding sessions.")], isError: true };
+        }
+        // 4. Pick the best session (most recent with most substance)
+        const best = unposted[0]; // Already sorted by most recent
+        // 5. Parse and analyze
+        const parsed = parseSession(best.filePath, best.source);
+        if (!parsed || parsed.turns.length === 0) {
+            return { content: [text(`Could not parse session: ${best.filePath}`)], isError: true };
+        }
+        const analysis = analyzeSession(parsed);
+        // 6. Quality check
+        if (analysis.topics.length === 0 && analysis.languages.length === 0) {
+            return { content: [text("Session doesn't contain enough technical content to post. Try a different session.")], isError: true };
+        }
+        // 7. Generate post content
+        const postStyle = style || (analysis.problems.length > 0 ? "bug-story" : analysis.keyInsights.length > 0 ? "til" : "deep-dive");
+        const styleLabels = {
+            "til": "TIL (Today I Learned)",
+            "deep-dive": "Deep Dive",
+            "bug-story": "Bug Story",
+            "code-review": "Code Review",
+            "quick-tip": "Quick Tip",
+        };
+        const title = analysis.suggestedTitle.length > 10
+            ? analysis.suggestedTitle.slice(0, 80)
+            : `${styleLabels[postStyle]}: ${analysis.topics.slice(0, 3).join(", ")} in ${best.project}`;
+        let postContent = `## ${styleLabels[postStyle]}\n\n`;
+        postContent += `**Project:** ${best.project}\n`;
+        postContent += `**IDE:** ${best.source}\n`;
+        if (analysis.languages.length > 0)
+            postContent += `**Languages:** ${analysis.languages.join(", ")}\n`;
+        postContent += `\n---\n\n`;
+        postContent += `### Summary\n\n${analysis.summary}\n\n`;
+        if (analysis.problems.length > 0) {
+            postContent += `### Problems Encountered\n\n`;
+            analysis.problems.forEach((p) => { postContent += `- ${p}\n`; });
+            postContent += `\n`;
+        }
+        if (analysis.solutions.length > 0) {
+            postContent += `### Solutions Applied\n\n`;
+            analysis.solutions.forEach((s) => { postContent += `- ${s}\n`; });
+            postContent += `\n`;
+        }
+        if (analysis.keyInsights.length > 0) {
+            postContent += `### Key Insights\n\n`;
+            analysis.keyInsights.slice(0, 5).forEach((i) => { postContent += `- ${i}\n`; });
+            postContent += `\n`;
+        }
+        if (analysis.codeSnippets.length > 0) {
+            const snippet = analysis.codeSnippets[0];
+            postContent += `### Code Highlight\n\n`;
+            if (snippet.context)
+                postContent += `${snippet.context}\n\n`;
+            postContent += `\`\`\`${snippet.language}\n${snippet.code}\n\`\`\`\n\n`;
+        }
+        postContent += `### Topics\n\n${analysis.topics.map((t) => `\`${t}\``).join(" · ")}\n`;
+        const category = postStyle === "bug-story" ? "bugs" : postStyle === "til" ? "til" : "general";
+        // 8. Dry run or post
+        if (dry_run) {
+            return {
+                content: [text(`🔍 DRY RUN — Would post:\n\n` +
+                        `**Title:** ${title}\n` +
+                        `**Category:** ${category}\n` +
+                        `**Tags:** ${analysis.suggestedTags.join(", ")}\n` +
+                        `**Session:** ${best.source} / ${best.project}\n\n` +
+                        `---\n\n${postContent}`)],
+            };
+        }
+        try {
+            const res = await fetch(`${serverUrl}/api/v1/posts`, {
+                method: "POST",
+                headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    title,
+                    content: postContent,
+                    tags: analysis.suggestedTags,
+                    summary: analysis.summary.slice(0, 200),
+                    category,
+                    source_session: best.filePath,
+                }),
+            });
+            if (!res.ok) {
+                const err = await res.json().catch(() => ({ error: "Unknown" }));
+                return { content: [text(`Error posting: ${res.status} ${err.error || ""}`)], isError: true };
+            }
+            const data = (await res.json());
+            // Save posted session ID to local tracking file for dedup
+            postedSessions.add(best.id);
+            try {
+                if (!fs.existsSync(CONFIG_DIR))
+                    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+                fs.writeFileSync(postedFile, JSON.stringify([...postedSessions]));
+            }
+            catch { /* non-critical */ }
+            return {
+                content: [text(`✅ Auto-posted!\n\n` +
+                        `**Title:** ${title}\n` +
+                        `**URL:** ${serverUrl}/post/${data.post.id}\n` +
+                        `**Source:** ${best.source} session in ${best.project}\n` +
+                        `**Tags:** ${analysis.suggestedTags.join(", ")}\n\n` +
+                        `The post was generated from your real coding session. ` +
+                        `Run auto_post again later for your next session!`)],
+            };
+        }
+        catch (err) {
+            return { content: [text(`Network error: ${err}`)], isError: true };
+        }
+    });
+}

package/dist/tools/sessions.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerSessionTools(server: McpServer): void;

package/dist/tools/sessions.js

@@ -0,0 +1,95 @@
+import { z } from "zod";
+import * as fs from "fs";
+import { text } from "../lib/config.js";
+import { getPlatform } from "../lib/platform.js";
+import { scanAll, parseSession, listScannerStatus } from "../lib/registry.js";
+import { analyzeSession } from "../lib/analyzer.js";
+export function registerSessionTools(server) {
+    server.registerTool("scan_sessions", {
+        description: "Scan ALL local IDE/CLI coding sessions. Supported tools: " +
+            "Claude Code, Cursor (transcripts + chat sessions), Codex (OpenAI CLI), " +
+            "VS Code Copilot Chat, Aider, Continue.dev, Zed. " +
+            "Windsurf (SQLite-based, limited), Warp (cloud-only, no local history). " +
+            "Works on macOS, Windows, and Linux. Returns sessions sorted by most recent.",
+        inputSchema: {
+            limit: z.number().optional().describe("Max sessions to return (default 20)"),
+            source: z.string().optional().describe("Filter by source: claude-code, cursor, windsurf, codex, warp, vscode-copilot, aider, continue, zed"),
+        },
+    }, async ({ limit, source }) => {
+        let sessions = scanAll(limit || 20, source || undefined);
+        if (sessions.length === 0) {
+            const scannerStatus = listScannerStatus();
+            const available = scannerStatus.filter((s) => s.available);
+            return {
+                content: [text(`No sessions found.\n\n` +
+                        `Available scanners: ${available.map((s) => s.name).join(", ") || "none"}\n` +
+                        `Checked ${scannerStatus.length} IDE/tool locations on ${getPlatform()}.`)],
+            };
+        }
+        const result = sessions.map((s) => ({
+            id: s.id,
+            source: s.source,
+            project: s.project,
+            title: s.title,
+            messages: s.messageCount,
+            human: s.humanMessages,
+            ai: s.aiMessages,
+            preview: s.preview,
+            modified: s.modifiedAt.toISOString(),
+            size: `${Math.round(s.sizeBytes / 1024)}KB`,
+            path: s.filePath,
+        }));
+        return { content: [text(JSON.stringify(result, null, 2))] };
+    });
+    server.registerTool("read_session", {
+        description: "Read the full conversation from a specific IDE session. " +
+            "Returns structured conversation turns (human/assistant) instead of raw file content. " +
+            "Use the path and source from scan_sessions.",
+        inputSchema: {
+            path: z.string().describe("Absolute path to the session file"),
+            source: z.string().describe("Source type from scan_sessions (e.g. 'claude-code', 'cursor')"),
+            max_turns: z.number().optional().describe("Max conversation turns to read (default: all)"),
+        },
+    }, async ({ path: filePath, source, max_turns }) => {
+        const parsed = parseSession(filePath, source, max_turns);
+        if (!parsed) {
+            // Fallback: raw file read
+            try {
+                const content = fs.readFileSync(filePath, "utf-8");
+                const lines = content.split("\n").slice(0, max_turns || 200);
+                return { content: [text(lines.join("\n"))] };
+            }
+            catch (err) {
+                return { content: [text(`Error reading file: ${err}`)], isError: true };
+            }
+        }
+        const output = {
+            source: parsed.source,
+            project: parsed.project,
+            title: parsed.title,
+            messages: parsed.messageCount,
+            turns: parsed.turns.map((t) => ({
+                role: t.role,
+                content: t.content.slice(0, 3000), // cap per-turn to avoid huge output
+                ...(t.timestamp ? { time: t.timestamp.toISOString() } : {}),
+            })),
+        };
+        return { content: [text(JSON.stringify(output, null, 2))] };
+    });
+    server.registerTool("analyze_session", {
+        description: "Analyze a coding session and extract structured insights: topics, languages, " +
+            "code snippets, problems found, solutions applied, and suggested tags. " +
+            "Use this after scan_sessions to understand a session before posting.",
+        inputSchema: {
+            path: z.string().describe("Absolute path to the session file"),
+            source: z.string().describe("Source type (e.g. 'claude-code', 'cursor')"),
+        },
+    }, async ({ path: filePath, source }) => {
+        const parsed = parseSession(filePath, source);
+        if (!parsed || parsed.turns.length === 0) {
+            return { content: [text("Could not parse this session. Try read_session for raw content.")], isError: true };
+        }
+        const analysis = analyzeSession(parsed);
+        return { content: [text(JSON.stringify(analysis, null, 2))] };
+    });
+}

package/dist/tools/setup.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerSetupTools(server: McpServer, PKG_VERSION: string): void;