cli

This MCP server exposes a lightweight CLI resource model where each cli resource represents an individual command entry with a name, a help subtree, and a text/plain representation. The server provides three tools: add, help, and run. The add tool recursively parses a CLI help menu subtree and stores its command definition in server state, updating clients about resource changes. The help tool returns the subtree definitions for available commands, and the run tool executes a known command using the previously stored definition. To begin, you must first add a command using the add tool, which seeds the server with a representation of a CLI command. Once added, you can query the structure with help to understand available subcommands and then invoke run to execute a known command with optional arguments.

Typical workflow:

• Use add to ingest a CLI command by providing its name and help menu structure as defined by the server’s CLI parsing logic. This builds the internal resource tree and makes the command runnable.
• Use help to inspect the available command subtree definitions and their metadata (names, help text, mimetypes).
• Use run to execute a known command by referencing its stored definition, along with any necessary cmd_args. The server will run the command and surface output back to the client.

If you’re debugging, consider using the MCP Inspector for a richer debugging experience, which can connect to MCP servers over stdio and display interactive debugging information including the URL to open in a browser.

Prerequisites:

• A runtime environment with the uv tool installed (the CLI bridge used by this MCP server). Ensure uv is accessible in your PATH, or configure the UV_PATH environment variable as needed.
• Access to the repository containing the cli MCP server (this project).

Installation steps:

1. Install uv if it’s not already installed. For macOS via Homebrew:
   • brew install uv
2. Ensure Node.js and npm are optional here since the server runs via uv; if you plan to use the MCP Inspector, have Node.js and npm installed.
3. Clone or download the cli MCP server repository to your local machine.
4. Prepare the configuration snippet for your MCP runner (see mcp_config example below). If you’re on macOS and using Claude Desktop, optionally set the UV_PATH to the exact uv executable path you must invoke.
5. Start the MCP server using the provided mcp_config snippet in your MCP runner. For example, if your runner reads the JSON config, feed it the snippet with the path-to-repo placeholder replaced by your actual path.
6. Open the MCP Inspector (optional) to connect to the server for debugging: run the command shown in the inspector launch instructions (usually something like npx @modelcontextprotocol/inspector uv --directory <path to repo> run cli).

Note: By design, you must explicitly add a command with the add tool before it can be run using the run tool.

Tips and notes:

• Before invoking run, you must add the command so the server has a stored definition to execute.
• The MCP Inspector is a recommended debugging tool for tracing commands, outputs, and resource changes.
• If you’re on macOS or using Claude Desktop, ensure the uv executable is correctly referenced in your config (you may need to set UV_PATH to /opt/homebrew/bin/uv or equivalent).
• When inspecting help, the server returns the CLI’s subtree definitions, which describe available command names, subcommands, and help text.
• Environment variables can be used to point to the uv executable or configure runtime paths; expose them in your mcp_config as needed.
• The CLI resources are exposed via a simple model: each resource has a name, a help subtree, and a text/plain MIME type for its representation.