cov-loupe 3.0.0

data/docs/dev/arch-decisions/004-x-arch-decision.md

@@ -0,0 +1,203 @@
+# ADR 004: Ruby `instance_eval` for Success Predicates
+
+[Back to main README](../../README.md)
+
+## Status
+
+Accepted
+
+## Context
+
+SimpleCov MCP needed a mechanism for users to define custom coverage policies beyond simple percentage thresholds. Different projects have different requirements:
+
+- Some want all files above 80%, others allow a few files below threshold
+- Some need different thresholds for different directories (e.g., 90% for API code, 60% for legacy)
+- Some want total project coverage minimums
+- CI/CD pipelines need exit codes based on policy compliance
+
+We considered several approaches:
+
+1. **Built-in policy DSL**: Define a limited language for expressing policies (e.g., YAML/JSON config)
+2. **Plugin architecture**: Define a protocol/interface, require users to create Ruby classes implementing it
+3. **Ruby file evaluation**: Load and execute arbitrary Ruby code that returns a callable predicate
+4. **Sandboxed DSL**: Use a restricted Ruby environment (e.g., `$SAFE` levels, isolated VMs)
+
+### Key Requirements
+
+- Flexibility: Support arbitrarily complex coverage policies
+- Simplicity: Easy for users to write and understand
+- Debuggability: Users can use standard Ruby debugging tools
+- CI/CD integration: Clear exit codes (0 = pass, 1 = fail, 2 = error)
+- Access to coverage data: Predicates need access to the full `CoverageModel` API
+
+### Why Not a Custom DSL?
+
+A custom DSL would be:
+- Limited in expressiveness (hard to predict all future use cases)
+- Harder to debug (users can't use standard Ruby tools)
+- More maintenance burden (parsing, validation, documentation)
+- Still vulnerable to injection if it allowed any dynamic computation
+
+### Why Not Sandboxing?
+
+Ruby's sandboxing options are limited:
+- `$SAFE` levels were deprecated and removed in Ruby 2.7+
+- Full VM isolation (Docker, etc.) is too heavy for a CLI tool
+- Any Turing-complete sandbox can be escaped given enough effort
+- True security requires not executing untrusted code at all
+
+## Decision
+
+We chose to **evaluate Ruby files using `instance_eval`** with prominent security warnings rather than attempting to create a false sense of security through incomplete sandboxing.
+
+### Implementation
+
+The implementation is in `lib/cov_loupe/cli.rb:191-214`:
+
+```ruby
+def load_success_predicate(path)
+  unless File.exist?(path)
+    raise "Success predicate file not found: #{path}"
+  end
+
+  content = File.read(path)
+
+  # WARNING: The predicate code executes with full Ruby privileges.
+  # It has unrestricted access to the file system, network, and system commands.
+  # Only use predicate files from trusted sources.
+  #
+  # We evaluate in a fresh Object context to prevent accidental access to
+  # CLI internals, but this provides NO security isolation.
+  evaluation_context = Object.new
+  predicate = evaluation_context.instance_eval(content, path, 1)
+
+  unless predicate.respond_to?(:call)
+    raise "Success predicate must be callable (lambda, proc, or object with #call method)"
+  end
+
+  predicate
+rescue SyntaxError => e
+  raise "Syntax error in success predicate file: #{e.message}"
+end
+```
+
+The predicate is then called with a `CoverageModel` instance:
+
+```ruby
+def run_success_predicate
+  predicate = load_success_predicate(config.success_predicate)
+  model = CoverageModel.new(**config.model_options)
+
+  result = predicate.call(model)
+  exit(result ? 0 : 1)  # 0 = success, 1 = failure
+rescue => e
+  warn "Success predicate error: #{e.message}"
+  warn e.backtrace.first(5).join("\n") if config.error_mode == :debug
+  exit 2  # Exit code 2 for predicate errors
+end
+```
+
+### Security Model: Treat as Executable Code
+
+Rather than pretending to sandbox untrusted code, we treat success predicates **exactly like any other Ruby code in the project**:
+
+1. **Prominent warnings** in documentation (examples/success_predicates/README.md:5-17):
+   ```
+   ⚠️ SECURITY WARNING
+
+   Success predicates execute as arbitrary Ruby code with full system privileges.
+   Only use predicate files from trusted sources.
+   - Never use predicates from untrusted or unknown sources
+   - Review predicates before use, especially in CI/CD environments
+   - Store predicates in version control with code review
+   ```
+
+2. **Code review workflow**: Predicates live in version control alongside tests
+3. **CI/CD best practices**: Same permissions model as running tests themselves
+4. **Example predicates**: Well-documented examples showing safe patterns
+
+### Predicate API
+
+Success predicates must be callable (lambda, proc, or object with `#call` method):
+
+**Lambda example:**
+```ruby
+->(model) do
+  model.all_files.all? { |f| f['percentage'] >= 80 }
+end
+```
+
+**Class example:**
+
+```ruby
+
+class CoveragePolicy
+  def call(model)
+    api_files = model.all_files.select { |f| f['file'].start_with?('lib/api/') }
+    api_files.all? { |f| f['percentage'] >= 90 }
+  end
+end
+
+AllFilesAboveThreshold.new
+```
+
+The predicate receives a full `CoverageModel` instance with access to:
+- `all_files(tracked_globs:, sort_order:)` - All file coverage data
+- `summary_for(path)` - Coverage summary for a specific file
+- `uncovered_for(path)` - Uncovered lines for a specific file
+- `detailed_for(path)` - Per-line coverage data
+
+## Consequences
+
+### Positive
+
+1. **Maximum flexibility**: Users can express arbitrarily complex coverage policies using full Ruby
+2. **Familiar tooling**: Users can debug predicates with standard Ruby tools (pry, byebug, etc.)
+3. **Simplicity**: No custom DSL to learn, document, or maintain
+4. **Honesty**: Security model is clear and doesn't provide false confidence
+5. **Composability**: Users can require other libraries, define helper methods, etc.
+6. **Excellent examples**: We provide 5+ well-documented example predicates
+
+### Negative
+
+1. **Security responsibility**: Users must understand the security implications
+2. **Potential misuse**: Users might mistakenly trust untrusted predicate files
+3. **No isolation**: Buggy predicates can access/modify anything in the system
+4. **Documentation burden**: Must clearly communicate security model
+
+### Trade-offs
+
+- **Versus custom DSL**: More powerful and debuggable, but requires user awareness of security
+- **Versus plugin architecture**: Simpler (no gem dependencies, no protocol to learn), but same security profile
+- **Versus incomplete sandboxing**: Honest about capabilities rather than security theater
+
+### Threat Model
+
+This approach is **appropriate** when:
+- Predicate files are stored in version control with code review
+- Users treat predicates like any other code in their project (tests, Rakefile, etc.)
+- CI/CD environments already execute arbitrary code (tests, build scripts)
+
+This approach is **inappropriate** when:
+- Processing untrusted predicate files from unknown sources
+- Allowing users to upload predicates via web interface
+- Running in a multi-tenant environment without isolation
+
+### Future Considerations
+
+If demand arises for truly untrusted predicate execution, alternatives include:
+
+1. **JSON-based policy format**: Limited expressiveness but safe
+2. **WebAssembly sandbox**: Execute policies in an isolated WASM runtime
+3. **External process**: Run predicates in separate process with restricted permissions
+
+However, for the primary use case (CI/CD policy enforcement), the current approach is simpler and more flexible than these alternatives.
+
+## References
+
+- Implementation: `lib/cov_loupe/cli.rb:191-214` (load predicate), `lib/cov_loupe/cli.rb:179-189` (execute)
+- Security warnings: `examples/success_predicates/README.md:5-17`
+- Example predicates: `examples/success_predicates/*.rb`
+- CoverageModel API: `lib/cov_loupe/model.rb`
+- CLI config: `lib/cov_loupe/cli_config.rb:18` (success_predicate field)
+- Option parsing: `lib/cov_loupe/option_parser_builder.rb` (--success-predicate flag)

data/docs/dev/arch-decisions/005-x-arch-decision.md

@@ -0,0 +1,189 @@
+# ADR 005: No SimpleCov Runtime Dependency
+
+[Back to main README](../../README.md)
+
+## Status
+
+Replaced – cov-loupe now requires SimpleCov at runtime so that multi-suite resultsets can be merged using SimpleCov’s combine helpers.
+
+## Context
+
+SimpleCov MCP provides tooling for inspecting SimpleCov coverage reports. When designing the gem, we had to decide whether to depend on SimpleCov as a runtime dependency.
+
+### Alternative Approaches
+
+1. **Runtime dependency on SimpleCov**: Use SimpleCov's API to read and process coverage data
+2. **Development-only dependency**: Read SimpleCov's `.resultset.json` files directly without requiring SimpleCov at runtime
+3. **Support multiple coverage formats**: Parse coverage data from multiple tools (SimpleCov, Coverage, etc.)
+
+### Key Considerations
+
+**Dependency weight**: SimpleCov itself has dependencies:
+- `docile` (~> 1.1)
+- `simplecov-html` (~> 0.11)
+- `simplecov_json_formatter` (~> 0.1)
+
+**Use case separation**:
+- SimpleCov is needed when **running tests** to collect coverage
+- SimpleCov MCP is needed when **inspecting coverage** after tests complete
+- These are temporally separated activities
+
+**Deployment contexts**:
+- CI/CD: Coverage collection happens in test job, inspection might happen in a separate analysis job
+- Production: Some teams want to analyze coverage data without installing test dependencies
+- Developer machines: May want to inspect coverage without full test suite dependencies
+
+**Format stability**:
+- SimpleCov's `.resultset.json` format is stable and well-documented
+- The format is simple JSON with predictable structure
+- Breaking changes would affect all SimpleCov users, so the format is unlikely to change
+
+## Decision
+
+We chose to **make SimpleCov a development dependency only** and read `.resultset.json` files directly using Ruby's standard library JSON parser.
+
+### Implementation
+
+The gem only depends on `mcp` at runtime (cov-loupe.gemspec:26):
+```ruby
+# Runtime deps (stdlib: json, time, pathname)
+spec.add_runtime_dependency 'mcp', '~> 0.3'
+spec.add_development_dependency 'simplecov', '~> 0.21'
+```
+
+Coverage data is read directly from JSON files (lib/cov_loupe/model.rb:34-42):
+```ruby
+rs = CovUtil.find_resultset(@root, resultset: resultset)
+raw = JSON.parse(File.read(rs))
+# SimpleCov typically writes a single test suite entry to .resultset.json
+# Find the first entry that has coverage data (skip comment entries)
+_suite, data = raw.find { |k, v| v.is_a?(Hash) && v.key?('coverage') }
+raise "No test suite with coverage data found in resultset file: #{rs}" unless data
+cov = data['coverage'] or raise "No 'coverage' key found in resultset file: #{rs}"
+@cov = cov.transform_keys { |k| File.absolute_path(k, @root) }
+@cov_timestamp = (data['timestamp'] || data['created_at'] || 0).to_i
+```
+
+Coverage calculations use simple algorithms (lib/cov_loupe/util.rb:42-71):
+```ruby
+def summary(arr)
+  total = 0
+  covered = 0
+  arr.compact.each do |hits|
+    total += 1
+    covered += 1 if hits.to_i > 0
+  end
+  percentage = total.zero? ? 100.0 : ((covered.to_f * 100.0 / total) * 100).round / 100.0
+  { 'covered' => covered, 'total' => total, 'percentage' => percentage }
+end
+
+def uncovered(arr)
+  out = []
+  arr.each_with_index do |hits, i|
+    next if hits.nil?
+    out << (i + 1) if hits.to_i.zero?
+  end
+  out
+end
+
+def detailed(arr)
+  rows = []
+  arr.each_with_index do |hits, i|
+    h = hits&.to_i
+    rows << { 'line' => i + 1, 'hits' => h, 'covered' => h.positive? } if h
+  end
+  rows
+end
+```
+
+### SimpleCov .resultset.json Format
+
+The format we parse has this structure:
+```json
+{
+  "RSpec": {
+    "coverage": {
+      "/absolute/path/to/file.rb": {
+        "lines": [null, 1, 3, 0, null, 5, ...]
+      }
+    },
+    "timestamp": 1633072800
+  }
+}
+```
+
+Where:
+- Top level keys are test suite names (e.g., "RSpec", "Minitest")
+- `coverage` contains file paths mapped to coverage data
+- `lines` is an array where each index represents a line number (0-indexed)
+- Array values: `null` = not executable, `0` = not covered, `>0` = hit count
+- `timestamp` is Unix timestamp when coverage was collected
+
+### Resultset Discovery
+
+We implement flexible discovery of `.resultset.json` files (lib/cov_loupe/util.rb:6-10):
+```ruby
+RESULTSET_CANDIDATES = [
+  '.resultset.json',
+  'coverage/.resultset.json',
+  'tmp/.resultset.json'
+].freeze
+```
+
+This supports common SimpleCov configurations without requiring SimpleCov to be loaded.
+
+## Consequences
+
+### Positive
+
+1. **Lightweight installation**: No transitive dependencies beyond `mcp` gem
+2. **Deployment flexibility**: Can analyze coverage in environments without test dependencies
+3. **Faster installation**: Fewer gems to download and install
+4. **Clear separation of concerns**: Coverage collection vs. coverage analysis are independent
+5. **CI/CD optimization**: Analysis jobs don't need full test suite dependencies
+6. **Production-safe**: Can be deployed to production environments if needed (e.g., for monitoring)
+
+### Negative
+
+1. **Format dependency**: Tightly coupled to SimpleCov's JSON format
+2. **Breaking changes risk**: If SimpleCov changes `.resultset.json` structure, we must adapt
+3. **Limited to SimpleCov**: Cannot read coverage data from other Ruby coverage tools
+4. **Duplicate logic**: Coverage percentage calculations reimplemented (though simple)
+5. **Maintenance**: Must track SimpleCov format changes manually
+
+### Trade-offs
+
+- **Versus runtime dependency**: Lighter weight but less resilient to format changes
+- **Versus multi-format support**: Simpler implementation but locked to SimpleCov ecosystem
+- **Versus using SimpleCov API**: More flexible deployment but requires understanding the file format
+
+### Risk Mitigation
+
+1. **Format stability**: SimpleCov has maintained `.resultset.json` compatibility for years
+2. **Simple format**: JSON structure is straightforward and unlikely to change dramatically
+3. **Development dependency**: We still use SimpleCov in our own tests, so format changes would be detected immediately
+4. **Documentation**: CLAUDE.md documents the format dependency explicitly
+5. **Error handling**: Robust error messages when format doesn't match expectations
+
+### Format Evolution Strategy
+
+If SimpleCov's format changes:
+1. **Minor additions** (new keys): Ignore unknown keys, only parse what we need
+2. **Breaking changes** (structure changes): Version detection logic to support multiple formats
+3. **Alternative formats**: Could add support for other coverage tools' JSON formats if needed
+
+### Current Limitations Accepted
+
+- Only supports SimpleCov (not Coverage gem, other tools)
+- Assumes standard `.resultset.json` locations
+- No support for merged coverage from multiple test runs (SimpleCov handles this before writing JSON)
+- No support for branch coverage (SimpleCov feature not widely used yet)
+
+## References
+
+- Gemspec dependencies: `cov-loupe.gemspec:26-28`
+- JSON parsing: `lib/cov_loupe/model.rb:34-57`
+- Coverage calculations: `lib/cov_loupe/util.rb:42-71`
+- Resultset discovery: `lib/cov_loupe/util.rb:6-10`, `lib/cov_loupe/util.rb:34-36`
+- SimpleCov format documentation: https://github.com/simplecov-ruby/simplecov
+- Development usage: Uses SimpleCov in `spec/spec_helper.rb` to test itself

data/docs/dev/arch-decisions/README.md

@@ -0,0 +1,60 @@
+# Architecture Decision Records
+
+[Back to main README](../../README.md)
+
+## What is an ADR?
+
+An Architecture Decision Record (ADR) captures a significant architectural decision made during the development of this project, along with its context and consequences.
+
+## ADR Format
+
+Each ADR follows this structure:
+
+### Title
+A short phrase describing the decision (e.g., "Dual-Mode Operation: CLI and MCP Server")
+
+### Status
+- **Accepted**: The decision has been made and is currently in effect
+- **Proposed**: Under consideration
+- **Deprecated**: No longer applicable
+- **Superseded**: Replaced by a newer decision
+
+### Context
+The background, problem statement, and constraints that led to the decision.
+
+### Decision
+The architectural choice that was made.
+
+### Consequences
+The implications of this decision, both positive and negative. This includes:
+- Benefits gained
+- Trade-offs accepted
+- Complexity introduced
+- Future constraints
+
+### References
+Links to related code, issues, documentation, or other ADRs.
+
+## Index of ADRs
+
+- [001: Dual-Mode Operation](001-x-arch-decision.md) - CLI vs MCP server mode detection
+- [002: Context-Aware Error Handling](002-x-arch-decision.md) - Mode-specific error handling strategy
+- [003: Coverage Staleness Detection](003-x-arch-decision.md) - Three-type staleness system
+- [004: Ruby Instance Eval for Success Predicates](004-x-arch-decision.md) - Dynamic Ruby evaluation approach
+- [005: No SimpleCov Runtime Dependency](005-x-arch-decision.md) - Superseded by the multi-suite merge work (runtime SimpleCov dependency)
+
+## When to Create an ADR
+
+Create an ADR when:
+- Making a decision that affects the structure or behavior of the system
+- Choosing between multiple viable approaches
+- Accepting significant trade-offs
+- Making decisions that future maintainers should understand
+
+## Contributing
+
+When adding a new ADR:
+1. Use the next sequential number (e.g., `006-x-arch-decision.md`)
+2. Follow the format outlined above
+3. Update this README's index
+4. Link to relevant code and documentation

data/docs/dev/presentations/cov-loupe-presentation.md

@@ -0,0 +1,255 @@
+[Back to main README](../../README.md)
+
+---
+marp: true
+theme: default
+class: lead
+paginate: true
+backgroundColor: #fff
+color: #333
+---
+
+# SimpleCovMCP
+### MCP Server, CLI, and Library for SimpleCov Ruby Test Coverage 
+
+- Keith Bennett
+- First presented to PhRUG (Philippines Ruby User Group), 2025-10-01
+
+---
+
+## What is SimpleCov MCP?
+
+A **three-in-one** gem that makes SimpleCov coverage data accessible to:
+
+- 🤖 **AI agents** via Model Context Protocol (MCP)
+- 💻 **Command line** via its command line interface
+- 📚 **Ruby scripts and applications** as a library
+
+**Lazy dependency** on SimpleCov - single-suite resultsets avoid loading it; multi-suite files trigger a merge via SimpleCov’s combine helpers.
+
+What is it *not*? It is not a replacement for SimpleCov's generated web presentation of the coverage data.
+
+
+This code base requires a Ruby version >= 3.2.0, because this is required by the mcp gem it uses.
+
+---
+
+## High Level Objectives
+
+- Query coverage programmatically
+- Integrate with AI tools
+- Automate coverage analysis
+- Focus on specific files/patterns
+
+---
+
+## Key Features
+
+- **Lazy SimpleCov dependency** - only loaded when multi-suite resultsets need merging
+- **Flexible resultset location** - via CLI flags, passed parameter, or env var
+- **Staleness detection** - warns or optionally errors when files newer than coverage
+- **JSON output** - perfect for jq, scripts, CI/CD
+- **Source code integration** - show uncovered lines with or without context
+- **Colored output** - readable terminal display
+
+---
+
+## Demo 1: MCP Server Mode
+### AI Coverage Assistant
+
+```bash
+# Test the MCP server manually
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"coverage_summary_tool","arguments":{"path":"lib/cov_loupe/model.rb"}}}' | cov-loupe
+```
+
+**What AI agents can do:**
+- Analyze coverage gaps
+- Suggest testing priorities  
+- Generate ad-hoc coverage reports
+
+---
+
+## MCP Tools (Functions) Available
+
+| Tool                      | Purpose                    | Example CLI Command                                  |
+|---------------------------|----------------------------|------------------------------------------------------|
+| `all_files_coverage_tool` | Project-wide coverage data | `cov-loupe list`                                 |
+| `coverage_detailed_tool`  | Per-line hit counts        | `cov-loupe detailed lib/cov_loupe/model.rb`  |
+| `coverage_raw_tool`       | Raw SimpleCov lines array  | `cov-loupe raw lib/cov_loupe/model.rb`       |
+| `coverage_summary_tool`   | Get coverage % for a file  | `cov-loupe summary lib/cov_loupe/model.rb`   |
+| `coverage_table_tool`     | Formatted coverage table   | `cov-loupe list`                                 |
+| `coverage_totals_tool`    | Aggregated line totals     | `cov-loupe totals`                               |
+| `help_tool`               | Tool usage guidance        | `cov-loupe --help`                               |
+| `uncovered_lines_tool`    | Find missing test coverage | `cov-loupe uncovered lib/cov_loupe/cli.rb`   |
+| `version_tool`            | Display version info       | `cov-loupe version`                              |
+
+---
+
+## Demo 2: CLI Tool
+### 
+
+```bash
+# Show all files, worst coverage first
+cov-loupe
+
+# Focus on a specific file
+cov-loupe summary lib/cov_loupe/cli.rb
+
+# Find untested lines with source context
+cov-loupe uncovered lib/cov_loupe/cli.rb --source=uncovered --source-context 3
+
+# JSON for scripts
+cov-loupe -fJ | jq '.files[] | select(.percentage < 80)'
+
+# Ruby alternative:
+cov-loupe -fJ | ruby -r json -e '
+  JSON.parse($stdin.read)["files"].select { |f| f["percentage"] < 80 }.each do |f|
+    puts JSON.pretty_generate(f)
+  end
+'
+
+# Rexe alternative:
+cov-loupe -fJ | rexe -ij -mb -oJ 'self["files"].select { |f| f["percentage"] < 80 }'
+```
+
+---
+
+## Demo 2: CLI Tool (cont'd.)
+
+```bash
+# Custom resultset location
+cov-loupe --resultset coverage-all/
+
+# Sort by highest coverage
+cov-loupe --sort-order d
+
+# Staleness checking (file newer than coverage?)
+cov-loupe --staleness error
+
+# Track new files missing from coverage
+cov-loupe --tracked-globs "lib/**/tools/*.rb"
+```
+
+---
+
+## Demo 3: Ruby Library
+### Programmatic Integration
+
+```ruby
+require 'cov_loupe'
+
+model = CovLoupe::CoverageModel.new
+
+# Get project overview
+files = model.all_files
+puts "Lowest coverage: #{files.first['percentage']}%"
+
+# Focus on specific concerns
+uncovered = model.uncovered_for("lib/wifi-wand/models/ubuntu_model.rb")
+puts "Uncovered hash's keys: #{uncovered.keys.inspect}" 
+puts "Missing lines: #{uncovered['uncovered'].inspect}"
+
+# Output:
+# Lowest coverage: 17.0%
+# Uncovered hash's keys: ["file", "uncovered", "summary"]
+# Missing lines: [13, 17, 21,...200, 203]
+```
+
+---
+
+## Custom Threshold Git Pre-Commit Hook
+
+```ruby
+require 'cov_loupe'
+
+files = CovLoupe::CoverageModel.new.all_files
+critical, other = files.partition { |f| f['file'].include?('/lib/critical/') }
+
+fails = critical.select { |f| f['percentage'] < 100.0 } + 
+        other.select { |f| f['percentage'] < 90.0 }
+
+if fails.any?
+  puts "❌ Coverage failures:"
+  fails.each { |f| puts "  #{f['file']}: #{f['percentage']}%" }
+  exit 1
+else
+  puts "✅ All thresholds met!"
+end
+```
+
+---
+
+## Architecture Overview
+
+```
+lib/cov_loupe
+├── base_tool.rb
+├── cli.rb
+├── error_handler_factory.rb
+├── error_handler.rb
+├── errors.rb
+├── mcp_server.rb
+├── model.rb
+├── path_relativizer.rb
+├── staleness_checker.rb
+├── tools
+│ ├── all_files_coverage_tool.rb
+│ ├── coverage_detailed_tool.rb
+│ ├── coverage_raw_tool.rb
+│ ├── coverage_summary_tool.rb
+│ ├── coverage_table_tool.rb
+│ ├── coverage_totals_tool.rb
+│ ├── help_tool.rb
+│ ├── uncovered_lines_tool.rb
+│ └── version_tool.rb
+├── util.rb
+└── version.rb
+```
+
+**Clean separation:** CLI ↔ Model ↔ MCP Tools
+
+---
+
+## MCP Plumbing - the MCP Gem
+
+#### BaseTool subclasses the `mcp` gem's Tool class and defines a schema (see base_tool.rb):
+```ruby
+class BaseTool < ::MCP::Tool
+  # ...
+end
+```
+
+* [BaseTool source](https://github.com/keithrbennett/cov-loupe/blob/main/lib/cov_loupe/base_tool.rb)
+* [BaseTool subclass source](https://github.com/keithrbennett/cov-loupe/blob/main/lib/cov_loupe/tools/coverage_detailed_tool.rb)
+
+The MCP tools available to the model subclass BaseTool and implement their respective tasks.
+
+#### mcp_server.rb creates an instance of the mcp gem's Server class and runs it:
+
+```ruby
+server = ::MCP::Server.new(
+  name:    'cov-loupe',
+  version: CovLoupe::VERSION,
+  tools:   tools
+)
+::MCP::Server::Transports::StdioTransport.new(server).open
+```
+
+
+----
+
+## Questions?
+
+**Demo requests:**
+- Specific MCP tool usage?
+- CLI workflow examples?  
+- Library integration patterns?
+- AI assistant setup?
+
+**Contact:**
+- GitHub issues for bugs/features
+- Ruby community discussions
+
+**Thank you!** 🙏
+
+*Making test coverage accessible to humans and AI alike*