@roam-research/roam-tools-core 0.4.0

package/dist/operations/files.js

@@ -0,0 +1,175 @@
+import { z } from "zod";
+import { readFile } from "fs/promises";
+import { basename, extname } from "path";
+import { imageResult, textResult } from "../types.js";
+// Schemas
+export const FileGetSchema = z.object({
+    url: z.string().describe("Firebase storage URL of the file"),
+});
+export const FileUploadSchema = z.object({
+    filePath: z.string().optional().describe("Local file path (preferred) - server reads the file directly"),
+    url: z.string().optional().describe("Remote URL to fetch the image from"),
+    base64: z.string().optional().describe("Base64-encoded image data (fallback for sandboxed clients)"),
+    mimetype: z.string().optional().describe("MIME type (e.g., image/png, image/jpeg) - auto-detected if not provided"),
+    filename: z.string().optional().describe("Original filename for reference - derived from path/url if not provided"),
+});
+export const FileDeleteSchema = z.object({
+    url: z.string().describe("Firebase storage URL of the file to delete"),
+});
+// Detect MIME type from base64 image data by checking magic bytes
+function detectMimeTypeFromBase64(base64) {
+    // JPEG: FF D8 FF -> /9j/
+    if (base64.startsWith("/9j/"))
+        return "image/jpeg";
+    // PNG: 89 50 4E 47 -> iVBOR
+    if (base64.startsWith("iVBOR"))
+        return "image/png";
+    // GIF: 47 49 46 38 -> R0lG
+    if (base64.startsWith("R0lG"))
+        return "image/gif";
+    // WebP: 52 49 46 46 ... 57 45 42 50 -> UklGR
+    if (base64.startsWith("UklGR"))
+        return "image/webp";
+    // BMP: 42 4D -> Qk
+    if (base64.startsWith("Qk"))
+        return "image/bmp";
+    // PDF: 25 50 44 46 -> JVBE
+    if (base64.startsWith("JVBE"))
+        return "application/pdf";
+    // TIFF (little-endian): 49 49 2A 00 -> SUkq
+    if (base64.startsWith("SUkq"))
+        return "image/tiff";
+    // TIFF (big-endian): 4D 4D 00 2A -> TU0A
+    if (base64.startsWith("TU0A"))
+        return "image/tiff";
+    // ICO: 00 00 01 00 -> AAAB
+    if (base64.startsWith("AAAB"))
+        return "image/x-icon";
+    // AVIF/HEIC: check for ftyp box (base64 varies, check common patterns)
+    // These are harder to detect reliably from base64 prefix alone
+    return null;
+}
+// Detect MIME type from file extension
+function detectMimeTypeFromExtension(filePath) {
+    const ext = extname(filePath).toLowerCase();
+    const mimeTypes = {
+        // Common image formats
+        ".jpg": "image/jpeg",
+        ".jpeg": "image/jpeg",
+        ".png": "image/png",
+        ".gif": "image/gif",
+        ".webp": "image/webp",
+        ".bmp": "image/bmp",
+        ".svg": "image/svg+xml",
+        ".ico": "image/x-icon",
+        ".tiff": "image/tiff",
+        ".tif": "image/tiff",
+        // Modern formats
+        ".heic": "image/heic",
+        ".heif": "image/heif",
+        ".avif": "image/avif",
+        // Documents
+        ".pdf": "application/pdf",
+    };
+    return mimeTypes[ext] || null;
+}
+// Read file from local path and return base64 + mimetype
+async function readLocalFile(filePath) {
+    const buffer = await readFile(filePath);
+    const base64 = buffer.toString("base64");
+    const filename = basename(filePath);
+    // Try extension first, then magic bytes
+    let mimetype = detectMimeTypeFromExtension(filePath);
+    if (!mimetype) {
+        mimetype = detectMimeTypeFromBase64(base64);
+    }
+    if (!mimetype) {
+        throw new Error(`Could not detect MIME type for file: ${filePath}`);
+    }
+    return { base64, mimetype, filename };
+}
+// Fetch file from URL and return base64 + mimetype
+async function fetchRemoteFile(url) {
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`Failed to fetch ${url}: ${response.status} ${response.statusText}`);
+    }
+    const buffer = await response.arrayBuffer();
+    const base64 = Buffer.from(buffer).toString("base64");
+    // Extract filename from URL path
+    const urlPath = new URL(url).pathname;
+    const filename = basename(urlPath) || "image";
+    // Try Content-Type header first, then extension, then magic bytes
+    let mimetype = response.headers.get("content-type")?.split(";")[0];
+    if (!mimetype || mimetype === "application/octet-stream") {
+        mimetype = detectMimeTypeFromExtension(urlPath) || detectMimeTypeFromBase64(base64) || undefined;
+    }
+    if (!mimetype) {
+        throw new Error(`Could not detect MIME type for URL: ${url}`);
+    }
+    return { base64, mimetype, filename };
+}
+export async function getFile(client, params) {
+    const response = await client.call("file.get", [
+        { url: params.url, format: "base64" },
+    ]);
+    if (!response.result) {
+        throw new Error("No file data returned");
+    }
+    const { base64, mimetype } = response.result;
+    const mimeType = mimetype || detectMimeTypeFromBase64(base64);
+    if (mimeType?.startsWith("image/")) {
+        return imageResult(base64, mimeType);
+    }
+    // Non-image file - return as text (base64 encoded)
+    return textResult(response.result);
+}
+export async function uploadFile(client, params) {
+    // Validate exactly one source is provided
+    const sources = [params.filePath, params.url, params.base64].filter(Boolean);
+    if (sources.length === 0) {
+        throw new Error("One of filePath, url, or base64 must be provided");
+    }
+    if (sources.length > 1) {
+        throw new Error("Only one of filePath, url, or base64 should be provided");
+    }
+    let base64;
+    let mimetype;
+    let filename;
+    if (params.filePath) {
+        // Read from local file system
+        const fileData = await readLocalFile(params.filePath);
+        base64 = fileData.base64;
+        mimetype = params.mimetype || fileData.mimetype;
+        filename = params.filename || fileData.filename;
+    }
+    else if (params.url) {
+        // Fetch from remote URL
+        const fileData = await fetchRemoteFile(params.url);
+        base64 = fileData.base64;
+        mimetype = params.mimetype || fileData.mimetype;
+        filename = params.filename || fileData.filename;
+    }
+    else {
+        // Use provided base64 directly (params.base64 must be set due to validation above)
+        base64 = params.base64;
+        mimetype = params.mimetype || detectMimeTypeFromBase64(base64) || "application/octet-stream";
+        filename = params.filename;
+    }
+    const response = await client.call("file.upload", [
+        { base64, mimetype, filename },
+    ]);
+    if (!response.result) {
+        throw new Error("No URL returned from upload");
+    }
+    let url = response.result;
+    // Strip markdown image wrapper if present (API currently returns "![](url)")
+    if (url.startsWith("![](") && url.endsWith(")")) {
+        url = url.slice(4, -1);
+    }
+    return textResult({ url });
+}
+export async function deleteFile(client, params) {
+    await client.call("file.delete", [{ url: params.url }]);
+    return textResult({ deleted: true });
+}

package/dist/operations/graphs.d.ts

@@ -0,0 +1,26 @@
+import { z } from "zod";
+import type { CallToolResult } from "../types.js";
+export declare const ListGraphsSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+export declare const SetupNewGraphSchema: z.ZodObject<{
+    graph: z.ZodOptional<z.ZodString>;
+    nickname: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    nickname?: string | undefined;
+    graph?: string | undefined;
+}, {
+    nickname?: string | undefined;
+    graph?: string | undefined;
+}>;
+export type ListGraphsParams = z.infer<typeof ListGraphsSchema>;
+export type SetupNewGraphParams = z.infer<typeof SetupNewGraphSchema>;
+/**
+ * List all configured graphs with their nicknames.
+ */
+export declare function listGraphs(): Promise<CallToolResult>;
+/**
+ * Set up a new Roam graph connection, or list available graphs.
+ * Call without arguments to list available graphs from Roam Desktop.
+ * Call with graph + nickname to request a token and save the configuration.
+ */
+export declare function setupNewGraph(args: SetupNewGraphParams): Promise<CallToolResult>;
+//# sourceMappingURL=graphs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"graphs.d.ts","sourceRoot":"","sources":["../../src/operations/graphs.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAsBlD,eAAO,MAAM,gBAAgB,gDAAe,CAAC;AAE7C,eAAO,MAAM,mBAAmB;;;;;;;;;EAoB9B,CAAC;AAMH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAChE,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAMtE;;GAEG;AACH,wBAAsB,UAAU,IAAI,OAAO,CAAC,cAAc,CAAC,CAmB1D;AAqDD;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,cAAc,CAAC,CAiKzB"}

package/dist/operations/graphs.js

@@ -0,0 +1,214 @@
+// src/core/operations/graphs.ts
+// Graph management operations
+import { z } from "zod";
+import { textResult, RoamError, ErrorCodes } from "../types.js";
+import { getConfiguredGraphs, getConfiguredGraphsSafe, getPort, saveGraphToConfig, } from "../graph-resolver.js";
+import { fetchAvailableGraphs, requestToken, sleep, openRoamApp, slugify, } from "../roam-api.js";
+// ============================================================================
+// Schemas
+// ============================================================================
+export const ListGraphsSchema = z.object({});
+export const SetupNewGraphSchema = z.object({
+    graph: z
+        .string()
+        .regex(/^[A-Za-z0-9_-]+$/, "Graph name must contain only letters, numbers, hyphens, and underscores")
+        .optional()
+        .describe("The canonical Roam graph name. Omit graph and nickname to list available graphs."),
+    nickname: z
+        .string()
+        .min(1, "Nickname must not be empty")
+        .optional()
+        .describe("A short, memorable label describing what this graph is for (e.g. 'my personal graph', 'work notes', 'book club'). " +
+        "Ask the user what they call this graph — use their natural language, not hyphenated format. " +
+        "Do not just copy the graph name. Required when graph is provided."),
+});
+// ============================================================================
+// Operations
+// ============================================================================
+/**
+ * List all configured graphs with their nicknames.
+ */
+export async function listGraphs() {
+    try {
+        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.",
+            setup: "To connect additional graphs, use the setup_new_graph tool (call it without arguments to see available graphs).",
+        });
+    }
+    catch (error) {
+        if (error instanceof RoamError) {
+            return textResult({
+                error: {
+                    code: error.code,
+                    message: error.message,
+                },
+            });
+        }
+        throw error;
+    }
+}
+/**
+ * Dedup available graphs: if same name exists as both hosted and offline, keep hosted.
+ * Consistent with getMcpConfig() dedup behavior in graph-resolver.ts.
+ */
+function dedupAvailableGraphs(graphs) {
+    const byName = new Map();
+    for (const g of graphs) {
+        const existing = byName.get(g.name);
+        if (existing) {
+            if (g.type === "hosted")
+                byName.set(g.name, g);
+        }
+        else {
+            byName.set(g.name, g);
+        }
+    }
+    return Array.from(byName.values());
+}
+/**
+ * Fetch available graphs from Roam Desktop, retrying once if Roam isn't running.
+ * Deduplicates by name (hosted takes priority over offline).
+ */
+async function fetchAvailableGraphsWithRetry(port) {
+    let raw;
+    try {
+        raw = await fetchAvailableGraphs(port);
+    }
+    catch (error) {
+        const err = error;
+        const isConnectionError = err.cause?.code === "ECONNREFUSED" ||
+            err.message?.includes("fetch failed");
+        if (!isConnectionError) {
+            throw error;
+        }
+        await openRoamApp();
+        await sleep(5000);
+        try {
+            raw = await fetchAvailableGraphs(port);
+        }
+        catch {
+            throw new RoamError("Could not connect to Roam Desktop. Make sure it is running and the Local API is enabled in Settings > Local API.", ErrorCodes.CONNECTION_FAILED);
+        }
+    }
+    return dedupAvailableGraphs(raw);
+}
+/**
+ * Set up a new Roam graph connection, or list available graphs.
+ * Call without arguments to list available graphs from Roam Desktop.
+ * Call with graph + nickname to request a token and save the configuration.
+ */
+export async function setupNewGraph(args) {
+    const { graph, nickname: rawNickname } = args;
+    // List mode: no args → return available graphs from Roam Desktop
+    if (!graph) {
+        const port = await getPort();
+        const availableGraphs = await fetchAvailableGraphsWithRetry(port);
+        const configuredGraphs = await getConfiguredGraphsSafe();
+        return textResult({
+            available_graphs: availableGraphs.map((g) => ({
+                name: g.name,
+                type: g.type,
+            })),
+            already_configured: configuredGraphs.map((g) => ({
+                name: g.name,
+                nickname: g.nickname,
+                type: g.type,
+                accessLevel: g.accessLevel,
+                lastKnownTokenStatus: g.lastKnownTokenStatus,
+            })),
+            instruction: "Call setup_new_graph with graph and nickname to connect one of the available graphs.",
+        });
+    }
+    // Setup mode: graph provided, nickname required
+    if (!rawNickname) {
+        throw new RoamError("nickname is required when graph is provided.", ErrorCodes.VALIDATION_ERROR);
+    }
+    // 1. Slugify nickname
+    const nickname = slugify(rawNickname);
+    if (!nickname) {
+        throw new RoamError(`Nickname "${rawNickname}" produces an empty result after converting to kebab-case. Use a nickname with at least one letter or number.`, ErrorCodes.VALIDATION_ERROR);
+    }
+    // 2. Check if graph is already configured
+    const existingGraphs = await getConfiguredGraphsSafe();
+    const matchingConfigs = existingGraphs.filter((g) => g.name === graph);
+    if (matchingConfigs.length > 0) {
+        const allRevoked = matchingConfigs.every((g) => g.lastKnownTokenStatus === "revoked");
+        if (!allRevoked) {
+            // At least one active config — return as already configured
+            return textResult({
+                status: "already_configured",
+                graphs: matchingConfigs.map((g) => ({
+                    name: g.name,
+                    nickname: g.nickname,
+                    type: g.type,
+                    accessLevel: g.accessLevel,
+                    lastKnownTokenStatus: g.lastKnownTokenStatus,
+                })),
+                instruction: "This graph is already configured. Pass the 'nickname' value as the graph parameter. Call get_graph_guidelines before operating on it.",
+            });
+        }
+        // All revoked — fall through to re-request a new token
+    }
+    // 3. Check nickname collision
+    const nicknameCollision = existingGraphs.find((g) => g.nickname.toLowerCase() === nickname.toLowerCase() && g.name !== graph);
+    if (nicknameCollision) {
+        throw new RoamError(`Nickname "${nickname}" is already used by graph "${nicknameCollision.name}". Please choose a different nickname.`, ErrorCodes.VALIDATION_ERROR);
+    }
+    // 4. Get port and fetch available graphs
+    const port = await getPort();
+    const availableGraphs = await fetchAvailableGraphsWithRetry(port);
+    // 5. Find graph type
+    const graphInfo = availableGraphs.find((g) => g.name === graph);
+    if (!graphInfo) {
+        throw new RoamError(`Graph "${graph}" was not found in Roam Desktop. Make sure the graph name is correct and that it is available in the app.`, ErrorCodes.VALIDATION_ERROR, {
+            available_graphs: availableGraphs.map((g) => g.name),
+        });
+    }
+    // 6. Request token (blocks until user approves/denies in Roam)
+    const result = await requestToken(port, graph, graphInfo.type, "full");
+    // 7. Handle errors
+    if (!result.success || !result.token) {
+        const error = result.error;
+        const errorCode = error && typeof error === "object" ? error.code : undefined;
+        const errorMessage = error
+            ? typeof error === "string"
+                ? error
+                : error.message || "Unknown error"
+            : "Unknown error";
+        switch (errorCode) {
+            case "USER_REJECTED":
+                throw new RoamError("Token request was denied in Roam. The user must approve the request in the Roam desktop app.", ErrorCodes.USER_REJECTED);
+            case "GRAPH_BLOCKED":
+                throw new RoamError("This graph has blocked token requests. Unblock it in Roam Settings > Graph > Local API Tokens.", ErrorCodes.GRAPH_BLOCKED);
+            case "TIMEOUT":
+                throw new RoamError("No response after 5 minutes. Please try again — the user needs to approve the request in the Roam desktop app.", ErrorCodes.TIMEOUT);
+            case "REQUEST_IN_PROGRESS":
+                throw new RoamError("Another token request is already pending for this graph. The user should respond to the existing request in Roam first.", ErrorCodes.REQUEST_IN_PROGRESS);
+            default:
+                throw new RoamError(`Token request failed: ${errorMessage}`, ErrorCodes.INTERNAL_ERROR);
+        }
+    }
+    // 8. Save to config
+    const accessLevel = (result.grantedAccessLevel || "full");
+    const graphConfig = {
+        name: graph,
+        type: graphInfo.type,
+        token: result.token,
+        nickname,
+        accessLevel,
+    };
+    await saveGraphToConfig(graphConfig);
+    // 9. Return success
+    return textResult({
+        status: "connected",
+        graph: {
+            name: graph,
+            nickname,
+            type: graphInfo.type,
+            accessLevel,
+        },
+        instruction: "Graph connected successfully. Call get_graph_guidelines next to understand the graph's conventions before making any changes.",
+    });
+}

package/dist/operations/navigation.d.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+import type { RoamClient } from "../client.js";
+import type { CallToolResult } from "../types.js";
+export declare const GetOpenWindowsSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+export declare const GetSelectionSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+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;
+}>;
+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;
+}, {
+    uid: string;
+    type?: "mentions" | "block" | "outline" | undefined;
+}>;
+export type OpenMainWindowParams = z.infer<typeof OpenMainWindowSchema>;
+export type OpenSidebarParams = z.infer<typeof OpenSidebarSchema>;
+export declare function getOpenWindows(client: RoamClient): Promise<CallToolResult>;
+export declare function getSelection(client: RoamClient): Promise<CallToolResult>;
+export declare function openMainWindow(client: RoamClient, params: OpenMainWindowParams): Promise<CallToolResult>;
+export declare function openSidebar(client: RoamClient, params: OpenSidebarParams): Promise<CallToolResult>;
+//# sourceMappingURL=navigation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../src/operations/navigation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAkE,cAAc,EAAE,MAAM,aAAa,CAAC;AAIlH,eAAO,MAAM,oBAAoB,gDAAe,CAAC;AAEjD,eAAO,MAAM,kBAAkB,gDAAe,CAAC;AAE/C,eAAO,MAAM,oBAAoB;;;;;;;;;EAG/B,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;;;;;;EAG5B,CAAC;AAGH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AACxE,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAElE,wBAAsB,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,CAAC,CAShF;AAED,wBAAsB,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,CAAC,CAS9E;AAED,wBAAsB,cAAc,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,cAAc,CAAC,CAQ9G;AAED,wBAAsB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,cAAc,CAAC,CAUxG"}

package/dist/operations/navigation.js

@@ -0,0 +1,54 @@
+import { z } from "zod";
+import { textResult } from "../types.js";
+// Schemas
+export const GetOpenWindowsSchema = z.object({});
+export const GetSelectionSchema = z.object({});
+export const OpenMainWindowSchema = z.object({
+    uid: z.string().optional().describe("UID of page or block"),
+    title: z.string().optional().describe("Page title (alternative to uid)"),
+});
+export const OpenSidebarSchema = z.object({
+    uid: z.string().describe("UID of page or block"),
+    type: z.enum(["block", "outline", "mentions"]).optional().describe("View type (default: outline)"),
+});
+export async function getOpenWindows(client) {
+    const [mainResponse, sidebarResponse] = await Promise.all([
+        client.call("ui.mainWindow.getOpenView", []),
+        client.call("ui.rightSidebar.getWindows", []),
+    ]);
+    return textResult({
+        main: mainResponse.result ?? null,
+        sidebar: sidebarResponse.result ?? [],
+    });
+}
+export async function getSelection(client) {
+    const [focusedResponse, multiSelectedResponse] = await Promise.all([
+        client.call("ui.getFocusedBlock", []),
+        client.call("ui.multiselect.getSelected", []),
+    ]);
+    return textResult({
+        focused: focusedResponse.result ?? null,
+        multiSelected: multiSelectedResponse.result ?? [],
+    });
+}
+export async function openMainWindow(client, params) {
+    if (params.uid) {
+        // Could be a page or block - openBlock handles both
+        await client.call("ui.mainWindow.openBlock", [{ block: { uid: params.uid } }]);
+    }
+    else if (params.title) {
+        await client.call("ui.mainWindow.openPage", [{ page: { title: params.title } }]);
+    }
+    return textResult({ success: true });
+}
+export async function openSidebar(client, params) {
+    await client.call("ui.rightSidebar.addWindow", [
+        {
+            window: {
+                type: params.type || "outline",
+                "block-uid": params.uid,
+            },
+        },
+    ]);
+    return textResult({ success: true });
+}

package/dist/operations/pages.d.ts

@@ -0,0 +1,63 @@
+import { z } from "zod";
+import type { RoamClient } from "../client.js";
+import type { CallToolResult } from "../types.js";
+export declare const CreatePageSchema: z.ZodObject<{
+    title: z.ZodString;
+    markdown: z.ZodOptional<z.ZodString>;
+    uid: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    title: string;
+    markdown?: string | undefined;
+    uid?: string | undefined;
+}, {
+    title: string;
+    markdown?: string | undefined;
+    uid?: 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;
+    maxDepth?: number | undefined;
+}, {
+    title?: string | undefined;
+    uid?: string | undefined;
+    maxDepth?: number | undefined;
+}>;
+export declare const DeletePageSchema: z.ZodObject<{
+    uid: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    uid: string;
+}, {
+    uid: string;
+}>;
+export declare const UpdatePageSchema: z.ZodObject<{
+    uid: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    childrenViewType: z.ZodOptional<z.ZodEnum<["document", "bullet", "numbered"]>>;
+    mergePages: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    uid: string;
+    title?: string | undefined;
+    childrenViewType?: "bullet" | "numbered" | "document" | undefined;
+    mergePages?: boolean | undefined;
+}, {
+    uid: string;
+    title?: string | undefined;
+    childrenViewType?: "bullet" | "numbered" | "document" | undefined;
+    mergePages?: boolean | undefined;
+}>;
+export declare const GetGuidelinesSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+export type CreatePageParams = z.infer<typeof CreatePageSchema>;
+export type GetPageParams = z.infer<typeof GetPageSchema>;
+export type DeletePageParams = z.infer<typeof DeletePageSchema>;
+export type UpdatePageParams = z.infer<typeof UpdatePageSchema>;
+export declare function createPage(client: RoamClient, params: CreatePageParams): Promise<CallToolResult>;
+export declare function getPage(client: RoamClient, params: GetPageParams): Promise<CallToolResult>;
+export declare function deletePage(client: RoamClient, params: DeletePageParams): Promise<CallToolResult>;
+export declare function updatePage(client: RoamClient, params: UpdatePageParams): Promise<CallToolResult>;
+export declare function getGuidelines(client: RoamClient): Promise<CallToolResult>;
+//# sourceMappingURL=pages.d.ts.map

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

@@ -0,0 +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"}

package/dist/operations/pages.js

@@ -0,0 +1,59 @@
+import { z } from "zod";
+import { textResult } from "../types.js";
+// Schemas
+export const CreatePageSchema = z.object({
+    title: z.string().describe("Page title"),
+    markdown: z.string().optional().describe("Markdown content for the page"),
+    uid: z.string().optional(),
+});
+export const GetPageSchema = z.object({
+    title: z.string().optional().describe("Page title (alternative to uid)"),
+    uid: z.string().optional().describe("Page UID"),
+    maxDepth: z.coerce.number().optional().describe("Max depth of children to include in markdown (omit for full tree)"),
+});
+export const DeletePageSchema = z.object({
+    uid: z.string().describe("Page UID to delete"),
+});
+export const UpdatePageSchema = z.object({
+    uid: z.string().describe("Page UID"),
+    title: z.string().optional().describe("New page title"),
+    childrenViewType: z.enum(["document", "bullet", "numbered"]).optional().describe("How children are displayed (document, bullet, or numbered)"),
+    mergePages: z.boolean().optional().describe("If true, merge with existing page when renaming to a title that already exists (default: false)"),
+});
+export const GetGuidelinesSchema = z.object({});
+export async function createPage(client, params) {
+    const response = await client.call("data.page.fromMarkdown", [
+        {
+            page: { title: params.title, uid: params.uid },
+            "markdown-string": params.markdown,
+        },
+    ]);
+    return textResult(response.result ?? { uid: "" });
+}
+export async function getPage(client, params) {
+    const apiParams = params.uid ? { uid: params.uid } : { title: params.title };
+    if (params.maxDepth !== undefined)
+        apiParams.maxDepth = params.maxDepth;
+    const response = await client.call("data.ai.getPage", [apiParams]);
+    return textResult(response.result ?? null);
+}
+export async function deletePage(client, params) {
+    await client.call("data.page.delete", [{ page: { uid: params.uid } }]);
+    return textResult({ success: true });
+}
+export async function updatePage(client, params) {
+    const page = { uid: params.uid };
+    if (params.title !== undefined)
+        page.title = params.title;
+    if (params.childrenViewType !== undefined)
+        page["children-view-type"] = params.childrenViewType;
+    const apiParams = { page };
+    if (params.mergePages !== undefined)
+        apiParams["merge-pages"] = params.mergePages;
+    await client.call("data.page.update", [apiParams]);
+    return textResult({ success: true });
+}
+export async function getGuidelines(client) {
+    const response = await client.call("data.ai.getGraphGuidelines", []);
+    return textResult(response.result ?? { guidelines: null, starredPages: [] });
+}

package/dist/operations/query.d.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+import type { RoamClient } from "../client.js";
+import type { CallToolResult } from "../types.js";
+export declare const QuerySchema: z.ZodObject<{
+    uid: z.ZodOptional<z.ZodString>;
+    query: z.ZodOptional<z.ZodString>;
+    sort: z.ZodOptional<z.ZodEnum<["created-date", "edited-date", "daily-note-date"]>>;
+    sortOrder: z.ZodOptional<z.ZodEnum<["asc", "desc"]>>;
+    includePath: z.ZodOptional<z.ZodBoolean>;
+    offset: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    maxDepth: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    sort?: "created-date" | "edited-date" | "daily-note-date" | undefined;
+    uid?: string | undefined;
+    maxDepth?: number | undefined;
+    offset?: number | undefined;
+    limit?: number | undefined;
+    sortOrder?: "asc" | "desc" | undefined;
+    includePath?: boolean | undefined;
+    query?: string | undefined;
+}, {
+    sort?: "created-date" | "edited-date" | "daily-note-date" | undefined;
+    uid?: string | undefined;
+    maxDepth?: number | undefined;
+    offset?: number | undefined;
+    limit?: number | undefined;
+    sortOrder?: "asc" | "desc" | undefined;
+    includePath?: boolean | undefined;
+    query?: string | undefined;
+}>;
+export type QueryParams = z.infer<typeof QuerySchema>;
+export declare function query(client: RoamClient, params: QueryParams): Promise<CallToolResult>;
+//# sourceMappingURL=query.d.ts.map