triliumnext-mcp 0.3.10-beta.1 → 0.3.10-beta.2

package/build/modules/attributeManager.js

@@ -4,6 +4,7 @@
  */
 import axios from 'axios';
 import { logVerbose, logVerboseApi, logVerboseAxiosError } from "../utils/verboseUtils.js";
+import { validateAndTranslateTemplate, createTemplateRelationError } from "../utils/templateMapper.js";
 /**
  * Manage note attributes with write operations (create, update, delete)
  * This function provides write-only access to note attributes
@@ -49,12 +50,30 @@ async function create_single_attribute(noteId, attribute, axiosInstance) {
                 errors: validation.errors
             };
         }
+        // Translate template names to note IDs for template relations
+        let processedValue = attribute.value || "";
+        if (attribute.type === "relation" && attribute.name === "template" && attribute.value) {
+            try {
+                processedValue = validateAndTranslateTemplate(attribute.value);
+                logVerbose("create_single_attribute", `Translated template relation`, {
+                    from: attribute.value,
+                    to: processedValue
+                });
+            }
+            catch (error) {
+                return {
+                    success: false,
+                    message: createTemplateRelationError(attribute.value),
+                    errors: [error instanceof Error ? error.message : 'Template validation failed']
+                };
+            }
+        }
         // Prepare attribute data for ETAPI
         const attributeData = {
             noteId: noteId,
             type: attribute.type,
             name: attribute.name,
-            value: attribute.value || "",
+            value: processedValue,
             position: attribute.position || 10,
             isInheritable: attribute.isInheritable || false
         };
@@ -95,11 +114,26 @@ async function create_batch_attributes(noteId, attributes, axiosInstance) {
                 errors.push(`Validation failed for ${attribute.type} '${attribute.name}': ${validation.errors.join(', ')}`);
                 return null;
             }
+            // Translate template names to note IDs for template relations
+            let processedValue = attribute.value || "";
+            if (attribute.type === "relation" && attribute.name === "template" && attribute.value) {
+                try {
+                    processedValue = validateAndTranslateTemplate(attribute.value);
+                    logVerbose("create_batch_attributes", `Translated template relation`, {
+                        from: attribute.value,
+                        to: processedValue
+                    });
+                }
+                catch (error) {
+                    errors.push(createTemplateRelationError(attribute.value));
+                    return null;
+                }
+            }
             const attributeData = {
                 noteId: noteId,
                 type: attribute.type,
                 name: attribute.name,
-                value: attribute.value || "",
+                value: processedValue,
                 position: attribute.position || 10,
                 isInheritable: attribute.isInheritable || false
             };

package/build/modules/noteManager.js

@@ -5,6 +5,7 @@
 import { processContentArray } from '../utils/contentProcessor.js';
 import { logVerbose, logVerboseError, logVerboseApi } from '../utils/verboseUtils.js';
 import { getContentRequirements, validateContentForNoteType, extractTemplateRelation } from '../utils/contentRules.js';
+import { validateAndTranslateTemplate, createTemplateRelationError } from '../utils/templateMapper.js';
 /**
  * Strip HTML tags from content for text notes
  */
@@ -209,11 +210,26 @@ export async function handleCreateNote(args, axiosInstance) {
  */
 async function createNoteAttributes(noteId, attributes, axiosInstance) {
     const attributePromises = attributes.map(async (attr) => {
+        // Translate template names to note IDs for template relations
+        let processedValue = attr.value || '';
+        if (attr.type === "relation" && attr.name === "template" && attr.value) {
+            try {
+                processedValue = validateAndTranslateTemplate(attr.value);
+                logVerbose("createNoteAttributes", `Translated template relation`, {
+                    from: attr.value,
+                    to: processedValue
+                });
+            }
+            catch (error) {
+                logVerboseError("createNoteAttributes", error);
+                throw new Error(createTemplateRelationError(attr.value));
+            }
+        }
         const attributeData = {
             noteId: noteId,
             type: attr.type,
             name: attr.name,
-            value: attr.value || '',
+            value: processedValue,
             position: attr.position || 10,
             isInheritable: attr.isInheritable || false
         };

package/build/modules/searchQueryBuilder.js

@@ -1,4 +1,5 @@
 import { logVerboseInput, logVerboseOutput, logVerboseTransform } from "../utils/verboseUtils.js";
+import { translateTemplateNameToId, isBuiltinTemplate } from "../utils/templateMapper.js";
 export function buildSearchQuery(params) {
     const queryParts = [];
     // Verbose logging
@@ -191,6 +192,12 @@ function enhanceRelationProperty(name, op, value) {
     if (op === 'exists' || op === 'not_exists' || !value) {
         return name;
     }
+    // Translate built-in template names to note IDs
+    if (isTemplateOrSystemRelation(name) && isBuiltinTemplate(value)) {
+        const translatedValue = translateTemplateNameToId(value);
+        logVerboseTransform("searchQueryBuilder", value, translatedValue, `Translated template name`);
+        return `${name}.noteId`;
+    }
     // Auto-detect noteId patterns and apply appropriate suffix
     if (isNoteIdPattern(value) && isTemplateOrSystemRelation(name)) {
         return `${name}.noteId`;

package/build/modules/toolDefinitions.js

@@ -15,7 +15,7 @@ export function createWriteTools() {
                 properties: {
                     parentNoteId: {
                         type: "string",
-                        description: "ID of the parent note",
+                        description: "ID of the parent note. ⚠️ IMPORTANT: When creating child notes for special note types, ensure proper requirements:\n• RENDER parents: child must be type='code', mime='text/html' (HTML content for rendering)\n• CALENDAR parents: child must have #startDate, #endDate, #startTime, #endTime labels\n• BOARD parents: child must have #status label (e.g., 'To Do', 'In Progress', 'Done')\n• Missing required labels/relations will cause child notes to not display properly",
                         default: "root"
                     },
                     title: {
@@ -25,11 +25,11 @@ export function createWriteTools() {
                     type: {
                         type: "string",
                         enum: ["text", "code", "render", "search", "relationMap", "book", "noteMap", "mermaid", "webView"],
-                        description: "Type of note (aligned with TriliumNext ETAPI specification)",
+                        description: "Type of note (aligned with TriliumNext ETAPI specification). ⚠️ SPECIAL TYPES REQUIRE CHILD NOTES:\n• RENDER: Creates empty container - requires child HTML code note with ~renderNote relation\n• CALENDAR (template): Creates empty container - requires child notes with date/time labels\n• BOARD (template): Creates empty container - requires child notes with #status labels\n• All other types can contain content directly",
                     },
                     content: {
                         type: "string",
-                        description: "Content of the note (optional). Content requirements by note type: TEXT notes require HTML content (plain text auto-wrapped in <p> tags, e.g., '<p>Hello world</p>', '<strong>bold</strong>'); CODE/MERMAID notes require plain text ONLY (HTML tags rejected, e.g., 'def fibonacci(n):'); ⚠️ OMIT CONTENT for: 1) WEBVIEW notes (use #webViewSrc label instead), 2) Container templates (Board, Calendar, Grid View, List View, Table, Geo Map), 3) System notes: RENDER (create child HTML note with type='code' and mime='application/x-html', then link with ~renderNote relation), SEARCH (queries in search properties), RELATION_MAP (visual maps), NOTE_MAP (visual hierarchies), BOOK (container notes) - these must be EMPTY to work properly. When omitted, note will be created with empty content."
+                        description: "Content of the note (optional). Content requirements by note type: TEXT notes require HTML content (plain text auto-wrapped in <p> tags, e.g., '<p>Hello world</p>', '<strong>bold</strong>'); CODE/MERMAID notes require plain text ONLY (HTML tags rejected, e.g., 'def fibonacci(n):'); ⚠️ OMIT CONTENT for: 1) WEBVIEW notes (use #webViewSrc label instead), 2) Container templates (Board, Calendar, Grid View, List View, Table, Geo Map), 3) System notes: RENDER, SEARCH, RELATION_MAP, NOTE_MAP, BOOK - these must be EMPTY to work properly. When omitted, note will be created with empty content.\n\n📋 WORKFLOW FOR SPECIAL NOTE TYPES:\n• RENDER notes: Create empty → create child HTML code note → add ~renderNote relation to child\n• CALENDAR/BOARD/GRID/LIST/TABLE/GEO templates: Create empty with ~template relation → add child notes with proper labels\n• TEXT SNIPPET templates: Create with ~template relation + content\n• Most other types: Add content directly during creation"
                     },
                     mime: {
                         type: "string",
@@ -37,7 +37,7 @@ export function createWriteTools() {
                     },
                     attributes: {
                         type: "array",
-                        description: "Optional attributes to create with the note (labels and relations). Enables one-step note creation with metadata. Labels use #tag format (e.g., 'important', 'project'), relations connect to other notes (e.g., template relations use 'Board', 'Calendar', 'Text Snippet'). ⚠️ TEMPLATE RESTRICTIONS: Container templates (Board, Calendar, Grid View, List View, Table, Geo Map) MUST be empty notes - add content as child notes.",
+                        description: "Optional attributes to create with the note (labels and relations). Enables one-step note creation with metadata. ⚠️ CRITICAL: Always add template relations during create_note when possible!\n\n📋 TEMPLATE RELATIONS (add during create_note):\n• ~template = 'Board' (kanban task boards)\n• ~template = 'Calendar' (calendar event displays)\n• ~template = 'Grid View' (grid layouts)\n• ~template = 'List View' (list layouts)\n• ~template = 'Table' (table structures)\n• ~template = 'Geo Map' (geographic maps)\n• ~template = 'Text Snippet' (reusable text)\n\n⚠️ SPECIAL CASES requiring separate steps:\n• ~renderNote = '<noteId>' (RENDER notes - requires existing child note ID)\n• Custom relations pointing to specific notes (use note IDs after creation)\n\n📋 LABELS & OTHER RELATIONS:\n• Labels: #tag format (e.g., #important, #project)\n• Relations: ~connection format (e.g., ~author, ~publisher)\n• Template relations use human-readable names (auto-translated to system IDs)\n\n⚠️ TEMPLATE RESTRICTIONS: Container templates MUST be empty notes - add content as child notes",
                         items: {
                             type: "object",
                             properties: {
@@ -332,7 +332,7 @@ export function createWriteAttributeTools() {
     return [
         {
             name: "manage_attributes",
-            description: "Manage note attributes with write operations (create, update, delete). Create labels (#tags), template relations (~template), update existing attributes, and organize notes with metadata. IMPORTANT: This tool only provides write access - use read_attributes to view existing attributes. Relations require values pointing to existing notes (e.g., template relations use 'Board', 'Calendar'; author relations use target note titles or IDs). UPDATE LIMITATIONS: For labels, only value and position can be updated. For relations, only position can be updated. The isInheritable property cannot be changed via update - delete and recreate to modify inheritability. Supports single operations and efficient batch creation for better performance.",
+            description: "Manage note attributes with write operations (create, update, delete). Create labels (#tags), template relations (~template), update existing attributes, and organize notes with metadata. ⚠️ PRIORITY: Use create_note with attributes parameter for template relations when possible - only use this tool for post-creation modifications or complex scenarios.\n\n✅ BEST PRACTICE: Most template relations (~template = 'Board', 'Calendar', etc.) should be added during create_note\n❌ USE THIS TOOL FOR: ~renderNote relations, custom note-to-note relations, post-creation label updates\n\nIMPORTANT: This tool only provides write access - use read_attributes to view existing attributes. Relations require values pointing to existing notes (e.g., template relations use human-readable names like 'Board', 'Calendar' which are automatically translated to system note IDs; author relations use target note titles or IDs). UPDATE LIMITATIONS: For labels, only value and position can be updated. For relations, only position can be updated. The isInheritable property cannot be changed via update - delete and recreate to modify inheritability. Supports single operations and efficient batch creation for better performance.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -362,7 +362,7 @@ export function createWriteAttributeTools() {
                                 },
                                 value: {
                                     type: "string",
-                                    description: "Attribute value: REQUIRED for relations (relations must point to existing notes - use template names like 'Board', 'Calendar', 'Text Snippet' or target note IDs/titles like 'Tolkien' or 'abc123def'), optional for labels (e.g., status labels like 'In Progress', priority labels like 'High'). Relations always need values since they connect notes together."
+                                    description: "Attribute value: REQUIRED for relations (relations must point to existing notes - use human-readable template names like 'Board', 'Calendar', 'Text Snippet' which are automatically translated to system note IDs, or use target note IDs/titles like 'Tolkien' or 'abc123def' for custom relations), optional for labels (e.g., status labels like 'In Progress', priority labels like 'High'). Relations always need values since they connect notes together."
                                 },
                                 position: {
                                     type: "number",

package/build/utils/contentIntegrity.js

@@ -96,14 +96,8 @@ export async function validateContentForUpdate(rawContent, type) {
             break;
         case 'code':
         case 'mermaid':
-            // For code/mermaid notes, reject HTML content
-            if (isLikelyHtml(contentString)) {
-                return {
-                    isValid: false,
-                    processedContent: contentString,
-                    error: `${type} notes require plain text only, but HTML content was detected. Remove HTML tags and use plain text format.`
-                };
-            }
+            // Allow both plain text and HTML content for code/mermaid notes
+            // HTML validation removed to support more flexible content
             break;
         case 'render':
         case 'search':

package/build/utils/contentRules.js

@@ -13,6 +13,8 @@ const CONTAINER_TEMPLATES = [
     'Table', // Spreadsheet-like tables
     'Geo Map' // Geographic maps
 ];
+// Import template translation utilities
+import { isBuiltinTemplate } from "./templateMapper.js";
 /**
  * Get content rules for a note type (without considering templates)
  */
@@ -34,25 +36,25 @@ export function getNoteTypeContentRules(noteType) {
                 requiresHtml: false,
                 description: "Content must be empty - render notes display HTML content from child notes via ~renderNote relation",
                 examples: [""],
-                errorMessage: "Render notes must be empty. Create a child code note with type='code' and mime='application/x-html' containing your HTML, then link it with ~renderNote='child-note-title' relation."
+                errorMessage: "Render notes must be empty. Create a child code note with type='code' and mime='text/html' containing your HTML, then link it with ~renderNote='child-note-title' relation."
             };
         case 'code':
             return {
                 allowContent: true,
                 enforceEmpty: false,
                 requiresHtml: false,
-                description: "Plain text only (no HTML tags)",
-                examples: ["def fibonacci(n):", "console.log('hello');"],
-                errorMessage: "Code notes require plain text only. HTML tags are not allowed."
+                description: "Plain text or HTML content allowed",
+                examples: ["def fibonacci(n):", "console.log('hello');", "<div>HTML code example</div>"],
+                errorMessage: "Code notes accept both plain text and HTML content."
             };
         case 'mermaid':
             return {
                 allowContent: true,
                 enforceEmpty: false,
                 requiresHtml: false,
-                description: "Plain text only (Mermaid diagram syntax)",
-                examples: ["graph TD; A-->B", "sequenceDiagram; A->B: Hello"],
-                errorMessage: "Mermaid notes require plain text diagram syntax only. HTML tags are not allowed."
+                description: "Plain text or HTML content allowed (Mermaid diagram syntax)",
+                examples: ["graph TD; A-->B", "sequenceDiagram; A->B: Hello", "<div>HTML with Mermaid</div>"],
+                errorMessage: "Mermaid notes accept both plain text and HTML content."
             };
         case 'webView':
             return {
@@ -132,7 +134,7 @@ export function getTemplateContentRules(noteType, templateRelation) {
         ? templateRelation
         : templateRelation?.value;
     // Check if this is a container template that must be empty (overrides base rules)
-    if (noteType === 'book' && templateValue && CONTAINER_TEMPLATES.includes(templateValue)) {
+    if (noteType === 'book' && templateValue && isBuiltinTemplate(templateValue) && CONTAINER_TEMPLATES.includes(templateValue)) {
         return {
             ...baseRules,
             allowContent: false,
@@ -231,9 +233,7 @@ export async function validateContentForNoteType(content, noteType, currentConte
     // Type-specific validation
     switch (noteType) {
         case 'text':
-        case 'render':
-        case 'webView':
-            // HTML required for these types
+            // HTML required for text notes
             if (rules.requiresHtml && !isLikelyHtml(textContent)) {
                 // Auto-wrap plain text in HTML
                 const wrappedContent = `<p>${textContent}</p>`;
@@ -246,16 +246,8 @@ export async function validateContentForNoteType(content, noteType, currentConte
             break;
         case 'code':
         case 'mermaid':
-            // Plain text required for code/mermaid notes
-            if (rules.requiresHtml === false && isLikelyHtml(textContent)) {
-                return {
-                    valid: false,
-                    content,
-                    error: `${noteType} notes require plain text only, but HTML content was detected. ` +
-                        `Remove HTML tags and use plain text format. ` +
-                        `Expected format: ${rules.examples.join(', ')}`
-                };
-            }
+            // Allow both plain text and HTML content for code/mermaid notes
+            // HTML validation removed to support more flexible content
             break;
     }
     return {

package/build/utils/templateMapper.js

@@ -0,0 +1,113 @@
+/**
+ * Template name to note ID mapping system for TriliumNext MCP
+ *
+ * This module provides translation between human-readable template names
+ * and their corresponding system note IDs in TriliumNext.
+ */
+// Built-in template name to note ID mapping
+export const TEMPLATE_NAME_TO_ID = {
+    'Grid View': '_template_grid_view',
+    'Calendar': '_template_calendar',
+    'Board': '_template_board',
+    'List View': '_template_list_view',
+    'Table': '_template_table',
+    'Geo Map': '_template_geo_map',
+    'Text Snippet': '_template_text_snippet'
+};
+// Reverse mapping for ID to name resolution
+export const TEMPLATE_ID_TO_NAME = Object.fromEntries(Object.entries(TEMPLATE_NAME_TO_ID).map(([name, id]) => [id, name]));
+// List of all built-in template names for validation
+export const BUILTIN_TEMPLATE_NAMES = Object.keys(TEMPLATE_NAME_TO_ID);
+// List of all built-in template IDs for validation
+export const BUILTIN_TEMPLATE_IDS = Object.values(TEMPLATE_NAME_TO_ID);
+/**
+ * Translates a human-readable template name to its system note ID
+ * @param templateName - Human-readable template name (e.g., "Grid View")
+ * @returns System note ID (e.g., "_template_grid_view")
+ */
+export function translateTemplateNameToId(templateName) {
+    return TEMPLATE_NAME_TO_ID[templateName] || templateName;
+}
+/**
+ * Translates a system note ID back to human-readable template name
+ * @param templateId - System note ID (e.g., "_template_grid_view")
+ * @returns Human-readable template name (e.g., "Grid View")
+ */
+export function translateTemplateIdToName(templateId) {
+    return TEMPLATE_ID_TO_NAME[templateId] || templateId;
+}
+/**
+ * Checks if a template name is a built-in template
+ * @param templateName - Template name to check
+ * @returns True if it's a built-in template
+ */
+export function isBuiltinTemplate(templateName) {
+    return templateName in TEMPLATE_NAME_TO_ID;
+}
+/**
+ * Checks if a template ID is a built-in template ID
+ * @param templateId - Template ID to check
+ * @returns True if it's a built-in template ID
+ */
+export function isBuiltinTemplateId(templateId) {
+    return templateId in TEMPLATE_ID_TO_NAME;
+}
+/**
+ * Validates and translates a template name for API use
+ * @param templateName - Template name to validate and translate
+ * @returns Translated template ID ready for API calls
+ * @throws Error if template name is invalid
+ */
+export function validateAndTranslateTemplate(templateName) {
+    if (typeof templateName !== 'string' || templateName.trim() === '') {
+        throw new Error('Template name cannot be empty');
+    }
+    // Check if it's a built-in template
+    if (isBuiltinTemplate(templateName)) {
+        return translateTemplateNameToId(templateName);
+    }
+    // Check if it's already a valid note ID pattern
+    if (isNoteIdPattern(templateName)) {
+        return templateName;
+    }
+    // Not a built-in template and not a note ID - show helpful error
+    throw new Error(`Invalid template: "${templateName}". Template relations must link to a note ID. ` +
+        `For built-in templates, use one of: ${BUILTIN_TEMPLATE_NAMES.join(', ')}. ` +
+        `For custom templates, use the note ID (e.g., "abc123"). ` +
+        `~template relations should always reference note IDs, not human-readable names.`);
+}
+/**
+ * Checks if a string matches Trilium note ID patterns
+ * @param value - String to check
+ * @returns True if it matches note ID patterns
+ */
+function isNoteIdPattern(value) {
+    // Trilium note IDs are typically alphanumeric with underscores, like "_template_grid_view" or "abc123def"
+    return /^[a-zA-Z0-9_]+$/.test(value) && value.length > 2;
+}
+/**
+ * Gets a list of available built-in templates for error messages
+ * @returns Formatted string listing available templates
+ */
+export function getAvailableTemplatesMessage() {
+    return `Available built-in templates: ${BUILTIN_TEMPLATE_NAMES.join(', ')}. ` +
+        `Custom templates should use their note ID (e.g., "abc123").`;
+}
+/**
+ * Provides enhanced error message for template relation validation
+ * @param templateValue - The template value that failed validation
+ * @returns Detailed error message
+ */
+export function createTemplateRelationError(templateValue) {
+    if (typeof templateValue !== 'string' || templateValue.trim() === '') {
+        return 'Template relation value cannot be empty';
+    }
+    if (isBuiltinTemplate(templateValue)) {
+        // This shouldn't happen if validation is working correctly
+        return `Built-in template "${templateValue}" should have been translated to "${translateTemplateNameToId(templateValue)}"`;
+    }
+    if (isNoteIdPattern(templateValue)) {
+        return `Template note ID "${templateValue}" may not exist. Verify the note ID is correct.`;
+    }
+    return `Invalid template relation: "${templateValue}". ${getAvailableTemplatesMessage()}`;
+}

package/build/utils/validationUtils.js

@@ -148,7 +148,9 @@ export function validateOperator(op) {
 export function validateTemplateRelation(templateName) {
     const validTemplates = ['Calendar', 'Board', 'Text Snippet', 'Grid View', 'List View', 'Table', 'Geo Map'];
     if (typeof templateName !== 'string' || !validTemplates.includes(templateName)) {
-        throw new Error(`Invalid template: ${templateName}. Must be one of: ${validTemplates.join(', ')}`);
+        throw new Error(`Invalid template: ${templateName}. Must be one of: ${validTemplates.join(', ')}. ` +
+            `Template relations must link to note IDs. For built-in templates, use their note ID (e.g., "_template_grid_view"). ` +
+            `For custom templates, use the actual note ID.`);
     }
     return templateName;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "triliumnext-mcp",
-  "version": "0.3.10-beta.1",
+  "version": "0.3.10-beta.2",
   "description": "A model context protocol server for TriliumNext Notes",
   "type": "module",
   "bin": {