Modex

🚀 Modex Introduction

Modex is an MCP (Model Context Protocol) client and server implemented in Clojure, mostly compliant with the 2024-11-05 MCP Specification. Messages use the JSON-RPC 2.0 serialization format.

✨ Features

• Communication Protocol: Supports two transmission types:

  • [x] Standard Input/Output (stdio/stdout)
  • [ ] Server-Sent Events (SSE)

• Key Components:

  • MCP Client: Interacts with the MCP server via stdio.
  • MCP Server: Implements the AServer protocol, supporting tools, resources, and prompts.

🚀 Quick Start

1. Build Modex

   lein project
   

2. Run the MCP Server

   clojure -m modex.mcp.server
   

3. Configure Claude Desktop

   Open claude_desktop_config.json and add the following content:

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

4. Restart Claude Desktop. Now you can use run foo or what does foo say? to invoke tools.

💻 Usage Examples

Basic Usage

(defmodex :foo
  (defmethod handle-tool-call :default
    [tool-id args]
    {:result "Hello, AI!"}))

When you call run foo or what does foo say?, Claude Desktop will send the following JSON-RPC request:

{
  "id": 1,
  "method": "tool/default",
  "params": {
    "toolId": ":foo"
  }
}

The server returns the response:

{
  "id": 1,
  "result": "Hello, AI!"
}

🔧 Technical Details

• Tools

  • Define tools using defmodex.
  • Use handle-tool-call as the handling method.

• Message Format

  • Request: {:keys [id method ?params]}
  • Response: {:keys [id result ?error]}
  • Notification: {:keys [method ?params]}

📚 Documentation

Core Components

• Modex Server

  • Implements the AServer protocol.
  • Supports tools, resources, and prompts.

• MCP Client (e.g., Claude Desktop)

  • Interacts with the MCP server using standard input and output.

Project Status

• [x] Passed tests
• [x] Ease of use (AServer/A Client protocol)
• [x] Tool support
• [ ] Resource support
• [ ] Prompt support
• [In progress] SSE support
• [In progress] Streaming HTTP support (2025-03-26 MCP Specification)

Development Background

The existing library mcp-clj uses SSE, so an mcp-proxy is required to proxy SSE <=> stdio. Modex aims to simplify this process.

Frequently Asked Questions

• How can I modify the server on a connected MCP client (e.g., Claude Desktop)?

  Currently, direct modification is not possible. However, nREPL support is planned to allow real-time evaluation of code changes without stopping the service. Due to limitations, you currently need to rebuild the uberjar and restart Claude Desktop.

Acknowledgments

The development of Modex is funded by the following paying customers:

• Nextdoc - A Salesforce tool providing document streaming services.
• Huppi - Accounting software for small businesses.

📄 License

• Free for non-commercial use: Use, modify, and distribute under GPLv3, as long as it remains open source.
• Commercial use: Users who wish to use the modified version privately can purchase a perpetual commercial license for a one-time payment of $20. This covers the cost of AI computer tokens used in public development.

This tool is distributed under the GNU General Public License v3.0 (GPLv3). You have the right to use, modify, and distribute it freely, subject to the terms of the license.

Authors

• Alex Petrov - Initial version
• Andrey Vasilyev - Current maintainer

Thank you for your attention!