franks42/bb-mcp-server

# stdio (Claude Code)
bb server

# HTTP (Streamable HTTP spec 2025-03-26)
bb server --http --nickname my-server --config system.edn

# Server management
bb server:start-wait --nickname my-server --config system.edn  # Start + wait for health
bb server:stop my-server                                        # Stop by nickname
bb server:restart my-server                                     # Stop + start
bb server:list                                                  # List running servers
bb server:ports my-server                                       # Show all ports

{:modules ["hello" "echo" "calculate" "mcp-nrepl" "mcp-local-eval"]}

# Single module or collection of modules
BB_MCP_EXTERNAL_MODULES=/path/to/my-module bb server --http

# Multiple paths (colon-separated)
BB_MCP_EXTERNAL_MODULES=/path/to/module1:/path/to/modules-collection bb server --http

;; Via mcp-local-eval, nrepl-eval, or direct REPL
(require '[bb-mcp-server.module.system :as system])
(system/load-new-module! "/path/to/external-module")

;; system.edn - minimal bootstrap
{:modules ["mcp-local-eval"]}  ; Just local-eval!

# Start server with ephemeral port and nickname
bb server --http 0 --nickname dev

# Evaluate code (auto-discovers server by nickname)
bb mcp-eval "(+ 1 2 3)"                    # => 6
bb mcp-eval "(range 5)" --nickname dev     # => (0 1 2 3 4)
bb mcp-eval "(System/getenv \"HOME\")"     # => "/Users/..."

# result (default): Just the result value
bb mcp-eval "(do (println \"hi\") 42)"
# => 42

# full: Structured map with status, result, stdout, stderr
bb mcp-eval "(do (println \"hi\") 42)" --output full
# => {:status :ok, :result 42, :stdout "hi\n", :stderr ""}

# pipe: stdout→stdout, stderr→stderr, result to stdout
bb mcp-eval "(do (println \"hi\") 42)" --output pipe
# hi
# 42

# Pretty-print complex data
bb mcp-eval "(ns-publics 'clojure.string)" --pprint

# Check registered tools
bb mcp-eval "(require '[bb-mcp-server.registry :as r]) (mapv :name (r/list-tools))"

# Inspect server state
bb mcp-eval "*ns*"  # => #object[sci.lang.Namespace user]

# Error handling (exits with code 1)
bb mcp-eval "(/ 1 0)" --output pipe  # Prints error to stderr

(require '[bb-mcp-server.mcp-client :as client])

;; Simple eval
(client/eval-code! "dev" "(+ 1 2)")  ; => 3

;; With EDN parsing (preserves sets, keywords)
(client/eval-code! 3000 "#{:a :b}" {:output-format :edn})  ; => #{:a :b}

;; Full response with stdout/stderr
(client/eval-code-full! "dev" "(do (println \"x\") 42)")
; => {:status :ok, :result 42, :stdout "x\n", :stderr ""}

bb mcp servers                           # List running servers
bb mcp tools --mcp dev                   # List available tools
bb mcp call echo.echo '{"message":"hi"}' # Call any tool with JSON args
bb mcp init                              # Get server info

# Start MCP server with nrepl module
bb server --http --port 3001 --config bb-nrepl-system.edn --nickname nrepl-mcp

# Start your nREPL server (or use an existing one)
bb --nrepl-server 7888 &

# Connect to nREPL server
bb nrepl connect 7888 --nickname my-app --mcp nrepl-mcp

# Evaluate code
bb nrepl eval "(+ 1 2 3)" --mcp nrepl-mcp
# => 6

# Load a file
bb nrepl load-file src/my_app/core.clj --mcp nrepl-mcp

# List connections
bb nrepl list --mcp nrepl-mcp

# Disconnect
bb nrepl disconnect my-app --mcp nrepl-mcp

# result (default): Just the value
bb nrepl eval "(do (println \"hi\") 42)" --mcp nrepl-mcp
# => 42

# full: Complete response with stdout/stderr
bb nrepl eval "(do (println \"hi\") 42)" --mcp nrepl-mcp --output full --pprint
# => {:status "success", :value "42", :out "hi\n", ...}

# pipe: stdout→stdout, stderr→stderr, value to stdout
bb nrepl eval "(do (println \"hi\") 42)" --mcp nrepl-mcp --output pipe
# hi
# 42

# Eval with explicit port
bb nrepl-direct eval "(+ 1 2 3)" --port 7888
# => 6

# Eval using port discovery from server nickname
bb nrepl-direct eval "(+ 1 2 3)" --nickname scittle-dev
# => 6

# Load local file (reads file, sends content as code)
bb nrepl-direct load-local-file src/browser/app.cljs --nickname scittle-dev

# Load file from server's filesystem
bb nrepl-direct load-file /path/to/file.clj --port 7888

# Read code from stdin
echo "(range 5)" | bb nrepl-direct eval - --port 7888

# Describe server capabilities
bb nrepl-direct describe --port 7888

# Use nrepl-server port (default)
bb nrepl-direct eval "(+ 1 2)" --nickname scittle-dev

# Use nrepl-proxy port (for browser connections)
bb nrepl-direct eval "(+ 1 2)" --nickname scittle-dev --service nrepl-proxy

# Start MCP server with nREPL test server
bb server --http --config bb-nrepl-server-system.edn

# Open iTerm2 with rebel-readline
bb rebel-nrepl-client 7888

# Start scittle-dev server (requires sente-lite bundle)
bb server --http --config bb-scittle-dev-system.edn --nickname scittle-dev

# Open browser to bootstrap page
open http://127.0.0.1:8091

# Connect rebel-readline to proxy
bb rebel-nrepl-client 1667

(browser/list)            ; List connected browsers
(browser/repl :browser-1) ; Switch to browser REPL

;; Now you're in the browser!
(+ 1 2 3)                 ; => 6
(js/alert "Hello!")       ; Shows browser alert
js/navigator.userAgent    ; Access browser APIs

:cljs/quit                ; Return to bb

{:modules ["mcp-local-eval" "mcp-nrepl" "nrepl-server"
           "sente-browser" "nrepl-proxy-server"]
 :config {"sente-browser" {:ws-port 8090
                           :bootstrap-port 8091
                           :bundle-path "/path/to/sente-lite-nrepl.cljs"}
          "nrepl-proxy-server" {:port 1667
                                :write-port-file? true}}}

{
  "mcpServers": {
    "bb-mcp": {
      "command": "bb",
      "args": ["server:stdio"],
      "cwd": "/path/to/bb-mcp-server"
    }
  }
}

bb test:all       # Run all tests (modules + bootstrap)
bb test:modules   # Run module tests only
bb test:bootstrap # Run bootstrap configuration tests
bb test:e2e       # Run E2E MCP client tests (requires running server)
bb lint           # clj-kondo (0 errors, 0 warnings)
bb format         # cljfmt
bb server:stop my-server  # Stop server by nickname
bb server:list            # List running servers

# Bootstrap with minimal module set (local-eval only)
bb bootstrap-server

# Custom bootstrap config
bb server --config bb-bootstrap-system.edn

# With nickname for port file identification
bb server --config bb-bootstrap-system.edn --nickname my-server

{:modules ["mcp-local-eval"]}  ; Minimal setup for local evaluation