Fix STDIO MCP server deadlock caused by list_changed notification handlers blocking the reader thread

Author: ericdallo

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## Unreleased
 
+- Fix STDIO MCP server deadlock caused by list_changed notification handlers blocking the reader thread.
 - Consider Anthropic internal server error as a retriable error.
 - Improve MCP error logging to show error code, message, and data instead of null.
 - Improve error handling when MCP promtps fail on server side.

deps-lock.json

@@ -982,6 +982,16 @@
       "mvn-repo": "https://repo.clojars.org/",
       "hash": "sha256-Xe66kz8gwkNNCBozUpigMJuTl2+p1ZQc+QwEgldebZA="
     },
+    {
+      "mvn-path": "dev/ericdallo/rewrite-json/0.1.1/rewrite-json-0.1.1.jar",
+      "mvn-repo": "https://repo.clojars.org/",
+      "hash": "sha256-1XnFTWANPTA8jRfrz/gP7V3MMQ0ht4tJIBDCI5vuOb8="
+    },
+    {
+      "mvn-path": "dev/ericdallo/rewrite-json/0.1.1/rewrite-json-0.1.1.pom",
+      "mvn-repo": "https://repo.clojars.org/",
+      "hash": "sha256-smGEfZ7nI45VkdHtuZVDmdoXvEXU3xcgK1Q5kGfJfYQ="
+    },
     {
       "mvn-path": "expound/expound/0.9.0/expound-0.9.0.jar",
       "mvn-repo": "https://repo.clojars.org/",

src/eca/features/tools/mcp.clj

@@ -137,28 +137,50 @@
                                       (logger/info logger-tag (format "[%s] %s" server-name msg)))})
        :needs-reinit?* nil})))
 
+(defn ^:private non-blocking-handler
+  "Wraps a notification handler so it runs on a separate thread.
+  Prevents STDIO transport deadlock where the reader thread blocks on a
+  synchronous fetch request inside a notification handler, making it
+  unable to read incoming responses."
+  [f]
+  (pcs/wrap-initialized-check
+   (fn [jsonrpc-notification]
+     (future (f jsonrpc-notification)))))
+
 (defn ^:private ->client [name transport init-timeout workspaces
                           {:keys [on-tools-change]}]
   (let [tools-consumer (fn [tools]
                          (logger/info logger-tag
                                       (format "[%s] Tools list changed, received %d tools"
                                               name (count tools)))
                          (on-tools-change tools))
-        tools-nhandler (pcs/wrap-initialized-check
-                        (fn [jsonrpc-notification]
-                          (pcs/fetch-tools jsonrpc-notification
-                                           {:on-tools tools-consumer})))
         client (pmc/make-mcp-client
                 {:info (pes/make-info name "current")
                  :client-transport transport
                  :primitives {:roots (mapv #(pcap/make-root-item (:uri %)
                                                                  {:name (:name %)})
                                            workspaces)}
                  :notification-handlers
-                 {psd/method-notifications-tools-list_changed tools-nhandler
-                  psd/method-notifications-message (fn [params]
-                                                     (logger/info logger-tag
-                                                                  (format "[MCP-%s] %s" name (:data params))))}
+                 {psd/method-notifications-tools-list_changed
+                  (non-blocking-handler
+                   (fn [notification]
+                     (pcs/fetch-tools notification
+                                      {:on-tools tools-consumer})))
+
+                  psd/method-notifications-resources-list_changed
+                  (non-blocking-handler
+                   (fn [notification]
+                     (pcs/fetch-resources notification)))
+
+                  psd/method-notifications-prompts-list_changed
+                  (non-blocking-handler
+                   (fn [notification]
+                     (pcs/fetch-prompts notification)))
+
+                  psd/method-notifications-message
+                  (fn [params]
+                    (logger/info logger-tag
+                                 (format "[MCP-%s] %s" name (:data params))))}
                  :print-banner? false})]
     (pmc/initialize-and-notify! client
                                 {:timeout-millis (* 1000 init-timeout)})