Clojure REPL Commands For Java Info

This is a small library with REPL tools that are intended to be used by nREPL-based MCP tools and AI. The idea is that when you are working with Java libraries in Clojure this will enable you to start an nREPL, and have an nREPL MCP be able to ask for javadoc or even the Java source code of classes and methods. The AI can then automatically build a much better (and compact) context window for very specific Java things.

The basic way this works is as follows:

The built-in classes have local source code in a src.zip. All of the other code on the classpath typically comes from a Maven-style repo, and those files are stored in your ~/.m2 folder.

The Java ecosystem has a standard naming for source JARs, which you can download from Maven.

So, we use the classpath to discover things (e.g. Java reflection and classpath scanning), and then this code will auto-download (and cache) the source jar files for anything on your classpath.

It then uses some GitHub libraries to parse the source code to locally extract and format the source code or docstrings from the source code!

So, now instead of having to point your AI at huge HTML javadoc pages online, it can use the nREPL to get targeted info straight from the literal source code of those libraries.

Of course, the Clojure REPL already has this support for clojure code, so this library just balances it out.

See https://clojuredocs.org/clojure.repl/source.

General Usage

NOTE: This library downloads Java source using Clojure's tools.deps library.

1. Install an AI tool that supports MCP use, like Roo Code or Claude Code
2. Add an nREPL MCP server
3. Run an nREPL

The finding-java-doc-and-source.md is a document you can point your AI at to tell it how to use this library, and it is readable by you as well, of course.

You'll also want to give your AI a document to tell it how to find your nREPL port.

Further Suggestions and Reading

If you install the nrepl-mcp-server (https://github.com/JohanCodinha/nrepl-mcp-server) into you AI tool, you can then give you AI instructions like: I have an nREPL running on port X. You can discover the javadoc or source code for Java interop (or .java files in my project) using the nREPL, and you can find instructions for those function calls in finding-java-doc-and-sources.md (where you point it at the file from this repo, which you copy into you working source tree).

NOTE: At the time of this writing, the nrepl mcp server had a patch (I contributed) to prevent crashed due to UTF encodings, and NPM had not been updated. So, installing/building it locally is recommended.

Status

Just starting to play with it. Contributions welcome. Tested against Java 21. Other versions may have parsing issues.

Possible extensions

I've been thinking it would be relatively easy to add a few things that might give AI more power:

• Search for class names that contain some pattern
• An apropos index, generated by scanning the classpath for all classes, pre-downloading all the source jars, extracting public fully-qualified classes, and then pulling the class descriptions. Then you (or an AI) could query for things related to some topic and get a list of class names.

License

Copyright 2025, Fulcrologic, LLC.

MIT License.