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.

Source code is maintained in a separate repository — github.com/dotutils/list-cli-mcp-impl — which is currently private.

See it in action

An agent is asked to fetch data from Azure DevOps. Without a catalog of what's installed, it can't tell that the machine already has the az CLI (with the azure-devops extension) that would answer the question — so it gives up or guesses. With this server in context, the agent discovers az via get_clis, and just runs it.

Without the MCP — doesn't realize az is available	With the MCP — finds and uses the az CLI

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. Beyond the bundled catalog, a miss also consults live package managers (winget on Windows; npm on any platform) so tools outside the curated list still get an install suggestion (source: "online"). On by default; opt out with CLICATALOG_ONLINE_INSTALL_SEARCH=0, and suppressed entirely under execution-policy=never.
• 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."]
}

Example — a miss for a tool outside the bundled catalog, answered by the live winget search (source: "online"):

{
  "results": [{
    "name": "eza", "status": "not-found",
    "install": [{ "manager": "winget", "id": "eza-community.eza", "command": "winget install eza-community.eza" }],
    "source": "online", "confidence": 0.55
  }]
}

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

Planned / not yet implemented

The server is useful today (L1–L3 discovery, lexical + Sampling-based query, install suggestions), but several higher-fidelity features from the design plan are still ahead:

• Bridge to completion-spec databases for high-fidelity capabilities. Instead of scraping --help, pull structured subcommands/flags/descriptions from the existing completion corpora — carapace (carapace <cmd> export, ~1000+ commands, millisecond exports) and bundled Fig / Amazon Q specs (400+ popular CLIs). These are the well-known "tool description" databases that power shell autocompletion, giving accurate L3 data mostly without executing the target.
• Semantic search over the catalog (local embeddings). Layer an optional, offline ONNX embedding retriever (e.g. bge-small / MiniLM) onto the existing FTS5 query mode for a hybrid lexical+semantic match — so intent queries like "container runtime" rank well even without a client model. Off by default.
• Richer provenance resolvers. Map each binary back to its owning package manager (winget / scoop / choco, apt / dnf, brew, command-not-found) — non-executing where possible — to answer "who installed this node?" and to strengthen install suggestions.
• Trust & tamper signals. Per-entry signature/hash verdicts (WinVerifyTrust / codesign / dpkg -V / rpm -V) by default, with opt-in network attestation (Sigstore / SLSA) and an OSV/NVD vulnerability overlay; Elicitation-gated warnings for tampered / untrusted binaries. Includes a learned-spec store that persists inferred capability specs keyed by (path, sha256, version).
• Push-based change detection. Optional FileSystemWatcher invalidation with richer list_changed diffs, beyond the current TTL + on-miss refresh.
• Runtime guard companion (out of scope for v1). A separate shell-hook / PATH-shim component that queries this server's trust oracle before commands run — documented, not built here.

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