Require type parameter on deps_grep and filter binary entries

- Make type required: "clj" (source in jar) or "java" (download source jars)
- Always filter binary entries (.class, images, native libs, archives, etc.)
- Remove needs-java-sources? and type-to-glob in favor of direct type check
- Add no-backwards-compatibility note to CLAUDE.md for MCP tool guidelines

Author: Bruce Hauman

CLAUDE.md

@@ -19,5 +19,6 @@
 - Validate inputs and provide helpful error messages
 - Return structured data with both result and error status
 - Maintain atom-based state for consistent service access
+- **No backwards compatibility required**: This is an MCP server — tool schemas, parameters, and behavior can change freely between versions. Don't hesitate to make breaking changes to tool contracts when it improves the design.
 
 Fast Apply: IMPORTANT: Use \`edit_file\` over \`str_replace\` or full file writes. It works with partial code snippets—no need for full file content.

src/clojure_mcp/tools/deps_grep/core.clj

@@ -69,30 +69,38 @@
       (when (.exists sources-file)
         sources-path))))
 
-(defn needs-java-sources?
-  "Check if the search options indicate we're looking for Java files."
-  [{:keys [type glob]}]
-  (or (= "java" type)
-      (and glob (re-find #"\.java" glob))))
+(def ^:private binary-extensions
+  "File extensions that are binary and should never be searched."
+  #{".class" ".jar" ".war" ".ear"
+    ".png" ".jpg" ".jpeg" ".gif" ".ico" ".bmp" ".svg" ".webp"
+    ".so" ".dll" ".dylib" ".o" ".a"
+    ".zip" ".gz" ".tar" ".bz2" ".xz"
+    ".ttf" ".otf" ".woff" ".woff2"
+    ".pdf" ".doc" ".docx"})
+
+(defn binary-entry?
+  "Returns true if a jar entry path has a known binary extension."
+  [entry-path]
+  (some #(str/ends-with? (str/lower-case entry-path) %) binary-extensions))
 
 (defn get-jars-with-sources
   "Given a list of jars and search opts, return jars plus any available sources jars.
-   When searching for Java files, downloads missing sources from Maven Central."
+   When type is \"java\", downloads missing sources from Maven Central."
   [jars opts]
   (let [;; First find sources jars already in Maven cache
         existing-sources (->> jars
                               (keep find-sources-jar)
                               (remove (set jars)))]
-    (if (needs-java-sources? opts)
-      ;; For Java searches, also download missing sources
+    (if (= "java" (:type opts))
+      ;; For Java ecosystem jars, download source jars to get searchable text
       (let [jars-with-sources (set (map #(str/replace % #"-sources\.jar$" ".jar")
                                         existing-sources))
             jars-missing-sources (remove jars-with-sources jars)
             _ (log/debug "Checking for Java sources for" (count jars-missing-sources) "jars")
             downloaded-sources (deps-sources/ensure-sources-jars! jars-missing-sources)]
         (log/debug "Downloaded" (count downloaded-sources) "sources jars")
         (into (vec jars) (concat existing-sources downloaded-sources)))
-      ;; For non-Java searches, just use existing sources
+      ;; For Clojure ecosystem jars, source is in the jar already
       (into (vec jars) existing-sources))))
 
 (defn parse-library-filter
@@ -153,19 +161,14 @@
                                            (str "(" (str/replace alts "," "|") ")"))))]
       (boolean (re-find (re-pattern (str pattern-regex "$")) path)))))
 
-(defn type-to-glob
-  "Convert a file type (like 'clj') to a glob pattern."
-  [type-str]
-  (when type-str
-    (str "*." type-str)))
-
 (defn filter-entries
-  "Filter jar entries by glob and/or type patterns."
-  [entries {:keys [glob type]}]
-  (let [effective-glob (or glob (type-to-glob type))]
-    (if effective-glob
-      (filter #(glob-matches? effective-glob %) entries)
-      entries)))
+  "Filter jar entries, removing binary files and applying optional glob pattern.
+   Binary extensions (.class, images, native libs, etc.) are always excluded."
+  [entries {:keys [glob]}]
+  (let [text-entries (remove binary-entry? entries)]
+    (if glob
+      (filter #(glob-matches? glob %) text-entries)
+      text-entries)))
 
 (defn search-jar-entry-rg
   "Search using ripgrep. Reads jar entry via Java, pipes content to rg via stdin.
@@ -242,8 +245,10 @@
    - pattern: Regex pattern to search for
    - opts: Map of options
      :library - Required. Maven group or group/artifact to search
-     :glob - Filter files by glob pattern (e.g., \"*.clj\")
-     :type - Filter files by type (e.g., \"clj\", \"java\")
+     :type - Required. Jar ecosystem type: \"clj\" or \"java\"
+             \"clj\" searches the jar directly (source is in the jar)
+             \"java\" downloads source jars from Maven Central
+     :glob - Optional. Filter files by glob pattern (e.g., \"*.java\")
      :output-mode - :content, :files-with-matches, or :count
      :case-insensitive - Case insensitive search
      :line-numbers - Include line numbers (default true for content mode)
@@ -263,7 +268,7 @@
       (if-not base-jars
         {:error "Failed to resolve classpath. Is this a deps.edn project?"}
         (let [library (:library opts)
-              cache-key [project-dir library (needs-java-sources? opts)]
+              cache-key [project-dir library (:type opts)]
               filtered-jars (filter-jars-by-library base-jars library)]
           (if (empty? filtered-jars)
             {:error (str "No libraries found matching: " (:library opts)

src/clojure_mcp/tools/deps_grep/tool.clj

@@ -21,9 +21,12 @@
   "Search for patterns in dependency jar files on the classpath.
 - Uses `clojure -Spath` to resolve the exact dependency jars
 - Searches inside jar files for matching content
-- Supports glob patterns to filter file types (e.g., \"*.clj\", \"*.java\")
+- The `type` parameter is required and indicates the jar ecosystem:
+  - \"clj\": Clojure libraries (source is in the jar, searched directly)
+  - \"java\": Java libraries (source jars downloaded from Maven Central)
+- Binary files (.class, images, native libs) are always excluded
+- Optional `glob` parameter narrows which files are searched (e.g., \"*.java\", \"*test*\")
 - Three output modes: content (with line numbers), files_with_matches, count
-- Use this to find code patterns in your project's dependencies
 - Results include both jar path and entry path for use with deps_read tool
 - Requires: clojure CLI. Optional: ripgrep (rg) for context/multiline support
 - For Java sources: also requires curl (downloads sources from Maven Central)")
@@ -37,15 +40,16 @@
                 :glob {:type :string
                        :description "Glob pattern to filter files (e.g., \"*.clj\", \"*.{clj,java}\")"}
                 :type {:type :string
-                       :description "File type to search (e.g., \"clj\", \"java\"). Alternative to glob."}
+                       :enum ["clj" "java"]
+                       :description "Jar ecosystem type. \"clj\" for Clojure libraries (source in jar), \"java\" for Java libraries (downloads source jars from Maven Central)."}
                 :output_mode {:type :string
                               :enum ["content" "files_with_matches" "count"]
                               :description "Output mode: 'content' shows matching lines, 'files_with_matches' shows file paths, 'count' shows match count"}
                 :case_insensitive {:type :boolean
                                    :description "Case insensitive search"}
                 :head_limit {:type :integer
                              :description "Limit output to first N results"}}
-   :required [:pattern :library]})
+   :required [:pattern :library :type]})
 
 (defmethod tool-system/validate-inputs :deps-grep [{:keys [nrepl-client-atom]} inputs]
   (let [{:keys [pattern library glob type output_mode case_insensitive head_limit]} inputs
@@ -57,6 +61,10 @@
       (throw (ex-info "Missing required parameter: pattern" {:inputs inputs})))
     (when-not library
       (throw (ex-info "Missing required parameter: library" {:inputs inputs})))
+    (when-not type
+      (throw (ex-info "Missing required parameter: type (must be \"clj\" or \"java\")" {:inputs inputs})))
+    (when-not (#{"clj" "java"} type)
+      (throw (ex-info (str "Invalid type: \"" type "\". Must be \"clj\" or \"java\"") {:inputs inputs})))
 
     {:project-dir project-dir
      :pattern pattern