CliCatalog.Mcp

CLI Catalog MCP Server

An MCP server that catalogs the command-line tools available on the current machine — what exists, where it lives, which copy actually runs, its version/identity, and (on demand) what it can do — and, when a tool is missing, how to install it.

It exposes a single, self-describing tool, get_clis, designed to be cheap enough to keep in an agent's context on every turn.

What it's good for

• Stop guessing whether a CLI exists. Before an agent runs rg, docker, gh, jq, kubectl, … it can check availability instantly instead of failing on a missing command.
• Explain shadowing. When the same command lives in several PATH directories, it reports the winner and the shadowed copies — the answer to "why am I getting the wrong python?".
• Capability discovery. Ask by intent ("json diff", "container runtime") and get a ranked shortlist. When the client supports MCP Sampling, results are ranked semantically by the client's model.
• Install suggestions. A miss returns typo corrections ("did you mean rg?") and per-manager install commands (winget / scoop / brew / apt) — as advisory text only.
• Onboarding / environment diagnostics. A fast, structured inventory of a dev box, CI runner, or container.

How it works

Discovery is tiered so callers pay only for the depth they need:

Safe by default: L1 never executes anything; L2 prefers non-executing sources (Windows PE version resource, file metadata); L3 execution is opt-in, time-boxed, and sandboxed-in-intent (closed stdin, disabled pager, hard timeout, output cap). The server never installs or modifies anything.

Requirements

• .NET 10 SDK (pinned via global.json).

Build & run

dotnet build list-cli-mcp.slnx -c Release
dotnet run --project src/CliCatalog.Mcp        # starts the stdio server (waits for an MCP client)

Run as a .NET tool (dnx / global install)

The host is published to NuGet.org as a .NET tool (command name cli-catalog-mcp, package id CliCatalog.Mcp), so it can be run without a persistent install via dnx (the .NET 10 one-off tool runner, similar to npx). It is downloaded and cached on first use:

dnx CliCatalog.Mcp --yes           # latest published version
dnx [email protected] --yes     # or pin a specific version

Or install it once and get a cli-catalog-mcp command on your PATH:

dotnet tool install -g CliCatalog.Mcp             # from NuGet.org
cli-catalog-mcp                                    # starts the stdio server

Use it from an MCP client (e.g. VS Code / Copilot)

Point your client at the server over stdio. The smallest config uses dnx, which downloads and runs the published package on demand — no install step. --yes skips the download confirmation prompt (required because the client runs the server non-interactively):

// .vscode/mcp.json
{
  "servers": {
    "cli-catalog": {
      "type": "stdio",
      "command": "dnx",
      "args": ["CliCatalog.Mcp", "--yes"]
    }
  }
}

If you installed it globally (dotnet tool install -g CliCatalog.Mcp), point at the command directly:

{
  "servers": {
    "cli-catalog": {
      "type": "stdio",
      "command": "cli-catalog-mcp"
    }
  }
}

For local development against a source checkout, run it via dotnet run:

{
  "servers": {
    "cli-catalog": {
      "type": "stdio",
      "command": "dotnet",
      "args": ["run", "--project", "src/CliCatalog.Mcp", "-c", "Release"]
    }
  }
}

The get_clis tool

All parameters are optional; the mode is chosen by which you pass:

Behavior by input:

• no arguments → list installed commands (paginated).
• name → resolve the winner + full shadowing chain + details at depth; a miss returns did-you-mean + install options.
• query → ranked shortlist (semantic when Sampling is available, otherwise lexical full-text).

Example — a miss with correction + install options:

{
  "results": [{
    "name": "ripgrepp", "status": "not-found",
    "didYouMean": [{ "name": "rg", "package": "ripgrep", "distance": 1 }],
    "install": [{ "manager": "winget", "id": "BurntSushi.ripgrep.MSVC", "command": "winget install BurntSushi.ripgrep.MSVC" }]
  }],
  "hints": ["Pass scope=installable to search tools you could install."]
}

Results are structured JSON only, and every capability/identity field is tagged with its source (and confidence where applicable) so agents know how a value was derived.

Configuration (environment variables)

Operator-facing, read at startup:

Project layout

src/CliCatalog.Core   # scanning, cache (SQLite + FTS5), change detection, enrichment, sampling — no MCP dep
src/CliCatalog.Mcp    # stdio host: the get_clis tool, resources, list_changed notifier
tests/                # unit, exec-hazard/security, and stdio end-to-end tests
docs/                 # design & implementation plan

See docs/design-and-implementation-plan.md for the full design, rationale, and roadmap.