ocean-brain 0.2.1 → 0.3.0

package/dist/mcp.js

@@ -1,20 +1,250 @@
 #!/usr/bin/env node
 
 // src/mcp.ts
-import fs from "fs";
-import path from "path";
+import fs2 from "fs";
+import path2 from "path";
 import { fileURLToPath } from "url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z as z2 } from "zod";
+
+// src/mcp-write-safety.ts
+import crypto from "crypto";
+import fs from "fs";
+import os from "os";
+import path from "path";
 import { z } from "zod";
-var __dirname = path.dirname(fileURLToPath(import.meta.url));
+var destructiveMcpWriteFields = {
+  dryRun: z.boolean().optional().default(true).describe("Preview the destructive change first. Set dryRun to false only after you receive an operationId and confirmToken."),
+  operationId: z.string().optional().describe("Operation id returned by the dry-run response. Required when dryRun is false."),
+  confirmToken: z.string().optional().describe("Confirmation token returned by the dry-run response. Required when dryRun is false."),
+  force: z.boolean().optional().default(false).describe("Explicitly confirm a bulk destructive change when the preview says force is required.")
+};
+var McpCliWriteSafetyError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "McpCliWriteSafetyError";
+    this.code = code;
+  }
+};
+var DEFAULT_TTL_MS = 10 * 60 * 1e3;
+var DEFAULT_ROOT_DIR = path.resolve(os.homedir(), ".ocean-brain", "mcp-write-safety");
+var createError = (code, message) => new McpCliWriteSafetyError(code, message);
+var ensureDirExists = (dirPath) => {
+  fs.mkdirSync(dirPath, { recursive: true });
+};
+var hashToken = (token) => crypto.createHash("sha256").update(token).digest("hex");
+var toPublicPendingOperation = (operation) => ({
+  actor: operation.actor,
+  affectedIds: operation.affectedIds,
+  createdAt: operation.createdAt,
+  estimatedChangeCount: operation.estimatedChangeCount,
+  expiresAt: operation.expiresAt,
+  force: operation.force,
+  operationId: operation.operationId,
+  risk: operation.risk,
+  summary: operation.summary,
+  toolName: operation.toolName
+});
+var parsePendingOperation = (raw) => JSON.parse(raw);
+var defaultMcpWriteSafetyDir = () => {
+  return path.resolve(process.env.OCEAN_BRAIN_MCP_WRITE_SAFETY_DIR || DEFAULT_ROOT_DIR);
+};
+var formatMcpGraphqlError = (error) => {
+  const suffix = [];
+  if (error.extensions?.code) {
+    suffix.push(`code=${error.extensions.code}`);
+  }
+  if (error.extensions?.operationId) {
+    suffix.push(`operationId=${error.extensions.operationId}`);
+  }
+  if (suffix.length === 0) {
+    return `GraphQL error: ${error.message}`;
+  }
+  return `GraphQL error: ${error.message} (${suffix.join(", ")})`;
+};
+var createMcpWriteSafetyCoordinator = (options = {}) => {
+  const rootDir = path.resolve(options.rootDir ?? defaultMcpWriteSafetyDir());
+  const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+  const now = options.now ?? (() => /* @__PURE__ */ new Date());
+  const randomBytes = options.randomBytes ?? ((size) => crypto.randomBytes(size));
+  const pendingDir = path.resolve(rootDir, "pending");
+  const logPath = path.resolve(rootDir, "operations.jsonl");
+  const appendLog = (entry) => {
+    ensureDirExists(rootDir);
+    fs.appendFileSync(logPath, `${JSON.stringify(entry)}
+`, "utf-8");
+  };
+  const buildLogEntry = (operation, phase, detail) => ({
+    actor: operation.actor,
+    affectedIds: operation.affectedIds,
+    estimatedChangeCount: operation.estimatedChangeCount,
+    force: operation.force,
+    operationId: operation.operationId,
+    phase,
+    risk: operation.risk,
+    summary: operation.summary,
+    timestamp: now().toISOString(),
+    toolName: operation.toolName,
+    ...detail ? { detail } : {}
+  });
+  const getPendingPath = (operationId) => path.resolve(pendingDir, `${operationId}.json`);
+  const cleanupExpiredOperations = () => {
+    if (!fs.existsSync(pendingDir)) {
+      return;
+    }
+    for (const fileName of fs.readdirSync(pendingDir)) {
+      const filePath = path.resolve(pendingDir, fileName);
+      const pendingOperation = parsePendingOperation(fs.readFileSync(filePath, "utf-8"));
+      if (new Date(pendingOperation.expiresAt).getTime() > now().getTime()) {
+        continue;
+      }
+      fs.rmSync(filePath, { force: true });
+      appendLog(buildLogEntry(toPublicPendingOperation(pendingOperation), "expired"));
+    }
+  };
+  const listPendingOperations = () => {
+    cleanupExpiredOperations();
+    if (!fs.existsSync(pendingDir)) {
+      return [];
+    }
+    return fs.readdirSync(pendingDir).map((fileName) => path.resolve(pendingDir, fileName)).map((filePath) => parsePendingOperation(fs.readFileSync(filePath, "utf-8"))).map(toPublicPendingOperation).sort((left, right) => left.createdAt.localeCompare(right.createdAt));
+  };
+  const prepareOperation = (input) => {
+    ensureDirExists(pendingDir);
+    const operationId = `mcpw_${randomBytes(8).toString("hex")}`;
+    const confirmToken = `confirm_${randomBytes(12).toString("hex")}`;
+    const currentTime = now();
+    const createdAt = currentTime.toISOString();
+    const expiresAt = new Date(currentTime.getTime() + ttlMs).toISOString();
+    const pendingOperation = {
+      actor: input.actor,
+      affectedIds: input.affectedIds,
+      confirmTokenHash: hashToken(confirmToken),
+      createdAt,
+      estimatedChangeCount: input.estimatedChangeCount,
+      expiresAt,
+      force: Boolean(input.force),
+      operationId,
+      risk: input.risk,
+      summary: input.summary,
+      toolName: input.toolName
+    };
+    fs.writeFileSync(getPendingPath(operationId), JSON.stringify(pendingOperation, null, 2), "utf-8");
+    appendLog(buildLogEntry(toPublicPendingOperation(pendingOperation), "prepared"));
+    return {
+      ...toPublicPendingOperation(pendingOperation),
+      confirmToken
+    };
+  };
+  const requireConfirmedOperation = (request, expected) => {
+    if (!request.operationId || !request.confirmToken) {
+      throw createError(
+        "CONFIRMATION_REQUIRED",
+        "A destructive MCP write requires operationId and confirmToken after a dry run."
+      );
+    }
+    const pendingPath = getPendingPath(request.operationId);
+    if (!fs.existsSync(pendingPath)) {
+      throw createError("INVALID_CONFIRMATION", "The write confirmation was not found or has already been consumed.");
+    }
+    const pendingOperation = parsePendingOperation(fs.readFileSync(pendingPath, "utf-8"));
+    const publicPendingOperation = toPublicPendingOperation(pendingOperation);
+    if (new Date(pendingOperation.expiresAt).getTime() <= now().getTime()) {
+      fs.rmSync(pendingPath, { force: true });
+      appendLog(buildLogEntry(publicPendingOperation, "expired"));
+      throw createError("CONFIRMATION_EXPIRED", "The write confirmation expired. Run dryRun again.");
+    }
+    if (pendingOperation.toolName !== expected.toolName) {
+      appendLog(buildLogEntry(publicPendingOperation, "rejected", "tool_mismatch"));
+      throw createError("INVALID_CONFIRMATION", "The write confirmation does not match this MCP tool.");
+    }
+    if (pendingOperation.confirmTokenHash !== hashToken(request.confirmToken)) {
+      appendLog(buildLogEntry(publicPendingOperation, "rejected", "token_mismatch"));
+      throw createError("INVALID_CONFIRMATION", "The write confirmation token is invalid.");
+    }
+    fs.rmSync(pendingPath, { force: true });
+    appendLog(buildLogEntry(publicPendingOperation, "confirmed"));
+    return publicPendingOperation;
+  };
+  const ensureDestructiveWriteRequest = (request, input) => {
+    if (request.dryRun ?? true) {
+      return {
+        kind: "dry-run",
+        operation: prepareOperation({
+          ...input,
+          force: request.force ?? input.force
+        })
+      };
+    }
+    return {
+      kind: "confirmed",
+      operation: requireConfirmedOperation(request, { toolName: input.toolName })
+    };
+  };
+  const recordWriteResult = (operation, success, detail) => {
+    appendLog(buildLogEntry(operation, success ? "executed" : "failed", detail));
+  };
+  const getStatus = () => {
+    const pendingOperations = listPendingOperations();
+    return {
+      confirmationTtlMs: ttlMs,
+      logPath,
+      pendingDir,
+      pendingOperationCount: pendingOperations.length,
+      pendingOperations,
+      rootDir,
+      writeToolsEnabled: false
+    };
+  };
+  return {
+    ensureDestructiveWriteRequest,
+    getStatus,
+    listPendingOperations,
+    prepareOperation,
+    recordWriteResult,
+    requireConfirmedOperation
+  };
+};
+
+// src/mcp.ts
+var __dirname = path2.dirname(fileURLToPath(import.meta.url));
 var pkg = JSON.parse(
-  fs.readFileSync(path.resolve(__dirname, "..", "package.json"), "utf-8")
+  fs2.readFileSync(path2.resolve(__dirname, "..", "package.json"), "utf-8")
 );
-async function graphql(serverUrl, query, variables) {
-  const response = await fetch(`${serverUrl}/graphql`, {
+var OCEAN_BRAIN_MCP_TOOLS = {
+  searchNotes: "ocean_brain_search_notes",
+  readNote: "ocean_brain_read_note",
+  createNote: "ocean_brain_create_note",
+  updateNote: "ocean_brain_update_note",
+  listTags: "ocean_brain_list_tags",
+  listNotesByTag: "ocean_brain_list_notes_by_tag",
+  listRecentNotes: "ocean_brain_list_recent_notes",
+  writeSafetyStatus: "ocean_brain_write_safety_status",
+  findNoteCleanupCandidates: "ocean_brain_find_note_cleanup_candidates",
+  createTag: "ocean_brain_create_tag",
+  deleteNote: "ocean_brain_delete_note"
+};
+var noteLayoutSchema = z2.enum(["narrow", "wide", "full"]);
+var normalizeOceanBrainTagName = (name) => {
+  const trimmedName = name.trim();
+  if (!trimmedName) {
+    throw new Error("Tag name is required.");
+  }
+  const normalizedName = trimmedName.startsWith("@") ? trimmedName : `@${trimmedName}`;
+  if (normalizedName === "@" || /\s/.test(normalizedName.slice(1))) {
+    throw new Error("Ocean Brain tag names must be a single token. Example: @project");
+  }
+  return normalizedName;
+};
+async function graphql(serverUrl, token, query, variables) {
+  const response = await fetch(`${serverUrl}/graphql/mcp`, {
     method: "POST",
-    headers: { "Content-Type": "application/json" },
+    headers: {
+      "Content-Type": "application/json",
+      ...token ? { Authorization: `Bearer ${token}` } : {}
+    },
     body: JSON.stringify({ query, variables })
   });
   if (!response.ok) {
@@ -22,24 +252,48 @@ async function graphql(serverUrl, query, variables) {
   }
   const result = await response.json();
   if (result.errors?.length) {
-    throw new Error(`GraphQL error: ${result.errors[0].message}`);
+    throw new Error(formatMcpGraphqlError(result.errors[0]));
   }
   return result.data;
 }
-async function startMcpServer(serverUrl) {
+async function jsonRequest(serverUrl, token, pathName, body) {
+  const response = await fetch(`${serverUrl}${pathName}`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      ...token ? { Authorization: `Bearer ${token}` } : {}
+    },
+    body: JSON.stringify(body)
+  });
+  const result = await response.json();
+  if (!response.ok) {
+    throw new Error(`Request failed: ${result.code || response.status} ${result.message || response.statusText}`);
+  }
+  return result;
+}
+var requireWriteToken = (token, toolName) => {
+  if (token) {
+    return token;
+  }
+  throw new Error(`${toolName} requires an MCP bearer token. Set --token or --token-file.`);
+};
+async function startMcpServer(serverUrl, token, options = {}) {
   const server = new McpServer({
     name: "ocean-brain",
     version: pkg.version
   });
+  const writeSafety = createMcpWriteSafetyCoordinator({
+    rootDir: options.writeSafetyDir ?? defaultMcpWriteSafetyDir()
+  });
   server.tool(
-    "search_notes",
-    "Search notes by keyword. Returns a list of matching notes with title and tags. Use read_note to get full content of a specific note.",
+    OCEAN_BRAIN_MCP_TOOLS.searchNotes,
+    "Search Ocean Brain notes by keyword. Returns matching note titles and tags. Use ocean_brain_read_note to get full content for a specific note.",
     {
-      query: z.string().describe("Search keyword"),
-      limit: z.number().optional().default(10).describe("Max results (default: 10)")
+      query: z2.string().describe("Search keyword"),
+      limit: z2.number().optional().default(10).describe("Max results (default: 10)")
     },
     async ({ query, limit }) => {
-      const data = await graphql(serverUrl, `
+      const data = await graphql(serverUrl, token, `
                 query ($searchFilter: SearchFilterInput, $pagination: PaginationInput) {
                     allNotes(searchFilter: $searchFilter, pagination: $pagination) {
                         totalCount
@@ -73,14 +327,14 @@ async function startMcpServer(serverUrl) {
     }
   );
   server.tool(
-    "read_note",
-    "Read content of a note by ID. Returns truncated by default (1000 chars). Set maxLength to 0 for full content only when necessary.",
+    OCEAN_BRAIN_MCP_TOOLS.readNote,
+    "Read an Ocean Brain note by ID. Returns truncated content by default (1000 chars). Set maxLength to 0 only when full content is necessary.",
     {
-      id: z.string().describe("Note ID"),
-      maxLength: z.number().optional().default(1e3).describe("Max content length in characters. 0 for full content. (default: 1000)")
+      id: z2.string().describe("Note ID"),
+      maxLength: z2.number().optional().default(1e3).describe("Max content length in characters. 0 for full content. (default: 1000)")
     },
     async ({ id, maxLength }) => {
-      const data = await graphql(serverUrl, `
+      const data = await graphql(serverUrl, token, `
                 query ($id: ID!) {
                     note(id: $id) {
                         id
@@ -120,11 +374,59 @@ async function startMcpServer(serverUrl) {
     }
   );
   server.tool(
-    "list_tags",
-    "List all tags with their note counts.",
+    OCEAN_BRAIN_MCP_TOOLS.createNote,
+    "Create an Ocean Brain note from markdown through the MCP write path. This is the preferred way to author new notes without sending internal BlockNote JSON.",
+    {
+      title: z2.string().describe("Note title"),
+      markdown: z2.string().optional().default("").describe("Markdown body for the new note. Defaults to an empty note body."),
+      layout: noteLayoutSchema.optional().describe("Optional note layout: narrow, wide, or full.")
+    },
+    async ({ title, markdown, layout }) => {
+      const writeToken = requireWriteToken(token, OCEAN_BRAIN_MCP_TOOLS.createNote);
+      const result = await jsonRequest(serverUrl, writeToken, "/api/mcp/notes/create", {
+        title,
+        markdown,
+        ...layout ? { layout } : {}
+      });
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify(result, null, 2)
+        }]
+      };
+    }
+  );
+  server.tool(
+    OCEAN_BRAIN_MCP_TOOLS.updateNote,
+    "Update an Ocean Brain note from markdown through the MCP write path. Pass only the fields you want to change.",
+    {
+      id: z2.string().describe("Note ID to update"),
+      title: z2.string().optional().describe("New note title"),
+      markdown: z2.string().optional().describe("Replacement markdown body"),
+      layout: noteLayoutSchema.optional().describe("Optional note layout: narrow, wide, or full.")
+    },
+    async ({ id, title, markdown, layout }) => {
+      const writeToken = requireWriteToken(token, OCEAN_BRAIN_MCP_TOOLS.updateNote);
+      const result = await jsonRequest(serverUrl, writeToken, "/api/mcp/notes/update", {
+        id,
+        ...title !== void 0 ? { title } : {},
+        ...markdown !== void 0 ? { markdown } : {},
+        ...layout ? { layout } : {}
+      });
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify(result, null, 2)
+        }]
+      };
+    }
+  );
+  server.tool(
+    OCEAN_BRAIN_MCP_TOOLS.listTags,
+    "List Ocean Brain tags with their note counts.",
     {},
     async () => {
-      const data = await graphql(serverUrl, `
+      const data = await graphql(serverUrl, token, `
                 query ($searchFilter: SearchFilterInput, $pagination: PaginationInput) {
                     allTags(searchFilter: $searchFilter, pagination: $pagination) {
                         totalCount
@@ -149,13 +451,93 @@ async function startMcpServer(serverUrl) {
     }
   );
   server.tool(
-    "list_recent_notes",
-    "List recently updated notes. Returns titles and tags only. Use read_note to get content of a specific note.",
+    OCEAN_BRAIN_MCP_TOOLS.listNotesByTag,
+    "List Ocean Brain notes for a specific tag name. The tool accepts either @tag or tag and resolves it to the canonical Ocean Brain tag name first.",
+    {
+      tag: z2.string().describe("Tag name to inspect. You can pass @project or project."),
+      limit: z2.number().optional().default(20).describe("Max results (default: 20)"),
+      offset: z2.number().optional().default(0).describe("Pagination offset (default: 0)")
+    },
+    async ({ tag, limit, offset }) => {
+      const normalizedTag = normalizeOceanBrainTagName(tag);
+      const tagsData = await graphql(serverUrl, token, `
+                query ($searchFilter: SearchFilterInput, $pagination: PaginationInput) {
+                    allTags(searchFilter: $searchFilter, pagination: $pagination) {
+                        totalCount
+                        tags {
+                            id
+                            name
+                            referenceCount
+                        }
+                    }
+                }
+            `, {
+        searchFilter: { query: normalizedTag },
+        pagination: { limit: 100, offset: 0 }
+      });
+      const tagResult = tagsData?.allTags;
+      const exactMatches = tagResult.tags.filter((item) => item.name === normalizedTag);
+      if (exactMatches.length === 0) {
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              requestedTag: tag,
+              normalizedTag,
+              tagFound: false,
+              noteCount: 0,
+              notes: []
+            }, null, 2)
+          }]
+        };
+      }
+      const selectedTag = exactMatches[0];
+      const notesData = await graphql(serverUrl, token, `
+                query ($searchFilter: SearchFilterInput, $pagination: PaginationInput) {
+                    tagNotes(searchFilter: $searchFilter, pagination: $pagination) {
+                        totalCount
+                        notes {
+                            id
+                            title
+                            updatedAt
+                            tags { id name }
+                        }
+                    }
+                }
+            `, {
+        searchFilter: { query: selectedTag.id },
+        pagination: { limit, offset }
+      });
+      const noteResult = notesData?.tagNotes;
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            requestedTag: tag,
+            normalizedTag,
+            tagFound: true,
+            duplicateExactMatchCount: exactMatches.length,
+            tag: selectedTag,
+            totalCount: noteResult.totalCount,
+            notes: noteResult.notes.map((note) => ({
+              id: note.id,
+              title: note.title,
+              updatedAt: note.updatedAt,
+              tags: note.tags.map((item) => item.name)
+            }))
+          }, null, 2)
+        }]
+      };
+    }
+  );
+  server.tool(
+    OCEAN_BRAIN_MCP_TOOLS.listRecentNotes,
+    "List recently updated Ocean Brain notes. Returns titles and tags only. Use ocean_brain_read_note to get full content for a specific note.",
     {
-      limit: z.number().optional().default(10).describe("Max results (default: 10)")
+      limit: z2.number().optional().default(10).describe("Max results (default: 10)")
     },
     async ({ limit }) => {
-      const data = await graphql(serverUrl, `
+      const data = await graphql(serverUrl, token, `
                 query ($searchFilter: SearchFilterInput, $pagination: PaginationInput) {
                     allNotes(searchFilter: $searchFilter, pagination: $pagination) {
                         totalCount
@@ -186,9 +568,188 @@ async function startMcpServer(serverUrl) {
       };
     }
   );
+  server.tool(
+    OCEAN_BRAIN_MCP_TOOLS.writeSafetyStatus,
+    "Inspect pending destructive write confirmations and local operation log state for enabled Ocean Brain MCP write tools.",
+    {},
+    async () => {
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            ...writeSafety.getStatus(),
+            destructiveWriteTools: [OCEAN_BRAIN_MCP_TOOLS.deleteNote],
+            writeTools: [
+              OCEAN_BRAIN_MCP_TOOLS.createNote,
+              OCEAN_BRAIN_MCP_TOOLS.updateNote,
+              OCEAN_BRAIN_MCP_TOOLS.createTag,
+              OCEAN_BRAIN_MCP_TOOLS.deleteNote
+            ],
+            writeToolsEnabled: true
+          }, null, 2)
+        }]
+      };
+    }
+  );
+  server.tool(
+    OCEAN_BRAIN_MCP_TOOLS.findNoteCleanupCandidates,
+    "Find Ocean Brain note cleanup candidates for temporary or draft notes before deletion. Use this before ocean_brain_delete_note.",
+    {
+      keywords: z2.string().optional().default("temp tmp draft test wip").describe("Keywords that mark a note as a cleanup candidate. Comma or space separated."),
+      limit: z2.number().optional().default(20).describe("Max results (default: 20)"),
+      offset: z2.number().optional().default(0).describe("Pagination offset (default: 0)")
+    },
+    async ({ keywords, limit, offset }) => {
+      const normalizedKeywords = keywords.split(/[,\s]+/).map((keyword) => keyword.trim()).filter(Boolean);
+      const data = await graphql(serverUrl, token, `
+                query ($query: String, $pagination: PaginationInput) {
+                    noteCleanupCandidates(query: $query, pagination: $pagination) {
+                        id
+                        title
+                        updatedAt
+                        pinned
+                        tagNames
+                        reminderCount
+                        backReferenceCount
+                        matchedTerms
+                        reasons
+                        requiresForce
+                        forceReasons
+                    }
+                }
+            `, {
+        query: keywords,
+        pagination: { limit, offset }
+      });
+      const result = data?.noteCleanupCandidates;
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            keywords: normalizedKeywords,
+            limit,
+            offset,
+            candidateCount: result.length,
+            notes: result
+          }, null, 2)
+        }]
+      };
+    }
+  );
+  server.tool(
+    OCEAN_BRAIN_MCP_TOOLS.createTag,
+    "Create an Ocean Brain tag through the MCP write path. The tool accepts either @tag or tag and creates the canonical Ocean Brain tag if it does not already exist.",
+    {
+      name: z2.string().describe("Tag name to create. You can pass @project or project.")
+    },
+    async ({ name }) => {
+      const writeToken = requireWriteToken(token, OCEAN_BRAIN_MCP_TOOLS.createTag);
+      const result = await jsonRequest(serverUrl, writeToken, "/api/mcp/tags/create", {
+        name
+      });
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify(result, null, 2)
+        }]
+      };
+    }
+  );
+  server.tool(
+    OCEAN_BRAIN_MCP_TOOLS.deleteNote,
+    "Delete an Ocean Brain note safely through a dry-run and confirmation flow. Start with dryRun=true, then call again with dryRun=false, operationId, and confirmToken.",
+    {
+      id: z2.string().describe("Note ID to delete"),
+      ...destructiveMcpWriteFields
+    },
+    async ({ id, dryRun, operationId, confirmToken, force }) => {
+      const writeToken = requireWriteToken(token, OCEAN_BRAIN_MCP_TOOLS.deleteNote);
+      const data = await graphql(serverUrl, writeToken, `
+                query ($id: ID!) {
+                    noteCleanupPreview(id: $id) {
+                        id
+                        title
+                        updatedAt
+                        pinned
+                        tagNames
+                        reminderCount
+                        backReferences {
+                            id
+                            title
+                        }
+                        orphanedTagNames
+                        requiresForce
+                        forceReasons
+                    }
+                }
+            `, { id });
+      const preview = data?.noteCleanupPreview;
+      if (!preview) {
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              deleted: false,
+              reason: "NOTE_NOT_FOUND",
+              id
+            }, null, 2)
+          }]
+        };
+      }
+      const intent = writeSafety.ensureDestructiveWriteRequest(
+        { dryRun, operationId, confirmToken, force },
+        {
+          actor: "mcp-bearer",
+          affectedIds: [preview.id],
+          estimatedChangeCount: 1,
+          force: preview.requiresForce,
+          risk: "destructive",
+          summary: `Delete note ${preview.id} (${preview.title})`,
+          toolName: OCEAN_BRAIN_MCP_TOOLS.deleteNote
+        }
+      );
+      if (intent.kind === "dry-run") {
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              mode: "dry-run",
+              preview,
+              operation: intent.operation
+            }, null, 2)
+          }]
+        };
+      }
+      if (intent.operation.force && !force) {
+        throw new Error(`${OCEAN_BRAIN_MCP_TOOLS.deleteNote} requires force=true because ${preview.forceReasons.join(", ")}.`);
+      }
+      try {
+        const result = await jsonRequest(serverUrl, writeToken, "/api/mcp/notes/delete", {
+          id: preview.id
+        });
+        writeSafety.recordWriteResult(intent.operation, true);
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              mode: "commit",
+              preview,
+              operation: intent.operation,
+              result
+            }, null, 2)
+          }]
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown MCP note delete error";
+        writeSafety.recordWriteResult(intent.operation, false, message);
+        throw error;
+      }
+    }
+  );
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }
 export {
+  OCEAN_BRAIN_MCP_TOOLS,
   startMcpServer
 };