openalmanac 0.4.3 → 0.4.4

package/dist/tool-tracking.d.ts

@@ -1,14 +1,34 @@
 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;
@@ -21,6 +41,8 @@ interface ToolTrackingDeps {
     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;

package/dist/tool-tracking.js

@@ -1,31 +1,45 @@
+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" },
-    search_topics: { tool_group: "read", intent_domain: "search" },
-    list_pages: { tool_group: "read", intent_domain: "page_read" },
-    list_topics: { tool_group: "read", intent_domain: "page_read" },
-    list_wikis: { tool_group: "read", intent_domain: "wiki_management" },
-    download: { tool_group: "read", intent_domain: "page_read" },
-    read_page: { tool_group: "read", intent_domain: "page_read" },
-    search_web: { tool_group: "research", intent_domain: "web_research" },
-    read_webpage: { tool_group: "research", intent_domain: "web_research" },
-    search_images: { tool_group: "research", intent_domain: "web_research" },
-    view_images: { tool_group: "research", intent_domain: "web_research" },
-    new: { tool_group: "write", intent_domain: "page_write" },
-    publish: { tool_group: "write", intent_domain: "page_write" },
-    delete_pages: { tool_group: "write", intent_domain: "page_write" },
-    create_topics: { tool_group: "write", intent_domain: "topic_management" },
-    update_topic: { tool_group: "write", intent_domain: "topic_management" },
-    create_wiki: { tool_group: "wiki_admin", intent_domain: "wiki_management" },
-    get_wiki_settings: { tool_group: "wiki_admin", intent_domain: "wiki_management" },
-    update_wiki_settings: { tool_group: "wiki_admin", intent_domain: "wiki_management" },
-    join_wiki: { tool_group: "wiki_admin", intent_domain: "wiki_management" },
-    get_wiki_membership: { tool_group: "wiki_admin", intent_domain: "wiki_management" },
-    whoami: { tool_group: "account", intent_domain: "auth" },
+    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" };
+    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)
@@ -52,10 +66,11 @@ export function wrapMcpToolDefinition(definition, deps) {
         async execute(...args) {
             await validateAuth();
             const startedAt = now();
+            const trackingState = { details: {} };
             let success = false;
             let caught;
             try {
-                const result = await execute(...args);
+                const result = await trackingDetailsStorage.run(trackingState, async () => execute(...args));
                 success = true;
                 return result;
             }
@@ -67,6 +82,7 @@ export function wrapMcpToolDefinition(definition, deps) {
                 const event = {
                     tool_name: definition.name,
                     ...metadata,
+                    ...trackingState.details,
                     success,
                     duration_ms: Math.max(0, Math.round(now() - startedAt)),
                     mcp_version: deps.mcpVersion,

package/dist/tools/pages/index.js

@@ -3,10 +3,34 @@ 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",
@@ -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;

package/package.json

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