@roam-research/roam-tools-core 0.4.2 → 0.5.0

package/dist/graph-resolver.js

@@ -288,7 +288,7 @@ export async function resolveGraph(providedGraph) {
         if (!graphConfig) {
             throw new RoamError(`Graph "${providedGraph}" not found in config. Available graph nicknames are listed below.`, ErrorCodes.GRAPH_NOT_CONFIGURED, {
                 available_graphs: await getConfiguredGraphs(),
-                instruction: "Pass the 'nickname' value as the graph parameter. Before operating on a graph, call get_graph_guidelines to understand its conventions.",
+                instruction: "Pass the 'nickname' value as the graph parameter. After identifying which graph to use, ALWAYS call get_graph_guidelines next — it returns essential context and orientation for the session.",
             });
         }
         return {
@@ -315,7 +315,7 @@ export async function resolveGraph(providedGraph) {
     // 3. Multiple graphs - require explicit selection
     throw new RoamError("Multiple graphs configured. Pass a graph nickname as the graph parameter to specify which graph to use.", ErrorCodes.GRAPH_NOT_SELECTED, {
         available_graphs: await getConfiguredGraphs(),
-        instruction: "Pass the 'nickname' value as the graph parameter. Before operating on a graph, call get_graph_guidelines to understand its conventions.",
+        instruction: "Pass the 'nickname' value as the graph parameter. After identifying which graph to use, ALWAYS call get_graph_guidelines next — it returns essential context and orientation for the session.",
     });
 }
 /**

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export type { CallToolResult, TextContent, ImageContent, GraphType, AccessLevel, GraphConfig, RoamMcpConfig, ResolvedGraph, ErrorCode, RoamApiError, RoamResponse, RoamClientConfig, Block, Page, BlockLocation, WindowType, SidebarWindow, SidebarWindowInfo, FocusedBlock, SelectedBlock, MainWindowViewType, MainWindowView, SearchResultPath, SearchResult, SearchResponse, Template, QueryResult, QueryResponse, TokenInfoResponse, TokenInfoResult, } from "./types.js";
+export type { CallToolResult, TextContent, ImageContent, GraphType, AccessLevel, GraphConfig, RoamMcpConfig, ResolvedGraph, ErrorCode, RoamApiError, RoamResponse, RoamClientConfig, Block, Page, BlockLocation, WindowType, SidebarWindow, SidebarWindowInfo, FocusedBlock, SelectedBlock, MainWindowViewType, MainWindowView, SearchResultPath, SearchResult, SearchResponse, RecentlyOpenedBlock, RecentlyOpenedItem, DailyNotePagesViewItem, RecentlyEditedPage, SearchSuggestionsResponse, SearchTemplatesResponse, GetPageResponse, GetBlockResponse, Template, QueryResult, QueryResponse, TokenInfoResponse, TokenInfoResult, } from "./types.js";
 export { GraphConfigSchema, RoamMcpConfigSchema, ErrorCodes, RoamError, CONFIG_VERSION, EXPECTED_API_VERSION, textResult, imageResult, errorResult, getErrorMessage, } from "./types.js";
 export { RoamClient } from "./client.js";
 export { getPort, resolveGraph, saveGraphToConfig, removeGraphFromConfig, updateGraphTokenStatus, getConfiguredGraphsSafe, getConfiguredGraphs, findGraphConfig, getMcpConfig, getOpenGraphs, } from "./graph-resolver.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,YAAY,EACV,cAAc,EAAE,WAAW,EAAE,YAAY,EACzC,SAAS,EAAE,WAAW,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EACjE,SAAS,EAAE,YAAY,EAAE,YAAY,EAAE,gBAAgB,EACvD,KAAK,EAAE,IAAI,EAAE,aAAa,EAC1B,UAAU,EAAE,aAAa,EAAE,iBAAiB,EAC5C,YAAY,EAAE,aAAa,EAC3B,kBAAkB,EAAE,cAAc,EAClC,gBAAgB,EAAE,YAAY,EAAE,cAAc,EAC9C,QAAQ,EAAE,WAAW,EAAE,aAAa,EACpC,iBAAiB,EAAE,eAAe,GACnC,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,iBAAiB,EAAE,mBAAmB,EACtC,UAAU,EAAE,SAAS,EACrB,cAAc,EAAE,oBAAoB,EACpC,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,eAAe,GACtD,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,OAAO,EACL,OAAO,EAAE,YAAY,EACrB,iBAAiB,EAAE,qBAAqB,EAAE,sBAAsB,EAChE,uBAAuB,EAAE,mBAAmB,EAAE,eAAe,EAC7D,YAAY,EAAE,aAAa,GAC5B,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,oBAAoB,EAAE,YAAY,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,GAChE,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,cAAc,EAAE,cAAc,EAAE,qBAAqB,GACtD,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC5D,YAAY,EACV,cAAc,EAAE,oBAAoB,EAAE,wBAAwB,GAC/D,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,YAAY,EACV,cAAc,EAAE,WAAW,EAAE,YAAY,EACzC,SAAS,EAAE,WAAW,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EACjE,SAAS,EAAE,YAAY,EAAE,YAAY,EAAE,gBAAgB,EACvD,KAAK,EAAE,IAAI,EAAE,aAAa,EAC1B,UAAU,EAAE,aAAa,EAAE,iBAAiB,EAC5C,YAAY,EAAE,aAAa,EAC3B,kBAAkB,EAAE,cAAc,EAClC,gBAAgB,EAAE,YAAY,EAAE,cAAc,EAC9C,mBAAmB,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,kBAAkB,EACnF,yBAAyB,EAAE,uBAAuB,EAClD,eAAe,EAAE,gBAAgB,EACjC,QAAQ,EAAE,WAAW,EAAE,aAAa,EACpC,iBAAiB,EAAE,eAAe,GACnC,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,iBAAiB,EAAE,mBAAmB,EACtC,UAAU,EAAE,SAAS,EACrB,cAAc,EAAE,oBAAoB,EACpC,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,eAAe,GACtD,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,OAAO,EACL,OAAO,EAAE,YAAY,EACrB,iBAAiB,EAAE,qBAAqB,EAAE,sBAAsB,EAChE,uBAAuB,EAAE,mBAAmB,EAAE,eAAe,EAC7D,YAAY,EAAE,aAAa,GAC5B,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,oBAAoB,EAAE,YAAY,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,GAChE,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,cAAc,EAAE,cAAc,EAAE,qBAAqB,GACtD,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC5D,YAAY,EACV,cAAc,EAAE,oBAAoB,EAAE,wBAAwB,GAC/D,MAAM,YAAY,CAAC"}

package/dist/operations/blocks.d.ts

@@ -2,16 +2,25 @@ import { z } from "zod";
 import type { RoamClient } from "../client.js";
 import type { CallToolResult } from "../types.js";
 export declare const CreateBlockSchema: z.ZodObject<{
-    parentUid: z.ZodString;
+    parentUid: z.ZodOptional<z.ZodString>;
+    pageTitle: z.ZodOptional<z.ZodString>;
+    dailyNotePage: z.ZodOptional<z.ZodString>;
+    nestUnder: z.ZodOptional<z.ZodString>;
     markdown: z.ZodString;
     order: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodEnum<["first", "last"]>]>>;
 }, "strip", z.ZodTypeAny, {
     markdown: string;
-    parentUid: string;
+    parentUid?: string | undefined;
+    pageTitle?: string | undefined;
+    dailyNotePage?: string | undefined;
+    nestUnder?: string | undefined;
     order?: number | "first" | "last" | undefined;
 }, {
     markdown: string;
-    parentUid: string;
+    parentUid?: string | undefined;
+    pageTitle?: string | undefined;
+    dailyNotePage?: string | undefined;
+    nestUnder?: string | undefined;
     order?: number | "first" | "last" | undefined;
 }>;
 export declare const GetBlockSchema: z.ZodObject<{
@@ -71,25 +80,25 @@ export declare const GetBacklinksSchema: z.ZodObject<{
     includePath: z.ZodOptional<z.ZodBoolean>;
     maxDepth: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
-    title?: string | undefined;
     sort?: "created-date" | "edited-date" | "daily-note-date" | undefined;
-    search?: string | undefined;
     uid?: string | undefined;
-    maxDepth?: number | undefined;
-    offset?: number | undefined;
-    limit?: number | undefined;
+    title?: string | undefined;
     sortOrder?: "asc" | "desc" | undefined;
     includePath?: boolean | undefined;
+    offset?: number | undefined;
+    limit?: number | undefined;
+    maxDepth?: number | undefined;
+    search?: string | undefined;
 }, {
-    title?: string | undefined;
     sort?: "created-date" | "edited-date" | "daily-note-date" | undefined;
-    search?: string | undefined;
     uid?: string | undefined;
-    maxDepth?: number | undefined;
-    offset?: number | undefined;
-    limit?: number | undefined;
+    title?: string | undefined;
     sortOrder?: "asc" | "desc" | undefined;
     includePath?: boolean | undefined;
+    offset?: number | undefined;
+    limit?: number | undefined;
+    maxDepth?: number | undefined;
+    search?: string | undefined;
 }>;
 export type CreateBlockParams = z.infer<typeof CreateBlockSchema>;
 export type GetBlockParams = z.infer<typeof GetBlockSchema>;
@@ -108,6 +117,7 @@ export interface BacklinkResult {
     }>;
 }
 export interface GetBacklinksResponse {
+    queriedAt?: string;
     total: number;
     results: BacklinkResult[];
 }
@@ -117,4 +127,44 @@ export declare function updateBlock(client: RoamClient, params: UpdateBlockParam
 export declare function deleteBlock(client: RoamClient, params: DeleteBlockParams): Promise<CallToolResult>;
 export declare function moveBlock(client: RoamClient, params: MoveBlockParams): Promise<CallToolResult>;
 export declare function getBacklinks(client: RoamClient, params: GetBacklinksParams): Promise<CallToolResult>;
+export declare const AddCommentSchema: z.ZodObject<{
+    blockUid: z.ZodString;
+    comment: z.ZodOptional<z.ZodString>;
+    commentMarkdown: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    blockUid: string;
+    comment?: string | undefined;
+    commentMarkdown?: string | undefined;
+}, {
+    blockUid: string;
+    comment?: string | undefined;
+    commentMarkdown?: string | undefined;
+}>;
+export declare const GetCommentsSchema: z.ZodObject<{
+    blockUid: z.ZodString;
+    maxDepth: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    blockUid: string;
+    maxDepth?: number | undefined;
+}, {
+    blockUid: string;
+    maxDepth?: number | undefined;
+}>;
+export type AddCommentParams = z.infer<typeof AddCommentSchema>;
+export type GetCommentsParams = z.infer<typeof GetCommentsSchema>;
+export interface CommentResult {
+    parentUid: string;
+    author: string;
+    createdTime: string;
+    editedTime: string;
+    markdown: string;
+    singleEditableUid: string | null;
+}
+export interface GetCommentsResponse {
+    queriedAt?: string;
+    total: number;
+    comments: CommentResult[];
+}
+export declare function addComment(client: RoamClient, params: AddCommentParams): Promise<CallToolResult>;
+export declare function getComments(client: RoamClient, params: GetCommentsParams): Promise<CallToolResult>;
 //# sourceMappingURL=blocks.d.ts.map

package/dist/operations/blocks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"blocks.d.ts","sourceRoot":"","sources":["../../src/operations/blocks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAIlD,eAAO,MAAM,iBAAiB;;;;;;;;;;;;EAI5B,CAAC;AAEH,eAAO,MAAM,cAAc;;;;;;;;;EAGzB,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;EAK5B,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;;;EAE5B,CAAC;AAEH,eAAO,MAAM,eAAe;;;;;;;;;;;;EAI1B,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAU7B,CAAC;AAGH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAClE,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAC5D,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAClE,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAClE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAC9D,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAGpE,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChE;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,cAAc,EAAE,CAAC;CAC3B;AAED,wBAAsB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,cAAc,CAAC,CAWxG;AAED,wBAAsB,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAMlG;AAED,wBAAsB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,cAAc,CAAC,CAQxG;AAED,wBAAsB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,cAAc,CAAC,CAGxG;AAED,wBAAsB,SAAS,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAapG;AAED,wBAAsB,YAAY,CAChC,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,cAAc,CAAC,CAezB"}
+{"version":3,"file":"blocks.d.ts","sourceRoot":"","sources":["../../src/operations/blocks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAoB,MAAM,aAAa,CAAC;AAIpE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;EAiB5B,CAAC;AAEH,eAAO,MAAM,cAAc;;;;;;;;;EAGzB,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;EAK5B,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;;;EAE5B,CAAC;AAEH,eAAO,MAAM,eAAe;;;;;;;;;;;;EAI1B,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAU7B,CAAC;AAGH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAClE,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAC5D,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAClE,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAClE,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAC9D,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAGpE,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChE;AAED,MAAM,WAAW,oBAAoB;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,cAAc,EAAE,CAAC;CAC3B;AAED,wBAAsB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,cAAc,CAAC,CAkCxG;AAED,wBAAsB,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAMlG;AAED,wBAAsB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,cAAc,CAAC,CAQxG;AAED,wBAAsB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,cAAc,CAAC,CAGxG;AAED,wBAAsB,SAAS,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAapG;AAED,wBAAsB,YAAY,CAChC,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,cAAc,CAAC,CAezB;AAID,eAAO,MAAM,gBAAgB;;;;;;;;;;;;EAI3B,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;;;;;;EAG5B,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAChE,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC3B;AAED,wBAAsB,UAAU,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,CAAC,CAiBtG;AAED,wBAAsB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,cAAc,CAAC,CAMxG"}

package/dist/operations/blocks.js

@@ -1,8 +1,11 @@
 import { z } from "zod";
-import { textResult } from "../types.js";
+import { textResult, RoamError, ErrorCodes } from "../types.js";
 // Schemas
 export const CreateBlockSchema = z.object({
-    parentUid: z.string().describe("UID of parent block or page"),
+    parentUid: z.string().optional().describe("UID of parent block or page. Exactly one of parentUid, pageTitle, or dailyNotePage is required."),
+    pageTitle: z.string().optional().describe("Page title to create block under (creates the page if it doesn't exist). Exactly one of parentUid, pageTitle, or dailyNotePage is required."),
+    dailyNotePage: z.string().regex(/^\d{2}-\d{2}-\d{4}$/, "Must be MM-DD-YYYY format (e.g. '03-17-2026')").optional().describe("Daily note date in MM-DD-YYYY format (e.g. '03-17-2026'). Targets that day's daily note page, creating it if needed. Exactly one of parentUid, pageTitle, or dailyNotePage is required."),
+    nestUnder: z.string().optional().describe("Insert under a direct child block matching this string (matches on the block's string field, including markup like **bold** or [[links]]). If no match exists, creates a new child block with this text first, then inserts under it. Works with parentUid, pageTitle, or dailyNotePage."),
     markdown: z.string().describe("Markdown content for the block"),
     order: z.union([z.coerce.number(), z.enum(["first", "last"])]).optional().describe("Position (number, 'first', or 'last'). Defaults to 'last'"),
 });
@@ -36,14 +39,31 @@ export const GetBacklinksSchema = z.object({
     maxDepth: z.coerce.number().optional().describe("Max depth of children to include in markdown (default: 2)"),
 });
 export async function createBlock(client, params) {
+    // Validate: exactly one of parentUid, pageTitle, or dailyNotePage
+    const targets = [params.parentUid, params.pageTitle, params.dailyNotePage].filter(v => v !== undefined);
+    if (targets.length === 0) {
+        throw new RoamError("Either 'parentUid', 'pageTitle', or 'dailyNotePage' is required to specify where to create the block", ErrorCodes.VALIDATION_ERROR);
+    }
+    if (targets.length > 1) {
+        throw new RoamError("Provide only one of 'parentUid', 'pageTitle', or 'dailyNotePage'", ErrorCodes.VALIDATION_ERROR);
+    }
+    const location = {
+        order: params.order ?? "last",
+    };
+    if (params.parentUid !== undefined) {
+        location["parent-uid"] = params.parentUid;
+    }
+    else if (params.dailyNotePage !== undefined) {
+        location["page-title"] = { "daily-note-page": params.dailyNotePage };
+    }
+    else {
+        location["page-title"] = params.pageTitle;
+    }
+    if (params.nestUnder !== undefined) {
+        location["nest-under-str"] = params.nestUnder;
+    }
     const response = await client.call("data.block.fromMarkdown", [
-        {
-            location: {
-                "parent-uid": params.parentUid,
-                order: params.order ?? "last",
-            },
-            "markdown-string": params.markdown,
-        },
+        { location, "markdown-string": params.markdown },
     ]);
     return textResult(response.result ?? { uids: [] });
 }
@@ -106,3 +126,38 @@ export async function getBacklinks(client, params) {
     const response = await client.call("data.ai.getBacklinks", [apiParams]);
     return textResult(response.result ?? { total: 0, results: [] });
 }
+// --- Comments ---
+export const AddCommentSchema = z.object({
+    blockUid: z.string().describe("UID of the block to comment on"),
+    comment: z.string().optional().describe("Plain text comment (single block, editable later via update_block). Required if commentMarkdown not provided. Preferred for simple comments."),
+    commentMarkdown: z.string().optional().describe("Markdown comment parsed into multiple blocks. Required if comment not provided. Use only when you need structure (lists, headings). Harder to edit later."),
+});
+export const GetCommentsSchema = z.object({
+    blockUid: z.string().describe("UID of the block to get comments for"),
+    maxDepth: z.coerce.number().optional().describe("Max depth of children to include in each comment's markdown (omit for full tree)"),
+});
+export async function addComment(client, params) {
+    // Validate: exactly one of comment or commentMarkdown must be provided
+    const hasComment = params.comment !== undefined;
+    const hasCommentMarkdown = params.commentMarkdown !== undefined;
+    if (!hasComment && !hasCommentMarkdown) {
+        throw new RoamError("Provide one of 'comment' or 'commentMarkdown'", ErrorCodes.VALIDATION_ERROR);
+    }
+    if (hasComment && hasCommentMarkdown) {
+        throw new RoamError("Provide 'comment' or 'commentMarkdown', not both", ErrorCodes.VALIDATION_ERROR);
+    }
+    const apiParams = { "block-uid": params.blockUid };
+    if (hasComment)
+        apiParams["reply-string"] = params.comment;
+    if (hasCommentMarkdown)
+        apiParams["reply-markdown"] = params.commentMarkdown;
+    const response = await client.call("data.block.addComment", [apiParams]);
+    return textResult(response.result ?? { uids: [] });
+}
+export async function getComments(client, params) {
+    const apiParams = { uid: params.blockUid };
+    if (params.maxDepth !== undefined)
+        apiParams.maxDepth = params.maxDepth;
+    const response = await client.call("data.ai.getComments", [apiParams]);
+    return textResult(response.result ?? { total: 0, comments: [] });
+}

package/dist/operations/files.d.ts

@@ -16,14 +16,14 @@ export declare const FileUploadSchema: z.ZodObject<{
     filename: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     url?: string | undefined;
-    base64?: string | undefined;
     filePath?: string | undefined;
+    base64?: string | undefined;
     mimetype?: string | undefined;
     filename?: string | undefined;
 }, {
     url?: string | undefined;
-    base64?: string | undefined;
     filePath?: string | undefined;
+    base64?: string | undefined;
     mimetype?: string | undefined;
     filename?: string | undefined;
 }>;

package/dist/operations/graphs.js

@@ -33,7 +33,7 @@ export async function listGraphs() {
         const graphs = await getConfiguredGraphs();
         return textResult({
             graphs,
-            instruction: "Pass the 'nickname' value as the graph parameter. Before operating on a graph, call get_graph_guidelines to understand its conventions.",
+            instruction: "Pass the 'nickname' value as the graph parameter. After identifying which graph to use, ALWAYS call get_graph_guidelines next — it returns essential context and orientation for the session.",
             setup: "To connect additional graphs, use the setup_new_graph tool (call it without arguments to see available graphs).",
         });
     }

package/dist/operations/navigation.d.ts

@@ -7,21 +7,21 @@ export declare const OpenMainWindowSchema: z.ZodObject<{
     uid: z.ZodOptional<z.ZodString>;
     title: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    title?: string | undefined;
     uid?: string | undefined;
-}, {
     title?: string | undefined;
+}, {
     uid?: string | undefined;
+    title?: string | undefined;
 }>;
 export declare const OpenSidebarSchema: z.ZodObject<{
     uid: z.ZodString;
     type: z.ZodOptional<z.ZodEnum<["block", "outline", "mentions"]>>;
 }, "strip", z.ZodTypeAny, {
     uid: string;
-    type?: "mentions" | "block" | "outline" | undefined;
+    type?: "block" | "outline" | "mentions" | undefined;
 }, {
     uid: string;
-    type?: "mentions" | "block" | "outline" | undefined;
+    type?: "block" | "outline" | "mentions" | undefined;
 }>;
 export type OpenMainWindowParams = z.infer<typeof OpenMainWindowSchema>;
 export type OpenSidebarParams = z.infer<typeof OpenSidebarSchema>;

package/dist/operations/pages.d.ts

@@ -7,24 +7,24 @@ export declare const CreatePageSchema: z.ZodObject<{
     uid: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     title: string;
-    markdown?: string | undefined;
     uid?: string | undefined;
+    markdown?: string | undefined;
 }, {
     title: string;
-    markdown?: string | undefined;
     uid?: string | undefined;
+    markdown?: string | undefined;
 }>;
 export declare const GetPageSchema: z.ZodObject<{
     title: z.ZodOptional<z.ZodString>;
     uid: z.ZodOptional<z.ZodString>;
     maxDepth: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
-    title?: string | undefined;
     uid?: string | undefined;
+    title?: string | undefined;
     maxDepth?: number | undefined;
 }, {
-    title?: string | undefined;
     uid?: string | undefined;
+    title?: string | undefined;
     maxDepth?: number | undefined;
 }>;
 export declare const DeletePageSchema: z.ZodObject<{
@@ -42,12 +42,12 @@ export declare const UpdatePageSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     uid: string;
     title?: string | undefined;
-    childrenViewType?: "bullet" | "numbered" | "document" | undefined;
+    childrenViewType?: "document" | "bullet" | "numbered" | undefined;
     mergePages?: boolean | undefined;
 }, {
     uid: string;
     title?: string | undefined;
-    childrenViewType?: "bullet" | "numbered" | "document" | undefined;
+    childrenViewType?: "document" | "bullet" | "numbered" | undefined;
     mergePages?: boolean | undefined;
 }>;
 export declare const GetGuidelinesSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;

package/dist/operations/pages.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pages.d.ts","sourceRoot":"","sources":["../../src/operations/pages.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAIlD,eAAO,MAAM,gBAAgB;;;;;;;;;;;;EAI3B,CAAC;AAEH,eAAO,MAAM,aAAa;;;;;;;;;;;;EAIxB,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;;;EAE3B,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;EAK3B,CAAC;AAEH,eAAO,MAAM,mBAAmB,gDAAe,CAAC;AAGhD,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAChE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAC1D,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAChE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE,wBAAsB,UAAU,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,CAAC,CAQtG;AAED,wBAAsB,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAMhG;AAED,wBAAsB,UAAU,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,CAAC,CAGtG;AAED,wBAAsB,UAAU,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,CAAC,CAUtG;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,CAAC,CAK/E"}
+{"version":3,"file":"pages.d.ts","sourceRoot":"","sources":["../../src/operations/pages.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAmB,MAAM,aAAa,CAAC;AAInE,eAAO,MAAM,gBAAgB;;;;;;;;;;;;EAI3B,CAAC;AAEH,eAAO,MAAM,aAAa;;;;;;;;;;;;EAIxB,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;;;EAE3B,CAAC;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;EAK3B,CAAC;AAEH,eAAO,MAAM,mBAAmB,gDAAe,CAAC;AAGhD,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAChE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAC1D,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAChE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEhE,wBAAsB,UAAU,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,CAAC,CAQtG;AAED,wBAAsB,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAMhG;AAED,wBAAsB,UAAU,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,CAAC,CAGtG;AAED,wBAAsB,UAAU,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,CAAC,CAUtG;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,CAAC,CAwB/E"}

package/dist/operations/pages.js

@@ -55,5 +55,13 @@ export async function updatePage(client, params) {
 }
 export async function getGuidelines(client) {
     const response = await client.call("data.ai.getGraphGuidelines", []);
-    return textResult(response.result ?? { guidelines: null, starredPages: [] });
+    const result = response.result ?? { guidelines: null, starredPages: [], todaysDailyNotePage: null };
+    const dnpTitle = result.todaysDailyNotePage;
+    const nextSteps = dnpTitle
+        ? `Start by reading today's daily note page ("${dnpTitle}") with get_page — this is the user's primary workspace for the day. If you need more context, call search with an empty query for recently edited and viewed content. Skip these orientation steps only when the user has already given you a specific task to execute (e.g. "create a page called X").`
+        : `Start by calling search with an empty query to see recently edited and viewed content. Skip this only when the user has already given you a specific task to execute.`;
+    return textResult({
+        ...result,
+        nextSteps,
+    });
 }

package/dist/operations/query.d.ts

@@ -13,21 +13,21 @@ export declare const QuerySchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     sort?: "created-date" | "edited-date" | "daily-note-date" | undefined;
     uid?: string | undefined;
-    maxDepth?: number | undefined;
-    offset?: number | undefined;
-    limit?: number | undefined;
+    query?: string | undefined;
     sortOrder?: "asc" | "desc" | undefined;
     includePath?: boolean | undefined;
-    query?: string | undefined;
+    offset?: number | undefined;
+    limit?: number | undefined;
+    maxDepth?: number | undefined;
 }, {
     sort?: "created-date" | "edited-date" | "daily-note-date" | undefined;
     uid?: string | undefined;
-    maxDepth?: number | undefined;
-    offset?: number | undefined;
-    limit?: number | undefined;
+    query?: string | undefined;
     sortOrder?: "asc" | "desc" | undefined;
     includePath?: boolean | undefined;
-    query?: string | undefined;
+    offset?: number | undefined;
+    limit?: number | undefined;
+    maxDepth?: number | undefined;
 }>;
 export type QueryParams = z.infer<typeof QuerySchema>;
 export declare function query(client: RoamClient, params: QueryParams): Promise<CallToolResult>;

package/dist/operations/search.d.ts

@@ -10,17 +10,17 @@ export declare const SearchSchema: z.ZodObject<{
     maxDepth: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     query: string;
-    maxDepth?: number | undefined;
+    includePath?: boolean | undefined;
     offset?: number | undefined;
     limit?: number | undefined;
-    includePath?: boolean | undefined;
+    maxDepth?: number | undefined;
     scope?: "pages" | "blocks" | "all" | undefined;
 }, {
     query: string;
-    maxDepth?: number | undefined;
+    includePath?: boolean | undefined;
     offset?: number | undefined;
     limit?: number | undefined;
-    includePath?: boolean | undefined;
+    maxDepth?: number | undefined;
     scope?: "pages" | "blocks" | "all" | undefined;
 }>;
 export declare const SearchTemplatesSchema: z.ZodObject<{

package/dist/operations/search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/operations/search.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAA4B,cAAc,EAAE,MAAM,aAAa,CAAC;AAI5E,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;EAOvB,CAAC;AAEH,eAAO,MAAM,qBAAqB;;;;;;EAEhC,CAAC;AAGH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AACxD,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE1E,wBAAsB,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC,CAY9F;AAED,wBAAsB,eAAe,CACnC,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,cAAc,CAAC,CAKzB"}
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/operations/search.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAsE,cAAc,EAAE,MAAM,aAAa,CAAC;AAItH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;EAOvB,CAAC;AAEH,eAAO,MAAM,qBAAqB;;;;;;EAEhC,CAAC;AAGH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AACxD,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE1E,wBAAsB,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC,CAY9F;AAED,wBAAsB,eAAe,CACnC,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,cAAc,CAAC,CAKzB"}

package/dist/operations/search.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { textResult } from "../types.js";
 // Schemas
 export const SearchSchema = z.object({
-    query: z.string().describe("Search query"),
+    query: z.string().describe("Search query — use empty string to get recently edited and viewed content"),
     scope: z.enum(["pages", "blocks", "all"]).optional().describe("Search scope: 'pages' for page titles only, 'blocks' for block content only, 'all' for both (default: 'all')"),
     offset: z.coerce.number().optional().describe("Skip first N results (default: 0)"),
     limit: z.coerce.number().optional().describe("Max results (default: 20)"),
@@ -29,5 +29,5 @@ export async function searchTemplates(client, params) {
     const response = await client.call("data.ai.searchTemplates", [
         { query: params.query },
     ]);
-    return textResult(response.result ?? []);
+    return textResult(response.result ?? { results: [] });
 }

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,cAAc,EAAkC,MAAM,YAAY,CAAC;AAEjF,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA8BzC,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;IACnC,MAAM,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IACvE,IAAI,EAAE,QAAQ,CAAC;CAChB;AAGD,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;IACnC,MAAM,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IACnD,IAAI,EAAE,YAAY,CAAC;CACpB;AAED,MAAM,MAAM,cAAc,GAAG,oBAAoB,GAAG,wBAAwB,CAAC;AAmL7E,eAAO,MAAM,KAAK,EAAE,cAAc,EAGjC,CAAC;AAEF,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAEjE;AA0FD,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,cAAc,CAAC,CA+HzB"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,cAAc,EAAkC,MAAM,YAAY,CAAC;AAEjF,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA+BzC,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;IACnC,MAAM,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IACvE,IAAI,EAAE,QAAQ,CAAC;CAChB;AAGD,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;IACnC,MAAM,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IACnD,IAAI,EAAE,YAAY,CAAC;CACpB;AAED,MAAM,MAAM,cAAc,GAAG,oBAAoB,GAAG,wBAAwB,CAAC;AA+L7E,eAAO,MAAM,KAAK,EAAE,cAAc,EAGjC,CAAC;AAEF,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAEjE;AA0FD,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,cAAc,CAAC,CA+HzB"}

package/dist/tools.js

@@ -3,7 +3,7 @@ import { RoamError } from "./types.js";
 import { RoamClient } from "./client.js";
 import { resolveGraph, getPort, updateGraphTokenStatus } from "./graph-resolver.js";
 import { CreatePageSchema, GetPageSchema, DeletePageSchema, UpdatePageSchema, GetGuidelinesSchema, createPage, getPage, deletePage, updatePage, getGuidelines, } from "./operations/pages.js";
-import { CreateBlockSchema, GetBlockSchema, UpdateBlockSchema, DeleteBlockSchema, MoveBlockSchema, GetBacklinksSchema, createBlock, getBlock, updateBlock, deleteBlock, moveBlock, getBacklinks, } from "./operations/blocks.js";
+import { CreateBlockSchema, GetBlockSchema, UpdateBlockSchema, DeleteBlockSchema, MoveBlockSchema, GetBacklinksSchema, AddCommentSchema, GetCommentsSchema, createBlock, getBlock, updateBlock, deleteBlock, moveBlock, getBacklinks, addComment, getComments, } from "./operations/blocks.js";
 import { SearchSchema, SearchTemplatesSchema, search, searchTemplates } from "./operations/search.js";
 import { QuerySchema, query } from "./operations/query.js";
 import { GetOpenWindowsSchema, GetSelectionSchema, OpenMainWindowSchema, OpenSidebarSchema, getOpenWindows, getSelection, openMainWindow, openSidebar, } from "./operations/navigation.js";
@@ -46,15 +46,17 @@ const graphManagementTools = [
 const GUIDELINES_NOTE = "\n\nNote: Call get_graph_guidelines first when starting to work with a graph.";
 // Content Tools (require graph/client)
 const contentTools = [
-    defineTool("get_graph_guidelines", "IMPORTANT: Call this tool first when starting to work with a graph, before performing any other operations. Returns user-defined instructions and preferences for AI agents. The user may have specified naming conventions, preferred structures, or constraints that should guide your behavior.", GetGuidelinesSchema, getGuidelines),
+    defineTool("get_graph_guidelines", "IMPORTANT: Call this tool first when starting to work with a graph, before performing any other operations. Returns user-defined instructions and preferences for AI agents. The user may have specified naming conventions, preferred structures, or constraints that should guide your behavior. After receiving the response, follow the nextSteps field — it contains orientation actions you should take before proceeding.", GetGuidelinesSchema, getGuidelines),
     defineTool("create_page", "Create a new page in Roam, optionally with markdown content." + GUIDELINES_NOTE, CreatePageSchema, createPage),
-    defineTool("create_block", "Create a new block under a parent, using markdown content. Supports nested bulleted lists - pass a markdown string with `- ` list items and indentation to create an entire block hierarchy in a single call." + GUIDELINES_NOTE, CreateBlockSchema, createBlock),
+    defineTool("create_block", "Create blocks from markdown content. Target by parentUid, pageTitle, or dailyNotePage (page created if needed). Use nestUnder to insert under a specific child block. Supports nested bulleted lists via markdown indentation." + GUIDELINES_NOTE, CreateBlockSchema, createBlock),
     defineTool("update_block", "Update an existing block's content or properties." + GUIDELINES_NOTE, UpdateBlockSchema, updateBlock),
     defineTool("delete_block", "Delete a block and all its children." + GUIDELINES_NOTE, DeleteBlockSchema, deleteBlock),
     defineTool("move_block", "Move a block to a new location." + GUIDELINES_NOTE, MoveBlockSchema, moveBlock),
+    defineTool("add_comment", "Add a comment to a block (comment thread, NOT a child block). Prefer `comment` for simple text; use `commentMarkdown` for structured content. Same-day calls on the same block append to your existing comment." + GUIDELINES_NOTE, AddCommentSchema, addComment),
+    defineTool("get_comments", "Get comments on a block with author, timestamps, and edit info. If singleEditableUid is set, the comment can be edited with update_block. Only works for blocks, not pages." + GUIDELINES_NOTE, GetCommentsSchema, getComments),
     defineTool("delete_page", "Delete a page and all its contents." + GUIDELINES_NOTE, DeletePageSchema, deletePage),
     defineTool("update_page", "Update a page's title or children view type. Set mergePages to true if renaming to a title that already exists." + GUIDELINES_NOTE, UpdatePageSchema, updatePage),
-    defineTool("search", "Search for pages and blocks by text. Returns paginated results with markdown content and optional breadcrumb paths." + GUIDELINES_NOTE, SearchSchema, search),
+    defineTool("search", "Search for pages and blocks by text. Returns paginated results with markdown content and optional breadcrumb paths. Call with an empty query to get recently edited and viewed content — useful for understanding what the user is currently working on." + GUIDELINES_NOTE, SearchSchema, search),
     defineTool("search_templates", "Search Roam templates by name. When the user mentions 'my X template' or 'the X template', use this tool to find it. Templates are user-created reusable content blocks tagged with [[roam/templates]]. Returns template name, uid, and content as markdown." + GUIDELINES_NOTE, SearchTemplatesSchema, searchTemplates),
     defineTool("roam_query", 'Execute a Roam query ({{query: }} or {{[[query]]: }} blocks, NOT Datalog). Two modes: (1) UID mode - pass a block UID containing a query component to run it with saved settings/filters; (2) Query mode - pass a raw query string like "{and: [[TODO]] {not: [[DONE]]}}". Returns paginated results with markdown content.' + GUIDELINES_NOTE, QuerySchema, query),
     defineTool("get_page", "Get a page's content as markdown. Returns content with <roam> metadata tags containing UIDs - use these for follow-up operations but strip them when showing content to the user. Show remaining content verbatim, never paraphrase. Use maxDepth for large pages." + GUIDELINES_NOTE, GetPageSchema, getPage),

package/dist/types.d.ts

@@ -14,8 +14,8 @@ export declare const GraphConfigSchema: z.ZodObject<{
     accessLevel: z.ZodOptional<z.ZodEnum<["read-only", "read-append", "full"]>>;
     lastKnownTokenStatus: z.ZodOptional<z.ZodEnum<["active", "revoked"]>>;
 }, "strip", z.ZodTypeAny, {
-    type: "hosted" | "offline";
     name: string;
+    type: "hosted" | "offline";
     token: string;
     nickname: string;
     accessLevel?: "read-only" | "read-append" | "full" | undefined;
@@ -39,8 +39,8 @@ export declare const RoamMcpConfigSchema: z.ZodObject<{
         accessLevel: z.ZodOptional<z.ZodEnum<["read-only", "read-append", "full"]>>;
         lastKnownTokenStatus: z.ZodOptional<z.ZodEnum<["active", "revoked"]>>;
     }, "strip", z.ZodTypeAny, {
-        type: "hosted" | "offline";
         name: string;
+        type: "hosted" | "offline";
         token: string;
         nickname: string;
         accessLevel?: "read-only" | "read-append" | "full" | undefined;
@@ -55,8 +55,8 @@ export declare const RoamMcpConfigSchema: z.ZodObject<{
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
     graphs: {
-        type: "hosted" | "offline";
         name: string;
+        type: "hosted" | "offline";
         token: string;
         nickname: string;
         accessLevel?: "read-only" | "read-append" | "full" | undefined;
@@ -112,7 +112,7 @@ export declare class RoamError extends Error {
     constructor(message: string, code?: ErrorCode | undefined, context?: Record<string, unknown> | undefined);
 }
 export declare const CONFIG_VERSION = 1;
-export declare const EXPECTED_API_VERSION = "1.1.0";
+export declare const EXPECTED_API_VERSION = "1.1.2";
 export interface RoamApiError {
     message: string;
     code?: string;
@@ -188,14 +188,64 @@ export interface SearchResult {
     type?: "page";
 }
 export interface SearchResponse {
+    queriedAt?: string;
     total: number;
     results: SearchResult[];
 }
+export interface RecentlyOpenedBlock {
+    uid: string;
+    string: string;
+    openedAt: string;
+    path?: string;
+}
+export interface RecentlyOpenedItem {
+    uid: string;
+    title: string;
+    type: "page";
+    openedAt: string;
+    visitCount: number;
+    totalDurationMs: number;
+    currentlyOpen?: boolean;
+    blocks?: RecentlyOpenedBlock[];
+}
+export interface DailyNotePagesViewItem {
+    type: "dailyNotePagesView";
+    totalDurationMs: number;
+    currentlyOpen: boolean;
+}
+export interface RecentlyEditedPage {
+    uid: string;
+    title: string;
+    editedBy: string;
+    editedAt: string;
+}
+export interface SearchSuggestionsResponse {
+    queriedAt?: string;
+    suggestions: {
+        recentlyOpenedByUser: (RecentlyOpenedItem | DailyNotePagesViewItem)[];
+        recentlyEditedPages: RecentlyEditedPage[];
+    };
+}
 export interface Template {
     name: string;
     uid: string;
     content: string;
 }
+export interface SearchTemplatesResponse {
+    queriedAt?: string;
+    results: Template[];
+}
+export interface GetPageResponse {
+    uid: string;
+    markdown: string;
+    queriedAt: string;
+}
+export interface GetBlockResponse {
+    uid: string;
+    markdown: string;
+    path: string;
+    queriedAt: string;
+}
 export interface QueryResult {
     uid: string;
     markdown: string;
@@ -203,6 +253,7 @@ export interface QueryResult {
     type?: "page";
 }
 export interface QueryResponse {
+    queriedAt?: string;
     total: number;
     results: QueryResult[];
 }

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -81,8 +81,17 @@ export class RoamError extends Error {
 // so a newer version may write a config that an older version can't parse.
 // Bump this when the config schema changes in a breaking way.
 export const CONFIG_VERSION = 1;
-// API version this client expects (major.minor must match)
-export const EXPECTED_API_VERSION = "1.1.0";
+// API version this client expects. Sent as `expectedApiVersion` in every request.
+// Roam's compatibility check compares major.minor ONLY — patch is ignored.
+// So 1.1.0, 1.1.1, 1.1.2 are all compatible; 1.1.x and 1.2.x are NOT.
+//
+// When to bump:
+// - Patch bump on Roam side (e.g. 1.1.1 → 1.1.2): no change needed here, but
+//   you can bump for cosmetic alignment.
+// - Minor bump on Roam side (e.g. 1.1.x → 1.2.0): MUST bump here too, or all
+//   requests will fail with VERSION_MISMATCH.
+// - This is independent of the npm package version (0.x.y in package.json).
+export const EXPECTED_API_VERSION = "1.1.2";
 // Helper to extract error message from RoamResponse
 export function getErrorMessage(error) {
     if (!error)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roam-research/roam-tools-core",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Core library for Roam Research tools",
   "repository": {
     "type": "git",