openalmanac 0.2.32 → 0.2.34

package/dist/tools/articles.js

@@ -6,6 +6,24 @@ import { request, ARTICLES_DIR, getAuthStatus } from "../auth.js";
 import { validateArticle, parseFrontmatter } from "../validate.js";
 import { openBrowser } from "../browser.js";
 const SLUG_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+/**
+ * Workaround for Claude Agent SDK MCP transport bug (#18260):
+ * Array/object parameters are sometimes serialized as JSON strings
+ * instead of native values. This preprocessor coerces them back.
+ */
+function coerceJson(schema) {
+    return z.preprocess((val) => {
+        if (typeof val === "string") {
+            try {
+                return JSON.parse(val);
+            }
+            catch {
+                return val;
+            }
+        }
+        return val;
+    }, schema);
+}
 const WRITING_GUIDE = `
 ## Article structure
 
@@ -124,6 +142,54 @@ External image URLs are auto-persisted on publish — no extra steps needed.
 function ensureArticlesDir() {
     mkdirSync(ARTICLES_DIR, { recursive: true });
 }
+function resolveArticleDir(communitySlug) {
+    return communitySlug ? join(ARTICLES_DIR, communitySlug) : ARTICLES_DIR;
+}
+function resolveArticlePaths(slug, communitySlug) {
+    const dir = resolveArticleDir(communitySlug);
+    return {
+        dir,
+        filePath: join(dir, `${slug}.md`),
+        originalPath: join(dir, `.${slug}.original.md`),
+    };
+}
+function findDraftCandidates(slug) {
+    const matches = [];
+    const root = resolveArticlePaths(slug);
+    if (existsSync(root.filePath)) {
+        matches.push({ communitySlug: null, filePath: root.filePath, originalPath: root.originalPath });
+    }
+    try {
+        const dirs = readdirSync(ARTICLES_DIR).filter((d) => {
+            try {
+                return statSync(join(ARTICLES_DIR, d)).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        });
+        for (const communitySlug of dirs) {
+            const scoped = resolveArticlePaths(slug, communitySlug);
+            if (existsSync(scoped.filePath)) {
+                matches.push({ communitySlug, filePath: scoped.filePath, originalPath: scoped.originalPath });
+            }
+        }
+    }
+    catch { /* ignore readdir errors */ }
+    return matches;
+}
+function resolvePublishCandidate(slug) {
+    const matches = findDraftCandidates(slug);
+    if (matches.length === 0) {
+        const fallback = resolveArticlePaths(slug);
+        throw new Error(`File not found: ${fallback.filePath}\nUse download to get an existing article or new to create a scaffold.`);
+    }
+    if (matches.length > 1) {
+        const paths = matches.map((match) => `  - ${match.filePath}`).join("\n");
+        throw new Error(`Multiple local drafts found for slug "${slug}". Publish is ambiguous.\n${paths}\nRemove the duplicate draft or publish from the exact community context.`);
+    }
+    return matches[0];
+}
 export function registerArticleTools(server) {
     server.addTool({
         name: "search_articles",
@@ -131,7 +197,7 @@ export function registerArticleTools(server) {
             "Use this to check if articles or stubs exist before creating them, or to find entity slugs for wikilinks. " +
             "Results include 'stub' field (true/false) and 'entity_type' field. No authentication needed.",
         parameters: z.object({
-            queries: z.array(z.string()).min(1).max(20).describe("Search queries (1-20)"),
+            queries: coerceJson(z.array(z.string()).min(1).max(20)).describe("Search queries (1-20)"),
             limit: z.number().default(5).describe("Max results per query (1-50, default 5)"),
             include_stubs: z.boolean().default(true).describe("Include stub articles in results (default true)"),
         }),
@@ -148,9 +214,17 @@ export function registerArticleTools(server) {
             "Use this to reference or summarize existing articles in conversation. " +
             "For editing articles locally, use 'download' instead. No authentication needed.",
         parameters: z.object({
-            slugs: z.array(z.string()).min(1).max(20).describe("Article slugs to read (1-20)"),
+            slugs: coerceJson(z.array(z.string()).min(1).max(20)).describe("Article slugs to read (1-20)"),
+            community_slug: z.string().optional().describe("Community slug for reading community-owned wiki articles. Omit for global almanac articles."),
         }),
-        async execute({ slugs }) {
+        async execute({ slugs, community_slug }) {
+            if (community_slug) {
+                const results = await Promise.all(slugs.map(async (slug) => {
+                    const resp = await request("GET", `/api/communities/${community_slug}/wiki/${slug}`);
+                    return await resp.json();
+                }));
+                return JSON.stringify({ results }, null, 2);
+            }
             const resp = await request("POST", "/api/articles/batch", {
                 json: { slugs },
             });
@@ -161,9 +235,10 @@ export function registerArticleTools(server) {
         name: "create_stubs",
         description: "Create stub articles — placeholders for entities that don't have full articles yet. " +
             "Use this for every entity (person, organization, topic, etc.) mentioned in an article. " +
+            "For community wiki stubs, include community_slug on each stub. " +
             "Idempotent: existing slugs return their current status. Requires login.",
         parameters: z.object({
-            stubs: z.array(z.object({
+            stubs: coerceJson(z.array(z.object({
                 slug: z
                     .string()
                     .min(1)
@@ -187,7 +262,9 @@ export function registerArticleTools(server) {
                     .optional()
                     .describe("2-4 sentence summary of the entity. This becomes the stub page content. " +
                     "Be informative — include key facts, dates, and context."),
-            })).min(1).max(50).describe("Stubs to create (1-50)"),
+                community_slug: z.string().optional().describe("Community slug for community-owned stubs. Omit for global stubs."),
+                topics: z.array(z.string()).optional().describe("Topic slugs for community wiki stubs (e.g. ['techniques', 'tools'])."),
+            })).min(1).max(50)).describe("Stubs to create (1-50)"),
         }),
         async execute({ stubs }) {
             const resp = await request("POST", "/api/articles/stubs", {
@@ -199,24 +276,33 @@ export function registerArticleTools(server) {
     });
     server.addTool({
         name: "download",
-        description: "Download an article to your local workspace for editing. The file is saved to ~/.openalmanac/articles/{slug}.md " +
-            "with YAML frontmatter. Returns a writing guide covering article structure, infobox format, citations, and quality rules. " +
+        description: "Download an article to your local workspace for editing. Global articles are saved to ~/.openalmanac/articles/{slug}.md. " +
+            "Community wiki articles are saved to ~/.openalmanac/articles/{community_slug}/{slug}.md. " +
+            "Returns a writing guide covering article structure, infobox format, citations, and quality rules. " +
             "After editing, use 'publish' to push your changes live.",
         parameters: z.object({
             slug: z.string().describe("Article slug (e.g. 'machine-learning')"),
+            community_slug: z.string().optional().describe("Community slug for downloading a community-owned wiki article. " +
+                "Omit for global almanac articles."),
         }),
-        async execute({ slug }) {
+        async execute({ slug, community_slug }) {
             if (!SLUG_RE.test(slug)) {
                 throw new Error(`Invalid slug "${slug}". Must be kebab-case (e.g. 'machine-learning').`);
             }
-            const resp = await request("GET", `/api/articles/${slug}`, {
+            const apiPath = community_slug
+                ? `/api/communities/${community_slug}/wiki/${slug}`
+                : `/api/articles/${slug}`;
+            const resp = await request("GET", apiPath, {
                 params: { format: "md" },
             });
             const markdown = await resp.text();
             ensureArticlesDir();
-            const filePath = join(ARTICLES_DIR, `${slug}.md`);
+            // Community articles go in a subdirectory
+            const { dir, filePath, originalPath } = resolveArticlePaths(slug, community_slug);
+            if (community_slug) {
+                mkdirSync(dir, { recursive: true });
+            }
             writeFileSync(filePath, markdown, "utf-8");
-            const originalPath = join(ARTICLES_DIR, `.${slug}.original.md`);
             writeFileSync(originalPath, markdown, "utf-8");
             const { frontmatter, content } = parseFrontmatter(markdown);
             const title = frontmatter.title || "(untitled)";
@@ -232,6 +318,8 @@ export function registerArticleTools(server) {
     server.addTool({
         name: "new",
         description: "Create a new article scaffold in your local working directory (~/.openalmanac/articles/). " +
+            "For community wiki articles, provide community_slug and optional topics — the file is saved under " +
+            "~/.openalmanac/articles/{community_slug}/{slug}.md. " +
             "The file is created with YAML frontmatter and an empty body. Returns a writing guide covering article structure, infobox format, citations, and quality rules. " +
             "Edit the file to add content and sources, then use publish to go live.",
         parameters: z.object({
@@ -239,17 +327,36 @@ export function registerArticleTools(server) {
                 .string()
                 .describe("Unique kebab-case identifier (e.g. 'machine-learning'). Pattern: ^[a-z0-9]+(-[a-z0-9]+)*$"),
             title: z.string().describe("Article title"),
+            community_slug: z.string().optional().describe("Community slug for community-owned wiki articles (e.g. 'lockpicking'). " +
+                "Omit for global almanac articles."),
+            topics: coerceJson(z.array(z.string()).default([])).describe("Topic slugs for community wiki articles (e.g. ['techniques', 'tools']). " +
+                "Topics are community-specific categories."),
         }),
-        async execute({ slug, title }) {
+        async execute({ slug, title, community_slug, topics }) {
             if (!SLUG_RE.test(slug)) {
                 throw new Error(`Invalid slug "${slug}". Must be kebab-case (e.g. 'machine-learning'). Pattern: ^[a-z0-9]+(-[a-z0-9]+)*$`);
             }
+            if (community_slug && !SLUG_RE.test(community_slug)) {
+                throw new Error(`Invalid community_slug "${community_slug}". Must be kebab-case.`);
+            }
             ensureArticlesDir();
-            const filePath = join(ARTICLES_DIR, `${slug}.md`);
+            // Community articles are saved in a subdirectory
+            let dir = ARTICLES_DIR;
+            if (community_slug) {
+                dir = join(ARTICLES_DIR, community_slug);
+                mkdirSync(dir, { recursive: true });
+            }
+            const filePath = join(dir, `${slug}.md`);
             if (existsSync(filePath)) {
                 throw new Error(`File already exists: ${filePath}\nUse download to refresh it, or publish to push changes.`);
             }
-            const frontmatter = yamlStringify({ article_id: slug, title, sources: [] });
+            const meta = { article_id: slug, title };
+            if (community_slug)
+                meta.community_slug = community_slug;
+            if (topics && topics.length > 0)
+                meta.topics = topics;
+            meta.sources = [];
+            const frontmatter = yamlStringify(meta);
             const scaffold = `---\n${frontmatter}---\n\n`;
             writeFileSync(filePath, scaffold, "utf-8");
             return `Created ${filePath}\n\n${WRITING_GUIDE}`;
@@ -257,7 +364,7 @@ export function registerArticleTools(server) {
     });
     server.addTool({
         name: "publish",
-        description: "Validate and publish an article from your local workspace. Reads ~/.openalmanac/articles/{slug}.md, " +
+        description: "Validate and publish an article from your local workspace. Reads ~/.openalmanac/articles/{slug}.md or the matching community draft, " +
             "validates content and sources, and publishes to OpenAlmanac. Requires login.",
         parameters: z.object({
             slug: z.string().describe("Article slug matching the filename (without .md)"),
@@ -268,14 +375,8 @@ export function registerArticleTools(server) {
             if (!SLUG_RE.test(slug)) {
                 throw new Error(`Invalid slug "${slug}". Must be kebab-case (e.g. 'machine-learning').`);
             }
-            const filePath = join(ARTICLES_DIR, `${slug}.md`);
-            let raw;
-            try {
-                raw = readFileSync(filePath, "utf-8");
-            }
-            catch {
-                throw new Error(`File not found: ${filePath}\nUse download to get an existing article or new to create a scaffold.`);
-            }
+            const { communitySlug, filePath, originalPath } = resolvePublishCandidate(slug);
+            const raw = readFileSync(filePath, "utf-8");
             // Local validation
             const errors = validateArticle(raw);
             if (errors.length > 0) {
@@ -299,8 +400,17 @@ export function registerArticleTools(server) {
                 contentType: "text/markdown",
             });
             const data = (await resp.json());
-            const articleUrl = `https://www.openalmanac.org/article/${slug}?celebrate=true`;
-            openBrowser(articleUrl);
+            const canonicalPath = typeof data.canonical_path === "string"
+                ? data.canonical_path
+                : communitySlug
+                    ? `/communities/${communitySlug}/wiki/${slug}`
+                    : `/article/${slug}`;
+            const articleUrl = `https://www.openalmanac.org${canonicalPath}?celebrate=true`;
+            const inGui = process.env.OPENALMANAC_GUI === "1";
+            // Skip browser open when running inside the GUI — it handles navigation itself
+            if (!inGui) {
+                openBrowser(articleUrl);
+            }
             // Clean up local files after successful publish
             let cleanupWarning = "";
             try {
@@ -312,14 +422,17 @@ export function registerArticleTools(server) {
                 }
             }
             try {
-                unlinkSync(join(ARTICLES_DIR, `.${slug}.original.md`));
+                unlinkSync(originalPath);
             }
             catch (e) {
                 if (e.code !== "ENOENT") {
                     cleanupWarning += `\nNote: could not remove original copy: ${e.message}`;
                 }
             }
-            return `Pushed successfully.\n\nArticle URL (share this exact link with the user): ${articleUrl}${cleanupWarning}\n\n${JSON.stringify(data, null, 2)}`;
+            const urlLine = inGui
+                ? "The article has been published! Let the user know it's live. Do not send them to a web URL."
+                : `Article URL (share this exact link with the user): ${articleUrl}`;
+            return `Pushed successfully.\n\n${urlLine}${cleanupWarning}\n\n${JSON.stringify(data, null, 2)}`;
         },
     });
     server.addTool({
@@ -379,9 +492,6 @@ export function registerArticleTools(server) {
                 ? `Logged in as ${auth.name}.`
                 : "Not logged in. Use login to authenticate.";
             const files = readdirSync(ARTICLES_DIR).filter((f) => f.endsWith(".md") && !f.startsWith("."));
-            if (files.length === 0) {
-                return `${authLine}\n\nLocal articles (0 files in ${ARTICLES_DIR}):\n  (none — use download or new to get started)`;
-            }
             const rows = [];
             for (const file of files) {
                 const filePath = join(ARTICLES_DIR, file);
@@ -395,7 +505,37 @@ export function registerArticleTools(server) {
                 const modified = stat.mtime.toISOString().slice(0, 16).replace("T", " ");
                 rows.push(`  ${file}  —  "${title}"  (${size}, modified ${modified})`);
             }
-            return `${authLine}\n\nLocal articles (${files.length} file(s) in ${ARTICLES_DIR}):\n${rows.join("\n")}`;
+            try {
+                const dirs = readdirSync(ARTICLES_DIR).filter((entry) => {
+                    try {
+                        return statSync(join(ARTICLES_DIR, entry)).isDirectory();
+                    }
+                    catch {
+                        return false;
+                    }
+                });
+                for (const communitySlug of dirs) {
+                    const dir = join(ARTICLES_DIR, communitySlug);
+                    const communityFiles = readdirSync(dir).filter((f) => f.endsWith(".md") && !f.startsWith("."));
+                    for (const file of communityFiles) {
+                        const filePath = join(dir, file);
+                        const stat = statSync(filePath);
+                        const raw = readFileSync(filePath, "utf-8");
+                        const { frontmatter } = parseFrontmatter(raw);
+                        const title = frontmatter.title || "(untitled)";
+                        const size = stat.size < 1024
+                            ? `${stat.size}B`
+                            : `${(stat.size / 1024).toFixed(1)}KB`;
+                        const modified = stat.mtime.toISOString().slice(0, 16).replace("T", " ");
+                        rows.push(`  ${communitySlug}/${file}  —  "${title}"  (${size}, modified ${modified})`);
+                    }
+                }
+            }
+            catch { /* ignore subdir scan errors */ }
+            if (rows.length === 0) {
+                return `${authLine}\n\nLocal articles (0 files in ${ARTICLES_DIR}):\n  (none — use download or new to get started)`;
+            }
+            return `${authLine}\n\nLocal articles (${rows.length} file(s) in ${ARTICLES_DIR}):\n${rows.join("\n")}`;
         },
     });
 }

package/dist/tools/communities.js

@@ -1,5 +1,23 @@
 import { z } from "zod";
 import { request } from "../auth.js";
+/**
+ * Workaround for Claude Agent SDK MCP transport bug (#18260):
+ * Array/object parameters are sometimes serialized as JSON strings
+ * instead of native values. This preprocessor coerces them back.
+ */
+function coerceJson(schema) {
+    return z.preprocess((val) => {
+        if (typeof val === "string") {
+            try {
+                return JSON.parse(val);
+            }
+            catch {
+                return val;
+            }
+        }
+        return val;
+    }, schema);
+}
 export function registerCommunityTools(server) {
     server.addTool({
         name: "search_communities",
@@ -98,10 +116,10 @@ export function registerCommunityTools(server) {
             "Idempotent — already-linked articles are reported but don't cause errors. Requires login.",
         parameters: z.object({
             article_id: z.string().describe("Article slug/ID to link (e.g. 'machine-learning')"),
-            community_slugs: z
+            community_slugs: coerceJson(z
                 .array(z.string())
                 .min(1)
-                .max(50)
+                .max(50))
                 .describe("List of community slugs to link the article to (max 50)"),
         }),
         async execute({ article_id, community_slugs }) {

package/dist/tools/research.js

@@ -1,6 +1,24 @@
 import { z } from "zod";
 import { imageContent } from "fastmcp";
 import { request } from "../auth.js";
+/**
+ * Workaround for Claude Agent SDK MCP transport bug (#18260):
+ * Array/object parameters are sometimes serialized as JSON strings
+ * instead of native values. This preprocessor coerces them back.
+ */
+function coerceJson(schema) {
+    return z.preprocess((val) => {
+        if (typeof val === "string") {
+            try {
+                return JSON.parse(val);
+            }
+            catch {
+                return val;
+            }
+        }
+        return val;
+    }, schema);
+}
 export function registerResearchTools(server) {
     server.addTool({
         name: "search_web",
@@ -70,7 +88,7 @@ export function registerResearchTools(server) {
             "- For the infobox hero image, set `infobox.header.image_url` in frontmatter instead\n\n" +
             "Requires login. Rate limit: 10/min.",
         parameters: z.object({
-            queries: z.array(z.string()).min(1).max(10).describe("Image search queries (1-10)"),
+            queries: coerceJson(z.array(z.string()).min(1).max(10)).describe("Image search queries (1-10)"),
             source: z.enum(["wikimedia", "google"]).default("wikimedia").describe("Image source: 'wikimedia' (free, open-licensed — preferred) or 'google' (broader coverage)"),
             limit: z.number().default(5).describe("Max results per query (1-10, default 5)"),
         }),
@@ -87,7 +105,7 @@ export function registerResearchTools(server) {
         description: "View images to verify they're suitable. Use after search_images to inspect candidates " +
             "before including them. Returns each image so you can see what it shows and write accurate captions.",
         parameters: z.object({
-            urls: z.array(z.string().url()).min(1).max(10).describe("Image URLs to view (1-10)"),
+            urls: coerceJson(z.array(z.string().url()).min(1).max(10)).describe("Image URLs to view (1-10)"),
         }),
         async execute({ urls }) {
             const results = await Promise.allSettled(urls.map(async (url) => {
@@ -118,11 +136,11 @@ export function registerResearchTools(server) {
             "Each source becomes a clickable citation bubble when you use [@key] markers in your text. " +
             "Collect sources from your read_webpage calls and any subagent results, then register them all in one call.",
         parameters: z.object({
-            sources: z.array(z.object({
+            sources: coerceJson(z.array(z.object({
                 key: z.string().describe("Citation key — kebab-case, BibTeX-style: {domain}-{title-words} (e.g. 'nytimes-climate-report')"),
                 url: z.string().describe("Source URL"),
                 title: z.string().describe("Source title — include publication name after em dash (e.g. 'Climate Report — The New York Times')"),
-            })).min(1).describe("Sources to register for citation"),
+            })).min(1)).describe("Sources to register for citation"),
         }),
         async execute({ sources }) {
             return `Registered ${sources.length} source${sources.length === 1 ? "" : "s"}. Use [@key] markers in your response to cite them.`;

package/dist/validate.js

@@ -34,6 +34,30 @@ export function validateArticle(raw) {
             message: "Must be kebab-case (e.g. 'machine-learning'). Pattern: ^[a-z0-9]+(-[a-z0-9]+)*$",
         });
     }
+    const communitySlug = frontmatter.community_slug;
+    if (communitySlug != null && (typeof communitySlug !== "string" || !SLUG_RE.test(communitySlug))) {
+        errors.push({
+            field: "community_slug",
+            message: "Must be kebab-case (e.g. 'lockpicking'). Pattern: ^[a-z0-9]+(-[a-z0-9]+)*$",
+        });
+    }
+    const topics = frontmatter.topics;
+    if (topics != null) {
+        if (!Array.isArray(topics)) {
+            errors.push({ field: "topics", message: "Topics must be an array of kebab-case slugs" });
+        }
+        else {
+            for (let i = 0; i < topics.length; i++) {
+                const topic = topics[i];
+                if (typeof topic !== "string" || !SLUG_RE.test(topic)) {
+                    errors.push({
+                        field: `topics[${i}]`,
+                        message: "Must be kebab-case (e.g. 'spool-pins')",
+                    });
+                }
+            }
+        }
+    }
     // sources
     const sources = frontmatter.sources;
     if (!Array.isArray(sources)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openalmanac",
-  "version": "0.2.32",
+  "version": "0.2.34",
   "description": "OpenAlmanac — pull, edit, and push articles to the open knowledge base",
   "type": "module",
   "bin": {