@roam-research/roam-mcp 0.3.1

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

@@ -0,0 +1,119 @@
+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;
+    markdown: z.ZodString;
+    order: z.ZodOptional<z.ZodUnion<[z.ZodNumber, z.ZodEnum<["first", "last"]>]>>;
+}, "strip", z.ZodTypeAny, {
+    markdown: string;
+    parentUid: string;
+    order?: number | "first" | "last" | undefined;
+}, {
+    markdown: string;
+    parentUid: string;
+    order?: number | "first" | "last" | undefined;
+}>;
+export declare const GetBlockSchema: z.ZodObject<{
+    uid: z.ZodString;
+    maxDepth: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    uid: string;
+    maxDepth?: number | undefined;
+}, {
+    uid: string;
+    maxDepth?: number | undefined;
+}>;
+export declare const UpdateBlockSchema: z.ZodObject<{
+    uid: z.ZodString;
+    string: z.ZodOptional<z.ZodString>;
+    open: z.ZodOptional<z.ZodBoolean>;
+    heading: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    uid: string;
+    string?: string | undefined;
+    open?: boolean | undefined;
+    heading?: number | undefined;
+}, {
+    uid: string;
+    string?: string | undefined;
+    open?: boolean | undefined;
+    heading?: number | undefined;
+}>;
+export declare const DeleteBlockSchema: z.ZodObject<{
+    uid: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    uid: string;
+}, {
+    uid: string;
+}>;
+export declare const MoveBlockSchema: z.ZodObject<{
+    uid: z.ZodString;
+    parentUid: z.ZodString;
+    order: z.ZodUnion<[z.ZodNumber, z.ZodEnum<["first", "last"]>]>;
+}, "strip", z.ZodTypeAny, {
+    uid: string;
+    parentUid: string;
+    order: number | "first" | "last";
+}, {
+    uid: string;
+    parentUid: string;
+    order: number | "first" | "last";
+}>;
+export declare const GetBacklinksSchema: z.ZodObject<{
+    uid: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    offset: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    sort: z.ZodOptional<z.ZodEnum<["created-date", "edited-date", "daily-note-date"]>>;
+    sortOrder: z.ZodOptional<z.ZodEnum<["asc", "desc"]>>;
+    search: z.ZodOptional<z.ZodString>;
+    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;
+    sortOrder?: "asc" | "desc" | undefined;
+    includePath?: boolean | 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;
+    sortOrder?: "asc" | "desc" | undefined;
+    includePath?: boolean | undefined;
+}>;
+export type CreateBlockParams = z.infer<typeof CreateBlockSchema>;
+export type GetBlockParams = z.infer<typeof GetBlockSchema>;
+export type UpdateBlockParams = z.infer<typeof UpdateBlockSchema>;
+export type DeleteBlockParams = z.infer<typeof DeleteBlockSchema>;
+export type MoveBlockParams = z.infer<typeof MoveBlockSchema>;
+export type GetBacklinksParams = z.infer<typeof GetBacklinksSchema>;
+export interface BacklinkResult {
+    uid: string;
+    type?: "page";
+    markdown: string;
+    path?: Array<{
+        uid: string;
+        title?: string;
+        string?: string;
+    }>;
+}
+export interface GetBacklinksResponse {
+    total: number;
+    results: BacklinkResult[];
+}
+export declare function createBlock(client: RoamClient, params: CreateBlockParams): Promise<CallToolResult>;
+export declare function getBlock(client: RoamClient, params: GetBlockParams): Promise<CallToolResult>;
+export declare function updateBlock(client: RoamClient, params: UpdateBlockParams): Promise<CallToolResult>;
+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>;

package/dist/core/operations/blocks.js

@@ -0,0 +1,108 @@
+import { z } from "zod";
+import { textResult } from "../types.js";
+// Schemas
+export const CreateBlockSchema = z.object({
+    parentUid: z.string().describe("UID of parent block or page"),
+    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'"),
+});
+export const GetBlockSchema = z.object({
+    uid: z.string().describe("Block UID"),
+    maxDepth: z.coerce.number().optional().describe("Max depth of children to include in markdown (omit for full tree)"),
+});
+export const UpdateBlockSchema = z.object({
+    uid: z.string().describe("Block UID"),
+    string: z.string().optional().describe("New text content"),
+    open: z.boolean().optional().describe("Collapse state"),
+    heading: z.coerce.number().optional().describe("Heading level (0-3)"),
+});
+export const DeleteBlockSchema = z.object({
+    uid: z.string().describe("Block UID to delete"),
+});
+export const MoveBlockSchema = z.object({
+    uid: z.string().describe("Block UID to move"),
+    parentUid: z.string().describe("UID of the new parent block or page"),
+    order: z.union([z.coerce.number(), z.enum(["first", "last"])]).describe("Position in the new parent (number, 'first', or 'last')"),
+});
+export const GetBacklinksSchema = z.object({
+    uid: z.string().optional().describe("UID of page or block (required if no title)"),
+    title: z.string().optional().describe("Page title (required if no uid)"),
+    offset: z.coerce.number().optional().describe("Skip first N results (default: 0)"),
+    limit: z.coerce.number().optional().describe("Max results to return (default: 20)"),
+    sort: z.enum(["created-date", "edited-date", "daily-note-date"]).optional().describe("Sort order (default: created-date)"),
+    sortOrder: z.enum(["asc", "desc"]).optional().describe("Sort direction (default: desc)"),
+    search: z.string().optional().describe("Filter results by text match (searches block, parents, children, page title)"),
+    includePath: z.boolean().optional().describe("Include breadcrumb path to each result (default: true)"),
+    maxDepth: z.coerce.number().optional().describe("Max depth of children to include in markdown (default: 2)"),
+});
+export async function createBlock(client, params) {
+    const response = await client.call("data.block.fromMarkdown", [
+        {
+            location: {
+                "parent-uid": params.parentUid,
+                order: params.order ?? "last",
+            },
+            "markdown-string": params.markdown,
+        },
+    ]);
+    return textResult(response.result ?? { uids: [] });
+}
+export async function getBlock(client, params) {
+    const apiParams = { uid: params.uid };
+    if (params.maxDepth !== undefined)
+        apiParams.maxDepth = params.maxDepth;
+    const response = await client.call("data.ai.getBlock", [apiParams]);
+    return textResult(response.result ?? null);
+}
+export async function updateBlock(client, params) {
+    const block = { uid: params.uid };
+    if (params.string !== undefined)
+        block.string = params.string;
+    if (params.open !== undefined)
+        block.open = params.open;
+    if (params.heading !== undefined)
+        block.heading = params.heading;
+    await client.call("data.block.update", [{ block }]);
+    return textResult({ success: true });
+}
+export async function deleteBlock(client, params) {
+    await client.call("data.block.delete", [{ block: { uid: params.uid } }]);
+    return textResult({ success: true });
+}
+export async function moveBlock(client, params) {
+    await client.call("data.block.move", [
+        {
+            location: {
+                "parent-uid": params.parentUid,
+                order: params.order,
+            },
+            block: {
+                uid: params.uid,
+            },
+        },
+    ]);
+    return textResult({ success: true });
+}
+export async function getBacklinks(client, params) {
+    const apiParams = {};
+    if (params.uid !== undefined)
+        apiParams.uid = params.uid;
+    if (params.title !== undefined)
+        apiParams.title = params.title;
+    if (params.offset !== undefined)
+        apiParams.offset = params.offset;
+    if (params.limit !== undefined)
+        apiParams.limit = params.limit;
+    if (params.sort !== undefined)
+        apiParams.sort = params.sort;
+    if (params.sortOrder !== undefined)
+        apiParams.sortOrder = params.sortOrder;
+    if (params.search !== undefined)
+        apiParams.search = params.search;
+    if (params.includePath !== undefined)
+        apiParams.includePath = params.includePath;
+    if (params.maxDepth !== undefined)
+        apiParams.maxDepth = params.maxDepth;
+    const response = await client.call("data.ai.getBacklinks", [apiParams]);
+    return textResult(response.result ?? { total: 0, results: [] });
+}

package/dist/core/operations/files.d.ts

@@ -0,0 +1,42 @@
+import { z } from "zod";
+import type { RoamClient } from "../client.js";
+import type { CallToolResult } from "../types.js";
+export declare const FileGetSchema: z.ZodObject<{
+    url: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+}, {
+    url: string;
+}>;
+export declare const FileUploadSchema: z.ZodObject<{
+    filePath: z.ZodOptional<z.ZodString>;
+    url: z.ZodOptional<z.ZodString>;
+    base64: z.ZodOptional<z.ZodString>;
+    mimetype: z.ZodOptional<z.ZodString>;
+    filename: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    url?: string | undefined;
+    base64?: string | undefined;
+    filePath?: string | undefined;
+    mimetype?: string | undefined;
+    filename?: string | undefined;
+}, {
+    url?: string | undefined;
+    base64?: string | undefined;
+    filePath?: string | undefined;
+    mimetype?: string | undefined;
+    filename?: string | undefined;
+}>;
+export declare const FileDeleteSchema: z.ZodObject<{
+    url: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+}, {
+    url: string;
+}>;
+export type FileGetParams = z.infer<typeof FileGetSchema>;
+export type FileUploadParams = z.infer<typeof FileUploadSchema>;
+export type FileDeleteParams = z.infer<typeof FileDeleteSchema>;
+export declare function getFile(client: RoamClient, params: FileGetParams): Promise<CallToolResult>;
+export declare function uploadFile(client: RoamClient, params: FileUploadParams): Promise<CallToolResult>;
+export declare function deleteFile(client: RoamClient, params: FileDeleteParams): Promise<CallToolResult>;

package/dist/core/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/core/operations/graphs.d.ts

@@ -0,0 +1,25 @@
+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>;

package/dist/core/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.",
+    });
+}