enhance: API tools to add to page, search blocks and

update a block's content. Also fix search not returning usable
uuids in response

Author: logseq-cldwalker

deps/cli/src/logseq/cli/commands/mcp_server.cljs

@@ -26,13 +26,14 @@
 
 (def ^:private local-tools
   "MCP Tools when running with a local graph"
-  (merge-with
-   merge
-   cli-common-mcp-server/api-tools
-   {:getPage {:fn local-get-page}
-    :listPages {:fn local-list-pages}
-    :listProperties {:fn local-list-properties}
-    :listTags {:fn local-list-tags}}))
+  (let [tools {:getPage {:fn local-get-page}
+               :listPages {:fn local-list-pages}
+               :listProperties {:fn local-list-properties}
+               :listTags {:fn local-list-tags}}]
+    (merge-with
+     merge
+     (select-keys cli-common-mcp-server/api-tools (keys tools))
+     tools)))
 
 (defn- create-http-server
   [mcp-server opts]

deps/cli/src/logseq/cli/common/mcp/server.cljs

@@ -8,8 +8,8 @@
 
 ;; Server util fns
 ;; ===============
-(def ^:private transports
-  "Stores transports by session ID"
+;; "Stores transports by session ID"
+(defonce ^:private transports
   (atom {}))
 
 ;; See https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http
@@ -85,11 +85,14 @@
 
 (defn- api-tool
   "Calls API method w/ args and returns a MCP response"
-  [api-fn api-method method-args]
+  [api-fn api-method method-args & {:keys [write-tool?]}]
   (-> (p/let [body (api-fn api-method method-args)]
-        (if-let [error (aget body "error")]
+        (if-let [error (and body (aget body "error"))]
           (mcp-error-response (str "API Error: " error))
-          (mcp-success-response body)))
+          (if write-tool?
+            ;; Writes that return have succeeded since writes fail fast if they don't write
+            (mcp-success-response {:ok true})
+            (mcp-success-response body))))
       (p/catch unexpected-api-error)))
 
 (defn- api-get-page
@@ -108,22 +111,65 @@
   [call-api-fn _args]
   (call-api-fn "logseq.cli.listProperties" []))
 
+(defn- api-add-to-page
+  [call-api-fn args]
+  (call-api-fn "logseq.editor.appendBlockInPage"
+               [(aget args "pageName")
+                (aget args "content")
+                #js {:mcp-options #js {:force (aget args "force")}}]
+               {:write-tool? true}))
+
+(defn- api-update-block
+  [call-api-fn args]
+  (call-api-fn "logseq.editor.updateBlock"
+               [(aget args "blockUUID")
+                (aget args "content")
+                #js {:mcp true}]
+               {:write-tool? true}))
+
+(defn- api-search-blocks
+  [call-api-fn args]
+  (call-api-fn "logseq.app.search" [(aget args "searchTerm") #js {:enable-snippet? false}]))
+
 (def api-tools
   "MCP Tools when calling API server"
   {:listPages
    {:fn api-list-pages
-    :config #js {:title "List Pages"}}
+    :config #js {:title "List Pages"
+                 :description "List all pages in a graph"}}
    :getPage
    {:fn api-get-page
     :config #js {:title "Get Page"
                  :description "Get a page's content including its blocks"
                  :inputSchema #js {:pageName (z/string)}}}
+   :addToPage
+   {:fn api-add-to-page
+    :config #js {:title "Add to Page"
+                 :description "Add a block to a page"
+                 :inputSchema #js {:pageName (-> (z/string) (.describe "The page's name or uuid"))
+                                   :content (-> (z/string) (.describe "Block content"))
+                                   :force (-> (z/boolean)
+                                              (z/optional)
+                                              (.describe "Force given page to be created"))}}}
+   :updateBlock
+   {:fn api-update-block
+    :config #js {:title "Update Block"
+                 :description "Update block with new content"
+                 :inputSchema #js {:blockUUID (z/string)
+                                   :content (-> (z/string) (.describe "Block content"))}}}
+   :searchBlocks
+   {:fn api-search-blocks
+    :config #js {:title "Search Blocks"
+                 :description "Search graph for blocks containing search term"
+                 :inputSchema #js {:searchTerm (z/string)}}}
    :listTags
    {:fn api-list-tags
-    :config #js {:title "List Tags"}}
+    :config #js {:title "List Tags"
+                 :description "List all tags in a graph"}}
    :listProperties
    {:fn api-list-properties
-    :config #js {:title "List Properties"}}})
+    :config #js {:title "List Properties"
+                 :description "List all properties in a graph"}}})
 
 (defn call-api-tool [tool-fn api-fn args]
   (tool-fn (partial api-tool api-fn) args))

src/main/logseq/api.cljs

@@ -794,18 +794,24 @@
        {:block/uuid (sdk-utils/uuid-or-throw-error block-uuid) :repo repo}))))
 
 (def ^:export update_block
+  "Updates block with 3rd arg being a js map with following keys:
+   * :mcp - When set behaves as MCP tools expect
+   * :properties - A map of properties to update
+   * Remaining keys are passed to save-block!"
   (fn [block-uuid content ^js opts]
     (p/let [repo (state/get-current-repo)
             db-base? (config/db-based-graph? repo)
             block (<pull-block block-uuid)
             opts (bean/->clj opts)]
-      (when block
+      (if block
         (p/do!
          (when (and db-base? (seq (:properties opts)))
            (api-block/save-db-based-block-properties! block (:properties opts)))
          (editor-handler/save-block! repo
                                      (sdk-utils/uuid-or-throw-error block-uuid) content
-                                     (if db-base? (dissoc opts :properties) opts)))))))
+                                     (if db-base? (dissoc opts :properties) opts)))
+        (when (:mcp opts)
+          (throw (ex-info (str "Block " (pr-str block-uuid) " not found") {})))))))
 
 (def ^:export move_block
   (fn [src-block-uuid target-block-uuid ^js opts]
@@ -1077,23 +1083,34 @@
                       (insert_block target content (bean/->js opts)))))))))
 
 (defn ^:export append_block_in_page
+  "Append a block to a page and creates page if it does not exist.
+   If the 'mcp-options' opts key is set, this fn assumes MCP defaults by not creating a page unless explicitly
+   forced to. `opts` arg are options passed to `insert_block` except for
+   key the 'mcp-options', which has the following keys:
+   * :force - When set forces creation of nonexistent page"
   [uuid-or-page-name content ^js opts]
   (let [current-page? (or (and (nil? content) (nil? opts))
                           (and (nil? opts) (some->> content (instance? js/Object))))
         opts (if current-page? content opts)
+        mcp-options (bean/->clj (aget opts "mcp-options"))
         content (if current-page? uuid-or-page-name content)
         uuid-or-page-name (if current-page?
                             (or (state/get-current-page) (date/today))
                             uuid-or-page-name)]
     (p/let [_ (<ensure-page-loaded uuid-or-page-name)
             page? (not (util/uuid-string? uuid-or-page-name))
             page-not-exist? (and page? (nil? (db-model/get-page uuid-or-page-name)))
-            _ (and page-not-exist? (page-handler/<create! uuid-or-page-name
-                                                          {:redirect? false
-                                                           :format (state/get-preferred-format)}))]
-      (when-let [block (db-model/get-page uuid-or-page-name)]
+            _ (when (and page-not-exist?
+                         (or (nil? mcp-options)
+                             (:force mcp-options)))
+                (page-handler/<create! uuid-or-page-name
+                                       {:redirect? false
+                                        :format (state/get-preferred-format)}))]
+      (if-let [block (db-model/get-page uuid-or-page-name)]
         (let [target (str (:block/uuid block))]
-          (insert_block target content opts))))))
+          (insert_block target content opts))
+        (when mcp-options
+          (throw (ex-info (str "Page " (pr-str uuid-or-page-name) " not found") {})))))))
 
 ;; plugins
 (defn ^:export validate_external_plugins [urls]
@@ -1264,7 +1281,7 @@
 (defn ^:export search
   [q' & [opts]]
   (-> (search-handler/search (state/get-current-repo) q' (if opts (js->clj opts :keywordize-keys true) {}))
-      (p/then #(bean/->js %))))
+      (p/then #(bean/->js (sdk-utils/normalize-keyword-for-json %)))))
 
 ;; helpers
 (defn ^:export set_focused_settings