{"id":26011498,"url":"https://github.com/theronic/modex","last_synced_at":"2025-06-20T22:40:13.999Z","repository":{"id":280863395,"uuid":"943164754","full_name":"theronic/modex","owner":"theronic","description":"Modex: Model Context Protocol Server \u0026 Client in Native Clojure","archived":false,"fork":false,"pushed_at":"2025-03-05T18:19:44.000Z","size":12,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-05T18:41:23.842Z","etag":null,"topics":["clojure","mcp","mcp-client","mcp-server","model-context-protocol"],"latest_commit_sha":null,"homepage":"http://petrustheron.com/","language":"Clojure","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/theronic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-05T09:16:40.000Z","updated_at":"2025-03-05T18:19:47.000Z","dependencies_parsed_at":"2025-03-05T18:41:26.161Z","dependency_job_id":"6ffb7add-c829-40fc-b177-2344540d9680","html_url":"https://github.com/theronic/modex","commit_stats":null,"previous_names":["theronic/modex"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theronic%2Fmodex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theronic%2Fmodex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theronic%2Fmodex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theronic%2Fmodex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/theronic","download_url":"https://codeload.github.com/theronic/modex/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242121315,"owners_count":20075088,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["clojure","mcp","mcp-client","mcp-server","model-context-protocol"],"created_at":"2025-03-05T23:28:19.556Z","updated_at":"2025-03-05T23:28:20.006Z","avatar_url":"https://github.com/theronic.png","language":"Clojure","funding_links":[],"categories":["📚 Projects (1974 total)","Reference Implementations \u0026 Examples"],"sub_categories":["MCP Servers"],"readme":"# Modex: Model Context Protocol Server \u0026 Client in Clojure\n\nModex (MOdel + ContEXt) is a native Clojure implementation of the [Model Context Protocol](https://modelcontextprotocol.io/) that lets you augment your AI with new tools, resources and prompts.\n\nBecause it's native Clojure, you don't need to deal with Anthropic's [MCP Java SDK](https://github.com/modelcontextprotocol/java-sdk).\n\nModex implements the `stdio` transport, so no need for a proxy like\n[mcp-proxy](https://github.com/sparfenyuk/mcp-proxy) to translate between SSE \u003c=\u003e stdio or vice versa.\n\n## Table of Contents\n\n1. [Quickstart](#quickstart)\n2. [What is MCP?](#what-is-mcp)\n3. [What can Modex do?](#what-can-modex-do)\n4. [Detailed Step-by-Step Instructions](#detailed-step-by-step-instructions)\n5. [Implementation](#implementation)\n6. [Project Status](#project-status)\n7. [Rationale](#rationale)\n8. [FAQ](#faq)\n9. [Licence](#licence)\n\n## Quickstart\n\n1. `git clone git@github.com:theronic/modex.git`\n2. `cd modex`\n3. `./build.sh` builds an uberjar at `target/modex-mcp-server-0.1.0.jar`.\n4. Open your Claude Desktop Config at `~/Library/Application\\ Support/Claude/claude_desktop_config.json`\n5. Configure a new MCP Server that will run the uberjar at its _full path_:\n\n```json\n{\n  \"mcpServers\": {\n    \"modex-mcp-hello-world\": {\n      \"command\": \"java\",\n      \"args\": [\"-jar\", \"/Users/your-username/code/modex/target/modex-mcp-server-0.1.0.jar\"]\n    }\n  },\n  \"globalShortcut\": \"\"\n}\n```\n\n6. Restart Claude Desktop to activate your new MCP Server + tools :)\n\n## What is MCP?\n\nMCP lets you augment your AI models with Tools, Resources \u0026 Prompts:\n\n- **Tools** are things it can do, like query a database (e.g. Datomic).\n- **Resources** are files and data it can read, like PDF bank statements.\n- **Prompts** are templated messages and workflows.\n\nFor example, you could make a tool that fetches purchases from your bank's API and let the AI categorize your expenses, and then use another tool to write those expense categories to your accounting system, or to a database. Pretty cool.\n\n## What can Modex do?\n\nThe Modex skeleton exposes a single tool named `foo` that answers an MCP Client (like your LLM), with:\n\n```clojure\n{:content [{:type \"text\"\n            :text \"Hello, AI!\" \n            :isError false}]}\n```\n\nYour MCP client (e.g. Claude Desktop) can connect to this server and use exposed tools to provide additional context to your AI models.\n\n## Detailed Step-by-Step Instructions\n\n### Step 1: Build the Uberjar\n\nBefore you can run it, you have to build it first. The build outputs an uberjar, which is like a Java executable.\n\n```bash\nclojure -T:build uber\n```\n\nor run the helper which does that:\n```bash\n./build.sh\n```\n(you might need to run `chmod +x build.sh`)\n\n### Step 2: Open Claude Desktop Config\n\nOpen your Claude Desktop Configuration file, `claude_desktop_config.json`, which on MacOS should be at:\n\n    ~/Library/Application\\ Support/Claude/claude_desktop_config.json\n\n### Step 3: Configure your MCP Server\n\nAdd an element under `mcpServers` so it looks like this:\n\n```json\n{\n  \"mcpServers\": {\n    \"modex-mcp-hello-world\": {\n      \"command\": \"java\",\n      \"args\": [\"-jar\", \"/Users/your-username/code/modex/target/modex-mcp-server-0.1.0.jar\"]\n    }\n  },\n  \"globalShortcut\": \"\"\n}\n```\n\nThis tells Claude Desktop there is a tool named `modex-mcp-hello-world` and it can connect to by running `java -jar /path/to/your/uber.jar`.\n\nThe 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.\n\n### Step 4: Restart Claude Desktop\n\nYou should now be able to ask Claude \"run foo\", or \"what does foo say?\" and it will run\nthe `foo` tool and reply with the response, \"Hello, AI!\".\n\n## Implementation\n\nModex implements an MCP client \u0026 server in Clojure that is _mostly_ compliant with the [2024-11-05 MCP Spec](https://spec.modelcontextprotocol.io/specification/2024-11-05/).\n\nMessages are encoded using the JSON-RPC 2.0 wire format. \n\nThere are 3 message types:\n- Requests have `{:keys [id method ?params]}`\n- Responses have `{:keys [id result ?error]}`\n- Notifications have `{:keys [method ?params}`\n\nMCP supports two transport types:\n- [x] stdio/stdout – implemented in Modex.\n- [ ] Server-Sent Events (SSE) – not implemented yet. Useful for restricted networks\n\n## Project Status\n\n- [x] Passing tests\n- [ ] Ergonomics (AServer / AClient protocol?)\n- [ ] nREPL for live changes to running process\n- [ ] SSE support\n\n## Rationale\n\nThere is an existing library [mcp-clj](https://github.com/hugoduncan/mcp-clj) that uses SSE, so it requires mcp-proxy to proxy from SSE \u003c=\u003e stdio. I was annoyed by this, so I made Modex.\n\n## FAQ\n\n### Can I modify the server while an MCP Client (like Claude Desktop) is connected?\n\nNot 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.\n\nBtw. I tried to get it to run `clojure -M -m modex.mcp.server`, but you can't set Claude Desktop's working directory.\n\nSo currently, I rebuild the uberjar and restart Claude Desktop. Will fix.\n\n## License \n\nIn summary:\n- **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.\n- **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.\n\nThis 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.\n\nIf you wish to use or modify this tool in a proprietary project—without releasing your changes under the GPLv3—you \nmay purchase a commercial license. This allows you to keep your modifications private for personal or commercial use.\nTo obtain a commercial license, please contact me at [modex@petrus.co.za](mailto:modex@petrus.co.za).\n\n## Author(s)\n\n- [Petrus Theron](http://petrustheron.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheronic%2Fmodex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftheronic%2Fmodex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheronic%2Fmodex/lists"}