@firfi/huly-mcp 0.20.0 → 0.21.0

package/README.md

@@ -351,8 +351,8 @@ Resource roadmap:
 | `delete_teamspace` | Permanently delete a Huly document teamspace. This action cannot be undone. |
 | `list_documents` | List documents in a Huly teamspace. Returns documents sorted by modification date (newest first). Each result includes a 'url' field pointing to the document in the Huly web app. Supports searching by title substring (titleSearch) and content (contentSearch). |
 | `get_document` | Retrieve full details for a Huly document including markdown content and a 'url' field pointing to the document in the Huly web app. Use this to view document content and metadata. |
-| `create_document` | Create a new document in a Huly teamspace. Content supports full markdown including native Mermaid diagrams (```mermaid blocks render interactively in Huly UI). Optionally pass parent as a document title or ID to create a nested child document; invalid parents fail instead of silently creating a top-level document. Returns the created document id and a 'url' field pointing to the document in the Huly web app. Use link_document_to_issue to associate the document with a tracker issue. |
-| `edit_document` | Edit an existing Huly document. Two content modes (mutually exclusive): (1) 'content' for full replace, (2) 'old_text' + 'new_text' for targeted search-and-replace. Multiple matches error unless replace_all is true. Empty new_text deletes matched text. Also supports renaming via 'title'. Content supports full markdown including native Mermaid diagrams. Returns a 'url' field pointing to the document in the Huly web app. |
+| `create_document` | Create a new document in a Huly teamspace. Content is markdown and supports native Mermaid diagrams (```mermaid blocks render interactively in Huly UI). Use markdown links to current-workspace Huly browse URLs for native references; Huly browse links returned in get_document content round-trip as native references. The URL identifies the object; link text is display text; plain issue keys stay text. External URLs stay normal markdown links. Optionally pass parent as a document title or ID to create a nested child document; invalid parents fail instead of silently creating a top-level document. Returns the created document id and a 'url' field pointing to the document in the Huly web app. Use link_document_to_issue only if you also want an issue-document association. |
+| `edit_document` | Edit an existing Huly document. You may rename with title and/or edit the body. Body editing has two mutually exclusive modes: (1) content replaces the entire markdown body, (2) old_text + new_text performs exact targeted search-and-replace. Use markdown links to current-workspace Huly browse URLs for native references; Huly browse links returned in get_document content round-trip as native references. The URL identifies the object; link text is display text; plain issue keys stay text. External URLs stay normal markdown links. For targeted replace, multiple matches error unless replace_all is true; empty new_text deletes matched text. Content supports native Mermaid diagrams. Returns a 'url' field pointing to the document in the Huly web app. |
 | `list_inline_comments` | List inline comment threads from a Huly document. Extracts comments embedded in document content as ProseMirror marks. Each comment includes the highlighted text and thread ID. Set includeReplies=true to also fetch thread reply messages with sender names. |
 | `delete_document` | Permanently delete a Huly document. This action cannot be undone. |
 

package/dist/index.cjs

@@ -62706,41 +62706,41 @@ var require_model = __commonJS({
     var model_exports = {};
     __export2(model_exports, {
       MarkupMarkType: () => MarkupMarkType,
-      MarkupNodeType: () => MarkupNodeType,
+      MarkupNodeType: () => MarkupNodeType2,
       emptyMarkupNode: () => emptyMarkupNode
     });
     module2.exports = __toCommonJS2(model_exports);
-    var MarkupNodeType = /* @__PURE__ */ ((MarkupNodeType2) => {
-      MarkupNodeType2["doc"] = "doc";
-      MarkupNodeType2["paragraph"] = "paragraph";
-      MarkupNodeType2["blockquote"] = "blockquote";
-      MarkupNodeType2["horizontal_rule"] = "horizontalRule";
-      MarkupNodeType2["heading"] = "heading";
-      MarkupNodeType2["code_block"] = "codeBlock";
-      MarkupNodeType2["text"] = "text";
-      MarkupNodeType2["image"] = "image";
-      MarkupNodeType2["file"] = "file";
-      MarkupNodeType2["reference"] = "reference";
-      MarkupNodeType2["emoji"] = "emoji";
-      MarkupNodeType2["hard_break"] = "hardBreak";
-      MarkupNodeType2["ordered_list"] = "orderedList";
-      MarkupNodeType2["bullet_list"] = "bulletList";
-      MarkupNodeType2["list_item"] = "listItem";
-      MarkupNodeType2["taskList"] = "taskList";
-      MarkupNodeType2["taskItem"] = "taskItem";
-      MarkupNodeType2["todoList"] = "todoList";
-      MarkupNodeType2["todoItem"] = "todoItem";
-      MarkupNodeType2["subLink"] = "subLink";
-      MarkupNodeType2["table"] = "table";
-      MarkupNodeType2["table_row"] = "tableRow";
-      MarkupNodeType2["table_cell"] = "tableCell";
-      MarkupNodeType2["table_header"] = "tableHeader";
-      MarkupNodeType2["mermaid"] = "mermaid";
-      MarkupNodeType2["comment"] = "comment";
-      MarkupNodeType2["markdown"] = "markdown";
-      MarkupNodeType2["embed"] = "embed";
-      return MarkupNodeType2;
-    })(MarkupNodeType || {});
+    var MarkupNodeType2 = /* @__PURE__ */ ((MarkupNodeType22) => {
+      MarkupNodeType22["doc"] = "doc";
+      MarkupNodeType22["paragraph"] = "paragraph";
+      MarkupNodeType22["blockquote"] = "blockquote";
+      MarkupNodeType22["horizontal_rule"] = "horizontalRule";
+      MarkupNodeType22["heading"] = "heading";
+      MarkupNodeType22["code_block"] = "codeBlock";
+      MarkupNodeType22["text"] = "text";
+      MarkupNodeType22["image"] = "image";
+      MarkupNodeType22["file"] = "file";
+      MarkupNodeType22["reference"] = "reference";
+      MarkupNodeType22["emoji"] = "emoji";
+      MarkupNodeType22["hard_break"] = "hardBreak";
+      MarkupNodeType22["ordered_list"] = "orderedList";
+      MarkupNodeType22["bullet_list"] = "bulletList";
+      MarkupNodeType22["list_item"] = "listItem";
+      MarkupNodeType22["taskList"] = "taskList";
+      MarkupNodeType22["taskItem"] = "taskItem";
+      MarkupNodeType22["todoList"] = "todoList";
+      MarkupNodeType22["todoItem"] = "todoItem";
+      MarkupNodeType22["subLink"] = "subLink";
+      MarkupNodeType22["table"] = "table";
+      MarkupNodeType22["table_row"] = "tableRow";
+      MarkupNodeType22["table_cell"] = "tableCell";
+      MarkupNodeType22["table_header"] = "tableHeader";
+      MarkupNodeType22["mermaid"] = "mermaid";
+      MarkupNodeType22["comment"] = "comment";
+      MarkupNodeType22["markdown"] = "markdown";
+      MarkupNodeType22["embed"] = "embed";
+      return MarkupNodeType22;
+    })(MarkupNodeType2 || {});
     var MarkupMarkType = /* @__PURE__ */ ((MarkupMarkType2) => {
       MarkupMarkType2["link"] = "link";
       MarkupMarkType2["em"] = "italic";
@@ -81771,7 +81771,7 @@ var require_connection2 = __commonJS({
     });
     module2.exports = __toCommonJS2(connection_exports);
     var import_analytics = require_lib2();
-    var import_client38 = __toESM2(require_lib6());
+    var import_client39 = __toESM2(require_lib6());
     var import_core57 = __toESM2(require_lib4());
     var import_platform4 = __toESM2(require_lib());
     var import_rpc = require_lib18();
@@ -81882,7 +81882,7 @@ var require_connection2 = __commonJS({
           }
           if (!this.closed) {
             void this.sendRequest({
-              method: import_client38.pingConst,
+              method: import_client39.pingConst,
               params: [],
               once: true,
               handleResult: /* @__PURE__ */ __name(async (result) => {
@@ -81915,7 +81915,7 @@ var require_connection2 = __commonJS({
         }
       }
       isConnected() {
-        return this.websocket != null && this.websocket.readyState === import_client38.ClientSocketReadyState.OPEN && this.helloReceived;
+        return this.websocket != null && this.websocket.readyState === import_client39.ClientSocketReadyState.OPEN && this.helloReceived;
       }
       delay = 0;
       onConnectHandlers = [];
@@ -82055,8 +82055,8 @@ var require_connection2 = __commonJS({
           }
           return;
         }
-        if (resp.result === import_client38.pingConst) {
-          void this.sendRequest({ method: import_client38.pingConst, params: [] }).catch((err) => {
+        if (resp.result === import_client39.pingConst) {
+          void this.sendRequest({ method: import_client39.pingConst, params: [] }).catch((err) => {
             this.ctx.error("failed to send ping", { err });
           });
           return;
@@ -82148,15 +82148,15 @@ var require_connection2 = __commonJS({
         }
       }
       checkArrayBufferPing(data) {
-        if (data.byteLength === import_client38.pingConst.length || data.byteLength === import_client38.pongConst.length) {
+        if (data.byteLength === import_client39.pingConst.length || data.byteLength === import_client39.pongConst.length) {
           const text = new TextDecoder().decode(data);
-          if (text === import_client38.pingConst) {
-            void this.sendRequest({ method: import_client38.pingConst, params: [] }).catch((err) => {
+          if (text === import_client39.pingConst) {
+            void this.sendRequest({ method: import_client39.pingConst, params: [] }).catch((err) => {
               this.ctx.error("failed to send ping", { err });
             });
             return true;
           }
-          if (text === import_client38.pongConst) {
+          if (text === import_client39.pongConst) {
             this.pingResponse = Date.now();
             return true;
           }
@@ -82166,7 +82166,7 @@ var require_connection2 = __commonJS({
       openConnection(ctx, socketId) {
         this.binaryMode = false;
         this.helloReceived = false;
-        const clientSocketFactory = this.opt?.socketFactory ?? (0, import_platform4.getMetadata)(import_client38.default.metadata.ClientSocketFactory) ?? ((url4) => {
+        const clientSocketFactory = this.opt?.socketFactory ?? (0, import_platform4.getMetadata)(import_client39.default.metadata.ClientSocketFactory) ?? ((url4) => {
           const s = new WebSocket(url4);
           return s;
         });
@@ -82201,12 +82201,12 @@ var require_connection2 = __commonJS({
           if (this.websocket !== wsocket) {
             return;
           }
-          if (event.data === import_client38.pongConst) {
+          if (event.data === import_client39.pongConst) {
             this.pingResponse = Date.now();
             return;
           }
-          if (event.data === import_client38.pingConst) {
-            void this.sendRequest({ method: import_client38.pingConst, params: [] }).catch((err) => {
+          if (event.data === import_client39.pingConst) {
+            void this.sendRequest({ method: import_client39.pingConst, params: [] }).catch((err) => {
               this.ctx.error("failed to send ping", { err });
             });
             return;
@@ -82271,8 +82271,8 @@ var require_connection2 = __commonJS({
           if (this.websocket !== wsocket) {
             return;
           }
-          const useBinary = this.opt?.useBinaryProtocol ?? (0, import_platform4.getMetadata)(import_client38.default.metadata.UseBinaryProtocol) ?? true;
-          this.compressionMode = this.opt?.useProtocolCompression ?? (0, import_platform4.getMetadata)(import_client38.default.metadata.UseProtocolCompression) ?? false;
+          const useBinary = this.opt?.useBinaryProtocol ?? (0, import_platform4.getMetadata)(import_client39.default.metadata.UseBinaryProtocol) ?? true;
+          this.compressionMode = this.opt?.useProtocolCompression ?? (0, import_platform4.getMetadata)(import_client39.default.metadata.UseProtocolCompression) ?? false;
           const helloRequest = {
             method: "hello",
             params: [],
@@ -82318,13 +82318,13 @@ var require_connection2 = __commonJS({
             if (w instanceof Promise) {
               await w;
             }
-            if (data.method !== import_client38.pingConst) {
+            if (data.method !== import_client39.pingConst) {
               this.requests.set(id, promise4);
             }
             promise4.sendData = () => {
-              if (this.websocket?.readyState === import_client38.ClientSocketReadyState.OPEN) {
+              if (this.websocket?.readyState === import_client39.ClientSocketReadyState.OPEN) {
                 promise4.startTime = Date.now();
-                if (data.method !== import_client38.pingConst) {
+                if (data.method !== import_client39.pingConst) {
                   const dta = this.rpcHandler.serialize(
                     {
                       method: data.method,
@@ -82337,7 +82337,7 @@ var require_connection2 = __commonJS({
                   );
                   this.websocket?.send(dta);
                 } else {
-                  this.websocket?.send(import_client38.pingConst);
+                  this.websocket?.send(import_client39.pingConst);
                 }
               }
             };
@@ -82351,7 +82351,7 @@ var require_connection2 = __commonJS({
               };
             }
             promise4.sendData();
-            if (data.method !== import_client38.pingConst) {
+            if (data.method !== import_client39.pingConst) {
               return await promise4.promise;
             }
           },
@@ -82517,7 +82517,7 @@ var require_lib19 = __commonJS({
       default: () => index_default
     });
     module2.exports = __toCommonJS2(index_exports2);
-    var import_client38 = __toESM2(require_lib6());
+    var import_client39 = __toESM2(require_lib6());
     var import_core57 = __toESM2(require_lib4());
     var import_platform4 = __toESM2(require_lib());
     var import_connection = require_connection2();
@@ -82561,8 +82561,8 @@ var require_lib19 = __commonJS({
       return {
         function: {
           GetClient: /* @__PURE__ */ __name(async (token, endpoint, opt) => {
-            const filterModel = (0, import_platform4.getMetadata)(import_client38.default.metadata.FilterModel) ?? "none";
-            const extraFilter = (0, import_platform4.getMetadata)(import_client38.default.metadata.ExtraFilter) ?? [];
+            const filterModel = (0, import_platform4.getMetadata)(import_client39.default.metadata.FilterModel) ?? "none";
+            const extraFilter = (0, import_platform4.getMetadata)(import_client39.default.metadata.ExtraFilter) ?? [];
             const handler = /* @__PURE__ */ __name(async (handler2) => {
               const url4 = (0, import_core57.concatLink)(endpoint, `/${token}`);
               const upgradeHandler = /* @__PURE__ */ __name((...txes) => {
@@ -82590,7 +82590,7 @@ var require_lib19 = __commonJS({
                 throw new Error("Workspace or account not found in token");
               }
               const newOpt = { ...opt };
-              const connectTimeout = opt?.connectionTimeout ?? (0, import_platform4.getMetadata)(import_client38.default.metadata.ConnectionTimeout);
+              const connectTimeout = opt?.connectionTimeout ?? (0, import_platform4.getMetadata)(import_client39.default.metadata.ConnectionTimeout);
               let connectPromise;
               if ((connectTimeout ?? 0) > 0) {
                 connectPromise = new Promise((resolve2, reject) => {
@@ -82642,7 +82642,7 @@ var require_lib19 = __commonJS({
     function returnUITxes(txes, extraFilter) {
       const configs = /* @__PURE__ */ new Map();
       (0, import_core57.fillConfiguration)(txes, configs);
-      const allowedPlugins = [...(0, import_platform4.getPlugins)(), ...(0, import_platform4.getMetadata)(import_client38.default.metadata.ExtraPlugins) ?? []];
+      const allowedPlugins = [...(0, import_platform4.getPlugins)(), ...(0, import_platform4.getMetadata)(import_client39.default.metadata.ExtraPlugins) ?? []];
       const excludedPlugins = Array.from(configs.values()).filter(
         (it) => !it.enabled || !allowedPlugins.includes(it.pluginId) || extraFilter.includes(it.pluginId)
       );
@@ -82690,7 +82690,7 @@ var require_lib19 = __commonJS({
     }
     __name(returnClientTxes, "returnClientTxes");
     function createModelPersistence(workspace) {
-      const overrideStore = (0, import_platform4.getMetadata)(import_client38.default.metadata.OverridePersistenceStore);
+      const overrideStore = (0, import_platform4.getMetadata)(import_client39.default.metadata.OverridePersistenceStore);
       if (overrideStore !== void 0) {
         return overrideStore;
       }
@@ -82787,11 +82787,11 @@ var require_client6 = __commonJS({
     });
     module2.exports = __toCommonJS2(client_exports);
     var import_account_client2 = require_lib5();
-    var import_client38 = __toESM2(require_lib6());
+    var import_client39 = __toESM2(require_lib6());
     var import_core57 = require_lib4();
     var import_platform4 = require_lib();
     var import_config9 = require_config();
-    var import_markup11 = require_markup();
+    var import_markup12 = require_markup();
     var import_utils14 = require_utils9();
     async function connect(url4, options) {
       const config3 = await (0, import_config9.loadServerConfig)(url4);
@@ -82813,9 +82813,9 @@ var require_client6 = __commonJS({
     }
     __name(connect, "connect");
     async function createClient(url4, endpoint, token, workspaceUuid, account, config3, options) {
-      (0, import_platform4.addLocation)(import_client38.clientId, () => Promise.resolve().then(() => __toESM(require_lib19())));
+      (0, import_platform4.addLocation)(import_client39.clientId, () => Promise.resolve().then(() => __toESM(require_lib19())));
       const { socketFactory, connectionTimeout } = options;
-      const clientFactory = await (0, import_platform4.getResource)(import_client38.default.function.GetClient);
+      const clientFactory = await (0, import_platform4.getResource)(import_client39.default.function.GetClient);
       const connection = await clientFactory(token, endpoint, {
         socketFactory,
         connectionTimeout
@@ -82832,7 +82832,7 @@ var require_client6 = __commonJS({
         this.connection = connection;
         this.account = account;
         this.client = new import_core57.TxOperations(connection, account.primarySocialId);
-        this.markup = (0, import_markup11.createMarkupOperations)(url4, workspace, token, config3);
+        this.markup = (0, import_markup12.createMarkupOperations)(url4, workspace, token, config3);
       }
       static {
         __name(this, "PlatformClientImpl");
@@ -82861,7 +82861,7 @@ var require_client6 = __commonJS({
       async processMarkup(_class, id, data) {
         const result = {};
         for (const [key, value3] of Object.entries(data)) {
-          if (value3 instanceof import_markup11.MarkupContent) {
+          if (value3 instanceof import_markup12.MarkupContent) {
             result[key] = this.markup.uploadMarkup(_class, id, key, value3.content, value3.kind);
           } else {
             result[key] = value3;
@@ -83936,11 +83936,11 @@ var require_storage2 = __commonJS({
     var __toCommonJS2 = (mod) => __copyProps2(__defProp2({}, "__esModule", { value: true }), mod);
     var storage_exports = {};
     __export2(storage_exports, {
-      connectStorage: () => import_client38.connectStorage,
-      createStorageClient: () => import_client38.createStorageClient
+      connectStorage: () => import_client39.connectStorage,
+      createStorageClient: () => import_client39.createStorageClient
     });
     module2.exports = __toCommonJS2(storage_exports);
-    var import_client38 = require_client7();
+    var import_client39 = require_client7();
     __reExport2(storage_exports, require_error3(), module2.exports);
     __reExport2(storage_exports, require_types8(), module2.exports);
   }
@@ -152358,6 +152358,16 @@ var DocumentEditModeError = class extends Schema_exports.TaggedError()(
     return `Invalid edit_document mode: ${this.reason}`;
   }
 };
+var DocumentReferenceError = class extends Schema_exports.TaggedError()(
+  "DocumentReferenceError",
+  {
+    reason: Schema_exports.String
+  }
+) {
+  get message() {
+    return `Invalid document references: ${this.reason}`;
+  }
+};
 
 // src/huly/errors-files.ts
 var BYTES_PER_MB = 1024 * 1024;
@@ -153686,6 +153696,7 @@ var HulyDomainError = Schema_exports.Union(
   DocumentEmptyContentError,
   DocumentContentCorruptedError,
   DocumentEditModeError,
+  DocumentReferenceError,
   CommentNotFoundError,
   MilestoneNotFoundError,
   ChannelNotFoundError,
@@ -153764,6 +153775,12 @@ var isMarkdownSerializableMark = (mark) => !isInlineCommentMark(mark);
 
 // src/huly/operations/markup.ts
 var jsonAsMarkup = import_text.jsonToMarkup;
+var MARKDOWN_INPUT_REF_URL = "https://huly-mcp.invalid/no-reference-conversion";
+var markdownInputRefUrl = UrlString.make(MARKDOWN_INPUT_REF_URL);
+var markdownInputUrlConfig = (urls) => ({
+  refUrl: markdownInputRefUrl,
+  imageUrl: urls.imageUrl
+});
 var testMarkupUrlConfig = {
   refUrl: UrlString.make("https://test.invalid/browse?workspace=test"),
   imageUrl: UrlString.make("https://test.invalid/files?workspace=test&file=")
@@ -153803,9 +153820,125 @@ var markupToMarkdownString = (markup, urls) => {
   return markupNodeToMarkdownString(json3, urls);
 };
 var markdownToMarkupString = (markdown, urls) => {
-  const json3 = (0, import_text_markdown.markdownToMarkup)(markdown, urls);
+  const json3 = (0, import_text_markdown.markdownToMarkup)(markdown, markdownInputUrlConfig(urls));
   return jsonAsMarkup(json3);
 };
+var trimmedQueryValue = (query, name) => {
+  const value3 = query.get(name);
+  if (value3 === null) {
+    return void 0;
+  }
+  const trimmed2 = value3.trim();
+  return trimmed2 === "" ? void 0 : trimmed2;
+};
+var hasAnyNativeReferenceQueryField = (query) => ["_id", "_class", "label"].some((name) => query.has(name));
+var parseUrlPair = (href, refUrl) => {
+  try {
+    return {
+      candidateUrl: new URL(href),
+      refUrl: new URL(refUrl)
+    };
+  } catch {
+    return void 0;
+  }
+};
+var parseNativeReferenceQuery = (query) => {
+  const id = trimmedQueryValue(query, "_id");
+  const objectClass = trimmedQueryValue(query, "_class");
+  const label = trimmedQueryValue(query, "label");
+  if (id === void 0 || objectClass === void 0 || label === void 0) {
+    const missing = [
+      id === void 0 ? "id" : void 0,
+      objectClass === void 0 ? "objectclass" : void 0,
+      label === void 0 ? "label" : void 0
+    ].filter((name) => name !== void 0);
+    return { _tag: "missing", missing };
+  }
+  return {
+    _tag: "reference",
+    reference: {
+      id: DocId.make(id),
+      objectClass: ObjectClassName.make(objectClass),
+      label: NonEmptyString2.make(label)
+    }
+  };
+};
+var parseNativeBrowseReferenceHref = (href, urls) => {
+  const parsedUrlPair = parseUrlPair(href, urls.refUrl);
+  if (parsedUrlPair === void 0) {
+    return { _tag: "notReference" };
+  }
+  const { candidateUrl, refUrl } = parsedUrlPair;
+  if (candidateUrl.origin !== refUrl.origin || candidateUrl.pathname !== refUrl.pathname) {
+    return { _tag: "notReference" };
+  }
+  if (candidateUrl.searchParams.get("workspace") !== refUrl.searchParams.get("workspace")) {
+    return { _tag: "notReference" };
+  }
+  if (!hasAnyNativeReferenceQueryField(candidateUrl.searchParams)) {
+    return { _tag: "notReference" };
+  }
+  const parsedQuery = parseNativeReferenceQuery(candidateUrl.searchParams);
+  if (parsedQuery._tag === "missing") {
+    return { _tag: "malformed", reason: `reference missing ${parsedQuery.missing.join(", ")}` };
+  }
+  return {
+    _tag: "reference",
+    reference: parsedQuery.reference
+  };
+};
+var linkHref = (node) => {
+  const linkMark = node.marks?.find((mark) => mark.type === "link" && typeof mark.attrs?.href === "string");
+  const href = linkMark?.attrs?.href;
+  return typeof href === "string" ? href : void 0;
+};
+var referenceNodeFromTextNode = (node, reference) => ({
+  type: import_text.MarkupNodeType.reference,
+  attrs: {
+    id: reference.id,
+    objectclass: reference.objectClass,
+    label: reference.label
+  },
+  content: [{
+    type: import_text.MarkupNodeType.text,
+    text: typeof node.text === "string" && node.text !== "" ? node.text : reference.label,
+    marks: []
+  }]
+});
+var transformNativeReferenceLinks = (node, urls) => {
+  const href = node.type === import_text.MarkupNodeType.text ? linkHref(node) : void 0;
+  if (href !== void 0) {
+    const parsed = parseNativeBrowseReferenceHref(href, urls);
+    if (parsed._tag === "malformed") {
+      return { node, malformedReferences: [parsed.reason], changed: false };
+    }
+    if (parsed._tag === "reference") {
+      return {
+        node: referenceNodeFromTextNode(node, parsed.reference),
+        malformedReferences: [],
+        changed: true
+      };
+    }
+  }
+  if (node.content === void 0) {
+    return { node, malformedReferences: [], changed: false };
+  }
+  const transformed = node.content.map((child) => transformNativeReferenceLinks(child, urls));
+  const changed = transformed.some((entry) => entry.changed);
+  return {
+    node: changed ? { ...node, content: transformed.map((entry) => entry.node) } : node,
+    malformedReferences: transformed.flatMap((entry) => entry.malformedReferences),
+    changed
+  };
+};
+var markdownToMarkupStringWithHulyLinks = (markdown, urls) => {
+  const json3 = (0, import_text_markdown.markdownToMarkup)(markdown, markdownInputUrlConfig(urls));
+  const transformed = transformNativeReferenceLinks(json3, urls);
+  return {
+    markup: jsonAsMarkup(transformed.node),
+    malformedReferences: transformed.malformedReferences
+  };
+};
 var optionalMarkdownToMarkup = (md, urls, fallback = "") => md && md.trim() !== "" ? markdownToMarkupString(md, urls) : fallback;
 function optionalMarkupToMarkdown(markup, urls, fallback = "") {
   return markup === null || markup === void 0 ? fallback : markupToMarkdownString(markup, urls);
@@ -153899,6 +154032,10 @@ var connectWithRetry = (connect, errorPrefix) => withConnectionRetry(
     }
   })
 );
+var markdownInputOptions = (opts) => ({
+  refUrl: MARKDOWN_INPUT_REF_URL,
+  imageUrl: opts.imageUrl
+});
 function toInternalMarkup(value3, format7, opts, sdk) {
   switch (format7) {
     case "markup":
@@ -153906,7 +154043,7 @@ function toInternalMarkup(value3, format7, opts, sdk) {
     case "html":
       return sdk.jsonToMarkup(sdk.htmlToJSON(value3));
     case "markdown":
-      return sdk.jsonToMarkup(sdk.markdownToMarkup(value3, opts));
+      return sdk.jsonToMarkup(sdk.markdownToMarkup(value3, markdownInputOptions(opts)));
     default:
       absurd(format7);
       throw new Error(`Invalid format: ${format7}`);
@@ -164471,6 +164608,7 @@ var INVALID_PARAMS_TAGS = /* @__PURE__ */ new Set([
   "DocumentEmptyContentError",
   "DocumentContentCorruptedError",
   "DocumentEditModeError",
+  "DocumentReferenceError",
   "CommentNotFoundError",
   "MilestoneNotFoundError",
   "ChannelNotFoundError",
@@ -167160,6 +167298,10 @@ var parseDeleteIssueTemplateParams = Schema_exports.decodeUnknown(DeleteIssueTem
 var parseAddTemplateChildParams = Schema_exports.decodeUnknown(AddTemplateChildParamsSchema);
 var parseRemoveTemplateChildParams = Schema_exports.decodeUnknown(RemoveTemplateChildParamsSchema);
 
+// src/domain/schemas/document-native-references.ts
+var DOCUMENT_NATIVE_REFERENCE_LINK_USAGE = "Use markdown links to current-workspace Huly browse URLs for native references; Huly browse links returned in get_document content round-trip as native references. The URL identifies the object; link text is display text; plain issue keys stay text.";
+var DOCUMENT_NATIVE_REFERENCE_TOOL_USAGE = `${DOCUMENT_NATIVE_REFERENCE_LINK_USAGE} External URLs stay normal markdown links.`;
+
 // src/domain/schemas/documents.ts
 var ListTeamspacesParamsSchema = Schema_exports.Struct({
   includeArchived: Schema_exports.optional(Schema_exports.Boolean.annotations({
@@ -167264,7 +167406,7 @@ var EditDocumentParamsSchema = EditDocumentParamsBase.pipe(
     const hasSearchReplace = hasOldText && hasNewText;
     const hasUpdateField = params.title !== void 0 || hasContent || hasSearchReplace;
     if (hasContent && (hasOldText || hasNewText)) {
-      return "Cannot provide both 'content' (full replace) and 'old_text'/'new_text' (search-and-replace). Use one mode or the other.";
+      return "Cannot provide 'content' with 'old_text'/'new_text'. Use full replace or search-and-replace, not both.";
     }
     if (hasOldText !== hasNewText) {
       return "Both 'old_text' and 'new_text' must be provided together for search-and-replace mode.";
@@ -170223,7 +170365,7 @@ var parseDeleteTestResultParams = Schema_exports.decodeUnknown(DeleteTestResultP
 var parseRunTestPlanParams = Schema_exports.decodeUnknown(RunTestPlanParamsSchema);
 
 // src/version.ts
-var VERSION = true ? "0.20.0" : "0.0.0-dev";
+var VERSION = true ? "0.21.0" : "0.0.0-dev";
 
 // src/mcp/tool-output-schema.ts
 var defaultToolOutputSchema = {
@@ -170598,6 +170740,19 @@ var listDirectMessages = (params) => Effect_exports.gen(function* () {
 var import_core13 = __toESM(require_lib4(), 1);
 var import_rank = __toESM(require_lib33(), 1);
 
+// src/huly/operations/document-native-references.ts
+var malformedReferenceList = (entries2) => entries2.map((entry) => `'${entry}'`).join(", ");
+var renderDocumentContentForWrite = (content) => Effect_exports.gen(function* () {
+  const client = yield* HulyClient;
+  const rendered = markdownToMarkupStringWithHulyLinks(content, client.markupUrlConfig);
+  if (rendered.malformedReferences.length > 0) {
+    return yield* new DocumentReferenceError({
+      reason: `malformed Huly native reference links in content: ${malformedReferenceList(rendered.malformedReferences)}`
+    });
+  }
+  return { markup: rendered.markup, format: "markup" };
+});
+
 // src/huly/operations/documents-shared.ts
 var findTeamspace = (identifier2, opts) => Effect_exports.gen(function* () {
   const client = yield* HulyClient;
@@ -170705,20 +170860,22 @@ var editDocument = (params) => Effect_exports.gen(function* () {
     if (params.content.trim() === "") {
       updateOps.content = null;
     } else if (doc.content) {
+      const renderedContent = yield* renderDocumentContentForWrite(params.content);
       yield* client.updateMarkup(
         documentPlugin.class.Document,
         doc._id,
         "content",
-        params.content,
-        "markdown"
+        renderedContent.markup,
+        renderedContent.format
       );
     } else {
+      const renderedContent = yield* renderDocumentContentForWrite(params.content);
       const contentMarkupRef = yield* client.uploadMarkup(
         documentPlugin.class.Document,
         doc._id,
         "content",
-        params.content,
-        "markdown"
+        renderedContent.markup,
+        renderedContent.format
       );
       updateOps.content = contentMarkupRef;
     }
@@ -170746,12 +170903,13 @@ var editDocument = (params) => Effect_exports.gen(function* () {
     }
     const idx = currentContent.indexOf(params.old_text);
     const newContent = params.replace_all ? currentContent.split(params.old_text).join(params.new_text) : currentContent.substring(0, idx) + params.new_text + currentContent.substring(idx + params.old_text.length);
+    const renderedContent = yield* renderDocumentContentForWrite(newContent);
     yield* client.updateMarkup(
       documentPlugin.class.Document,
       doc._id,
       "content",
-      newContent,
-      "markdown"
+      renderedContent.markup,
+      renderedContent.format
     );
   }
   const finalTitle = updateOps.title ?? doc.title;
@@ -171067,13 +171225,17 @@ var createDocument = (params) => Effect_exports.gen(function* () {
     { sort: { rank: import_core13.SortingOrder.Descending } }
   );
   const rank = (0, import_rank.makeRank)(lastDoc?.rank, void 0);
-  const contentMarkupRef = params.content !== void 0 && params.content.trim() !== "" ? yield* client.uploadMarkup(
-    documentPlugin.class.Document,
-    documentId,
-    "content",
-    params.content,
-    "markdown"
-  ) : null;
+  const content = params.content;
+  const contentMarkupRef = content !== void 0 && content.trim() !== "" ? yield* Effect_exports.gen(function* () {
+    const renderedContent = yield* renderDocumentContentForWrite(content);
+    return yield* client.uploadMarkup(
+      documentPlugin.class.Document,
+      documentId,
+      "content",
+      renderedContent.markup,
+      renderedContent.format
+    );
+  }) : null;
   const documentData = {
     title: params.title,
     content: contentMarkupRef,
@@ -175283,7 +175445,7 @@ var documentTools = [
   },
   {
     name: "create_document",
-    description: "Create a new document in a Huly teamspace. Content supports full markdown including native Mermaid diagrams (```mermaid blocks render interactively in Huly UI). Optionally pass parent as a document title or ID to create a nested child document; invalid parents fail instead of silently creating a top-level document. Returns the created document id and a 'url' field pointing to the document in the Huly web app. Use link_document_to_issue to associate the document with a tracker issue.",
+    description: "Create a new document in a Huly teamspace. Content is markdown and supports native Mermaid diagrams (```mermaid blocks render interactively in Huly UI). " + DOCUMENT_NATIVE_REFERENCE_TOOL_USAGE + " Optionally pass parent as a document title or ID to create a nested child document; invalid parents fail instead of silently creating a top-level document. Returns the created document id and a 'url' field pointing to the document in the Huly web app. Use link_document_to_issue only if you also want an issue-document association.",
     category: CATEGORY10,
     inputSchema: createDocumentParamsJsonSchema,
     handler: createToolHandler(
@@ -175294,7 +175456,7 @@ var documentTools = [
   },
   {
     name: "edit_document",
-    description: "Edit an existing Huly document. Two content modes (mutually exclusive): (1) 'content' for full replace, (2) 'old_text' + 'new_text' for targeted search-and-replace. Multiple matches error unless replace_all is true. Empty new_text deletes matched text. Also supports renaming via 'title'. Content supports full markdown including native Mermaid diagrams. Returns a 'url' field pointing to the document in the Huly web app.",
+    description: "Edit an existing Huly document. You may rename with title and/or edit the body. Body editing has two mutually exclusive modes: (1) content replaces the entire markdown body, (2) old_text + new_text performs exact targeted search-and-replace. " + DOCUMENT_NATIVE_REFERENCE_TOOL_USAGE + " For targeted replace, multiple matches error unless replace_all is true; empty new_text deletes matched text. Content supports native Mermaid diagrams. Returns a 'url' field pointing to the document in the Huly web app.",
     category: CATEGORY10,
     inputSchema: editDocumentParamsJsonSchema,
     handler: createToolHandler(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firfi/huly-mcp",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "MCP server for Huly integration",
   "mcpName": "io.github.dearlordylord/huly-mcp",
   "type": "module",