triliumnext-mcp 0.3.11 → 0.3.12

package/build/modules/attributeHandler.js

@@ -221,6 +221,38 @@ function format_attribute_response(result, noteId, operation) {
                 text: `📋 Error details:\n${result.errors.map((err, i) => `${i + 1}. ${err}`).join('\n')}`
             });
         }
+        // Add specific guidance for common errors
+        if (result.errors && result.errors.some(err => err.includes("already exists"))) {
+            content.push({
+                type: "text",
+                text: `💡 **Attribute Already Exists**
+
+The attribute you're trying to create already exists on this note. Here are your options:
+
+1. **Update the existing attribute** (recommended):
+   - Use operation: "update" instead of "create"
+   - Only the value and position can be updated for labels
+   - Only the position can be updated for relations
+
+2. **Delete and recreate** (for inheritable changes):
+   - First delete with operation: "delete"
+   - Then recreate with operation: "create"
+   - Use this when you need to change the 'isInheritable' property
+
+3. **View current attributes**:
+   - Use read_attributes to see all existing attributes
+   - Check current values, positions, and inheritable settings
+
+📋 **Example update operation**:
+\`\`\`
+{
+  "noteId": "${noteId}",
+  "operation": "update",
+  "attributes": [{"type": "label", "name": "your_attribute", "value": "new_value"}]
+}
+\`\`\``
+            });
+        }
     }
     // Add attribute data for successful operations
     if (result.success && result.attributes && result.attributes.length > 0) {
@@ -246,6 +278,28 @@ function format_attribute_response(result, noteId, operation) {
             });
         }
     }
+    // Add guidance for batch operations with conflicts
+    if (result.success && operation === "batch_create" && result.errors && result.errors.length > 0) {
+        const hasConflicts = result.errors.some(err => err.includes("Skipping duplicate") || err.includes("already exist"));
+        if (hasConflicts) {
+            content.push({
+                type: "text",
+                text: `⚠️ **Batch Operation Summary**
+
+Some attributes were skipped due to conflicts (already existing). This is normal behavior for batch operations:
+
+✅ **Successfully created**: ${result.attributes?.length || 0} attributes
+❌ **Skipped duplicates**: ${result.errors?.filter(err => err.includes("Skipping duplicate") || err.includes("already exist")).length || 0} attributes
+
+💡 **To manage skipped attributes**:
+- Use \`read_attributes\` to view current attributes
+- Use \`update\` operation to modify existing attributes
+- Use \`delete\` operation to remove unwanted attributes first
+
+This approach prevents accidental overwrites while allowing partial success for batch operations.`
+            });
+        }
+    }
     return { content };
 }
 /**
@@ -316,5 +370,11 @@ export function get_attributes_help() {
 - Template relations require the target note to exist in your Trilium instance
 - Position values control display order (lower numbers appear first)
 - Use read_attributes to view existing attributes before making changes
+
+🛡️ **Validation & Conflict Handling**:
+- Create operations now validate against existing attributes to prevent duplicates
+- If an attribute already exists, you'll get detailed error messages with guidance
+- Batch operations skip duplicates and continue with valid attributes
+- Use "update" to modify existing attributes, "create" for new ones only
 `;
 }

package/build/modules/attributeManager.js

@@ -5,6 +5,7 @@
 import axios from 'axios';
 import { logVerbose, logVerboseApi, logVerboseAxiosError } from "../utils/verboseUtils.js";
 import { validateAndTranslateTemplate, createTemplateRelationError } from "../utils/templateMapper.js";
+import { cleanAttributeName, generateCleaningMessage } from "../utils/attributeNameCleaner.js";
 /**
  * Manage note attributes with write operations (create, update, delete)
  * This function provides write-only access to note attributes
@@ -36,12 +37,38 @@ export async function manage_attributes(params, axiosInstance) {
         };
     }
 }
+/**
+ * Check if an attribute already exists on a note
+ */
+async function check_attribute_exists(noteId, attribute, axiosInstance) {
+    try {
+        const response = await axiosInstance.get(`/notes/${noteId}`);
+        const existingAttributes = response.data.attributes.map((attr) => ({
+            type: attr.type,
+            name: attr.name,
+            value: attr.value,
+            position: attr.position,
+            isInheritable: attr.isInheritable
+        }));
+        // Find matching attribute by name and type
+        const matchingAttribute = existingAttributes.find(attr => attr.name === attribute.name && attr.type === attribute.type);
+        return {
+            exists: !!matchingAttribute,
+            existingAttribute: matchingAttribute,
+            allAttributes: existingAttributes
+        };
+    }
+    catch (error) {
+        // If we can't read attributes, assume it doesn't exist and let the create operation handle the error
+        return { exists: false };
+    }
+}
 /**
  * Create a single attribute on a note
  */
 async function create_single_attribute(noteId, attribute, axiosInstance) {
     try {
-        // Validate attribute
+        // Validate attribute with auto-correction
         const validation = validate_attribute(attribute);
         if (!validation.valid) {
             return {
@@ -50,20 +77,42 @@ async function create_single_attribute(noteId, attribute, axiosInstance) {
                 errors: validation.errors
             };
         }
+        // Use cleaned attribute if correction was made
+        const attributeToUse = validation.cleanedAttribute || attribute;
+        // Check if attribute already exists (use cleaned name)
+        const existenceCheck = await check_attribute_exists(noteId, attributeToUse, axiosInstance);
+        if (existenceCheck.exists && existenceCheck.existingAttribute) {
+            const existing = existenceCheck.existingAttribute;
+            const availableAttrs = existenceCheck.allAttributes?.map((attr) => `${attr.type}:${attr.name}`).join(', ') || 'none';
+            let message = `Attribute '${attributeToUse.name}' of type '${attributeToUse.type}' already exists on note ${noteId}. Available attributes: ${availableAttrs}`;
+            // Add cleaning information if name was corrected
+            if (validation.cleaningResult && validation.cleaningResult.wasCleaned) {
+                message += `\n\n🔧 **Note**: Attribute name was auto-corrected from "${validation.cleaningResult.originalName}" to "${attributeToUse.name}"`;
+            }
+            return {
+                success: false,
+                message,
+                errors: [
+                    "Attribute already exists",
+                    `Existing ${attributeToUse.type} '${attributeToUse.name}' has value: ${existing.value || 'none'}, position: ${existing.position || 'default'}, inheritable: ${existing.isInheritable || false}`,
+                    "To modify the existing attribute, use operation: 'update' instead of 'create'"
+                ]
+            };
+        }
         // Translate template names to note IDs for template relations
-        let processedValue = attribute.value || "";
-        if (attribute.type === "relation" && attribute.name === "template" && attribute.value) {
+        let processedValue = attributeToUse.value || "";
+        if (attributeToUse.type === "relation" && attributeToUse.name === "template" && attributeToUse.value) {
             try {
-                processedValue = validateAndTranslateTemplate(attribute.value);
+                processedValue = validateAndTranslateTemplate(attributeToUse.value);
                 logVerbose("create_single_attribute", `Translated template relation`, {
-                    from: attribute.value,
+                    from: attributeToUse.value,
                     to: processedValue
                 });
             }
             catch (error) {
                 return {
                     success: false,
-                    message: createTemplateRelationError(attribute.value),
+                    message: createTemplateRelationError(attributeToUse.value),
                     errors: [error instanceof Error ? error.message : 'Template validation failed']
                 };
             }
@@ -71,17 +120,22 @@ async function create_single_attribute(noteId, attribute, axiosInstance) {
         // Prepare attribute data for ETAPI
         const attributeData = {
             noteId: noteId,
-            type: attribute.type,
-            name: attribute.name,
+            type: attributeToUse.type,
+            name: attributeToUse.name,
             value: processedValue,
-            position: attribute.position || 10,
-            isInheritable: attribute.isInheritable || false
+            position: attributeToUse.position || 10,
+            isInheritable: attributeToUse.isInheritable || false
         };
         // Make API call to create attribute
         const response = await axiosInstance.post(`/attributes`, attributeData);
+        // Build success message with cleaning information
+        let successMessage = `Successfully created ${attributeToUse.type} '${attributeToUse.name}' on note ${noteId}`;
+        if (validation.cleaningResult && validation.cleaningResult.wasCleaned) {
+            successMessage += `\n\n${generateCleaningMessage([validation.cleaningResult])}`;
+        }
         return {
             success: true,
-            message: `Successfully created ${attribute.type} '${attribute.name}' on note ${noteId}`,
+            message: successMessage,
             attributes: [response.data]
         };
     }
@@ -93,6 +147,50 @@ async function create_single_attribute(noteId, attribute, axiosInstance) {
         };
     }
 }
+/**
+ * Validate batch attributes for conflicts and duplicates
+ */
+async function validate_batch_attributes(noteId, attributes, axiosInstance) {
+    try {
+        // Get all existing attributes once
+        const response = await axiosInstance.get(`/notes/${noteId}`);
+        const existingAttributes = response.data.attributes.map((attr) => ({
+            type: attr.type,
+            name: attr.name,
+            value: attr.value,
+            position: attr.position,
+            isInheritable: attr.isInheritable
+        }));
+        const conflicts = [];
+        const validAttributes = [];
+        // Check each new attribute against existing ones
+        for (const attribute of attributes) {
+            const existingMatch = existingAttributes.find(attr => attr.name === attribute.name && attr.type === attribute.type);
+            if (existingMatch) {
+                conflicts.push({
+                    attribute,
+                    existingAttribute: existingMatch
+                });
+            }
+            else {
+                validAttributes.push(attribute);
+            }
+        }
+        return {
+            conflicts,
+            validAttributes,
+            allExistingAttributes: existingAttributes
+        };
+    }
+    catch (error) {
+        // If we can't read attributes, assume no conflicts and proceed
+        return {
+            conflicts: [],
+            validAttributes: attributes,
+            allExistingAttributes: []
+        };
+    }
+}
 /**
  * Create multiple attributes in batch
  */
@@ -104,38 +202,58 @@ async function create_batch_attributes(noteId, attributes, axiosInstance) {
             attributes: []
         };
     }
+    // Validate batch for conflicts first
+    const batchValidation = await validate_batch_attributes(noteId, attributes, axiosInstance);
     const results = [];
     const errors = [];
-    // Create attributes in parallel for better performance
-    const promises = attributes.map(async (attribute) => {
+    // Add conflict warnings if any
+    if (batchValidation.conflicts.length > 0) {
+        const conflictMessages = batchValidation.conflicts.map(({ attribute, existingAttribute }) => {
+            return `Skipping duplicate ${attribute.type} '${attribute.name}' (already exists with value: ${existingAttribute.value || 'none'})`;
+        });
+        errors.push(...conflictMessages);
+    }
+    // If all attributes are conflicts, return early
+    if (batchValidation.validAttributes.length === 0) {
+        return {
+            success: false,
+            message: `All ${attributes.length} attributes already exist on note ${noteId}`,
+            errors,
+            attributes: []
+        };
+    }
+    // Create only valid (non-conflicting) attributes in parallel
+    const promises = batchValidation.validAttributes.map(async (attribute) => {
         try {
             const validation = validate_attribute(attribute);
             if (!validation.valid) {
                 errors.push(`Validation failed for ${attribute.type} '${attribute.name}': ${validation.errors.join(', ')}`);
                 return null;
             }
+            // Use cleaned attribute if correction was made
+            const attributeToUse = validation.cleanedAttribute || attribute;
             // Translate template names to note IDs for template relations
-            let processedValue = attribute.value || "";
-            if (attribute.type === "relation" && attribute.name === "template" && attribute.value) {
+            let processedValue = attributeToUse.value || "";
+            if (attributeToUse.type === "relation" && attributeToUse.name === "template" && attributeToUse.value) {
                 try {
-                    processedValue = validateAndTranslateTemplate(attribute.value);
+                    processedValue = validateAndTranslateTemplate(attributeToUse.value);
                     logVerbose("create_batch_attributes", `Translated template relation`, {
-                        from: attribute.value,
+                        from: attributeToUse.value,
                         to: processedValue
                     });
                 }
                 catch (error) {
-                    errors.push(createTemplateRelationError(attribute.value));
+                    errors.push(createTemplateRelationError(attributeToUse.value));
                     return null;
                 }
             }
             const attributeData = {
                 noteId: noteId,
-                type: attribute.type,
-                name: attribute.name,
+                type: attributeToUse.type,
+                name: attributeToUse.name,
                 value: processedValue,
-                position: attribute.position || 10,
-                isInheritable: attribute.isInheritable || false
+                position: attributeToUse.position || 10,
+                isInheritable: attributeToUse.isInheritable || false
             };
             const response = await axiosInstance.post(`/attributes`, attributeData);
             results.push(response.data);
@@ -148,7 +266,7 @@ async function create_batch_attributes(noteId, attributes, axiosInstance) {
         }
     });
     await Promise.all(promises);
-    if (errors.length === attributes.length) {
+    if (errors.length === batchValidation.validAttributes.length) {
         return {
             success: false,
             message: "All attribute creation operations failed",
@@ -156,10 +274,19 @@ async function create_batch_attributes(noteId, attributes, axiosInstance) {
         };
     }
     const successCount = results.length;
+    const validCount = batchValidation.validAttributes.length;
+    const conflictCount = batchValidation.conflicts.length;
     const totalCount = attributes.length;
+    let message = `Created ${successCount}/${validCount} valid attributes successfully`;
+    if (conflictCount > 0) {
+        message += ` (${conflictCount} skipped due to conflicts, ${totalCount} total requested)`;
+    }
+    if (errors.length > 0) {
+        message += ` with ${errors.length} errors`;
+    }
     return {
         success: successCount > 0,
-        message: `Created ${successCount}/${totalCount} attributes successfully${errors.length > 0 ? ` with ${errors.length} errors` : ''}`,
+        message,
         attributes: results,
         errors: errors.length > 0 ? errors : undefined
     };
@@ -169,17 +296,28 @@ async function create_batch_attributes(noteId, attributes, axiosInstance) {
  */
 async function update_attribute(noteId, attribute, axiosInstance) {
     try {
+        // Clean attribute name first
+        const cleaningResult = cleanAttributeName(attribute.name, attribute.type);
+        const attributeToUse = {
+            ...attribute,
+            name: cleaningResult.cleanedName
+        };
         // For update, we need the attribute ID, which requires finding it first
         const noteResponse = await axiosInstance.get(`/notes/${noteId}`);
         // Debug: Log available attributes
         logVerbose("update_attribute", `Available attributes on note ${noteId}`, noteResponse.data.attributes);
-        // Find the attribute to update by name and type
-        const targetAttribute = noteResponse.data.attributes.find((attr) => attr.name === attribute.name && attr.type === attribute.type);
+        // Find the attribute to update by name and type (use cleaned name)
+        const targetAttribute = noteResponse.data.attributes.find((attr) => attr.name === attributeToUse.name && attr.type === attributeToUse.type);
         if (!targetAttribute) {
             const availableAttrs = noteResponse.data.attributes.map((attr) => `${attr.type}:${attr.name}`).join(', ');
+            let message = `Attribute '${attributeToUse.name}' of type '${attributeToUse.type}' not found on note ${noteId}. Available attributes: ${availableAttrs || 'none'}`;
+            // Add cleaning information if name was corrected
+            if (cleaningResult.wasCleaned) {
+                message += `\n\n🔧 **Note**: Attribute name was auto-corrected from "${cleaningResult.originalName}" to "${attributeToUse.name}"`;
+            }
             return {
                 success: false,
-                message: `Attribute '${attribute.name}' of type '${attribute.type}' not found on note ${noteId}. Available attributes: ${availableAttrs || 'none'}`,
+                message,
                 errors: ["Attribute not found"]
             };
         }
@@ -189,20 +327,20 @@ async function update_attribute(noteId, attribute, axiosInstance) {
         // - For relations: only position can be updated
         // - isInheritable cannot be updated via PATCH, requires delete+recreate
         const updateData = {};
-        if (attribute.type === "label") {
-            updateData.value = attribute.value !== undefined ? attribute.value : targetAttribute.value;
+        if (attributeToUse.type === "label") {
+            updateData.value = attributeToUse.value !== undefined ? attributeToUse.value : targetAttribute.value;
         }
-        if (attribute.position !== undefined) {
-            updateData.position = attribute.position;
+        if (attributeToUse.position !== undefined) {
+            updateData.position = attributeToUse.position;
         }
         else if (targetAttribute.position !== undefined) {
             updateData.position = targetAttribute.position;
         }
         // Check if isInheritable is being changed (not allowed via PATCH)
-        if (attribute.isInheritable !== undefined && attribute.isInheritable !== targetAttribute.isInheritable) {
+        if (attributeToUse.isInheritable !== undefined && attributeToUse.isInheritable !== targetAttribute.isInheritable) {
             logVerbose("update_attribute", "isInheritable change detected, requires delete+recreate", {
                 current: targetAttribute.isInheritable,
-                requested: attribute.isInheritable
+                requested: attributeToUse.isInheritable
             });
             return {
                 success: false,
@@ -213,9 +351,14 @@ async function update_attribute(noteId, attribute, axiosInstance) {
         logVerbose("update_attribute", "Update data", updateData);
         logVerboseApi("PATCH", `/attributes/${targetAttribute.attributeId}`, updateData);
         const response = await axiosInstance.patch(`/attributes/${targetAttribute.attributeId}`, updateData);
+        // Build success message with cleaning information
+        let successMessage = `Successfully updated ${attributeToUse.type} '${attributeToUse.name}' on note ${noteId}`;
+        if (cleaningResult.wasCleaned) {
+            successMessage += `\n\n${generateCleaningMessage([cleaningResult])}`;
+        }
         return {
             success: true,
-            message: `Successfully updated ${attribute.type} '${attribute.name}' on note ${noteId}`,
+            message: successMessage,
             attributes: [response.data]
         };
     }
@@ -241,21 +384,37 @@ async function update_attribute(noteId, attribute, axiosInstance) {
  */
 async function delete_attribute(noteId, attribute, axiosInstance) {
     try {
+        // Clean attribute name first
+        const cleaningResult = cleanAttributeName(attribute.name, attribute.type);
+        const attributeToUse = {
+            ...attribute,
+            name: cleaningResult.cleanedName
+        };
         // For delete, we need the attribute ID, which requires finding it first
         const noteResponse = await axiosInstance.get(`/notes/${noteId}`);
-        // Find the attribute to delete by name and type
-        const targetAttribute = noteResponse.data.attributes.find((attr) => attr.name === attribute.name && attr.type === attribute.type);
+        // Find the attribute to delete by name and type (use cleaned name)
+        const targetAttribute = noteResponse.data.attributes.find((attr) => attr.name === attributeToUse.name && attr.type === attributeToUse.type);
         if (!targetAttribute) {
+            let message = `Attribute '${attributeToUse.name}' of type '${attributeToUse.type}' not found on note ${noteId}`;
+            // Add cleaning information if name was corrected
+            if (cleaningResult.wasCleaned) {
+                message += `\n\n🔧 **Note**: Attribute name was auto-corrected from "${cleaningResult.originalName}" to "${attributeToUse.name}"`;
+            }
             return {
                 success: false,
-                message: `Attribute '${attribute.name}' of type '${attribute.type}' not found on note ${noteId}`,
+                message,
                 errors: ["Attribute not found"]
             };
         }
         await axiosInstance.delete(`/attributes/${targetAttribute.attributeId}`);
+        // Build success message with cleaning information
+        let successMessage = `Successfully deleted ${attributeToUse.type} '${attributeToUse.name}' from note ${noteId}`;
+        if (cleaningResult.wasCleaned) {
+            successMessage += `\n\n${generateCleaningMessage([cleaningResult])}`;
+        }
         return {
             success: true,
-            message: `Successfully deleted ${attribute.type} '${attribute.name}' from note ${noteId}`
+            message: successMessage
         };
     }
     catch (error) {
@@ -267,7 +426,7 @@ async function delete_attribute(noteId, attribute, axiosInstance) {
     }
 }
 /**
- * Validate attribute data
+ * Validate attribute data with auto-correction
  */
 function validate_attribute(attribute) {
     const errors = [];
@@ -275,8 +434,14 @@ function validate_attribute(attribute) {
     if (!["label", "relation"].includes(attribute.type)) {
         errors.push("Attribute type must be either 'label' or 'relation'");
     }
-    // Validate name
-    if (!attribute.name || typeof attribute.name !== 'string' || attribute.name.trim() === '') {
+    // Clean attribute name first
+    const cleaningResult = cleanAttributeName(attribute.name, attribute.type);
+    const cleanedAttribute = {
+        ...attribute,
+        name: cleaningResult.cleanedName
+    };
+    // Validate name (using cleaned name)
+    if (!cleanedAttribute.name || typeof cleanedAttribute.name !== 'string' || cleanedAttribute.name.trim() === '') {
         errors.push("Attribute name is required and must be a non-empty string");
     }
     // Validate position
@@ -293,7 +458,9 @@ function validate_attribute(attribute) {
     }
     return {
         valid: errors.length === 0,
-        errors
+        errors,
+        cleanedAttribute: cleaningResult.wasCleaned ? cleanedAttribute : undefined,
+        cleaningResult: cleaningResult.wasCleaned ? cleaningResult : undefined
     };
 }
 /**

package/build/modules/noteManager.js

@@ -6,6 +6,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';
+import { cleanAttributeName, generateCleaningMessage } from '../utils/attributeNameCleaner.js';
 /**
  * Strip HTML tags from content for text notes
  */
@@ -207,8 +208,15 @@ export async function handleCreateNote(args, axiosInstance) {
     if (attributes && attributes.length > 0) {
         try {
             logVerbose("handleCreateNote", `Creating ${attributes.length} attributes for note ${noteId}`, attributes);
-            await createNoteAttributes(noteId, attributes, axiosInstance);
+            const attributeResult = await createNoteAttributes(noteId, attributes, axiosInstance);
             logVerbose("handleCreateNote", `Successfully created all attributes for note ${noteId}`);
+            // Add cleaning information to response if any corrections were made
+            if (attributeResult.cleaningResults && attributeResult.cleaningResults.length > 0) {
+                const cleaningMessage = generateCleaningMessage(attributeResult.cleaningResults);
+                if (cleaningMessage) {
+                    response.data.attributeCleaningMessage = cleaningMessage;
+                }
+            }
         }
         catch (attributeError) {
             const errorMsg = `Note created but attributes failed to apply: ${attributeError instanceof Error ? attributeError.message : attributeError}`;
@@ -226,37 +234,49 @@ export async function handleCreateNote(args, axiosInstance) {
  * Create attributes for a note (helper function)
  */
 async function createNoteAttributes(noteId, attributes, axiosInstance) {
+    const cleaningResults = [];
     const attributePromises = attributes.map(async (attr) => {
+        // Clean attribute name first
+        const cleaningResult = cleanAttributeName(attr.name, attr.type);
+        if (cleaningResult.wasCleaned) {
+            cleaningResults.push(cleaningResult);
+        }
+        // Use cleaned attribute name
+        const cleanedAttr = {
+            ...attr,
+            name: cleaningResult.cleanedName
+        };
         // Translate template names to note IDs for template relations
-        let processedValue = attr.value || '';
-        if (attr.type === "relation" && attr.name === "template" && attr.value) {
+        let processedValue = cleanedAttr.value || '';
+        if (cleanedAttr.type === "relation" && cleanedAttr.name === "template" && cleanedAttr.value) {
             try {
-                processedValue = validateAndTranslateTemplate(attr.value);
+                processedValue = validateAndTranslateTemplate(cleanedAttr.value);
                 logVerbose("createNoteAttributes", `Translated template relation`, {
-                    from: attr.value,
+                    from: cleanedAttr.value,
                     to: processedValue
                 });
             }
             catch (error) {
                 logVerboseError("createNoteAttributes", error);
-                throw new Error(createTemplateRelationError(attr.value));
+                throw new Error(createTemplateRelationError(cleanedAttr.value));
             }
         }
         const attributeData = {
             noteId: noteId,
-            type: attr.type,
-            name: attr.name,
+            type: cleanedAttr.type,
+            name: cleanedAttr.name,
             value: processedValue,
-            position: attr.position || 10,
-            isInheritable: attr.isInheritable || false
+            position: cleanedAttr.position || 10,
+            isInheritable: cleanedAttr.isInheritable || false
         };
         logVerboseApi("POST", `/attributes`, attributeData);
         const response = await axiosInstance.post(`/attributes`, attributeData);
-        logVerbose("createNoteAttributes", `Created ${attr.type} '${attr.name}' for note ${noteId}`, response.data);
+        logVerbose("createNoteAttributes", `Created ${cleanedAttr.type} '${cleanedAttr.name}' for note ${noteId}`, response.data);
         return response;
     });
     const results = await Promise.all(attributePromises);
     logVerbose("createNoteAttributes", `Successfully created ${results.length} attributes for note ${noteId}`);
+    return { results, cleaningResults };
 }
 /**
  * Handle update note operation
@@ -298,6 +318,103 @@ export async function handleUpdateNote(args, axiosInstance) {
                 };
             }
         }
+        // Step 2.5: Type change validation if provided
+        if (type && type !== currentNote.data.type) {
+            const currentType = currentNote.data.type;
+            const newType = type;
+            // Check for incompatible type changes with template relations
+            const existingAttributes = currentNote.data.attributes || [];
+            const templateRelation = existingAttributes.find((attr) => attr.type === 'relation' && attr.name === 'template')?.value;
+            if (templateRelation) {
+                // Container templates require 'book' type
+                const containerTemplates = [
+                    'board', '_template_board',
+                    'grid view', '_template_grid_view',
+                    'list view', '_template_list_view',
+                    'geo map', '_template_geo_map',
+                    'calendar', '_template_calendar'
+                ];
+                const isContainerTemplate = containerTemplates.includes(templateRelation.toLowerCase());
+                if (isContainerTemplate && newType !== 'book') {
+                    return {
+                        noteId,
+                        message: `TYPE CHANGE CONFLICT: Cannot change note type from "${currentType}" to "${newType}" while it has a "${templateRelation}" template relation.
+
+📋 **Template Compatibility Rules**:
+Container templates (Board, Calendar, Grid View, List View, Geo Map) require type "book" to function properly.
+
+🛠️ **Solutions**:
+1. **Keep current type**: Use type "book" to maintain template functionality
+2. **Remove template**: Delete the ~template relation first, then change type
+3. **Choose different template**: Switch to a template compatible with type "${newType}"
+
+💡 **For most use cases**: If you want a regular note with "${templateRelation}" features, consider:
+- Using type "text" with the ~template relation removed
+- Creating a child note inside this container for your content
+
+Please remove the template relation first or keep type as "book".`,
+                        revisionCreated: false,
+                        conflict: true
+                    };
+                }
+                // Book type can only be used with container templates
+                if (newType === 'book' && !isContainerTemplate) {
+                    return {
+                        noteId,
+                        message: `TYPE CHANGE CONFLICT: Cannot change note type to "book" while it has a "${templateRelation}" template relation.
+
+📋 **Book Type Requirements**:
+Book type should only be used with container templates (Board, Calendar, Grid View, List View, Geo Map) that provide specialized layouts.
+
+🛠️ **Solutions**:
+1. **Use type "text"**: Best for regular notes with content
+2. **Switch to container template**: Change ~template to "Board", "Calendar", etc. for specialized layouts
+3. **Keep current type**: Use "${currentType}" for optimal functionality
+
+💡 **Recommendation**: For regular notes with template relations, type "text" usually provides the best experience.
+
+Please choose a compatible template or use type "text".`,
+                        revisionCreated: false,
+                        conflict: true
+                    };
+                }
+            }
+            // Validate content compatibility for type changes with content updates
+            if (rawContent && currentContent.data) {
+                try {
+                    // Test if existing content is compatible with new type
+                    await validateContentForNoteType(currentContent.data, newType, currentContent.data, templateRelation);
+                }
+                catch (validationError) {
+                    const errorMessage = validationError instanceof Error ? validationError.message : String(validationError);
+                    return {
+                        noteId,
+                        message: `CONTENT COMPATIBILITY ERROR: Cannot change note type from "${currentType}" to "${newType}" with current content.
+
+📋 **Content Requirements for ${newType}**:
+${errorMessage}
+
+🛠️ **Solutions**:
+1. **Clean content**: Remove HTML, formatting, or incompatible elements
+2. **Keep current type**: Use "${currentType}" for existing content
+3. **Manual conversion**: Convert content manually to match ${newType} requirements
+
+💡 **Content Guidelines**:
+- **Code notes**: Plain text only (no HTML tags)
+- **Text notes**: HTML content (plain text auto-wrapped in <p> tags)
+- **Mermaid notes**: Plain text diagram definitions only
+
+Please modify the content to be compatible with type "${newType}" or keep the current type.`,
+                        revisionCreated: false,
+                        conflict: true
+                    };
+                }
+            }
+            logVerbose("handleUpdateNote", `Type change validation passed: ${currentType} → ${newType}`, {
+                templateRelation,
+                hasContent: !!rawContent
+            });
+        }
         // Handle title-only update (efficient PATCH operation)
         if (isTitleOnlyUpdate) {
             // For title-only updates, skip revision creation for efficiency
@@ -306,6 +423,10 @@ export async function handleUpdateNote(args, axiosInstance) {
             if (mime) {
                 patchData.mime = mime;
             }
+            // Add note type if provided (new capability)
+            if (type) {
+                patchData.type = type;
+            }
             logVerboseApi("PATCH", `/notes/${noteId}`, patchData);
             const response = await axiosInstance.patch(`/notes/${noteId}`, patchData, {
                 headers: {
@@ -315,10 +436,11 @@ export async function handleUpdateNote(args, axiosInstance) {
             if (response.status !== 200) {
                 throw new Error(`Unexpected response status: ${response.status}`);
             }
+            const typeMessage = type ? ` and type updated to "${type}"` : "";
             const mimeMessage = mime ? ` and MIME type updated to "${mime}"` : "";
             return {
                 noteId,
-                message: `Note ${noteId} title updated successfully to "${title}"${mimeMessage}`,
+                message: `Note ${noteId} title updated successfully to "${title}"${typeMessage}${mimeMessage}`,
                 revisionCreated: false,
                 conflict: false
             };
@@ -391,12 +513,15 @@ export async function handleUpdateNote(args, axiosInstance) {
         if (contentResponse.status !== 204) {
             throw new Error(`Unexpected response status: ${contentResponse.status}`);
         }
-        // Step 7: Update title and MIME type if provided (multi-parameter update)
-        if (isMultiParamUpdate && (title || mime)) {
+        // Step 7: Update title, type, and MIME type if provided (multi-parameter update)
+        if (isMultiParamUpdate && (title || type || mime)) {
             const patchData = {};
             if (title) {
                 patchData.title = title;
             }
+            if (type) {
+                patchData.type = type;
+            }
             if (mime) {
                 patchData.mime = mime;
             }
@@ -417,10 +542,11 @@ export async function handleUpdateNote(args, axiosInstance) {
         const correctionMsg = (finalContent !== rawContent) ? " (content auto-corrected)" : "";
         const modeMsg = mode === 'append' ? " (content appended)" : " (content overwritten)";
         const titleMsg = (isMultiParamUpdate && title) ? ` (title updated to "${title}")` : "";
+        const typeMsg = (isMultiParamUpdate && type) ? ` (type updated to "${type}")` : "";
         const mimeMsg = (isMultiParamUpdate && mime) ? ` (MIME type updated to "${mime}")` : "";
         return {
             noteId,
-            message: `Note ${noteId} updated successfully${revisionMsg}${correctionMsg}${modeMsg}${titleMsg}${mimeMsg}`,
+            message: `Note ${noteId} updated successfully${revisionMsg}${correctionMsg}${modeMsg}${titleMsg}${typeMsg}${mimeMsg}`,
             revisionCreated,
             conflict: false
         };

package/build/modules/toolDefinitions.js

@@ -9,13 +9,13 @@ export function createWriteTools() {
     return [
         {
             name: "create_note",
-            description: "Create a new note in TriliumNext with duplicate title detection. When a note with the same title already exists in the same directory, you'll be presented with choices: skip creation or update the existing note. ONLY use this tool when the user explicitly requests note creation (e.g., 'create a note', 'make a new note'). DO NOT use this tool proactively or when the user is only asking questions about their notes. TIP: For code notes, content is plain text (no HTML processing).",
+            description: "Create a new note in TriliumNext with duplicate title detection. When a note with the same title already exists in the same directory, you'll be presented with choices: skip creation or update the existing note. ⚠️ **PARENT FOLDER SELECTION**: If user references a parent folder by name (e.g., 'create meeting note in Projects folder') and there are multiple folders with that name, ALWAYS use resolve_note_id first to find the exact parent note ID and let user choose the correct location. ONLY use this tool when the user explicitly requests note creation (e.g., 'create a note', 'make a new note'). DO NOT use this tool proactively or when the user is only asking questions about their notes. TIP: For code notes, content is plain text (no HTML processing).",
             inputSchema: {
                 type: "object",
                 properties: {
                     parentNoteId: {
                         type: "string",
-                        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",
+                        description: "ID of the parent note. ⚠️ CRITICAL: If you have multiple folders/notes with identical names (e.g., multiple 'Projects' folders, multiple 'Grid View' notes), you MUST use the exact note ID - do NOT guess or auto-select! When multiple potential parents exist, the system will detect conflicts and ask you to choose the specific parent note ID.\n\n🔍 **FINDING PARENT NOTE ID**: Use resolve_note_id to find the exact note ID when you only know the folder name. Example: resolve_note_id({noteName: 'Projects'}) will return the note ID and show alternatives if multiple matches exist.\n\n📋 **PARENT NOTE 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\n\n⚠️ **MULTIPLE PARENTS WITH SAME NAME**: When users say 'put note under Projects folder' but there are multiple 'Projects' folders, ALWAYS use resolve_note_id first to let users choose the correct parent, then use the returned note ID for parentNoteId.",
                         default: "root"
                     },
                     title: {
@@ -74,7 +74,7 @@ export function createWriteTools() {
         },
         {
             name: "update_note",
-            description: "Update note with support for title-only updates, content overwrite, or content append. ⚠️ REQUIRED: ALWAYS call get_note first to obtain current hash. MODE SELECTION: Use 'append' when user wants to add/insert content (e.g., 'append to note', 'add to the end', 'insert content', 'add more content', 'continue writing', 'add to bottom'). Use 'overwrite' when replacing entire content (e.g., 'replace content', 'overwrite note', 'update the whole note', 'completely replace'). TITLE-ONLY: Efficient title changes without content modification. PREVENTS: Overwriting changes made by other users (hash mismatch) or content type violations. ONLY use when user explicitly requests note update. WORKFLOW: get_note → review content → update_note with returned hash",
+            description: "Update note with support for title-only updates, content operations, note type changes, and MIME type updates. ⚠️ REQUIRED: ALWAYS call get_note first to obtain current hash and validate current note type. MODE SELECTION: Use 'append' when adding content, 'overwrite' when replacing content, or title-only for efficient title changes. TYPE CHANGES: Convert between note types (e.g., 'text' to 'code') with automatic validation for template compatibility and content requirements. MIME UPDATES: Change content type for code notes (e.g., JavaScript to Python). PREVENTS: Overwriting changes made by other users (hash mismatch) or invalid type conversions. WORKFLOW: get_note → review current state → update_note with hash",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -84,16 +84,16 @@ export function createWriteTools() {
                     },
                     title: {
                         type: "string",
-                        description: "New title for the note. If provided alone (without content), performs efficient title-only update without affecting note content or blobId."
+                        description: "New title for the note. If provided alone (without content, type, or mime), performs efficient title-only update without affecting note content or blobId."
                     },
                     type: {
                         type: "string",
                         enum: ["text", "code", "render", "search", "relationMap", "book", "noteMap", "mermaid", "webView"],
-                        description: "Type of note (aligned with TriliumNext ETAPI specification). This determines content validation requirements. Required when updating content, optional for title-only updates."
+                        description: "NEW: Change note type with validation (e.g., convert 'text' to 'code' note). ⚠️ IMPORTANT: Type changes are validated for template compatibility - notes with ~template='Board' must remain type='book', ~template='Calendar' must remain type='book', etc. Content compatibility is also validated (e.g., HTML content may not be suitable for code notes). Use this when converting between different note formats (e.g., changing a text note to a code note for better syntax highlighting, or converting a generic note to a Mermaid diagram). Optional - omit if not changing note type."
                     },
                     mime: {
                         type: "string",
-                        description: "MIME type for code/file/image notes. Helps with syntax highlighting and content type identification."
+                        description: "NEW: Update MIME type for code notes (e.g., change 'text/javascript' to 'text/x-python'). Only valid for code-type notes. Use this when switching programming languages or content types. Optional - omit if not changing MIME type."
                     },
                     content: {
                         type: "string",
@@ -354,7 +354,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. ⚠️ 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.",
+            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.\n\n🛡️ VALIDATION: Create operations automatically check for existing attributes to prevent duplicates. If an attribute already exists, you'll receive detailed error messages with guidance on using 'update' instead. Batch operations skip duplicates and continue processing valid attributes.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -365,7 +365,7 @@ export function createWriteAttributeTools() {
                     operation: {
                         type: "string",
                         enum: ["create", "update", "delete", "batch_create"],
-                        description: "Operation type: 'create' (new attribute), 'update' (modify existing - limited to label value/position and relation position only), 'delete' (remove attribute), 'batch_create' (multiple new attributes efficiently)"
+                        description: "Operation type: 'create' (new attribute - validates against existing attributes to prevent duplicates), 'update' (modify existing - limited to label value/position and relation position only), 'delete' (remove attribute), 'batch_create' (multiple new attributes efficiently - skips duplicates and continues with valid attributes)"
                     },
                     attributes: {
                         type: "array",

package/build/utils/attributeNameCleaner.js

@@ -0,0 +1,115 @@
+/**
+ * Attribute Name Cleaner Utility
+ * Auto-corrects common LLM mistakes in attribute names by removing
+ * leading/trailing # and ~ symbols that don't belong in attribute names.
+ */
+import { logVerbose } from './verboseUtils.js';
+/**
+ * Clean attribute name by removing invalid leading/trailing symbols
+ *
+ * Trilium ETAPI requires attribute names to be clean without # or ~ symbols.
+ * LLMs often mistakenly add these symbols to attribute names.
+ *
+ * @param attributeName The attribute name to clean
+ * @param attributeType The type of attribute (label or relation)
+ * @returns CleaningResult with details about any corrections made
+ */
+export function cleanAttributeName(attributeName, attributeType) {
+    const originalName = attributeName;
+    const corrections = [];
+    if (!attributeName || typeof attributeName !== 'string') {
+        return {
+            cleanedName: attributeName,
+            wasCleaned: false,
+            originalName,
+            corrections: []
+        };
+    }
+    let cleanedName = attributeName.trim();
+    // Remove leading # symbol (common LLM mistake for labels)
+    if (attributeType === 'label' && cleanedName.startsWith('#')) {
+        cleanedName = cleanedName.substring(1).trim();
+        corrections.push(`Removed leading '#' symbol`);
+    }
+    // Remove leading ~ symbol (common LLM mistake for relations)
+    if (attributeType === 'relation' && cleanedName.startsWith('~')) {
+        cleanedName = cleanedName.substring(1).trim();
+        corrections.push(`Removed leading '~' symbol`);
+    }
+    const wasCleaned = corrections.length > 0;
+    // Log corrections if any were made
+    if (wasCleaned) {
+        logVerbose('cleanAttributeName', `Auto-corrected ${attributeType} name`, {
+            original: originalName,
+            corrected: cleanedName,
+            corrections,
+            attributeType
+        });
+    }
+    return {
+        cleanedName,
+        wasCleaned,
+        originalName,
+        corrections
+    };
+}
+/**
+ * Clean an array of attributes
+ *
+ * @param attributes Array of attributes to clean
+ * @returns Array of cleaned attributes with cleaning information
+ */
+export function cleanAttributeNames(attributes) {
+    return attributes.map(attribute => {
+        const cleaningResult = cleanAttributeName(attribute.name, attribute.type);
+        return {
+            ...attribute,
+            name: cleaningResult.cleanedName,
+            cleaningResult: cleaningResult.wasCleaned ? cleaningResult : undefined
+        };
+    });
+}
+/**
+ * Generate user-friendly message about corrections
+ *
+ * @param cleaningResults Array of cleaning results
+ * @returns User-friendly message describing corrections
+ */
+export function generateCleaningMessage(cleaningResults) {
+    const totalCorrections = cleaningResults.filter(r => r.wasCleaned).length;
+    if (totalCorrections === 0) {
+        return '';
+    }
+    const correctionsByType = cleaningResults.reduce((acc, result) => {
+        if (result.wasCleaned) {
+            result.corrections.forEach(correction => {
+                acc[correction] = (acc[correction] || 0) + 1;
+            });
+        }
+        return acc;
+    }, {});
+    const correctionSummary = Object.entries(correctionsByType)
+        .map(([correction, count]) => `${count}× ${correction}`)
+        .join(', ');
+    return `🔧 **Auto-Corrections Applied**\n` +
+        `Fixed ${totalCorrections} attribute name(s): ${correctionSummary}\n\n` +
+        `💡 **Common LLM Mistakes Fixed**:\n` +
+        `• Attribute names should NOT start with # or ~ symbols\n` +
+        `• # symbols are for attribute values in search queries (e.g., #book)\n` +
+        `• ~ symbols are for attribute values in search queries (e.g., ~template)\n` +
+        `• Attribute names should be plain text (e.g., "startDate", "template")`;
+}
+/**
+ * Check if an attribute name needs cleaning
+ *
+ * @param attributeName The attribute name to check
+ * @returns True if the name needs cleaning
+ */
+export function needsCleaning(attributeName, attributeType = 'label') {
+    if (!attributeName || typeof attributeName !== 'string') {
+        return false;
+    }
+    const trimmed = attributeName.trim();
+    return (attributeType === 'label' && trimmed.startsWith('#')) ||
+        (attributeType === 'relation' && trimmed.startsWith('~'));
+}

package/package.json

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