openalmanac 0.4.2 → 0.4.4

package/dist/auth.d.ts

@@ -14,6 +14,7 @@ export type AuthStatus = {
 };
 export declare function getAuthStatus(): Promise<AuthStatus>;
 export declare function buildAuthHeaders(): Record<string, string>;
+export declare function requireValidApiKey(): Promise<void>;
 export declare function request(method: string, path: string, options?: {
     auth?: boolean;
     params?: Record<string, string | number | boolean>;

package/dist/auth.js

@@ -59,6 +59,20 @@ export async function getAuthStatus() {
 export function buildAuthHeaders() {
     return { Authorization: `Bearer ${requireApiKey()}` };
 }
+export async function requireValidApiKey() {
+    const key = requireApiKey();
+    const resp = await fetch(`${API_BASE}/api/users/me`, {
+        headers: { Authorization: `Bearer ${key}` },
+        signal: AbortSignal.timeout(10_000),
+    });
+    if (resp.ok)
+        return;
+    if (resp.status === 401 || resp.status === 403) {
+        throw new Error(`Authentication failed (${resp.status}). Your API key may be invalid or expired. Run 'login' to re-authenticate.`);
+    }
+    const text = await resp.text();
+    throw new Error(`${resp.status} ${resp.statusText}: ${text}`);
+}
 export async function request(method, path, options = {}) {
     const { auth = false, params, json, body, contentType } = options;
     let url = `${API_BASE}${path}`;

package/dist/instructions.js

@@ -1,5 +1,5 @@
 export const SERVER_INSTRUCTIONS = [
-    "OpenAlmanac is an open knowledge base — a Wikipedia anyone can read from and write to through an API. Pages are markdown files with YAML frontmatter, [@key] citation markers, and [[wikilinks]]. Content is organized into wikis, each with topics, pages, and navigation.",
+    "Almanac is an open knowledge base — a Wikipedia anyone can read from and write to through an API. Pages are markdown files with YAML frontmatter, [@key] citation markers, and [[wikilinks]]. Content is organized into wikis, each with topics, pages, and navigation.",
     "",
     "## How this should feel",
     "",
@@ -113,7 +113,7 @@ export const SERVER_INSTRUCTIONS = [
     "",
     "## Working across wikis",
     "",
-    "OpenAlmanac is multi-wiki. Every page lives inside one wiki. Before writing or creating anything, ground yourself:",
+    "Almanac 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.",
@@ -136,7 +136,7 @@ export const SERVER_INSTRUCTIONS = [
     "",
     "## Technical workflow",
     "",
-    "Reading and searching pages 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.",
+    "All Almanac MCP tools except `login` and `logout` require login. Login creates a personal API key linked to your user account, so MCP reads, research, and contributions are attributed to you.",
     "",
     "Core flow: login (once) → `whoami` (confirm identity) → `list_wikis` or `search_pages` (what exists?) → `search_web` + `read_webpage` (research) → `new` (scaffold) or `download` (existing) → edit files under ~/.openalmanac/pages/{wiki_slug}/ → `publish`.",
     "",

package/dist/onboarding-copy.js

@@ -2,7 +2,7 @@
 // post-login connected page rendered by `login-core.ts`.
 //
 // The example prompt is a starter question on purpose: the goal is to give
-// new users an easy first message that teaches them what OpenAlmanac can do
+// new users an easy first message that teaches them what Almanac can do
 // instead of assuming they already know what to ask. If the example prompt
 // changes, both surfaces (`setup.ts` next steps + `login-core.ts` terminal
 // mock) update automatically because they consume this single constant.

package/dist/server.js

@@ -10,6 +10,7 @@ import { registerTopicTools } from "./tools/topics.js";
 import { registerUserTools } from "./tools/users.js";
 import { getApiKey } from "./auth.js";
 import { SERVER_INSTRUCTIONS } from "./instructions.js";
+import { installMcpToolTracking } from "./tool-tracking.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
 export function createServer() {
@@ -17,12 +18,12 @@ export function createServer() {
         console.error(`
 ┌──────────────────────────────────────────────────┐
 │                                                  │
-│   Welcome to OpenAlmanac                         │
+│   Welcome to Almanac                             │
 │                                                  │
 │   Try asking your agent:                         │
 │                                                  │
-│   → "Write an Almanac page about CORS"        │
-│   → "Improve the Alan Turing page"            │
+│   → "Write an Almanac page about CORS"           │
+│   → "Improve the Alan Turing page"               │
 │                                                  │
 │   Docs: openalmanac.org/contribute               │
 │                                                  │
@@ -30,10 +31,11 @@ export function createServer() {
 `);
     }
     const server = new FastMCP({
-        name: "OpenAlmanac",
+        name: "Almanac",
         version: pkg.version,
         instructions: SERVER_INSTRUCTIONS,
     });
+    installMcpToolTracking(server, pkg.version);
     registerAuthTools(server);
     registerPageTools(server);
     registerResearchTools(server);

package/dist/setup/clients.js

@@ -254,7 +254,7 @@ export function applyClientSetup(clients, mode) {
     return { configured, alreadyConfigured };
 }
 export function printSetupPlan(clients, options) {
-    const heading = options.dryRun ? "Dry run" : "OpenAlmanac MCP setup";
+    const heading = options.dryRun ? "Dry run" : "Almanac MCP setup";
     process.stdout.write(`${heading}\n\n`);
     if (clients.length === 0) {
         process.stdout.write("No supported clients detected. Use --client <name> to force a target or --print to inspect supported snippets.\n");

package/dist/tool-registry.js

@@ -1,4 +1,4 @@
-// Single source of truth for the MCP tools the OpenAlmanac server exposes.
+// Single source of truth for the MCP tools the Almanac server exposes.
 //
 // This file is the contract that ties three otherwise-independent surfaces
 // together:

package/dist/tool-tracking.d.ts

@@ -0,0 +1,49 @@
+import type { FastMCP } from "fastmcp";
+type ToolGroup = "read" | "write" | "research" | "wiki_admin" | "account";
+type EntityType = "account" | "image" | "page" | "topic" | "web" | "wiki";
+type MutationScope = "none" | "local" | "backend" | "backend_dry_run";
+type IntentDomain = "auth" | "page_read" | "page_write" | "search" | "topic_management" | "web_research" | "wiki_management";
+export interface McpToolCallEvent {
+    tool_name: string;
+    tool_group: ToolGroup;
+    intent_domain: IntentDomain;
+    operation: string;
+    entity_type: EntityType;
+    mutation_scope: MutationScope;
+    success: boolean;
+    duration_ms: number;
+    mcp_version: string;
+    error_type?: string;
+    wiki_slug?: string;
+    dry_run?: boolean;
+    requested_count?: number;
+    result_count?: number;
+    result_created_count?: number;
+    result_updated_count?: number;
+    result_renamed_count?: number;
+    result_unchanged_count?: number;
+    result_error_count?: number;
+    result_skipped_count?: number;
+    result_stub_created_count?: number;
+    planned_created_count?: number;
+    planned_updated_count?: number;
+    planned_renamed_count?: number;
+    planned_error_count?: number;
+}
+interface McpToolDefinition {
+    name: string;
+    execute?: (...args: any[]) => unknown;
+    [key: string]: unknown;
+}
+interface ToolTrackingDeps {
+    mcpVersion: string;
+    validateAuth?: () => Promise<void>;
+    trackToolCall?: (event: McpToolCallEvent) => Promise<void>;
+    now?: () => number;
+}
+export type McpTrackingDetails = Partial<Omit<McpToolCallEvent, "tool_name" | "tool_group" | "intent_domain" | "success" | "duration_ms" | "mcp_version" | "error_type">>;
+export declare function setMcpTrackingDetails(details: McpTrackingDetails): void;
+export declare function postMcpToolCall(event: McpToolCallEvent): Promise<void>;
+export declare function wrapMcpToolDefinition<T extends McpToolDefinition>(definition: T, deps: ToolTrackingDeps): T;
+export declare function installMcpToolTracking(server: FastMCP, mcpVersion: string): FastMCP;
+export {};

package/dist/tool-tracking.js

@@ -0,0 +1,108 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { request, requireValidApiKey } from "./auth.js";
+const AUTH_EXEMPT_TOOLS = new Set(["login", "logout"]);
+const trackingDetailsStorage = new AsyncLocalStorage();
+export function setMcpTrackingDetails(details) {
+    const store = trackingDetailsStorage.getStore();
+    if (store) {
+        store.details = { ...store.details, ...details };
+    }
+}
+const TOOL_METADATA = {
+    search_pages: { tool_group: "read", intent_domain: "search", operation: "page_search", entity_type: "page", mutation_scope: "none" },
+    search_topics: { tool_group: "read", intent_domain: "search", operation: "topic_search", entity_type: "topic", mutation_scope: "none" },
+    list_pages: { tool_group: "read", intent_domain: "page_read", operation: "page_list", entity_type: "page", mutation_scope: "none" },
+    list_topics: { tool_group: "read", intent_domain: "page_read", operation: "topic_list", entity_type: "topic", mutation_scope: "none" },
+    list_wikis: { tool_group: "read", intent_domain: "wiki_management", operation: "wiki_list", entity_type: "wiki", mutation_scope: "none" },
+    download: { tool_group: "read", intent_domain: "page_read", operation: "page_download", entity_type: "page", mutation_scope: "local" },
+    read_page: { tool_group: "read", intent_domain: "page_read", operation: "page_read", entity_type: "page", mutation_scope: "none" },
+    search_web: { tool_group: "research", intent_domain: "web_research", operation: "web_search", entity_type: "web", mutation_scope: "none" },
+    read_webpage: { tool_group: "research", intent_domain: "web_research", operation: "webpage_read", entity_type: "web", mutation_scope: "none" },
+    search_images: { tool_group: "research", intent_domain: "web_research", operation: "image_search", entity_type: "image", mutation_scope: "none" },
+    view_images: { tool_group: "research", intent_domain: "web_research", operation: "image_view", entity_type: "image", mutation_scope: "none" },
+    new: { tool_group: "write", intent_domain: "page_write", operation: "page_scaffold", entity_type: "page", mutation_scope: "local" },
+    publish: { tool_group: "write", intent_domain: "page_write", operation: "page_publish", entity_type: "page", mutation_scope: "backend" },
+    delete_pages: { tool_group: "write", intent_domain: "page_write", operation: "page_delete", entity_type: "page", mutation_scope: "backend" },
+    create_topics: { tool_group: "write", intent_domain: "topic_management", operation: "topic_create", entity_type: "topic", mutation_scope: "backend" },
+    update_topic: { tool_group: "write", intent_domain: "topic_management", operation: "topic_update", entity_type: "topic", mutation_scope: "backend" },
+    create_wiki: { tool_group: "wiki_admin", intent_domain: "wiki_management", operation: "wiki_create", entity_type: "wiki", mutation_scope: "backend" },
+    get_wiki_settings: { tool_group: "wiki_admin", intent_domain: "wiki_management", operation: "wiki_settings_read", entity_type: "wiki", mutation_scope: "none" },
+    update_wiki_settings: { tool_group: "wiki_admin", intent_domain: "wiki_management", operation: "wiki_settings_update", entity_type: "wiki", mutation_scope: "backend" },
+    join_wiki: { tool_group: "wiki_admin", intent_domain: "wiki_management", operation: "wiki_join", entity_type: "wiki", mutation_scope: "backend" },
+    get_wiki_membership: { tool_group: "wiki_admin", intent_domain: "wiki_management", operation: "wiki_membership_read", entity_type: "wiki", mutation_scope: "none" },
+    whoami: { tool_group: "account", intent_domain: "auth", operation: "account_read", entity_type: "account", mutation_scope: "none" },
+};
+function metadataForTool(toolName) {
+    return TOOL_METADATA[toolName] ?? {
+        tool_group: "account",
+        intent_domain: "auth",
+        operation: "unknown",
+        entity_type: "account",
+        mutation_scope: "none",
+    };
+}
+function errorType(error) {
+    if (error instanceof Error && error.name)
+        return error.name;
+    return typeof error;
+}
+export async function postMcpToolCall(event) {
+    await request("POST", "/api/mcp/tool-calls", {
+        auth: true,
+        json: event,
+    });
+}
+export function wrapMcpToolDefinition(definition, deps) {
+    if (!definition.execute || AUTH_EXEMPT_TOOLS.has(definition.name)) {
+        return definition;
+    }
+    const execute = definition.execute;
+    const validateAuth = deps.validateAuth ?? requireValidApiKey;
+    const trackToolCall = deps.trackToolCall ?? postMcpToolCall;
+    const now = deps.now ?? Date.now;
+    const metadata = metadataForTool(definition.name);
+    return {
+        ...definition,
+        async execute(...args) {
+            await validateAuth();
+            const startedAt = now();
+            const trackingState = { details: {} };
+            let success = false;
+            let caught;
+            try {
+                const result = await trackingDetailsStorage.run(trackingState, async () => execute(...args));
+                success = true;
+                return result;
+            }
+            catch (error) {
+                caught = error;
+                throw error;
+            }
+            finally {
+                const event = {
+                    tool_name: definition.name,
+                    ...metadata,
+                    ...trackingState.details,
+                    success,
+                    duration_ms: Math.max(0, Math.round(now() - startedAt)),
+                    mcp_version: deps.mcpVersion,
+                };
+                if (caught !== undefined) {
+                    event.error_type = errorType(caught);
+                }
+                try {
+                    await trackToolCall(event);
+                }
+                catch {
+                    // Analytics should never change tool behavior.
+                }
+            }
+        },
+    };
+}
+export function installMcpToolTracking(server, mcpVersion) {
+    const addTool = server.addTool.bind(server);
+    server.addTool =
+        (definition) => addTool(wrapMcpToolDefinition(definition, { mcpVersion }));
+    return server;
+}

package/dist/tools/auth.js

@@ -4,7 +4,7 @@ export function registerAuthTools(server) {
     server.addTool({
         name: "login",
         description: "Log in via browser to connect your account and get a personal API key. This is the required " +
-            "first step before creating or updating pages. Only needs to be called once.\n\n" +
+            "first step before using Almanac MCP tools. Only needs to be called once.\n\n" +
             "If you already have a valid API key, this returns immediately without opening a browser.",
         async execute() {
             const result = await performLogin();

package/dist/tools/pages/index.js

@@ -3,15 +3,39 @@ import { readFileSync, writeFileSync, mkdirSync, readdirSync, existsSync } from
 import { stringify as yamlStringify } from "yaml";
 import { request } from "../../auth.js";
 import { openBrowser } from "../../browser.js";
+import { setMcpTrackingDetails } from "../../tool-tracking.js";
 import { coerceJson } from "../../utils.js";
 import { formatPublishResults } from "./publish-format.js";
 import { resolvePageDir, resolvePagePaths, SLUG_RE } from "./workspace.js";
 import { WRITING_GUIDE } from "./writing-guide.js";
+function summarizePublishTracking(results, requestedCount, wiki_slug, dryRun) {
+    const details = {
+        wiki_slug,
+        dry_run: dryRun,
+        mutation_scope: dryRun ? "backend_dry_run" : "backend",
+        requested_count: requestedCount,
+        result_count: results.length,
+        result_error_count: results.filter(result => result.status === "error").length,
+        result_stub_created_count: results.reduce((count, result) => count + (result.stubs_created?.length ?? 0), 0),
+    };
+    if (dryRun) {
+        details.planned_created_count = results.filter(result => result.plan?.action === "create").length;
+        details.planned_updated_count = results.filter(result => result.plan?.action === "update").length;
+        details.planned_renamed_count = results.filter(result => result.plan?.action === "rename").length;
+        details.planned_error_count = results.filter(result => result.plan?.action === "error").length;
+        return details;
+    }
+    details.result_created_count = results.filter(result => result.status === "created").length;
+    details.result_updated_count = results.filter(result => result.status === "updated").length;
+    details.result_renamed_count = results.filter(result => result.status === "renamed").length;
+    details.result_unchanged_count = results.filter(result => result.status === "unchanged").length;
+    return details;
+}
 export function registerPageTools(server) {
     server.addTool({
         name: "search_pages",
-        description: "Search OpenAlmanac pages and stubs across all wikis. Use to check existence, find slugs for wikilinks, " +
-            "or discover content. Optional wiki filter to scope results. No authentication needed.",
+        description: "Search Almanac pages and stubs across all wikis. Use to check existence, find slugs for wikilinks, " +
+            "or discover content. Optional wiki filter to scope results. Requires login.",
         parameters: z.object({
             queries: coerceJson(z.array(z.string()).min(1).max(20)).describe("Search queries (1-20)"),
             wiki: z.string().optional().describe("Filter to a specific wiki slug"),
@@ -28,7 +52,7 @@ export function registerPageTools(server) {
             };
             if (wiki)
                 body.wiki = wiki;
-            const resp = await request("POST", "/api/search/batch", { json: body });
+            const resp = await request("POST", "/api/search/batch", { auth: true, json: body });
             const data = (await resp.json());
             const byQuery = {};
             for (const set of data.results) {
@@ -39,8 +63,8 @@ export function registerPageTools(server) {
     });
     server.addTool({
         name: "search_topics",
-        description: "Search OpenAlmanac topics across all wikis. Use to discover topic slugs and topic pages. " +
-            "Optional wiki filter to scope results. No authentication needed.",
+        description: "Search Almanac topics across all wikis. Use to discover topic slugs and topic pages. " +
+            "Optional wiki filter to scope results. Requires login.",
         parameters: z.object({
             queries: coerceJson(z.array(z.string()).min(1).max(20)).describe("Search queries (1-20)"),
             wiki: z.string().optional().describe("Filter to a specific wiki slug"),
@@ -54,7 +78,7 @@ export function registerPageTools(server) {
                 };
                 if (wiki)
                     params.wiki = wiki;
-                const resp = await request("GET", "/api/search", { params });
+                const resp = await request("GET", "/api/search", { auth: true, params });
                 results[q] = await resp.json();
             }
             return JSON.stringify(results, null, 2);
@@ -64,7 +88,7 @@ export function registerPageTools(server) {
         name: "list_pages",
         description: "Browse pages in a wiki. Structured listing, not fuzzy search. " +
             "Use to see what exists, find stubs, or discover pages by topic. " +
-            "Each returned page includes topic objects with both slug and title.",
+            "Each returned page includes topic objects with both slug and title. Requires login.",
         parameters: z.object({
             wiki_slug: z.string().describe("Wiki slug"),
             topic: z.string().optional().describe("Filter by topic slug"),
@@ -78,7 +102,7 @@ export function registerPageTools(server) {
                 params.topic = topic;
             if (stubs_only)
                 params.stub = true;
-            const resp = await request("GET", `/api/w/${wiki_slug}/pages`, { params });
+            const resp = await request("GET", `/api/w/${wiki_slug}/pages`, { auth: true, params });
             return JSON.stringify(await resp.json(), null, 2);
         },
     });
@@ -198,6 +222,13 @@ export function registerPageTools(server) {
                 nudges.length > 0 ? nudges.join("\n") : "",
                 WRITING_GUIDE,
             ];
+            setMcpTrackingDetails({
+                wiki_slug,
+                requested_count: pages.length,
+                result_count: created.length + skipped.length,
+                result_created_count: created.length,
+                result_skipped_count: skipped.length,
+            });
             return parts.filter(Boolean).join("\n\n");
         },
     });
@@ -253,8 +284,11 @@ export function registerPageTools(server) {
             });
             const results = (await resp.json());
             const summary = formatPublishResults(results, targetSlugs, wiki_slug, dry_run ?? false);
+            const dryRun = dry_run ?? false;
+            const details = summarizePublishTracking(results, targetSlugs.length, wiki_slug, dryRun);
+            setMcpTrackingDetails(details);
             // Open browser on single-page publish success (non-GUI, non-dry-run).
-            if (!dry_run && targetSlugs.length === 1 && process.env.OPENALMANAC_GUI !== "1") {
+            if (!dryRun && targetSlugs.length === 1 && process.env.OPENALMANAC_GUI !== "1") {
                 const r = results[0];
                 if (r && r.status !== "error") {
                     const resultSlug = r.slug;
@@ -272,13 +306,13 @@ export function registerPageTools(server) {
         description: "Read a single page by slug. Returns the full page JSON including content, topics, sources, and infobox. " +
             "No side effects — use this to read a page without downloading it to disk or joining the wiki. " +
             "For editing, use `download` instead (it writes local files and handles ref tokens). " +
-            "For discovery, use `search_pages` instead. No authentication needed.",
+            "For discovery, use `search_pages` instead. Requires login.",
         parameters: z.object({
             wiki_slug: z.string().describe("Wiki slug"),
             page_slug: z.string().describe("Page slug"),
         }),
         async execute({ wiki_slug, page_slug }) {
-            const resp = await request("GET", `/api/w/${wiki_slug}/pages/${page_slug}`);
+            const resp = await request("GET", `/api/w/${wiki_slug}/pages/${page_slug}`, { auth: true });
             return JSON.stringify(await resp.json(), null, 2);
         },
     });

package/dist/tools/topics.js

@@ -4,13 +4,14 @@ import { coerceJson } from "../utils.js";
 export function registerTopicTools(server) {
     server.addTool({
         name: "list_topics",
-        description: "List topics in a wiki. Returns flat list or graph (nodes + edges). No authentication needed.",
+        description: "List topics in a wiki. Returns flat list or graph (nodes + edges). Requires login.",
         parameters: z.object({
             wiki_slug: z.string().describe("Wiki slug"),
             format: z.enum(["flat", "graph"]).default("flat").describe("Response format"),
         }),
         async execute({ wiki_slug, format }) {
             const resp = await request("GET", `/api/w/${wiki_slug}/topics`, {
+                auth: true,
                 params: { format },
             });
             return JSON.stringify(await resp.json(), null, 2);

package/dist/tools/wikis.js

@@ -1,6 +1,18 @@
 import { z } from "zod";
 import { request } from "../auth.js";
 import { coerceJson } from "../utils.js";
+const MAX_IMAGE_URL_LENGTH = 2048;
+const httpImageUrlSchema = z.string()
+    .max(MAX_IMAGE_URL_LENGTH)
+    .refine((value) => !value.startsWith("data:") && !value.includes("base64,"), "Use an http(s) image URL, not inline image data")
+    .refine((value) => value.startsWith("http://") || value.startsWith("https://"), "Image URL must start with http:// or https://");
+const coverImageUrlSchema = z.string()
+    .max(MAX_IMAGE_URL_LENGTH)
+    .refine((value) => value.startsWith("linear-gradient(") ||
+    value.startsWith("http://") ||
+    value.startsWith("https://"), "Cover image must be an http(s) URL or gallery gradient")
+    .refine((value) => value.startsWith("linear-gradient(") ||
+    (!value.startsWith("data:") && !value.includes("base64,")), "Use an http(s) image URL, not inline image data");
 // 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.
@@ -34,7 +46,7 @@ const navItemSchema = z.lazy(() => z.object({
 const themeSchema = z.object({
     accent_color: z.string().optional(),
     name_font: z.string().optional(),
-    logo_url: z.string().optional(),
+    logo_url: httpImageUrlSchema.nullable().optional(),
     cover_tint_intensity: z.number().optional(),
     logo_tint_intensity: z.number().optional(),
     cover_y_offset: z.number().optional(),
@@ -42,12 +54,13 @@ const themeSchema = z.object({
 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.",
+        description: "List every wiki on Almanac. 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. Requires login.",
         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", {
+                auth: true,
                 params: { include_global },
             });
             return JSON.stringify(await resp.json(), null, 2);
@@ -71,23 +84,23 @@ export function registerWikiTools(server) {
     });
     server.addTool({
         name: "get_wiki_settings",
-        description: "Read a wiki's details and settings (nav, cover, theme). No authentication needed.",
+        description: "Read a wiki's details and settings (nav, cover, theme). Requires login.",
         parameters: z.object({
             wiki_slug: z.string().describe("Wiki slug"),
         }),
         async execute({ wiki_slug }) {
-            const resp = await request("GET", `/api/w/${wiki_slug}`);
+            const resp = await request("GET", `/api/w/${wiki_slug}`, { auth: true });
             return JSON.stringify(await resp.json(), null, 2);
         },
     });
     server.addTool({
         name: "update_wiki_settings",
-        description: "Update a wiki's settings. Pass any combination of `nav`, `cover_image_url`, and `theme` — omitted fields are preserved (the backend uses exclude_unset merge). For example, `{nav: [...]}` updates navigation only without touching theme or cover_image_url. 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.",
+        description: "Update a wiki's settings. Pass any combination of `nav`, `cover_image_url`, and `theme` — omitted fields are preserved (the backend uses exclude_unset merge). For example, `{nav: [...]}` updates navigation only without touching theme or cover_image_url. `cover_image_url` accepts http(s) image URLs or gallery gradients; `theme.logo_url` accepts http(s) image URLs. Do not pass inline base64/data image strings. 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(navItemSchema).optional(),
-                cover_image_url: z.string().optional(),
+                cover_image_url: coverImageUrlSchema.nullable().optional(),
                 theme: themeSchema.optional(),
             })).describe("Settings to update"),
         }),

package/package.json

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