ocean-brain 0.8.1 → 0.10.0

package/dist/mcp.js

@@ -6,7 +6,7 @@ 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 z2 } from "zod";
+import { z as z3 } from "zod";
 
 // src/mcp-note-output.ts
 var formatBackReferenceLink = (backReference) => {
@@ -58,65 +58,86 @@ var formatMcpReadNoteOutput = ({
 };
 
 // src/mcp-intent-write-tools.ts
+import { z as z2 } from "zod";
+
+// src/mcp-tool-support.ts
 import { z } from "zod";
-var markdownPatchSelectorSchema = z.discriminatedUnion("type", [
-  z.object({
-    type: z.literal("exact_text"),
-    text: z.string(),
-    before: z.string().optional(),
-    after: z.string().optional()
+var noteLayoutSchema = z.enum(["narrow", "wide", "full"]);
+var createMcpTextToolResult = (text) => ({
+  content: [
+    {
+      type: "text",
+      text
+    }
+  ]
+});
+var createMcpJsonToolResult = (value) => {
+  return createMcpTextToolResult(JSON.stringify(value, null, 2));
+};
+
+// src/mcp-intent-write-tools.ts
+var markdownPatchSelectorSchema = z2.discriminatedUnion("type", [
+  z2.object({
+    type: z2.literal("exact_text"),
+    text: z2.string(),
+    before: z2.string().optional(),
+    after: z2.string().optional()
   }),
-  z.object({
-    type: z.literal("match_candidate"),
-    text: z.string(),
-    matchIndex: z.number().int().nonnegative(),
-    lineStart: z.number().int().positive(),
-    matchSha256: z.string(),
-    surroundingHash: z.string(),
-    positionHint: z.enum(["first", "last"]).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 = z.discriminatedUnion("type", [
-  z.object({
-    type: z.literal("replace"),
-    replacement: z.string()
+var markdownPatchOperationSchema = z2.discriminatedUnion("type", [
+  z2.object({
+    type: z2.literal("replace"),
+    replacement: z2.string()
   }),
-  z.object({
-    type: z.literal("insert_before"),
-    insertion: z.string()
+  z2.object({
+    type: z2.literal("insert_before"),
+    insertion: z2.string()
   }),
-  z.object({
-    type: z.literal("insert_after"),
-    insertion: z.string()
+  z2.object({
+    type: z2.literal("insert_after"),
+    insertion: z2.string()
   })
 ]);
-var markdownAppendPlacementSchema = z.discriminatedUnion("type", [
-  z.object({
-    type: z.literal("end")
+var markdownAppendPlacementSchema = z2.discriminatedUnion("type", [
+  z2.object({
+    type: z2.literal("end")
   }),
-  z.object({
-    type: z.literal("after_heading"),
-    heading: z.string(),
-    level: z.number().int().min(1).max(6).optional()
+  z2.object({
+    type: z2.literal("after_heading"),
+    heading: z2.string(),
+    level: z2.number().int().min(1).max(6).optional()
   })
 ]);
-var markdownWritePolicySchema = z.object({
-  allowNoop: z.boolean().optional(),
-  preserveTags: z.union([z.boolean(), z.literal("warn")]).optional(),
-  preserveReferences: z.union([z.boolean(), z.literal("warn")]).optional()
+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()
 }).optional();
+var markdownWriteBaselineFields = {
+  expectedUpdatedAt: z2.string().optional().describe("Expected note updatedAt from the read you based this edit on. Required unless baseMarkdownSha256 is provided."),
+  baseMarkdownSha256: z2.string().optional().describe("SHA-256 of the current markdown. Optional alternative to expectedUpdatedAt.")
+};
 var MCP_METADATA_PROPERTY_PATCH_LIMIT = 50;
 var normalizeMetadataPropertyKey = (key) => key.trim().toLowerCase().replace(/\s+/g, "-");
-var metadataPropertyPatchSchema = z.object({
-  set: z.array(z.object({
-    key: z.string().min(1).describe("Property key from ocean_brain_list_properties."),
-    value: z.string().describe("String value: select option.value, date YYYY-MM-DD, boolean true/false, number finite string, url http(s).")
+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: z.array(z.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.")
+  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: z.ZodIssueCode.custom,
+      code: z2.ZodIssueCode.custom,
       message: "properties must include set or deleteKeys."
     });
     return;
@@ -126,7 +147,7 @@ var metadataPropertyPatchSchema = z.object({
     const key = normalizeMetadataPropertyKey(item.key);
     if (setKeys.has(key)) {
       context.addIssue({
-        code: z.ZodIssueCode.custom,
+        code: z2.ZodIssueCode.custom,
         message: `properties.set contains duplicate key ${key}.`
       });
     }
@@ -137,13 +158,13 @@ var metadataPropertyPatchSchema = z.object({
     const key = normalizeMetadataPropertyKey(rawKey);
     if (deleteKeys.has(key)) {
       context.addIssue({
-        code: z.ZodIssueCode.custom,
+        code: z2.ZodIssueCode.custom,
         message: `properties.deleteKeys contains duplicate key ${key}.`
       });
     }
     if (setKeys.has(key)) {
       context.addIssue({
-        code: z.ZodIssueCode.custom,
+        code: z2.ZodIssueCode.custom,
         message: `properties cannot set and delete ${key} in one request.`
       });
     }
@@ -161,10 +182,9 @@ var registerIntentWriteTools = (server, {
     tools.patchNoteMarkdown,
     "Patch a specific part of a note, like finding text with `rg` and editing only that match. Use for localized edits: fix one sentence, replace one paragraph, insert before/after exact text, or edit one section. Do not use for whole-note rewrites; use ocean_brain_replace_note_markdown instead.",
     {
-      id: z.string().describe("Note ID to patch"),
-      expectedUpdatedAt: z.string().optional().describe("Expected note updatedAt from the read you based this edit on. Required unless baseMarkdownSha256 is provided."),
-      baseMarkdownSha256: z.string().optional().describe("SHA-256 of the current markdown. Optional alternative to expectedUpdatedAt."),
-      intent: z.string().describe("Human-readable reason for the patch."),
+      id: z2.string().describe("Note ID to patch"),
+      ...markdownWriteBaselineFields,
+      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
@@ -181,25 +201,19 @@ var registerIntentWriteTools = (server, {
         ...policy ? { policy } : {}
       };
       const result = await jsonRequest2(serverUrl, writeToken, "/api/mcp/notes/patch-markdown", payload);
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify(result, null, 2)
-        }]
-      };
+      return createMcpJsonToolResult(result);
     }
   );
   server.tool(
     tools.appendNoteMarkdown,
     "Append markdown without changing existing content, like `cat addition.md >> note.md`. Use for adding logs, status updates, meeting notes, or new sections at the end or after a heading. Do not use to modify or replace existing body content.",
     {
-      id: z.string().describe("Note ID to append to"),
-      expectedUpdatedAt: z.string().optional().describe("Expected note updatedAt from the read you based this edit on. Required unless baseMarkdownSha256 is provided."),
-      baseMarkdownSha256: z.string().optional().describe("SHA-256 of the current markdown. Optional alternative to expectedUpdatedAt."),
-      intent: z.string().describe("Human-readable reason for the append."),
-      insertion: z.string().describe("Markdown to append. Tags are body tokens such as [@tag] or [#tag]."),
+      id: z2.string().describe("Note ID to append to"),
+      ...markdownWriteBaselineFields,
+      intent: z2.string().describe("Human-readable reason for the append."),
+      insertion: z2.string().describe("Markdown to append. Tags are body tokens such as [@tag]."),
       placement: markdownAppendPlacementSchema.optional().describe("Default is end. after_heading requires one unique matching heading."),
-      separator: z.enum(["\n\n", "\n"]).optional().describe("Separator inserted around appended markdown. Defaults to a blank line."),
+      separator: z2.enum(["\n\n", "\n"]).optional().describe("Separator inserted around appended markdown. Defaults to a blank line."),
       policy: markdownWritePolicySchema
     },
     async ({ id, expectedUpdatedAt, baseMarkdownSha256, intent, insertion, placement, separator, policy }) => {
@@ -215,22 +229,17 @@ var registerIntentWriteTools = (server, {
         ...policy ? { policy } : {}
       };
       const result = await jsonRequest2(serverUrl, writeToken, "/api/mcp/notes/append-markdown", payload);
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify(result, null, 2)
-        }]
-      };
+      return createMcpJsonToolResult(result);
     }
   );
   server.tool(
     tools.updateNoteMetadata,
     "Update note metadata only: title, layout, or properties. This does not edit the note body. 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: z.string().describe("Note ID to update"),
-      expectedUpdatedAt: z.string().describe("Expected note updatedAt from the read you based this metadata edit on. Required to prevent stale writes."),
-      title: z.string().optional().describe("New note title"),
-      layout: z.enum(["narrow", "wide", "full"]).optional().describe("New note layout"),
+      id: z2.string().describe("Note ID to update"),
+      expectedUpdatedAt: z2.string().describe("Expected note updatedAt from the read you based this metadata edit on. Required to prevent stale writes."),
+      title: z2.string().optional().describe("New note title"),
+      layout: noteLayoutSchema.optional().describe("New note layout"),
       properties: metadataPropertyPatchSchema.describe("Patch existing shared property values. Include set and/or deleteKeys; empty patches are rejected.")
     },
     async ({ id, expectedUpdatedAt, title, layout, properties }) => {
@@ -243,23 +252,17 @@ var registerIntentWriteTools = (server, {
         ...properties ? { properties } : {}
       };
       const result = await jsonRequest2(serverUrl, writeToken, "/api/mcp/notes/metadata", payload);
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify(result, null, 2)
-        }]
-      };
+      return createMcpJsonToolResult(result);
     }
   );
   server.tool(
     tools.replaceNoteMarkdown,
     "Replace the entire note body, like overwriting a markdown file with `cat new.md > note.md`. Use when the user explicitly asks to rewrite, replace, regenerate, restructure, or overwrite the whole note. Do not use for localized edits such as fixing one sentence, changing one paragraph, or inserting under a heading; use ocean_brain_patch_note_markdown instead.",
     {
-      id: z.string().describe("Note ID to replace"),
-      expectedUpdatedAt: z.string().optional().describe("Expected note updatedAt from the read you based this edit on. Required unless baseMarkdownSha256 is provided."),
-      baseMarkdownSha256: z.string().optional().describe("SHA-256 of the current markdown. Optional alternative to expectedUpdatedAt."),
-      intent: z.string().describe("Human-readable reason for the full replace."),
-      replacement: z.string().describe("Complete replacement markdown body. Tags are body tokens such as [@tag] or [#tag]."),
+      id: z2.string().describe("Note ID to replace"),
+      ...markdownWriteBaselineFields,
+      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]."),
       policy: markdownWritePolicySchema
     },
     async ({ id, expectedUpdatedAt, baseMarkdownSha256, intent, replacement, policy }) => {
@@ -273,12 +276,7 @@ var registerIntentWriteTools = (server, {
         ...policy ? { policy } : {}
       };
       const result = await jsonRequest2(serverUrl, writeToken, "/api/mcp/notes/replace-markdown", payload);
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify(result, null, 2)
-        }]
-      };
+      return createMcpJsonToolResult(result);
     }
   );
 };
@@ -331,7 +329,6 @@ 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",
   patchNoteMarkdown: "ocean_brain_patch_note_markdown",
   appendNoteMarkdown: "ocean_brain_append_note_markdown",
   updateNoteMetadata: "ocean_brain_update_note_metadata",
@@ -346,12 +343,11 @@ 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 propertyValueTypeSchema = z2.enum(["text", "url", "number", "date", "boolean", "select"]);
-var propertyFilterOperatorSchema = z2.enum(["equals", "before", "after", "exists", "notExists"]);
-var viewSortBySchema = z2.enum(["updatedAt", "createdAt", "title"]);
-var viewSortOrderSchema = z2.enum(["asc", "desc"]);
+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 formatMcpGraphqlError = (error) => {
   const suffix = [];
   if (error.extensions?.code) {
@@ -365,17 +361,20 @@ var formatMcpGraphqlError = (error) => {
   }
   return `GraphQL error: ${error.message} (${suffix.join(", ")})`;
 };
-var propertyFilterSchema = z2.object({
-  key: z2.string().describe("Property key from ocean_brain_list_properties, e.g. state"),
+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: z2.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).")
+  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");
@@ -441,17 +440,13 @@ var requireWriteToken = (token, toolName) => {
   }
   throw new Error(`${toolName} requires an MCP bearer token. Set --token or --token-file.`);
 };
-async function startMcpServer(serverUrl, token) {
-  const server = new McpServer({
-    name: "ocean-brain",
-    version: pkg.version
-  });
+var registerMcpTools = (server, serverUrl, token) => {
   server.tool(
     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, `
@@ -479,20 +474,15 @@ async function startMcpServer(serverUrl, token) {
         tags: note.tags.map((t) => t.name),
         preview: note.contentAsMarkdown.slice(0, 100)
       }));
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify({ totalCount: result.totalCount, notes }, null, 2)
-        }]
-      };
+      return createMcpJsonToolResult({ totalCount: result.totalCount, 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.",
     {
-      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, `
@@ -519,20 +509,15 @@ async function startMcpServer(serverUrl, token) {
         backReferences,
         maxLength
       });
-      return {
-        content: [{
-          type: "text",
-          text: output
-        }]
-      };
+      return createMcpTextToolResult(output);
     }
   );
   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: 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]. 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 }) => {
@@ -542,37 +527,7 @@ async function startMcpServer(serverUrl, token) {
         markdown,
         ...layout ? { layout } : {}
       });
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify(result, null, 2)
-        }]
-      };
-    }
-  );
-  server.tool(
-    OCEAN_BRAIN_MCP_TOOLS.updateNote,
-    "Legacy full-field note update kept for backward compatibility. Prefer ocean_brain_patch_note_markdown for localized body edits, ocean_brain_append_note_markdown for additions, ocean_brain_replace_note_markdown for whole-body rewrites, and ocean_brain_update_note_metadata for title/layout/properties. Use this only when a legacy client needs combined field updates.",
-    {
-      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]."),
-      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 }) => {
-      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)
-        }]
-      };
+      return createMcpJsonToolResult(result);
     }
   );
   registerIntentWriteTools(server, {
@@ -603,21 +558,16 @@ async function startMcpServer(serverUrl, token) {
         pagination: { limit: 100, offset: 0 }
       });
       const result = data?.allTags;
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify(result, null, 2)
-        }]
-      };
+      return createMcpJsonToolResult(result);
     }
   );
   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: z2.string().optional().default("").describe("Optional property key/name search query"),
-      limit: z2.number().optional().default(50).describe("Max results (default: 50, server max: 100)"),
-      offset: z2.number().optional().default(0).describe("Pagination offset (default: 0)")
+      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, `
@@ -639,42 +589,32 @@ async function startMcpServer(serverUrl, token) {
         pagination: { limit, offset }
       });
       const result = data?.notePropertyKeys;
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify({
-            totalCount: result.totalCount,
-            propertyKeys: result.keys
-          }, null, 2)
-        }]
-      };
+      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: 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);
       const tagResult = await fetchOceanBrainTags(serverUrl, token, normalizedTag);
       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)
-          }]
-        };
+        return createMcpJsonToolResult({
+          requestedTag: tag,
+          normalizedTag,
+          tagFound: false,
+          noteCount: 0,
+          notes: []
+        });
       }
       const selectedTag = exactMatches[0];
       const notesData = await graphql(serverUrl, token, `
@@ -694,35 +634,30 @@ async function startMcpServer(serverUrl, token) {
         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)
-        }]
-      };
+      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: 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);
@@ -770,44 +705,40 @@ async function startMcpServer(serverUrl, token) {
         });
         noteResult = notesData?.notesByTagNames;
       }
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify({
-            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)
-            }))
-          }, null, 2)
-        }]
-      };
+      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: z2.array(propertyFilterSchema).min(1).max(10).describe("Required property filters. Multiple property filters are combined with AND."),
-      tagNames: z2.array(z2.string()).optional().default([]).describe("Optional tag filters. You can pass @project, #project, or project."),
+      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: z2.boolean().optional().default(false).describe("Include returned note properties. Defaults to false to reduce tokens."),
-      propertyKeys: z2.array(z2.string()).optional().default([]).describe("Property keys to include in output; automatically includes properties."),
-      limit: z2.number().optional().default(20).describe("Max results (default: 20, server max: 50)"),
-      offset: z2.number().optional().default(0).describe("Pagination offset (default: 0)")
+      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 graphql(serverUrl, token, `
                 query ($input: NotesByPropertiesInput!, $pagination: PaginationInput, $includeProperties: Boolean!) {
                     notesByProperties(input: $input, pagination: $pagination) {
@@ -824,7 +755,7 @@ async function startMcpServer(serverUrl, token) {
                 }
             `, {
         input: {
-          tagNames,
+          tagNames: normalizedTagNames,
           mode,
           propertyFilters,
           sortBy,
@@ -834,36 +765,27 @@ async function startMcpServer(serverUrl, token) {
         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
-          )
-        }]
-      };
+      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: 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, `
@@ -889,21 +811,16 @@ async function startMcpServer(serverUrl, token) {
         updatedAt: note.updatedAt,
         tags: note.tags.map((t) => t.name)
       }));
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify({ totalCount: result.totalCount, notes }, null, 2)
-        }]
-      };
+      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: 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);
@@ -928,61 +845,54 @@ async function startMcpServer(serverUrl, token) {
         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)
-        }]
-      };
+      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: 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);
+      const normalizedName = normalizeOceanBrainTagName(name);
       const result = await jsonRequest(serverUrl, writeToken, "/api/mcp/tags/create", {
-        name
+        name: normalizedName
       });
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify(result, null, 2)
-        }]
-      };
+      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: z2.string().describe("Note ID to move to trash")
+      id: z3.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 });
-        return {
-          content: [{
-            type: "text",
-            text: JSON.stringify(result, null, 2)
-          }]
-        };
+        return createMcpJsonToolResult(result);
       } catch (error) {
         const message = error instanceof Error ? error.message : "Unknown MCP note delete error";
         throw new Error(message);
       }
     }
   );
+};
+async function startMcpServer(serverUrl, token) {
+  const server = new McpServer({
+    name: "ocean-brain",
+    version: pkg.version
+  });
+  registerMcpTools(server, serverUrl, token);
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }
@@ -993,5 +903,6 @@ export {
   OCEAN_BRAIN_MCP_TOOLS,
   OCEAN_BRAIN_MCP_VERSION_HEADER,
   createMcpRequestHeaders,
+  normalizeOceanBrainTagName,
   startMcpServer
 };