@sayknow-cli/coding-agent 0.3.1 → 0.3.4

package/src/cli/mcp-cli.ts

@@ -0,0 +1,272 @@
+/**
+ * Direct MCP server registration CLI helpers.
+ *
+ * This surface only writes explicit user-provided server definitions to SKC's
+ * own MCP config. It never imports or inherits live configs from other agents.
+ */
+import { getMCPConfigPath, getProjectDir } from "@sayknow-cli/utils";
+import { getMCPServer, readMCPConfigFile, removeMCPServer, upsertMCPServer } from "../runtime-mcp/config-writer";
+import type { MCPConfigFile, MCPServerConfig } from "../runtime-mcp/types";
+
+export type MCPAction = "add" | "list" | "remove";
+
+export interface MCPCommandArgs {
+	action: MCPAction;
+	name?: string;
+	commandArgs?: string[];
+	flags: {
+		project?: boolean;
+		force?: boolean;
+		json?: boolean;
+		type?: "stdio" | "http" | "sse";
+		command?: string;
+		url?: string;
+		arg?: string[];
+		env?: string[];
+		header?: string[];
+		cwd?: string;
+		timeout?: number;
+	};
+	cwd?: string;
+}
+
+export class MCPArgsError extends Error {}
+
+interface ScopedPath {
+	scope: "user" | "project";
+	path: string;
+}
+
+interface RedactedServerEntry {
+	name: string;
+	config: MCPServerConfig;
+}
+
+const REDACTED = "<redacted>";
+const SENSITIVE_KEY_PATTERN =
+	/(?:token|secret|key|credential|password|passwd|pwd|authorization|auth|bearer|cookie|session)/i;
+
+function resolvePath(args: MCPCommandArgs): ScopedPath {
+	const scope = args.flags.project ? "project" : "user";
+	return { scope, path: getMCPConfigPath(scope, args.cwd ?? getProjectDir()) };
+}
+
+function parsePairs(values: string[] | undefined, label: string): Record<string, string> | undefined {
+	if (!values || values.length === 0) return undefined;
+	const parsed: Record<string, string> = {};
+	for (const value of values) {
+		const index = value.indexOf("=");
+		if (index <= 0) {
+			throw new MCPArgsError(`Invalid ${label}. Use KEY=VALUE.`);
+		}
+		const key = value.slice(0, index).trim();
+		if (!key) {
+			throw new MCPArgsError(`Invalid ${label}. Key cannot be empty.`);
+		}
+		parsed[key] = value.slice(index + 1);
+	}
+	return parsed;
+}
+
+function buildServerConfig(args: MCPCommandArgs): MCPServerConfig {
+	const type = args.flags.type ?? (args.flags.url ? "http" : "stdio");
+	const timeout = args.flags.timeout;
+	const shared = timeout === undefined ? {} : { timeout };
+
+	if (type === "stdio") {
+		const command = args.flags.command ?? args.commandArgs?.[0];
+		if (!command) {
+			throw new MCPArgsError("`skc mcp add` requires --command <cmd> or a positional command for stdio servers.");
+		}
+		const config: MCPServerConfig = {
+			...shared,
+			type: "stdio",
+			command,
+		};
+		const positionalArgs = args.flags.command ? [] : (args.commandArgs ?? []).slice(1);
+		const serverArgs = [...positionalArgs, ...(args.flags.arg ?? [])];
+		if (serverArgs.length > 0) config.args = serverArgs;
+		const env = parsePairs(args.flags.env, "env");
+		if (env) config.env = env;
+		if (args.flags.cwd) config.cwd = args.flags.cwd;
+		return config;
+	}
+
+	const url = args.flags.url ?? args.commandArgs?.[0];
+	if (!url) {
+		throw new MCPArgsError(`\`skc mcp add --type ${type}\` requires --url <url> or a positional URL.`);
+	}
+	const headers = parsePairs(args.flags.header, "header");
+	if (type === "http") {
+		const config: MCPServerConfig = {
+			...shared,
+			type,
+			url,
+		};
+		if (headers) config.headers = headers;
+		return config;
+	}
+	const config: MCPServerConfig = {
+		...shared,
+		type,
+		url,
+	};
+	if (headers) config.headers = headers;
+	return config;
+}
+
+function redactRecord(
+	record: Record<string, string> | undefined,
+	redactAllValues: boolean,
+): Record<string, string> | undefined {
+	if (!record) return undefined;
+	return Object.fromEntries(
+		Object.entries(record).map(([key, value]) => [
+			key,
+			redactAllValues || SENSITIVE_KEY_PATTERN.test(key) ? REDACTED : value,
+		]),
+	);
+}
+
+export function redactMCPServerConfig(config: MCPServerConfig): MCPServerConfig {
+	const redacted = { ...config } as MCPServerConfig;
+	if ("env" in redacted) {
+		const env = redactRecord(redacted.env, true);
+		if (env) redacted.env = env;
+	}
+	if ("headers" in redacted) {
+		const headers = redactRecord(redacted.headers, true);
+		if (headers) redacted.headers = headers;
+	}
+	if (redacted.auth) {
+		redacted.auth = {
+			type: redacted.auth.type,
+			credentialId: redacted.auth.credentialId ? REDACTED : undefined,
+			tokenUrl: redacted.auth.tokenUrl,
+			clientId: redacted.auth.clientId ? REDACTED : undefined,
+			clientSecret: redacted.auth.clientSecret ? REDACTED : undefined,
+		};
+	}
+	if (redacted.oauth) {
+		redacted.oauth = {
+			clientId: redacted.oauth.clientId ? REDACTED : undefined,
+			clientSecret: redacted.oauth.clientSecret ? REDACTED : undefined,
+			redirectUri: redacted.oauth.redirectUri,
+			callbackPort: redacted.oauth.callbackPort,
+			callbackPath: redacted.oauth.callbackPath,
+		};
+	}
+	return redacted;
+}
+
+function collectEntries(config: MCPConfigFile): RedactedServerEntry[] {
+	return Object.entries(config.mcpServers ?? {})
+		.sort(([a], [b]) => a.localeCompare(b))
+		.map(([name, serverConfig]) => ({ name, config: redactMCPServerConfig(serverConfig) }));
+}
+
+function writeJson(value: unknown): void {
+	process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+function renderServerLine(entry: RedactedServerEntry): string {
+	const config = entry.config;
+	if (config.type === "http" || config.type === "sse") {
+		return `${entry.name}\t${config.type}\t${config.url}`;
+	}
+	const args = config.args && config.args.length > 0 ? ` ${config.args.join(" ")}` : "";
+	return `${entry.name}\tstdio\t${config.command}${args}`;
+}
+
+function renderDetails(entry: RedactedServerEntry): string {
+	return `${renderServerLine(entry)}\n${JSON.stringify(entry.config, null, 2)}`;
+}
+
+async function runAdd(args: MCPCommandArgs, scoped: ScopedPath): Promise<void> {
+	if (!args.name) throw new MCPArgsError("`skc mcp add` requires a server name.");
+	const config = buildServerConfig(args);
+	const result = await upsertMCPServer(scoped.path, args.name, config, { force: args.flags.force });
+	const redacted = redactMCPServerConfig(config);
+	if (args.flags.json) {
+		writeJson({
+			action: "add",
+			status: result.status,
+			name: args.name,
+			scope: scoped.scope,
+			path: scoped.path,
+			config: redacted,
+		});
+		return;
+	}
+	if (result.status === "skipped") {
+		process.stdout.write(
+			`MCP server "${args.name}" already exists in ${scoped.scope} config. Pass --force to overwrite.\n`,
+		);
+		return;
+	}
+	process.stdout.write(`MCP server "${args.name}" ${result.status} in ${scoped.scope} config: ${scoped.path}\n`);
+}
+
+async function runList(args: MCPCommandArgs, scoped: ScopedPath): Promise<void> {
+	const config = await readMCPConfigFile(scoped.path);
+	const entries = collectEntries(config);
+	if (args.flags.json) {
+		writeJson({ action: "list", scope: scoped.scope, path: scoped.path, servers: entries });
+		return;
+	}
+	if (entries.length === 0) {
+		process.stdout.write(`No MCP servers registered in ${scoped.scope} config: ${scoped.path}\n`);
+		return;
+	}
+	process.stdout.write(`MCP servers in ${scoped.scope} config: ${scoped.path}\n`);
+	for (const entry of entries) {
+		process.stdout.write(`${renderDetails(entry)}\n`);
+	}
+}
+
+async function runRemove(args: MCPCommandArgs, scoped: ScopedPath): Promise<void> {
+	if (!args.name) throw new MCPArgsError("`skc mcp remove` requires a server name.");
+	const existing = await getMCPServer(scoped.path, args.name);
+	if (!existing) {
+		throw new MCPArgsError(`MCP server "${args.name}" not found in ${scoped.scope} config.`);
+	}
+	await removeMCPServer(scoped.path, args.name);
+	const entry = { name: args.name, config: redactMCPServerConfig(existing) };
+	if (args.flags.json) {
+		writeJson({
+			action: "remove",
+			status: "removed",
+			name: args.name,
+			scope: scoped.scope,
+			path: scoped.path,
+			removed: entry,
+		});
+		return;
+	}
+	process.stdout.write(`Removed MCP server "${args.name}" from ${scoped.scope} config: ${scoped.path}\n`);
+	process.stdout.write(`${renderDetails(entry)}\n`);
+}
+
+export async function runMCPCommand(args: MCPCommandArgs): Promise<void> {
+	const scoped = resolvePath(args);
+	try {
+		switch (args.action) {
+			case "add":
+				await runAdd(args, scoped);
+				return;
+			case "list":
+				await runList(args, scoped);
+				return;
+			case "remove":
+				await runRemove(args, scoped);
+				return;
+		}
+	} catch (error) {
+		if (error instanceof MCPArgsError) {
+			process.stderr.write(`${error.message}\n`);
+			process.exitCode = 2;
+			return;
+		}
+		throw error;
+	}
+}

package/src/cli/plugin-cli.ts

@@ -17,6 +17,7 @@ import {
 	MarketplaceManager,
 } from "../extensibility/plugins/marketplace/index.js";
 import { type ScanReport, scanPluginDir } from "../extensibility/plugins/security-scanner";
+import { installSkcPluginBundle, isSkcPluginBundleSource, readRegistry } from "../extensibility/skc-plugins";
 import { theme } from "../modes/theme/theme";
 
 // =============================================================================
@@ -50,6 +51,8 @@ export interface PluginCommandArgs {
 		disable?: string;
 		set?: string;
 		scope?: "user" | "project";
+		user?: boolean;
+		project?: boolean;
 	};
 }
 
@@ -111,6 +114,10 @@ export function parsePluginArgs(args: string[]): PluginCommandArgs | undefined {
 			result.flags.dryRun = true;
 		} else if (arg === "-l" || arg === "--local") {
 			result.flags.local = true;
+		} else if (arg === "--user") {
+			result.flags.user = true;
+		} else if (arg === "--project") {
+			result.flags.project = true;
 		} else if (arg === "--enable" && i + 1 < args.length) {
 			result.flags.enable = args[++i];
 		} else if (arg === "--disable" && i + 1 < args.length) {
@@ -366,7 +373,14 @@ function printSecurityAdvisory(report: ScanReport): void {
 async function handleInstall(
 	manager: PluginManager,
 	packages: string[],
-	flags: { json?: boolean; force?: boolean; dryRun?: boolean; scope?: "user" | "project" },
+	flags: {
+		json?: boolean;
+		force?: boolean;
+		dryRun?: boolean;
+		scope?: "user" | "project";
+		user?: boolean;
+		project?: boolean;
+	},
 ): Promise<void> {
 	if (packages.length === 0) {
 		console.error(chalk.red(`Usage: ${APP_NAME} plugin install <package[@version]>[features] ...`));
@@ -381,6 +395,32 @@ async function handleInstall(
 	const knownMarketplaces = new Set((await mktMgr.listMarketplaces()).map(m => m.name));
 
 	for (const spec of packages) {
+		// SKC plugin bundle classifier: a source containing sayknow-plugin.json (or a
+		// git/tarball source) routes to the bundle installer BEFORE marketplace/npm.
+		if (await isSkcPluginBundleSource(spec)) {
+			if (flags.user === flags.project) {
+				console.error(
+					chalk.red(`SKC plugin bundle install requires exactly one of --user or --project for "${spec}".`),
+				);
+				process.exit(1);
+			}
+			const scope: "user" | "project" = flags.user ? "user" : "project";
+			try {
+				const res = await installSkcPluginBundle(spec, { scope, cwd: process.cwd(), force: flags.force });
+				if (flags.json) {
+					console.log(JSON.stringify({ name: res.entry.name, status: res.status, scope }, null, 2));
+				} else {
+					console.log(
+						chalk.green(`${theme.status.success} ${res.status} SKC plugin ${res.entry.name} (${scope})`),
+					);
+				}
+			} catch (err) {
+				console.error(chalk.red(`${theme.status.error} Failed to install SKC plugin ${spec}: ${err}`));
+				process.exit(1);
+			}
+			continue;
+		}
+
 		const target = classifyInstallTarget(spec, knownMarketplaces);
 
 		if (target.type === "marketplace") {
@@ -519,13 +559,16 @@ async function handleList(manager: PluginManager, flags: { json?: boolean }): Pr
 	const npmPlugins = await manager.list();
 	const mktMgr = await makeMarketplaceManager();
 	const mktPlugins = await mktMgr.listInstalledPlugins();
+	const cwd = getProjectDir();
+	const [skcUser, skcProject] = await Promise.all([readRegistry("user", cwd), readRegistry("project", cwd)]);
+	const skcBundles = [...skcUser.plugins, ...skcProject.plugins];
 
 	if (flags.json) {
-		console.log(JSON.stringify({ npm: npmPlugins, marketplace: mktPlugins }, null, 2));
+		console.log(JSON.stringify({ npm: npmPlugins, marketplace: mktPlugins, skc: skcBundles }, null, 2));
 		return;
 	}
 
-	if (npmPlugins.length === 0 && mktPlugins.length === 0) {
+	if (npmPlugins.length === 0 && mktPlugins.length === 0 && skcBundles.length === 0) {
 		console.log(chalk.dim("No plugins installed"));
 		console.log(chalk.dim(`\nInstall plugins with: ${APP_NAME} plugin install <package>`));
 		return;
@@ -567,6 +610,26 @@ async function handleList(manager: PluginManager, flags: { json?: boolean }): Pr
 			console.log(`  ${plugin.id} (${version})${scopeLabel}${shadowLabel}`);
 		}
 	}
+
+	if (skcBundles.length > 0) {
+		if (npmPlugins.length > 0 || mktPlugins.length > 0) console.log();
+		console.log(chalk.bold("SKC Plugin Bundles:\n"));
+		for (const plugin of skcBundles) {
+			const status = plugin.enabled ? chalk.green(theme.status.enabled) : chalk.dim(theme.status.disabled);
+			const scopeLabel = chalk.dim(` (${plugin.scope})`);
+			const disabledCount = plugin.disabledSurfaceIds.length;
+			const quarantineCount = plugin.quarantine?.length ?? 0;
+			const detail = [
+				disabledCount > 0 ? `${disabledCount} disabled` : null,
+				quarantineCount > 0 ? `${quarantineCount} quarantined` : null,
+			]
+				.filter((v): v is string => Boolean(v))
+				.join(", ");
+			console.log(
+				`${status} ${plugin.name}@${plugin.version}${scopeLabel}${detail ? chalk.dim(` — ${detail}`) : ""}`,
+			);
+		}
+	}
 }
 
 async function handleLink(manager: PluginManager, paths: string[], flags: { json?: boolean }): Promise<void> {

package/src/cli/web-search-cli.ts

@@ -15,6 +15,7 @@ import {
 	type SearchQueryParams,
 } from "../web/search/index";
 import { SEARCH_PROVIDER_ORDER, setPreferredSearchProvider, setSearchFallbackProviders } from "../web/search/provider";
+import { setSearchHardTimeoutMs } from "../web/search/providers/utils";
 import { renderSearchResult } from "../web/search/render";
 import type { SearchProviderId } from "../web/search/types";
 
@@ -179,6 +180,10 @@ export async function runSearchCommand(cmd: SearchCommandArgs): Promise<void> {
 			configuredFallback.filter(value => typeof value === "string" && isConfigurableSearchProviderId(value)),
 		);
 	}
+	const configuredTimeout = settings.get("web_search.timeout");
+	if (typeof configuredTimeout === "number" && Number.isFinite(configuredTimeout) && configuredTimeout > 0) {
+		setSearchHardTimeoutMs(configuredTimeout * 1000);
+	}
 
 	const params: SearchQueryParams = {
 		query: cmd.query,

package/src/cli.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 
 /**
- * CLI entry point — registers all commands explicitly and delegates to the
+ * CLI entry point — registers all commands explicitly and delegates to the
  * lightweight CLI runner from pi-utils.
  */
 import { Args, type CliConfig, Command, type CommandEntry, Flags, run } from "@sayknow-cli/utils/cli";
@@ -22,7 +22,7 @@ process.title = APP_NAME;
 const rootHelpFlags = ["--help", "-h", "help"];
 const versionFlags = ["--version", "-v"];
 
-const commands: CommandEntry[] = [
+export const commands: CommandEntry[] = [
 	{ name: "codex-native-hook", load: () => import("./commands/codex-native-hook").then(m => m.default) },
 	{ name: "state", load: () => import("./commands/state").then(m => m.default) },
 	{ name: "setup", load: () => import("./commands/setup").then(m => m.default) },
@@ -39,6 +39,7 @@ const commands: CommandEntry[] = [
 	{ name: "daemon", load: () => import("./commands/daemon").then(m => m.default) },
 	{ name: "web-search", aliases: ["q"], load: () => import("./commands/web-search").then(m => m.default) },
 	{ name: "mcp-serve", load: () => import("./commands/mcp-serve").then(m => m.default) },
+	{ name: "mcp", load: () => import("./commands/mcp").then(m => m.default) },
 	{
 		name: "contribute-pr",
 		aliases: ["contribution-prep"],
@@ -48,6 +49,7 @@ const commands: CommandEntry[] = [
 	{ name: "migrate", load: () => import("./commands/migrate").then(m => m.default) },
 	{ name: "rlm", load: () => import("./commands/rlm").then(m => m.default) },
 	{ name: "update", load: () => import("./commands/update").then(m => m.default) },
+	{ name: "plugin", load: () => import("./commands/plugin").then(m => m.default) },
 	{ name: "launch", load: () => import("./commands/launch").then(m => m.default) },
 ];
 
@@ -62,10 +64,7 @@ async function showHelp(config: CliConfig): Promise<void> {
 }
 
 async function installRuntimeGlobals(): Promise<void> {
-	const [{ installH2Fetch }, { procmgr }] = await Promise.all([
-		import("@sayknow-cli/ai"),
-		import("@sayknow-cli/utils"),
-	]);
+	const { installH2Fetch } = await import("@sayknow-cli/ai/utils/h2-fetch");
 	// Activate HTTP/2 for all `fetch()` calls (provider streams, OAuth, model
 	// discovery, web tools). Bun's HTTP/2 client is gated on a startup flag we
 	// can't toggle from JS, so we patch globalThis.fetch to pass
@@ -75,8 +74,25 @@ async function installRuntimeGlobals(): Promise<void> {
 
 	// Strip macOS malloc-stack-logging env vars before any subprocess is spawned.
 	// Otherwise every child bun process (subagents, plugin installs, ptree spawns,
-	// etc.) prints a `MallocStackLogging: can't turn off …` warning to stderr.
-	procmgr.scrubProcessEnv();
+	// etc.) prints a `MallocStackLogging: can't turn off …` warning to stderr.
+	delete process.env.MallocStackLogging;
+	delete process.env.MallocStackLoggingNoCompact;
+}
+
+function hasRootFastFlag(argv: string[], flags: readonly string[]): boolean {
+	for (const arg of argv) {
+		if (isSubcommand(arg)) return false;
+		if (flags.includes(arg)) return true;
+	}
+	return false;
+}
+
+function hasRootHelpFlag(argv: string[]): boolean {
+	return hasRootFastFlag(argv, rootHelpFlags);
+}
+
+function hasRootVersionFlag(argv: string[]): boolean {
+	return hasRootFastFlag(argv, versionFlags);
 }
 
 class RootHelpCommand extends Command {
@@ -165,7 +181,7 @@ function isSubcommand(first: string | undefined): boolean {
  *
  * Purpose: catch the silent worker-load regressions that hit compiled
  * binaries (issues #1011 and #1027). Neither `--version` nor
- * `stats --summary` actually spawns a Worker on a fresh install — the
+ * `stats --summary` actually spawns a Worker on a fresh install — the
  * sync path early-returns when no session files exist. This probe is the
  * minimal end-to-end test that proves `new Worker(...)` resolves and the
  * bundled worker module evaluates successfully. Wired into
@@ -196,7 +212,7 @@ export async function runCli(argv: string[]): Promise<void> {
 		await runSmokeTest();
 		return;
 	}
-	if (rootHelpFlags.includes(argv[0] ?? "")) {
+	if (hasRootHelpFlag(argv)) {
 		const { renderRootHelp } = await import("@sayknow-cli/utils/cli");
 		const { getExtraHelpText } = await import("./cli/fast-help");
 		renderRootHelp({ bin: APP_NAME, version: VERSION, commands: new Map([["launch", RootHelpCommand]]) });
@@ -206,7 +222,7 @@ export async function runCli(argv: string[]): Promise<void> {
 		}
 		return;
 	}
-	if (versionFlags.includes(argv[0] ?? "")) {
+	if (hasRootVersionFlag(argv)) {
 		process.stdout.write(`${APP_NAME}/${VERSION}\n`);
 		return;
 	}
@@ -223,4 +239,6 @@ export async function runCli(argv: string[]): Promise<void> {
 	return run({ bin: APP_NAME, version: VERSION, argv: runArgv, commands, help: showHelp });
 }
 
-await runCli(process.argv.slice(2));
+if (import.meta.main) {
+	await runCli(process.argv.slice(2));
+}

package/src/commands/mcp.ts

@@ -0,0 +1,117 @@
+/**
+ * Direct MCP server registration for standalone SKC.
+ */
+import { Args, Command, Flags } from "@sayknow-cli/utils/cli";
+import { type MCPAction, type MCPCommandArgs, runMCPCommand } from "../cli/mcp-cli";
+
+const ACTIONS: MCPAction[] = ["add", "list", "remove"];
+
+export default class MCP extends Command {
+	static description = "Register standalone MCP servers explicitly in SKC config";
+	static delegateHelp = true;
+
+	static examples = [
+		"skc mcp add context7 npx -y @upstash/context7-mcp",
+		"skc mcp add docs --type http --url https://example.test/mcp --header Authorization=Bearer_TOKEN",
+		"skc mcp list --json",
+		"skc mcp remove context7",
+	];
+
+	static args = {
+		action: Args.string({ description: "MCP action", required: false, options: ACTIONS }),
+		name: Args.string({ description: "Server name", required: false }),
+		commandArgs: Args.string({
+			description: "Command/URL and trailing args for add",
+			required: false,
+			multiple: true,
+		}),
+	};
+
+	static flags = {
+		project: Flags.boolean({ description: "Write/read project scope (./.skc/mcp.json) instead of user scope" }),
+		force: Flags.boolean({ description: "Overwrite an existing server during add", default: false }),
+		json: Flags.boolean({
+			char: "j",
+			description: "Emit machine-readable JSON with sensitive values redacted",
+			default: false,
+		}),
+		type: Flags.string({ description: "Server transport type", options: ["stdio", "http", "sse"] }),
+		command: Flags.string({ description: "Stdio server command for add" }),
+		url: Flags.string({ description: "HTTP/SSE server URL for add" }),
+		arg: Flags.string({ description: "Argument passed to a stdio server (repeatable)", multiple: true }),
+		env: Flags.string({
+			description: "Environment variable for stdio server as KEY=VALUE (repeatable)",
+			multiple: true,
+		}),
+		header: Flags.string({
+			description: "HTTP/SSE header as KEY=VALUE (repeatable; redacted in output)",
+			multiple: true,
+		}),
+		cwd: Flags.string({ description: "Working directory for stdio server" }),
+		timeout: Flags.integer({ description: "Connection timeout in milliseconds" }),
+	};
+
+	async run(): Promise<void> {
+		if (this.argv.includes("--help") || this.argv.includes("-h")) {
+			this.printHelp();
+			return;
+		}
+
+		const { args, flags } = await this.parse(MCP);
+		const action = (args.action ?? "list") as MCPAction;
+		const cmd: MCPCommandArgs = {
+			action,
+			name: args.name,
+			commandArgs: args.commandArgs,
+			flags: {
+				project: flags.project,
+				force: flags.force,
+				json: flags.json,
+				type: flags.type as MCPCommandArgs["flags"]["type"],
+				command: flags.command,
+				url: flags.url,
+				arg: flags.arg,
+				env: flags.env,
+				header: flags.header,
+				cwd: flags.cwd,
+				timeout: flags.timeout,
+			},
+		};
+		await runMCPCommand(cmd);
+	}
+
+	private printHelp(): void {
+		process.stdout.write(`Register standalone MCP servers explicitly in SKC config
+
+USAGE
+  $ skc mcp [add|list|remove] [NAME] [COMMAND_OR_URL] [ARGS...] [FLAGS]
+
+COMMANDS
+  add     Add an explicit user-provided MCP server definition
+  list    List registered servers with env/header/auth values redacted
+  remove  Remove a registered server and print the removed definition redacted
+
+FLAGS
+      --project          Use project scope (./.skc/mcp.json) instead of user scope
+      --force            Overwrite an existing server during add
+  -j, --json             Emit machine-readable JSON with sensitive values redacted
+      --type=<value>     stdio | http | sse (default: stdio, or http when --url is set)
+      --command=<value>  Stdio server command for add
+      --url=<value>      HTTP/SSE server URL for add
+      --arg=<value>      Stdio server argument (repeatable)
+      --env=<value>      Stdio env var as KEY=VALUE (repeatable; redacted in output)
+      --header=<value>   HTTP/SSE header as KEY=VALUE (repeatable; redacted in output)
+      --cwd=<value>      Working directory for stdio server
+      --timeout=<int>    Connection timeout in milliseconds
+
+EXAMPLES
+  $ skc mcp add context7 npx -y @upstash/context7-mcp
+  $ skc mcp add docs --type http --url https://example.test/mcp --header Authorization=Bearer_TOKEN
+  $ skc mcp list --json
+  $ skc mcp remove context7
+
+SECURITY
+  This command writes only the server definition supplied on this invocation. It does not import or inherit Claude Code, Codex, OpenCode, or other live MCP configs. Public output redacts env, header, auth, and OAuth credential values.
+`);
+	}
+}

package/src/commands/plugin.ts

@@ -49,6 +49,8 @@ export default class Plugin extends Command {
 			description: 'Install scope: "user" (default) or "project"',
 			options: ["user", "project"],
 		}),
+		user: Flags.boolean({ description: "Install SKC plugin bundle into the user root" }),
+		project: Flags.boolean({ description: "Install SKC plugin bundle into the project root" }),
 	};
 
 	async run(): Promise<void> {
@@ -69,6 +71,8 @@ export default class Plugin extends Command {
 				disable: flags.disable,
 				set: flags.set,
 				scope: flags.scope as "user" | "project" | undefined,
+				user: flags.user,
+				project: flags.project,
 			},
 		};