Added docstrings with the help of Claude. There might be some minor mistakes here and there, will need a full review before a non-alpha release.

Author: green-coder

deps.edn

@@ -15,4 +15,11 @@
 
            ;; clojure -M:outdated --upgrade
            :outdated {:extra-deps {com.github.liquidz/antq {:mvn/version "2.11.1276"}}
-                      :main-opts  ["-m" "antq.core"]}}}
+                      :main-opts  ["-m" "antq.core"]}
+
+           ;; Starts a nREPL server on port 7888 so that the Clojure-MCP tool can work on that codebase
+           ;; clojure -M:nrepl
+           :nrepl {:extra-paths ["test"]
+                   :extra-deps {nrepl/nrepl {:mvn/version "1.3.1"}}
+                   :jvm-opts ["-Djdk.attach.allowAttachSelf"]
+                   :main-opts ["-m" "nrepl.cmdline" "--port" "7888"]}}}

src/mcp_toolkit/client.cljc

@@ -5,27 +5,72 @@
             [mcp-toolkit.impl.common :refer [user-callback]]
             [promesa.core :as p]))
 
-(defn request-set-logging-level [context level]
+(defn request-set-logging-level
+  "Sets the logging level on the MCP server.
+   (see https://modelcontextprotocol.io/specification/2025-06-18/server/utilities/logging#log-levels)
+
+   Args:
+     context - The client session context
+     level   - Logging level, accepted values are \"debug\", \"info\", \"notice\", \"warning\", \"error\", \"critical\", \"alert\" and \"emergency\"
+
+   Returns:
+     A promise that resolves when the server acknowledges the level change."
+  [context level]
   (json-rpc/call-remote-method context {:method "logging/setLevel"
                                         :params {:level level}}))
 
-(defn request-complete-prompt-param [context prompt-name
-                                     param-name param-value]
+(defn request-complete-prompt-param
+  "Requests autocompletion for a prompt parameter from the MCP server.
+   (see https://modelcontextprotocol.io/specification/2025-06-18/server/utilities/completion#data-types)
+
+   Args:
+     context      - The client session context
+     prompt-name  - Name of the prompt to complete
+     param-name   - Name of the parameter to complete
+     param-value  - Current partial value of the parameter
+
+   Returns:
+     A promise that resolves to completion suggestions from the server."
+  [context prompt-name
+   param-name param-value]
   (json-rpc/call-remote-method context {:method "completion/complete"
                                         :params {:ref {:type "ref/prompt"
                                                        :name prompt-name}
                                                  :argument {:name param-name
                                                             :value param-value}}}))
 
-(defn request-complete-resource-uri [context uri-template
-                                     param-name param-value]
+(defn request-complete-resource-uri
+  "Requests autocompletion for a resource URI parameter from the MCP server.
+   (see https://modelcontextprotocol.io/specification/2025-06-18/server/utilities/completion#data-types)
+
+   Args:
+     context      - The client session context
+     uri-template - URI template to complete
+     param-name   - Name of the parameter to complete
+     param-value  - Current partial value of the parameter
+
+   Returns:
+     A promise that resolves to completion suggestions from the server."
+  [context uri-template
+   param-name param-value]
   (json-rpc/call-remote-method context {:method "completion/complete"
                                         :params {:ref {:type "ref/resource"
                                                        :uri uri-template}
                                                  :argument {:name param-name
                                                             :value param-value}}}))
 
-(defn request-prompt-list [context]
+(defn request-prompt-list
+  "Requests the list of available prompts from the MCP server.
+   Updates the session's server-prompt-by-name index and calls the
+   on-server-prompt-list-updated callback.
+   (see https://modelcontextprotocol.io/specification/2025-06-18/server/prompts#listing-prompts)
+
+   Args:
+     context - The client session context
+
+   Returns:
+     A promise that resolves when prompts are fetched and stored."
+  [context]
   (let [{:keys [session]} context
         {:keys [server-capabilities]} @session]
     (when (contains? server-capabilities :prompts)
@@ -34,12 +79,34 @@
                     (swap! session assoc :server-prompt-by-name (mc/index-by :name prompts))
                     ((user-callback :on-server-prompt-list-updated) context)))))))
 
-(defn request-prompt [context prompt-name arguments]
+(defn request-prompt
+  "Requests a specific prompt from the MCP server with given arguments.
+  (see https://modelcontextprotocol.io/specification/2025-06-18/server/prompts#getting-a-prompt)
+
+   Args:
+     context     - The client session context
+     prompt-name - Name of the prompt to retrieve
+     arguments   - Map of arguments to pass to the prompt
+
+   Returns:
+     A promise that resolves to the prompt response from the server."
+  [context prompt-name arguments]
   (json-rpc/call-remote-method context {:method "prompts/get"
                                         :params {:name prompt-name
                                                  :arguments arguments}}))
 
-(defn request-resource-list [context]
+(defn request-resource-list
+  "Requests the list of available resources from the MCP server.
+   Updates the session's server-resource-by-uri index and calls the
+   on-server-resource-list-updated callback.
+   (see https://modelcontextprotocol.io/specification/2025-06-18/server/resources#listing-resources)
+
+   Args:
+     context - The client session context
+
+   Returns:
+     A promise that resolves when the resource descriptions are fetched and stored."
+  [context]
   (let [{:keys [session]} context
         {:keys [server-capabilities]} @session]
     (when (contains? server-capabilities :resources)
@@ -48,23 +115,72 @@
                     (swap! session assoc :server-resource-by-uri (mc/index-by :uri resources))
                     ((user-callback :on-server-resource-list-updated) context)))))))
 
-(defn request-resource [context resource-uri]
+(defn request-resource
+  "Requests a specific resource from the MCP server by URI.
+   (see https://modelcontextprotocol.io/specification/2025-06-18/server/resources#reading-resources)
+
+   Args:
+     context      - The client session context
+     resource-uri - URI of the resource to retrieve
+
+   Returns:
+     A promise that resolves to the resource content from the server."
+  [context resource-uri]
   (json-rpc/call-remote-method context {:method "resources/read"
                                         :params {:uri resource-uri}}))
 
-(defn request-resource-template-list [context]
+(defn request-resource-template-list
+  "Requests the list of available resource templates from the MCP server.
+   (see https://modelcontextprotocol.io/specification/2025-06-18/server/resources#resource-templates)
+
+   Args:
+     context - The client session context
+
+   Returns:
+     A promise that resolves to the list of resource templates."
+  [context]
   (json-rpc/call-remote-method context {:method "resources/templates/list"}))
 
+(defn request-subscribe-resource
+  "Subscribes to changes for a specific resource on the MCP server.
+   (see https://modelcontextprotocol.io/specification/2025-06-18/server/resources#subscriptions)
 
-(defn request-subscribe-resource [context resource-uri]
+   Args:
+     context      - The client session context
+     resource-uri - URI of the resource to subscribe to
+
+   Returns:
+     A promise that resolves when subscription is confirmed."
+  [context resource-uri]
   (json-rpc/call-remote-method context {:method "resources/subscribe"
                                         :params {:uri resource-uri}}))
 
-(defn request-unsubscribe-resource [context resource-uri]
+(defn request-unsubscribe-resource
+  "Unsubscribes from changes for a specific resource on the MCP server.
+   (see https://modelcontextprotocol.io/specification/2025-06-18/server/resources#subscriptions)
+
+   Args:
+     context      - The client session context
+     resource-uri - URI of the resource to unsubscribe from
+
+   Returns:
+     A promise that resolves when unsubscription is confirmed."
+  [context resource-uri]
   (json-rpc/call-remote-method context {:method "resources/unsubscribe"
                                         :params {:uri resource-uri}}))
 
-(defn request-tool-list [context]
+(defn request-tool-list
+  "Requests the list of available tools from the MCP server.
+   Updates the session's server-tool-by-name index and triggers the
+   on-server-tool-list-updated callback.
+   (see https://modelcontextprotocol.io/specification/2025-06-18/server/tools#listing-tools)
+
+   Args:
+     context - The client session context
+
+   Returns:
+     A promise that resolves when the tool descriptions are fetched and stored."
+  [context]
   (let [{:keys [session]} context
         {:keys [server-capabilities]} @session]
     (when (contains? server-capabilities :prompts)
@@ -73,19 +189,60 @@
                     (swap! session assoc :server-tool-by-name (mc/index-by :name tools))
                     ((user-callback :on-server-tool-list-updated) context)))))))
 
-(defn request-tool-invocation [context tool-name arguments]
+(defn request-tool-invocation
+  "Invokes a specific tool on the MCP server with given arguments.
+   (see https://modelcontextprotocol.io/specification/2025-06-18/server/tools#calling-tools)
+
+   Args:
+     context   - The client session context
+     tool-name - Name of the tool to invoke
+     arguments - Map of arguments to pass to the tool
+
+   Returns:
+     A promise that resolves to the tool execution result."
+  [context tool-name arguments]
   (json-rpc/call-remote-method context {:method "tools/call"
                                         :params {:name tool-name
                                                  :arguments arguments}}))
 
-(defn notify-cancel-request [context request-id]
+(defn notify-cancel-request
+  "Sends a cancellation notification for a specific request to the MCP server.
+   (see https://modelcontextprotocol.io/specification/2025-06-18/basic/utilities/cancellation#cancellation-flow)
+
+   Args:
+     context    - The client session context
+     request-id - ID of the request to cancel
+    
+   Returns:
+     nil"
+  [context request-id]
   (json-rpc/send-message context (json-rpc/notification "cancelled"
                                                         {:requestId request-id})))
 
-(defn notify-root-list-updated [context]
+(defn notify-root-list-updated
+  "Notifies the MCP server that the client's root list has been updated.
+   (see https://modelcontextprotocol.io/specification/2025-06-18/client/roots#root-list-changes)
+
+   Args:
+     context - The client session context
+
+   Returns:
+     nil"
+  [context]
   (json-rpc/send-message context (json-rpc/notification "roots/list_changed")))
 
-(defn send-first-handshake-message [context]
+(defn send-first-handshake-message
+  "Sends the initial handshake message to establish the MCP connection.
+   Initializes the session with server capabilities and triggers the on-initialized callback
+   upon receiving the server's response.
+   (see https://modelcontextprotocol.io/specification/2025-06-18/architecture#capability-negotiation)
+
+   Args:
+     context - The client session context
+
+   Returns:
+     nil"
+  [context]
   (let [{:keys [session]} context
         {:keys [client-info
                 client-capabilities