triliumnext-mcp 0.3.10-beta.2 → 0.3.11

package/build/index.js

@@ -9,6 +9,7 @@ import { handleCreateNoteRequest, handleUpdateNoteRequest, handleDeleteNoteReque
 import { handleSearchNotesRequest } from "./modules/searchHandler.js";
 import { handleResolveNoteRequest } from "./modules/resolveHandler.js";
 import { handleManageAttributes, handleReadAttributes } from "./modules/attributeHandler.js";
+import { handleListAttributesRequest } from "./modules/attributeListHandler.js";
 const TRILIUM_API_URL = process.env.TRILIUM_API_URL;
 const TRILIUM_API_TOKEN = process.env.TRILIUM_API_TOKEN;
 const PERMISSIONS = process.env.PERMISSIONS || "READ;WRITE";
@@ -77,6 +78,8 @@ class TriliumServer {
                         return await handleReadAttributes(request.params.arguments, this.axiosInstance, this);
                     case "manage_attributes":
                         return await handleManageAttributes(request.params.arguments, this.axiosInstance, this);
+                    case "list_attributes":
+                        return await handleListAttributesRequest(request.params.arguments, this.axiosInstance, this);
                     default:
                         throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${request.params.name}`);
                 }

package/build/modules/attributeListHandler.js

@@ -0,0 +1,34 @@
+/**
+ * Attribute List Handler Module
+ * Centralized request handling for attribute listing operations
+ */
+import { McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+import { handleListAttributes } from "./attributeListManager.js";
+/**
+ * Handle list_attributes tool requests
+ */
+export async function handleListAttributesRequest(args, axiosInstance, permissionChecker) {
+    if (!permissionChecker.hasPermission("READ")) {
+        throw new McpError(ErrorCode.InvalidRequest, "Permission denied: Not authorized to list attributes.");
+    }
+    try {
+        const listOperation = {
+            noteId: args.noteId,
+            hierarchyLevel: args.hierarchyLevel || 'immediate',
+            limit: args.limit || 50
+        };
+        const result = await handleListAttributes(listOperation, axiosInstance);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify(result, null, 2)
+                }]
+        };
+    }
+    catch (error) {
+        if (error instanceof McpError) {
+            throw error;
+        }
+        throw new McpError(ErrorCode.InvalidParams, error instanceof Error ? error.message : String(error));
+    }
+}

package/build/modules/attributeListManager.js

@@ -0,0 +1,147 @@
+/**
+ * Attribute List Management Module
+ * Handles attribute listing operations using search_notes internally
+ */
+import { handleSearchNotes } from './searchManager.js';
+import { logVerboseInput, logVerboseOutput } from '../utils/verboseUtils.js';
+/**
+ * Handle list attributes operation using search_notes internally
+ */
+export async function handleListAttributes(args, axiosInstance) {
+    logVerboseInput('handleListAttributes', args);
+    // Build search criteria based on hierarchy navigation
+    const searchCriteria = buildHierarchySearchCriteria(args);
+    // Use search_notes internally to find notes
+    const searchOperation = {
+        searchCriteria: searchCriteria,
+        limit: args.limit || 100
+    };
+    const searchResults = await handleSearchNotes(searchOperation, axiosInstance);
+    // Extract and organize attributes from search results
+    const attributes = extractAttributesFromResults(searchResults.results, args);
+    // Generate summary
+    const summary = generateAttributeSummary(attributes, args);
+    const result = {
+        attributes: attributes,
+        summary: summary
+    };
+    logVerboseOutput('handleListAttributes', result);
+    return result;
+}
+/**
+ * Build search criteria for hierarchy navigation
+ */
+function buildHierarchySearchCriteria(args) {
+    const criteria = [];
+    const hierarchyLevel = args.hierarchyLevel || 'immediate';
+    if (hierarchyLevel === 'immediate') {
+        // For immediate level, search for direct parents and children
+        criteria.push({
+            property: 'parents.noteId',
+            type: 'noteProperty',
+            op: '=',
+            value: args.noteId
+        });
+        criteria.push({
+            property: 'children.noteId',
+            type: 'noteProperty',
+            op: '=',
+            value: args.noteId,
+            logic: 'OR'
+        });
+    }
+    else {
+        // For all levels, search for ancestors and descendants
+        criteria.push({
+            property: 'ancestors.noteId',
+            type: 'noteProperty',
+            op: '=',
+            value: args.noteId
+        });
+        criteria.push({
+            property: 'descendants.noteId',
+            type: 'noteProperty',
+            op: '=',
+            value: args.noteId,
+            logic: 'OR'
+        });
+    }
+    // Exclude the anchor note itself
+    criteria.push({
+        property: 'noteId',
+        type: 'noteProperty',
+        op: '!=',
+        value: args.noteId,
+        logic: 'AND'
+    });
+    return criteria;
+}
+/**
+ * Extract and organize attributes from search results
+ */
+function extractAttributesFromResults(searchResults, args) {
+    const attributes = [];
+    for (const note of searchResults) {
+        if (note.attributes && Array.isArray(note.attributes)) {
+            for (const attribute of note.attributes) {
+                const attributeInfo = {
+                    noteId: note.noteId,
+                    noteTitle: note.title,
+                    noteType: note.type,
+                    attributeId: attribute.attributeId,
+                    attributeType: attribute.type,
+                    attributeName: attribute.name,
+                    attributeValue: attribute.value || '',
+                    position: attribute.position || 10,
+                    isInheritable: attribute.isInheritable || false,
+                    hierarchyPath: buildHierarchyPath(note, args)
+                };
+                attributes.push(attributeInfo);
+            }
+        }
+    }
+    return attributes;
+}
+/**
+ * Build hierarchy path for attribute context
+ */
+function buildHierarchyPath(note, args) {
+    const hierarchyLevel = args.hierarchyLevel || 'immediate';
+    const noteTitle = note.title || 'Unknown';
+    if (hierarchyLevel === 'immediate') {
+        return `Related to ${args.noteId}: ${noteTitle}`;
+    }
+    else {
+        return `Hierarchy-connected to ${args.noteId}: ${noteTitle}`;
+    }
+}
+/**
+ * Generate summary of attributes found
+ */
+function generateAttributeSummary(attributes, args) {
+    const totalAttributes = attributes.length;
+    if (totalAttributes === 0) {
+        return `No attributes found`;
+    }
+    // Group by attribute type
+    const labelCount = attributes.filter(attr => attr.attributeType === 'label').length;
+    const relationCount = attributes.filter(attr => attr.attributeType === 'relation').length;
+    // Group by note
+    const uniqueNotes = new Set(attributes.map(attr => attr.noteId)).size;
+    let summary = `Found ${totalAttributes} attributes across ${uniqueNotes} notes`;
+    if (labelCount > 0 || relationCount > 0) {
+        summary += ` (${labelCount} labels, ${relationCount} relations)`;
+    }
+    // Add hierarchy context
+    const hierarchyLevel = args.hierarchyLevel || 'immediate';
+    if (hierarchyLevel === 'immediate') {
+        summary += ` in immediate hierarchy (parents and children)`;
+    }
+    else {
+        summary += ` in full hierarchy (ancestors and descendants)`;
+    }
+    // Add unique attribute names count
+    const uniqueAttributeNames = new Set(attributes.map(attr => attr.attributeName)).size;
+    summary += ` with ${uniqueAttributeNames} unique attribute types`;
+    return summary;
+}

package/build/modules/noteManager.js

@@ -129,35 +129,52 @@ async function checkDuplicateTitleInDirectory(parentNoteId, title, axiosInstance
  * Handle create note operation
  */
 export async function handleCreateNote(args, axiosInstance) {
-    const { parentNoteId, title, type, content: rawContent, mime, attributes, forceCreate = false } = args;
+    const { parentNoteId, title, type, content: rawContent, mime, attributes } = args;
     // Validate required parameters
     if (!parentNoteId || !title || !type) {
         throw new Error("parentNoteId, title, and type are required for create operation.");
     }
-    // Check for duplicate title in the same directory (unless forceCreate is true)
-    if (!forceCreate) {
-        const duplicateCheck = await checkDuplicateTitleInDirectory(parentNoteId, title, axiosInstance);
-        if (duplicateCheck.found) {
-            return {
-                message: `Found existing note with title "${title}" in this directory. Please choose how to proceed:`,
-                duplicateFound: true,
-                duplicateNoteId: duplicateCheck.duplicateNoteId,
-                choices: {
-                    skip: "Skip creation - do nothing",
-                    createAnyway: "Create anyway - create duplicate note with same title (set forceCreate: true)",
-                    updateExisting: "Update existing - replace content of existing note with new content"
-                },
-                nextSteps: `Please specify your choice by calling create_note again with your preferred action. To update the existing note, use update_note with noteId: ${duplicateCheck.duplicateNoteId}`
-            };
-        }
+    // Check for duplicate title in the same directory
+    const duplicateCheck = await checkDuplicateTitleInDirectory(parentNoteId, title, axiosInstance);
+    if (duplicateCheck.found) {
+        return {
+            message: `Found existing note with title "${title}" in this directory. Please choose how to proceed:`,
+            duplicateFound: true,
+            duplicateNoteId: duplicateCheck.duplicateNoteId,
+            choices: {
+                skip: "Skip creation - do nothing",
+                updateExisting: "Update existing - replace content of existing note with new content"
+            },
+            nextSteps: `Please specify your choice by calling create_note again with a different title, or use update_note with noteId: ${duplicateCheck.duplicateNoteId}`
+        };
     }
     // Process content to ETAPI format
     // Content is optional - if not provided, default to empty string
     const content = rawContent || "";
     // Extract template relation for content validation
     const templateRelation = extractTemplateRelation(attributes);
+    // Clean template relation for consistent processing
+    const cleanedTemplateRelation = templateRelation ? templateRelation.trim() : '';
+    // Auto-correct note type for container templates
+    let correctedType = type;
+    if (templateRelation) {
+        // List of container templates that 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 = cleanedTemplateRelation &&
+            containerTemplates.includes(cleanedTemplateRelation.toLowerCase());
+        if (isContainerTemplate && type !== 'book') {
+            logVerbose("handleCreateNote", `Auto-correcting note type from '${type}' to 'book' for ${templateRelation} template`);
+            correctedType = 'book';
+        }
+    }
     // Validate content with template-aware rules
-    const contentValidation = await validateContentForNoteType(content, type, undefined, templateRelation);
+    const contentValidation = await validateContentForNoteType(content, correctedType, undefined, templateRelation);
     if (!contentValidation.valid) {
         return {
             message: `CONTENT_VALIDATION_ERROR: ${contentValidation.error}`,
@@ -168,7 +185,7 @@ export async function handleCreateNote(args, axiosInstance) {
     // Use validated content (may have been auto-corrected)
     const validatedContent = contentValidation.content;
     // Process content to ETAPI format
-    const processed = await processContentArray(validatedContent, type);
+    const processed = await processContentArray(validatedContent, correctedType);
     if (processed.error) {
         throw new Error(`Content processing error: ${processed.error}`);
     }
@@ -177,7 +194,7 @@ export async function handleCreateNote(args, axiosInstance) {
     const noteData = {
         parentNoteId,
         title,
-        type,
+        type: correctedType,
         content: processedContent
     };
     // Add MIME type if specified

package/build/modules/searchManager.js

@@ -5,6 +5,55 @@
 import { buildSearchQuery } from "./searchQueryBuilder.js";
 import { trimNoteResults } from "../utils/noteFormatter.js";
 import { createSearchDebugInfo } from "../utils/verboseUtils.js";
+/**
+ * Filters out parent notes from search results when performing hierarchy searches
+ * This prevents the parent folder itself from appearing in results when searching for its children/descendants
+ *
+ * @param searchResults - The raw search results from Trilium API
+ * @param searchArgs - The original search arguments used to detect hierarchy searches
+ * @returns Filtered search results with parent notes excluded
+ */
+function filterParentNotes(searchResults, searchArgs) {
+    // If no search criteria, return results as-is (no filtering needed)
+    if (!searchArgs.searchCriteria || !Array.isArray(searchArgs.searchCriteria)) {
+        return searchResults;
+    }
+    // Check if any search criteria involves hierarchy navigation (parents, children, ancestors)
+    const hasHierarchySearch = searchArgs.searchCriteria.some(criteria => {
+        if (criteria.type !== 'noteProperty')
+            return false;
+        const property = criteria.property;
+        return property.startsWith('parents.') ||
+            property.startsWith('children.') ||
+            property.startsWith('ancestors.');
+    });
+    // If no hierarchy search, return results as-is
+    if (!hasHierarchySearch) {
+        return searchResults;
+    }
+    // Extract target note IDs from hierarchy search criteria
+    const targetNoteIds = new Set();
+    searchArgs.searchCriteria.forEach(criteria => {
+        if (criteria.type === 'noteProperty' && criteria.value) {
+            const property = criteria.property;
+            // Handle different hierarchy property patterns
+            if (property.endsWith('.noteId') && criteria.op === '=') {
+                targetNoteIds.add(criteria.value);
+            }
+            // For other hierarchy properties, we might need to resolve note IDs from titles
+            // This is a simplified approach - in practice, you'd need to resolve titles to IDs
+        }
+    });
+    // If no target note IDs found, return results as-is
+    if (targetNoteIds.size === 0) {
+        return searchResults;
+    }
+    // Filter out notes that match the target note IDs (these are the parents we want to exclude)
+    const filteredResults = searchResults.filter(note => {
+        return !targetNoteIds.has(note.noteId);
+    });
+    return filteredResults;
+}
 /**
  * Handle search notes operation
  */
@@ -26,7 +75,10 @@ export async function handleSearchNotes(args, axiosInstance) {
     // Prepare verbose debug info if enabled
     const verboseInfo = createSearchDebugInfo(query, args);
     let searchResults = response.data.results || [];
-    const trimmedResults = trimNoteResults(searchResults);
+    // Apply parent filtering for hierarchy searches to exclude parent notes from results
+    // This implements the documented behavior: "Parent note filtering automatically applied to avoid showing parent in children/descendant lists"
+    const filteredResults = filterParentNotes(searchResults, args);
+    const trimmedResults = trimNoteResults(filteredResults);
     return {
         results: trimmedResults,
         debugInfo: verboseInfo

package/build/modules/toolDefinitions.js

@@ -9,7 +9,7 @@ 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, create anyway (with forceCreate: true), 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. 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: {
@@ -29,7 +29,7 @@ export function createWriteTools() {
                     },
                     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, 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"
+                        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. ⚠️ 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",
+                        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 book note type with empty content - add content as child notes",
                         items: {
                             type: "object",
                             properties: {
@@ -68,11 +68,6 @@ export function createWriteTools() {
                             required: ["type", "name"]
                         }
                     },
-                    forceCreate: {
-                        type: "boolean",
-                        description: "Bypass duplicate title check and create note even if a note with the same title already exists in the same directory. Use this when you want to intentionally create duplicate notes.",
-                        default: false
-                    },
                 },
                 required: ["parentNoteId", "title", "type"],
             },
@@ -187,7 +182,7 @@ export function createReadTools() {
     return [
         {
             name: "get_note",
-            description: "Get a note and its content by ID. Perfect for when someone wants to see what's in a note, extract specific information, or prepare for search and replace operations. Getting the full content lets you see the context and create better regex patterns for extraction or replacement.",
+            description: "Get a note and its content by ID. Perfect for when someone wants to see what's in a note, extract specific information, or prepare for search and replace operations. Getting the full content lets you see the context and extract information accurately. For extracting information from multiple notes: use search_notes to find relevant notes, then use get_note (with useRegex=false for LLM analysis, or useRegex=true for simple pattern matching).",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -197,16 +192,16 @@ export function createReadTools() {
                     },
                     searchPattern: {
                         type: "string",
-                        description: "Optional pattern to search for within the note. Use when you need to find specific text or extract information.",
+                        description: "Optional pattern to search for within the note. ⚠️ IMPORTANT: When users request to extract specific types of information (URLs, emails, dates, code snippets, etc.), automatically generate appropriate regex patterns based on the extraction request. Use useRegex=true for pattern matching and searchFlags='gi' for comprehensive results.",
                     },
                     useRegex: {
                         type: "boolean",
-                        description: "Whether to use regex patterns (default: true).",
-                        default: true
+                        description: "Whether to use regex patterns for searchPattern. Set to true for simple pattern matching, or false to let LLM read and analyze full content for more accurate extraction (recommended for complex cases like URLs, emails with context).",
+                        default: false
                     },
                     searchFlags: {
                         type: "string",
-                        description: "Search options. Defaults to 'gi' (find all matches, case-insensitive).",
+                        description: "Search options. Defaults to 'gi' (find all matches, case-insensitive). Use 'gi' for comprehensive extraction of all patterns.",
                         default: "gi"
                     },
                 },
@@ -322,6 +317,33 @@ export function createReadAttributeTools() {
                 },
                 required: ["noteId"]
             }
+        },
+        {
+            name: "list_attributes",
+            description: "List attributes from note hierarchy using search_notes internally. Explore attributes across immediate hierarchy (parents and children) or full hierarchy (ancestors and descendants). Returns comprehensive attribute information including note context, attribute details, and hierarchy relationships. Perfect for understanding template usage, label patterns, and relation networks across your note structure.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    noteId: {
+                        type: "string",
+                        description: "Anchor note ID for hierarchy navigation"
+                    },
+                    hierarchyLevel: {
+                        type: "string",
+                        enum: ["immediate", "all"],
+                        description: "Hierarchy navigation depth: 'immediate' (direct parents and children only) or 'all' (include ancestors and descendants)",
+                        default: "immediate"
+                    },
+                    limit: {
+                        type: "number",
+                        description: "Maximum number of results to return",
+                        default: 50,
+                        minimum: 1,
+                        maximum: 200
+                    }
+                },
+                required: ["noteId"]
+            }
         }
     ];
 }

package/build/utils/contentRules.js

@@ -206,8 +206,16 @@ export async function validateContentForNoteType(content, noteType, currentConte
     const textContent = content.trim();
     // Get template-aware content rules
     const rules = getTemplateContentRules(noteType, templateRelation);
-    // Check if content is allowed at all
-    if (!rules.allowContent) {
+    // Special handling for container templates: empty content is always valid
+    if (!textContent && rules.enforceEmpty) {
+        return {
+            valid: true,
+            content: "",
+            corrected: false
+        };
+    }
+    // Check if content is allowed at all (only for non-empty content)
+    if (!rules.allowContent && textContent) {
         return {
             valid: false,
             content,

package/package.json

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