ocean-brain 0.5.0 → 0.6.0

package/dist/mcp.js

@@ -6,7 +6,7 @@ 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";
+import { z as z3 } from "zod";
 
 // src/mcp-write-safety.ts
 import crypto from "crypto";
@@ -15,11 +15,16 @@ import os from "os";
 import path from "path";
 import { z } from "zod";
 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."),
+  dryRun: z.boolean().optional().default(true).describe("Preview the destructive change first. Commit only after dry-run returns operation.operationId and operation.confirmToken."),
+  operationId: z.string().optional().describe("Dry-run response operation.operationId. Required when dryRun is false."),
+  confirmToken: z.string().optional().describe("Dry-run response operation.confirmToken. 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 confirmedMcpWriteFields = {
+  dryRun: z.boolean().optional().default(true).describe("Preview the write first. Commit only after dry-run returns operation.operationId and operation.confirmToken."),
+  operationId: z.string().optional().describe("Dry-run response operation.operationId. Required when dryRun is false."),
+  confirmToken: z.string().optional().describe("Dry-run response operation.confirmToken. Required when dryRun is false.")
+};
 var McpCliWriteSafetyError = class extends Error {
   code;
   constructor(code, message) {
@@ -42,6 +47,7 @@ var toPublicPendingOperation = (operation) => ({
   estimatedChangeCount: operation.estimatedChangeCount,
   expiresAt: operation.expiresAt,
   force: operation.force,
+  ...operation.operationFingerprint ? { operationFingerprint: operation.operationFingerprint } : {},
   operationId: operation.operationId,
   risk: operation.risk,
   summary: operation.summary,
@@ -126,6 +132,7 @@ var createMcpWriteSafetyCoordinator = (options = {}) => {
       estimatedChangeCount: input.estimatedChangeCount,
       expiresAt,
       force: Boolean(input.force),
+      ...input.operationFingerprint ? { operationFingerprint: input.operationFingerprint } : {},
       operationId,
       risk: input.risk,
       summary: input.summary,
@@ -160,6 +167,10 @@ var createMcpWriteSafetyCoordinator = (options = {}) => {
       appendLog(buildLogEntry(publicPendingOperation, "rejected", "tool_mismatch"));
       throw createError("INVALID_CONFIRMATION", "The write confirmation does not match this MCP tool.");
     }
+    if (expected.operationFingerprint && pendingOperation.operationFingerprint !== expected.operationFingerprint) {
+      appendLog(buildLogEntry(publicPendingOperation, "rejected", "operation_fingerprint_mismatch"));
+      throw createError("INVALID_CONFIRMATION", "The write confirmation does not match this MCP operation.");
+    }
     if (pendingOperation.confirmTokenHash !== hashToken(request.confirmToken)) {
       appendLog(buildLogEntry(publicPendingOperation, "rejected", "token_mismatch"));
       throw createError("INVALID_CONFIRMATION", "The write confirmation token is invalid.");
@@ -180,7 +191,10 @@ var createMcpWriteSafetyCoordinator = (options = {}) => {
     }
     return {
       kind: "confirmed",
-      operation: requireConfirmedOperation(request, { toolName: input.toolName })
+      operation: requireConfirmedOperation(request, {
+        toolName: input.toolName,
+        operationFingerprint: input.operationFingerprint
+      })
     };
   };
   const recordWriteResult = (operation, success, detail) => {
@@ -215,6 +229,12 @@ var formatBackReferenceLine = (backReference) => {
   }
   return `- ${backReference.id}: ${backReference.title}`;
 };
+var formatPropertyLine = (property) => {
+  const displayValue = (property.option?.label ?? property.value) || "(empty)";
+  const rawValue = property.option?.value ?? property.value;
+  const rawValueLabel = rawValue ? `, value=${rawValue}` : "";
+  return `- ${property.key} (${property.name}): ${displayValue} [${property.valueType}${rawValueLabel}]`;
+};
 var formatMcpReadNoteOutput = ({
   note,
   backReferences,
@@ -227,10 +247,14 @@ var formatMcpReadNoteOutput = ({
     markdown = markdown.slice(0, maxLength);
   }
   const backReferenceLines = backReferences.length > 0 ? backReferences.map(formatBackReferenceLine) : ["- (none)"];
+  const propertyLines = note.properties && note.properties.length > 0 ? note.properties.map(formatPropertyLine) : ["- (none)"];
   return [
     `# ${note.title}`,
     "",
     `Tags: ${note.tags.map((tag) => tag.name).join(", ") || "(none)"}`,
+    "",
+    "Properties:",
+    ...propertyLines,
     `Created: ${note.createdAt}`,
     `Updated: ${note.updatedAt}`,
     ...truncated ? [`Content: ${totalLength} chars (showing first ${maxLength})`] : [],
@@ -243,6 +267,476 @@ var formatMcpReadNoteOutput = ({
   ].join("\n");
 };
 
+// src/mcp-intent-write-tools.ts
+import crypto2 from "crypto";
+import { z as z2 } from "zod";
+var markdownPatchSelectorSchema = z2.discriminatedUnion("type", [
+  z2.object({
+    type: z2.literal("exact_text"),
+    text: z2.string(),
+    before: z2.string().optional(),
+    after: z2.string().optional()
+  }),
+  z2.object({
+    type: z2.literal("match_candidate"),
+    text: z2.string(),
+    matchIndex: z2.number().int().nonnegative(),
+    lineStart: z2.number().int().positive(),
+    matchSha256: z2.string(),
+    surroundingHash: z2.string(),
+    positionHint: z2.enum(["first", "last"]).optional()
+  })
+]);
+var markdownPatchOperationSchema = z2.discriminatedUnion("type", [
+  z2.object({
+    type: z2.literal("replace"),
+    replacement: z2.string()
+  }),
+  z2.object({
+    type: z2.literal("insert_before"),
+    insertion: z2.string()
+  }),
+  z2.object({
+    type: z2.literal("insert_after"),
+    insertion: z2.string()
+  })
+]);
+var markdownAppendPlacementSchema = z2.discriminatedUnion("type", [
+  z2.object({
+    type: z2.literal("end")
+  }),
+  z2.object({
+    type: z2.literal("after_heading"),
+    heading: z2.string(),
+    level: z2.number().int().min(1).max(6).optional()
+  })
+]);
+var markdownWritePolicySchema = z2.object({
+  allowNoop: z2.boolean().optional(),
+  maxChangedChars: z2.number().int().nonnegative().optional(),
+  maxChangedLines: z2.number().int().nonnegative().optional(),
+  preserveTags: z2.union([z2.boolean(), z2.literal("warn")]).optional(),
+  preserveReferences: z2.union([z2.boolean(), z2.literal("warn")]).optional()
+}).optional();
+var MCP_METADATA_PROPERTY_PATCH_LIMIT = 50;
+var normalizeMetadataPropertyKey = (key) => key.trim().toLowerCase().replace(/\s+/g, "-");
+var metadataPropertyPatchSchema = z2.object({
+  set: z2.array(z2.object({
+    key: z2.string().min(1).describe("Property key from ocean_brain_list_properties."),
+    value: z2.string().describe("String value: select option.value, date YYYY-MM-DD, boolean true/false, number finite string, url http(s).")
+  })).max(MCP_METADATA_PROPERTY_PATCH_LIMIT).optional().describe("Set up to 50 property values. Keys must be unique."),
+  deleteKeys: z2.array(z2.string().min(1)).max(MCP_METADATA_PROPERTY_PATCH_LIMIT).optional().describe("Remove up to 50 property values from this note. Keys must be unique and not also in set.")
+}).superRefine((patch, context) => {
+  if ((patch.set?.length ?? 0) === 0 && (patch.deleteKeys?.length ?? 0) === 0) {
+    context.addIssue({
+      code: z2.ZodIssueCode.custom,
+      message: "properties must include set or deleteKeys."
+    });
+    return;
+  }
+  const setKeys = /* @__PURE__ */ new Set();
+  for (const item of patch.set ?? []) {
+    const key = normalizeMetadataPropertyKey(item.key);
+    if (setKeys.has(key)) {
+      context.addIssue({
+        code: z2.ZodIssueCode.custom,
+        message: `properties.set contains duplicate key ${key}.`
+      });
+    }
+    setKeys.add(key);
+  }
+  const deleteKeys = /* @__PURE__ */ new Set();
+  for (const rawKey of patch.deleteKeys ?? []) {
+    const key = normalizeMetadataPropertyKey(rawKey);
+    if (deleteKeys.has(key)) {
+      context.addIssue({
+        code: z2.ZodIssueCode.custom,
+        message: `properties.deleteKeys contains duplicate key ${key}.`
+      });
+    }
+    if (setKeys.has(key)) {
+      context.addIssue({
+        code: z2.ZodIssueCode.custom,
+        message: `properties cannot set and delete ${key} in one request.`
+      });
+    }
+    deleteKeys.add(key);
+  }
+}).optional();
+var sha256 = (value) => crypto2.createHash("sha256").update(value).digest("hex");
+var normalizeServerUrl = (serverUrl) => {
+  try {
+    const url = new URL(serverUrl);
+    url.hash = "";
+    return url.toString().replace(/\/$/, "");
+  } catch {
+    return serverUrl.replace(/\/$/, "");
+  }
+};
+var createIntentWriteOperationFingerprint = (serverUrl, token, toolName, payload) => {
+  return sha256(JSON.stringify({
+    payload,
+    serverUrl: normalizeServerUrl(serverUrl),
+    tokenDigest: token ? sha256(token) : null,
+    toolName
+  }));
+};
+var getErrorDetail = (error) => {
+  return error instanceof Error ? error.message : "Unknown MCP write error";
+};
+var prepareConfirmedWriteOperation = (writeSafety, result, input) => {
+  if (result.status !== "dry_run") {
+    return result;
+  }
+  return {
+    ...result,
+    operation: writeSafety.prepareOperation({
+      actor: "mcp-bearer",
+      affectedIds: input.affectedIds,
+      estimatedChangeCount: result.proposed?.changedLineCount ?? 1,
+      operationFingerprint: input.operationFingerprint,
+      risk: "high-impact",
+      summary: input.summary,
+      toolName: input.toolName
+    })
+  };
+};
+var requireConfirmedWriteOperation = (writeSafety, request, input) => {
+  const intent = writeSafety.ensureDestructiveWriteRequest(
+    request,
+    {
+      actor: "mcp-bearer",
+      affectedIds: input.affectedIds,
+      estimatedChangeCount: 1,
+      operationFingerprint: input.operationFingerprint,
+      risk: "high-impact",
+      summary: input.summary,
+      toolName: input.toolName
+    }
+  );
+  if (intent.kind !== "confirmed") {
+    throw new Error("Expected a confirmed MCP write operation.");
+  }
+  return intent.operation;
+};
+var executeConfirmedWrite = async (writeSafety, operation, request) => {
+  try {
+    const result = await request();
+    writeSafety.recordWriteResult(
+      operation,
+      result.status === "applied",
+      result.status === "applied" ? void 0 : result.reason
+    );
+    return result;
+  } catch (error) {
+    writeSafety.recordWriteResult(operation, false, getErrorDetail(error));
+    throw error;
+  }
+};
+var registerIntentWriteTools = (server, {
+  jsonRequest: jsonRequest2,
+  requireWriteToken: requireWriteToken2,
+  serverUrl,
+  token,
+  tools,
+  writeSafety
+}) => {
+  server.tool(
+    tools.patchNoteMarkdown,
+    "Patch a small part of an Ocean Brain note. Dry-run is the default; commit requires operationId and confirmToken from the dry-run result.",
+    {
+      id: z2.string().describe("Note ID to patch"),
+      expectedUpdatedAt: z2.string().optional().describe("Expected note updatedAt from a prior read. Required unless baseMarkdownSha256 is provided."),
+      baseMarkdownSha256: z2.string().optional().describe("SHA-256 of the current markdown. Required unless expectedUpdatedAt is provided."),
+      intent: z2.string().describe("Human-readable reason for the patch."),
+      selector: markdownPatchSelectorSchema.describe("Exact text or previously returned match candidate."),
+      operation: markdownPatchOperationSchema.describe("replace, insert_before, or insert_after."),
+      policy: markdownWritePolicySchema,
+      ...confirmedMcpWriteFields
+    },
+    async ({ id, expectedUpdatedAt, baseMarkdownSha256, intent, selector, operation, policy, dryRun, operationId, confirmToken }) => {
+      const writeToken = requireWriteToken2(token, tools.patchNoteMarkdown);
+      const payload = {
+        id,
+        ...expectedUpdatedAt ? { expectedUpdatedAt } : {},
+        ...baseMarkdownSha256 ? { baseMarkdownSha256 } : {},
+        intent,
+        selector,
+        operation,
+        ...policy ? { policy } : {}
+      };
+      const operationFingerprint = createIntentWriteOperationFingerprint(serverUrl, writeToken, tools.patchNoteMarkdown, payload);
+      if (dryRun) {
+        const result2 = await jsonRequest2(serverUrl, writeToken, "/api/mcp/notes/patch-markdown", {
+          ...payload,
+          dryRun: true
+        });
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify(prepareConfirmedWriteOperation(writeSafety, result2, {
+              affectedIds: [id],
+              operationFingerprint,
+              summary: intent,
+              toolName: tools.patchNoteMarkdown
+            }), null, 2)
+          }]
+        };
+      }
+      const confirmedOperation = requireConfirmedWriteOperation(
+        writeSafety,
+        { dryRun, operationId, confirmToken },
+        {
+          affectedIds: [id],
+          operationFingerprint,
+          summary: intent,
+          toolName: tools.patchNoteMarkdown
+        }
+      );
+      const result = await executeConfirmedWrite(
+        writeSafety,
+        confirmedOperation,
+        () => jsonRequest2(serverUrl, writeToken, "/api/mcp/notes/patch-markdown", {
+          ...payload,
+          dryRun: false
+        })
+      );
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify(result, null, 2)
+        }]
+      };
+    }
+  );
+  server.tool(
+    tools.appendNoteMarkdown,
+    "Append markdown to a note without replacing existing body content. Dry-run is the default; commit requires operationId and confirmToken.",
+    {
+      id: z2.string().describe("Note ID to append to"),
+      expectedUpdatedAt: z2.string().optional().describe("Expected note updatedAt from a prior read. Required unless baseMarkdownSha256 is provided."),
+      baseMarkdownSha256: z2.string().optional().describe("SHA-256 of the current markdown. Required unless expectedUpdatedAt is provided."),
+      intent: z2.string().describe("Human-readable reason for the append."),
+      insertion: z2.string().describe("Markdown to append. Tags are body tokens such as [@tag] or [#tag]."),
+      placement: markdownAppendPlacementSchema.optional().describe("Default is end. after_heading requires one unique matching heading."),
+      separator: z2.enum(["\n\n", "\n"]).optional().describe("Separator inserted around appended markdown. Defaults to a blank line."),
+      policy: markdownWritePolicySchema,
+      ...confirmedMcpWriteFields
+    },
+    async ({ id, expectedUpdatedAt, baseMarkdownSha256, intent, insertion, placement, separator, policy, dryRun, operationId, confirmToken }) => {
+      const writeToken = requireWriteToken2(token, tools.appendNoteMarkdown);
+      const payload = {
+        id,
+        ...expectedUpdatedAt ? { expectedUpdatedAt } : {},
+        ...baseMarkdownSha256 ? { baseMarkdownSha256 } : {},
+        intent,
+        insertion,
+        ...placement ? { placement } : {},
+        ...separator ? { separator } : {},
+        ...policy ? { policy } : {}
+      };
+      const operationFingerprint = createIntentWriteOperationFingerprint(serverUrl, writeToken, tools.appendNoteMarkdown, payload);
+      if (dryRun) {
+        const result2 = await jsonRequest2(serverUrl, writeToken, "/api/mcp/notes/append-markdown", {
+          ...payload,
+          dryRun: true
+        });
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify(prepareConfirmedWriteOperation(writeSafety, result2, {
+              affectedIds: [id],
+              operationFingerprint,
+              summary: intent,
+              toolName: tools.appendNoteMarkdown
+            }), null, 2)
+          }]
+        };
+      }
+      const confirmedOperation = requireConfirmedWriteOperation(
+        writeSafety,
+        { dryRun, operationId, confirmToken },
+        {
+          affectedIds: [id],
+          operationFingerprint,
+          summary: intent,
+          toolName: tools.appendNoteMarkdown
+        }
+      );
+      const result = await executeConfirmedWrite(
+        writeSafety,
+        confirmedOperation,
+        () => jsonRequest2(serverUrl, writeToken, "/api/mcp/notes/append-markdown", {
+          ...payload,
+          dryRun: false
+        })
+      );
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify(result, null, 2)
+        }]
+      };
+    }
+  );
+  server.tool(
+    tools.updateNoteMetadata,
+    "Update note title/layout/properties. For properties, call ocean_brain_list_properties first. Use existing property key and string value only; do not send valueType. select=option.value, date=YYYY-MM-DD, boolean=true/false, number=finite string, url=http(s). Use deleteKeys to remove values. Definitions are not created.",
+    {
+      id: z2.string().describe("Note ID to update"),
+      expectedUpdatedAt: z2.string().describe("Expected note updatedAt from a prior read."),
+      title: z2.string().optional().describe("New note title"),
+      layout: z2.enum(["narrow", "wide", "full"]).optional().describe("New note layout"),
+      properties: metadataPropertyPatchSchema.describe("Patch existing shared property values. Include set and/or deleteKeys; empty patches are rejected."),
+      ...confirmedMcpWriteFields
+    },
+    async ({ id, expectedUpdatedAt, title, layout, properties, dryRun, operationId, confirmToken }) => {
+      const writeToken = requireWriteToken2(token, tools.updateNoteMetadata);
+      const payload = {
+        id,
+        expectedUpdatedAt,
+        ...title !== void 0 ? { title } : {},
+        ...layout ? { layout } : {},
+        ...properties ? { properties } : {}
+      };
+      const summary = properties ? `Update note ${id} metadata and properties` : `Update note ${id} metadata`;
+      const operationFingerprint = createIntentWriteOperationFingerprint(serverUrl, writeToken, tools.updateNoteMetadata, payload);
+      if (dryRun) {
+        const result2 = await jsonRequest2(serverUrl, writeToken, "/api/mcp/notes/metadata", {
+          ...payload,
+          dryRun: true
+        });
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify(prepareConfirmedWriteOperation(writeSafety, result2, {
+              affectedIds: [id],
+              operationFingerprint,
+              summary,
+              toolName: tools.updateNoteMetadata
+            }), null, 2)
+          }]
+        };
+      }
+      const confirmedOperation = requireConfirmedWriteOperation(
+        writeSafety,
+        { dryRun, operationId, confirmToken },
+        {
+          affectedIds: [id],
+          operationFingerprint,
+          summary,
+          toolName: tools.updateNoteMetadata
+        }
+      );
+      const result = await executeConfirmedWrite(
+        writeSafety,
+        confirmedOperation,
+        () => jsonRequest2(serverUrl, writeToken, "/api/mcp/notes/metadata", {
+          ...payload,
+          dryRun: false
+        })
+      );
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify(result, null, 2)
+        }]
+      };
+    }
+  );
+  server.tool(
+    tools.replaceNoteMarkdown,
+    "Replace a note body as a high-impact full overwrite. Dry-run returns a full diff; commit requires operationId and confirmToken.",
+    {
+      id: z2.string().describe("Note ID to replace"),
+      expectedUpdatedAt: z2.string().optional().describe("Expected note updatedAt from a prior read. Required unless baseMarkdownSha256 is provided."),
+      baseMarkdownSha256: z2.string().optional().describe("SHA-256 of the current markdown. Required unless expectedUpdatedAt is provided."),
+      intent: z2.string().describe("Human-readable reason for the full replace."),
+      replacement: z2.string().describe("Complete replacement markdown body. Tags are body tokens such as [@tag] or [#tag]."),
+      policy: markdownWritePolicySchema,
+      ...confirmedMcpWriteFields
+    },
+    async ({ id, expectedUpdatedAt, baseMarkdownSha256, intent, replacement, policy, dryRun, operationId, confirmToken }) => {
+      const writeToken = requireWriteToken2(token, tools.replaceNoteMarkdown);
+      const payload = {
+        id,
+        ...expectedUpdatedAt ? { expectedUpdatedAt } : {},
+        ...baseMarkdownSha256 ? { baseMarkdownSha256 } : {},
+        intent,
+        replacement,
+        ...policy ? { policy } : {}
+      };
+      const operationFingerprint = createIntentWriteOperationFingerprint(serverUrl, writeToken, tools.replaceNoteMarkdown, payload);
+      if (dryRun) {
+        const result2 = await jsonRequest2(serverUrl, writeToken, "/api/mcp/notes/replace-markdown", {
+          ...payload,
+          dryRun: true
+        });
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify(prepareConfirmedWriteOperation(writeSafety, result2, {
+              affectedIds: [id],
+              operationFingerprint,
+              summary: intent,
+              toolName: tools.replaceNoteMarkdown
+            }), null, 2)
+          }]
+        };
+      }
+      const confirmedOperation = requireConfirmedWriteOperation(
+        writeSafety,
+        { dryRun, operationId, confirmToken },
+        {
+          affectedIds: [id],
+          operationFingerprint,
+          summary: intent,
+          toolName: tools.replaceNoteMarkdown
+        }
+      );
+      const result = await executeConfirmedWrite(
+        writeSafety,
+        confirmedOperation,
+        () => jsonRequest2(serverUrl, writeToken, "/api/mcp/notes/replace-markdown", {
+          ...payload,
+          dryRun: false
+        })
+      );
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify(result, null, 2)
+        }]
+      };
+    }
+  );
+};
+
+// src/mcp-property-query-output.ts
+var formatPropertyQueryResponse = ({
+  result,
+  query,
+  includeProperties,
+  propertyKeys
+}) => ({
+  query: {
+    ...query,
+    includeProperties,
+    propertyKeys
+  },
+  totalCount: result.totalCount,
+  notes: result.notes.map((note) => ({
+    id: note.id,
+    title: note.title,
+    createdAt: note.createdAt,
+    updatedAt: note.updatedAt,
+    tags: note.tags.map((item) => item.name),
+    ...includeProperties ? {
+      properties: propertyKeys.length > 0 ? (note.properties ?? []).filter((property) => propertyKeys.includes(property.key)) : note.properties ?? []
+    } : {}
+  }))
+});
+
 // src/mcp.ts
 var __dirname = path2.dirname(fileURLToPath(import.meta.url));
 var pkg = JSON.parse(
@@ -253,7 +747,13 @@ var OCEAN_BRAIN_MCP_TOOLS = {
   readNote: "ocean_brain_read_note",
   createNote: "ocean_brain_create_note",
   updateNote: "ocean_brain_update_note",
+  patchNoteMarkdown: "ocean_brain_patch_note_markdown",
+  appendNoteMarkdown: "ocean_brain_append_note_markdown",
+  updateNoteMetadata: "ocean_brain_update_note_metadata",
+  replaceNoteMarkdown: "ocean_brain_replace_note_markdown",
   listTags: "ocean_brain_list_tags",
+  listProperties: "ocean_brain_list_properties",
+  queryNotesByProperties: "ocean_brain_query_notes_by_properties",
   listNotesByTag: "ocean_brain_list_notes_by_tag",
   listNotesByTags: "ocean_brain_list_notes_by_tags",
   listRecentNotes: "ocean_brain_list_recent_notes",
@@ -262,8 +762,18 @@ var OCEAN_BRAIN_MCP_TOOLS = {
   createTag: "ocean_brain_create_tag",
   deleteNote: "ocean_brain_delete_note"
 };
-var noteLayoutSchema = z2.enum(["narrow", "wide", "full"]);
-var tagMatchModeSchema = z2.enum(["and", "or"]);
+var noteLayoutSchema = z3.enum(["narrow", "wide", "full"]);
+var tagMatchModeSchema = z3.enum(["and", "or"]);
+var propertyValueTypeSchema = z3.enum(["text", "url", "number", "date", "boolean", "select"]);
+var propertyFilterOperatorSchema = z3.enum(["equals", "before", "after", "exists", "notExists"]);
+var viewSortBySchema = z3.enum(["updatedAt", "createdAt", "title"]);
+var viewSortOrderSchema = z3.enum(["asc", "desc"]);
+var propertyFilterSchema = z3.object({
+  key: z3.string().describe("Property key from ocean_brain_list_properties, e.g. state"),
+  valueType: propertyValueTypeSchema.describe("Property value type from the property definition"),
+  operator: propertyFilterOperatorSchema.describe("Filter operator. before/after are only valid for date or number properties."),
+  value: z3.string().nullable().optional().describe("Filter value. Required unless operator is exists or notExists. select=option.value, date=YYYY-MM-DD, boolean=true/false, number=finite, url=http(s).")
+});
 var normalizeOceanBrainTagName = (name) => {
   const trimmedName = name.trim();
   if (!trimmedName) {
@@ -349,8 +859,8 @@ async function startMcpServer(serverUrl, token, options = {}) {
     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: z2.string().describe("Search keyword"),
-      limit: z2.number().optional().default(10).describe("Max results (default: 10)")
+      query: z3.string().describe("Search keyword"),
+      limit: z3.number().optional().default(10).describe("Max results (default: 10)")
     },
     async ({ query, limit }) => {
       const data = await graphql(serverUrl, token, `
@@ -388,10 +898,10 @@ async function startMcpServer(serverUrl, token, options = {}) {
   );
   server.tool(
     OCEAN_BRAIN_MCP_TOOLS.readNote,
-    "Read an Ocean Brain note by ID. Returns truncated content by default (1000 chars) and includes a back-reference summary. Set maxLength to 0 only when full content is necessary.",
+    "Read an Ocean Brain note by ID. Returns properties, tags, truncated content by default (1000 chars), and a back-reference summary. Set maxLength to 0 only when full content is necessary.",
     {
-      id: z2.string().describe("Note ID"),
-      maxLength: z2.number().optional().default(1e3).describe("Max content length in characters. 0 for full content. (default: 1000)")
+      id: z3.string().describe("Note ID"),
+      maxLength: z3.number().optional().default(1e3).describe("Max content length in characters. 0 for full content. (default: 1000)")
     },
     async ({ id, maxLength }) => {
       const data = await graphql(serverUrl, token, `
@@ -403,6 +913,7 @@ async function startMcpServer(serverUrl, token, options = {}) {
                         createdAt
                         updatedAt
                         tags { id name }
+                        properties { key name value valueType option { id label value color order } }
                     }
                     backReferences(id: $id) {
                         id
@@ -427,10 +938,10 @@ async function startMcpServer(serverUrl, token, options = {}) {
   );
   server.tool(
     OCEAN_BRAIN_MCP_TOOLS.createNote,
-    "Create an Ocean Brain note from markdown through the MCP write path. In MCP markdown, use explicit tags like [@project] or [#project], and use [[Note Title]] for note links. When writing linked notes, prefer creating or organizing the reference target note first. A single link is enough for Ocean Brain to surface a back reference on the other note.",
+    "Create an Ocean Brain note from markdown. Search/read first to avoid duplicates; prefer patching an existing note when the intent is a local change.",
     {
-      title: z2.string().describe("Note title"),
-      markdown: z2.string().optional().default("").describe("Markdown body for the new note. In MCP markdown, tags must use [@tag] or [#tag]. Defaults to an empty note body."),
+      title: z3.string().describe("Note title"),
+      markdown: z3.string().optional().default("").describe("Markdown body for the new note. In MCP markdown, tags must use [@tag] or [#tag]. Defaults to an empty note body."),
       layout: noteLayoutSchema.optional().describe("Optional note layout: narrow, wide, or full. Prefer wide for most notes unless the user explicitly wants narrow or full.")
     },
     async ({ title, markdown, layout }) => {
@@ -450,11 +961,11 @@ async function startMcpServer(serverUrl, token, options = {}) {
   );
   server.tool(
     OCEAN_BRAIN_MCP_TOOLS.updateNote,
-    "Update an Ocean Brain note from markdown through the MCP write path. In MCP markdown, use explicit tags like [@project] or [#project], and use [[Note Title]] for note links. When you add linked notes, prefer organizing the reference target note first. A single link is enough for Ocean Brain to surface a back reference on the other note.",
+    "Legacy full-field note update through the MCP write path. Prefer patch/append/metadata tools for small changes; use this only when intentionally replacing provided fields.",
     {
-      id: z2.string().describe("Note ID to update"),
-      title: z2.string().optional().describe("New note title"),
-      markdown: z2.string().optional().describe("Replacement markdown body. In MCP markdown, tags must use [@tag] or [#tag]."),
+      id: z3.string().describe("Note ID to update"),
+      title: z3.string().optional().describe("New note title"),
+      markdown: z3.string().optional().describe("Replacement markdown body. In MCP markdown, tags must use [@tag] or [#tag]."),
       layout: noteLayoutSchema.optional().describe("Optional note layout: narrow, wide, or full. Prefer wide for most notes unless the user explicitly wants narrow or full.")
     },
     async ({ id, title, markdown, layout }) => {
@@ -473,6 +984,14 @@ async function startMcpServer(serverUrl, token, options = {}) {
       };
     }
   );
+  registerIntentWriteTools(server, {
+    jsonRequest,
+    requireWriteToken,
+    serverUrl,
+    token,
+    tools: OCEAN_BRAIN_MCP_TOOLS,
+    writeSafety
+  });
   server.tool(
     OCEAN_BRAIN_MCP_TOOLS.listTags,
     "List Ocean Brain tags with their note counts.",
@@ -502,13 +1021,52 @@ async function startMcpServer(serverUrl, token, options = {}) {
       };
     }
   );
+  server.tool(
+    OCEAN_BRAIN_MCP_TOOLS.listProperties,
+    "List shared Ocean Brain property definitions. Use this before property queries so keys, value types, and select option values are valid.",
+    {
+      query: z3.string().optional().default("").describe("Optional property key/name search query"),
+      limit: z3.number().optional().default(50).describe("Max results (default: 50, server max: 100)"),
+      offset: z3.number().optional().default(0).describe("Pagination offset (default: 0)")
+    },
+    async ({ query, limit, offset }) => {
+      const data = await graphql(serverUrl, token, `
+                query ($query: String, $pagination: PaginationInput) {
+                    notePropertyKeys(query: $query, pagination: $pagination) {
+                        totalCount
+                        keys {
+                            key
+                            name
+                            valueType
+                            noteCount
+                            updatedAt
+                            options { id label value color order }
+                        }
+                    }
+                }
+            `, {
+        query,
+        pagination: { limit, offset }
+      });
+      const result = data?.notePropertyKeys;
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            totalCount: result.totalCount,
+            propertyKeys: result.keys
+          }, null, 2)
+        }]
+      };
+    }
+  );
   server.tool(
     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)")
+      tag: z3.string().describe("Tag name to inspect. You can pass @project or project."),
+      limit: z3.number().optional().default(20).describe("Max results (default: 20)"),
+      offset: z3.number().optional().default(0).describe("Pagination offset (default: 0)")
     },
     async ({ tag, limit, offset }) => {
       const normalizedTag = normalizeOceanBrainTagName(tag);
@@ -571,10 +1129,10 @@ async function startMcpServer(serverUrl, token, options = {}) {
     OCEAN_BRAIN_MCP_TOOLS.listNotesByTags,
     "List Ocean Brain notes for multiple tag names. Supports AND/OR matching and resolves each input tag to the canonical Ocean Brain tag name first.",
     {
-      tags: z2.array(z2.string()).min(1).describe("Tag names to inspect. You can pass @project or project values."),
+      tags: z3.array(z3.string()).min(1).describe("Tag names to inspect. You can pass @project or project values."),
       mode: tagMatchModeSchema.optional().default("and").describe("Tag match mode. Use and for intersection, or for union. Defaults to and."),
-      limit: z2.number().optional().default(20).describe("Max results (default: 20)"),
-      offset: z2.number().optional().default(0).describe("Pagination offset (default: 0)")
+      limit: z3.number().optional().default(20).describe("Max results (default: 20)"),
+      offset: z3.number().optional().default(0).describe("Pagination offset (default: 0)")
     },
     async ({ tags, mode, limit, offset }) => {
       const normalizedTags = normalizeOceanBrainTagNames(tags);
@@ -644,11 +1202,78 @@ async function startMcpServer(serverUrl, token, options = {}) {
       };
     }
   );
+  server.tool(
+    OCEAN_BRAIN_MCP_TOOLS.queryNotesByProperties,
+    "Call ocean_brain_list_properties first. Requires >=1 propertyFilter; use search/recent for broad lists. Use key/valueType from the property definition. Values are strings: select=option.value, date=YYYY-MM-DD, boolean=true/false, number=finite, url=http(s). exists/notExists need no value. Property filters use AND; tagNames use mode. Summaries are returned by default; use propertyKeys for needed property details.",
+    {
+      propertyFilters: z3.array(propertyFilterSchema).min(1).max(10).describe("Required property filters. Multiple property filters are combined with AND."),
+      tagNames: z3.array(z3.string()).optional().default([]).describe("Optional tag filters. You can pass @project, #project, or project."),
+      mode: tagMatchModeSchema.optional().default("and").describe("Tag match mode for tagNames only. Property filters are always combined with AND."),
+      sortBy: viewSortBySchema.optional().default("updatedAt").describe("Sort field (default: updatedAt)"),
+      sortOrder: viewSortOrderSchema.optional().default("desc").describe("Sort order (default: desc)"),
+      includeProperties: z3.boolean().optional().default(false).describe("Include returned note properties. Defaults to false to reduce tokens."),
+      propertyKeys: z3.array(z3.string()).optional().default([]).describe("Property keys to include in output; automatically includes properties."),
+      limit: z3.number().optional().default(20).describe("Max results (default: 20, server max: 50)"),
+      offset: z3.number().optional().default(0).describe("Pagination offset (default: 0)")
+    },
+    async ({ propertyFilters, tagNames, mode, sortBy, sortOrder, includeProperties, propertyKeys, limit, offset }) => {
+      const shouldIncludeProperties = includeProperties || propertyKeys.length > 0;
+      const data = await graphql(serverUrl, token, `
+                query ($input: NotesByPropertiesInput!, $pagination: PaginationInput, $includeProperties: Boolean!) {
+                    notesByProperties(input: $input, pagination: $pagination) {
+                        totalCount
+                        notes {
+                            id
+                            title
+                            createdAt
+                            updatedAt
+                            tags { id name }
+                            properties @include(if: $includeProperties) { key name value valueType option { id label value color order } }
+                        }
+                    }
+                }
+            `, {
+        input: {
+          tagNames,
+          mode,
+          propertyFilters,
+          sortBy,
+          sortOrder
+        },
+        pagination: { limit, offset },
+        includeProperties: shouldIncludeProperties
+      });
+      const result = data?.notesByProperties;
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify(
+            formatPropertyQueryResponse({
+              result,
+              query: {
+                propertyFilters,
+                tagNames,
+                mode,
+                sortBy,
+                sortOrder,
+                limit,
+                offset
+              },
+              includeProperties: shouldIncludeProperties,
+              propertyKeys
+            }),
+            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: z2.number().optional().default(10).describe("Max results (default: 10)")
+      limit: z3.number().optional().default(10).describe("Max results (default: 10)")
     },
     async ({ limit }) => {
       const data = await graphql(serverUrl, token, `
@@ -696,6 +1321,10 @@ async function startMcpServer(serverUrl, token, options = {}) {
             writeTools: [
               OCEAN_BRAIN_MCP_TOOLS.createNote,
               OCEAN_BRAIN_MCP_TOOLS.updateNote,
+              OCEAN_BRAIN_MCP_TOOLS.patchNoteMarkdown,
+              OCEAN_BRAIN_MCP_TOOLS.appendNoteMarkdown,
+              OCEAN_BRAIN_MCP_TOOLS.updateNoteMetadata,
+              OCEAN_BRAIN_MCP_TOOLS.replaceNoteMarkdown,
               OCEAN_BRAIN_MCP_TOOLS.createTag,
               OCEAN_BRAIN_MCP_TOOLS.deleteNote
             ],
@@ -709,9 +1338,9 @@ async function startMcpServer(serverUrl, token, options = {}) {
     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)")
+      keywords: z3.string().optional().default("temp tmp draft test wip").describe("Keywords that mark a note as a cleanup candidate. Comma or space separated."),
+      limit: z3.number().optional().default(20).describe("Max results (default: 20)"),
+      offset: z3.number().optional().default(0).describe("Pagination offset (default: 0)")
     },
     async ({ keywords, limit, offset }) => {
       const normalizedKeywords = keywords.split(/[,\s]+/).map((keyword) => keyword.trim()).filter(Boolean);
@@ -754,7 +1383,7 @@ async function startMcpServer(serverUrl, token, options = {}) {
     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.")
+      name: z3.string().describe("Tag name to create. You can pass @project or project.")
     },
     async ({ name }) => {
       const writeToken = requireWriteToken(token, OCEAN_BRAIN_MCP_TOOLS.createTag);
@@ -773,7 +1402,7 @@ async function startMcpServer(serverUrl, token, options = {}) {
     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"),
+      id: z3.string().describe("Note ID to delete"),
       ...destructiveMcpWriteFields
     },
     async ({ id, dryRun, operationId, confirmToken, force }) => {