feat: port CLI, TUI, and launcher from v1.5 into v2

.github/workflows/main.yml

@@ -39,6 +39,35 @@ jobs:
         working-directory: ./clients/web
         run: npm run test:coverage
 
+      - name: Install CLI client dependencies
+        working-directory: ./clients/cli
+        run: npm install
+
+      - name: Run CLI tests
+        working-directory: ./clients/cli
+        run: npm run test
+
+      - name: Install TUI client dependencies
+        working-directory: ./clients/tui
+        run: npm install
+
+      - name: Run TUI tests
+        working-directory: ./clients/tui
+        run: npm run test
+
+      - name: Install launcher dependencies
+        working-directory: ./clients/launcher
+        run: npm install
+
+      - name: Build TUI and launcher
+        run: npm run build:tui && npm run build:launcher
+
+      - name: Smoke test launcher
+        run: |
+          node clients/launcher/build/index.js --help
+          node clients/launcher/build/index.js --cli --help
+          node clients/launcher/build/index.js --tui --help
+
       - name: Cache Playwright browsers
         uses: actions/cache@v4
         with:

.gitignore

@@ -3,7 +3,8 @@
 .DS_Store
 .claude/
 node_modules
-dist
+clients/web/dist
+clients/**/build
 test-servers/build
 .env
 /.playwright-mcp/

.npmignore

@@ -0,0 +1,12 @@
+# npm pack uses .npmignore instead of .gitignore when this file exists.
+# Built artifacts are whitelisted via package.json "files".
+
+node_modules
+.env
+.idea
+.vscode
+.DS_Store
+.claude/
+*.log
+coverage
+storybook-static

AGENTS.md

@@ -20,9 +20,9 @@ inspector/
 │   │   │                               #   quiet-config-warnings.mjs (--import hook for `npm run dev`: drops benign
 │   │   │                               #     node-only UNRESOLVED_IMPORT warnings Rolldown prints at config load)
 │   │   └── static/                     # sandbox_proxy.html (served by sandbox-controller for MCP Apps tab)
-│   ├── cli/                            # CLI client
-│   ├── tui/                            # TUI client
-│   ├── launcher/                       # Shared launcher
+│   ├── cli/                            # CLI client (tsup bundle, @inspector/core alias)
+│   ├── tui/                            # TUI client (Ink + React, tsup bundle)
+│   ├── launcher/                       # Shared launcher (relative imports into sibling build/ outputs)
 ├── core/                               # Shared core code (no package.json — consumed via the `@inspector/core` vite alias)
 │   ├── auth/                           # OAuth: state machine, providers, discovery, storage
 │   │   ├── browser/                    # Browser-side OAuth (sessionStorage, BrowserNavigation)
@@ -110,6 +110,9 @@ All work should be driven by items on the project board.
 - Ensure test coverage for each file is at least 90%
 - In unit tests that expect error output, suppress it from the console
 - Run unit tests with `npm run test` (or `npm run test:watch` during development) from `clients/web/`
+- Run CLI tests with `npm run test` from `clients/cli/` (builds test-servers + CLI bin first via `pretest`)
+- Run TUI tests with `npm run test` from `clients/tui/`
+- From repo root, `npm run test` runs web unit tests, then CLI and TUI tests
 - Run `npm run test:coverage` to verify the per-file gate: lines ≥ 90, statements ≥ 85, functions ≥ 80, branches ≥ 50 (CI enforces this gate). Branches is intentionally relaxed because Mantine portal/media-query branches are not exercisable under happy-dom; new business-logic branches should still be covered.
 - Run `npm run test:integration` (also from `clients/web/`) for the v1.5-ported InspectorClient + transport + auth integration suite. It runs under a separate `integration` vitest project in node env (no happy-dom) with 30s timeouts. The script builds `test-servers/` first via `tsc -p ../../test-servers --noCheck` so the stdio MCP test server can be spawned as a real subprocess. CI runs it as its own step after unit tests.
 - Test files live alongside the source as `<Name>.test.tsx` (or `.test.ts` for non-React modules). v1.5-ported integration tests live under `clients/web/src/test/integration/`, mirroring the `core/` source layout (`mcp/`, `mcp/node/`, `mcp/remote/`, `auth/`, `auth/node/`, `storage/`). Any test file under that folder is automatically picked up by the `integration` vitest project (node env, 30s timeouts) via the folder glob in `vite.config.ts` — placement is the manifest, there is no enumeration to keep in sync. Tests outside the folder run in the `unit` project (happy-dom). When adding a new test for, e.g., `core/mcp/remote/foo.ts`, put it at `src/test/integration/mcp/remote/foo.test.ts`.

clients/cli/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/__tests__/README.md

@@ -0,0 +1,44 @@
+# CLI Tests
+
+## Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run in watch mode (useful for test file changes; won't work on CLI source changes without rebuild)
+npm run test:watch
+
+# Run specific test file
+npm run test:cli          # cli.test.ts
+npm run test:cli-tools   # tools.test.ts
+npm run test:cli-headers # headers.test.ts
+npm run test:cli-metadata # metadata.test.ts
+```
+
+## Test Files
+
+- `cli.test.ts` - Basic CLI functionality: CLI mode, environment variables, config files, resources, prompts, logging, transport types
+- `tools.test.ts` - Tool-related tests: Tool discovery, JSON argument parsing, error handling, prompts
+- `headers.test.ts` - Header parsing and validation
+- `metadata.test.ts` - Metadata functionality: General metadata, tool-specific metadata, parsing, merging, validation
+
+## Helpers
+
+The `helpers/` directory contains shared utilities:
+
+- `cli-runner.ts` - Spawns CLI as subprocess and captures output
+- `test-mcp-server.ts` - Standalone stdio MCP server script for stdio transport testing
+- `instrumented-server.ts` - In-process MCP test server for HTTP/SSE transports with request recording
+- `assertions.ts` - Custom assertion helpers for CLI output validation
+- `fixtures.ts` - Test config file generators and temporary directory management
+
+## Notes
+
+- Tests run in parallel across files (Vitest default)
+- Tests within a file run sequentially (we have isolated config files and ports, so we could get more aggressive if desired)
+- Config files use `crypto.randomUUID()` for uniqueness in parallel execution
+- HTTP/SSE servers use dynamic port allocation to avoid conflicts
+- Coverage is not used because much of the code that we want to measure is run by a spawned process, so it can't be tracked by Vitest
+- /sample-config.json is no longer used by tests - not clear if this file serves some other purpose so leaving it for now
+- All tests now use built-in MCP test servers, there are no external dependencies on servers from a registry