klee 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 508af2506e1d6db7fbadde901c29284c219ee4cf7471dac68a21d34110b82a2d
-  data.tar.gz: c9dcc725e9a626c9f1ff45c68e46868eaa25166ccf4e88d93bcd0009a3a7211e
+  metadata.gz: 6ad4060f69da403186a89fb198ddfdb917606eac5e3344dcb5b0cc58f3d1bdd8
+  data.tar.gz: 90b540e449684b48e71714194b3c622f9fd35ecae931cb4b94fb53545f338958
 SHA512:
-  metadata.gz: e411a8b0c08b4304327663139192ccaed4a05d62048b94b151564065d71b5c3f574c780b3e278c127c54368744a2cd99ad5fd8ba514fb1f1545b65a1977fb17d
-  data.tar.gz: dcc64449cbfc1d0f60243f4a2eeee661d5075a271b79c3906b476af37bcc9624b6d740424df96596103f13af663932003aa76b002bb453a82b8da413c68f8d3f
+  metadata.gz: 46ed4f0a4469aee13b165138f3ff04da7b30819e6e37b01524e750df591a52cf6da53dc2f082a8c353a1bfa6a47e37111814baf8bbcdd377f246797ea12ec283
+  data.tar.gz: 77af3a015eb3e3fd8267b78525e46f53bb51694b2160d12a04e05bf6c04734549ed628a9cb5a8955cf4c9d6d4ec3ac1a544b011556125fdd5d07d2e1b6b71037

data/CHANGELOG.md

@@ -1,5 +1,41 @@
-## [Unreleased]
+# Changelog
 
-## [0.1.0] - 2022-05-01
+All notable changes to this project will be documented in this file.
 
-- Initial release
+The format is based on [Keep a Changelog](http://keepachangelog.com/)
+and this project adheres to [Semantic Versioning](http://semver.org/).
+
+## [0.1.2] - 2026-02-01
+
+### Added
+
+- MCP server support via klee-mcp executable (requires gem install mcp) (08c2294)
+- discover_vocabulary tool for extracting domain language (08c2294)
+- find_concept_clusters tool for identifying related concepts (08c2294)
+- explore_concept tool for deep-diving into specific concepts (08c2294)
+- find_collaborators tool for finding co-occurring objects (08c2294)
+- check_naming_consistency tool for detecting naming deviations (08c2294)
+- codebase_summary tool for high-level vocabulary overview (08c2294)
+
+### Changed
+
+- README now includes MCP server setup and available tools (f84bdc5)
+
+## [0.1.1] - 2026-01-29
+
+### Changed
+
+- Switch to supporting ruby 3.4 and up. (84fdd9c)
+- Require ruby 3.4 and above (067ec87)
+
+### Added
+
+- Reissue for version and release support. (885fe28)
+- SimpleCov for coverage reporting (889d169)
+- Coverage comment from PRs (067ec87)
+- Klee.scan() method for codebase-wide analysis with glob patterns (3e509a1)
+- ConceptIndex for aggregating domain concepts across files (3e509a1)
+- CollaboratorIndex for pairwise co-occurrence and clustering (3e509a1)
+- FileAnalyzer using Prism AST to extract classes, methods, and collaborators (3e509a1)
+- Configurable threshold and ignore list for filtering noise (3e509a1)
+- Method-level scope option for tighter coupling analysis (3e509a1)

data/README.md

@@ -52,6 +52,87 @@ filtered = Klee.object_concepts(Something, modifiers: %i[fill_in_ hover_over_ _m
 filtered[4] #=> Set of concepts excluding any common modifiers
 ```
 
+### Scan a codebase for domain concepts
+
+Discover hidden vocabulary across your entire codebase by analyzing class and method names.
+
+```ruby
+codebase = Klee.scan("app/**/*.rb", "lib/**/*.rb")
+
+# See all concepts ranked by frequency
+codebase.concepts.rank
+# => {
+#   "user" => { classes: Set["User", "UserSession"], methods: Set["current_user", "find_user"] },
+#   "account" => { classes: Set["Account", "AccountManager"], methods: Set["account_balance"] },
+#   ...
+# }
+
+# Drill into a specific concept
+codebase.concepts[:account]
+# => { classes: Set["Account", "AccountManager"], methods: Set["account_balance", "close_account"] }
+
+# Filter noise with ignore list and threshold
+codebase = Klee.scan("app/**/*.rb",
+                     ignore: %i[new create get set find all],
+                     threshold: 3)
+```
+
+### Find collaborator clusters
+
+Discover which objects frequently work together across your codebase.
+
+```ruby
+codebase = Klee.scan("app/**/*.rb", threshold: 3)
+
+# Pairwise co-occurrence (which objects appear together in files)
+codebase.collaborators.pairs
+# => { ["account", "user"] => 15, ["session", "user"] => 12, ... }
+
+# Method-level co-occurrence (tighter coupling)
+codebase.collaborators.pairs(scope: :method)
+# => { ["account", "user"] => 8, ... }
+
+# What collaborates with a specific object
+codebase.collaborators.for(:user)
+# => { "account" => 15, "session" => 12, "order" => 5 }
+
+# Derived clusters (connected components)
+codebase.collaborators.clusters
+# => [Set["user", "account", "session"], Set["order", "payment", "invoice"]]
+```
+
+### MCP Server for Claude Code
+
+Expose klee's vocabulary analysis to Claude Code or other MCP clients.
+
+```bash
+# Install the mcp gem (optional dependency)
+gem install mcp
+
+# Run the server
+klee-mcp
+```
+
+Configure Claude Code in `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "klee": {
+      "command": "klee-mcp"
+    }
+  }
+}
+```
+
+Available tools:
+- `discover_vocabulary` - Extract domain language from a codebase
+- `find_concept_clusters` - Identify groups of related concepts
+- `explore_concept` - Deep-dive into a specific concept
+- `find_collaborators` - Find objects that work together
+- `check_naming_consistency` - Detect naming pattern deviations
+- `codebase_summary` - High-level vocabulary overview
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/exe/klee-mcp

@@ -0,0 +1,21 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+begin
+  require "mcp"
+rescue LoadError
+  warn <<~ERROR
+    klee-mcp requires the 'mcp' gem for MCP server support.
+
+    Install it with:
+      gem install mcp
+
+    Then run klee-mcp again.
+  ERROR
+  exit 1
+end
+
+require "klee"
+require "klee/mcp"
+
+Klee::MCP::Server.new.run

data/lib/klee/codebase.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Klee
+  class Codebase
+    def initialize(*patterns, ignore: [], threshold: 2)
+      @patterns = patterns
+      @ignore = ignore
+      @threshold = threshold
+    end
+
+    def concepts
+      @concepts ||= build_concept_index
+    end
+
+    def collaborators
+      @collaborators ||= build_collaborator_index
+    end
+
+    private
+
+    def files
+      @patterns.flat_map { |p| Dir.glob(p) }
+        .uniq
+        .select { |f| File.file?(f) && f.end_with?(".rb") }
+    end
+
+    def analyzers
+      @analyzers ||= files.map { |path| FileAnalyzer.new(path) }
+    end
+
+    def build_concept_index
+      index = ConceptIndex.new(ignore: @ignore, threshold: @threshold)
+      analyzers.each { |a| index.add(a) }
+      index
+    end
+
+    def build_collaborator_index
+      index = CollaboratorIndex.new(ignore: @ignore, threshold: @threshold)
+      analyzers.each { |a| index.add(a) }
+      index
+    end
+  end
+end

data/lib/klee/collaborator_index.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Klee
+  class CollaboratorIndex
+    def initialize(ignore: [], threshold: 2)
+      @ignore = Set.new(ignore.map(&:to_s))
+      @threshold = threshold
+      @file_pairs = Hash.new(0)
+      @method_pairs = Hash.new(0)
+    end
+
+    def add(file_analyzer)
+      # File-level pairs
+      collabs = filter(file_analyzer.collaborators.uniq)
+      each_pair(collabs) { |pair| @file_pairs[pair] += 1 }
+
+      # Method-level pairs
+      file_analyzer.method_collaborators.each_value do |method_collabs|
+        filtered = filter(method_collabs.uniq)
+        each_pair(filtered) { |pair| @method_pairs[pair] += 1 }
+      end
+    end
+
+    def pairs(scope: :file)
+      source = (scope == :method) ? @method_pairs : @file_pairs
+      source.select { |_, count| count >= @threshold }
+        .sort_by { |_, count| -count }.to_h
+    end
+
+    def for(collaborator)
+      name = collaborator.to_s
+      pairs.select { |pair, _| pair.include?(name) }
+        .transform_keys { |pair| (pair - [name]).first }
+    end
+
+    def clusters
+      build_clusters(pairs)
+    end
+
+    private
+
+    def filter(names)
+      names.map(&:to_s).reject { |n| @ignore.include?(n) }
+    end
+
+    def each_pair(items)
+      items.combination(2).each { |pair| yield pair.sort }
+    end
+
+    def build_clusters(pair_data)
+      graph = Hash.new { |h, k| h[k] = Set.new }
+      pair_data.each_key do |(a, b)|
+        graph[a] << b
+        graph[b] << a
+      end
+
+      visited = Set.new
+      clusters = []
+
+      graph.each_key do |node|
+        next if visited.include?(node)
+
+        cluster = Set.new
+        stack = [node]
+
+        while stack.any?
+          current = stack.pop
+          next if visited.include?(current)
+
+          visited << current
+          cluster << current
+          stack.concat(graph[current].to_a)
+        end
+
+        clusters << cluster if cluster.size > 1
+      end
+
+      clusters.sort_by { |c| -c.size }
+    end
+  end
+end

data/lib/klee/collaborators.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Klee
+  class Collaborators
+    def initialize(const)
+      @const = const
+    end
+    attr_reader :const
+
+    def lexed
+      Prism.lex_file(Object.const_source_location(const.name).first)
+    end
+
+    def additional_processing_types = [:DOT, :BRACKET_LEFT]
+
+    def identifier_with_additional_processing
+      lexed.value.each_cons(2).filter_map do |(token, next_token)|
+        if token.first.type == :IDENTIFIER &&
+            additional_processing_types.include?(next_token.first.type)
+          token.first.value
+        end
+      end
+    end
+
+    def tally
+      identifier_with_additional_processing.tally
+    end
+
+    def rank
+      tally.group_by do |_, count|
+        count
+      end.sort.reverse.to_h.transform_values do |value|
+        value.map(&:first)
+      end.reject do |key, value|
+        value.empty? || key < 3
+      end
+    end
+  end
+end

data/lib/klee/concept_index.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Klee
+  class ConceptIndex
+    include Enumerable
+
+    def initialize(ignore: [], threshold: 2)
+      @ignore = Set.new(ignore.map(&:to_s))
+      @threshold = threshold
+      @data = Hash.new { |h, k| h[k] = {classes: Set.new, methods: Set.new} }
+    end
+
+    def add(file_analyzer)
+      file_analyzer.class_names.each do |name|
+        words_from(name).each { |word| @data[word][:classes] << name }
+      end
+
+      file_analyzer.method_names.each do |name|
+        words_from(name).each { |word| @data[word][:methods] << name }
+      end
+    end
+
+    def [](concept)
+      @data[concept.to_s]
+    end
+
+    def each(&block)
+      filtered.each(&block)
+    end
+
+    def rank
+      filtered.sort_by { |word, locs| -(locs[:classes].size + locs[:methods].size) }.to_h
+    end
+
+    private
+
+    def words_from(name)
+      name.to_s.gsub(/([a-z])([A-Z])/, '\1_\2')
+        .downcase.split("_")
+        .reject { |w| w.empty? || @ignore.include?(w) }
+    end
+
+    def filtered
+      @data.select { |_, locs| (locs[:classes].size + locs[:methods].size) >= @threshold }
+    end
+  end
+end

data/lib/klee/concepts.rb

@@ -26,7 +26,7 @@ module Klee
 
     def clear
       clearable = instance_variables - %i[@method_names @modifiers]
-      clearable.each { send(:remove_instance_variable, _1) }
+      clearable.each { send(:remove_instance_variable, it) }
     end
 
     def each(&block)
@@ -34,7 +34,7 @@ module Klee
     end
 
     def samples
-      @samples ||= method_names.flat_map{ words(_1) }.tally
+      @samples ||= method_names.flat_map { words(it) }.tally
     end
 
     def max
@@ -52,7 +52,7 @@ module Klee
     private
 
     def modifier_matcher
-      @modifier_matcher ||= Regexp.new modifiers.map{ Regexp.quote(_1) }.join("|")
+      @modifier_matcher ||= Regexp.new modifiers.map { Regexp.quote(it) }.join("|")
     end
 
     def words(method_name)
@@ -66,7 +66,7 @@ module Klee
         end
         .gsub(/\s/, "")
         .split("_")
-        .delete_if { _1.empty? }
+        .delete_if { it.empty? }
     end
   end
 end

data/lib/klee/file_analyzer.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Klee
+  class FileAnalyzer
+    attr_reader :path, :class_names, :method_names, :collaborators, :method_collaborators
+
+    def initialize(path)
+      @path = path
+      @class_names = []
+      @method_names = []
+      @collaborators = []
+      @method_collaborators = Hash.new { |h, k| h[k] = [] }
+      parse
+    end
+
+    private
+
+    def parse
+      result = Prism.parse_file(@path)
+      visit(result.value, current_method: nil)
+    end
+
+    def visit(node, current_method:)
+      case node
+      when Prism::ClassNode, Prism::ModuleNode
+        @class_names << node.name.to_s
+      when Prism::DefNode
+        @method_names << node.name.to_s
+        current_method = node.name.to_s
+      when Prism::CallNode
+        name = extract_collaborator(node)
+        if name
+          @collaborators << name
+          @method_collaborators[current_method] << name if current_method
+        end
+      end
+
+      node.child_nodes.compact.each { |child| visit(child, current_method: current_method) }
+    end
+
+    def extract_collaborator(call_node)
+      receiver = call_node.receiver
+      case receiver
+      when Prism::LocalVariableReadNode
+        receiver.name.to_s
+      when Prism::InstanceVariableReadNode
+        receiver.name.to_s.delete_prefix("@")
+      when Prism::CallNode
+        # Chain like user.account.name - extract the root
+        extract_collaborator(receiver)
+      end
+    end
+  end
+end

data/lib/klee/gestalt.rb

@@ -1,4 +1,3 @@
-require "set"
 module Klee
   class Gestalt
     def initialize(object, patterns:, ignored:)
@@ -49,15 +48,15 @@ module Klee
     end
 
     def prefixes
-      plot.select { |key, _| patterns.prefixes.include?(key) }
+      plot.slice(*patterns.prefixes)
     end
 
     def infixes
-      plot.select { |key, _| patterns.infixes.include?(key) }
+      plot.slice(*patterns.infixes)
     end
 
     def suffixes
-      plot.select { |key, _| patterns.suffixes.include?(key) }
+      plot.slice(*patterns.suffixes)
     end
 
     def unusual?(*items)

data/lib/klee/mcp/path_validator.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Klee
+  module MCP
+    class PathValidator
+      def initialize(allowed_roots: [Dir.pwd])
+        @allowed_roots = allowed_roots.map { |r| File.expand_path(r) }
+      end
+
+      def validate!(patterns)
+        patterns.each do |pattern|
+          expanded = expand_pattern_root(pattern)
+          unless allowed?(expanded)
+            raise SecurityError, "Pattern '#{pattern}' resolves to '#{expanded}' which is outside allowed roots: #{@allowed_roots.join(", ")}"
+          end
+        end
+      end
+
+      private
+
+      def expand_pattern_root(pattern)
+        base = pattern.split(/[*?\[{]/).first || "."
+        base = "." if base.empty?
+        File.expand_path(base)
+      end
+
+      def allowed?(path)
+        @allowed_roots.any? { |root| path.start_with?(root) }
+      end
+    end
+  end
+end

data/lib/klee/mcp/server.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "mcp"
+require_relative "tools/discover_vocabulary"
+require_relative "tools/find_concept_clusters"
+require_relative "tools/explore_concept"
+require_relative "tools/find_collaborators"
+require_relative "tools/check_naming_consistency"
+require_relative "tools/codebase_summary"
+
+module Klee
+  module MCP
+    class Server
+      TOOLS = [
+        Tools::DiscoverVocabulary,
+        Tools::FindConceptClusters,
+        Tools::ExploreConcept,
+        Tools::FindCollaborators,
+        Tools::CheckNamingConsistency,
+        Tools::CodebaseSummary
+      ].freeze
+
+      def initialize
+        @server = ::MCP::Server.new(
+          name: "klee",
+          version: Klee::MCP::VERSION,
+          tools: TOOLS
+        )
+      end
+
+      def run
+        transport = ::MCP::Server::Transports::StdioTransport.new(@server)
+        transport.open
+      end
+    end
+  end
+end

data/lib/klee/mcp/tools/check_naming_consistency.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Klee
+  module MCP
+    module Tools
+      class CheckNamingConsistency < ::MCP::Tool
+        description "Find methods that deviate from established naming patterns. Identifies unusual names and suggests alternatives based on common conventions in the codebase."
+
+        input_schema(
+          properties: {
+            patterns: {
+              type: "array",
+              items: {type: "string"},
+              description: "Glob patterns to match Ruby files, e.g. ['app/**/*.rb']"
+            },
+            conventions: {
+              type: "object",
+              properties: {
+                prefixes: {
+                  type: "array",
+                  items: {type: "string"},
+                  description: "Expected method prefixes, e.g. ['find_', 'create_', 'update_', 'delete_']"
+                },
+                suffixes: {
+                  type: "array",
+                  items: {type: "string"},
+                  description: "Expected method suffixes, e.g. ['?', '!', '_at', '_by']"
+                }
+              },
+              description: "Naming conventions to check against"
+            },
+            threshold: {
+              type: "integer",
+              description: "Levenshtein distance threshold for similarity suggestions (default: 6)"
+            },
+            ignore: {
+              type: "array",
+              items: {type: "string"},
+              description: "Method names to ignore"
+            }
+          },
+          required: ["patterns"]
+        )
+
+        class << self
+          def call(patterns:, conventions: {}, threshold: 6, ignore: [], server_context: nil)
+            validator = Klee::MCP::PathValidator.new
+            validator.validate!(patterns)
+
+            codebase = Klee.scan(*patterns, ignore: ignore, threshold: 1)
+            all_methods = codebase.concepts.flat_map { |_, locs| locs[:methods].to_a }.uniq
+
+            prefixes = conventions["prefixes"] || conventions[:prefixes] || []
+            suffixes = conventions["suffixes"] || conventions[:suffixes] || []
+
+            conforming = {}
+            unusual = []
+
+            prefixes.each do |prefix|
+              matched = all_methods.select { |m| m.start_with?(prefix) }
+              conforming["#{prefix}*"] = matched.sort if matched.any?
+            end
+
+            suffixes.each do |suffix|
+              matched = all_methods.select { |m| m.end_with?(suffix) }
+              conforming["*#{suffix}"] = matched.sort if matched.any?
+            end
+
+            conforming_methods = conforming.values.flatten.uniq
+            non_conforming = all_methods - conforming_methods
+
+            non_conforming.each do |method|
+              suggestion = find_similar(method, conforming_methods, threshold)
+              unusual << if suggestion
+                {
+                  method: method,
+                  suggestion: suggestion[:name],
+                  similarity: suggestion[:distance]
+                }
+              else
+                {method: method, suggestion: nil, similarity: nil}
+              end
+            end
+
+            unusual.sort_by! { |u| u[:similarity] || Float::INFINITY }
+
+            result = {
+              conforming: conforming,
+              unusual: unusual.first(50)
+            }
+
+            ::MCP::Tool::Response.new([{
+              type: "text",
+              text: JSON.pretty_generate(result)
+            }])
+          end
+
+          private
+
+          def find_similar(method, candidates, max_distance)
+            best = nil
+            best_distance = max_distance + 1
+
+            candidates.each do |candidate|
+              distance = levenshtein_distance(method, candidate)
+              if distance < best_distance
+                best = candidate
+                best_distance = distance
+              end
+            end
+
+            best ? {name: best, distance: best_distance} : nil
+          end
+
+          def levenshtein_distance(a, b)
+            return b.length if a.empty?
+            return a.length if b.empty?
+
+            matrix = Array.new(a.length + 1) { Array.new(b.length + 1) }
+
+            (0..a.length).each { |i| matrix[i][0] = i }
+            (0..b.length).each { |j| matrix[0][j] = j }
+
+            (1..a.length).each do |i|
+              (1..b.length).each do |j|
+                cost = (a[i - 1] == b[j - 1]) ? 0 : 1
+                matrix[i][j] = [
+                  matrix[i - 1][j] + 1,
+                  matrix[i][j - 1] + 1,
+                  matrix[i - 1][j - 1] + cost
+                ].min
+              end
+            end
+
+            matrix[a.length][b.length]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/klee/mcp/tools/codebase_summary.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Klee
+  module MCP
+    module Tools
+      class CodebaseSummary < ::MCP::Tool
+        description "Get a high-level vocabulary overview of a Ruby codebase for quick onboarding. Shows top domain concepts, concept clusters, and vocabulary metrics."
+
+        input_schema(
+          properties: {
+            patterns: {
+              type: "array",
+              items: {type: "string"},
+              description: "Glob patterns to match Ruby files, e.g. ['app/**/*.rb', 'lib/**/*.rb']"
+            },
+            threshold: {
+              type: "integer",
+              description: "Minimum occurrences for concepts (default: 2)"
+            },
+            ignore: {
+              type: "array",
+              items: {type: "string"},
+              description: "Words to ignore"
+            }
+          },
+          required: ["patterns"]
+        )
+
+        class << self
+          def call(patterns:, threshold: 2, ignore: [], server_context: nil)
+            validator = Klee::MCP::PathValidator.new
+            validator.validate!(patterns)
+
+            codebase = Klee.scan(*patterns, ignore: ignore, threshold: threshold)
+
+            ranked = codebase.concepts.rank
+            top_concepts = ranked.first(15).map(&:first)
+
+            clusters = codebase.collaborators.clusters
+
+            total_classes = Set.new
+            total_methods = Set.new
+            total_identifiers = 0
+
+            codebase.concepts.each do |_, locs|
+              total_classes.merge(locs[:classes])
+              total_methods.merge(locs[:methods])
+              total_identifiers += locs[:classes].size + locs[:methods].size
+            end
+
+            unique_concepts = ranked.keys.size
+            vocabulary_richness = total_identifiers.zero? ? 0 : (unique_concepts.to_f / total_identifiers).round(2)
+
+            result = {
+              top_concepts: top_concepts,
+              concept_clusters: clusters.size,
+              total_classes: total_classes.size,
+              total_methods: total_methods.size,
+              vocabulary_richness: vocabulary_richness,
+              cluster_preview: clusters.first(3).map { |c| c.to_a.sort }
+            }
+
+            ::MCP::Tool::Response.new([{
+              type: "text",
+              text: JSON.pretty_generate(result)
+            }])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/klee/mcp/tools/discover_vocabulary.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Klee
+  module MCP
+    module Tools
+      class DiscoverVocabulary < ::MCP::Tool
+        description "Extract the domain language vocabulary from a Ruby codebase. Returns words that appear frequently in class and method names, revealing the key domain concepts."
+
+        input_schema(
+          properties: {
+            patterns: {
+              type: "array",
+              items: {type: "string"},
+              description: "Glob patterns to match Ruby files, e.g. ['app/**/*.rb', 'lib/**/*.rb']"
+            },
+            threshold: {
+              type: "integer",
+              description: "Minimum occurrences for a word to be included (default: 3)"
+            },
+            limit: {
+              type: "integer",
+              description: "Maximum number of vocabulary terms to return (default: 30)"
+            },
+            ignore: {
+              type: "array",
+              items: {type: "string"},
+              description: "Words to ignore, e.g. common terms like 'get', 'set', 'new'"
+            }
+          },
+          required: ["patterns"]
+        )
+
+        class << self
+          def call(patterns:, threshold: 3, limit: 30, ignore: [], server_context: nil)
+            validator = Klee::MCP::PathValidator.new
+            validator.validate!(patterns)
+
+            codebase = Klee.scan(*patterns, ignore: ignore, threshold: threshold)
+            ranked = codebase.concepts.rank
+
+            vocabulary = ranked.first(limit).map do |word, locations|
+              {
+                word: word,
+                frequency: locations[:classes].size + locations[:methods].size,
+                in_classes: locations[:classes].to_a,
+                in_methods: locations[:methods].to_a
+              }
+            end
+
+            ::MCP::Tool::Response.new([{
+              type: "text",
+              text: JSON.pretty_generate({vocabulary: vocabulary})
+            }])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/klee/mcp/tools/explore_concept.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Klee
+  module MCP
+    module Tools
+      class ExploreConcept < ::MCP::Tool
+        description "Deep-dive into a specific domain concept to see everywhere it appears in the codebase, what it co-occurs with, and naming patterns used."
+
+        input_schema(
+          properties: {
+            patterns: {
+              type: "array",
+              items: {type: "string"},
+              description: "Glob patterns to match Ruby files, e.g. ['app/**/*.rb']"
+            },
+            concept: {
+              type: "string",
+              description: "The domain concept word to explore, e.g. 'subscription', 'user', 'order'"
+            },
+            threshold: {
+              type: "integer",
+              description: "Minimum occurrences threshold (default: 1)"
+            },
+            ignore: {
+              type: "array",
+              items: {type: "string"},
+              description: "Words to ignore"
+            }
+          },
+          required: ["patterns", "concept"]
+        )
+
+        class << self
+          def call(patterns:, concept:, threshold: 1, ignore: [], server_context: nil)
+            validator = Klee::MCP::PathValidator.new
+            validator.validate!(patterns)
+
+            codebase = Klee.scan(*patterns, ignore: ignore, threshold: threshold)
+            concept_data = codebase.concepts[concept]
+
+            collaborator_pairs = codebase.collaborators.for(concept)
+            co_occurs_with = collaborator_pairs.keys.sort_by { |k| -collaborator_pairs[k] }
+
+            methods = concept_data[:methods].to_a
+            naming_patterns = methods.group_by { |m| extract_pattern(m, concept) }
+              .transform_values(&:sort)
+
+            result = {
+              concept: concept,
+              appears_in: {
+                classes: concept_data[:classes].to_a.sort,
+                methods: methods.sort
+              },
+              co_occurs_with: co_occurs_with,
+              naming_patterns: naming_patterns
+            }
+
+            ::MCP::Tool::Response.new([{
+              type: "text",
+              text: JSON.pretty_generate(result)
+            }])
+          end
+
+          private
+
+          def extract_pattern(method_name, concept)
+            case method_name
+            when /^#{concept}_/ then "#{concept}_*"
+            when /_#{concept}$/ then "*_#{concept}"
+            when /_#{concept}_/ then "*_#{concept}_*"
+            when /#{concept}\?$/ then "#{concept}?"
+            when /#{concept}!$/ then "#{concept}!"
+            else "other"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/klee/mcp/tools/find_collaborators.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Klee
+  module MCP
+    module Tools
+      class FindCollaborators < ::MCP::Tool
+        description "Discover which objects conceptually belong together by analyzing co-occurrence patterns. Shows what a given object typically works with."
+
+        input_schema(
+          properties: {
+            patterns: {
+              type: "array",
+              items: {type: "string"},
+              description: "Glob patterns to match Ruby files, e.g. ['app/**/*.rb']"
+            },
+            object: {
+              type: "string",
+              description: "The object/variable name to find collaborators for, e.g. 'User', 'order', 'cart'"
+            },
+            threshold: {
+              type: "integer",
+              description: "Minimum co-occurrences to be considered a collaborator (default: 2)"
+            },
+            scope: {
+              type: "string",
+              enum: ["file", "method"],
+              description: "Scope for finding collaborators: 'file' (default) or 'method' level"
+            },
+            ignore: {
+              type: "array",
+              items: {type: "string"},
+              description: "Object names to ignore"
+            }
+          },
+          required: ["patterns", "object"]
+        )
+
+        class << self
+          def call(patterns:, object:, threshold: 2, scope: "file", ignore: [], server_context: nil)
+            validator = Klee::MCP::PathValidator.new
+            validator.validate!(patterns)
+
+            codebase = Klee.scan(*patterns, ignore: ignore, threshold: threshold)
+            pairs = codebase.collaborators.pairs(scope: scope.to_sym)
+
+            relevant_pairs = pairs.select { |pair, _| pair.include?(object) }
+
+            collaborators = relevant_pairs.map do |pair, count|
+              other = (pair - [object]).first
+              {
+                name: other,
+                co_occurrences: count,
+                scope: scope
+              }
+            end.sort_by { |c| -c[:co_occurrences] }
+
+            result = {
+              object: object,
+              collaborators: collaborators
+            }
+
+            ::MCP::Tool::Response.new([{
+              type: "text",
+              text: JSON.pretty_generate(result)
+            }])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/klee/mcp/tools/find_concept_clusters.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Klee
+  module MCP
+    module Tools
+      class FindConceptClusters < ::MCP::Tool
+        description "Identify groups of domain concepts that frequently appear together in code, suggesting logical module boundaries or related functionality."
+
+        input_schema(
+          properties: {
+            patterns: {
+              type: "array",
+              items: {type: "string"},
+              description: "Glob patterns to match Ruby files, e.g. ['app/**/*.rb']"
+            },
+            threshold: {
+              type: "integer",
+              description: "Minimum co-occurrences for concepts to be considered related (default: 2)"
+            },
+            ignore: {
+              type: "array",
+              items: {type: "string"},
+              description: "Collaborator names to ignore"
+            }
+          },
+          required: ["patterns"]
+        )
+
+        class << self
+          def call(patterns:, threshold: 2, ignore: [], server_context: nil)
+            validator = Klee::MCP::PathValidator.new
+            validator.validate!(patterns)
+
+            codebase = Klee.scan(*patterns, ignore: ignore, threshold: threshold)
+            raw_clusters = codebase.collaborators.clusters
+
+            clusters = raw_clusters.map do |cluster_set|
+              {
+                concepts: cluster_set.to_a.sort,
+                size: cluster_set.size
+              }
+            end
+
+            ::MCP::Tool::Response.new([{
+              type: "text",
+              text: JSON.pretty_generate({clusters: clusters})
+            }])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/klee/mcp/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Klee
+  module MCP
+    VERSION = "0.1.0"
+  end
+end

data/lib/klee/mcp.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "mcp/version"
+require_relative "mcp/path_validator"
+require_relative "mcp/server"
+
+module Klee
+  module MCP
+  end
+end

data/lib/klee/patterns.rb

@@ -9,7 +9,7 @@ module Klee
 
     def prefix(which)
       @patterns[__callee__].add which
-      send("to_#{__callee__}", which).tap { match(_1) }
+      send("to_#{__callee__}", which).tap { match(it) }
     end
     alias_method :suffix, :prefix
     alias_method :infix, :prefix
@@ -40,7 +40,7 @@ module Klee
     end
 
     def key_for(pattern)
-      keys.find { pattern =~ _1 }
+      keys.find { pattern =~ it }
     end
 
     private

data/lib/klee/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Klee
-  VERSION = "0.1.0"
+  VERSION = "0.1.2"
 end

data/lib/klee.rb

@@ -1,9 +1,15 @@
 # frozen_string_literal: true
 
+# require "classifier-reborn"
 require_relative "klee/version"
 require_relative "klee/patterns"
 require_relative "klee/gestalt"
 require_relative "klee/concepts"
+require_relative "klee/collaborators"
+require_relative "klee/file_analyzer"
+require_relative "klee/concept_index"
+require_relative "klee/collaborator_index"
+require_relative "klee/codebase"
 
 module Klee
   class Error < StandardError; end
@@ -20,10 +26,14 @@ module Klee
     Patterns.new(&block)
   end
 
-  def self.concepts(*methond_names, modifiers: [])
-    Concepts.new(*methond_names, modifiers: [])
+  def self.concepts(*method_names, modifiers: [])
+    Concepts.new(*method_names, modifiers: [])
   end
 
+  # def self.classifier
+  #   @classifier ||= ClassifierReborn::Bayes.new "Interesting", "Uninteresting"
+  # end
+
   def self.object_concepts(object, modifiers: [])
     names = if object.respond_to?(:public_instance_methods)
       object.public_instance_methods(false)
@@ -38,4 +48,12 @@ module Klee
     ignored: Class.instance_methods)
     Gestalt.new(object, patterns: patterns, ignored: ignored).trace(threshold: threshold)
   end
+
+  def self.collaborators(const)
+    Klee::Collaborators.new(const)
+  end
+
+  def self.scan(*patterns, ignore: [], threshold: 2)
+    Codebase.new(*patterns, ignore: ignore, threshold: threshold)
+  end
 end

data/sig/klee.rbs

@@ -0,0 +1,4 @@
+module Klee
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -1,21 +1,35 @@
 --- !ruby/object:Gem::Specification
 name: klee
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Jim Gay
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-05-06 00:00:00.000000000 Z
-dependencies: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: prism
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Evaluate the similarities and differences in your objects. Art does not
   reflect what is seen, rather it makes the hidden visible.
 email:
 - jim@saturnflyer.com
 executables:
 - klee
+- klee-mcp
 extensions: []
 extra_rdoc_files: []
 files:
@@ -26,11 +40,28 @@ files:
 - bin/console
 - bin/setup
 - exe/klee
+- exe/klee-mcp
 - lib/klee.rb
+- lib/klee/codebase.rb
+- lib/klee/collaborator_index.rb
+- lib/klee/collaborators.rb
+- lib/klee/concept_index.rb
 - lib/klee/concepts.rb
+- lib/klee/file_analyzer.rb
 - lib/klee/gestalt.rb
+- lib/klee/mcp.rb
+- lib/klee/mcp/path_validator.rb
+- lib/klee/mcp/server.rb
+- lib/klee/mcp/tools/check_naming_consistency.rb
+- lib/klee/mcp/tools/codebase_summary.rb
+- lib/klee/mcp/tools/discover_vocabulary.rb
+- lib/klee/mcp/tools/explore_concept.rb
+- lib/klee/mcp/tools/find_collaborators.rb
+- lib/klee/mcp/tools/find_concept_clusters.rb
+- lib/klee/mcp/version.rb
 - lib/klee/patterns.rb
 - lib/klee/version.rb
+- sig/klee.rbs
 homepage: https://github.com/saturnflyer/klee
 licenses:
 - MIT
@@ -38,7 +69,13 @@ metadata:
   homepage_uri: https://github.com/saturnflyer/klee
   source_code_uri: https://github.com/saturnflyer/klee
   changelog_uri: https://github.com/saturnflyer/klee/blob/main/CHANGELOG.md
-post_install_message:
+post_install_message: |
+  klee installed successfully!
+
+  For MCP server support (Claude Code integration), also install:
+    gem install mcp
+
+  Then run: klee-mcp
 rdoc_options: []
 require_paths:
 - lib
@@ -46,15 +83,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 3.4.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.27
-signing_key:
+rubygems_version: 4.0.5
 specification_version: 4
 summary: Evaluate the similarities and differences in your objects
 test_files: []