Add some documentation.

Author: green-coder

.github/workflows/cljdoc.yml

@@ -0,0 +1,31 @@
+name: CljDoc
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+
+  check-cljdoc:
+
+    name: Check source code
+
+    timeout-minutes: 60
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Clojure
+        uses: DeLaGuardo/setup-clojure@master
+        with:
+          cli: latest
+
+      - name: Build the jar and update pom.xml's version
+        run: clojure -X:jar && mkdir target && mv *.jar target/
+
+      - name: CljDoc Check
+        uses: cljdoc/[email protected]

CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+
+Versions prior to v0.1.0 are considered experimental, their API may change.
+
+## [Unreleased]

deps.edn

@@ -22,4 +22,13 @@
            :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"]}}}
+                   :main-opts ["-m" "nrepl.cmdline" "--port" "7888"]}
+
+           :jar  {:replace-deps {com.github.seancorfield/depstar {:mvn/version "2.1.303"}}
+                  :exec-fn      hf.depstar/jar
+                  :exec-args    {:sync-pom    true
+                                 :group-id    "fi.metosin"
+                                 :artifact-id "mcp-toolkit"
+                                 :version     "0.0.1"
+                                 :jar         "mcp-toolkit.jar"}}}}
+

doc/SUMMARY.md

@@ -0,0 +1,8 @@
+# Summary
+
+[Introduction](introduction.md)
+[API Design](api-design.md)
+[The session atom](session.md)
+[The context hashmap](context.md)
+[Using the library](using-the-library.md)
+[REPL story](repl-story.md)

doc/api-design.md

@@ -0,0 +1,18 @@
+## API Design
+
+MCP-toolkit is used in a client-server architecture, the client typically being an agentic AI,
+and the server typically being an MCP server in Clojure.
+
+The namespace `mcp-toolkit.client` is for implementing a MCP client, it is designed to communicate with a MCP server.
+The namespace `mcp-toolkit.server` is for implementing a MCP server, it is designed to communicate with a MCP client.
+If you want to implement a MCP proxy, you can use both.
+
+The API design is the same in both namespaces:
+- The state representing the communication with the remote site is in an atom called `session`.
+- A hashmap `context` contains the `session` and a few other things related to interfacing with the transport layout.
+- The `context` is passed as the first parameter of most of functions in the API.
+- The `session` contains some callbacks which are called when receiving certain kind of messages from the MCP protocol.
+  By default some of the callbacks are pointing to provided function which implement a default behavior.
+  If the user wants to customize the behavior, s/he can do it at the creation of the session value.
+- All the message handlers are assumed to either return a value to be immediately sent as `:result` to the caller, or
+  to return a Promesa promise which will resolve to that value later, asynchronously.

doc/cljdoc.edn

@@ -0,0 +1,8 @@
+{:cljdoc.doc/tree [["Readme"            {:file "README.md"}]
+                   ["Changes"           {:file "CHANGELOG.md"}]
+                   ["Introduction"      {:file "doc/introduction.md"}]
+                   ["API design"        {:file "doc/api-design.md"}]
+                   ["Session"           {:file "doc/session.md"}]
+                   ["Context"           {:file "doc/context.md"}]
+                   ["Using the library" {:file "doc/using-the-library.md"}]
+                   ["REPL story"        {:file "doc/repl-story.md"}]]}

doc/context.md

@@ -0,0 +1,17 @@
+## The context hashmap
+
+The context hashmap contains:
+- The session atom
+- Some I/O related functions which are use-case specific and that the user has to provide.
+- The `:send-message` function 
+- The `:close-connection` function
+
+The context hashmap is also used for passing the current message to be processed to the event handlers.
+
+### Context vs. session
+
+The difference between the `context` and the `session` is that the `session` is a mutable state (an atom) being shared by all the event handlers,
+while the `context` is an immutable Clojure value contains contextual information, like the current message being processed.
+
+You can add your own data in either the `context` or the `session` if it makes sense for you,
+all the message handlers and the user callbacks are called with the context as their first (and only) argument.

doc/introduction.md

@@ -0,0 +1,10 @@
+## Introduction
+
+MCP-toolkit is a library for interfacing Clojure code with the MCP protocol.
+
+It provides a structure for:
+- registering and unregistering your prompts, resources, tools, roots, etc ...
+- making them discoverable and invocable to the remote site
+- updating their presence or lack of
+- sending notifications to the remote site when they are updated
+- experimenting and developing MCP tools from a REPL session while a they are being served

doc/repl-story.md

@@ -0,0 +1,12 @@
+## REPL story
+
+When your client or your server is running, connect to it via a REPL using the method of your choice.
+
+On the server side, you can register or unregister resources using:
+- `add-prompt`, `remove-prompt`, `add-resource`, `remove-resource`, `add-tool`, `remove-tool`, `set-resource-templates` and `set-resource-uri-complete-fn`
+  which will mutate the session atom and notify the client about the changes.
+
+On the client side, you can do the same using `add-root` and `remove-root`.
+
+For all of those above functions, you need to pass the context as the first argument.
+To make it accessible from the root level in your Clojure program, depending on your setup, it may be handing to have a root-level atom referring to it.

doc/session.md

@@ -0,0 +1,14 @@
+## The session atom
+
+A session is typically created using the function `mcp-toolkit.client/create-session` or `mcp-toolkit.client/create-session`.
+
+It contains:
+- The `:initialized` boolean, becomes true after the initial handshake between the client and server.
+- The `:protocol-version` used, initialized after the initial handshake.
+- `:client-capabilities` / `:server-capabilities` listing what features the remote site supports.
+- Some data about the ongoing Remote Method Calls, waiting for a response.
+- The locally registered resources and a maintained collection of the resources available on the remote site.
+- The callbacks starting with `:on-`, triggered on events, some of them directly being some types of messages.
+  Some of them are defaulting to a built-in behavior which maintain the collection of resources available on the remote site.
+
+The session atom can be modified from the message handlers.