repl

This MCP server is focused on Clojure development, providing a rich set of built-in tools and nREPL integration to streamline editing, evaluation, refactoring, and analysis from within an autonomous coding assistant environment. It exposes a suite of over 50 development tools that you can invoke directly against your project’s REPL, enabling tasks like evaluating code, refactoring namespaces, analyzing dependencies, profiling performance, and performing code quality checks. The server supports two transports: STDIO for local development and HTTP+SSE for production deployments, making it easy to integrate with IDEs, editors, or external copilots.

To use it, add the MCP server to your project (via the suggested deps.edn alias in the Quick Start) and start the MCP server with the chosen transport. Once running, you can access tools such as eval, load-file, format-code, lint-code, analyze-project, find-unused-vars, clean-ns, rename-function-across-project, extract-function, profile-cpu, profile-alloc, add-libs, sync-deps, and check-namespace. Tools are designed to be invoked from your assistant workflow (for example Claude or other agents) and return structured results that you can render or act upon in your tooling pipeline. The integration with nREPL middleware (cider-nrepl and refactor-nrepl) means you get a familiar REPL experience with powerful editing and navigation capabilities during development.

In practice, you would start the MCP server in STDIO mode for development, or switch to HTTP+SSE when deploying to a production-like environment, then use the provided toolset to manipulate and inspect your Clojure project without restarting the REPL. The architecture emphasizes hot-loading dependencies, robust error handling, and a consistent tool interface, making it suitable for embedding in coding assistants that orchestrate workflows across your codebase.

Prerequisites:

• Java 11 or newer
• clojure CLI tools installed (to use the recommended deps.edn alias in Quick Start)
• Your project with a deps.edn file (if integrating into an existing Clojure project) or a suitable runtime setup to run an MCP server

Installation steps:

1. Ensure Java and Clojure CLI are installed. For example:
   • Install Java from Oracle/OpenJDK
   • Install Clojure CLI: https://clojure.org/guides/getting_started
2. Add the MCP alias to your project as shown in the Quick Start section of the README. Example deps.edn entry:

{:aliases
 {:repl-mcp {:main-opts ["-m" "is.simm.repl-mcp"]
             :extra-paths ["test"]
             :jvm-opts ["-Djdk.attach.allowAttachSelf"
                        "-XX:+UnlockDiagnosticVMOptions"
                        "-XX:+DebugNonSafepoints"
                        "-XX:+EnableDynamicAgentLoading"
                        "--enable-native-access=ALL-UNNAMED"]
             :extra-deps {is.simm/repl-mcp {:git/url "https://github.com/simm-is/repl-mcp" :git/sha "latest-sha"}
                          org.slf4j/slf4j-api {:mvn/version "2.0.17"}
                          org.slf4j/slf4j-simple {:mvn/version "2.0.17"}}}}}

3. Start the MCP server using the recommended transport:

   • STDIO (development): clojure -M:repl-mcp
   • HTTP+SSE (production): clojure -M:repl-mcp --transport sse --http-port 8080
   • Custom nREPL port: clojure -M:repl-mcp --nrepl-port 27889

4. If you plan to integrate Claude/VS Code or other clients, configure the client to point at the appropriate transport and port as described in the README (e.g., Claude integration commands or VS Code mcp.json example).

Note: This alpha project is designed to be minimally invasive and easy to connect to your existing REPL workflows, but being alpha software, ensure you validate in a staging environment before production use.

Tips and common issues:

• Transport choice matters: STDIO is simplest for local development, while HTTP+SSE enables remote workflows. Ensure firewall and port access are configured for production usage.
• nREPL middleware (cider-nrepl and refactor-nrepl) is integrated; you’ll get IDE-like navigation, refactoring support, and live evaluation. If you experience port conflicts, explicitly set a different nREPL port with --nrepl-port.
• Hot-reloading and dependency management are supported via tools like add-libs and sync-deps. You can load new dependencies at runtime without restarting the REPL. Ensure you are on Clojure 1.12+ for best compatibility.
• If you’re embedding in Claude or another assistant, provide clear tool usage instructions through CLAUDE.md to guide tool invocations and expected inputs/outputs.
• Environment variables: JAVA_HOME may be required to point to a specific JDK. Some environments may also benefit from CLJ options for profiling or agent loading; see the JVM options block in the Quick Start example.
• Since this is alpha, expect API changes and evolving tool interfaces. Keep an eye on the repository for updates and breaking changes.