pi-clojure-mcp

Persistent, project-aware Clojure development inside Pi.

Connect Pi to an existing nREPL or explicitly start a managed one. Let your coding agent inspect live namespaces, run project tests, make focused edits, and verify behavior in the same running application.

                                                .+++######+++.
    ##################                        +################+.
    ##################                      +++++++##++++########+
    ##################                       .+++    +++++..+######.
    ######      ######                    .+###+ .++. +++++++ +#####.
    ######      ######                   .####+ +++++..+++++++ +####+
    ######      ######            <->    +####..++++++ +++++++..#####
    ############      ######             +####..+++++.. ++++++. #####
    ############      ######             +####+ ++++ ++..+++++ +####+
    ############      ######              +####+ .+..+++. +++ +###++
    ######            ######              .+####++. .++++     ..
    ######            ######                +######+++++++++++++++
    ######            ######                 .++###############+.
                                                .++++####++++.

             pi.dev                                Clojure

Uses upstream ClojureMCP for evaluation, adding:

• nREPL management — attach to existing REPLs or explicitly start one, with clear readiness, ownership and lifecycle controls.

• Agent steering — the repl-driven-development skill encourages discovery and exploration over batch-then-test workflows.

• REPL feedback — highlighted forms, recorded request timing, expandable output and readable runtime-identity cards.

Why this exists

Pi provides MCP tools; ClojureMCP provides Clojure evaluation. Using them together raises practical questions: What is connected? Is it ready? Who owns it? What happens if I reload?

This package makes those answers visible and gives the agent explicit lifecycle controls. Connecting starts the MCP integration server, which runs on the JVM; starting an application REPL is a separate, opt-in action.

Choose your path

• New here: Quick start

• Already run nREPL: Attach an existing REPL

• Want Pi to start Clojure: Start a managed REPL

• Working across projects: Multi-project workflow

• Discovery failing: Troubleshooting

• Contributing: Development

Related MCP server: pi-agent-mcp

Quick start

With the prerequisites ready:

1. Install a released version:

   pi install npm:pi-clojure-mcp@0.2.0

   For unpublished source, use a local checkout.

2. Start Pi in your Clojure project:

   cd /path/to/your/clojure-project
   pi

3. Check /clj for help and /mcp for the pi_clojure server and its five tools. Trust the project when appropriate.

4. Ask the agent to attach to your existing nREPL using its verified port, or explicitly start a fresh managed REPL for this project. Have it report readiness, application cwd and ownership.

5. Give it a concrete question about your application. Inspect a relevant value or function, make a focused change, and verify the affected behavior.

Keep valuable state across Pi reloads by using an external REPL. See lifetime choices before choosing managed startup or reloading an existing session.

Choose your REPL lifetime

Explicit managed stop/replacement requires state-loss acknowledgment. Pi/MCP shutdown can also end that JVM: reload, exit and crashes have no universal confirmation step, and the heap is not replayed. See state and safety contracts.

Common actions

An eval's explicit port addresses that server without changing which target the management tools control. Follow the multi-project workflow when keeping more than one runtime.

The Pi workflow

Illustrative session, with an external project REPL already selected; the identity values below are examples:

You: Check pi_clojure's runtime status. Don't start or stop an application REPL.

Agent: External nREPL is ready at 127.0.0.1:7888.
       PID: 12345
       cwd: /work/my-app
       namespace (last reported): my-app.core

You: Inspect the function handling checkout totals, reproduce the problem,
     make the smallest fix, and run its project test in the same runtime.

Eval calls show requested Clojure code alongside received output; runtime calls show identity and ownership snapshots. Use Pi's native expansion (Ctrl+E by default, or click where supported) for all received text and the original status JSON. Failed requests keep their received error output visible. These feedback cards also work in HTML exports; model-facing results stay unchanged.

The repl-driven-development skill guides focused experiments, state-aware reloads and durable regression checks. Pi advertises it for on-demand use; /skill:repl-driven-development loads it explicitly.

Full tool names start with mcp__pi_clojure__. Evaluation, discovery and delimiter repair come from upstream ClojureMCP; use the live tool schemas for arguments. Call runtime_status for an updated readiness check: the footer is last-checked information, and the namespace field is last evaluation-reported.

Prerequisites

To use the package:

• Pi with native MCP and tool-renderer support, plus its supported Node runtime; tested with Pi 1.3.0.

• Clojure CLI.

• JDK 17 or later, the pinned upstream's minimum.

• Git and network access for initial dependency resolution.

Documentation

• First use and troubleshooting: installation, discovery and project targeting.

• Reference: flags, tool contracts and state-loss boundaries.

• Architecture: integration and implementation ownership.

• Development: contributor setup and checks.

• Skill design: rationale and references.

• Changelog and agent orientation.

MIT license; upstream dependency licenses are described in NOTICE.