triliumnext-mcp 0.3.12 → 0.3.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (246) hide show
  1. package/README.md +149 -149
  2. package/build/index.d.ts +3 -0
  3. package/build/index.d.ts.map +1 -0
  4. package/build/index.js +1 -4
  5. package/build/index.js.map +1 -0
  6. package/build/modules/attributeHandler.js +0 -60
  7. package/build/modules/attributeManager.js +34 -235
  8. package/build/modules/attributes/attributeListHandler.d.ts +14 -0
  9. package/build/modules/attributes/attributeListHandler.d.ts.map +1 -0
  10. package/build/modules/{attributeListHandler.js → attributes/attributeListHandler.js} +2 -1
  11. package/build/modules/attributes/attributeListHandler.js.map +1 -0
  12. package/build/modules/attributes/attributeManageHandler.d.ts +16 -0
  13. package/build/modules/attributes/attributeManageHandler.d.ts.map +1 -0
  14. package/build/modules/attributes/attributeManageHandler.js +261 -0
  15. package/build/modules/attributes/attributeManageHandler.js.map +1 -0
  16. package/build/modules/attributes/attributeManageManager.d.ts +13 -0
  17. package/build/modules/attributes/attributeManageManager.d.ts.map +1 -0
  18. package/build/modules/attributes/attributeManageManager.js +520 -0
  19. package/build/modules/attributes/attributeManageManager.js.map +1 -0
  20. package/build/modules/attributes/attributeReadHandler.d.ts +16 -0
  21. package/build/modules/attributes/attributeReadHandler.d.ts.map +1 -0
  22. package/build/modules/attributes/attributeReadHandler.js +136 -0
  23. package/build/modules/attributes/attributeReadHandler.js.map +1 -0
  24. package/build/modules/attributes/operations/attributeCreation.d.ts +15 -0
  25. package/build/modules/attributes/operations/attributeCreation.d.ts.map +1 -0
  26. package/build/modules/attributes/operations/attributeCreation.js +238 -0
  27. package/build/modules/attributes/operations/attributeCreation.js.map +1 -0
  28. package/build/modules/attributes/operations/attributeDeletion.d.ts +11 -0
  29. package/build/modules/attributes/operations/attributeDeletion.d.ts.map +1 -0
  30. package/build/modules/attributes/operations/attributeDeletion.js +63 -0
  31. package/build/modules/attributes/operations/attributeDeletion.js.map +1 -0
  32. package/build/modules/attributes/operations/attributeList.d.ts +29 -0
  33. package/build/modules/attributes/operations/attributeList.d.ts.map +1 -0
  34. package/build/modules/{attributeListManager.js → attributes/operations/attributeList.js} +3 -2
  35. package/build/modules/attributes/operations/attributeList.js.map +1 -0
  36. package/build/modules/attributes/operations/attributeRead.d.ts +13 -0
  37. package/build/modules/attributes/operations/attributeRead.d.ts.map +1 -0
  38. package/build/modules/attributes/operations/attributeRead.js +43 -0
  39. package/build/modules/attributes/operations/attributeRead.js.map +1 -0
  40. package/build/modules/attributes/operations/attributeUpdate.d.ts +11 -0
  41. package/build/modules/attributes/operations/attributeUpdate.d.ts.map +1 -0
  42. package/build/modules/attributes/operations/attributeUpdate.js +107 -0
  43. package/build/modules/attributes/operations/attributeUpdate.js.map +1 -0
  44. package/build/modules/attributes/operations/batchOperations.d.ts +18 -0
  45. package/build/modules/attributes/operations/batchOperations.d.ts.map +1 -0
  46. package/build/modules/attributes/operations/batchOperations.js +49 -0
  47. package/build/modules/attributes/operations/batchOperations.js.map +1 -0
  48. package/build/modules/attributes/validation/attributeValidator.d.ts +40 -0
  49. package/build/modules/attributes/validation/attributeValidator.d.ts.map +1 -0
  50. package/build/modules/attributes/validation/attributeValidator.js +84 -0
  51. package/build/modules/attributes/validation/attributeValidator.js.map +1 -0
  52. package/build/modules/attributes/validation/containerProtection.d.ts +14 -0
  53. package/build/modules/attributes/validation/containerProtection.d.ts.map +1 -0
  54. package/build/modules/attributes/validation/containerProtection.js +105 -0
  55. package/build/modules/attributes/validation/containerProtection.js.map +1 -0
  56. package/build/modules/fileManager.js +329 -0
  57. package/build/modules/noteHandler.js +73 -8
  58. package/build/modules/noteManager.js +173 -230
  59. package/build/modules/notes/crud/noteCreation.d.ts +26 -0
  60. package/build/modules/notes/crud/noteCreation.d.ts.map +1 -0
  61. package/build/modules/notes/crud/noteCreation.js +206 -0
  62. package/build/modules/notes/crud/noteCreation.js.map +1 -0
  63. package/build/modules/notes/crud/noteDeletion.d.ts +10 -0
  64. package/build/modules/notes/crud/noteDeletion.d.ts.map +1 -0
  65. package/build/modules/notes/crud/noteDeletion.js +19 -0
  66. package/build/modules/notes/crud/noteDeletion.js.map +1 -0
  67. package/build/modules/notes/crud/noteRetrieval.d.ts +10 -0
  68. package/build/modules/notes/crud/noteRetrieval.d.ts.map +1 -0
  69. package/build/modules/notes/crud/noteRetrieval.js +64 -0
  70. package/build/modules/notes/crud/noteRetrieval.js.map +1 -0
  71. package/build/modules/notes/crud/noteUpdate.d.ts +10 -0
  72. package/build/modules/notes/crud/noteUpdate.d.ts.map +1 -0
  73. package/build/modules/notes/crud/noteUpdate.js +305 -0
  74. package/build/modules/notes/crud/noteUpdate.js.map +1 -0
  75. package/build/modules/notes/noteHandler.d.ts +51 -0
  76. package/build/modules/notes/noteHandler.d.ts.map +1 -0
  77. package/build/modules/notes/noteHandler.js +211 -0
  78. package/build/modules/notes/noteHandler.js.map +1 -0
  79. package/build/modules/notes/noteManager.d.ts +102 -0
  80. package/build/modules/notes/noteManager.d.ts.map +1 -0
  81. package/build/modules/notes/noteManager.js +20 -0
  82. package/build/modules/notes/noteManager.js.map +1 -0
  83. package/build/modules/notes/operations/duplicateChecker.d.ts +12 -0
  84. package/build/modules/notes/operations/duplicateChecker.d.ts.map +1 -0
  85. package/build/modules/notes/operations/duplicateChecker.js +43 -0
  86. package/build/modules/notes/operations/duplicateChecker.js.map +1 -0
  87. package/build/modules/notes/operations/searchReplace.d.ts +14 -0
  88. package/build/modules/notes/operations/searchReplace.d.ts.map +1 -0
  89. package/build/modules/notes/operations/searchReplace.js +206 -0
  90. package/build/modules/notes/operations/searchReplace.js.map +1 -0
  91. package/build/modules/notes/validation/containerValidator.d.ts +13 -0
  92. package/build/modules/notes/validation/containerValidator.d.ts.map +1 -0
  93. package/build/modules/notes/validation/containerValidator.js +87 -0
  94. package/build/modules/notes/validation/containerValidator.js.map +1 -0
  95. package/build/modules/notes/validation/contentValidator.d.ts +14 -0
  96. package/build/modules/notes/validation/contentValidator.d.ts.map +1 -0
  97. package/build/modules/notes/validation/contentValidator.js +12 -0
  98. package/build/modules/notes/validation/contentValidator.js.map +1 -0
  99. package/build/modules/notes/validation/hashValidator.d.ts +12 -0
  100. package/build/modules/notes/validation/hashValidator.d.ts.map +1 -0
  101. package/build/modules/notes/validation/hashValidator.js +24 -0
  102. package/build/modules/notes/validation/hashValidator.js.map +1 -0
  103. package/build/modules/resolve/resolveHandler.d.ts +6 -0
  104. package/build/modules/resolve/resolveHandler.d.ts.map +1 -0
  105. package/build/modules/resolve/resolveHandler.js +53 -0
  106. package/build/modules/resolve/resolveHandler.js.map +1 -0
  107. package/build/modules/resolve/resolveManager.d.ts +31 -0
  108. package/build/modules/resolve/resolveManager.d.ts.map +1 -0
  109. package/build/modules/resolve/resolveManager.js +145 -0
  110. package/build/modules/resolve/resolveManager.js.map +1 -0
  111. package/build/modules/search/filtering/hierarchyFilter.d.ts +35 -0
  112. package/build/modules/search/filtering/hierarchyFilter.d.ts.map +1 -0
  113. package/build/modules/search/filtering/hierarchyFilter.js +187 -0
  114. package/build/modules/search/filtering/hierarchyFilter.js.map +1 -0
  115. package/build/modules/search/filtering/resultFilter.d.ts +42 -0
  116. package/build/modules/search/filtering/resultFilter.d.ts.map +1 -0
  117. package/build/modules/search/filtering/resultFilter.js +132 -0
  118. package/build/modules/search/filtering/resultFilter.js.map +1 -0
  119. package/build/modules/search/query/queryBuilder.d.ts +19 -0
  120. package/build/modules/search/query/queryBuilder.d.ts.map +1 -0
  121. package/build/modules/search/query/queryBuilder.js +471 -0
  122. package/build/modules/search/query/queryBuilder.js.map +1 -0
  123. package/build/modules/search/query/queryOptimizer.d.ts +30 -0
  124. package/build/modules/search/query/queryOptimizer.d.ts.map +1 -0
  125. package/build/modules/search/query/queryOptimizer.js +133 -0
  126. package/build/modules/search/query/queryOptimizer.js.map +1 -0
  127. package/build/modules/search/query/queryValidator.d.ts +53 -0
  128. package/build/modules/search/query/queryValidator.d.ts.map +1 -0
  129. package/build/modules/search/query/queryValidator.js +157 -0
  130. package/build/modules/search/query/queryValidator.js.map +1 -0
  131. package/build/modules/search/searchHandler.d.ts +15 -0
  132. package/build/modules/search/searchHandler.d.ts.map +1 -0
  133. package/build/modules/search/searchHandler.js +36 -0
  134. package/build/modules/search/searchHandler.js.map +1 -0
  135. package/build/modules/search/searchManager.d.ts +33 -0
  136. package/build/modules/search/searchManager.d.ts.map +1 -0
  137. package/build/modules/search/searchManager.js +77 -0
  138. package/build/modules/search/searchManager.js.map +1 -0
  139. package/build/modules/searchManager.js +1 -53
  140. package/build/modules/searchQueryBuilder.js +0 -7
  141. package/build/modules/shared/index.d.ts +18 -0
  142. package/build/modules/shared/index.d.ts.map +1 -0
  143. package/build/modules/shared/index.js +26 -0
  144. package/build/modules/shared/index.js.map +1 -0
  145. package/build/modules/toolDefinitions.js +44 -57
  146. package/build/modules/tools/definitions/attributeTools.d.ts +13 -0
  147. package/build/modules/tools/definitions/attributeTools.d.ts.map +1 -0
  148. package/build/modules/tools/definitions/attributeTools.js +130 -0
  149. package/build/modules/tools/definitions/attributeTools.js.map +1 -0
  150. package/build/modules/tools/definitions/readTools.d.ts +9 -0
  151. package/build/modules/tools/definitions/readTools.d.ts.map +1 -0
  152. package/build/modules/tools/definitions/readTools.js +130 -0
  153. package/build/modules/tools/definitions/readTools.js.map +1 -0
  154. package/build/modules/tools/definitions/writeTools.d.ts +9 -0
  155. package/build/modules/tools/definitions/writeTools.d.ts.map +1 -0
  156. package/build/modules/tools/definitions/writeTools.js +177 -0
  157. package/build/modules/tools/definitions/writeTools.js.map +1 -0
  158. package/build/modules/tools/toolDefinitions.d.ts +26 -0
  159. package/build/modules/tools/toolDefinitions.d.ts.map +1 -0
  160. package/build/modules/tools/toolDefinitions.js +450 -0
  161. package/build/modules/tools/toolDefinitions.js.map +1 -0
  162. package/build/modules/types/index.d.ts +134 -0
  163. package/build/modules/types/index.d.ts.map +1 -0
  164. package/build/modules/types/index.js +2 -0
  165. package/build/modules/types/index.js.map +1 -0
  166. package/build/modules/utils/attributes/attributeNameCleaner.d.ts +54 -0
  167. package/build/modules/utils/attributes/attributeNameCleaner.d.ts.map +1 -0
  168. package/build/{utils → modules/utils/attributes}/attributeNameCleaner.js +17 -2
  169. package/build/modules/utils/attributes/attributeNameCleaner.js.map +1 -0
  170. package/build/modules/utils/attributes/attributeUtils.d.ts +41 -0
  171. package/build/modules/utils/attributes/attributeUtils.d.ts.map +1 -0
  172. package/build/modules/utils/attributes/attributeUtils.js +116 -0
  173. package/build/modules/utils/attributes/attributeUtils.js.map +1 -0
  174. package/build/modules/utils/attributes/index.d.ts +7 -0
  175. package/build/modules/utils/attributes/index.d.ts.map +1 -0
  176. package/build/modules/utils/attributes/index.js +9 -0
  177. package/build/modules/utils/attributes/index.js.map +1 -0
  178. package/build/modules/utils/content/contentProcessor.d.ts +20 -0
  179. package/build/modules/utils/content/contentProcessor.d.ts.map +1 -0
  180. package/build/modules/utils/content/contentProcessor.js +186 -0
  181. package/build/modules/utils/content/contentProcessor.js.map +1 -0
  182. package/build/modules/utils/content/index.d.ts +7 -0
  183. package/build/modules/utils/content/index.d.ts.map +1 -0
  184. package/build/modules/utils/content/index.js +9 -0
  185. package/build/modules/utils/content/index.js.map +1 -0
  186. package/build/modules/utils/content/templateMapper.d.ts +63 -0
  187. package/build/modules/utils/content/templateMapper.d.ts.map +1 -0
  188. package/build/{utils → modules/utils/content}/templateMapper.js +1 -0
  189. package/build/modules/utils/content/templateMapper.js.map +1 -0
  190. package/build/modules/utils/formatting/index.d.ts +7 -0
  191. package/build/modules/utils/formatting/index.d.ts.map +1 -0
  192. package/build/modules/utils/formatting/index.js +9 -0
  193. package/build/modules/utils/formatting/index.js.map +1 -0
  194. package/build/modules/utils/formatting/noteBuilder.d.ts +12 -0
  195. package/build/modules/utils/formatting/noteBuilder.d.ts.map +1 -0
  196. package/build/modules/utils/formatting/noteBuilder.js +18 -0
  197. package/build/modules/utils/formatting/noteBuilder.js.map +1 -0
  198. package/build/modules/utils/formatting/noteFormatter.d.ts +30 -0
  199. package/build/modules/utils/formatting/noteFormatter.d.ts.map +1 -0
  200. package/build/modules/utils/formatting/noteFormatter.js +59 -0
  201. package/build/modules/utils/formatting/noteFormatter.js.map +1 -0
  202. package/build/modules/utils/recovery/index.d.ts +6 -0
  203. package/build/modules/utils/recovery/index.d.ts.map +1 -0
  204. package/build/modules/utils/recovery/index.js +7 -0
  205. package/build/modules/utils/recovery/index.js.map +1 -0
  206. package/build/modules/utils/recovery/noteRecovery.d.ts +51 -0
  207. package/build/modules/utils/recovery/noteRecovery.d.ts.map +1 -0
  208. package/build/modules/utils/recovery/noteRecovery.js +195 -0
  209. package/build/modules/utils/recovery/noteRecovery.js.map +1 -0
  210. package/build/modules/utils/system/errorUtils.d.ts +34 -0
  211. package/build/modules/utils/system/errorUtils.d.ts.map +1 -0
  212. package/build/modules/utils/system/errorUtils.js +48 -0
  213. package/build/modules/utils/system/errorUtils.js.map +1 -0
  214. package/build/modules/utils/system/index.d.ts +8 -0
  215. package/build/modules/utils/system/index.d.ts.map +1 -0
  216. package/build/modules/utils/system/index.js +11 -0
  217. package/build/modules/utils/system/index.js.map +1 -0
  218. package/build/modules/utils/system/permissionUtils.d.ts +46 -0
  219. package/build/modules/utils/system/permissionUtils.d.ts.map +1 -0
  220. package/build/modules/utils/system/permissionUtils.js +56 -0
  221. package/build/modules/utils/system/permissionUtils.js.map +1 -0
  222. package/build/modules/utils/system/verboseUtils.d.ts +41 -0
  223. package/build/modules/utils/system/verboseUtils.d.ts.map +1 -0
  224. package/build/modules/utils/system/verboseUtils.js +102 -0
  225. package/build/modules/utils/system/verboseUtils.js.map +1 -0
  226. package/build/modules/utils/validation/contentIntegrity.d.ts +72 -0
  227. package/build/modules/utils/validation/contentIntegrity.d.ts.map +1 -0
  228. package/build/modules/utils/validation/contentIntegrity.js +160 -0
  229. package/build/modules/utils/validation/contentIntegrity.js.map +1 -0
  230. package/build/modules/utils/validation/contentRules.d.ts +53 -0
  231. package/build/modules/utils/validation/contentRules.d.ts.map +1 -0
  232. package/build/modules/utils/validation/contentRules.js +267 -0
  233. package/build/modules/utils/validation/contentRules.js.map +1 -0
  234. package/build/modules/utils/validation/index.d.ts +8 -0
  235. package/build/modules/utils/validation/index.d.ts.map +1 -0
  236. package/build/modules/utils/validation/index.js +11 -0
  237. package/build/modules/utils/validation/index.js.map +1 -0
  238. package/build/modules/utils/validation/validationUtils.d.ts +310 -0
  239. package/build/modules/utils/validation/validationUtils.d.ts.map +1 -0
  240. package/build/modules/utils/validation/validationUtils.js +199 -0
  241. package/build/modules/utils/validation/validationUtils.js.map +1 -0
  242. package/build/utils/contentIntegrity.js +8 -2
  243. package/build/utils/contentRules.js +23 -23
  244. package/build/utils/fileUtils.js +390 -0
  245. package/build/utils/validationUtils.js +1 -3
  246. package/package.json +2 -2
package/README.md CHANGED
@@ -1,150 +1,150 @@
1
- # TriliumNext Notes' MCP Server
2
-
3
- ⚠️ **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.** ⚠️
4
-
5
- A model context protocol server for TriliumNext Notes. This server provides tools to interact with your Trilium Notes instance through MCP.
6
-
7
- ## Quick Start
8
-
9
- Make sure to set up your environment variables first:
10
- - `TRILIUM_API_URL` (default: http://localhost:8080/etapi)
11
- - `TRILIUM_API_TOKEN` (required, get this from your Trilium Notes settings)
12
- - `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`)
13
- - `VERBOSE` (optional, default='false', which if true will print verbose debugging logs)
14
-
15
- ## Installation
16
-
17
- ### 1. Using with Claude Desktop
18
-
19
- Add the server config to your Claude Desktop configuration file:
20
-
21
- #### For Local Installation (on Windows)
22
-
23
- ```json
24
- "triliumnext-mcp": {
25
- "command": "cmd",
26
- "args": [
27
- "/k",
28
- "npx",
29
- "-y",
30
- "triliumnext-mcp"
31
- ],
32
- "env": {
33
- "TRILIUM_API_URL": "http://localhost:8080/etapi",
34
- "TRILIUM_API_TOKEN": "<YOUR_TRILIUM_API_TOKEN>",
35
- "PERMISSIONS": "READ;WRITE"
36
- }
37
- }
38
- ```
39
-
40
- #### For Local installation (on Linux)
41
-
42
- ```json
43
- "triliumnext-mcp": {
44
- "command": "npx",
45
- "args": [
46
- "-y",
47
- "triliumnext-mcp"
48
- ],
49
- "env": {
50
- "TRILIUM_API_URL": "http://localhost:8080/etapi",
51
- "TRILIUM_API_TOKEN": "<YOUR_TRILIUM_API_TOKEN>",
52
- "PERMISSIONS": "READ;WRITE"
53
- }
54
- }
55
- ```
56
-
57
- #### For Development (on Windows / Linux)
58
-
59
- ```bash
60
- cd /path/to/triliumnext-mcp
61
- npm run build
62
- ```
63
-
64
- ```json
65
- "triliumnext-mcp": {
66
- "command": "node",
67
- "args": [
68
- "/path/to/triliumnext-mcp/build/index.js"
69
- ],
70
- "env": {
71
- "TRILIUM_API_URL": "http://localhost:8080/etapi",
72
- "TRILIUM_API_TOKEN": "<YOUR_TRILIUM_API_TOKEN>",
73
- "PERMISSIONS": "READ;WRITE",
74
- "VERBOSE": "true"
75
- }
76
- }
77
- ```
78
-
79
- Location of the configuration file:
80
- - Windows: `%APPDATA%/Claude/claude_desktop_config.json`
81
- - MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
82
-
83
- **Feedback**: Please report issues and test results at [GitHub Issues](https://github.com/TriliumNext/Notes/issues)
84
-
85
- ## Available Tools
86
-
87
- The server provides the following tools for note management:
88
-
89
- ### Search & Discovery Tools
90
-
91
- - `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.
92
- - `resolve_note_id` - Find a note's ID by its title. Essential for getting a note's ID to use with other tools.
93
-
94
- ### Note Management Tools
95
-
96
- - `get_note` - Retrieve a note and its content by ID. Can also be used with regex to extract specific patterns from the content.
97
- - `create_note` - Create a new note. Supports 9 note types and allows creating attributes (labels and relations) in the same step.
98
- - `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.
99
- - `delete_note` - Permanently delete a note (⚠️ cannot be undone).
100
-
101
- ### Attribute Management Tools
102
-
103
- - `read_attributes` - Read all attributes (labels and relations) for a given note.
104
- - `manage_attributes` - Create, update, or delete attributes on a note. Supports batch creation.
105
-
106
- > 📖 **Detailed Usage**: See [Note Management Guide](docs/manage-notes-examples/index.md) for revision control strategy and best practices.
107
-
108
- ## Example Queries
109
-
110
- ### Search & Discovery
111
- - "Find my most recent 10 notes about 'n8n' since the beginning of 2024"
112
- - "Show me notes I've edited in the last 7 days"
113
- - "List all notes under 'n8n Template' folder, including subfolders"
114
-
115
- ### Content Management
116
- - "Add today's update to my work log" (uses `update_note` with `mode: 'append'`)
117
- - "Replace this draft with the final version" (uses `update_note` with `mode: 'overwrite'`)
118
- - "Create a new note called 'Weekly Review' in my journal folder"
119
-
120
- > 📖 **More Examples**: See [User Query Examples](docs/user-query-examples.md) for comprehensive usage scenarios.
121
-
122
- ## Documentation
123
-
124
- - [Note Management Guide](docs/manage-notes-examples/index.md) - Safe content editing with revision control
125
- - [User Query Examples](docs/user-query-examples.md) - Natural language query examples
126
- - [Search Query Examples](docs/search-examples/) - Advanced search syntax and filters
127
-
128
- ## Development
129
-
130
- If you want to contribute or modify the server:
131
-
132
- ```bash
133
- # Clone the repository
134
- git clone https://github.com/tan-yong-sheng/triliumnext-mcp.git
135
-
136
- # Install dependencies
137
- npm install
138
-
139
- # Build the server
140
- npm run build
141
-
142
- # For development with auto-rebuild
143
- npm run watch
144
- ```
145
-
146
- ## Contributing
147
-
148
- 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.
149
-
1
+ # TriliumNext Notes' MCP Server
2
+
3
+ ⚠️ **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.** ⚠️
4
+
5
+ A model context protocol server for TriliumNext Notes. This server provides tools to interact with your Trilium Notes instance through MCP.
6
+
7
+ ## Quick Start
8
+
9
+ Make sure to set up your environment variables first:
10
+ - `TRILIUM_API_URL` (default: http://localhost:8080/etapi)
11
+ - `TRILIUM_API_TOKEN` (required, get this from your Trilium Notes settings)
12
+ - `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`)
13
+ - `VERBOSE` (optional, default='false', which if true will print verbose debugging logs)
14
+
15
+ ## Installation
16
+
17
+ ### 1. Using with Claude Desktop
18
+
19
+ Add the server config to your Claude Desktop configuration file:
20
+
21
+ #### For Local Installation (on Windows)
22
+
23
+ ```json
24
+ "triliumnext-mcp": {
25
+ "command": "cmd",
26
+ "args": [
27
+ "/k",
28
+ "npx",
29
+ "-y",
30
+ "triliumnext-mcp"
31
+ ],
32
+ "env": {
33
+ "TRILIUM_API_URL": "http://localhost:8080/etapi",
34
+ "TRILIUM_API_TOKEN": "<YOUR_TRILIUM_API_TOKEN>",
35
+ "PERMISSIONS": "READ;WRITE"
36
+ }
37
+ }
38
+ ```
39
+
40
+ #### For Local installation (on Linux)
41
+
42
+ ```json
43
+ "triliumnext-mcp": {
44
+ "command": "npx",
45
+ "args": [
46
+ "-y",
47
+ "triliumnext-mcp"
48
+ ],
49
+ "env": {
50
+ "TRILIUM_API_URL": "http://localhost:8080/etapi",
51
+ "TRILIUM_API_TOKEN": "<YOUR_TRILIUM_API_TOKEN>",
52
+ "PERMISSIONS": "READ;WRITE"
53
+ }
54
+ }
55
+ ```
56
+
57
+ #### For Development (on Windows / Linux)
58
+
59
+ ```bash
60
+ cd /path/to/triliumnext-mcp
61
+ npm run build
62
+ ```
63
+
64
+ ```json
65
+ "triliumnext-mcp": {
66
+ "command": "node",
67
+ "args": [
68
+ "/path/to/triliumnext-mcp/build/index.js"
69
+ ],
70
+ "env": {
71
+ "TRILIUM_API_URL": "http://localhost:8080/etapi",
72
+ "TRILIUM_API_TOKEN": "<YOUR_TRILIUM_API_TOKEN>",
73
+ "PERMISSIONS": "READ;WRITE",
74
+ "VERBOSE": "true"
75
+ }
76
+ }
77
+ ```
78
+
79
+ Location of the configuration file:
80
+ - Windows: `%APPDATA%/Claude/claude_desktop_config.json`
81
+ - MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
82
+
83
+ **Feedback**: Please report issues and test results at [GitHub Issues](https://github.com/TriliumNext/Notes/issues)
84
+
85
+ ## Available Tools
86
+
87
+ The server provides the following tools for note management:
88
+
89
+ ### Search & Discovery Tools
90
+
91
+ - `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.
92
+ - `resolve_note_id` - Find a note's ID by its title. Essential for getting a note's ID to use with other tools.
93
+
94
+ ### Note Management Tools
95
+
96
+ - `get_note` - Retrieve a note and its content by ID. Can also be used with regex to extract specific patterns from the content.
97
+ - `create_note` - Create a new note. Supports 9 note types and allows creating attributes (labels and relations) in the same step.
98
+ - `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.
99
+ - `delete_note` - Permanently delete a note (⚠️ cannot be undone).
100
+
101
+ ### Attribute Management Tools
102
+
103
+ - `read_attributes` - Read all attributes (labels and relations) for a given note.
104
+ - `manage_attributes` - Create, update, or delete attributes on a note. Supports batch creation.
105
+
106
+ > 📖 **Detailed Usage**: See [Note Management Guide](docs/manage-notes-examples/index.md) for revision control strategy and best practices.
107
+
108
+ ## Example Queries
109
+
110
+ ### Search & Discovery
111
+ - "Find my most recent 10 notes about 'n8n' since the beginning of 2024"
112
+ - "Show me notes I've edited in the last 7 days"
113
+ - "List all notes under 'n8n Template' folder, including subfolders"
114
+
115
+ ### Content Management
116
+ - "Add today's update to my work log" (uses `update_note` with `mode: 'append'`)
117
+ - "Replace this draft with the final version" (uses `update_note` with `mode: 'overwrite'`)
118
+ - "Create a new note called 'Weekly Review' in my journal folder"
119
+
120
+ > 📖 **More Examples**: See [User Query Examples](docs/user-query-examples.md) for comprehensive usage scenarios.
121
+
122
+ ## Documentation
123
+
124
+ - [Note Management Guide](docs/manage-notes-examples/index.md) - Safe content editing with revision control
125
+ - [User Query Examples](docs/user-query-examples.md) - Natural language query examples
126
+ - [Search Query Examples](docs/search-examples/) - Advanced search syntax and filters
127
+
128
+ ## Development
129
+
130
+ If you want to contribute or modify the server:
131
+
132
+ ```bash
133
+ # Clone the repository
134
+ git clone https://github.com/tan-yong-sheng/triliumnext-mcp.git
135
+
136
+ # Install dependencies
137
+ npm install
138
+
139
+ # Build the server
140
+ npm run build
141
+
142
+ # For development with auto-rebuild
143
+ npm run watch
144
+ ```
145
+
146
+ ## Contributing
147
+
148
+ 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.
149
+
150
150
  Please feel free to open an issue or submit a pull request.
@@ -0,0 +1,3 @@
1
+ #!/usr/bin/env node
2
+ export { buildNoteParams } from './modules/utils/formatting/noteBuilder.js';
3
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AA0JA,OAAO,EACL,eAAe,EAChB,MAAM,2CAA2C,CAAC"}
package/build/index.js CHANGED
@@ -9,7 +9,6 @@ import { handleCreateNoteRequest, handleUpdateNoteRequest, handleDeleteNoteReque
9
9
  import { handleSearchNotesRequest } from "./modules/searchHandler.js";
10
10
  import { handleResolveNoteRequest } from "./modules/resolveHandler.js";
11
11
  import { handleManageAttributes, handleReadAttributes } from "./modules/attributeHandler.js";
12
- import { handleListAttributesRequest } from "./modules/attributeListHandler.js";
13
12
  const TRILIUM_API_URL = process.env.TRILIUM_API_URL;
14
13
  const TRILIUM_API_TOKEN = process.env.TRILIUM_API_TOKEN;
15
14
  const PERMISSIONS = process.env.PERMISSIONS || "READ;WRITE";
@@ -24,7 +23,7 @@ class TriliumServer {
24
23
  this.allowedPermissions = PERMISSIONS.split(';');
25
24
  this.server = new Server({
26
25
  name: "triliumnext-mcp",
27
- version: "0.3.10",
26
+ version: "0.3.13",
28
27
  }, {
29
28
  capabilities: {
30
29
  tools: {},
@@ -78,8 +77,6 @@ class TriliumServer {
78
77
  return await handleReadAttributes(request.params.arguments, this.axiosInstance, this);
79
78
  case "manage_attributes":
80
79
  return await handleManageAttributes(request.params.arguments, this.axiosInstance, this);
81
- case "list_attributes":
82
- return await handleListAttributesRequest(request.params.arguments, this.axiosInstance, this);
83
80
  default:
84
81
  throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${request.params.name}`);
85
82
  }
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
@@ -221,38 +221,6 @@ function format_attribute_response(result, noteId, operation) {
221
221
  text: `📋 Error details:\n${result.errors.map((err, i) => `${i + 1}. ${err}`).join('\n')}`
222
222
  });
223
223
  }
224
- // Add specific guidance for common errors
225
- if (result.errors && result.errors.some(err => err.includes("already exists"))) {
226
- content.push({
227
- type: "text",
228
- text: `💡 **Attribute Already Exists**
229
-
230
- The attribute you're trying to create already exists on this note. Here are your options:
231
-
232
- 1. **Update the existing attribute** (recommended):
233
- - Use operation: "update" instead of "create"
234
- - Only the value and position can be updated for labels
235
- - Only the position can be updated for relations
236
-
237
- 2. **Delete and recreate** (for inheritable changes):
238
- - First delete with operation: "delete"
239
- - Then recreate with operation: "create"
240
- - Use this when you need to change the 'isInheritable' property
241
-
242
- 3. **View current attributes**:
243
- - Use read_attributes to see all existing attributes
244
- - Check current values, positions, and inheritable settings
245
-
246
- 📋 **Example update operation**:
247
- \`\`\`
248
- {
249
- "noteId": "${noteId}",
250
- "operation": "update",
251
- "attributes": [{"type": "label", "name": "your_attribute", "value": "new_value"}]
252
- }
253
- \`\`\``
254
- });
255
- }
256
224
  }
257
225
  // Add attribute data for successful operations
258
226
  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
278
246
  });
279
247
  }
280
248
  }
281
- // Add guidance for batch operations with conflicts
282
- if (result.success && operation === "batch_create" && result.errors && result.errors.length > 0) {
283
- const hasConflicts = result.errors.some(err => err.includes("Skipping duplicate") || err.includes("already exist"));
284
- if (hasConflicts) {
285
- content.push({
286
- type: "text",
287
- text: `⚠️ **Batch Operation Summary**
288
-
289
- Some attributes were skipped due to conflicts (already existing). This is normal behavior for batch operations:
290
-
291
- ✅ **Successfully created**: ${result.attributes?.length || 0} attributes
292
- ❌ **Skipped duplicates**: ${result.errors?.filter(err => err.includes("Skipping duplicate") || err.includes("already exist")).length || 0} attributes
293
-
294
- 💡 **To manage skipped attributes**:
295
- - Use \`read_attributes\` to view current attributes
296
- - Use \`update\` operation to modify existing attributes
297
- - Use \`delete\` operation to remove unwanted attributes first
298
-
299
- This approach prevents accidental overwrites while allowing partial success for batch operations.`
300
- });
301
- }
302
- }
303
249
  return { content };
304
250
  }
305
251
  /**
@@ -370,11 +316,5 @@ export function get_attributes_help() {
370
316
  - Template relations require the target note to exist in your Trilium instance
371
317
  - Position values control display order (lower numbers appear first)
372
318
  - Use read_attributes to view existing attributes before making changes
373
-
374
- 🛡️ **Validation & Conflict Handling**:
375
- - Create operations now validate against existing attributes to prevent duplicates
376
- - If an attribute already exists, you'll get detailed error messages with guidance
377
- - Batch operations skip duplicates and continue with valid attributes
378
- - Use "update" to modify existing attributes, "create" for new ones only
379
319
  `;
380
320
  }