ocean-brain 0.13.3 → 0.14.0

package/dist/mcp.js

@@ -1,61 +1,12 @@
 #!/usr/bin/env node
 
 // src/mcp.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import fs from "fs";
 import path 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 z3 } from "zod";
-
-// src/mcp-note-output.ts
-var formatBackReferenceLink = (backReference) => {
-  return `[[${backReference.title}]](note:${backReference.id})`;
-};
-var formatBackReferenceLine = (backReference) => {
-  const referenceLink = formatBackReferenceLink(backReference);
-  if (backReference.updatedAt) {
-    return `- ${referenceLink} (updated: ${backReference.updatedAt})`;
-  }
-  return `- ${referenceLink}`;
-};
-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,
-  maxLength
-}) => {
-  let markdown = note.contentAsMarkdown;
-  const totalLength = markdown.length;
-  const truncated = maxLength > 0 && markdown.length > maxLength;
-  if (truncated) {
-    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})`] : [],
-    "",
-    "Back References:",
-    ...backReferenceLines,
-    "",
-    markdown,
-    ...truncated ? ["\n... (truncated, use maxLength: 0 to read full content)"] : []
-  ].join("\n");
-};
+import { z as z6 } from "zod";
 
 // src/mcp-intent-write-tools.ts
 import { z as z2 } from "zod";
@@ -63,6 +14,14 @@ import { z as z2 } from "zod";
 // src/mcp-tool-support.ts
 import { z } from "zod";
 var noteLayoutSchema = z.enum(["narrow", "wide", "full"]);
+var pageLimitSchema = (defaultLimit, maximum = 100) => z.number().int().positive().default(defaultLimit).transform((value) => Math.min(value, maximum));
+var pageOffsetSchema = z.number().int().nonnegative().default(0);
+var createPageInfo = (totalCount, limit, offset) => ({
+  limit,
+  offset,
+  hasMore: offset + limit < totalCount,
+  nextOffset: offset + limit < totalCount ? offset + limit : null
+});
 var createMcpTextToolResult = (text) => ({
   content: [
     {
@@ -71,9 +30,11 @@ var createMcpTextToolResult = (text) => ({
     }
   ]
 });
-var createMcpJsonToolResult = (value) => {
-  return createMcpTextToolResult(JSON.stringify(value, null, 2));
-};
+var createMcpJsonToolResult = (value) => ({
+  ...createMcpTextToolResult(JSON.stringify(value, null, 2)),
+  structuredContent: value,
+  ...value.status === "failed" || value.status === "needs_disambiguation" ? { isError: true } : {}
+});
 
 // src/mcp-intent-write-tools.ts
 var markdownPatchSelectorSchema = z2.discriminatedUnion("type", [
@@ -119,8 +80,8 @@ var markdownAppendPlacementSchema = z2.discriminatedUnion("type", [
 ]);
 var markdownWritePolicySchema = z2.object({
   allowNoop: z2.boolean().optional(),
-  preserveTags: z2.union([z2.boolean(), z2.literal("warn")]).optional(),
-  preserveReferences: z2.union([z2.boolean(), z2.literal("warn")]).optional()
+  preserveTags: z2.union([z2.boolean(), z2.literal("warn")]).optional().describe("true blocks tag-token count decreases; warn reports decreases. Does not preserve individual tag identities."),
+  preserveReferences: z2.union([z2.boolean(), z2.literal("warn")]).optional().describe("true blocks reference-count decreases; warn reports decreases. Does not preserve individual reference identities.")
 }).optional();
 var markdownWriteBaselineFields = {
   expectedUpdatedAt: z2.string().optional().describe("Expected note updatedAt from the read you based this edit on. Required unless baseMarkdownSha256 is provided."),
@@ -200,7 +161,7 @@ var registerIntentWriteTools = (server, {
         operation,
         ...policy ? { policy } : {}
       };
-      const result = await jsonRequest2(serverUrl, writeToken, "/api/mcp/notes/patch-markdown", payload);
+      const result = await jsonRequest2(serverUrl, writeToken, "/api/integrations/v1/notes/patch-markdown", payload);
       return createMcpJsonToolResult(result);
     }
   );
@@ -228,7 +189,7 @@ var registerIntentWriteTools = (server, {
         ...separator ? { separator } : {},
         ...policy ? { policy } : {}
       };
-      const result = await jsonRequest2(serverUrl, writeToken, "/api/mcp/notes/append-markdown", payload);
+      const result = await jsonRequest2(serverUrl, writeToken, "/api/integrations/v1/notes/append-markdown", payload);
       return createMcpJsonToolResult(result);
     }
   );
@@ -251,7 +212,7 @@ var registerIntentWriteTools = (server, {
         ...layout ? { layout } : {},
         ...properties ? { properties } : {}
       };
-      const result = await jsonRequest2(serverUrl, writeToken, "/api/mcp/notes/metadata", payload);
+      const result = await jsonRequest2(serverUrl, writeToken, "/api/integrations/v1/notes/metadata", payload);
       return createMcpJsonToolResult(result);
     }
   );
@@ -275,42 +236,328 @@ var registerIntentWriteTools = (server, {
         replacement,
         ...policy ? { policy } : {}
       };
-      const result = await jsonRequest2(serverUrl, writeToken, "/api/mcp/notes/replace-markdown", payload);
+      const result = await jsonRequest2(serverUrl, writeToken, "/api/integrations/v1/notes/replace-markdown", payload);
       return createMcpJsonToolResult(result);
     }
   );
 };
 
-// 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-note-output.ts
+import { z as z3 } from "zod";
+var formatBackReferenceLink = (backReference) => {
+  return `[[${backReference.title}]](note:${backReference.id})`;
+};
+var formatBackReferenceLine = (backReference) => {
+  const referenceLink = formatBackReferenceLink(backReference);
+  if (backReference.updatedAt) {
+    return `- ${referenceLink} (updated: ${backReference.updatedAt})`;
+  }
+  return `- ${referenceLink}`;
+};
+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,
+  maxLength
+}) => {
+  let markdown = note.contentAsMarkdown;
+  const totalLength = markdown.length;
+  const truncated = maxLength > 0 && markdown.length > maxLength;
+  if (truncated) {
+    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})`] : [],
+    "",
+    "Back References:",
+    ...backReferenceLines,
+    "",
+    markdown,
+    ...truncated ? ["\n... (truncated, use maxLength: 0 to read full content)"] : []
+  ].join("\n");
+};
+var readResultSchema = z3.object({
+  status: z3.enum(["read", "failed", "needs_disambiguation"]),
+  reason: z3.string().nullable(),
+  message: z3.string().nullable(),
+  note: z3.object({ id: z3.string(), title: z3.string(), createdAt: z3.string(), updatedAt: z3.string(), tags: z3.array(z3.object({ id: z3.string(), name: z3.string() })), properties: z3.array(z3.object({ key: z3.string(), name: z3.string(), value: z3.string(), valueType: z3.string(), option: z3.object({ label: z3.string(), value: z3.string() }).nullable() })) }),
+  markdown: z3.string(),
+  contentRange: z3.object({ start: z3.number(), end: z3.number(), totalLength: z3.number(), sectionEnd: z3.number(), hasMore: z3.boolean(), nextOffset: z3.number().nullable() }).nullable(),
+  candidates: z3.array(z3.object({ heading: z3.string(), level: z3.number(), start: z3.number(), end: z3.number() }))
+});
+var createMcpReadNoteResult = (raw, rawBackReferences) => {
+  const result = readResultSchema.parse(raw);
+  const backReferences = z3.array(z3.object({ id: z3.string(), title: z3.string() })).parse(rawBackReferences);
+  const structuredContent = { ...result, backReferences };
+  if (result.status !== "read") return createMcpJsonToolResult(structuredContent);
+  const range = result.contentRange;
+  const rangeText = range ? `
+Content range: [${range.start}, ${range.end}) of ${range.totalLength} UTF-16 units; sectionEnd: ${range.sectionEnd}; nextOffset: ${range.nextOffset ?? "none"}` : "";
+  return {
+    ...createMcpTextToolResult(formatMcpReadNoteOutput({ note: { ...result.note, contentAsMarkdown: result.markdown }, backReferences, maxLength: 0 }) + rangeText),
+    structuredContent
+  };
+};
+
+// src/mcp-query-tools.ts
+import { z as z4 } from "zod";
+var propertyFilterSchema = z4.object({
+  key: z4.string().min(1),
+  valueType: z4.enum(["text", "url", "number", "date", "boolean", "select"]),
+  operator: z4.enum(["equals", "notEquals", "contains", "notContains", "before", "after", "exists", "notExists"]),
+  value: z4.string().nullable().optional().describe(
+    "Required except exists/notExists. select=option.value, date=YYYY-MM-DD, boolean=true/false. contains/notContains: text/url; before/after: date/number."
+  )
+});
+var queryConditionsSchema = z4.object({
+  tagNames: z4.array(z4.string()),
+  mode: z4.enum(["and", "or"]),
+  propertyFilters: z4.array(propertyFilterSchema.extend({ name: z4.string().optional() })),
+  sortBy: z4.enum(["updatedAt", "createdAt", "title"]),
+  sortOrder: z4.enum(["asc", "desc"])
+});
+var optionSchema = z4.object({
+  id: z4.string(),
+  label: z4.string(),
+  value: z4.string(),
+  color: z4.string().nullable(),
+  order: z4.number()
+});
+var noteSummarySchema = z4.object({
+  id: z4.string(),
+  title: z4.string(),
+  createdAt: z4.string(),
+  updatedAt: z4.string(),
+  tags: z4.array(z4.object({ id: z4.string(), name: z4.string() })),
+  properties: z4.array(
+    z4.object({
+      key: z4.string(),
+      name: z4.string(),
+      value: z4.string(),
+      valueType: z4.string(),
+      option: optionSchema.nullable()
+    })
+  ).optional()
+});
+var pageInfoSchema = z4.object({
+  limit: z4.number(),
+  offset: z4.number(),
+  hasMore: z4.boolean(),
+  nextOffset: z4.number().nullable()
+});
+var propertyKeysSchema = z4.array(z4.string().trim().min(1)).max(50).transform((keys) => [...new Set(keys.map((key) => key.toLowerCase().replace(/\s+/g, "-")))]);
+var NOTE_SUMMARY_FIELDS = "id title createdAt updatedAt tags { id name } properties(keys: $propertyKeys) { key name value valueType option { id label value color order } }";
+var QUERY_CONDITION_FIELDS = "tagNames mode propertyFilters { key name valueType operator value } sortBy sortOrder";
+var registerQueryTools = (server, request) => {
+  server.registerTool(
+    "ocean_brain_query_notes",
+    {
+      description: "Query notes using tags and property conditions; no filters returns recent notes. mode combines tags only; property filters always use AND. Use list_properties for valid keys/types/options. Only requested propertyKeys are returned. No note bodies.",
+      inputSchema: {
+        tagNames: z4.array(z4.string().trim().min(1)).max(100).default([]),
+        mode: z4.enum(["and", "or"]).default("and"),
+        propertyFilters: z4.array(propertyFilterSchema).max(10).default([]),
+        sortBy: z4.enum(["updatedAt", "createdAt", "title"]).default("updatedAt"),
+        sortOrder: z4.enum(["asc", "desc"]).default("desc"),
+        propertyKeys: propertyKeysSchema.default([]),
+        limit: pageLimitSchema(20, 50),
+        offset: pageOffsetSchema
+      },
+      outputSchema: {
+        query: queryConditionsSchema,
+        totalCount: z4.number(),
+        notes: z4.array(noteSummarySchema),
+        missingTags: z4.array(z4.string()),
+        page: pageInfoSchema
+      },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ limit, offset, propertyKeys, ...input }) => {
+      const data = await request(
+        `query ($input: NotesByPropertiesInput!, $names: [String!]!, $pagination: PaginationInput!, $propertyKeys: [String!]) {
+            notesByQuery(input: $input, pagination: $pagination) { query { ${QUERY_CONDITION_FIELDS} } totalCount notes { ${NOTE_SUMMARY_FIELDS} } }
+            tagsByNames(names: $names) { name }
+        }`,
+        {
+          input,
+          names: input.tagNames,
+          propertyKeys,
+          pagination: { limit, offset }
+        }
+      );
+      const result = z4.object({
+        query: queryConditionsSchema,
+        totalCount: z4.number(),
+        notes: z4.array(noteSummarySchema)
+      }).parse(data?.notesByQuery);
+      const tags = z4.array(z4.object({ name: z4.string() })).parse(data?.tagsByNames);
+      return createMcpJsonToolResult({
+        ...result,
+        missingTags: result.query.tagNames.filter((name) => !tags.some((tag) => tag.name === name)),
+        page: createPageInfo(result.totalCount, limit, offset)
+      });
+    }
+  );
+};
+
+// src/mcp-view-tools.ts
+import { z as z5 } from "zod";
+var sectionSchema = queryConditionsSchema.extend({
+  id: z5.string(),
+  tabId: z5.string(),
+  title: z5.string(),
+  displayType: z5.enum(["list", "table", "board", "calendar"]),
+  limit: z5.number(),
+  order: z5.number(),
+  displayOptions: z5.object({
+    tableColumns: z5.array(z5.string()),
+    tablePropertyKeys: z5.array(z5.string()),
+    boardGroupByPropertyKey: z5.string().nullable(),
+    calendarDateField: z5.enum(["createdAt", "updatedAt", "property"]),
+    calendarDatePropertyKey: z5.string().nullable()
+  })
 });
+var SECTION_FIELDS = `id tabId title displayType limit order ${QUERY_CONDITION_FIELDS} displayOptions { tableColumns tablePropertyKeys boardGroupByPropertyKey calendarDateField calendarDatePropertyKey }`;
+var viewReadSchema = z5.object({
+  section: sectionSchema,
+  totalCount: z5.number(),
+  rows: z5.array(
+    z5.object({
+      note: noteSummarySchema,
+      groupValue: z5.string().nullable(),
+      calendarDate: z5.string().nullable()
+    })
+  ),
+  groupProperty: z5.object({
+    key: z5.string(),
+    name: z5.string(),
+    options: z5.array(optionSchema)
+  }).nullable()
+});
+var registerViewTools = (server, request) => {
+  server.registerTool(
+    "ocean_brain_list_views",
+    {
+      description: "Find saved view sections by section or tab title. Returns IDs, saved conditions and display settings without loading notes or switching the active tab.",
+      inputSchema: {
+        query: z5.string().default(""),
+        limit: pageLimitSchema(20, 50),
+        offset: pageOffsetSchema
+      },
+      outputSchema: {
+        totalCount: z5.number(),
+        views: z5.array(
+          z5.object({
+            sectionId: z5.string(),
+            tabTitle: z5.string(),
+            section: sectionSchema
+          })
+        ),
+        page: pageInfoSchema
+      },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ query, limit, offset }) => {
+      const data = await request(
+        `query ($query: String, $pagination: PaginationInput) { viewSections(query: $query, pagination: $pagination) { totalCount sections { tabTitle section { ${SECTION_FIELDS} } } } }`,
+        { query, pagination: { limit, offset } }
+      );
+      const result = z5.object({
+        totalCount: z5.number(),
+        sections: z5.array(z5.object({ tabTitle: z5.string(), section: sectionSchema }))
+      }).parse(data?.viewSections);
+      return createMcpJsonToolResult({
+        totalCount: result.totalCount,
+        views: result.sections.map((view) => ({
+          ...view,
+          sectionId: view.section.id
+        })),
+        page: createPageInfo(result.totalCount, limit, offset)
+      });
+    }
+  );
+  server.registerTool(
+    "ocean_brain_read_view",
+    {
+      description: "Read a saved view with its conditions, display settings and paged note rows. Board: omit groupValue for all columns; null means unclassified. Calendar: dateRange is required ([start,end), at most 32 days); saved date field controls order. propertyKeys overrides table columns; omit to use saved table property columns. section.limit is the UI display limit, separate from page.limit.",
+      inputSchema: {
+        sectionId: z5.string().min(1),
+        limit: pageLimitSchema(20, 50),
+        offset: pageOffsetSchema,
+        propertyKeys: propertyKeysSchema.optional(),
+        groupValue: z5.string().nullable().optional(),
+        dateRange: z5.object({ start: z5.string(), end: z5.string() }).optional()
+      },
+      outputSchema: {
+        ...viewReadSchema.shape,
+        selection: z5.object({
+          propertyKeys: z5.array(z5.string()),
+          groupValue: z5.string().nullable().optional(),
+          dateRange: z5.object({ start: z5.string(), end: z5.string() }).optional()
+        }),
+        page: pageInfoSchema
+      },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ sectionId, limit, offset, propertyKeys, groupValue, dateRange }) => {
+      const data = await request(
+        `query ($id: ID!, $pagination: PaginationInput, $propertyKeys: [String!], $groupValue: String, $dateRange: DateRangeInput) {
+            readViewSection(id: $id, pagination: $pagination, propertyKeys: $propertyKeys, groupValue: $groupValue, dateRange: $dateRange) {
+                section { ${SECTION_FIELDS} } totalCount groupProperty { key name options { id label value color order } }
+                rows { groupValue calendarDate note { ${NOTE_SUMMARY_FIELDS} } }
+            }
+        }`,
+        {
+          id: sectionId,
+          pagination: { limit, offset },
+          propertyKeys,
+          groupValue,
+          dateRange
+        }
+      );
+      const result = viewReadSchema.parse(data?.readViewSection);
+      const keys = propertyKeys ?? (result.section.displayType === "table" ? result.section.displayOptions.tablePropertyKeys : []);
+      const selection = {
+        propertyKeys: keys,
+        ...groupValue !== void 0 ? {
+          groupValue: groupValue === null ? null : groupValue.trim().toLowerCase().replace(/\s+/g, "-")
+        } : {},
+        ...dateRange ? { dateRange } : {}
+      };
+      return createMcpJsonToolResult({
+        ...result,
+        selection,
+        rows: result.rows.map((row) => ({
+          ...row,
+          note: {
+            ...row.note,
+            properties: row.note.properties?.filter((property) => keys.includes(property.key))
+          }
+        })),
+        page: createPageInfo(result.totalCount, limit, offset)
+      });
+    }
+  );
+};
 
 // src/mcp.ts
 var __dirname = path.dirname(fileURLToPath(import.meta.url));
-var pkg = JSON.parse(
-  fs.readFileSync(path.resolve(__dirname, "..", "package.json"), "utf-8")
-);
+var pkg = JSON.parse(fs.readFileSync(path.resolve(__dirname, "..", "package.json"), "utf-8"));
 if (!pkg.oceanBrain?.mcpCompatibilityVersion) {
   throw new Error("Ocean Brain MCP compatibility version is required in package metadata.");
 }
@@ -326,6 +573,9 @@ var createMcpRequestHeaders = (token) => ({
   ...token ? { Authorization: `Bearer ${token}` } : {}
 });
 var OCEAN_BRAIN_MCP_TOOLS = {
+  queryNotes: "ocean_brain_query_notes",
+  listViews: "ocean_brain_list_views",
+  readView: "ocean_brain_read_view",
   searchNotes: "ocean_brain_search_notes",
   readNote: "ocean_brain_read_note",
   createNote: "ocean_brain_create_note",
@@ -335,20 +585,9 @@ var OCEAN_BRAIN_MCP_TOOLS = {
   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",
-  findNoteCleanupCandidates: "ocean_brain_find_note_cleanup_candidates",
-  createTag: "ocean_brain_create_tag",
   deleteNote: "ocean_brain_delete_note"
 };
-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 searchModeSchema = z3.enum(["hybrid", "lexical", "semantic"]);
+var searchModeSchema = z6.enum(["hybrid", "lexical", "semantic"]);
 var graphqlSearchModes = {
   hybrid: "HYBRID",
   lexical: "LEXICAL",
@@ -367,51 +606,8 @@ var formatMcpGraphqlError = (error) => {
   }
   return `GraphQL error: ${error.message} (${suffix.join(", ")})`;
 };
-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) {
-    throw new Error("Tag name is required.");
-  }
-  if (trimmedName.startsWith("#")) {
-    throw new Error("Ocean Brain tags use @, not #. Example: @project");
-  }
-  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;
-};
-var normalizeOceanBrainTagNames = (names) => {
-  return Array.from(
-    new Set(names.map(normalizeOceanBrainTagName))
-  );
-};
-var fetchOceanBrainTags = async (serverUrl, token, query, graphqlRequest = graphql) => {
-  const data = await graphqlRequest(serverUrl, token, `
-        query ($searchFilter: SearchFilterInput, $pagination: PaginationInput) {
-            allTags(searchFilter: $searchFilter, pagination: $pagination) {
-                totalCount
-                tags {
-                    id
-                    name
-                    referenceCount
-                }
-            }
-        }
-    `, {
-    searchFilter: { query },
-    pagination: { limit: 100, offset: 0 }
-  });
-  return data?.allTags;
-};
 async function graphql(serverUrl, token, query, variables) {
-  const response = await fetch(`${serverUrl}/graphql/mcp`, {
+  const response = await fetch(`${serverUrl}/api/integrations/v1/graphql`, {
     method: "POST",
     headers: createMcpRequestHeaders(token),
     body: JSON.stringify({ query, variables })
@@ -455,17 +651,25 @@ var formatMcpSearchNotes = (notes) => notes.map((note) => ({
 }));
 var registerMcpTools = (server, serverUrl, token, options = {}) => {
   const graphqlRequest = options.graphqlRequest ?? graphql;
+  const queryRequest = (query, variables) => graphqlRequest(serverUrl, token, query, variables);
+  registerQueryTools(server, queryRequest);
+  registerViewTools(server, queryRequest);
   server.tool(
     OCEAN_BRAIN_MCP_TOOLS.searchNotes,
     "Search Ocean Brain notes by keyword or meaning. Lexical uses words only, hybrid combines words and meaning, and semantic uses meaning only. Results use one ranked result shape with match and semantic-search status. Use ocean_brain_read_note to get full content for a specific note.",
     {
-      query: z3.string().describe("Search words or a natural-language description"),
-      limit: z3.number().optional().default(10).describe("Results per page. Search returns at most 50 per page. (default: 10)"),
-      offset: z3.number().int().min(0).optional().default(0).describe("Results to skip for pagination (default: 0)"),
+      query: z6.string().describe("Search words or a natural-language description"),
+      limit: pageLimitSchema(10, 50).describe(
+        "Results per page. Search returns at most 50 per page. (default: 10)"
+      ),
+      offset: z6.number().int().min(0).optional().default(0).describe("Results to skip for pagination (default: 0)"),
       mode: searchModeSchema.default("hybrid").describe("Search mode. Defaults to hybrid.")
     },
     async ({ query, limit, offset, mode }) => {
-      const data = await graphqlRequest(serverUrl, token, `
+      const data = await graphqlRequest(
+        serverUrl,
+        token,
+        `
                 query ($query: String!, $mode: SearchMode!, $pagination: PaginationInput!) {
                     searchNotes(query: $query, mode: $mode, pagination: $pagination) {
                         totalCount
@@ -476,6 +680,7 @@ var registerMcpTools = (server, serverUrl, token, options = {}) => {
                             noteId
                             lexical
                             semantic
+                            excerpt { text source start end }
                         }
                         notes {
                             id
@@ -486,11 +691,13 @@ var registerMcpTools = (server, serverUrl, token, options = {}) => {
                         }
                     }
                 }
-            `, {
-        query,
-        mode: graphqlSearchModes[mode],
-        pagination: { limit, offset }
-      });
+            `,
+        {
+          query,
+          mode: graphqlSearchModes[mode],
+          pagination: { limit, offset }
+        }
+      );
       const result = data?.searchNotes;
       return createMcpJsonToolResult({
         totalCount: result.totalCount,
@@ -498,59 +705,68 @@ var registerMcpTools = (server, serverUrl, token, options = {}) => {
         semanticUsed: result.semanticUsed,
         semanticError: result.semanticError,
         matches: result.matches,
+        page: createPageInfo(result.totalCount, limit, offset),
         notes: formatMcpSearchNotes(result.notes)
       });
     }
   );
   server.tool(
     OCEAN_BRAIN_MCP_TOOLS.readNote,
-    "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.",
+    "Read note metadata, markdown and back references. Default 1000 UTF-16 units; maxLength: 0 reads the remaining body or whole selected section. Use offset or exact heading, never both. For continuation pass contentRange.nextOffset and expectedUpdatedAt from this read; sectionEnd bounds a selected section. Ambiguous headings return positions. Prefer structuredContent for code consumers.",
     {
-      id: z3.string().describe("Note ID"),
-      maxLength: z3.number().optional().default(1e3).describe("Max content length in characters. 0 for full content. (default: 1000)")
+      id: z6.string().min(1),
+      maxLength: z6.number().int().nonnegative().default(1e3),
+      offset: z6.number().int().nonnegative().optional(),
+      heading: z6.string().min(1).optional(),
+      expectedUpdatedAt: z6.string().optional()
     },
-    async ({ id, maxLength }) => {
-      const data = await graphqlRequest(serverUrl, token, `
-                query ($id: ID!) {
-                    note(id: $id) {
-                        id
-                        title
-                        contentAsMarkdown
-                        createdAt
-                        updatedAt
-                        tags { id name }
-                        properties { key name value valueType option { id label value color order } }
-                    }
-                    backReferences(id: $id) {
-                        id
-                        title
+    async (input) => {
+      if (input.heading !== void 0 && input.offset !== void 0)
+        throw new Error("Use either heading or offset, not both.");
+      const data = await graphqlRequest(
+        serverUrl,
+        token,
+        `
+                query ($id: ID!, $maxLength: Int, $offset: Int, $heading: String, $expectedUpdatedAt: String) {
+                    noteRead(id: $id, maxLength: $maxLength, offset: $offset, heading: $heading, expectedUpdatedAt: $expectedUpdatedAt) {
+                        status reason message markdown
+                        candidates { heading level start end }
+                        contentRange { start end totalLength sectionEnd hasMore nextOffset }
+                        note { id title createdAt updatedAt tags { id name } properties { key name value valueType option { label value } } }
                     }
+                    backReferences(id: $id) { id title }
                 }
-            `, { id });
-      const note = data?.note;
-      const backReferences = data?.backReferences ?? [];
-      const output = formatMcpReadNoteOutput({
-        note,
-        backReferences,
-        maxLength
-      });
-      return createMcpTextToolResult(output);
+            `,
+        input
+      );
+      return createMcpReadNoteResult(data?.noteRead, data?.backReferences);
     }
   );
   server.tool(
     OCEAN_BRAIN_MCP_TOOLS.createNote,
     "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: z3.string().describe("Note title"),
-      markdown: z3.string().optional().default("").describe("Markdown body for the new note. In MCP markdown, tags must use [@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.")
+      title: z6.string().describe("Note title"),
+      markdown: z6.string().optional().default("").describe(
+        "Markdown body for the new note. In MCP markdown, tags must use [@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."
+      ),
+      properties: z6.object({
+        set: z6.array(z6.object({ key: z6.string().min(1), value: z6.string() })).max(50)
+      }).strict().optional().describe(
+        "Set existing properties atomically with creation. Same keys/values as update_note_metadata; definitions and select options must already exist."
+      )
     },
-    async ({ title, markdown, layout }) => {
+    async ({ title, markdown, layout, properties }) => {
+      if (properties) metadataPropertyPatchSchema.parse(properties);
       const writeToken = requireWriteToken(token, OCEAN_BRAIN_MCP_TOOLS.createNote);
-      const result = await jsonRequest(serverUrl, writeToken, "/api/mcp/notes/create", {
+      const result = await jsonRequest(serverUrl, writeToken, "/api/integrations/v1/notes/create", {
         title,
         markdown,
-        ...layout ? { layout } : {}
+        ...layout ? { layout } : {},
+        ...properties ? { properties } : {}
       });
       return createMcpJsonToolResult(result);
     }
@@ -564,10 +780,17 @@ var registerMcpTools = (server, serverUrl, token, options = {}) => {
   });
   server.tool(
     OCEAN_BRAIN_MCP_TOOLS.listTags,
-    "List Ocean Brain tags with their note counts.",
-    {},
-    async () => {
-      const data = await graphqlRequest(serverUrl, token, `
+    "Search and page through Ocean Brain tags that are used by notes, with note counts.",
+    {
+      query: z6.string().default("").describe("Tag name search"),
+      limit: pageLimitSchema(100),
+      offset: pageOffsetSchema
+    },
+    async ({ query, limit, offset }) => {
+      const data = await graphqlRequest(
+        serverUrl,
+        token,
+        `
                 query ($searchFilter: SearchFilterInput, $pagination: PaginationInput) {
                     allTags(searchFilter: $searchFilter, pagination: $pagination) {
                         totalCount
@@ -578,24 +801,32 @@ var registerMcpTools = (server, serverUrl, token, options = {}) => {
                         }
                     }
                 }
-            `, {
-        searchFilter: { query: "" },
-        pagination: { limit: 100, offset: 0 }
-      });
+            `,
+        {
+          searchFilter: { query },
+          pagination: { limit, offset }
+        }
+      );
       const result = data?.allTags;
-      return createMcpJsonToolResult(result);
+      return createMcpJsonToolResult({
+        ...result,
+        page: createPageInfo(result.totalCount, limit, offset)
+      });
     }
   );
   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)")
+      query: z6.string().optional().default("").describe("Optional property key/name search query"),
+      limit: pageLimitSchema(50, 100).describe("Max results (default: 50, server max: 100)"),
+      offset: pageOffsetSchema.describe("Pagination offset (default: 0)")
     },
     async ({ query, limit, offset }) => {
-      const data = await graphqlRequest(serverUrl, token, `
+      const data = await graphqlRequest(
+        serverUrl,
+        token,
+        `
                 query ($query: String, $pagination: PaginationInput) {
                     notePropertyKeys(query: $query, pagination: $pagination) {
                         totalCount
@@ -609,301 +840,30 @@ var registerMcpTools = (server, serverUrl, token, options = {}) => {
                         }
                     }
                 }
-            `, {
-        query,
-        pagination: { limit, offset }
-      });
+            `,
+        {
+          query,
+          pagination: { limit, offset }
+        }
+      );
       const result = data?.notePropertyKeys;
       return createMcpJsonToolResult({
         totalCount: result.totalCount,
-        propertyKeys: result.keys
-      });
-    }
-  );
-  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: 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);
-      const tagResult = await fetchOceanBrainTags(serverUrl, token, normalizedTag, graphqlRequest);
-      const exactMatches = tagResult.tags.filter((item) => item.name === normalizedTag);
-      if (exactMatches.length === 0) {
-        return createMcpJsonToolResult({
-          requestedTag: tag,
-          normalizedTag,
-          tagFound: false,
-          noteCount: 0,
-          notes: []
-        });
-      }
-      const selectedTag = exactMatches[0];
-      const notesData = await graphqlRequest(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 createMcpJsonToolResult({
-        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)
-        }))
-      });
-    }
-  );
-  server.tool(
-    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: 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: 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);
-      const tagResults = await Promise.all(
-        normalizedTags.map(async (normalizedTag) => {
-          const result = await fetchOceanBrainTags(serverUrl, token, normalizedTag, graphqlRequest);
-          const exactMatches = result.tags.filter((item) => item.name === normalizedTag);
-          return {
-            normalizedTag,
-            exactMatches
-          };
-        })
-      );
-      const matchedTags = tagResults.filter((tagResult) => tagResult.exactMatches.length > 0).map((tagResult) => {
-        const selectedTag = tagResult.exactMatches[0];
-        return {
-          id: selectedTag.id,
-          name: selectedTag.name,
-          referenceCount: selectedTag.referenceCount,
-          duplicateExactMatchCount: tagResult.exactMatches.length
-        };
-      });
-      const missingTags = tagResults.filter((tagResult) => tagResult.exactMatches.length === 0).map((tagResult) => tagResult.normalizedTag);
-      let noteResult = {
-        totalCount: 0,
-        notes: []
-      };
-      if (mode === "and" && missingTags.length === 0 || mode === "or" && matchedTags.length > 0) {
-        const notesData = await graphqlRequest(serverUrl, token, `
-                    query ($tagNames: [String!]!, $mode: TagMatchMode!, $pagination: PaginationInput) {
-                        notesByTagNames(tagNames: $tagNames, mode: $mode, pagination: $pagination) {
-                            totalCount
-                            notes {
-                                id
-                                title
-                                updatedAt
-                                tags { id name }
-                            }
-                        }
-                    }
-                `, {
-          tagNames: normalizedTags,
-          mode,
-          pagination: { limit, offset }
-        });
-        noteResult = notesData?.notesByTagNames;
-      }
-      return createMcpJsonToolResult({
-        requestedTags: tags,
-        normalizedTags,
-        mode,
-        allTagsFound: missingTags.length === 0,
-        missingTags,
-        tags: matchedTags,
-        totalCount: noteResult.totalCount,
-        notes: noteResult.notes.map((note) => ({
-          id: note.id,
-          title: note.title,
-          updatedAt: note.updatedAt,
-          tags: note.tags.map((item) => item.name)
-        }))
-      });
-    }
-  );
-  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 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 normalizedTagNames = normalizeOceanBrainTagNames(tagNames);
-      const data = await graphqlRequest(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: normalizedTagNames,
-          mode,
-          propertyFilters,
-          sortBy,
-          sortOrder
-        },
-        pagination: { limit, offset },
-        includeProperties: shouldIncludeProperties
-      });
-      const result = data?.notesByProperties;
-      return createMcpJsonToolResult(formatPropertyQueryResponse({
-        result,
-        query: {
-          propertyFilters,
-          tagNames: normalizedTagNames,
-          mode,
-          sortBy,
-          sortOrder,
-          limit,
-          offset
-        },
-        includeProperties: shouldIncludeProperties,
-        propertyKeys
-      }));
-    }
-  );
-  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: z3.number().optional().default(10).describe("Max results (default: 10)")
-    },
-    async ({ limit }) => {
-      const data = await graphqlRequest(serverUrl, token, `
-                query ($searchFilter: SearchFilterInput, $pagination: PaginationInput) {
-                    allNotes(searchFilter: $searchFilter, pagination: $pagination) {
-                        totalCount
-                        notes {
-                            id
-                            title
-                            updatedAt
-                            tags { id name }
-                        }
-                    }
-                }
-            `, {
-        searchFilter: { query: "", sortBy: "updatedAt", sortOrder: "desc" },
-        pagination: { limit, offset: 0 }
+        propertyKeys: result.keys,
+        page: createPageInfo(result.totalCount, limit, offset)
       });
-      const result = data?.allNotes;
-      const notes = result.notes.map((note) => ({
-        id: note.id,
-        title: note.title,
-        updatedAt: note.updatedAt,
-        tags: note.tags.map((t) => t.name)
-      }));
-      return createMcpJsonToolResult({ totalCount: result.totalCount, notes });
-    }
-  );
-  server.tool(
-    OCEAN_BRAIN_MCP_TOOLS.findNoteCleanupCandidates,
-    "Find Ocean Brain note cleanup candidates for temporary or draft notes before deletion. This is optional discovery; ocean_brain_delete_note moves a single note to trash directly.",
-    {
-      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);
-      const data = await graphqlRequest(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 createMcpJsonToolResult({
-        keywords: normalizedKeywords,
-        limit,
-        offset,
-        candidateCount: result.length,
-        notes: result
-      });
-    }
-  );
-  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: z3.string().describe("Tag name to create. You can pass @project or project.")
-    },
-    async ({ name }) => {
-      const writeToken = requireWriteToken(token, OCEAN_BRAIN_MCP_TOOLS.createTag);
-      const normalizedName = normalizeOceanBrainTagName(name);
-      const result = await jsonRequest(serverUrl, writeToken, "/api/mcp/tags/create", {
-        name: normalizedName
-      });
-      return createMcpJsonToolResult(result);
     }
   );
   server.tool(
     OCEAN_BRAIN_MCP_TOOLS.deleteNote,
     "Move an Ocean Brain note to trash, like `mv note.md trash/`. This is a recoverable trash move, not permanent deletion. Deleted-note tag names are kept as restore metadata; orphan tags are not a blocking condition.",
     {
-      id: z3.string().describe("Note ID to move to trash")
+      id: z6.string().describe("Note ID to move to trash")
     },
     async ({ id }) => {
       const writeToken = requireWriteToken(token, OCEAN_BRAIN_MCP_TOOLS.deleteNote);
       try {
-        const result = await jsonRequest(serverUrl, writeToken, "/api/mcp/notes/delete", { id });
+        const result = await jsonRequest(serverUrl, writeToken, "/api/integrations/v1/notes/delete", { id });
         return createMcpJsonToolResult(result);
       } catch (error) {
         const message = error instanceof Error ? error.message : "Unknown MCP note delete error";
@@ -928,7 +888,6 @@ export {
   OCEAN_BRAIN_MCP_TOOLS,
   OCEAN_BRAIN_MCP_VERSION_HEADER,
   createMcpRequestHeaders,
-  normalizeOceanBrainTagName,
   registerMcpTools,
   startMcpServer
 };