openalmanac 0.2.56 → 0.2.58

package/dist/server.js

@@ -7,6 +7,7 @@ import { registerPageTools } from "./tools/pages.js";
 import { registerResearchTools } from "./tools/research.js";
 import { registerWikiTools } from "./tools/wikis.js";
 import { registerTopicTools } from "./tools/topics.js";
+import { registerUserTools } from "./tools/users.js";
 import { getApiKey } from "./auth.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
@@ -122,11 +123,54 @@ export function createServer() {
             "",
             "Why this order: the draft must be finished before subagents run. The linking agent needs to see what entities are actually in the text. The image agent needs to match images to specific content. The review agent needs the complete article. Everything reads the draft.",
             "",
+            "## Wikilink syntax",
+            "",
+            "Wikilinks are resolved server-side at publish time. There are four forms — every one uses double brackets:",
+            "",
+            "- `[[slug]]` — link to another page in the SAME wiki you're publishing to. Display text is the page's title.",
+            "- `[[slug|Display text]]` — same wiki, custom display text.",
+            "- `[[global:slug]]` / `[[global:slug|Display]]` — link to a page in the global almanac (the shared wiki with slug `global`). Use this for cross-cutting entities (people, technologies, concepts) that belong in the global knowledge base rather than a per-topic wiki.",
+            "- `[[wiki-slug:page-slug]]` / `[[wiki-slug:page-slug|Display]]` — link to a specific page in another wiki.",
+            "",
+            "Dead links auto-create stub pages on publish — you can link to entities that don't exist yet and the server will scaffold empty pages at those slugs so the links resolve. Use `resolve` before publish if you want to see which targets are `found` / `stub` / `not_found`.",
+            "",
+            "Inline mentions without brackets are NOT linked. If you want an entity to be linkable, wrap it in `[[...]]`.",
+            "",
+            "## Authoring an infobox",
+            "",
+            "Infoboxes have a strict pydantic schema on the backend — unknown section types, bare-string `header.links`, int values in `header.details`, and missing `primary` on timeline items are all rejected at publish time with a 400. Before authoring ANY infobox, fetch the full field-by-field reference:",
+            "",
+            "  https://www.openalmanac.org/infobox-schema.md",
+            "",
+            "Follow it exactly. Do not invent new section types or field names — if the schema doesn't describe what you want, fold the information into `key_value` or `list`. The six valid section types are `timeline`, `list`, `tags`, `grid`, `table`, `key_value`.",
+            "",
+            "## Working across wikis",
+            "",
+            "OpenAlmanac is multi-wiki. Every page lives inside one wiki. Before writing or creating anything, ground yourself:",
+            "",
+            "- `whoami` → who is the user? Needed to address them and to reason about \"my wikis\".",
+            "- `list_wikis` → what wikis exist? Use this BEFORE `create_wiki` so you can suggest contributing to an existing wiki instead of spinning up a parallel one.",
+            "",
+            "### Creating a new wiki — collaborative flow",
+            "",
+            "When the user says \"I want to start a wiki about X\", don't just call `create_wiki` and dump content. Do this:",
+            "",
+            "1. **Check what's there.** Call `list_wikis` to see existing wikis. If something close exists, surface it: \"There's already a `<slug>` wiki on a related area — do you want to contribute there, or is this a distinct enough angle?\"",
+            "2. **Research the space briefly.** Use `search_web` + `read_webpage` to get real information about the topic. A few quick reads, not a deep dive — enough to brainstorm coherently.",
+            "3. **Brainstorm structure with the user.** Be conversational, not a form-filler. Propose a few natural topics the wiki might have (3-6 bullet points max), what the scope is, what the voice/angle is. Ask what resonates. Don't write prose yet.",
+            "4. **Create the wiki.** `create_wiki` with title + description. The server auto-scaffolds a `main-page` with default homepage directives.",
+            "5. **Edit the main page in place.** `download` the auto-created `main-page` and edit the file (don't `new` a fresh `main-page` — the server derives slug from title, so a new scaffold would get a different slug and you'd end up with two homepages).",
+            "6. **Seed the topic hierarchy.** `create_topics_batch` with the topics you agreed on.",
+            "7. **Wire navigation.** `update_wiki_settings` with a `nav` array. Each NavItem needs exactly one of `page` / `topic` / `link`. Use `auto: {enabled: true}` on topic NavItems to auto-populate children from the topic DAG.",
+            "8. **Seed a few stub pages or first articles.** Stubs are fine — scaffold-and-fill-later is a supported workflow.",
+            "",
+            "The conversation drives the shape of the wiki. Don't over-engineer the topic hierarchy or the nav on turn one. Ship a small coherent starting shape and grow it with the user.",
+            "",
             "## Technical workflow",
             "",
             "Reading and searching articles is open. Writing requires an API key (from login). Login creates a personal API key linked to your user account, so contributions are attributed to you.",
             "",
-            "Core flow: login (once) → search_articles (check if exists) → search_web + read_webpage (research) → `new` (scaffold with wiki_slug) or `download` (batch with wiki_slug) → edit files under ~/.openalmanac/articles/{wiki_slug}/ → `publish` (slugs + wiki_slug).",
+            "Core flow: login (once) → `whoami` (confirm identity) → `list_wikis` or `search_articles` (what exists?) → `search_web` + `read_webpage` (research) → `new` (scaffold) or `download` (existing) → edit files under ~/.openalmanac/articles/{wiki_slug}/ → `publish`.",
             "",
             "After publishing, share the celebration URL when applicable. Use `list_articles` with `wiki_slug` to browse a wiki's pages.",
             "",
@@ -138,5 +182,6 @@ export function createServer() {
     registerResearchTools(server);
     registerWikiTools(server);
     registerTopicTools(server);
+    registerUserTools(server);
     return server;
 }

package/dist/tools/pages.js

@@ -93,19 +93,22 @@ export function registerPageTools(server) {
             include_stubs: z.boolean().default(true).describe("Include stubs in results"),
         }),
         async execute({ queries, wiki, limit, include_stubs }) {
-            const results = {};
-            for (const q of queries) {
-                const params = {
-                    query: q, limit, type: "pages",
-                };
-                if (wiki)
-                    params.wiki = wiki;
-                if (include_stubs)
-                    params.include_stubs = true;
-                const resp = await request("GET", "/api/search", { params });
-                results[q] = await resp.json();
+            // Single server round-trip via /api/search/batch (rate-limited 10/min).
+            // Backend fans out internally and returns [{query, results[], error?}, ...].
+            const body = {
+                queries,
+                limit,
+                include_stubs,
+            };
+            if (wiki)
+                body.wiki = wiki;
+            const resp = await request("POST", "/api/search/batch", { json: body });
+            const data = (await resp.json());
+            const byQuery = {};
+            for (const set of data.results) {
+                byQuery[set.query] = set.error ? { error: set.error } : set.results;
             }
-            return JSON.stringify(results, null, 2);
+            return JSON.stringify(byQuery, null, 2);
         },
     });
     server.addTool({
@@ -280,8 +283,10 @@ export function registerPageTools(server) {
                     continue;
                 }
                 okCount++;
-                // Delete local .md and .ref
-                const published_slug = r.renamed_from ? targetSlugs[results.indexOf(r)] : r.slug;
+                // The local file was named with the pre-rename slug. The server returns
+                // `renamed_from` on rename so we can clean up the right file without
+                // relying on request/response index parity.
+                const published_slug = r.renamed_from ?? r.slug;
                 const { filePath, refPath } = resolvePagePaths(published_slug, wiki_slug);
                 try {
                     unlinkSync(filePath);

package/dist/tools/topics.js

@@ -35,12 +35,13 @@ export function registerTopicTools(server) {
             wiki_slug: z.string().describe("Wiki slug"),
             title: z.string().describe("Topic title"),
             description: z.string().default("").describe("Topic description"),
+            image_url: z.string().url().max(2048).optional().describe("Topic image URL (https:// or http://)"),
             parent_slugs: coerceJson(z.array(z.string())).default([]).describe("Parent topic slugs"),
         }),
-        async execute({ wiki_slug, title, description, parent_slugs }) {
+        async execute({ wiki_slug, title, description, image_url, parent_slugs }) {
             const resp = await request("POST", `/api/w/${wiki_slug}/topics`, {
                 auth: true,
-                json: { title, description, parent_slugs },
+                json: { title, description, image_url, parent_slugs },
             });
             return JSON.stringify(await resp.json(), null, 2);
         },
@@ -53,6 +54,7 @@ export function registerTopicTools(server) {
             topics: coerceJson(z.array(z.object({
                 title: z.string(),
                 description: z.string().default(""),
+                image_url: z.string().url().max(2048).optional(),
                 parent_slugs: z.array(z.string()).default([]),
             })).min(1).max(100)).describe("Topics to create"),
         }),

package/dist/tools/users.d.ts

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

package/dist/tools/users.js

@@ -0,0 +1,13 @@
+import { z } from "zod";
+import { request } from "../auth.js";
+export function registerUserTools(server) {
+    server.addTool({
+        name: "whoami",
+        description: "Return the current user's profile — username, display name, avatar. Use this to ground any \"my X\" decision (which wikis am I a member of, how should I address the user, etc.) before making assumptions. Requires login.",
+        parameters: z.object({}),
+        async execute() {
+            const resp = await request("GET", "/api/users/me", { auth: true });
+            return JSON.stringify(await resp.json(), null, 2);
+        },
+    });
+}

package/dist/tools/wikis.js

@@ -13,10 +13,61 @@ function coerceJson(schema) {
         return val;
     }, schema);
 }
+// Mirrors backend `NavItem` in src/schemas/wiki_settings_schemas.py. The
+// refinement matches the `exactly_one_target` @model_validator there —
+// agents get a clear error pre-flight instead of a 422 round-trip.
+const navItemSchema = z.lazy(() => z.object({
+    label: z.string(),
+    page: z.string().optional(),
+    topic: z.string().optional(),
+    link: z.string().optional(),
+    children: z.array(navItemSchema).optional(),
+    auto: z.object({
+        enabled: z.boolean(),
+        include_subtopics: z.boolean().optional(),
+        include_pages: z.boolean().optional(),
+        subtopic_limit: z.number().int().positive().optional(),
+        page_limit: z.number().int().positive().optional(),
+        show_view_all: z.boolean().optional(),
+        hidden_topic_slugs: z.array(z.string()).optional(),
+        hidden_page_slugs: z.array(z.string()).optional(),
+        pinned: z.array(z.object({
+            kind: z.enum(["topic", "page"]),
+            slug: z.string(),
+        })).optional(),
+    }).optional(),
+}).refine((item) => {
+    const targets = [item.page, item.topic, item.link].filter((t) => typeof t === "string" && t.trim().length > 0);
+    return targets.length === 1;
+}, { message: "NavItem must have exactly one of page, topic, or link" }).refine((item) => !(item.auto && !item.topic), { message: "NavItem auto mode requires a topic target" }).refine((item) => !(item.auto && item.children && item.children.length > 0), { message: "NavItem cannot define children while auto mode is enabled" }));
+// Mirrors backend `WikiTheme`. All fields are optional from the MCP side —
+// the backend fills defaults. Extra keys are dropped (backend uses
+// model_config extra="ignore").
+const themeSchema = z.object({
+    accent_color: z.string().optional(),
+    name_font: z.string().optional(),
+    logo_url: z.string().optional(),
+    cover_tint_intensity: z.number().optional(),
+    logo_tint_intensity: z.number().optional(),
+    cover_y_offset: z.number().optional(),
+}).passthrough();
 export function registerWikiTools(server) {
+    server.addTool({
+        name: "list_wikis",
+        description: "List every wiki on OpenAlmanac. Use before creating a new wiki so you can suggest contributing to an existing one. The global almanac has slug `global` and is excluded by default — pass `include_global: true` to include it. No authentication needed.",
+        parameters: z.object({
+            include_global: z.boolean().default(false).describe("Include the global almanac wiki in results"),
+        }),
+        async execute({ include_global }) {
+            const resp = await request("GET", "/api/wikis", {
+                params: { include_global },
+            });
+            return JSON.stringify(await resp.json(), null, 2);
+        },
+    });
     server.addTool({
         name: "create_wiki",
-        description: "Create a new wiki. Returns the wiki slug and URL. Requires login.",
+        description: "Create a new wiki. Returns the wiki slug and URL. A welcome `main-page` is auto-created with default homepage directives — download it and edit in place rather than scaffolding a fresh `main-page` (the server derives slug from title, so a new scaffold would get a different slug). Requires login.",
         parameters: z.object({
             title: z.string().describe("Wiki title"),
             description: z.string().default("").describe("Wiki description"),
@@ -27,7 +78,7 @@ export function registerWikiTools(server) {
                 json: { title, description },
             });
             const wiki = (await resp.json());
-            return `Created wiki "${wiki.title}" at /w/${wiki.slug}`;
+            return `Created wiki "${wiki.title}" at /w/${wiki.slug}. The homepage was auto-scaffolded at slug "main-page" — download it to edit.`;
         },
     });
     server.addTool({
@@ -43,19 +94,13 @@ export function registerWikiTools(server) {
     });
     server.addTool({
         name: "update_wiki_settings",
-        description: "Update a wiki's settings (nav, cover_image_url, theme). Requires moderator access.",
+        description: "Update a wiki's settings (nav, cover_image_url, theme). Each NavItem must have exactly one of `page`, `topic`, or `link`. Use `auto` (only on topic items) to auto-populate children from the topic DAG. Requires moderator access.",
         parameters: z.object({
             wiki_slug: z.string().describe("Wiki slug"),
             settings: coerceJson(z.object({
-                nav: z.array(z.object({
-                    label: z.string(),
-                    page: z.string().optional(),
-                    topic: z.string().optional(),
-                    link: z.string().optional(),
-                    children: z.array(z.any()).optional(),
-                })).optional(),
+                nav: z.array(navItemSchema).optional(),
                 cover_image_url: z.string().optional(),
-                theme: z.record(z.unknown()).optional(),
+                theme: themeSchema.optional(),
             })).describe("Settings to update"),
         }),
         async execute({ wiki_slug, settings }) {
@@ -71,22 +116,16 @@ export function registerWikiTools(server) {
         description: "Update just the navigation tree for a wiki. Shorthand for updating settings.nav. Requires moderator access.",
         parameters: z.object({
             wiki_slug: z.string().describe("Wiki slug"),
-            nav: coerceJson(z.array(z.object({
-                label: z.string(),
-                page: z.string().optional(),
-                topic: z.string().optional(),
-                link: z.string().optional(),
-                children: z.array(z.any()).optional(),
-            }))).describe("Nav items"),
+            nav: coerceJson(z.array(navItemSchema)).describe("Nav items"),
         }),
         async execute({ wiki_slug, nav }) {
-            // Get current settings, merge nav
-            const getResp = await request("GET", `/api/w/${wiki_slug}`);
-            const wiki = (await getResp.json());
-            const settings = { ...wiki.settings, nav };
+            // Single atomic PATCH — the backend's update_settings service uses
+            // model_dump(exclude_unset=True) to merge partial bodies, so sending
+            // only {nav} doesn't touch theme or cover_image_url. Previously this
+            // did a GET-then-PATCH, which raced with concurrent settings updates.
             const resp = await request("PATCH", `/api/w/${wiki_slug}/settings`, {
                 auth: true,
-                json: settings,
+                json: { nav },
             });
             return JSON.stringify(await resp.json(), null, 2);
         },