Major docs refactor (updated all README files, cleanup up some design docs)

Author: BobDickinson

AGENTS.md

@@ -8,7 +8,7 @@
 - Build web: `npm run build-web`
 - Development mode: `npm run dev` (use `npm run dev:windows` on Windows)
 - Format code: `npm run prettier-fix`
-- Web lint: `cd web && npm run lint`
+- Web lint: `cd clients/web && npm run lint`
 
 ## Code Style Guidelines
 
@@ -25,6 +25,17 @@
 - Use Tailwind CSS for styling in the web app
 - Keep components small and focused on a single responsibility
 
+## Tool Input Parameter Handling
+
+When implementing or modifying tool input parameter handling in the Inspector:
+
+- **Omit optional fields with empty values** - When processing form inputs, omit empty strings or null values for optional parameters, UNLESS the field has an explicit default value in the schema that matches the current value
+- **Preserve explicit default values** - If a field schema contains an explicit default (e.g., `default: null`), and the current value matches that default, include it in the request. This is a meaningful value the tool expects
+- **Always include required fields** - Preserve required field values even when empty, allowing the MCP server to validate and return appropriate error messages
+- **Defer deep validation to the server** - Implement basic field presence checking in the Inspector client, but rely on the MCP server for parameter validation according to its schema
+
+These guidelines maintain clean parameter passing and proper separation of concerns between the Inspector client and MCP servers.
+
 ## Project Organization
 
 The project is organized as a monorepo with workspaces:

README.md

@@ -0,0 +1,107 @@
+# MCP Inspector CLI Client
+
+The CLI mode enables programmatic interaction with MCP servers from the command line. It is ideal for scripting, automation, continuous integration, and establishing an efficient feedback loop with AI coding assistants.
+
+## Running the CLI
+
+You can run the CLI client directly via `npx`:
+
+```bash
+npx @modelcontextprotocol/inspector --cli node build/index.js
+```
+
+The CLI mode supports operations across tools, resources, and prompts, returning structured JSON output.
+
+### Examples
+
+**Basic usage**
+
+```bash
+npx @modelcontextprotocol/inspector --cli node build/index.js
+```
+
+**With a configuration file**
+
+```bash
+npx @modelcontextprotocol/inspector --cli --config path/to/config.json --server myserver
+```
+
+**List available tools**
+
+```bash
+npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list
+```
+
+**Call a specific tool**
+
+```bash
+npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/call --tool-name mytool --tool-arg key=value --tool-arg another=value2
+```
+
+**Call a tool with JSON arguments**
+
+```bash
+npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/call --tool-name mytool --tool-arg 'options={"format": "json", "max_tokens": 100}'
+```
+
+**List available resources**
+
+```bash
+npx @modelcontextprotocol/inspector --cli node build/index.js --method resources/list
+```
+
+**List available prompts**
+
+```bash
+npx @modelcontextprotocol/inspector --cli node build/index.js --method prompts/list
+```
+
+### Remote Servers
+
+You can also connect to remote MCP servers using HTTP or SSE transports.
+
+**Connect to a remote MCP server (default is SSE)**
+
+```bash
+npx @modelcontextprotocol/inspector --cli https://my-mcp-server.example.com
+```
+
+**Connect with Streamable HTTP transport**
+
+```bash
+npx @modelcontextprotocol/inspector --cli https://my-mcp-server.example.com --transport http --method tools/list
+```
+
+**Pass custom headers**
+
+```bash
+npx @modelcontextprotocol/inspector --cli https://my-mcp-server.example.com --transport http --method tools/list --header "X-API-Key: your-api-key"
+```
+
+## Options
+
+### MCP server (which server to connect to)
+
+Options that specify the MCP server (config file, ad-hoc command/URL, env vars, headers) are shared by the Web, CLI, and TUI and are documented in [MCP server configuration](../../docs/mcp-server-configuration.md): `--config`, `--server`, `-e`, `--cwd`, `--header`, `--transport`, `--server-url`, and the positional `[target...]`.
+
+### CLI-specific (what to invoke)
+
+| Option                        | Description                                                                               |
+| ----------------------------- | ----------------------------------------------------------------------------------------- |
+| `--method <method>`           | MCP method to invoke (e.g. `tools/list`, `tools/call`, `resources/list`, `prompts/list`). |
+| `--tool-name <name>`          | Tool name (for `tools/call`).                                                             |
+| `--tool-arg <key=value>`      | Tool argument; repeat for multiple. Use `key='{"json":true}'` for JSON.                   |
+| `--uri <uri>`                 | Resource URI (for `resources/read`).                                                      |
+| `--prompt-name <name>`        | Prompt name (for `prompts/get`).                                                          |
+| `--prompt-args <key=value>`   | Prompt arguments; repeat for multiple.                                                    |
+| `--log-level <level>`         | Logging level for `logging/setLevel` (e.g. `debug`, `info`).                              |
+| `--metadata <key=value>`      | General metadata (key=value); applied to all methods.                                     |
+| `--tool-metadata <key=value>` | Tool-specific metadata for `tools/call`.                                                  |
+
+## Why use the CLI?
+
+While the Web Client provides a rich visual interface, the CLI is designed for:
+
+- **Automation**: Ideal for CI/CD pipelines and batch processing.
+- **AI Coding Assistants**: Provides a direct, machine-readable interface (JSON) for tools like Cursor or Claude to verify changes immediately.
+- **Log Analysis**: Easier integration with command-line utilities (like `jq`) to process and analyze MCP server output.

clients/cli/README.md

@@ -0,0 +1,15 @@
+# MCP Inspector Launcher
+
+The launcher is the package that provides the global `mcp-inspector` binary (e.g. when users run `npx @modelcontextprotocol/inspector`). It is not a separate user-facing app—it is the single entrypoint that selects and runs one of the clients (web, CLI, or TUI).
+
+## Responsibility
+
+- Parse the mode flag: `--web` (default), `--cli`, or `--tui`.
+- Forward the rest of `process.argv` to the chosen app.
+- Dynamically import that app’s runner and call it **in-process** (no `spawn()`).
+
+All configuration parsing, config-file loading, and server setup are handled by the app runners and by **core**; the launcher does not interpret config or env vars.
+
+## Architecture
+
+For how the launcher fits with the shared config processor and app runners, see the [Launcher and config consolidation](../../docs/launcher-config-consolidation-plan.md) document in the repo root `docs/` folder.

clients/launcher/README.md

@@ -0,0 +1,55 @@
+# MCP Inspector TUI Client
+
+The Terminal User Interface (TUI) client brings the interactive exploration capabilities of the Web Client directly to your terminal. It is built using [Ink](https://github.com/vadimdemedes/ink) to provide a rich, React-like component experience in a command-line environment.
+
+## Running the TUI
+
+You can run the TUI client via `npx`:
+
+```bash
+npx @modelcontextprotocol/inspector --tui node build/index.js
+```
+
+### With Configuration Files
+
+The TUI can load all servers from an MCP config file:
+
+```bash
+npx @modelcontextprotocol/inspector --tui --config mcp.json
+```
+
+(It does not use `--server`; all servers in the file are available in the TUI.)
+
+## Options
+
+### MCP server (which server(s) to connect to)
+
+Options that specify the MCP server(s) (config file, ad-hoc command/URL, env vars, headers) are shared by the Web, CLI, and TUI and are documented in [MCP server configuration](../../docs/mcp-server-configuration.md): `--config`, `-e`, `--cwd`, `--header`, `--transport`, `--server-url`, and the positional `[target...]`.
+
+### TUI-specific (OAuth for HTTP servers)
+
+When connecting to SSE or Streamable HTTP servers that use OAuth, you can pass:
+
+| Option                        | Description                                                                          |
+| ----------------------------- | ------------------------------------------------------------------------------------ |
+| `--client-id <id>`            | OAuth client ID (static client).                                                     |
+| `--client-secret <secret>`    | OAuth client secret (confidential clients).                                          |
+| `--client-metadata-url <url>` | OAuth Client ID Metadata Document URL (CIMD).                                        |
+| `--callback-url <url>`        | OAuth redirect/callback listener URL (default: `http://127.0.0.1:0/oauth/callback`). |
+
+## Features
+
+The TUI provides terminal-native tabs and panes for interacting with your MCP server:
+
+- **Resources**: Browse and read resources exposed by the server.
+- **Prompts**: List and test prompts.
+- **Tools**: View available tools and execute them with form-like inputs.
+- **History**: View the request and response history of your interactions.
+- **Console**: View the direct stdout/stderr and diagnostic logging of the connected server.
+
+## Navigation
+
+- Use the **Arrow Keys** (Left/Right) or **Tab** to switch between the main tabs (Resources, Tools, Prompts, etc.).
+- Use the **Arrow Keys** (Up/Down) to scroll through lists of items.
+- Press **Enter** to select an item, execute a tool, or fetch a resource.
+- Press **Escape** or `Ctrl+C` to exit the application.