openalmanac 0.3.2 → 0.3.3

package/dist/setup.js

@@ -137,6 +137,9 @@ const CLAUDE_CODE_MCP = join(CLAUDE_DIR, "mcp.json"); // Claude Code local MCP c
 const SETTINGS_JSON = join(CLAUDE_DIR, "settings.json");
 const CODEX_CONFIG = join(homedir(), ".codex", "config.toml");
 const CURSOR_MCP_JSON = join(homedir(), ".cursor", "mcp.json");
+const OPENCODE_DIR = join(homedir(), ".config", "opencode");
+const OPENCODE_JSON = join(OPENCODE_DIR, "opencode.json");
+const OPENCODE_JSONC = join(OPENCODE_DIR, "opencode.jsonc");
 const WINDSURF_MCP_JSON = join(homedir(), ".codeium", "mcp_config.json");
 function ensureDir(dir) {
     if (!existsSync(dir))
@@ -160,6 +163,7 @@ const SUPPORTED_CLIENT_IDS = [
     "claude-desktop",
     "codex",
     "cursor",
+    "opencode",
     "windsurf",
 ];
 const SUPPORTED_CLIENTS = {
@@ -256,6 +260,36 @@ const SUPPORTED_CLIENTS = {
             ],
         }),
     },
+    opencode: {
+        id: "opencode",
+        name: "OpenCode",
+        selectionLabel: "OpenCode",
+        detect: () => hasCommand("opencode") ||
+            existsSync(OPENCODE_JSON) ||
+            existsSync(OPENCODE_JSONC) ||
+            existsSync(OPENCODE_DIR),
+        configure: (mode) => {
+            const path = getOpenCodeConfigPath();
+            return {
+                changed: configureOpenCodeFile(path, mode),
+                snippets: [
+                    {
+                        path,
+                        content: jsonSnippet({
+                            "$schema": "https://opencode.ai/config.json",
+                            mcp: {
+                                almanac: {
+                                    type: "local",
+                                    command: [ALMANAC_MCP_ENTRY.command, ...ALMANAC_MCP_ENTRY.args],
+                                    enabled: true,
+                                },
+                            },
+                        }),
+                    },
+                ],
+            };
+        },
+    },
     windsurf: {
         id: "windsurf",
         name: "Windsurf",
@@ -340,6 +374,7 @@ function normalizeClientId(value) {
         desktop: "claude-desktop",
         codex: "codex",
         cursor: "cursor",
+        opencode: "opencode",
         windsurf: "windsurf",
     };
     const normalized = aliases[value];
@@ -390,6 +425,13 @@ function isClaudeDesktopInstalled() {
 function jsonSnippet(data) {
     return JSON.stringify(data, null, 2);
 }
+function getOpenCodeConfigPath() {
+    if (existsSync(OPENCODE_JSON))
+        return OPENCODE_JSON;
+    if (existsSync(OPENCODE_JSONC))
+        return OPENCODE_JSONC;
+    return OPENCODE_JSON;
+}
 function codexSnippet() {
     return [
         "[mcp_servers.almanac]",
@@ -401,6 +443,12 @@ function isAlmanacCurrent(server) {
     return (server?.command === "npx" &&
         JSON.stringify(server.args) === JSON.stringify(ALMANAC_MCP_ENTRY.args));
 }
+function isOpenCodeAlmanacCurrent(entry) {
+    return (entry?.type === "local" &&
+        entry?.enabled === true &&
+        JSON.stringify(entry.command) ===
+            JSON.stringify([ALMANAC_MCP_ENTRY.command, ...ALMANAC_MCP_ENTRY.args]));
+}
 function configureJsonMcpFile(path, mode) {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const json = readJson(path);
@@ -428,6 +476,29 @@ function configureCodexToml(path, mode) {
     }
     return true;
 }
+function configureOpenCodeFile(path, mode) {
+    const current = readJsonWithComments(path);
+    if (!current.$schema) {
+        current.$schema = "https://opencode.ai/config.json";
+    }
+    const mcp = isRecord(current.mcp) ? current.mcp : {};
+    if (!isRecord(current.mcp)) {
+        current.mcp = mcp;
+    }
+    if (isOpenCodeAlmanacCurrent(mcp.almanac)) {
+        return false;
+    }
+    mcp.almanac = {
+        type: "local",
+        command: [ALMANAC_MCP_ENTRY.command, ...ALMANAC_MCP_ENTRY.args],
+        enabled: true,
+    };
+    if (mode === "apply") {
+        ensureDir(dirname(path));
+        writeJson(path, current);
+    }
+    return true;
+}
 function readToml(path) {
     try {
         return readFileSync(path, "utf-8");
@@ -436,6 +507,72 @@ function readToml(path) {
         return "";
     }
 }
+function readJsonWithComments(path) {
+    try {
+        const raw = readFileSync(path, "utf-8");
+        const parsed = JSON.parse(stripJsonComments(raw));
+        return isRecord(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function stripJsonComments(input) {
+    let result = "";
+    let inString = false;
+    let inLineComment = false;
+    let inBlockComment = false;
+    let escaped = false;
+    for (let i = 0; i < input.length; i++) {
+        const char = input[i];
+        const next = input[i + 1];
+        if (inLineComment) {
+            if (char === "\n") {
+                inLineComment = false;
+                result += char;
+            }
+            continue;
+        }
+        if (inBlockComment) {
+            if (char === "*" && next === "/") {
+                inBlockComment = false;
+                i++;
+            }
+            continue;
+        }
+        if (inString) {
+            result += char;
+            if (escaped) {
+                escaped = false;
+            }
+            else if (char === "\\") {
+                escaped = true;
+            }
+            else if (char === "\"") {
+                inString = false;
+            }
+            continue;
+        }
+        if (char === "/" && next === "/") {
+            inLineComment = true;
+            i++;
+            continue;
+        }
+        if (char === "/" && next === "*") {
+            inBlockComment = true;
+            i++;
+            continue;
+        }
+        if (char === "\"") {
+            inString = true;
+        }
+        result += char;
+    }
+    return result;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 function upsertCodexServer(content) {
     const sectionName = "mcp_servers.almanac";
     const header = `[${sectionName}]`;
@@ -934,6 +1071,12 @@ function getNextSteps(clientsLabel) {
             `Ask ${BLUE}"Let's explore <topic> using Almanac"${RST}`,
         ];
     }
+    if (clientsLabel === "OpenCode") {
+        return [
+            `Type ${WHITE_BOLD}opencode${RST} to start OpenCode`,
+            `Ask ${BLUE}"Let's explore <topic> using Almanac"${RST}`,
+        ];
+    }
     if (clientsLabel === "Windsurf") {
         return [
             `Open ${WHITE_BOLD}Windsurf${RST} in your project`,

package/dist/tools/articles.d.ts

@@ -0,0 +1,2 @@
+import { FastMCP } from "fastmcp";
+export declare function registerArticleTools(server: FastMCP): void;

package/dist/tools/articles.js

@@ -0,0 +1,401 @@
+import { z } from "zod";
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, statSync, existsSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { stringify as yamlStringify } from "yaml";
+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]+)*$/;
+const WRITING_GUIDE = `
+## Article structure
+
+\`\`\`yaml
+---
+article_id: the-slug
+title: Article Title
+sources:
+  - key: example-source-title
+    url: https://example.com
+    title: Source Title
+    accessed_date: "2025-01-15"
+infobox:
+  header:
+    image_url: https://...         # optional hero image
+    subtitle: Short tagline
+    details:
+      - key: Born
+        value: January 1, 1990
+      - key: Occupation
+        value: Scientist
+    links:
+      - https://example.com
+  sections:
+    - type: timeline               # chronological events
+      title: Career Timeline
+      items:
+        - primary: "Started company"
+          period: "2010"
+          location: "San Francisco"
+    - type: list                   # key figures, works, features
+      title: Known For
+      items:
+        - title: First achievement
+        - title: Second achievement
+          subtitle: Additional detail
+    - type: tags                   # inline tags/chips
+      title: Genres
+      items:
+        - Rock
+        - Jazz
+    - type: grid                   # image grid
+      title: Gallery
+      items:
+        - title: Caption
+          image_url: https://...
+    - type: table                  # structured comparison
+      title: Statistics
+      items:
+        headers:
+          - Name
+          - Value
+        rows:
+          - cells:
+              - Height
+              - "6'2\\""
+    - type: key_value              # simple key-value pairs
+      title: Quick Facts
+      items:
+        - key: Population
+          value: "1.4 billion"
+---
+
+Article body with [@key] citation markers...
+\`\`\`
+
+## Infobox
+
+Include an infobox for any article about a person, place, organization, event, or concept. Pick the section types that fit — you don't need all six.
+
+## Citations
+
+- Mark claims with [@key] after punctuation: "The population is 1.4 billion.[@who-world-population]"
+- Keys must be kebab-case with at least one hyphen (e.g. 'nytimes-climate-report', 'who-malaria-2024')
+- Generate keys BibTeX-style: {domain}-{title-words} (e.g. 'arxiv-attention-is-all')
+- Every source in the sources list must be referenced at least once in the body with [@key]
+- Every [@key] marker must have a matching source with that key
+- Display numbers are computed automatically from first-appearance order — just use the keys
+
+## Images
+
+Use search_images to find relevant images. Images render as figures with visible captions.
+
+**Syntax:** \`![Caption text](url "position")\`
+
+Positions: \`"right"\` (default if omitted), \`"left"\`, \`"center"\`
+
+\`\`\`markdown
+![Alan Turing in 1930, aged 18](https://upload.wikimedia.org/...)
+
+The early life of Alan Turing began...
+
+![Panoramic view of Bletchley Park](https://upload.wikimedia.org/... "center")
+\`\`\`
+
+**Caption rules:**
+- Every image MUST have a descriptive caption — it is displayed below the image
+- Describe what the image shows: "Alan Turing in 1930, aged 18" not "Photo"
+- Include dates, context, or attribution when relevant
+
+**Placement:** 1-3 images per major section, spread throughout. First image near the top.
+For the infobox hero image, use \`infobox.header.image_url\` in frontmatter instead.
+
+External image URLs are auto-persisted on publish — no extra steps needed.
+
+## Writing quality
+
+- Every sentence should contain a specific fact the reader didn't know
+- No filler phrases ("It is worth noting", "In today's world", "Throughout history")
+- No promotional language ("revolutionary", "groundbreaking", "game-changing")
+- No inflated significance ("one of the most important", "changed the world forever")
+- No vague attribution ("many experts say", "it is widely regarded")
+- No formulaic conclusions ("In conclusion", "continues to shape")
+- Write like a concise encyclopedia, not a blog post
+`.trim();
+function ensureArticlesDir() {
+    mkdirSync(ARTICLES_DIR, { recursive: true });
+}
+export function registerArticleTools(server) {
+    server.addTool({
+        name: "search_articles",
+        description: "Search existing OpenAlmanac articles and stubs. Accepts multiple queries for batch lookup. " +
+            "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)"),
+            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)"),
+        }),
+        async execute({ queries, limit, include_stubs }) {
+            const resp = await request("POST", "/api/search/batch", {
+                json: { queries, limit, include_stubs },
+            });
+            return JSON.stringify(await resp.json(), null, 2);
+        },
+    });
+    server.addTool({
+        name: "read",
+        description: "Read article content from OpenAlmanac. Returns the content, sources, and metadata for each slug. " +
+            "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)"),
+        }),
+        async execute({ slugs }) {
+            const resp = await request("POST", "/api/articles/batch", {
+                json: { slugs },
+            });
+            return JSON.stringify(await resp.json(), null, 2);
+        },
+    });
+    server.addTool({
+        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. " +
+            "Idempotent: existing slugs return their current status. Requires login.",
+        parameters: z.object({
+            stubs: z.array(z.object({
+                slug: z
+                    .string()
+                    .min(1)
+                    .max(500)
+                    .describe("Unique kebab-case identifier. For people with LinkedIn: use their vanity ID (e.g. 'john-smith-4a8b2c1'). " +
+                    "For others: descriptive kebab-case (e.g. 'reinforcement-learning', 'openai')"),
+                title: z.string().describe("Display title (e.g. 'John Smith', 'Reinforcement Learning')"),
+                entity_type: z
+                    .enum(["person", "organization", "topic", "event", "creative_work", "place"])
+                    .optional()
+                    .describe("Entity type: 'person' for individuals, 'organization' for companies/institutions/nonprofits, " +
+                    "'topic' for concepts/fields/technologies, 'event' for conferences/historical events, " +
+                    "'creative_work' for books/papers/films/software, 'place' for cities/countries/landmarks"),
+                headline: z
+                    .string()
+                    .optional()
+                    .describe("Short headline (e.g. 'Professor of CS at MIT', 'AI research laboratory')"),
+                image_url: z.string().url().optional().describe("Image URL for the entity"),
+                summary: z
+                    .string()
+                    .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)"),
+        }),
+        async execute({ stubs }) {
+            const resp = await request("POST", "/api/articles/stubs", {
+                auth: true,
+                json: { stubs },
+            });
+            return JSON.stringify(await resp.json(), null, 2);
+        },
+    });
+    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. " +
+            "After editing, use 'publish' to push your changes live.",
+        parameters: z.object({
+            slug: z.string().describe("Article slug (e.g. 'machine-learning')"),
+        }),
+        async execute({ 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}`, {
+                params: { format: "md" },
+            });
+            const markdown = await resp.text();
+            ensureArticlesDir();
+            const filePath = join(ARTICLES_DIR, `${slug}.md`);
+            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)";
+            const wordCount = content.trim().split(/\s+/).filter(Boolean).length;
+            const isStub = frontmatter.stub === true;
+            const stubNote = isStub
+                ? "\n\nThis is a STUB article — a placeholder that hasn't been fully written yet. " +
+                    "Fill in the content body with a complete article, then push to publish."
+                : "";
+            return `Downloaded "${title}" to ${filePath}\n${wordCount} words, ${frontmatter.sources?.length ?? 0} sources.${stubNote}\n\n${WRITING_GUIDE}`;
+        },
+    });
+    server.addTool({
+        name: "new",
+        description: "Create a new article scaffold in your local working directory (~/.openalmanac/articles/). " +
+            "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({
+            slug: z
+                .string()
+                .describe("Unique kebab-case identifier (e.g. 'machine-learning'). Pattern: ^[a-z0-9]+(-[a-z0-9]+)*$"),
+            title: z.string().describe("Article title"),
+        }),
+        async execute({ slug, title }) {
+            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]+)*$`);
+            }
+            ensureArticlesDir();
+            const filePath = join(ARTICLES_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 scaffold = `---\n${frontmatter}---\n\n`;
+            writeFileSync(filePath, scaffold, "utf-8");
+            return `Created ${filePath}\n\n${WRITING_GUIDE}`;
+        },
+    });
+    server.addTool({
+        name: "publish",
+        description: "Validate and publish an article from your local workspace. Reads ~/.openalmanac/articles/{slug}.md, " +
+            "validates content and sources, and publishes to OpenAlmanac. Requires login.",
+        parameters: z.object({
+            slug: z.string().describe("Article slug matching the filename (without .md)"),
+            change_title: z.string().optional().describe("Short title for the change (e.g. 'Added early life section')"),
+            change_description: z.string().optional().describe("Longer description of what changed and why"),
+        }),
+        async execute({ slug, change_title, change_description }) {
+            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.`);
+            }
+            // Local validation
+            const errors = validateArticle(raw);
+            if (errors.length > 0) {
+                const lines = errors.map((e) => `  ${e.field}: ${e.message}`);
+                throw new Error(`Validation failed (${errors.length} error${errors.length > 1 ? "s" : ""}):\n${lines.join("\n")}\n\nFix the file and try again.`);
+            }
+            // Inject change_title/change_description into frontmatter if provided
+            let body = raw;
+            if (change_title || change_description) {
+                const { frontmatter, content } = parseFrontmatter(raw);
+                if (change_title)
+                    frontmatter.change_title = change_title;
+                if (change_description)
+                    frontmatter.change_description = change_description;
+                const newFrontmatter = yamlStringify(frontmatter);
+                body = `---\n${newFrontmatter}---\n${content}`;
+            }
+            const resp = await request("PUT", `/api/articles/${slug}`, {
+                auth: true,
+                body,
+                contentType: "text/markdown",
+            });
+            const data = (await resp.json());
+            const articleUrl = `https://www.openalmanac.org/article/${slug}?celebrate=true`;
+            openBrowser(articleUrl);
+            // Clean up local files after successful publish
+            let cleanupWarning = "";
+            try {
+                unlinkSync(filePath);
+            }
+            catch (e) {
+                if (e.code !== "ENOENT") {
+                    cleanupWarning = `\nNote: could not remove local draft: ${e.message}`;
+                }
+            }
+            try {
+                unlinkSync(join(ARTICLES_DIR, `.${slug}.original.md`));
+            }
+            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)}`;
+        },
+    });
+    server.addTool({
+        name: "requested_articles",
+        description: "List requested articles — stubs that are referenced by the most articles but haven't been fully written yet. " +
+            "Use this to find high-demand topics to write about. No authentication needed.",
+        parameters: z.object({
+            limit: z.number().default(20).describe("Max results (1-200, default 20)"),
+            offset: z.number().default(0).describe("Pagination offset (default 0)"),
+        }),
+        async execute({ limit, offset }) {
+            const resp = await request("GET", "/api/articles/requested", {
+                params: { limit, offset },
+            });
+            return JSON.stringify(await resp.json(), null, 2);
+        },
+    });
+    server.addTool({
+        name: "propose_article",
+        description: "Propose an article before writing it. Call this when you've researched enough and a specific article topic has come into focus. " +
+            "Structures your proposal with a user-facing summary and a detailed brief. " +
+            "The client environment determines what happens next — in GUI environments the user sees a plan card with options, " +
+            "in CLI environments you'll get a response telling you to proceed with writing. " +
+            "Do not start writing an article without proposing first.",
+        parameters: z.object({
+            summary: z.string().describe("User-facing summary: title, key sections, angle. Markdown. Concise — 3-5 bullet points."),
+            details: z.string().describe("Full handoff brief for the background agent. Include: all sources, key facts, user preferences, angle, what to avoid, related articles. Be thorough."),
+            title: z.string().describe("Proposed article title"),
+            slug: z.string().describe("Proposed article slug (kebab-case)"),
+            _userChoice: z.enum(["background", "here", "expired", "already_in_progress"]).optional().describe("Internal field set by GUI client. Never set this manually."),
+        }),
+        async execute({ summary, details, title, slug, _userChoice }) {
+            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 (_userChoice === "background") {
+                return `Article "${title}" is now being written in a background process. Continue exploring with the user. Do not write this article in this conversation.`;
+            }
+            if (_userChoice === "expired") {
+                return `The user navigated away before responding to the proposal. Proposal expired. Continue the conversation naturally.`;
+            }
+            if (_userChoice === "already_in_progress") {
+                return `Article "${title}" is already being generated in a background process. No action needed.`;
+            }
+            // "here" OR no _userChoice (CLI default) — proceed with writing
+            return `Article Proposal: ${title}\n\n${summary}\n\nProceed with writing this article following the writing flow in your instructions.`;
+        },
+    });
+    server.addTool({
+        name: "status",
+        description: "Show login status and list all article files in your local working directory (~/.openalmanac/articles/). " +
+            "Shows auth state, filename, title, file size, and last modified time.",
+        async execute() {
+            ensureArticlesDir();
+            const auth = await getAuthStatus();
+            const authLine = auth.loggedIn
+                ? `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);
+                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(`  ${file}  —  "${title}"  (${size}, modified ${modified})`);
+            }
+            return `${authLine}\n\nLocal articles (${files.length} file(s) in ${ARTICLES_DIR}):\n${rows.join("\n")}`;
+        },
+    });
+}

package/dist/tools/communities.d.ts

@@ -0,0 +1,2 @@
+import { FastMCP } from "fastmcp";
+export declare function registerCommunityTools(server: FastMCP): void;

package/dist/tools/communities.js

@@ -0,0 +1,127 @@
+import { z } from "zod";
+import { request } from "../auth.js";
+export function registerCommunityTools(server) {
+    server.addTool({
+        name: "search_communities",
+        description: "Search or list OpenAlmanac communities. Returns community names, descriptions, and member counts. " +
+            "Use this after pushing an article to find relevant communities for auto-linking. No authentication needed.",
+        parameters: z.object({
+            query: z
+                .string()
+                .optional()
+                .describe("Search term (case-insensitive match on name, slug, or description). Omit to list all."),
+            sort: z
+                .enum(["popular", "newest"])
+                .default("popular")
+                .describe("Sort order (default: popular)"),
+            limit: z
+                .number()
+                .min(1)
+                .max(100)
+                .default(20)
+                .describe("Max results (1-100, default 20)"),
+        }),
+        async execute({ query, sort, limit }) {
+            const params = { sort, limit };
+            if (query)
+                params.query = query;
+            const resp = await request("GET", "/api/communities", { params });
+            const data = (await resp.json());
+            const communities = data.communities.map((c) => ({
+                slug: c.slug,
+                name: c.name,
+                description: c.description,
+                member_count: c.member_count,
+                created_at: c.created_at,
+            }));
+            return `Found ${data.total} communities:\n\n${JSON.stringify(communities, null, 2)}`;
+        },
+    });
+    server.addTool({
+        name: "create_community",
+        description: "Create a new OpenAlmanac community. Requires login and at least 1 published article. " +
+            "Communities are spaces where articles can be curated and discussed around a topic.",
+        parameters: z.object({
+            name: z.string().min(1).max(100).describe("Community name (1-100 chars)"),
+            slug: z
+                .string()
+                .min(1)
+                .max(100)
+                .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/)
+                .describe("Unique kebab-case identifier (e.g. 'machine-learning')"),
+            description: z
+                .string()
+                .min(1)
+                .max(2000)
+                .describe("What the community is about (1-2000 chars)"),
+        }),
+        async execute({ name, slug, description }) {
+            const resp = await request("POST", "/api/communities", {
+                auth: true,
+                json: { name, slug, description },
+            });
+            const data = (await resp.json());
+            const communityUrl = `https://www.openalmanac.org/communities/${slug}`;
+            return `Community created!\n\nURL: ${communityUrl}\n\n${JSON.stringify(data, null, 2)}`;
+        },
+    });
+    server.addTool({
+        name: "create_post",
+        description: "Create a post in an OpenAlmanac community. Requires login and community membership. " +
+            "If you get a 403 error, you need to join the community first.",
+        parameters: z.object({
+            community_slug: z.string().describe("Community slug (e.g. 'machine-learning')"),
+            title: z.string().min(1).max(300).describe("Post title (1-300 chars)"),
+            body: z.string().max(10000).default("").describe("Post body (max 10000 chars)"),
+            flair: z
+                .enum(["discussion", "article-request", "question", "announcement"])
+                .optional()
+                .describe("Post flair/category"),
+        }),
+        async execute({ community_slug, title, body, flair }) {
+            const json = { title, body };
+            if (flair)
+                json.flair = flair;
+            const resp = await request("POST", `/api/communities/${community_slug}/posts`, {
+                auth: true,
+                json,
+            });
+            const data = (await resp.json());
+            const postUrl = `https://www.openalmanac.org/communities/${community_slug}/post/${data.id}`;
+            return `Post created!\n\nURL: ${postUrl}\n\n${JSON.stringify(data, null, 2)}`;
+        },
+    });
+    server.addTool({
+        name: "link_article",
+        description: "Link an article to one or more communities. Use this after pushing an article to connect it " +
+            "with relevant communities. Call search_communities first to find matching communities. " +
+            "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
+                .array(z.string())
+                .min(1)
+                .max(50)
+                .describe("List of community slugs to link the article to (max 50)"),
+        }),
+        async execute({ article_id, community_slugs }) {
+            const resp = await request("POST", `/api/articles/${article_id}/auto-link`, {
+                auth: true,
+                json: { community_slugs },
+            });
+            const data = (await resp.json());
+            const lines = [];
+            if (data.linked.length > 0) {
+                lines.push(`Linked to ${data.linked.length} communities: ${data.linked.join(", ")}`);
+            }
+            if (data.failed.length > 0) {
+                const failLines = data.failed.map((f) => `  ${f.slug}: ${f.reason}`);
+                lines.push(`Failed (${data.failed.length}):\n${failLines.join("\n")}`);
+            }
+            if (lines.length === 0) {
+                lines.push("No communities to link.");
+            }
+            return lines.join("\n\n");
+        },
+    });
+}

package/dist/tools/people.d.ts

@@ -0,0 +1,2 @@
+import { FastMCP } from "fastmcp";
+export declare function registerPeopleTools(server: FastMCP): void;

package/dist/tools/people.js

@@ -0,0 +1,20 @@
+import { z } from "zod";
+import { request } from "../auth.js";
+export function registerPeopleTools(server) {
+    server.addTool({
+        name: "search_people",
+        description: "Search for people to find their canonical slug for linking. Returns candidates with name, headline, " +
+            "image, and location. Use the returned slug when creating stubs and [[links]] for people. Requires login.",
+        parameters: z.object({
+            query: z.string().describe("Search terms (e.g. 'John Smith MIT professor')"),
+            limit: z.number().min(1).max(10).default(5).describe("Max results (1-10, default 5)"),
+        }),
+        async execute({ query, limit }) {
+            const resp = await request("GET", "/api/people/search", {
+                auth: true,
+                params: { query, limit },
+            });
+            return JSON.stringify(await resp.json(), null, 2);
+        },
+    });
+}

package/dist/tools/research.js

@@ -20,44 +20,50 @@ function coerceJson(schema) {
     }, schema);
 }
 export function registerResearchTools(server) {
-    // Discriminated union on `source` — each source's schema only surfaces its own
-    // options, so agents get typed autocomplete instead of an opaque options bag.
-    //
-    // Adding a new source (e.g. hackernews) = append another z.object variant with
-    // its own `source: z.literal(...)` and per-source fields. No existing schema
-    // changes.
-    const WebSearchInput = z.object({
-        source: z.literal("web").describe("Generic web search via Google/Serper. Use for general references, news, docs."),
-        query: z.string().min(1).describe("Search terms. Supports quoted phrases and site: operators."),
-        limit: z.number().int().min(1).max(20).default(10).describe("Max results (1-20, default 10)."),
-    });
-    const RedditSearchInput = z.object({
-        source: z.literal("reddit").describe("Search Reddit — use when the user wants community perspectives, subreddit consensus, lived experiences, or ranked-by-engagement content. Goes through a residential proxy so it sees past Reddit's anti-scraping."),
-        subreddit: z.string().optional().describe("Subreddit name without the 'r/' prefix (e.g. 'Harvard'). Omit to search across all of Reddit. Case-insensitive."),
-        query: z.string().optional().describe("Optional full-text search terms. Omit to return the subreddit's sorted listing (top posts of the year, etc.)."),
+    const SearchWebInput = z.object({
+        source: z.enum(["web", "reddit"]).describe("Search source. Use 'web' for Google/Serper and 'reddit' for community perspectives via Reddit."),
+        query: z.string().min(1).optional().describe("Search terms. Required for source='web'. Optional for source='reddit' — omit it there to return a sorted subreddit listing."),
+        subreddit: z.string().optional().describe("Reddit-only. Subreddit name without the 'r/' prefix (e.g. 'Harvard'). Omit to search across all of Reddit."),
         sort: z.enum(["top", "hot", "new", "rising", "controversial", "relevance", "comments"])
-            .default("top")
-            .describe("For listings: 'top'/'hot'/'new'/'rising'/'controversial'. For searches: 'relevance'/'top'/'new'/'comments'. Default 'top'."),
+            .optional()
+            .describe("Reddit-only. Listing/search sort. Defaults to 'top'. Use 'relevance' or 'comments' only when query is present."),
         time_range: z.enum(["hour", "day", "week", "month", "year", "all"])
-            .default("year")
-            .describe("Time window for top/controversial listings and all searches. Default 'year'."),
-        limit: z.number().int().min(1).max(100).default(25).describe("Max posts to return (1-100, default 25)."),
+            .optional()
+            .describe("Reddit-only. Time window for top/controversial listings and all searches. Defaults to 'year'."),
+        limit: z.number().int().min(1).max(100).optional().describe("Result limit. For source='web' defaults to 10 and must be <= 20. For source='reddit' defaults to 25 and can be up to 100."),
+    }).superRefine((input, ctx) => {
+        if (input.source === "web") {
+            if (!input.query?.trim()) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ["query"],
+                    message: "query is required when source='web'",
+                });
+            }
+            if (input.limit !== undefined && input.limit > 20) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ["limit"],
+                    message: "limit must be <= 20 when source='web'",
+                });
+            }
+        }
     });
     server.addTool({
         name: "search_web",
-        description: "Search the web or a specific community source (Reddit). Discriminated on `source`:\n\n" +
+        description: "Search the web or a specific community source (Reddit). Pick the source with the `source` field:\n\n" +
             "- `source: \"web\"` — general web search via Google. Use for news, docs, scholarly references.\n" +
             "- `source: \"reddit\"` — Reddit-aware search returning posts with score, flair, num_comments, permalink. " +
             "Use when the user is asking about community perspectives, subreddit consensus, or 'what do people think about X'.\n\n" +
-            "Each source exposes its own parameters — follow the schema for the source you pick. " +
+            "Use only the fields relevant to the source you pick. " +
             "Rate limit: 10/min. Requires API key.",
-        parameters: z.discriminatedUnion("source", [WebSearchInput, RedditSearchInput]),
+        parameters: SearchWebInput,
         async execute(input) {
             if (input.source === "reddit") {
                 const params = {
-                    sort: input.sort,
-                    time_range: input.time_range,
-                    limit: input.limit,
+                    sort: input.sort ?? "top",
+                    time_range: input.time_range ?? "year",
+                    limit: input.limit ?? 25,
                 };
                 if (input.subreddit)
                     params.subreddit = input.subreddit;
@@ -71,7 +77,7 @@ export function registerResearchTools(server) {
             }
             const resp = await request("GET", "/api/research/search", {
                 auth: true,
-                params: { query: input.query, limit: input.limit },
+                params: { query: input.query.trim(), limit: input.limit ?? 10 },
             });
             return JSON.stringify(await resp.json(), null, 2);
         },

package/package.json

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