# Use cov-loupe CLI as a fallback when the MCP server is unavailable

[Back to main README](../../index.md)

The `cov-loupe` application provides precise test coverage information for your Ruby application. It reads the `.resultset.json` file generated by SimpleCov and exposes that data through multiple subcommands.

Ideally it is configured as an MCP server so you can call its tools directly. If the MCP server is unavailable or errors prevent tool calls from succeeding, fall back to the CLI.

## Fallback instructions

1. **Detect the failure** – if any MCP tool call fails or the server is unreachable, do not
   retry it or attempt to read `.resultset.json` manually. Switch to CLI mode immediately.

2. **Run CLI commands** using `cov-loupe <subcommand>` (or `bundle exec exe/cov-loupe
   <subcommand>` when running from a local gem checkout). The subcommands mirror the MCP tools:

   | MCP tool | CLI subcommand | Example |
   |---|---|---|
   | `project_coverage` | `list` | `cov-loupe list` |
   | `file_coverage_summary` | `summary <path>` | `cov-loupe summary lib/foo.rb` |
   | `file_coverage_raw` | `raw <path>` | `cov-loupe raw lib/foo.rb` |
   | `file_uncovered_lines` | `uncovered <path>` | `cov-loupe uncovered lib/foo.rb` |
   | `file_coverage_detailed` | `detailed <path>` | `cov-loupe detailed lib/foo.rb` |
   | `project_coverage_totals` | `totals` | `cov-loupe totals` |
   | `project_validate` | `validate <expr>` | `cov-loupe validate 'pct >= 90'` |
   | `version` | `--version` (flag) | `cov-loupe --version` |

3. **Use `--help`** at any point to get up-to-date flag and argument information:
   ```
   cov-loupe --help
   cov-loupe list --help
   ```

4. **Treat CLI output as authoritative** – do not estimate or infer coverage figures from
   source files or test files. All data must come from `cov-loupe` output.

5. **Report the fallback** – briefly note in your response that you used the CLI rather than
   the MCP server, so the user knows which mode was active.
