Remove :parse-nrepl-port option for simpler nREPL auto-start

BREAKING CHANGE: The :parse-nrepl-port configuration option has been removed.
Port parsing is now automatic based on the presence of :port.

Simplifications:
- When :start-nrepl-cmd is used WITHOUT :port, automatically parse from output
- When :start-nrepl-cmd is used WITH :port, use that fixed port
- Eliminates confusing configuration combinations
- Makes the feature more intuitive for users

Migration:
- Remove :parse-nrepl-port from all configurations
- Old: :start-nrepl-cmd [...] :parse-nrepl-port true
- New: :start-nrepl-cmd [...]

Documentation:
- Added Claude Desktop limitations (requires :project-dir)
- Emphasized Claude Code compatibility
- Provided clear examples for different use cases

Author: Bruce Hauman

CHANGELOG.md

@@ -1,5 +1,71 @@
 # Changelog
 
+## [Unreleased]
+
+### Simplified nREPL Auto-Start 🚀
+
+**Launching an nREPL server is now incredibly simple!** Just provide `:start-nrepl-cmd` and the MCP server handles everything else - perfect for Claude Code and other CLI-based AI tools.
+
+#### Quick Start Examples
+
+**From your project directory**, just run:
+
+```bash
+# For Leiningen projects
+clojure -X:mcp :start-nrepl-cmd '["lein" "repl" ":headless"]'
+
+# For deps.edn projects  
+clojure -X:mcp :start-nrepl-cmd '["clojure" "-M:nrepl"]'
+
+# For Babashka scripts
+clojure -X:mcp :start-nrepl-cmd '["bb" "nrepl-server"]'
+```
+
+That's it! The MCP server will:
+- Start your nREPL server automatically
+- Discover the port from the output
+- Connect and manage the process lifecycle
+- Clean up when you're done
+
+#### Perfect for Claude Code
+
+This feature is especially valuable for **Claude Code** users who want to start coding immediately without managing separate terminal windows:
+
+1. Open Claude Code in your Clojure project directory
+2. The nREPL starts automatically when Claude connects
+3. Start coding with full REPL support!
+
+You can also configure this in `.clojure-mcp/config.edn`:
+```edn
+{:start-nrepl-cmd ["clojure" "-M:nrepl"]}
+```
+
+#### Note for Claude Desktop Users
+
+**Important**: Claude Desktop does not start MCP servers from your project directory, so `:start-nrepl-cmd` will not work unless you also provide `:project-dir` pointing to your specific project:
+
+```bash
+# For Claude Desktop, you must specify the project directory:
+clojure -X:mcp :start-nrepl-cmd '["lein" "repl" ":headless"]' :project-dir '"/path/to/your/clojure/project"'
+```
+
+This limitation does not affect Claude Code or other CLI-based tools that you run directly from your project directory.
+
+#### Using a Fixed Port
+
+If you prefer a specific port, just add it:
+```bash
+clojure -X:mcp :start-nrepl-cmd '["lein" "repl" ":headless"]' :port 7888
+```
+
+### Breaking Changes
+- **Removed `:parse-nrepl-port`**: This confusing option has been eliminated. The MCP server now intelligently determines whether to parse the port based on whether `:port` is provided. Simple!
+
+### Migration Note
+If you were using `:parse-nrepl-port`, just remove it:
+- Old: `:start-nrepl-cmd ["..."] :parse-nrepl-port true` 
+- New: `:start-nrepl-cmd ["..."]`
+
 ## [0.1.9-alpha] - 2025-9-16
 
 ### Major Refactoring: Configuration-Based Agent Tools

CONFIG.md

@@ -44,6 +44,12 @@ The timestamp tracking system prevents accidental overwrites when files are modi
 
 **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.
 
+**Note for Claude Desktop users**: Claude Desktop does not start MCP servers from your project directory, so `:start-nrepl-cmd` in your config file will not work by itself. You must also configure the `:project-dir` argument in Claude Desktop's settings to point to your specific project. This limitation does not affect Claude Code or other CLI-based tools that you run from your project directory.
+
+**Behavior:**
+- When used without `:port`, the MCP server will automatically parse the port from the command's output
+- When used with `:port`, it will use that fixed port instead of parsing from output
+
 **Available values:**
 - `["lein" "repl" ":headless"]` - Start Leiningen REPL in headless mode
 - `["clojure" "-M:nrepl"]` - Start Clojure with nREPL alias
@@ -54,19 +60,6 @@ The timestamp tracking system prevents accidental overwrites when files are modi
 - 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`
-**Optional** - The nREPL server port to connect to. **Required** unless using `:start-nrepl-cmd` with `:parse-nrepl-port`
+**Optional** - The nREPL server port to connect to. When using `:start-nrepl-cmd` without `:port`, the port will be automatically discovered from the command output.
 
 `:port 7888`
 
@@ -943,16 +943,15 @@ 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.
+**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.
+When used without `:port`, the MCP server will automatically parse the port from the command's output. When used with `:port`, it will use that fixed port instead.
 
-`:start-nrepl-cmd ["lein" "repl" ":headless"]` or `:start-nrepl-cmd ["clojure" "-M:nrepl"]`
+**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.
 
-#### `: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.
+**Note for Claude Desktop users**: Claude Desktop does not start MCP servers from your project directory, so `:start-nrepl-cmd` will not work unless you also provide `:project-dir` as a command line argument pointing to your specific project. For example: `:project-dir '"/path/to/your/clojure/project"'`. This limitation does not affect Claude Code or other CLI-based tools that you run from your project directory.
 
-`:parse-nrepl-port true`
+`:start-nrepl-cmd ["lein" "repl" ":headless"]` or `:start-nrepl-cmd ["clojure" "-M:nrepl"]`
 
 #### `:config-file`
 **Optional** - Specify the location of a configuration file. Must be a path to an existing file.
@@ -982,14 +981,17 @@ 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
+clojure -X:mcp :start-nrepl-cmd '["lein" "repl" ":headless"]'
 
 # For Claude Code with Clojure projects (from project directory)
-clojure -X:mcp :start-nrepl-cmd '["clojure" "-M:nrepl"]' :parse-nrepl-port true
+clojure -X:mcp :start-nrepl-cmd '["clojure" "-M:nrepl"]'
 
-# Auto-start with explicit port (doesn't parse from output)
+# Auto-start with explicit port (uses fixed port, no parsing)
 clojure -X:mcp :port 7888 :start-nrepl-cmd '["clojure" "-M:nrepl"]'
 
+# For Claude Desktop: must provide project-dir since it doesn't run from your project
+clojure -X:mcp :start-nrepl-cmd '["lein" "repl" ":headless"]' :project-dir '"/path/to/your/clojure/project"'
+
 # With custom host and project directory
 clojure -X:mcp :port 7888 :host '"0.0.0.0"' :project-dir '"/path/to/project"'
 

deps.edn

@@ -77,7 +77,6 @@
    :exec-args {:port 7888
                ;; test auto starting the repl
                ;; :start-nrepl-cmd ["clojure" "-M:nrepl"]
-               ;; :parse-nrepl-port true
                }}
 
   ;; DEV setup needs logback.xml

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

@@ -9,12 +9,8 @@
  ;; 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 is optional - if not provided, MCP will parse it from nREPL output
+ ;; Provide :port if you want to use a fixed port instead of parsing
  ;; :port 7888
 
  ;; Other common configurations
@@ -26,16 +22,13 @@
 ;; Alternative configurations:
 
 ;; For Leiningen projects (great for Claude Code):
-;; {:start-nrepl-cmd ["lein" "repl" ":headless"]
-;;  :parse-nrepl-port true}
+;; {:start-nrepl-cmd ["lein" "repl" ":headless"]}
 
 ;; For Babashka:
-;; {:start-nrepl-cmd ["bb" "nrepl-server"]
-;;  :parse-nrepl-port true}
+;; {:start-nrepl-cmd ["bb" "nrepl-server"]}
 
 ;; With fixed port (no port parsing):
 ;; {:start-nrepl-cmd ["clojure" "-M:nrepl"]
-;;  :parse-nrepl-port false
 ;;  :port 7888}
 
 ;; Claude Code usage:

src/clojure_mcp/config/schema.clj

@@ -263,9 +263,8 @@
    [:bash-over-nrepl {:optional true} :boolean]
    [:nrepl-env-type {:optional true} [:enum :clj :bb :basilisp :scittle]]
    [:start-nrepl-cmd {:optional true} [:sequential NonBlankString]]
-   [:parse-nrepl-port {:optional true} :boolean]
 
-   ;; Scratch pad configuration
+;; Scratch pad configuration
    [:scratch-pad-load {:optional true} :boolean]
    [:scratch-pad-file {:optional true} Path]
 

src/clojure_mcp/core.clj

@@ -364,10 +364,9 @@
                                     (and (.exists f) (.isFile f)))
                                   (catch Exception _ false))))
 (s/def ::start-nrepl-cmd (s/coll-of string? :kind vector?))
-(s/def ::parse-nrepl-port boolean?)
 (s/def ::nrepl-args (s/keys :req-un []
                             :opt-un [::port ::host ::config-file ::project-dir ::nrepl-env-type
-                                     ::start-nrepl-cmd ::parse-nrepl-port]))
+                                     ::start-nrepl-cmd]))
 
 (def nrepl-client-atom (atom nil))
 
@@ -552,7 +551,7 @@
    
    If auto-start conditions are met (see nrepl-launcher/should-start-nrepl?), it will:
    1. Start an nREPL server process using :start-nrepl-cmd
-   2. Parse the port from process output (if :parse-nrepl-port is true)
+   2. Parse the port from process output (if no :port provided)
    3. Pass the discovered port to the main MCP server setup
    
    Otherwise, it requires a :port parameter.
@@ -561,10 +560,10 @@
    - nrepl-args: Map with connection settings and optional nREPL start
      configuration
      - :port (required if not auto-starting) - nREPL server port
+       When provided with :start-nrepl-cmd, uses fixed port instead of parsing
      - :host (optional) - nREPL server host (defaults to localhost)  
      - :project-dir (optional) - Root directory for the project
      - :start-nrepl-cmd (optional) - Command to start nREPL server
-     - :parse-nrepl-port (optional) - Parse port from command output (default true)
    
    - component-factories: Map with factory functions
      - :make-tools-fn - (fn [nrepl-client-atom working-dir] ...) returns seq of tools