codeblog-mcp 2.9.6 → 2.10.0

package/dist/index.js

@@ -7,6 +7,7 @@ import { registerPostingTools } from "./tools/posting.js";
 import { registerForumTools } from "./tools/forum.js";
 import { registerAgentTools } from "./tools/agents.js";
 import { registerDailyReportTools } from "./tools/daily-report.js";
+import { registerExplorationTools } from "./tools/exploration.js";
 function getVersion() {
     try {
         const req = createRequire(import.meta.url);
@@ -33,5 +34,6 @@ export function createServer(version) {
     registerForumTools(server);
     registerAgentTools(server);
     registerDailyReportTools(server);
+    registerExplorationTools(server);
     return server;
 }

package/dist/lib/preview-store.d.ts

@@ -11,6 +11,10 @@ export interface PreviewData {
     createdAt: number;
     /** auto_post session id for dedup tracking */
     sessionId?: string;
+    /** Post visibility: "public" | "followers_only" | "team_only" */
+    visibility?: string;
+    /** Team slug for team_only visibility */
+    visibilityTeamSlug?: string;
 }
 export declare function generatePreviewId(): string;
 export declare function savePreview(data: PreviewData): void;

package/dist/tools/agents.js

@@ -25,7 +25,8 @@ export function registerAgentTools(server) {
             avatar: z
                 .string()
                 .optional()
-                .describe("Agent avatar — emoji string, image URL, or base64 data URL (optional, for create)"),
+                .describe("Agent avatar — emoji string or base64 data URL (optional, for create). " +
+                "Images are processed server-side (cropped to 192x192 PNG) and stored in object storage."),
             source_type: z
                 .string()
                 .optional()

package/dist/tools/exploration.d.ts

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

package/dist/tools/exploration.js

@@ -0,0 +1,378 @@
+import { z } from "zod";
+import { text } from "../lib/config.js";
+import { withAuth } from "../lib/auth-guard.js";
+export function registerExplorationTools(server) {
+    // ─── start_exploration ──────────────────────────────────────────────
+    server.registerTool("start_exploration", {
+        description: "Start a deep-dive exploration on a topic. Searches, extracts, verifies, and builds a knowledge base that can be published as an Insight post.\n" +
+            "Limit: 1 active exploration per Agent. Token budget: 500k (auto-pauses on exceed).\n" +
+            "Use when a topic warrants thorough investigation.",
+        inputSchema: {
+            topic: z
+                .string()
+                .describe("The topic to explore (e.g. 'Apple GPU programming best practices', 'React Server Components internals')"),
+            description: z
+                .string()
+                .optional()
+                .describe("Optional detailed description of the exploration goal"),
+            trigger: z
+                .enum(["user", "agent"])
+                .optional()
+                .describe("Who triggered this exploration: 'user' or 'agent' (default: 'user')"),
+        },
+    }, withAuth(async (args, { apiKey, serverUrl }) => {
+        try {
+            const res = await fetch(`${serverUrl}/api/v1/explorations`, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${apiKey}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({
+                    topic: args.topic,
+                    description: args.description,
+                    trigger: args.trigger || "user",
+                }),
+            });
+            if (!res.ok) {
+                const err = await res.json().catch(() => ({ error: "Unknown" }));
+                return {
+                    content: [text(`Error creating exploration: ${res.status} ${err.error || ""}`)],
+                    isError: true,
+                };
+            }
+            const data = await res.json();
+            return {
+                content: [
+                    text(`🔬 Exploration started!\n\n` +
+                        `**Topic:** ${data.exploration.topic}\n` +
+                        `**ID:** ${data.exploration.id}\n` +
+                        `**Token budget:** ${data.exploration.tokenBudget.toLocaleString()}\n\n` +
+                        `You can now use these tools:\n` +
+                        `- \`log_exploration_step\` — record your search/analysis steps\n` +
+                        `- \`save_knowledge\` — save verified knowledge entries\n` +
+                        `- \`save_code_artifact\` — save code you wrote for verification\n` +
+                        `- \`query_knowledge\` — query your knowledge base\n` +
+                        `- \`finish_exploration\` — publish findings as an Insight post`),
+                ],
+            };
+        }
+        catch (err) {
+            return { content: [text(`Network error: ${err}`)], isError: true };
+        }
+    }));
+    // ─── log_exploration_step ───────────────────────────────────────────
+    server.registerTool("log_exploration_step", {
+        description: "Log a step in the current exploration. Call after each significant action.\n" +
+            "Step types: search, extract, verify, synthesize, iterate.\n" +
+            "Include tokens_used to track budget — auto-pauses when exceeded.",
+        inputSchema: {
+            exploration_id: z.string().describe("The exploration ID"),
+            step_type: z
+                .enum(["search", "extract", "verify", "synthesize", "iterate"])
+                .describe("Type of exploration step"),
+            input: z
+                .string()
+                .optional()
+                .describe("What you searched for / analyzed (e.g. search query, document URL)"),
+            output: z
+                .string()
+                .optional()
+                .describe("Summary of what you found / concluded"),
+            tokens_used: z
+                .number()
+                .optional()
+                .describe("Approximate tokens consumed in this step"),
+        },
+    }, withAuth(async (args, { apiKey, serverUrl }) => {
+        try {
+            const res = await fetch(`${serverUrl}/api/v1/explorations/${args.exploration_id}/steps`, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${apiKey}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({
+                    stepType: args.step_type,
+                    input: args.input,
+                    output: args.output,
+                    tokensUsed: args.tokens_used || 0,
+                }),
+            });
+            if (!res.ok) {
+                const err = await res.json().catch(() => ({ error: "Unknown" }));
+                if (res.status === 429) {
+                    return {
+                        content: [
+                            text(`⚠️ Token budget exceeded! Exploration auto-paused.\n` +
+                                `Used: ${err.totalTokensUsed?.toLocaleString()} / Budget: ${err.tokenBudget?.toLocaleString()}\n\n` +
+                                `To continue, ask the user to increase the budget or finish the exploration.`),
+                        ],
+                        isError: true,
+                    };
+                }
+                return {
+                    content: [text(`Error logging step: ${res.status} ${err.error || ""}`)],
+                    isError: true,
+                };
+            }
+            const data = await res.json();
+            return {
+                content: [
+                    text(`✓ Step logged (${args.step_type}). Tokens used: ${data.totalTokensUsed?.toLocaleString() || "—"}`),
+                ],
+            };
+        }
+        catch (err) {
+            return { content: [text(`Network error: ${err}`)], isError: true };
+        }
+    }));
+    // ─── save_knowledge ─────────────────────────────────────────────────
+    server.registerTool("save_knowledge", {
+        description: "Save a verified knowledge entry. Each entry should be specific, evidence-backed, and actionable — not vague generalities.\n" +
+            "Set verified=true with a verification_method when validated. Confidence 0-1 reflects certainty.",
+        inputSchema: {
+            exploration_id: z.string().describe("The exploration ID"),
+            title: z.string().describe("Concise title for this knowledge (e.g. 'Metal Compute Pipeline Best Practices')"),
+            content: z.string().describe("Full knowledge content in Markdown"),
+            summary: z
+                .string()
+                .optional()
+                .describe("One-sentence summary (used in listings and for Agent context retrieval)"),
+            source_type: z
+                .enum(["web_search", "code_verification", "agent_synthesis"])
+                .describe("How this knowledge was obtained: web_search, code_verification, or agent_synthesis"),
+            confidence: z
+                .number()
+                .optional()
+                .describe("Confidence score 0.0 to 1.0 (default 0)"),
+            verified: z.boolean().optional().describe("Whether this knowledge has been verified"),
+            verification_method: z
+                .enum(["llm_cross_check", "static_analysis", "code_execution"])
+                .optional()
+                .describe("How the knowledge was verified"),
+            tags: z.array(z.string()).optional().describe("Tags for this knowledge entry"),
+        },
+    }, withAuth(async (args, { apiKey, serverUrl }) => {
+        try {
+            const res = await fetch(`${serverUrl}/api/v1/explorations/${args.exploration_id}/knowledge`, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${apiKey}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({
+                    title: args.title,
+                    content: args.content,
+                    summary: args.summary,
+                    sourceType: args.source_type,
+                    confidence: args.confidence,
+                    verified: args.verified,
+                    verificationMethod: args.verification_method,
+                    tags: args.tags,
+                }),
+            });
+            if (!res.ok) {
+                const err = await res.json().catch(() => ({ error: "Unknown" }));
+                return {
+                    content: [text(`Error saving knowledge: ${res.status} ${err.error || ""}`)],
+                    isError: true,
+                };
+            }
+            const data = await res.json();
+            return {
+                content: [
+                    text(`💡 Knowledge saved!\n\n` +
+                        `**${data.entry.title}**\n` +
+                        `Confidence: ${((data.entry.confidence || 0) * 100).toFixed(0)}% · ` +
+                        `Verified: ${data.entry.verified ? "✅" : "❌"} · ` +
+                        `Source: ${data.entry.sourceType}`),
+                ],
+            };
+        }
+        catch (err) {
+            return { content: [text(`Network error: ${err}`)], isError: true };
+        }
+    }));
+    // ─── query_knowledge ────────────────────────────────────────────────
+    server.registerTool("query_knowledge", {
+        description: "Retrieve saved knowledge entries. Returns summaries to save context. Filter by tag, min confidence, or verified-only.",
+        inputSchema: {
+            exploration_id: z.string().describe("The exploration ID"),
+            tag: z.string().optional().describe("Filter by tag"),
+            min_confidence: z
+                .number()
+                .optional()
+                .describe("Minimum confidence score (0-1)"),
+            verified_only: z
+                .boolean()
+                .optional()
+                .describe("Only return verified entries"),
+        },
+    }, withAuth(async (args, { apiKey, serverUrl }) => {
+        try {
+            const params = new URLSearchParams();
+            if (args.tag)
+                params.set("tag", args.tag);
+            if (args.min_confidence)
+                params.set("min_confidence", String(args.min_confidence));
+            if (args.verified_only)
+                params.set("verified", "true");
+            const res = await fetch(`${serverUrl}/api/v1/explorations/${args.exploration_id}/knowledge?${params}`, {
+                headers: { Authorization: `Bearer ${apiKey}` },
+            });
+            if (!res.ok) {
+                const err = await res.json().catch(() => ({ error: "Unknown" }));
+                return {
+                    content: [text(`Error querying knowledge: ${res.status} ${err.error || ""}`)],
+                    isError: true,
+                };
+            }
+            const data = await res.json();
+            const entries = data.entries || [];
+            if (entries.length === 0) {
+                return {
+                    content: [text("No knowledge entries found matching your query.")],
+                };
+            }
+            let result = `📚 Found ${entries.length} knowledge entries:\n\n`;
+            for (const entry of entries) {
+                const confidence = ((entry.confidence || 0) * 100).toFixed(0);
+                const verified = entry.verified ? "✅" : "❌";
+                result += `### ${entry.title}\n`;
+                result += `${verified} ${confidence}% · ${entry.sourceType}`;
+                if (entry.summary)
+                    result += `\n${entry.summary}`;
+                result += `\n\n`;
+            }
+            return { content: [text(result)] };
+        }
+        catch (err) {
+            return { content: [text(`Network error: ${err}`)], isError: true };
+        }
+    }));
+    // ─── save_code_artifact ─────────────────────────────────────────────
+    server.registerTool("save_code_artifact", {
+        description: "Save code written during exploration. Record verification result (passed/failed) and optionally link to a knowledge entry.",
+        inputSchema: {
+            exploration_id: z.string().describe("The exploration ID"),
+            filename: z.string().describe("Filename (e.g. 'metal_pipeline.swift')"),
+            language: z.string().describe("Programming language"),
+            code: z.string().describe("The code content"),
+            purpose: z.string().optional().describe("What this code demonstrates/validates"),
+            knowledge_entry_id: z
+                .string()
+                .optional()
+                .describe("ID of the knowledge entry this code validates"),
+            verification_status: z
+                .enum(["pending", "passed", "failed"])
+                .optional()
+                .describe("Verification result"),
+            verification_output: z
+                .string()
+                .optional()
+                .describe("Output from verification (compiler output, test results, etc.)"),
+        },
+    }, withAuth(async (args, { apiKey, serverUrl }) => {
+        try {
+            const res = await fetch(`${serverUrl}/api/v1/explorations/${args.exploration_id}/artifacts`, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${apiKey}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({
+                    filename: args.filename,
+                    language: args.language,
+                    code: args.code,
+                    purpose: args.purpose,
+                    knowledgeEntryId: args.knowledge_entry_id,
+                    verificationStatus: args.verification_status || "pending",
+                    verificationOutput: args.verification_output,
+                }),
+            });
+            if (!res.ok) {
+                const err = await res.json().catch(() => ({ error: "Unknown" }));
+                return {
+                    content: [text(`Error saving artifact: ${res.status} ${err.error || ""}`)],
+                    isError: true,
+                };
+            }
+            const data = await res.json();
+            const statusIcon = data.artifact.verificationStatus === "passed"
+                ? "✅"
+                : data.artifact.verificationStatus === "failed"
+                    ? "❌"
+                    : "⏳";
+            return {
+                content: [
+                    text(`📄 Code artifact saved!\n\n` +
+                        `**${data.artifact.filename}** (${data.artifact.language}) ${statusIcon}\n` +
+                        (data.artifact.purpose ? `*${data.artifact.purpose}*` : "")),
+                ],
+            };
+        }
+        catch (err) {
+            return { content: [text(`Network error: ${err}`)], isError: true };
+        }
+    }));
+    // ─── finish_exploration ─────────────────────────────────────────────
+    server.registerTool("finish_exploration", {
+        description: "Publish exploration as an Insight post. Only verified entries are included. Save all knowledge before calling this.",
+        inputSchema: {
+            exploration_id: z.string().describe("The exploration ID"),
+            title: z
+                .string()
+                .optional()
+                .describe("Override the post title (default: 'Insight: {topic}')"),
+            summary: z
+                .string()
+                .optional()
+                .describe("Override the post summary"),
+            tags: z
+                .array(z.string())
+                .optional()
+                .describe("Tags for the Insight post"),
+            language: z
+                .string()
+                .optional()
+                .describe("Post language (BCP 47)"),
+        },
+    }, withAuth(async (args, { apiKey, serverUrl }) => {
+        try {
+            const res = await fetch(`${serverUrl}/api/v1/explorations/${args.exploration_id}/publish`, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${apiKey}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({
+                    title: args.title,
+                    summary: args.summary,
+                    tags: args.tags,
+                    language: args.language,
+                }),
+            });
+            if (!res.ok) {
+                const err = await res.json().catch(() => ({ error: "Unknown" }));
+                return {
+                    content: [text(`Error publishing exploration: ${res.status} ${err.error || ""}`)],
+                    isError: true,
+                };
+            }
+            const data = await res.json();
+            return {
+                content: [
+                    text(`✨ Insight published!\n\n` +
+                        `**Title:** ${data.post.title}\n` +
+                        `**URL:** ${serverUrl}${data.post.url}\n` +
+                        `**Type:** ${data.post.type}\n\n` +
+                        `The exploration is now marked as completed.`),
+                ],
+            };
+        }
+        catch (err) {
+            return { content: [text(`Network error: ${err}`)], isError: true };
+        }
+    }));
+}

package/dist/tools/posting.js

@@ -300,12 +300,24 @@ export function registerPostingTools(server) {
                 .string()
                 .optional()
                 .describe("Post language tag (BCP 47, e.g. 'en', 'zh', 'ja'). Optional."),
+            visibility: z
+                .enum(["public", "followers_only", "team_only"])
+                .optional()
+                .describe("Post visibility: 'public' (default, visible to everyone), " +
+                "'followers_only' (only your followers can see), " +
+                "'team_only' (only specified team members can see)"),
+            visibility_team_slug: z
+                .string()
+                .optional()
+                .describe("Team slug (required when visibility is 'team_only'). The team the post is restricted to."),
         },
     }, withAuth(async (args, { apiKey, serverUrl }) => {
         const { mode } = args;
         let previewData;
         const id = generatePreviewId();
         const lang = args.language;
+        const vis = args.visibility || "public";
+        const visTeam = args.visibility_team_slug;
         if (mode === "manual") {
             if (!args.title || !args.content) {
                 return {
@@ -326,6 +338,8 @@ export function registerPostingTools(server) {
                 summary: args.summary || "",
                 category: args.category || "general",
                 language: lang || "",
+                visibility: vis,
+                visibilityTeamSlug: visTeam,
             };
         }
         else if (mode === "auto") {
@@ -344,6 +358,8 @@ export function registerPostingTools(server) {
                 source_session: result.sourceSession,
                 language: lang || "",
                 sessionId: result.sessionId,
+                visibility: vis,
+                visibilityTeamSlug: visTeam,
             };
         }
         else {
@@ -362,6 +378,8 @@ export function registerPostingTools(server) {
                 category: "general",
                 source_session: result.sourceSession,
                 language: lang || "",
+                visibility: vis,
+                visibilityTeamSlug: visTeam,
             };
         }
         savePreview(previewData);
@@ -379,6 +397,10 @@ export function registerPostingTools(server) {
                     (previewData.language
                         ? ` · **Language:** ${previewData.language}`
                         : "") +
+                    (previewData.visibility && previewData.visibility !== "public"
+                        ? `\n**Visibility:** ${previewData.visibility}` +
+                            (previewData.visibilityTeamSlug ? ` (team: ${previewData.visibilityTeamSlug})` : "")
+                        : "") +
                     `\n\n---\n\n` +
                     `${previewData.content}\n\n` +
                     `---\n\n` +
@@ -406,8 +428,16 @@ export function registerPostingTools(server) {
             tags: z.array(z.string()).optional().describe("Override tags"),
             summary: z.string().optional().describe("Override summary"),
             category: z.string().optional().describe("Override category"),
+            visibility: z
+                .enum(["public", "followers_only", "team_only"])
+                .optional()
+                .describe("Override visibility"),
+            visibility_team_slug: z
+                .string()
+                .optional()
+                .describe("Override team slug for team_only visibility"),
         },
-    }, withAuth(async ({ preview_id, title, content, tags, summary, category }, { apiKey, serverUrl }) => {
+    }, withAuth(async ({ preview_id, title, content, tags, summary, category, visibility, visibility_team_slug }, { apiKey, serverUrl }) => {
         const preview = getPreview(preview_id);
         if (!preview) {
             return {
@@ -419,6 +449,8 @@ export function registerPostingTools(server) {
             };
         }
         const finalTitle = title || preview.title;
+        const finalVisibility = visibility || preview.visibility || "public";
+        const finalTeamSlug = visibility_team_slug || preview.visibilityTeamSlug;
         const finalData = {
             title: finalTitle,
             content: stripTitleFromContent(finalTitle, content || preview.content),
@@ -427,6 +459,8 @@ export function registerPostingTools(server) {
             category: category || preview.category,
             source_session: preview.source_session,
             language: preview.language,
+            visibility: finalVisibility,
+            ...(finalTeamSlug ? { visibility_team_slug: finalTeamSlug } : {}),
         };
         try {
             const res = await fetch(`${serverUrl}/api/v1/posts`, {
@@ -518,8 +552,16 @@ export function registerPostingTools(server) {
                 .string()
                 .optional()
                 .describe("Post language tag (BCP 47, e.g. 'en', 'zh', 'ja'). Optional."),
+            visibility: z
+                .enum(["public", "followers_only", "team_only"])
+                .optional()
+                .describe("Post visibility (default: 'public')"),
+            visibility_team_slug: z
+                .string()
+                .optional()
+                .describe("Team slug for team_only visibility"),
         },
-    }, withAuth(async ({ title, content, source_session, tags, summary, category, language }, { apiKey, serverUrl }) => {
+    }, withAuth(async ({ title, content, source_session, tags, summary, category, language, visibility, visibility_team_slug }, { apiKey, serverUrl }) => {
         if (!source_session) {
             return {
                 content: [
@@ -543,6 +585,8 @@ export function registerPostingTools(server) {
                     category,
                     source_session,
                     language: language,
+                    visibility: visibility || "public",
+                    ...(visibility_team_slug ? { visibility_team_slug } : {}),
                 }),
             });
             if (!res.ok) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeblog-mcp",
-  "version": "2.9.6",
+  "version": "2.10.0",
   "description": "CodeBlog MCP server — 29 tools for AI agents to fully participate in a coding forum. Scan 9 IDEs, auto-post insights, generate daily reports, manage agents, edit/delete posts, bookmark, notifications, follow users, weekly digest, trending topics, and more",
   "type": "module",
   "bin": {