triliumnext-mcp 0.3.12 → 0.3.14

package/README.md

@@ -1,150 +1,197 @@
-# TriliumNext Notes' MCP Server
-
-⚠️ **DISCLAIMER: This is a prototype for https://github.com/TriliumNext/Notes/issues/705. Suggested only for developer use. Please backup your Trilium notes before using this tool.** ⚠️
-
-A model context protocol server for TriliumNext Notes. This server provides tools to interact with your Trilium Notes instance through MCP.
-
-## Quick Start
-
-Make sure to set up your environment variables first:
-- `TRILIUM_API_URL` (default: http://localhost:8080/etapi)
-- `TRILIUM_API_TOKEN` (required, get this from your Trilium Notes settings)
-- `PERMISSIONS` (optional, default='READ;WRITE', where READ grants access to `search_notes`, `get_note`, `resolve_note_id`, and `read_attributes`, and WRITE grants access to `create_note`, `update_note`, `delete_note`, and `manage_attributes`)
-- `VERBOSE` (optional, default='false', which if true will print verbose debugging logs)
-
-## Installation
-
-### 1. Using with Claude Desktop
-
-Add the server config to your Claude Desktop configuration file:
-
-#### For Local Installation (on Windows)
-
-```json
-"triliumnext-mcp": {
-  "command": "cmd",
-  "args": [
-        "/k",
-        "npx",
-        "-y",
-        "triliumnext-mcp"
-      ],
-   "env": {
-    "TRILIUM_API_URL": "http://localhost:8080/etapi",
-    "TRILIUM_API_TOKEN": "<YOUR_TRILIUM_API_TOKEN>",
-    "PERMISSIONS": "READ;WRITE"
-  }
-}
-```
-
-#### For Local installation (on Linux)
-
-```json
-"triliumnext-mcp": {
-  "command": "npx",
-  "args": [
-        "-y",
-        "triliumnext-mcp"
-      ],
-   "env": {
-    "TRILIUM_API_URL": "http://localhost:8080/etapi",
-    "TRILIUM_API_TOKEN": "<YOUR_TRILIUM_API_TOKEN>",
-    "PERMISSIONS": "READ;WRITE"
-  }
-}
-```
-
-#### For Development (on Windows / Linux)
-
-```bash
-cd /path/to/triliumnext-mcp
-npm run build
-```
-
-```json
-"triliumnext-mcp": {
-  "command": "node",
-  "args": [
-        "/path/to/triliumnext-mcp/build/index.js"
-  ],
-  "env": {
-    "TRILIUM_API_URL": "http://localhost:8080/etapi",
-    "TRILIUM_API_TOKEN": "<YOUR_TRILIUM_API_TOKEN>",
-    "PERMISSIONS": "READ;WRITE",
-    "VERBOSE": "true"
-  }
-}
-```
-
-Location of the configuration file:
-- Windows: `%APPDATA%/Claude/claude_desktop_config.json`
-- MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
-
-**Feedback**: Please report issues and test results at [GitHub Issues](https://github.com/TriliumNext/Notes/issues)
-
-## Available Tools
-
-The server provides the following tools for note management:
-
-### Search & Discovery Tools
-
-- `search_notes` - 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.
-- `resolve_note_id` - Find a note's ID by its title. Essential for getting a note's ID to use with other tools.
-
-### Note Management Tools
-
-- `get_note` - Retrieve a note and its content by ID. Can also be used with regex to extract specific patterns from the content.
-- `create_note` - Create a new note. Supports 9 note types and allows creating attributes (labels and relations) in the same step.
-- `update_note` - Updates a note's title or content. Requires a `mode` (`'overwrite'` or `'append'`) to specify the update type and an `expectedHash` to prevent conflicts.
-- `delete_note` - Permanently delete a note (⚠️ cannot be undone).
-
-### Attribute Management Tools
-
-- `read_attributes` - Read all attributes (labels and relations) for a given note.
-- `manage_attributes` - Create, update, or delete attributes on a note. Supports batch creation.
-
-> 📖 **Detailed Usage**: See [Note Management Guide](docs/manage-notes-examples/index.md) for revision control strategy and best practices.
-
-## Example Queries
-
-### Search & Discovery
-- "Find my most recent 10 notes about 'n8n' since the beginning of 2024"
-- "Show me notes I've edited in the last 7 days"
-- "List all notes under 'n8n Template' folder, including subfolders"
-
-### Content Management
-- "Add today's update to my work log" (uses `update_note` with `mode: 'append'`)
-- "Replace this draft with the final version" (uses `update_note` with `mode: 'overwrite'`)
-- "Create a new note called 'Weekly Review' in my journal folder"
-
-> 📖 **More Examples**: See [User Query Examples](docs/user-query-examples.md) for comprehensive usage scenarios.
-
-## Documentation
-
-- [Note Management Guide](docs/manage-notes-examples/index.md) - Safe content editing with revision control
-- [User Query Examples](docs/user-query-examples.md) - Natural language query examples
-- [Search Query Examples](docs/search-examples/) - Advanced search syntax and filters
-
-## Development
-
-If you want to contribute or modify the server:
-
-```bash
-# Clone the repository
-git clone https://github.com/tan-yong-sheng/triliumnext-mcp.git
-
-# Install dependencies
-npm install
-
-# Build the server
-npm run build
-
-# For development with auto-rebuild
-npm run watch
-```
-
-## Contributing
-
-Contributions are welcome! If you are looking to improve the server, please familiarize yourself with the official [Trilium Search DSL documentation](https://triliumnext.github.io/Docs/Wiki/search.html) and our internal [Search Query Examples](docs/search-examples/) to understand how search queries are constructed.
-
+# TriliumNext Notes' MCP Server
+
+⚠️ **DISCLAIMER: This is a prototype for https://github.com/TriliumNext/Notes/issues/705. Suggested only for developer use. Please backup your Trilium notes before using this tool.** ⚠️
+
+A model context protocol server for TriliumNext Notes. This server provides tools to interact with your Trilium Notes instance through MCP.
+
+## Quick Start
+
+Make sure to set up your environment variables first:
+- `TRILIUM_API_URL` (default: http://localhost:8080/etapi)
+- `TRILIUM_API_TOKEN` (required, get this from your Trilium Notes settings)
+- `PERMISSIONS` (optional, default='READ;WRITE', where READ grants access to `search_notes`, `get_note`, `resolve_note_id`, and `read_attributes`, and WRITE grants access to `create_note`, `update_note`, `delete_note`, and `manage_attributes`)
+- `VERBOSE` (optional, default='false', which if true will print verbose debugging logs)
+
+## Installation
+
+
+Below are the installation guide for this MCP on different MCP clients, such as Claude Desktop, Claude Code, Cursor, Cline, etc.
+
+<details>
+<summary>Claude Desktop</summary>
+
+Add to your Claude Desktop configuration:
+
+```json
+{
+  "mcpServers": {
+    "triliumnext-mcp": {
+      "command": "npx",
+      "args": ["triliumnext-mcp"],
+      "env": {
+        "TRILIUM_API_URL": "http://localhost:8080/etapi",
+        "TRILIUM_API_TOKEN": "<YOUR_TRILIUM_API_TOKEN>",
+        "PERMISSIONS": "READ;WRITE"
+      }
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary>Claude Code</summary>
+
+```bash
+claude mcp add triliumnext-mcp \
+  -e TRILIUM_API_URL=http://localhost:8080/etapi \
+  -e TRILIUM_API_TOKEN=<YOUR_TRILIUM_API_TOKEN> \
+  -e PERMISSIONS='READ;WRITE' \
+  -- npx triliumnext-mcp
+```
+
+Note: Increase the MCP startup timeout to 1 minutes and MCP tool execution timeout to about 5 minutes by updating `~\.claude\settings.json` as follows:
+
+```json
+{
+  "env": {
+    "MCP_TIMEOUT": "60000",
+    "MCP_TOOL_TIMEOUT": "300000"
+  }
+}
+```
+
+</details>
+
+<details>
+<summary>Cursor</summary>
+
+Go to: Settings -> Cursor Settings -> MCP -> Add new global MCP server
+
+Pasting the following configuration into your Cursor ~/.cursor/mcp.json file is the recommended approach. You may also install in a specific project by creating .cursor/mcp.json in your project folder. See [Cursor MCP docs](https://docs.cursor.com/context/model-context-protocol) for more info.
+
+```json
+{
+  "mcpServers": {
+    "triliumnext-mcp": {
+      "command": "npx",
+      "args": ["triliumnext-mcp"],
+      "env": {
+        "TRILIUM_API_URL": "http://localhost:8080/etapi",
+        "TRILIUM_API_TOKEN": "<YOUR_TRILIUM_API_TOKEN>",
+        "PERMISSIONS": "READ;WRITE"
+      }
+    }
+  }
+}
+```
+</details>
+
+
+<details>
+<summary>Cline</summary>
+
+Cline uses a JSON configuration file to manage MCP servers. To integrate the provided MCP server configuration:
+
+1. Open Cline and click on the MCP Servers icon in the top navigation bar.
+2. Select the Installed tab, then click Advanced MCP Settings.
+3. In the cline_mcp_settings.json file, add the following configuration:
+
+(i) Using Google AI Studio Provider
+```json
+{
+  "mcpServers": {
+    "timeout": 300, 
+    "type": "stdio",
+    "triliumnext-mcp": {
+      "command": "npx",
+      "args": ["triliumnext-mcp"],
+      "env": {
+        "TRILIUM_API_URL": "http://localhost:8080/etapi",
+        "TRILIUM_API_TOKEN": "<YOUR_TRILIUM_API_TOKEN>",
+        "PERMISSIONS": "READ;WRITE"
+      }
+    }
+  }
+}
+```
+</details>
+
+
+<details>
+
+<summary>Other MCP clients</summary>
+
+The server uses stdio transport and follows the standard MCP protocol. It can be integrated with any MCP-compatible client by running:
+
+```bash
+npx triliumnext-mcp
+```
+</details>
+
+## Available Tools
+
+The server provides the following tools for note management:
+
+### Search & Discovery Tools
+
+- `search_notes` - 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.
+- `resolve_note_id` - Find a note's ID by its title. Essential for getting a note's ID to use with other tools.
+
+### Note Management Tools
+
+- `get_note` - Retrieve a note and its content by ID. Can also be used with regex to extract specific patterns from the content.
+- `create_note` - Create a new note. Supports 9 note types and allows creating attributes (labels and relations) in the same step.
+- `update_note` - Updates a note's title or content. Requires a `mode` (`'overwrite'` or `'append'`) to specify the update type and an `expectedHash` to prevent conflicts.
+- `delete_note` - Permanently delete a note (⚠️ cannot be undone).
+
+### Attribute Management Tools
+
+- `read_attributes` - Read all attributes (labels and relations) for a given note.
+- `manage_attributes` - Create, update, or delete attributes on a note. Supports batch creation.
+
+> 📖 **Detailed Usage**: See [Note Management Guide](docs/manage-notes-examples/index.md) for revision control strategy and best practices.
+
+## Example Queries
+
+### Search & Discovery
+- "Find my most recent 10 notes about 'n8n' since the beginning of 2024"
+- "Show me notes I've edited in the last 7 days"
+- "List all notes under 'n8n Template' folder, including subfolders"
+
+### Content Management
+- "Add today's update to my work log" (uses `update_note` with `mode: 'append'`)
+- "Replace this draft with the final version" (uses `update_note` with `mode: 'overwrite'`)
+- "Create a new note called 'Weekly Review' in my journal folder"
+
+> 📖 **More Examples**: See [User Query Examples](docs/user-query-examples.md) for comprehensive usage scenarios.
+
+## Documentation
+
+- [Note Management Guide](docs/manage-notes-examples/index.md) - Safe content editing with revision control
+- [User Query Examples](docs/user-query-examples.md) - Natural language query examples
+- [Search Query Examples](docs/search-examples/) - Advanced search syntax and filters
+
+## Development
+
+If you want to contribute or modify the server:
+
+```bash
+# Clone the repository
+git clone https://github.com/tan-yong-sheng/triliumnext-mcp.git
+
+# Install dependencies
+npm install
+
+# Build the server
+npm run build
+
+# For development with auto-rebuild
+npm run watch
+```
+
+## Contributing
+
+Contributions are welcome! If you are looking to improve the server, please familiarize yourself with the official [Trilium Search DSL documentation](https://triliumnext.github.io/Docs/Wiki/search.html) and our internal [Search Query Examples](docs/search-examples/) to understand how search queries are constructed.
+
 Please feel free to open an issue or submit a pull request.

package/build/index.js

@@ -9,7 +9,6 @@ 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";
@@ -24,7 +23,7 @@ class TriliumServer {
         this.allowedPermissions = PERMISSIONS.split(';');
         this.server = new Server({
             name: "triliumnext-mcp",
-            version: "0.3.10",
+            version: "0.3.13",
         }, {
             capabilities: {
                 tools: {},
@@ -78,8 +77,6 @@ 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/attributeHandler.js

@@ -221,38 +221,6 @@ 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) {
@@ -278,28 +246,6 @@ The attribute you're trying to create already exists on this note. Here are your
             });
         }
     }
-    // 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 };
 }
 /**
@@ -370,11 +316,5 @@ 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
 `;
 }