Skip to content
Back to search

modex

Modex is a Clojure MCP Library to augment your AI models with Tools, Resources & Prompts using Clojure (Model Context Protocol). Implements MCP Server & Client.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/theronic--modex/badge.svg)](/listings/theronic--modex)

HTML

<a href="/listings/theronic--modex"><img src="/api/listings/theronic--modex/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. `git clone git@github.com:theronic/modex.git` 2. `cd modex` 3. `./build.sh` builds an uberjar at `target/modex-mcp-0.2.2.jar`. 4. Open your Claude Desktop Config at `~/Library/Application\ Support/Claude/claude_desktop_config.json` 5. Configure a new MCP Server that will run the uberjar at its _full path_:

{
  "mcpServers": {
    "modex-mcp-hello-world": {
      "command": "java",
      "args": ["-jar", "/Users/your-username/code/modex/target/modex-mcp-0.2.2.jar"]
    }
  },
  "globalShortcut": ""
}

6. Restart Claude Desktop to activate your new MCP Server + tools :) (Cmd+R refresh does not reload config, only restarts tools) 7. Tell Claude to "run the inc tool with 123", authorize the tool and you should see an output of 124.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 324 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Modex: Model Context Protocol Server & Client Library in Clojure
  2. Modex (MOdel + ContEXt) is a Clojure library that lets you augment your AI with new tools, resources and prompts.
  3. Modex implements (most of) the [Model Context Protocol](https://modelcontextprotocol.io/) to build MCP Servers & Clients in 'native' Clojure.
  4. Because it's native Clojure, you don't need to deal with Anthropic's [MCP Java SDK](https://github.com/modelcontextprotocol/java-sdk).
  5. Modex implements the `stdio` transport in the 2024-11-05 MCP spec, so no need for a proxy like
  6. [mcp-proxy](https://github.com/sparfenyuk/mcp-proxy) to translate between SSE <=> stdio or vice versa.
  7. ## Screenshot of Modex in Action
  8. Claude Desktop can talk to a Modex MCP Server via its MCP client:
  9. <img width="650" alt="image" src="https://github.com/user-attachments/assets/ef83b8da-1816-48c0-aba6-47b4b5623f7a" />
  10. ## Table of Contents
  11. 1. [Quickstart](#quickstart)
  12. 2. [What is MCP?](#what-is-mcp)
  13. 3. [What can Modex do?](#what-can-modex-do)
  14. 4. [Detailed Step-by-Step Instructions](#detailed-step-by-step-instructions)
  15. 5. [Implementation](#implementation)
  16. 6. [Project Status](#project-status)
  17. 7. [Rationale](#rationale)
  18. 8. [FAQ](#faq)
  19. 9. [Licence](#licence)
  20. ## Example Tools
  21. - [Datomic MCP](https://github.com/theronic/datomic-mcp) uses Modex to expose Datomic tools so your models can query DB schema and data in dev or prod.
  22. ## Quickstart
  23. 1. `git clone git@github.com:theronic/modex.git`
  24. 2. `cd modex`
  25. 3. `./build.sh` builds an uberjar at `target/modex-mcp-0.2.2.jar`.
  26. 4. Open your Claude Desktop Config at `~/Library/Application\ Support/Claude/claude_desktop_config.json`
  27. 5. Configure a new MCP Server that will run the uberjar at its _full path_:
  28. ```json
  29. {
  30. "mcpServers": {
  31. "modex-mcp-hello-world": {
  32. "command": "java",
  33. "args": ["-jar", "/Users/your-username/code/modex/target/modex-mcp-0.2.2.jar"]
  34. }
  35. },
  36. "globalShortcut": ""
  37. }
  38. ```
  39. 6. Restart Claude Desktop to activate your new MCP Server + tools :) (Cmd+R refresh does not reload config, only restarts tools)
  40. 7. Tell Claude to "run the inc tool with 123", authorize the tool and you should see an output of 124.
  41. ## What is MCP?
  42. MCP lets you augment your AI models with Tools, Resources & Prompts:
  43. - **Tools** are things it can do, like query a database (e.g. Datomic).
  44. - **Resources** are files and data it can read, like PDF bank statements.
  45. - **Prompts** are templated messages and workflows.
  46. ## Use Cases
  47. Modex is used by [datomic-mcp](https://github.com/theronic/datomic-mcp), which exposes our production Datomic databases to an MCP client like Claude Desktop. The AI model intelligently diagnoses support queries in production by reading our database schema and running queries that checks server state & IPs, so it can try to reach it and compare the desired state of VMs against the actual state in our clusters.
  48. Over time, I hope to automate the bulk of our recurring support queries using Modex + other MCP tools.
  49. ## What can Modex do?
  50. ### Full Example
  51. There is an MCP server example in [src/modex/mcp/core.clj](src/modex/mcp/core.clj) that defines an MCP server with some basic tools.
  52. Your MCP client (e.g. Claude Desktop) can connect to this server and use exposed tools to provide additional context to your AI models.
  53. ## Data Structures
  54. ### Tools
  55. Internally, a tool is just `Tool` record with several `Parameter` arguments:
  56. - `(defrecord Tool [name doc args handler])`
  57. - `(defrecord Parameter [name doc type required default])`
  58. However, it is more convenient to define tools using the `tool` & `tools` macros below.
  59. ### Describe a single tool with the `tool` macro:
  60. The `tool` macro acts like `defrecord`, where the handler definition takes a map of arguments ala `{:keys [arg1 arg2 ...]}` but with additional (optional) maps for `:type`, `:or` & `:doc`. This metadata is used to describe the tool to the MCP Client.
  61. - The MCP spec currently only supports `:string` & `:number` tool parameter types.
  62. - Presence in the `:or` map implies optionality.
  63. - Missing parameter docstrings default to parameter name string.
  64. ```clojure
  65. (require '[modex.mcp.tools :as tools])
  66. (def add-tool
  67. (tools/tool
  68. ; feels like defrecord.
  69. (add [{:keys [x y]
  70. :type {x :number
  71. y :number}
  72. :or {y 0} ; y is optional due to its presence in the :or map.
  73. :doc {x "First number"
  74. y "Second number"}}]
  75. [(+ x y)]))) ; tools should return a vector (to support multiple values).
  76. ```
  77. ### Invoke a Tool with `invoke-tool` incl. validation:
  78. Invocation uses a map of arguments like an MCP client would for a `tools/call` request:
  79. ```clojure
  80. (tools/invoke-tool add-tool {:x 5 :y 6}) ; Modex will map these arguments and call the handler.
  81. => {:success true, :results [11]} ; note :results is vector to support multiple values.
  82. ```
  83. ### Invoke a tool handler directly to skip validation & error-handling:
  84. ```clojure
  85. (tools/invoke-handler (:handler add-tool) {:x 5 :y 6})
  86. => [11] ; note vector result to support multiple values.
  87. ```
  88. ### Define a Toolset with `tools` macro
  89. The `tools` macro just calls the `tool` macro for each tool definition and returns a map of tools keyed on tool name (keyword):
  90. ```clojure
  91. (def my-tools
  92. "Define your tools here."
  93. (tools/tools
  94. (greet
  95. "Greets a person by name." ; tools can have a docstring
  96. [{:keys [first-name last-name]
  97. :doc {first-name "A person's first name."
  98. last-name "A person's last name (optional)."}
  99. :type {first-name :string
  100. last-name :string}
  101. :or {last-name nil}}] ; last-name is optional, implied by presence in `:or` map.
  102. ; tools should return collection.
  103. [(str "Hello from Modex, "
  104. (if last-name ; args can be optional
  105. (str first-name " " last-name)
  106. first-name) "!")])
  107. (add
  108. "Adds two numbers."
  109. ; Tool handler args also support deprecated vector arg-style,
  110. ; but this is superseded by the newer map-destructuring style:
  111. [^{:type :number :doc "First number to add."} a
  112. ^{:type :number :doc "Second number to add."} b]
  113. [(+ a b)])
  114. (subtract
  115. "Subtracts two numbers (- a b)"
  116. [^{:type :number :doc "First number."} a
  117. ^{:type :number :doc "Second number."} b]
  118. [(- a b)])
  119. (error-handling
  120. "This tool throws intentionally. Modex will handle errors for you."
  121. []
  122. (throw (ex-info "Modex will handle exceptions." {})))))
  123. ```
  124. ### Create a Modex MCP Server + tools:
  125. ```clojure
  126. (require '[modex.mcp.server :as server])
  127. (def my-mcp-server
  128. "Here we create a reified instance of AServer. Only tools are presently supported."
  129. (server/->server
  130. {:name "Modex MCP Server"
  131. :version "0.0.2"
  132. :initialize (fn [_init-params] ; init-params, but may contain client capabilities in future.
  133. "Do long-running setup & blocking I/O here, like connecting to prod database.")
  134. :tools my-tools
  135. :prompts nil ; Prompts are WIP.
  136. :resources nil})) ; Resources are WIP.
  137. ```
  138. ### Start your MCP Server
  139. ```clojure
  140. (server/start-server! my-mcp-server)
  141. ```
  142. Or put that in your `-main` function.
  143. ### Protocols
  144. Modex exposes an `AServer` protocol and a DSL to define tools protocols that describe MCP servers, which expose tools, resources & prompts.
  145. AServer Protocol:
  146. ```clojure
  147. (defprotocol AServer
  148. (protocol-version [this])
  149. (server-name [this])
  150. (version [this])
  151. (capabilities [this])
  152. (initialize [this _init-params]) ; init-params is empty for now, but may contain client capabilities in future.
  153. (list-tools [this])
  154. (call-tool [this tool-name arg-map])
  155. (list-resources [this])
  156. (list-prompts [this]))
  157. ```
  158. ## Detailed Step-by-Step Instructions
  159. ### Step 1: Build the Uberjar
  160. Before you can run it, you have to build it first. The build outputs an uberjar, which is like a Java executable.
  161. ```bash
  162. clojure -T:build uber
  163. ```
  164. or run the helper which does that:
  165. ```bash
  166. ./build.sh
  167. ```
  168. (you might need to run `chmod +x build.sh`)
  169. ### Step 2: Open Claude Desktop Config
  170. Open your Claude Desktop Configuration file, `claude_desktop_config.json`, which on MacOS should be at:
  171. ~/Library/Application\ Support/Claude/claude_desktop_config.json
  172. ### Step 3: Configure your MCP Server
  173. Add an element under `mcpServers` so it looks like this:
  174. ```json
  175. {
  176. "mcpServers": {
  177. "modex": {
  178. "command": "java",
  179. "args": ["-jar", "/Users/your-username/code/modex/target/modex-mcp-0.2.2.jar"]
  180. }
  181. },
  182. "globalShortcut": ""
  183. }
  184. ```
  185. This tells Claude Desktop there is a tool named `modex` and it can connect to by running `java -jar /path/to/your/uber.jar`.
  186. The way this works is that your local MCP Client (i.e. Claude Desktop), starts your MCP server process and communicates with it via stdin/stdout pipes.
  187. ### Step 4: Restart Claude Desktop
  188. You should now be able to ask Claude "run foo", or "what does foo say?" and it will run
  189. the `foo` tool and reply with the response, "Hello, AI!".
  190. ## Implementation
  191. Modex implements an MCP client & server in Clojure that is _mostly_ compliant with the [2024-11-05 MCP Spec](https://spec.modelcontextprotocol.io/specification/2024-11-05/).
  192. Messages are encoded using the JSON-RPC 2.0 wire format.
  193. There are 3 message types:
  194. - Requests have `{:keys [id method ?params]}`
  195. - Responses have `{:keys [id result ?error]}`
  196. - Notifications have `{:keys [method ?params}`
  197. MCP supports two transport types:
  198. - [x] stdio/stdout – implemented in Modex.
  199. - [ ] Server-Sent Events (SSE) – not implemented yet. Useful for restricted networks
  200. ## Project Status
  201. - [x] Passing tests
  202. - [x] Ergonomics (AServer / AClient protocol?)
  203. - [x] Tools
  204. - [x] nREPL for live changes to running process
  205. - [ ] Resources
  206. - [ ] Prompts
  207. - [in progress] SSE support
  208. - [in progress] Streaming HTTP Support (2025-03-26 MCP spec)
  209. ## Rationale
  210. There is an existing library [mcp-clj](https://github.com/hugoduncan/mcp-clj) that uses SSE, so it requires mcp-proxy to proxy from SSE <=> stdio. I was annoyed by this, so I made Modex.
  211. ## FAQ
  212. ### Can I modify the server while an MCP Client (like Claude Desktop) is connected?
  213. Not yet, but I'll add an nREPL soon so you can eval changes while Claude Desktop is connected to the process without rebuilding the uberjar.
  214. Btw. I tried to get it to run `clojure -M -m modex.mcp.server`, but you can't set Claude Desktop's working directory.
  215. So currently, I rebuild the uberjar and restart Claude Desktop. Will fix.
  216. ## Thank You To Paid Modex Customers:
  217. - [Nextdoc](https://nextdoc.io/) – Document Streaming for Salesforce
  218. - [Huppi](https://www.huppi.io/) — Small Business Accounting Software
  219. ## License
  220. In summary:
  221. - **Free for non-commercial use**: Use it, modify it, share it under [GPLv3](https://www.gnu.org/licenses/gpl-3.0.html) at no cost, just keep it open source.
  222. - **Commercial use**: Want to keep your changes private? Pay $20 once-off for a perpetual commercial license. This covers the cost of my AI tokens to keep building this in public.
  223. This tool is licensed under the [GNU General Public License v3.0 (GPLv3)](https://www.gnu.org/licenses/gpl-3.0.html). You are free to use, modify, and distribute it, provided that any derivative works are also licensed under the GPLv3 and made open source. This ensures the tool remains freely available to the community while requiring transparency for any changes.
  224. If you wish to use or modify this tool in a proprietary project—without releasing your changes under the GPLv3—you
  225. may purchase a commercial license. This allows you to keep your modifications private for personal or commercial use.
  226. To obtain a commercial license, please contact me at [modex@petrus.co.za](mailto:modex@petrus.co.za).
  227. ## Author(s)
  228. - [Petrus Theron](http://petrustheron.com)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.