simplecov-mcp

MCP server + CLI + Ruby library for inspecting SimpleCov coverage data

A flexible tool for analyzing SimpleCov coverage data with three interfaces:

• 🤖 MCP Server - Integrate coverage queries with AI coding assistants (Claude, Cursor, etc.)
• 💻 CLI - Command-line coverage reports, queries, and analysis
• 💎 Ruby Library - Programmatic API for custom coverage analysis

All without requiring SimpleCov at runtime—just reads the .resultset.json file.

gem install simplecov-mcp

# Run your tests with SimpleCov enabled
bundle exec rspec  # or your test command
# Verify coverage was generated
ls coverage/.resultset.json

CLI - View Coverage Table:

simplecov-mcp

CLI - Check Specific File:

simplecov-mcp summary lib/simplecov_mcp/model.rb
simplecov-mcp uncovered lib/simplecov_mcp/cli.rb

Ruby Library:

require "simplecov_mcp"
model = SimpleCovMcp::CoverageModel.new
files = model.all_files
# => [{ "file" => "lib/simplecov_mcp/model.rb", "covered" => 114, "total" => 118, "percentage" => 96.61, "stale" => false }, ...]
summary = model.summary_for("lib/simplecov_mcp/model.rb")
# => { "file" => "lib/simplecov_mcp/model.rb", "summary" => { "covered" => 114, "total" => 118, "pct" => 96.61 }, "stale" => false }

MCP Server: See MCP Integration Guide for AI assistant setup.

• ✅ Multiple interfaces - MCP server, CLI, and Ruby API
• ✅ Rich output formats - Tables, JSON, annotated source code
• ✅ Staleness detection - Identify outdated coverage for CI/CD
  • M (Missing): File no longer exists
  • T (Timestamp): File modified after coverage was generated
  • L (Length): Line count mismatch between source and coverage
• ✅ No runtime SimpleCov dependency - Just reads .resultset.json
• ✅ Flexible path resolution - Works with absolute or relative paths
• ✅ Comprehensive error handling - Context-aware messages for each mode

📚 Complete Guides:

• Installation - Setup for different environments and version managers
• CLI Usage - Complete command-line reference with examples
• MCP Integration - Configure with AI assistants (Claude, Cursor, Codex)
• Library API - Ruby API documentation and recipes
• Examples - Cookbook of common use cases
• Troubleshooting - Common issues and solutions
• Development - Contributing and development guide
• Error Handling - Error modes and exception handling

CLI (lowest coverage first): simplecov-mcp

Ruby summary:

require "simplecov_mcp"
model = SimpleCovMcp::CoverageModel.new
summary = model.summary_for("lib/simplecov_mcp/model.rb")
# => { "file" => "...", "summary" => { "covered" => 114, "total" => 118, "pct" => 96.61 }, "stale" => false }

More in CLI Usage and Library API.

• Ruby >= 3.2 (required by mcp gem dependency)
• SimpleCov-generated .resultset.json file
• RVM users: export your preferred ruby/gemset before running commands (e.g. rvm use 3.4.5@simplecov-mcp).

Codex’s macOS sandbox disallows running /bin/ps. RVM depends on ps to bootstrap its environment, so bundle exec rspec fails in that sandbox because the shell falls back to the system Ruby 2.6. There isn’t a repo-side fix—use a Ruby version manager that doesn’t rely on ps, or run the suite outside that environment. (Codex on Ubuntu, Gemini, and Claude Code aren’t affected.)

simplecov-mcp needs to locate the .resultset.json file generated by SimpleCov. You can configure this in several ways, which are checked in the following order of precedence:

1. Command-Line Option (--resultset)

This is the most direct way to specify the location. It overrides all other settings.

# Exact path to the file
simplecov-mcp --resultset /path/to/your/coverage/.resultset.json
# Path to the directory containing the file
simplecov-mcp --resultset /path/to/your/coverage

2. Environment Variable (SIMPLECOV_MCP_OPTS)

You can set default options in an environment variable. This is useful for setting a project-wide default without having to type it every time.

export SIMPLECOV_MCP_OPTS="--resultset /path/to/your/coverage"

Command-line options will always override the environment variable.

3. Default Search Paths

If no path is provided via the command line or environment variables, simplecov-mcp will search for .resultset.json in the following common locations, relative to the project root:

1. .resultset.json
2. coverage/.resultset.json
3. tmp/.resultset.json

4. MCP Server Configuration

When running as an MCP server, you can configure the resultset path in your client's configuration file.

{
  "mcpServers": {
    "simplecov-mcp": {
      "command": "/path/to/simplecov-mcp",
      "args": ["--resultset", "/path/to/your/coverage"]
    }
  }
}

For more details on MCP configuration, see the MCP Integration Guide.

# Files with worst coverage
simplecov-mcp list --sort-order d # display table in descending order, worst will be at end of output
simplecov-mcp list -o d           # same as above, short form option
simplecov-mcp list | less         # display table in pager, worst files first
simplecov-mcp list | head -10     # truncate the table
# Specific directory
simplecov-mcp list --tracked-globs "lib/simplecov_mcp/tools/**/*.rb"
# Export for analysis
simplecov-mcp list --json > coverage-report.json

# Fail build if coverage is stale
simplecov-mcp --stale error || exit 1
# Generate coverage report artifact
simplecov-mcp list --json > artifacts/coverage.json

# Quick summary
simplecov-mcp summary lib/simplecov_mcp/model.rb
# See uncovered lines
simplecov-mcp uncovered lib/simplecov_mcp/cli.rb
# View in context
simplecov-mcp uncovered lib/simplecov_mcp/cli.rb --source=uncovered --source-context 3
# Detailed hit counts
simplecov-mcp detailed lib/simplecov_mcp/util.rb

• list - Show all files with coverage (default)
• summary <path> - Coverage summary for a file
• raw <path> - Raw SimpleCov lines array
• uncovered <path> - List uncovered line numbers
• detailed <path> - Per-line coverage with hit counts
• version - Show version information

Run simplecov-mcp --help for complete options.

When running as an MCP server, these tools are exposed:

• coverage_summary_tool - File coverage summary
• coverage_detailed_tool - Per-line coverage
• coverage_raw_tool - Raw SimpleCov array
• uncovered_lines_tool - Uncovered line numbers
• all_files_coverage_tool - Project-wide coverage
• coverage_table_tool - Formatted table
• help_tool - Tool discovery and guidance
• version_tool - Version information

See MCP Integration Guide for details.

• "command not found" - See Installation Guide
• "cannot load such file -- mcp" - Upgrade to Ruby >= 3.2
• "Could not find .resultset.json" - Run tests to generate coverage. See the Configuring the Resultset section for more details.
• MCP server won't connect - Check PATH and Ruby version in MCP Troubleshooting

For more detailed help, see the full Troubleshooting Guide.

# Clone and setup
git clone https://github.com/keithrbennett/simplecov-mcp.git
cd simplecov-mcp
bundle install
# Run tests
bundle exec rspec
# Test locally
ruby -Ilib exe/simplecov-mcp
# Build and install
gem build simplecov-mcp.gemspec
gem install simplecov-mcp-*.gem

See docs/DEVELOPMENT.md for more (coming soon).

This gem does not depend on SimpleCov at runtime. It only reads the .resultset.json file that SimpleCov generates. As long as that file exists, simplecov-mcp can analyze it without requiring SimpleCov in your runtime environment.

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass (bundle exec rspec)
5. Submit a pull request

MIT License - see LICENSE file for details.

• GitHub: https://github.com/keithrbennett/simplecov-mcp
• RubyGems: https://rubygems.org/gems/simplecov-mcp
• Issues: https://github.com/keithrbennett/simplecov-mcp/issues
• Changelog: RELEASE_NOTES.md

• CLAUDE.md - Claude Code integration notes
• AGENTS.md - AI agent configuration
• GEMINI.md - Gemini-specific guidance

Made with ❤️ for better Ruby test coverage analysis