modelcontextprotocol/inspector
Watch
1
0
Fork
You've already forked inspector
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2

feat(web): catalog vs read-only session launch model + apply --header (#1481, #1483) (#1496)

Browse source 
* feat(web): catalog vs read-only session launch model + apply --header (#1481, #1483)

Per specification/v2_catalog_launch_config.md, `mcp-inspector --web` now selects
the backend's server-list source and a session-wide writability, instead of
seeding an inert `initialMcpConfig` the UI never read:

- `--catalog <path>` (and `MCP_CATALOG_PATH`) → active WRITABLE catalog
  (seed/CRUD/watch), like the default catalog.
- `--config <path>` → READ-ONLY session file: served in the UI but never
  written, seeded, or plaintext-secret-migrated — safe to point at a foreign
  config (e.g. claude_desktop_config.json).
- ad-hoc `--server-url`/command (+ `--header`) → one server held IN MEMORY
  (no file written); `--header` is lifted onto the entry so the seeded
  connection actually uses it (closes the #1483 warn-only no-op).
- nothing → default catalog (writable), unchanged.

Backend (`createRemoteApp`): new `writable` + `initialServers` options. GET
/api/servers branches three ways (in-memory / read-only file with no
seed+no migrate / writable catalog); the four mutating routes return 403 when
read-only; `/api/config` carries `writable`; the file watcher is skipped for
in-memory sessions. `--catalog`/`--config` are mutually exclusive and neither
combines with an ad-hoc target or `--header`; `--header` requires an ad-hoc
HTTP/SSE server (clear errors otherwise — no silent no-op).

UI: `useServerListWritable` reads `writable` from /api/config; the Servers
screen hides add/edit/clone/remove/reorder/settings and shows a read-only
banner when false. All new props default to writable=true (back-compatible).

Docs: spec gaps G2/G3/G4 updated; launcher README documents the flags.

Verified end-to-end against the built launcher: --config (writable:false,
file byte-stable, mutations 403), ad-hoc --header (in-memory, header lifted),
and --catalog (writable:true, POST persists).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* refactor(web): address review — Mantine <Code> in read-only banner, clarify watcher comment

- Replace raw <code> with Mantine <Code> in the read-only-session Alert
  (repo convention: prefer Mantine primitives over raw HTML).
- Add a comment near `watchable` clarifying that a read-only `--config` file
  is still watched on purpose (read-only blocks UI writes, not external
  observation; `writable` does not gate watching).

Deferred (per reviewer): consolidating useSandboxUrl + useServerListWritable
into one useConfig hook to avoid the duplicate /api/config fetch — optional
follow-up. The redundant ad-hoc header type-guard is kept as defensive.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Cliff Hall 2026-06-16 14:24:58 -04:00 • committed by GitHub
commit 91f02fd6db
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 1281 additions and 157 deletions
Download patch file Download diff file Expand all files Collapse all files

163
clients/web/server/run-web.ts
View file

@ -7,7 +7,11 @@
import { resolve, join, dirname } from "node:path";
import { fileURLToPath } from "node:url";
import { Command } from "commander";
import type { MCPServerConfig } from "../../../core/mcp/types.ts";
import type {
MCPConfig,
MCPServerConfig,
StoredMCPServer,
} from "../../../core/mcp/types.ts";
import {
resolveServerConfigs,
parseKeyValuePair,
@ -31,6 +35,22 @@ function ensureStdioCwd(config: MCPServerConfig): MCPServerConfig {
return config;
}
/**
* Derive a readable catalog id for an ad-hoc server seeded from CLI flags:
* the URL host for HTTP/SSE, or the command basename for stdio. Falls back to
* "server" so the id is always a non-empty `mcpServers` map key.
*/
function deriveSeedServerId(config: MCPServerConfig): string {
if (config.type === "sse" || config.type === "streamable-http") {
try {
return new URL(config.url).host || "server";
} catch {
return "server";
}
}
return config.command?.split(/[\\/]/).pop() || "server";
}
export async function runWeb(argv: string[]): Promise<number> {
const program = new Command();
@ -53,7 +73,8 @@ export async function runWeb(argv: string[]): Promise<number> {
parseKeyValuePair,
{},
)
.option("--config <path>", "config file path")
.option("--catalog <path>", "writable catalog file path")
.option("--config <path>", "read-only session config file path")
.option("--server <name>", "server name from config file")
.option("--transport <type>", "transport type (stdio, sse, http)")
.option("--server-url <url>", "server URL for SSE/HTTP transport")
@ -68,6 +89,7 @@ export async function runWeb(argv: string[]): Promise<number> {
.parse(preArgs);
const opts = program.opts() as {
catalog?: string;
config?: string;
server?: string;
e?: Record<string, string>;
@ -82,50 +104,139 @@ export async function runWeb(argv: string[]): Promise<number> {
const target = [...args, ...postArgs];
const isDev = !!opts.dev;
const hasServerInput =
opts.config ||
// Catalog source for the web backend (spec: v2_catalog_launch_config.md):
// - `--catalog <path>` / MCP_CATALOG_PATH → that file is the active WRITABLE
// catalog (CRUD, seed-if-missing, file-watch) — like the default catalog.
// - `--config <path>` → a READ-ONLY session file: shown in the UI but never
// written, seeded, or migrated (so a foreign config is safe to point at).
// - ad-hoc `--server-url` / command target → a one-server READ-ONLY session
// held in memory (no file written), with `--header` lifted onto the entry
// so the seeded connection actually uses those headers (#1483).
// - nothing → default catalog (writable), backend uses its default path.
// `initialMcpConfig` stays populated for the ad-hoc case only so the legacy
// GET /api/config defaults survive; the catalog path / in-memory list is what
// the UI's server list actually reads.
const catalogPath = opts.catalog ?? process.env.MCP_CATALOG_PATH;
const hasCatalog = !!catalogPath;
const hasConfig = !!opts.config;
const hasHeaders = !!opts.header && Object.keys(opts.header).length > 0;
const hasAdHocServer =
target.length > 0 ||
opts.serverUrl ||
(opts.transport && opts.transport !== "stdio");
!!opts.serverUrl ||
(!!opts.transport && opts.transport !== "stdio");
// Reject illegal flag combinations up front so each branch below is clean.
const conflict =
hasCatalog && hasConfig
? "--catalog and --config are mutually exclusive. --catalog is the writable catalog; --config is a read-only session file."
: hasCatalog && hasAdHocServer
? "--catalog cannot be combined with an ad-hoc server URL/command."
: hasCatalog && hasHeaders
? "--header cannot be combined with --catalog. Set per-server headers in the catalog file."
: hasConfig && hasAdHocServer
? "--config cannot be combined with an ad-hoc server URL/command. --config selects a read-only session file."
: hasConfig && hasHeaders
? "--header cannot be combined with --config. Set per-server headers inside the config file instead."
: null;
if (conflict) {
console.error(`Error: ${conflict}`);
process.exit(1);
}
let initialMcpConfig: MCPServerConfig | null = null;
let mcpConfigPath: string | undefined;
let writable = true;
let initialServers: MCPConfig | null = null;
if (hasServerInput) {
const serverOptions: ServerConfigOptions = {
configPath: opts.config,
serverName: opts.server,
target: target.length > 0 ? target : undefined,
transport: opts.transport as "stdio" | "sse" | "http" | undefined,
serverUrl: opts.serverUrl,
cwd: opts.cwd,
env: opts.e,
};
if (opts.header && Object.keys(opts.header).length > 0) {
if (hasCatalog) {
if (opts.server) {
console.warn(
"Warning: --header is accepted but initial HTTP headers are configured via server settings in the web UI (post-#1358).",
"Note: --server has no effect on the web UI yet; it lists every server in the catalog.",
);
}
// A writable catalog may not exist yet — the backend seeds it on first
// read, exactly like the default catalog — so we don't pre-validate it.
mcpConfigPath = resolve(process.cwd(), catalogPath!);
writable = true;
} else if (hasConfig) {
if (opts.server) {
console.warn(
"Note: --server has no effect on the web UI yet; it lists every server in the file.",
);
}
const resolvedConfigPath = resolve(process.cwd(), opts.config!);
try {
const configs = resolveServerConfigs(serverOptions, "single");
const config = configs[0];
if (!config) {
// Validate the file loads (and exists) before serving it: a read-only
// session never seeds, so a typo'd path would otherwise show a silently
// empty server list instead of a clear error.
resolveServerConfigs({ configPath: resolvedConfigPath }, "multi");
} catch (err) {
const message =
err instanceof Error ? err.message : "Could not load config file.";
console.error("Error:", message);
process.exit(1);
}
mcpConfigPath = resolvedConfigPath;
writable = false;
} else if (hasAdHocServer) {
let config: MCPServerConfig;
try {
const serverOptions: ServerConfigOptions = {
serverName: opts.server,
target: target.length > 0 ? target : undefined,
transport: opts.transport as "stdio" | "sse" | "http" | undefined,
serverUrl: opts.serverUrl,
cwd: opts.cwd,
env: opts.e,
};
const resolved = resolveServerConfigs(serverOptions, "single")[0];
if (!resolved) {
console.error(
"Error: Could not resolve server config. Use --config and --server, or pass a command/URL.",
"Error: Could not resolve server config. Pass a command/URL, or use --catalog / --config to serve a file.",
);
process.exit(1);
}
initialMcpConfig = ensureStdioCwd(config);
config = ensureStdioCwd(resolved);
} catch (err) {
const message =
err instanceof Error ? err.message : "Could not resolve server config.";
console.error("Error:", message);
process.exit(1);
}
if (hasHeaders && (config.type === "stdio" || config.type === undefined)) {
console.error(
"Error: --header only applies to HTTP/SSE servers; stdio servers take no HTTP headers.",
);
process.exit(1);
}
initialMcpConfig = config;
// In-memory session entry: the SDK config plus the flat `headers` record,
// which the backend lifts into `settings.headers` on read. Nothing is
// written to disk — the ad-hoc server is a read-only session list.
const entry: StoredMCPServer =
hasHeaders && config.type !== "stdio" && config.type !== undefined
? { ...config, headers: opts.header }
: { ...config };
initialServers = {
mcpServers: { [deriveSeedServerId(config)]: entry },
};
writable = false;
} else if (hasHeaders) {
console.error(
"Error: --header requires an ad-hoc --server-url or command target.",
);
process.exit(1);
}
const webConfig = buildWebServerConfig({ initialMcpConfig });
const webConfig = buildWebServerConfig({
initialMcpConfig,
mcpConfigPath,
writable,
initialServers,
});
if (!isDev) {
webConfig.staticRoot = join(__dirname, "..", "dist");
}