docs: Add documentation for auto-start nREPL CLI and config options (#101)

- Update README.md CLI options to document :start-nrepl-cmd and :parse-nrepl-port
- Update CONFIG.md with new configuration options for auto-starting nREPL
- Add example configuration file for auto-start feature
- Clarify that auto-start requires launching from project directory
- Emphasize usefulness for Claude Code and other CLI-based LLM tools

Co-authored-by: Bruce Hauman <[email protected]>

Author: bhauman

CONFIG.md

@@ -39,6 +39,34 @@ Controls the file timestamp tracking behavior (default: `:partial-read`). This s
 
 The timestamp tracking system prevents accidental overwrites when files are modified by external processes (other developers, editors, git operations, etc.).
 
+### `:start-nrepl-cmd`
+**Optional** - A command to automatically start an nREPL server if one is not already running. Must be specified as a vector of strings. The MCP server will start this process and manage its lifecycle.
+
+**Important**: This feature requires the MCP server to be launched from your project directory (where your `deps.edn` or `project.clj` is located). The nREPL server will be started in the current working directory. This makes it ideal for use with Claude Code and other command-line LLM clients where you want automatic nREPL startup - you can simply start Claude Code in your project directory and the nREPL will launch automatically.
+
+**Available values:**
+- `["lein" "repl" ":headless"]` - Start Leiningen REPL in headless mode
+- `["clojure" "-M:nrepl"]` - Start Clojure with nREPL alias
+- `["bb" "nrepl-server"]` - Start Babashka nREPL server
+
+**When to use:**
+- With Claude Code or other CLI-based LLM tools launched from your project directory
+- When you want automatic nREPL server management without separate terminal windows
+- In CI/CD environments where automatic startup is beneficial
+
+### `:parse-nrepl-port`
+**Optional** - When `true` and used with `:start-nrepl-cmd`, automatically discovers the nREPL port from the command's stdout output. Defaults to `true` when `:start-nrepl-cmd` is provided. The parser recognizes common nREPL port announcement formats.
+
+**Available values:**
+- `true` (default when `:start-nrepl-cmd` is provided) - Parse port from nREPL output
+- `false` - Don't parse port; requires `:port` to be explicitly provided
+
+**When to use:**
+- `true` - When the nREPL server announces its port in stdout (most common case)
+- `false` - When using a fixed port configuration or when port is known in advance
+
+**Note:** When `:parse-nrepl-port` is `false`, you must provide the `:port` configuration.
+
 ### `:emacs-notify`
 Boolean flag to enable Emacs integration notifications.
 

README.md

@@ -933,7 +933,7 @@ For a quick start: **[Creating Your Own Custom MCP Server](doc/custom-mcp-server
 Using the -X invocation requires EDN values.
 
 #### `:port`
-**Required** - The nREPL server port to connect to.
+**Optional** - The nREPL server port to connect to. Required unless using `:start-nrepl-cmd` with `:parse-nrepl-port` or relying on an existing `.nrepl-port` file.
 
 `:port 7888`
 
@@ -942,6 +942,18 @@ Using the -X invocation requires EDN values.
 
 `:host "localhost"` or `:host "0.0.0.0"`
 
+#### `:start-nrepl-cmd`
+**Optional** - A command to automatically start an nREPL server if one is not already running. Must be specified as a vector of strings. The MCP server will start this process and manage its lifecycle.
+
+**Important**: This option requires launching `clojure-mcp` from your project directory (where your `deps.edn` or `project.clj` is located). The nREPL server will be started in the current working directory. This is particularly useful for Claude Code and other command-line LLM clients where you want automatic nREPL startup without manual process management.
+
+`:start-nrepl-cmd ["lein" "repl" ":headless"]` or `:start-nrepl-cmd ["clojure" "-M:nrepl"]`
+
+#### `:parse-nrepl-port`
+**Optional** - When `true` and used with `:start-nrepl-cmd`, automatically discovers the nREPL port from the command's stdout output. Defaults to `false`. The parser recognizes common nREPL port announcement formats.
+
+`:parse-nrepl-port true`
+
 #### `:config-file`
 **Optional** - Specify the location of a configuration file. Must be a path to an existing file.
 
@@ -968,12 +980,25 @@ Using the -X invocation requires EDN values.
 # Basic usage with just port
 clojure -X:mcp :port 7888
 
+# With automatic nREPL server startup and port discovery
+# Perfect for Claude Code - run this from your project directory
+clojure -X:mcp :start-nrepl-cmd '["lein" "repl" ":headless"]' :parse-nrepl-port true
+
+# For Claude Code with Clojure projects (from project directory)
+clojure -X:mcp :start-nrepl-cmd '["clojure" "-M:nrepl"]' :parse-nrepl-port true
+
+# Auto-start with explicit port (doesn't parse from output)
+clojure -X:mcp :port 7888 :start-nrepl-cmd '["clojure" "-M:nrepl"]'
+
 # With custom host and project directory
 clojure -X:mcp :port 7888 :host '"0.0.0.0"' :project-dir '"/path/to/project"'
 
 # Using a custom config file
 clojure -X:mcp :port 7888 :config-file '"/path/to/custom-config.edn"'
 
+# Using existing .nrepl-port file (no explicit port needed)
+clojure -X:mcp
+
 # Specifying Babashka environment
 clojure -X:mcp :port 7888 :nrepl-env-type :bb
 ```

resources/configs/example-auto-start-nrepl.edn

@@ -0,0 +1,44 @@
+;; Example configuration for automatic nREPL server startup
+;; Place this in .clojure-mcp/config.edn in your project root
+;;
+;; IMPORTANT: This feature requires launching clojure-mcp from your project directory
+;; Perfect for Claude Code and other CLI-based LLM tools where you want automatic
+;; nREPL startup without managing separate processes
+
+{;; Automatically start an nREPL server when MCP server starts
+ ;; Must be a vector of strings representing the command and arguments
+ :start-nrepl-cmd ["clojure" "-M:nrepl"]
+
+ ;; Parse the port from nREPL output (default: true when :start-nrepl-cmd is provided)
+ ;; Set to false if you want to use a fixed port specified below
+ :parse-nrepl-port true
+
+ ;; Port is optional when :parse-nrepl-port is true
+ ;; Required when :parse-nrepl-port is false
+ ;; :port 7888
+
+ ;; Other common configurations
+ :allowed-directories ["." "src" "test" "resources"]
+ :write-file-guard :partial-read
+ :cljfmt true
+ :bash-over-nrepl true}
+
+;; Alternative configurations:
+
+;; For Leiningen projects (great for Claude Code):
+;; {:start-nrepl-cmd ["lein" "repl" ":headless"]
+;;  :parse-nrepl-port true}
+
+;; For Babashka:
+;; {:start-nrepl-cmd ["bb" "nrepl-server"]
+;;  :parse-nrepl-port true}
+
+;; With fixed port (no port parsing):
+;; {:start-nrepl-cmd ["clojure" "-M:nrepl"]
+;;  :parse-nrepl-port false
+;;  :port 7888}
+
+;; Claude Code usage:
+;; 1. Place this config in your-project/.clojure-mcp/config.edn
+;; 2. Open Claude Code in your project directory
+;; 3. The nREPL will start automatically when Claude Code connects