modex

Modex is a native Clojure implementation of an MCP server and client toolkit. It exposes a set of tools, prompts, and resources that you can hook into an MCP client (for example Claude Desktop) to augment AI models with additional capabilities such as database access, file reading, or custom workflows. The server is provided as an uberjar built from the Modex project, and you run it as a standard Java application. Clients connect to the server to invoke defined tools by name and pass arguments in a structured map; responses are returned in a consistent, machine-readable form that enables chaining tools and prompts during AI reasoning.

To use Modex, start the server (via the provided Uberjar) and configure your MCP client to connect to it by specifying the server’s command and the path to the jar. The Modex server exposes tools defined in your Modex toolset, and you can invoke them from the MCP client with argument maps like {:x 5 :y 6}. Tools can return results as a vector to support multiple outputs. You can also expose a collection of tools in a single module, then bootstrap an MCP server instance that lists those tools to clients. The integration with Claude Desktop (or other MCP clients) uses the standard MCP protocol to request tool invocations, obtain results, and present them to the AI model for reasoning and decision-making.

Prerequisites:

• Java Development Kit (JDK 17+ recommended)
• git
• A Clojure tooling setup to build the uberjar (as documented in the project, typically via clojure and the build tool in the repository)

Step-by-step installation:

1. Install Java (JDK 17+)

   • macOS: brew install openjdk@17; brew link --force --overwrite openjdk@17
   • Linux: sudo apt-get install openjdk-17-jdk
   • Windows: install from Oracle/OpenJDK installers

2. Clone the Modex repository and navigate into it: git clone https://github.com/theronic/modex.git cd modex

3. Build the Uberjar (this compiles the Clojure project and outputs target/modex-mcp-<version>.jar): ./build.sh

4. Verify the jar path (adjust the path in mcp_config accordingly): ls target/modex-mcp-*.jar

5. Run the MCP server using the generated uberjar: java -jar target/modex-mcp-0.2.2.jar

6. Configure your MCP client (e.g., Claude Desktop) to connect to the server, using the following example as a guide: "mcpServers": { "modex-mcp-hello-world": { "command": "java", "args": ["-jar", "/path/to/modex/target/modex-mcp-0.2.2.jar"] } }

Prerequisites continued:

• Access to a compatible MCP client (Claude Desktop or other MCP clients)
• Basic familiarity with editing JSON configuration files for MCP servers

Tips and common issues:

• Ensure the Uberjar path in mcp_config matches the actual output jar location after build.sh. A mismatch results in the MCP client failing to start or connect.
• If the server process starts but tools do not appear in the MCP client, confirm that your tool definitions are loaded and that the server exposes a list-tools endpoint as part of the AServer protocol.
• The Modex server is built for the 2024-11-05 MCP stdio transport, so no proxy is required for standard input/output communication with the client.
• If you update your toolset, rebuild the Uberjar to reflect changes; restart the MCP server (or the host application) to apply the new tool definitions.
• Environment variables are optional; you can add placeholders in mcp_config under env if you need to pass credentials or config paths to the server at startup.