Skip to content

Documentation for auto-start nREPL feature #101

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 16, 2025
Merged

Documentation for auto-start nREPL feature #101

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 28 additions & 0 deletions CONFIG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Comment on lines +57 to +63
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Default mismatch with README; align on a single truth and clarify stdout-only.

CONFIG.md says default is true when :start-nrepl-cmd is provided, but README says default is false. Recommend making the default “true when :start-nrepl-cmd is set” in both places and reiterating stdout-only behavior to match project preference.

-**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.
+**Optional** - When `true` and used with `:start-nrepl-cmd`, automatically discovers the nREPL port from the command's stdout (stdout-only) output. Defaults to `true` when `:start-nrepl-cmd` is provided. The parser recognizes common nREPL port announcement formats.
...
-`true` (default when `:start-nrepl-cmd` is provided) - Parse port from nREPL output
+`true` (default when `:start-nrepl-cmd` is provided) - Parse port from nREPL stdout
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
### `: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
### `:parse-nrepl-port`
**Optional** - When `true` and used with `:start-nrepl-cmd`, automatically discovers the nREPL port from the command's stdout (stdout-only) 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 stdout
- `false` - Don't parse port; requires `:port` to be explicitly provided
🤖 Prompt for AI Agents 
In CONFIG.md around lines 57-63, the documented default for `:parse-nrepl-port`
conflicts with README (CONFIG.md says default true when `:start-nrepl-cmd` is
provided, README says false) and the stdout-only behavior is not reiterated;
update CONFIG.md and README to agree that the default is “true when
`:start-nrepl-cmd` is set”, and add a short clarifying sentence in both files
that parsing only inspects the command's stdout (not stderr or other channels),
so both docs present the same default and explicitly state stdout-only behavior.

**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.

Expand Down
27 changes: 26 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`

Expand All @@ -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"]`

Comment on lines +945 to +951
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Clarify location requirement applies only to auto-start mode.

Avoid contradiction with “Location Independence” later in the doc.

-**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.
+**Important (auto-start mode only)**: When using `:start-nrepl-cmd`, you must launch `clojure-mcp` from your project directory (where your `deps.edn` or `project.clj` is located). The nREPL server is started in the current working directory. Outside of auto-start mode, you can run the MCP server from any directory. This is particularly useful for Claude Code and other CLI LLM clients where you want automatic nREPL startup without manual process management.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
#### `: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"]`
#### `: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 (auto-start mode only)**: When using `:start-nrepl-cmd`, you must launch `clojure-mcp` from your project directory (where your `deps.edn` or `project.clj` is located). The nREPL server is started in the current working directory. Outside of auto-start mode, you can run the MCP server from any directory. This is particularly useful for Claude Code and other CLI 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"]`
🤖 Prompt for AI Agents 
In README.md around lines 945 to 951, the text implies a directory requirement
that contradicts the later “Location Independence” section; clarify that the
working-directory requirement applies only when using the :start-nrepl-cmd
auto-start option. Update the paragraph to explicitly state: when you provide
:start-nrepl-cmd, MCP must be launched from your project directory because the
nREPL server is started in the current working directory; otherwise MCP remains
location-independent and no special working directory is required. Keep the
examples and mention that this only affects auto-start mode.

#### `: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`

Comment on lines +953 to +956
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Fix default to match CONFIG.md and clarify stdout-only parsing.

Current text says default is false; CONFIG.md says default true when :start-nrepl-cmd is set. Recommend align to true-when-present and mention stdout-only.

-**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.
+**Optional** - When `true` and used with `:start-nrepl-cmd`, automatically discovers the nREPL port from the command's stdout (stdout-only) output. Defaults to `true` when `:start-nrepl-cmd` is provided. The parser recognizes common nREPL port announcement formats.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
**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`
**Optional** - When `true` and used with `:start-nrepl-cmd`, automatically discovers the nREPL port from the command's stdout (stdout-only) output. Defaults to `true` when `:start-nrepl-cmd` is provided. The parser recognizes common nREPL port announcement formats.
`:parse-nrepl-port true`
🤖 Prompt for AI Agents 
In README.md around lines 953 to 956, the doc incorrectly states the default for
:parse-nrepl-port is false; update it to say the default is true when
:start-nrepl-cmd is set (otherwise false), and explicitly state that the parser
only inspects the command's stdout for nREPL port announcements; keep the
example but adjust the preceding sentence to reflect the corrected default and
stdout-only parsing behavior.

#### `:config-file`
**Optional** - Specify the location of a configuration file. Must be a path to an existing file.

Expand All @@ -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
```
Expand Down
44 changes: 44 additions & 0 deletions resources/configs/example-auto-start-nrepl.edn
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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

Comment on lines +12 to +15
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Clarify stdout-only parsing and implied default.

Match the docs: stdout-only, and default true when :start-nrepl-cmd is present.

-;; Parse the port from nREPL output (default: true when :start-nrepl-cmd is provided)
+;; Parse the port from nREPL stdout only (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
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
;; 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
;; Parse the port from nREPL stdout only (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
🤖 Prompt for AI Agents 
In resources/configs/example-auto-start-nrepl.edn around lines 12 to 15, the
comment for :parse-nrepl-port should be clarified to state that port parsing
reads only stdout and that the option defaults to true when :start-nrepl-cmd is
provided; update the comment text to explicitly mention "stdout-only" parsing
and that the default is true if :start-nrepl-cmd is set (and advise setting to
false to use a fixed port).

;; 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