kizlo 0.20.1 → 0.21.0

package/dist/cli/commands/_setup.js

@@ -1,7 +1,7 @@
 import { DEFAULT_WORDPRESS_TAG, LOCAL_DIR_REL } from "../wp/constants.js";
 import { composeStop, createStack, dockerHint, dockerStatus } from "../wp/docker.js";
 import { DEFAULT_ENV_KEYS, availablePackageManagers, detectInvokingPackageManager, ensureGitignored, envGroups, envKeysPresent, mergeEnv, pickStackPort, writeFileIfAbsent } from "../utils.js";
-import { DEFAULT_DEV_DB_PORT, DEFAULT_DEV_PORT, resolveStackName, stackProject } from "../daemon/config.js";
+import { DEFAULT_DEV_DB_PORT, DEFAULT_DEV_PORT, DEFAULT_MCP_PORT, resolveStackName, stackProject } from "../daemon/config.js";
 import { promptFragment, resolvePromptDefault } from "../presets/template.js";
 import { createAdminAppPassword } from "../wp/bootstrap.js";
 import { bootstrapDev } from "../wp/dev.js";
@@ -324,6 +324,10 @@ function devConfigFor(cwd) {
 	return {
 		configDir: cwd,
 		project: stackProject(resolveStackName(cwd), "dev"),
+		mcp: {
+			port: DEFAULT_MCP_PORT,
+			portExplicit: false
+		},
 		port: DEFAULT_DEV_PORT,
 		portExplicit: false,
 		dbPort: DEFAULT_DEV_DB_PORT,

package/dist/cli/commands/_wiring.js

@@ -10,7 +10,8 @@ import * as p from "@clack/prompts";
 //#region src/cli/commands/_wiring.ts
 /** The kizlo.config.ts a scaffolded project gets: the Kizlo directory, the import-alias preference, and,
 *  when local WordPress is chosen, `local: true` so `kizlo dev` and `kizlo test` boot the fixed
-*  `.kizlo/local` install (both stacks on with defaults; the object form is for configuring them). The
+*  `.kizlo/local` install (both stacks on with defaults; the object form configures them and turns each
+*  on with its own `enable: true`). The
 *  alias is always written (`""` for relative imports included) so it records a made decision a later
 *  `kizlo init` reads back instead of prompting for it again. The alias is written in its canonical `@/`
 *  form (never a bare `@`) so it reads like the imports it produces. */

package/dist/cli/commands/dev.js

@@ -2,7 +2,7 @@ import { createStack, dockerHint, dockerStatus, stackStatus } from "../wp/docker
 import { findConfigDir } from "../wp/utils.js";
 import { log } from "../daemon/logger.js";
 import { DEFAULT_ENV_KEYS, ensureGitignored, envGroups, groupDefault, mergeEnv, pickStackPort, withSpinner } from "../utils.js";
-import { resolveDevConfig, usesLocalWordPress } from "../daemon/config.js";
+import { resolveDevConfig, resolveMcpConfig, usesLocalWordPress } from "../daemon/config.js";
 import { bootstrapDev } from "../wp/dev.js";
 import { reapOrphans, registerSession, removeProjectContainers, spawnWatchdog, unregisterSession } from "../wp/session.js";
 import { syncSiteSettings } from "../wp/settings.js";
@@ -10,6 +10,8 @@ import { devStack } from "../wp/stack.js";
 import { palette } from "../banner.js";
 import { watchReload } from "../daemon/reload.js";
 import { startWatcher } from "../daemon/watch.js";
+import { createMcpState } from "../mcp/state.js";
+import { resolveMcpPort, startMcp } from "../mcp/index.js";
 import { join } from "node:path";
 import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { defineCommand } from "citty";
@@ -42,14 +44,16 @@ function note(text) {
 * Print the connection summary as an aligned, Next.js-style block. Shows the wp-admin URL on
 * the loopback ("Local") and — when local WordPress is installed on a LAN address rather than
 * localhost — on the network, so it can be opened from other devices. On a fresh install, also
-* show the default wp-admin login.
+* show the default wp-admin login. The MCP row is the address to paste into a harness's own
+* configuration: nothing writes one, because each harness reads a different file.
 */
-function printSummary(info) {
+function printSummary(info, mcpUrl) {
 	const { cyan, dim, reset } = palette();
 	const { port, hostname } = new URL(info.url);
 	const rows = [["WP Local", `http://localhost:${port}/wp-admin`]];
 	if (hostname !== "localhost") rows.push(["WP Network", `${info.url}/wp-admin`]);
 	rows.push(["Database Connection", `127.0.0.1:${info.dbPort}`]);
+	if (mcpUrl) rows.push(["MCP", mcpUrl]);
 	const width = Math.max(...rows.map(([label]) => label.length)) + 1;
 	const lines = ["", ...rows.map(([label, value]) => `   ${dim}- ${`${label}:`.padEnd(width)}${reset} ${cyan}${value}${reset}`)];
 	if (info.adminPassword) lines.push("", `   ${dim}admin login:${reset} ${info.username} / ${info.adminPassword}`);
@@ -180,7 +184,7 @@ function stopping(reason) {
 * and the teardown work against. Shared by the first boot and every reload reboot, so a changed
 * `dev.port` in `kizlo.config.ts` is re-resolved the same way each time.
 */
-async function prepareStack(cfg) {
+async function prepareStack(cfg, mcpPort) {
 	await removeProjectContainers(cfg.project);
 	const port = await pickStackPort(cfg.port, {
 		fixed: cfg.portExplicit,
@@ -194,7 +198,8 @@ async function prepareStack(cfg) {
 	const ready = {
 		...cfg,
 		port,
-		dbPort
+		dbPort,
+		mcpPort: mcpPort ?? await resolveMcpPort(cfg.mcp)
 	};
 	createStack(devStack(ready));
 	if (port !== cfg.port) note(`Port ${cfg.port} is in use — serving on ${port} instead.`);
@@ -207,7 +212,7 @@ async function prepareStack(cfg) {
 * one-time Ctrl+C hint. `start` is when the boot began, so the timing spans the whole reboot including
 * the spinner. The `.env` writes here are why the caller pauses the reload watcher around a reboot.
 */
-async function report(cfg, creds, reloaded, start) {
+async function syncEnv(cfg, creds) {
 	if (creds.appPassword) {
 		const env = updateWpEnv(cfg, creds);
 		note("Updated .env with the new WordPress credentials");
@@ -224,7 +229,16 @@ async function report(cfg, creds, reloaded, start) {
 			if (!sync.ok) note(`Could not sync the site settings to WordPress (${sync.error}) — make sure the kizlo plugin is active, then set them from the Kizlo settings.`);
 		}
 	} else if (syncLocalUrl(cfg.configDir, creds.url)) note("Updated .env WordPress URL to the current network address — restart your app to pick it up");
-	printSummary(creds);
+}
+/**
+* Print the summary and the timed ready line, once everything it names is actually up. Split from
+* {@link syncEnv} because the two have opposite ordering needs: the `.env` writes have to land before
+* the watcher starts, since that is where it reads the connection from, while the summary has to wait
+* until after, so the MCP address it prints belongs to a server that exists. `mcpUrl` is absent when
+* MCP is not running, and the row is then left out rather than pointing at nothing.
+*/
+function printReady(creds, reloaded, start, mcpUrl) {
+	printSummary(creds, mcpUrl);
 	const { green, dim, bold, reset } = palette();
 	const ms = Date.now() - start;
 	const took = ms < 1e3 ? `${ms}ms` : `${(ms / 1e3).toFixed(1)}s`;
@@ -236,9 +250,14 @@ async function report(cfg, creds, reloaded, start) {
 * then report. The first-boot path only — reboots go through {@link rebootStack}, which also folds the
 * prepare step under the spinner.
 */
-async function bootAndReport(cfg) {
+async function bootAndSync(cfg) {
 	const start = Date.now();
-	await report(cfg, await withSpinner("Starting local WordPress", () => bootstrapDev(cfg)), false, start);
+	const creds = await withSpinner("Starting local WordPress", () => bootstrapDev(cfg));
+	await syncEnv(cfg, creds);
+	return {
+		creds,
+		start
+	};
 }
 /**
 * Reboot the whole stack in place after a config/env change: re-resolve the config, recreate the
@@ -247,17 +266,21 @@ async function bootAndReport(cfg) {
 * the first boot, so this never re-arms. Returns the freshly resolved config (ports may have moved) so
 * the caller can re-target its watchers.
 */
-async function rebootStack(cwd, label) {
+async function rebootStack(cwd, label, mcpPort) {
 	const start = Date.now();
 	const { ready, creds } = await withSpinner(label, async () => {
-		const ready$1 = await prepareStack(await resolveDevConfig(cwd));
+		const ready$1 = await prepareStack(await resolveDevConfig(cwd), mcpPort);
 		return {
 			ready: ready$1,
 			creds: await bootstrapDev(ready$1)
 		};
 	});
-	await report(ready, creds, true, start);
-	return ready;
+	await syncEnv(ready, creds);
+	return {
+		ready,
+		creds,
+		start
+	};
 }
 /**
 * Boot local WordPress and run in the foreground until exit — the path behind bare `kizlo dev`. Arms
@@ -273,20 +296,33 @@ async function startForeground(cfg) {
 	const cwd = process.cwd();
 	let ready = await prepareStack(cfg);
 	const shutdown = await armForegroundTeardown(ready);
-	await bootAndReport(ready);
+	const { creds, start } = await bootAndSync(ready);
 	const stack = {
 		status: () => stackStatus(ready.project),
 		onStopped: () => shutdown()
 	};
-	let stopContract = await startWatcher(ready.configDir, { stack });
+	const mcp = createMcpState();
+	const mcpPort = ready.mcpPort;
+	let stopContract = await startWatcher(ready.configDir, {
+		stack,
+		mcp
+	});
+	const mcpServer = stopContract && mcpPort !== void 0 ? await startMcp(mcp, mcpPort) : void 0;
+	if (!stopContract) log.info("Another `kizlo dev` is serving MCP for this project.");
+	printReady(creds, false, start, mcpServer?.url);
 	let reloading = false;
 	const reload = async (changed) => {
 		if (reloading) return;
 		reloading = true;
 		try {
 			stopContract?.();
-			ready = await rebootStack(cwd, `${changed} changed — restarting the session`);
-			stopContract = await startWatcher(ready.configDir, { stack });
+			const rebooted = await rebootStack(cwd, `${changed} changed — restarting the session`, mcpPort);
+			ready = rebooted.ready;
+			stopContract = await startWatcher(ready.configDir, {
+				stack,
+				mcp
+			});
+			printReady(rebooted.creds, true, rebooted.start, mcpServer?.url);
 		} catch (error) {
 			log.error("Failed to reload the dev session:", error);
 		} finally {
@@ -299,6 +335,7 @@ async function startForeground(cfg) {
 	process.on("exit", () => {
 		stopContract?.();
 		stopReload();
+		mcpServer?.stop();
 	});
 	setInterval(() => {}, 1 << 30);
 	await new Promise(() => {});
@@ -312,15 +349,20 @@ async function startForeground(cfg) {
 * persistent watcher keeps the process alive on its own.
 */
 async function watchOnly(cwd) {
-	let stop = await startWatcher(cwd);
-	if (!stop) return;
+	const mcp = createMcpState();
+	let stop = await startWatcher(cwd, { mcp });
+	if (!stop) {
+		log.info("Another `kizlo dev` is serving MCP for this project.");
+		return;
+	}
+	const mcpServer = await startMcp(mcp, await resolveMcpPort(await resolveMcpConfig(cwd)));
 	let reloading = false;
 	const reload = async () => {
 		if (reloading) return;
 		reloading = true;
 		try {
 			stop?.();
-			stop = await startWatcher(cwd);
+			stop = await startWatcher(cwd, { mcp });
 		} finally {
 			setTimeout(() => {
 				reloading = false;
@@ -331,6 +373,7 @@ async function watchOnly(cwd) {
 	const shutdown = () => {
 		stop?.();
 		stopReload();
+		mcpServer?.stop();
 	};
 	process.on("exit", shutdown);
 	for (const signal of [

package/dist/cli/commands/generate.js

@@ -1,5 +1,5 @@
 import { log } from "../daemon/logger.js";
-import { resolveConfig } from "../daemon/config.js";
+import { resolveConfig, resolveWatchCredentials } from "../daemon/config.js";
 import { PartialContractError, generateOnce, reportGenerationError } from "../daemon/generate.js";
 import { testWordPressCredentials } from "./_test-wordpress.js";
 import path from "node:path";
@@ -38,18 +38,31 @@ const generate = defineCommand({
 	async run({ args }) {
 		const cwd = process.cwd();
 		const strict = args.strict === true;
-		let credentials;
+		let options;
 		if (args.test) try {
-			credentials = await testWordPressCredentials(cwd);
+			options = {
+				credentials: await testWordPressCredentials(cwd),
+				strict
+			};
 		} catch (error) {
 			log.error(error instanceof Error ? error.message : String(error));
 			process.exitCode = 1;
 			return;
 		}
-		const options = {
-			credentials,
-			strict
-		};
+		else {
+			const credentials = await resolveWatchCredentials(cwd);
+			if (credentials) options = {
+				credentials,
+				strict
+			};
+			else {
+				log.info("No WordPress connection configured; generating the contract only, introspection skipped.");
+				options = {
+					skipIntrospection: true,
+					strict
+				};
+			}
+		}
 		const cfg = await resolveConfig(cwd, { dir: args.dir });
 		if (!cfg) {
 			log.info("Nothing to generate. Set `dir` in kizlo.config.ts or pass --dir.");
@@ -66,6 +79,7 @@ const generate = defineCommand({
 			process.exit(1);
 		}
 		if (result.contract === "none") {
+			if (result.introspection === "skipped") return;
 			const file = path.resolve(cwd, cfg.introspectionPath);
 			log.success(`WordPress introspection ${result.introspection === "generated" ? "written to" : "already current at"} ${file}`);
 			return;

package/dist/cli/daemon/config.js

@@ -1,7 +1,9 @@
+import { integrationEnv, resolveWordPressConnection, wordPressConnectionComplete } from "../../kizlo.js";
 import { DEFAULT_WORDPRESS_TAG, INTROSPECTION_META_REL, LOCAL_DIR_REL } from "../wp/constants.js";
 import { credentialsPath, findConfigDir } from "../wp/utils.js";
+import { node } from "../../integrations/node/integration.js";
 import { log } from "./logger.js";
-import { detectPackageManager } from "../utils.js";
+import { detectPackageManager, loadEnvFiles } from "../utils.js";
 import { WORDPRESS_TAG_PATTERN } from "../wp/version.js";
 import { importIgnoringVirtualModules } from "./jiti.js";
 import z from "zod/v4";
@@ -48,6 +50,7 @@ const testStackSchema = z.object({
 	]).optional(),
 	command: z.string().optional()
 });
+const mcpSchema = z.object({ port: z.number().int().positive().optional() });
 const localSchema = z.union([z.boolean(), z.object({
 	enable: z.boolean().optional(),
 	name: z.string().optional(),
@@ -60,27 +63,38 @@ const configSchema = z.object({
 	dir: dirSchema.optional(),
 	alias: z.string().optional(),
 	local: localSchema.optional(),
+	mcp: mcpSchema.optional(),
 	wordpressClientDir: removedKey("`wordpressClientDir` has been removed. Use `dir: { introspection }` instead."),
 	name: removedKey("`name` is no longer a config root key. Move it under `local.name`."),
 	worktrees: removedKey("`worktrees` is no longer a config root key. Move it under `local.worktrees`."),
 	dev: removedKey("`dev` is no longer a config root key. Move it under `local.dev`."),
 	test: removedKey("`test` is no longer a config root key. Move it under `local.test`.")
 });
-/** Normalize `local` (absent, `true`, `false`, or the object form) into one shape the resolvers read. */
+/**
+* Normalize `local` (absent, `true`, `false`, or the object form) into one shape the resolvers read.
+* A stack is off unless its own `enable: true` is set; `local: true` is the shorthand that turns both on.
+*/
 function resolveLocal(fileConfig) {
 	const local = fileConfig?.local;
 	if (local === true) return {
 		enabled: true,
+		devEnabled: true,
+		testEnabled: true,
 		dev: {},
 		test: {}
 	};
 	if (!local) return {
 		enabled: false,
+		devEnabled: false,
+		testEnabled: false,
 		dev: {},
 		test: {}
 	};
+	const enabled = local.enable !== false;
 	return {
-		enabled: local.enable !== false,
+		enabled,
+		devEnabled: enabled && local.dev?.enable === true,
+		testEnabled: enabled && local.test?.enable === true,
 		name: local.name,
 		worktrees: local.worktrees,
 		dev: local.dev ?? {},
@@ -94,6 +108,16 @@ const CONFIG_FILES = [
 ];
 const DEFAULT_DEV_PORT = 8080;
 const DEFAULT_DEV_DB_PORT = 3307;
+/**
+* Port the MCP server binds on `127.0.0.1` when `mcp.port` is unset. It steps off a collision like the
+* stack ports do, so two projects need no configuration to run side by side. A harness config names a
+* port and cannot follow one that moves, which is what setting `mcp.port` is for.
+*
+* Deliberately clear of the stack ports' own scan ranges. Each default steps up to `PORT_SCAN_RANGE`
+* ports looking for a free one, so a default inside 8080-8179 could be handed to the dev stack and
+* then claimed again here, since the MCP probe runs before compose has published anything.
+*/
+const DEFAULT_MCP_PORT = 8300;
 const DEFAULT_TEST_PORT = 8889;
 /** The generated introspection artifact's filename, written under its resolved directory. */
 const INTROSPECTION_FILE = "introspection.ts";
@@ -241,7 +265,7 @@ async function resolveTestConfig(cwd) {
 	const inherit = test.inherit !== false;
 	return {
 		configDir,
-		local: local.enabled && test.enable !== false,
+		local: local.testEnabled,
 		project: stackProject(resolveStackName(configDir, {
 			name: local.name,
 			worktrees: local.worktrees
@@ -256,14 +280,37 @@ async function resolveTestConfig(cwd) {
 	};
 }
 /**
-* Whether this project runs local WordPress under `kizlo dev`: local is enabled and the dev stack is
-* on (`local.dev.enable !== false`) in `kizlo.config.*`. When false, `kizlo dev` has nothing to boot and
-* runs the contract watcher alone, the path a project pointing at its own WordPress takes. Written by
-* `create`/`init` when local WordPress is chosen, so it's committed and survives `kizlo dev reset`.
+* Whether this project runs local WordPress under `kizlo dev`: the `local` block is enabled and the dev
+* stack is turned on with `local.dev.enable: true` (or `local: true`) in `kizlo.config.*`. When false,
+* `kizlo dev` has nothing to boot and runs the contract watcher alone, the path a project pointing at its
+* own WordPress takes. Written by `create`/`init` when local WordPress is chosen, so it's committed and
+* survives `kizlo dev reset`.
 */
 async function usesLocalWordPress(cwd) {
-	const local = resolveLocal(await loadConfigFile(findConfigDir(cwd)));
-	return local.enabled && local.dev.enable !== false;
+	return resolveLocal(await loadConfigFile(findConfigDir(cwd))).devEnabled;
+}
+/**
+* WordPress credentials for the dev/generate watcher, or `undefined` when there is nothing to introspect:
+* the active profile is `local` but no local dev stack is enabled, or the active profile's connection
+* envs are incomplete. Callers then generate the contract with introspection skipped rather than fetching
+* from a WordPress that is not there. Unlike {@link resolveWordPressConnection}, this never throws.
+*/
+async function resolveWatchCredentials(cwd) {
+	loadEnvFiles(cwd);
+	const env = integrationEnv([node()]);
+	if (env("mode")?.trim() === "local" && !await usesLocalWordPress(cwd)) return void 0;
+	if (!wordPressConnectionComplete(env)) return void 0;
+	return resolveWordPressConnection(env).credentials;
+}
+function resolveMcp(fileConfig) {
+	return {
+		port: fileConfig?.mcp?.port ?? DEFAULT_MCP_PORT,
+		portExplicit: fileConfig?.mcp?.port !== void 0
+	};
+}
+/** Resolve `mcp` from `kizlo.config.*`, applying the defaults for a project that says nothing about it. */
+async function resolveMcpConfig(cwd) {
+	return resolveMcp(await loadConfigFile(findConfigDir(cwd)));
 }
 /**
 * Resolve the dev stack (`local.dev`) into concrete values for the `dev` command, applying defaults
@@ -273,7 +320,8 @@ async function usesLocalWordPress(cwd) {
 */
 async function resolveDevConfig(cwd) {
 	const configDir = findConfigDir(cwd);
-	const local = resolveLocal(await loadConfigFile(configDir));
+	const fileConfig = await loadConfigFile(configDir);
+	const local = resolveLocal(fileConfig);
 	const { dev } = local;
 	return {
 		configDir,
@@ -288,9 +336,10 @@ async function resolveDevConfig(cwd) {
 		wordpressTag: dev.version ?? DEFAULT_WORDPRESS_TAG,
 		fixtures: dev.fixtures ?? [],
 		wordpressPath: LOCAL_DIR_REL,
-		wordpressDir: path.resolve(configDir, LOCAL_DIR_REL)
+		wordpressDir: path.resolve(configDir, LOCAL_DIR_REL),
+		mcp: resolveMcp(fileConfig)
 	};
 }
 
 //#endregion
-export { CONFIG_FILES, DEFAULT_DEV_DB_PORT, DEFAULT_DEV_PORT, resolveConfig, resolveDevConfig, resolveStackName, resolveTestConfig, stackProject, usesLocalWordPress };
+export { CONFIG_FILES, DEFAULT_DEV_DB_PORT, DEFAULT_DEV_PORT, DEFAULT_MCP_PORT, resolveConfig, resolveDevConfig, resolveMcpConfig, resolveStackName, resolveTestConfig, resolveWatchCredentials, stackProject, usesLocalWordPress };

package/dist/cli/daemon/generate.js

@@ -178,7 +178,7 @@ function reportPluginVersion(installed) {
 async function fetchDocument(cwd, options, etag) {
 	loadEnvFiles(cwd);
 	const result = await fetchIntrospection(options.credentials ?? resolveWordPressConnection(integrationEnv([node()])).credentials, {
-		etag: options.strict ? void 0 : etag,
+		etag: !options.strict && !options.seed ? etag : void 0,
 		fetch: options.fetch
 	});
 	reportPluginVersion(result.pluginVersion);
@@ -205,10 +205,17 @@ async function generateIntrospectionSource(cwd, options = {}) {
 * it under `generated/`, and a package that only ships procedures writes it at its own `dir.introspection`.
 */
 async function generateIntrospectionOnce(cfg, options = {}) {
+	if (options.skipIntrospection) return "skipped";
 	const file = path.resolve(cfg.cwd, cfg.introspectionPath);
 	const metaPath = path.resolve(cfg.cwd, cfg.introspectionMetaPath);
-	const result = await fetchDocument(cfg.cwd, options, readWordPressMeta(metaPath, file)?.etag);
+	const meta = readWordPressMeta(metaPath, file);
+	const result = await fetchDocument(cfg.cwd, options, meta?.etag);
 	if (!result?.document) return "unchanged";
+	options.onDocument?.(result.document);
+	if (options.seed && meta && result.document.hash === meta.hash) {
+		if (result.etag !== meta.etag) atomicWrite(metaPath, wordPressMeta(result.etag, result.document.hash));
+		return "unchanged";
+	}
 	const generated = generateWordPressModule(result.document);
 	await assertGeneratedClientCompiles(generated);
 	fs.mkdirSync(path.dirname(file), { recursive: true });

package/dist/cli/daemon/watch.js

@@ -1,8 +1,5 @@
-import { integrationEnv, resolveWordPressConnection } from "../../kizlo.js";
-import { node } from "../../integrations/node/integration.js";
 import { log } from "./logger.js";
-import { loadEnvFiles } from "../utils.js";
-import { resolveConfig } from "./config.js";
+import { resolveConfig, resolveWatchCredentials } from "./config.js";
 import { IntrospectionFetchError } from "../../wordpress/fetch-introspection.js";
 import { generateIntrospectionOnce, generateOnce, reportGenerationError } from "./generate.js";
 import { acquire, lockPath, release } from "./lock.js";
@@ -17,9 +14,9 @@ function debounce(fn, delay) {
 		timer = setTimeout(() => void fn(...args), delay);
 	});
 }
-async function regenerate(cfg, credentials) {
+async function regenerate(cfg, options) {
 	try {
-		const result = await generateOnce(cfg, { credentials });
+		const result = await generateOnce(cfg, options);
 		if (result.contract === "built") log.success("Contract updated");
 		else if (result.contract === "empty" && cfg.server) log.warn(`No Kizlo server found in ${cfg.server.entry}`);
 	} catch (error) {
@@ -27,13 +24,13 @@ async function regenerate(cfg, credentials) {
 	}
 }
 /** Watches the server directory and regenerates the contract on change. Only called when a server is present. */
-async function watch(cfg, server, credentials) {
+async function watch(cfg, server, options) {
 	const watcher = new FSWatcher({
 		persistent: true,
 		ignoreInitial: true,
 		ignored: path.resolve(cfg.cwd, server.contractDir)
 	});
-	const onChange = debounce(() => regenerate(cfg, credentials), 300);
+	const onChange = debounce(() => regenerate(cfg, options), 300);
 	watcher.add(path.resolve(cfg.cwd, server.dir));
 	watcher.on("all", () => void onChange());
 	return watcher;
@@ -106,8 +103,8 @@ function createWordPressRefresh(cfg, options, stack) {
 	};
 }
 /** Run {@link createWordPressRefresh} on a timer, skipping a tick while the previous one is still going. */
-function refreshWordPress(cfg, credentials, stack) {
-	const refresh = createWordPressRefresh(cfg, { credentials }, stack);
+function refreshWordPress(cfg, options, stack) {
+	const refresh = createWordPressRefresh(cfg, options, stack);
 	let refreshing = false;
 	const timer = setInterval(() => {
 		if (refreshing) return;
@@ -139,25 +136,34 @@ async function startWatcher(cwd, opts) {
 			log.info("skipping the contract generation.");
 			return;
 		}
-		loadEnvFiles(cwd);
-		const { credentials } = resolveWordPressConnection(integrationEnv([node()]));
+		const credentials = await resolveWatchCredentials(cwd);
+		const options = credentials ? { credentials } : { skipIntrospection: true };
+		if (!credentials) log.info("No WordPress connection configured; running the contract watcher only, introspection skipped.");
+		if (opts?.mcp) {
+			opts.mcp.credentials = credentials;
+			options.seed = true;
+			options.onDocument = (document) => {
+				if (opts.mcp) opts.mcp.document = document;
+				options.seed = false;
+			};
+		}
 		try {
-			const result = await generateOnce(cfg, { credentials });
+			const result = await generateOnce(cfg, options);
 			if (result.contract === "built") log.success("Contract generated");
 			else if (result.contract === "empty" && cfg.server) log.warn(`No Kizlo server found in ${cfg.server.entry}`);
 			else if (result.introspection === "generated") log.success("WordPress introspection generated");
 		} catch (error) {
 			reportGenerationError("Failed to generate the Kizlo contract:", error);
 		}
-		const watcher = cfg.server ? await watch(cfg, cfg.server, credentials) : void 0;
-		const wordpressRefresh = refreshWordPress(cfg, credentials, opts?.stack);
+		const watcher = cfg.server ? await watch(cfg, cfg.server, options) : void 0;
+		const wordpressRefresh = credentials ? refreshWordPress(cfg, options, opts?.stack) : void 0;
 		let stopped = false;
 		handedOver = true;
 		return () => {
 			if (stopped) return;
 			stopped = true;
 			release(lock);
-			clearInterval(wordpressRefresh);
+			if (wordpressRefresh) clearInterval(wordpressRefresh);
 			watcher?.close();
 		};
 	} finally {

package/dist/cli/mcp/index.js

@@ -0,0 +1,46 @@
+import { log } from "../daemon/logger.js";
+import { pickStackPort } from "../utils.js";
+import { MCP_HOST, MCP_PATH, isAllowedOrigin, startMcpServer } from "./server.js";
+import { createMcpState } from "./state.js";
+
+//#region src/cli/mcp/index.ts
+/**
+* The port the server will bind, stepping off a collision unless the project pinned one.
+*
+* Resolved before the server starts so the dev summary can print the address alongside WordPress's.
+* A pinned port that is taken stops the command the way `dev.port` and `test.port` do: the developer
+* wrote that number, a harness config elsewhere names it, and quietly serving on a different one
+* would leave the harness connecting to nothing.
+*/
+async function resolveMcpPort(config) {
+	return pickStackPort(config.port, {
+		fixed: config.portExplicit,
+		host: MCP_HOST,
+		configKey: "mcp.port"
+	});
+}
+/**
+* Start the MCP server for a session that has a watcher, or say why it is not running.
+*
+* Called after the watcher starts and never inside its restart cycle. Two cases leave it off, and
+* neither is a failure of the session: another `kizlo dev` already holds the watcher lock and is
+* serving MCP itself (the caller skips this entirely), or there is no WordPress connection to expose,
+* where the contract watcher still has work to do and MCP has nothing to answer with.
+*/
+async function startMcp(state, port) {
+	if (!state.credentials) {
+		log.info("No WordPress connection configured; the MCP server is off for this session.");
+		return;
+	}
+	try {
+		const handle = await startMcpServer(state, { port });
+		log.success(`MCP server on ${handle.url}`);
+		return handle;
+	} catch (error) {
+		log.error("Failed to start the MCP server:", error);
+		return;
+	}
+}
+
+//#endregion
+export { resolveMcpPort, startMcp };

package/dist/cli/mcp/routes.js

@@ -0,0 +1,42 @@
+import { camel, endpointDefinition } from "../../wordpress/generate.js";
+
+//#region src/cli/mcp/routes.ts
+/**
+* Every operation in the document, keyed by route name.
+*
+* Built per call rather than cached: the watcher replaces the document whenever WordPress moves, and
+* a registry that outlived one would answer for routes that no longer exist while missing the ones
+* that just appeared. Walking a contract of a few hundred routes is far cheaper than getting that wrong.
+*/
+function routesOf(document) {
+	const routes = /* @__PURE__ */ new Map();
+	for (const [apiId, api] of Object.entries(document.apis)) {
+		const prefix = apiId.split(".").map(camel);
+		for (const [path, operations] of Object.entries(api.paths)) for (const [operationId, operation] of Object.entries(operations)) {
+			const name = [...prefix, camel(operationId)].join(".");
+			routes.set(name, {
+				name,
+				namespace: api.namespace,
+				method: operation.method,
+				path,
+				...operation.summary !== void 0 ? { summary: operation.summary } : {},
+				...operation.description !== void 0 ? { description: operation.description } : {},
+				...operation.deprecated !== void 0 ? { deprecated: operation.deprecated } : {},
+				operation,
+				definition: endpointDefinition({
+					namespace: api.namespace,
+					path,
+					operation
+				})
+			});
+		}
+	}
+	return routes;
+}
+/** Route names in the order a listing shows them, so two calls against one document agree. */
+function sortRoutes(routes) {
+	return [...routes].sort((left, right) => left.name.localeCompare(right.name));
+}
+
+//#endregion
+export { routesOf, sortRoutes };