search_notes

Instructions

Implementation Reference

• src/modules/searchHandler.ts:17-48 (handler)

  Entry point handler for search_notes tool: permission check, parameter mapping, core logic delegation, and MCP response formatting.

  export async function handleSearchNotesRequest(
    args: any,
    axiosInstance: any,
    permissionChecker: PermissionChecker
  ): Promise<{ content: Array<{ type: string; text: string }> }> {
    if (!permissionChecker.hasPermission("READ")) {
      throw new McpError(ErrorCode.InvalidRequest, "Permission denied: Not authorized to search notes.");
    }
  
    try {
      const searchOperation: SearchOperation = {
        text: args.text,
        searchCriteria: args.searchCriteria,
        limit: args.limit
      };
  
      const result = await handleSearchNotes(searchOperation, axiosInstance);
      const resultsText = JSON.stringify(result.results, null, 2);
  
      return {
        content: [{
          type: "text",
          text: `${result.debugInfo || ''}${resultsText}`
        }]
      };
    } catch (error) {
      if (error instanceof McpError) {
        throw error;
      }
      throw new McpError(ErrorCode.InvalidParams, error instanceof Error ? error.message : String(error));
    }
  }

• src/modules/searchManager.ts:27-62 (handler)

  Core implementation executing the TriliumNext search API call with dynamic query building, smart fastSearch optimization, result trimming, and debug information.

  export async function handleSearchNotes(
    args: SearchOperation,
    axiosInstance: any
  ): Promise<SearchResponse> {
    // Build query from structured parameters
    const query = buildSearchQuery(args);
    
    if (!query.trim()) {
      throw new Error("At least one search parameter must be provided");
    }
  
    const params = new URLSearchParams();
    params.append("search", query);
    
    // Smart fastSearch logic: use fastSearch=true ONLY when ONLY text parameter is provided (no other parameters)
    const hasOnlyText = args.text &&
      (!args.searchCriteria || !Array.isArray(args.searchCriteria) || args.searchCriteria.length === 0) &&
      !args.limit; // fastSearch doesn't support limit clauses
    
    params.append("fastSearch", hasOnlyText ? "true" : "false");
    params.append("includeArchivedNotes", "true"); // Always include archived notes
  
    const response = await axiosInstance.get(`/notes?${params.toString()}`);
    
    // Prepare verbose debug info if enabled
    const verboseInfo = createSearchDebugInfo(query, args);
    
    let searchResults = response.data.results || [];
  
    const trimmedResults = trimNoteResults(searchResults);
    
    return {
      results: trimmedResults,
      debugInfo: verboseInfo
    };
  }

• src/index.ts:109-110 (registration)

  Tool registration in the MCP CallToolRequestHandler switch statement dispatching to the handler function.

  case "search_notes":
    return await handleSearchNotesRequest(request.params.arguments, this.axiosInstance, this);

• src/modules/toolDefinitions.ts:261-321 (schema)

  MCP tool schema definition for 'search_notes' including detailed inputSchema with properties for text search, advanced searchCriteria array, and result limit.

      {
        name: "search_notes",
        description: "Unified search with comprehensive filtering capabilities including keyword search, date ranges, field-specific searches, attribute searches, note properties, template-based searches, note type filtering, MIME type filtering, and hierarchy navigation through unified searchCriteria structure. For simple keyword searches, use the 'text' parameter. For complex boolean logic like 'docker OR kubernetes', use searchCriteria with proper OR logic. For template search: use relation type with 'template.title' property and built-in template values like 'Calendar', 'Board', 'Text Snippet', 'Grid View', 'List View', 'Table', 'Geo Map'. For note type search: use noteProperty type with 'type' property and values from the 9 supported ETAPI types: 'text', 'code', 'render', 'search', 'relationMap', 'book', 'noteMap', 'mermaid', 'webView'. For MIME type search: use noteProperty type with 'mime' property and MIME values like 'text/javascript', 'text/x-python', 'text/vnd.mermaid', 'application/json'. Use hierarchy properties like 'parents.noteId', 'children.noteId', or 'ancestors.noteId' for navigation.",
        inputSchema: {
          type: "object",
          properties: searchProperties,
        },
      }
    ];
  }
  
  /**
   * Create shared search properties for reuse across search tools
   */
  function createSearchProperties() {
    return {
      text: {
        type: "string",
        description: "SIMPLE keyword search ONLY - single terms or exact phrases. Examples: 'kubernetes' (finds notes containing 'kubernetes'), 'machine learning' (finds notes containing both 'machine' AND 'learning' together), '\"docker kubernetes\"' (finds notes containing the exact phrase 'docker kubernetes'). ⚠️ WARNING: This parameter does NOT support boolean operators like OR, AND, NOT. If you use 'docker OR kubernetes', it will search for the literal text 'docker OR kubernetes' and return no results. For any boolean logic (OR, AND, NOT), you MUST use searchCriteria parameter instead.",
      },
      searchCriteria: {
        type: "array",
        description: "Unified search criteria array that supports all search types with complete boolean logic. Enables cross-type OR operations (e.g., 'relation OR dateCreated' searches). Supports labels, relations, note properties (including hierarchy navigation: parents.title, children.title, ancestors.title), note type filtering, MIME type filtering, and keyword searches. For keyword searches: use noteProperty type with 'title' or 'content' properties. Operators include existence checks (exists, not_exists), comparisons (=, !=, >=, <=, >, <), and text matching (contains, starts_with, ends_with, regex). Use OR logic between items for 'either/or' searches across ANY criteria types. Examples: Find mermaid diagrams by setting type property to 'mermaid'. Find JavaScript code by combining type 'code' with mime 'text/javascript'. Find mermaid notes by using OR logic between type criteria. Logic parameter connects current item to next item.",
        items: {
          type: "object",
          properties: {
            property: {
              type: "string",
              description: "Property name. For labels: tag name (e.g., 'book', 'author'). For relations: relation name with optional property path (e.g., 'author', 'author.title', 'template.title'). Built-in templates: use 'template.title' with values 'Calendar', 'Board', 'Text Snippet', 'Grid View', 'List View', 'Table', 'Geo Map'. For note properties: system property name (e.g., 'isArchived', 'type', 'mime', 'title', 'content', 'dateCreated') OR hierarchy properties (e.g., 'parents.title', 'children.title', 'ancestors.title', 'parents.parents.title')."
            },
            type: {
              type: "string",
              enum: ["label", "relation", "noteProperty"],
              description: "Type of search criteria: 'label' for #tags, 'relation' for ~relations, 'noteProperty' for note.* system properties and hierarchy navigation"
            },
            op: {
              type: "string",
              enum: ["exists", "not_exists", "=", "!=", ">=", "<=", ">", "<", "contains", "starts_with", "ends_with", "regex"],
              description: "Search operator for property matching and comparison. Use 'exists' to find notes with a property, 'not_exists' to find notes without the property at all, '=' for exact matches, '!=' to find notes that have the property but excluding specific values, '>=' and '<=' for ranges, and text operators like 'contains' for partial matches.",
              default: "exists"
            },
            value: {
              type: "string",
              description: "Value to compare against (optional for exists operator). For built-in template relations: use 'Calendar' (calendar notes), 'Board' (task boards), 'Text Snippet' (text snippets), 'Grid View' (grid layouts), 'List View' (list layouts), 'Table' (table views), 'Geo Map' (geography maps). For note type property: use ETAPI-aligned note types: 'text' (rich text), 'code' (code with syntax highlighting), 'render' (rendered content), 'search' (saved searches), 'relationMap' (relation maps), 'book' (folders/containers), 'noteMap' (note relationship maps), 'mermaid' (Mermaid diagrams), 'webView' (web content embedding). For note MIME property: use MIME types like 'text/javascript', 'text/x-python', 'text/x-java', 'text/css', 'text/html', 'text/x-typescript', 'text/x-sql', 'text/x-yaml', 'text/x-markdown', 'text/vnd.mermaid', 'application/json'. For noteProperty dates (dateCreated, dateModified): MUST use ISO date format - 'YYYY-MM-DDTHH:mm:ss.sssZ'. For hierarchy navigation: parent/ancestor note title or 'root' for top-level."
            },
            logic: {
              type: "string",
              enum: ["AND", "OR"],
              description: "Logic operator connecting this item to the NEXT item in the array. Think sequentially: each item's logic determines how it combines with the following item. For 'A OR B AND C' expressions, use OR on first item, AND on second item. For simple 'A OR B' use OR on first item only. Default AND creates standard conjunctions. System ignores logic on the final array item.",
              default: "AND"
            }
          },
          required: ["property", "type", "logic"]
        }
      },
      limit: {
        type: "number",
        description: "Maximum number of results to return",
      },
    };
  }