@warlock.js/core 5.30.0 → 5.32.0

package/esm/tooling/mcp/mcp-tools.mjs

@@ -0,0 +1,514 @@
+import { WarlockError } from "../../errors/warlock-error.mjs";
+import { ERROR_CODES, errorCodeDocsUrl, explainErrorCode, isWarlockErrorCode } from "../../errors/error-codes.mjs";
+import { INSPECT_SECTIONS } from "../inspect/inspect-report.types.mjs";
+import { CHECK_STEPS } from "../check/check-report.types.mjs";
+import { MAKE_GENERATORS, isMakeGenerator } from "../generate/generator-spec.mjs";
+import "../generate/index.mjs";
+import { readDocsFile, searchDocs } from "./docs-search.mjs";
+import { buildDbSchema } from "./db-schema.mjs";
+import { inputSchema } from "./tool-input.mjs";
+
+//#region ../../packages/core/src/tooling/mcp/mcp-tools.ts
+/** The `make` generators the `generate_make` tool can run (`warlock generate.<name>`). */
+const MCP_MAKE_GENERATORS = MAKE_GENERATORS;
+function stringArg(input, key) {
+	const value = input[key];
+	return typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
+}
+function booleanArg(input, key) {
+	return input[key] === true;
+}
+function integerArg(input, key, fallback) {
+	const value = input[key];
+	return typeof value === "number" && Number.isInteger(value) ? value : fallback;
+}
+function stringsArg(input, key) {
+	const value = input[key];
+	return Array.isArray(value) ? value.filter((item) => typeof item === "string") : void 0;
+}
+function includesText(values, needle) {
+	const lowered = needle.toLowerCase();
+	return values.some((value) => typeof value === "string" && value.toLowerCase().includes(lowered));
+}
+const MUTATING = /* @__PURE__ */ new Set([
+	"POST",
+	"PUT",
+	"PATCH",
+	"DELETE"
+]);
+function filterRoutes(routes, input) {
+	const filter = stringArg(input, "filter");
+	const method = stringArg(input, "method")?.toUpperCase();
+	const unguarded = booleanArg(input, "unguardedWrites");
+	return routes.filter((route) => (!filter || includesText([
+		route.path,
+		route.name,
+		route.handler,
+		route.sourceFile
+	], filter)) && (!method || route.method === method) && (!unguarded || MUTATING.has(route.method) && !route.auth.required && !route.isPage));
+}
+/** The `filter` match of one entry of a section, by the fields an agent would search. */
+function sectionEntryMatches(section, entry, filter) {
+	if (typeof entry !== "object" || entry === null) return false;
+	return includesText({
+		routes: [
+			"path",
+			"name",
+			"handler",
+			"sourceFile"
+		],
+		models: [
+			"name",
+			"table",
+			"sourceFile"
+		],
+		resources: ["name"],
+		config: ["key", "file"],
+		events: ["event"],
+		pages: [
+			"path",
+			"name",
+			"file"
+		],
+		jobs: ["name", "queue"],
+		schedules: ["name"],
+		packages: ["name"]
+	}[section].map((field) => {
+		const value = Reflect.get(entry, field);
+		return typeof value === "string" ? value : null;
+	}), filter);
+}
+const SECTION_DESCRIPTIONS = {
+	routes: "Registered HTTP routes from the booted router: method, path, name, source file, handler, middleware chain in run order, auth guard, CSRF, rate limit, logging policy, request JSON Schemas and declared responses ($refs resolve against `components`).",
+	models: "Cascade model classes: table, primary key, data source, columns (from the model's Seal schema), relations, resource, delete strategy and timestamp columns.",
+	resources: "Resources reached from route responses or models, with their output shape as JSON Schema and the models that use them.",
+	config: "Every loaded config key as a dotted path with its TYPE (never its value) and the src/config file it came from.",
+	events: "Event listeners app modules registered while loading, grouped by event, with the registering file.",
+	pages: "Pages @warlock.js/web installed: path, name, file, layout chain, loaders, actions and guard.",
+	jobs: "Queue jobs defined with defineJob() from @warlock.js/queue: name, queue, attempts, backoff, retention.",
+	schedules: "Scheduled tasks from @warlock.js/scheduler: name, cron expression, intervals, next run.",
+	packages: "Installed @warlock.js/* packages and their versions."
+};
+function inspectSectionTool(context, section) {
+	const properties = { filter: {
+		type: "string",
+		description: "Case-insensitive substring to keep only matching entries (names, paths, keys, files)."
+	} };
+	if (section === "routes") {
+		properties.method = {
+			type: "string",
+			description: "Only routes with this HTTP method (GET, POST, …)."
+		};
+		properties.unguardedWrites = {
+			type: "boolean",
+			description: "Only POST/PUT/PATCH/DELETE API routes that have no auth guard."
+		};
+	}
+	return {
+		name: `inspect_${section}`,
+		description: `${SECTION_DESCRIPTIONS[section]} Read from the app's registries (the same data as \`warlock inspect --json --section ${section}\`), not from source text. Read-only.`,
+		input: inputSchema(properties),
+		writes: false,
+		async run(input) {
+			const report = await context.inspect([section]);
+			const entries = report[section] ?? [];
+			const filter = stringArg(input, "filter");
+			const kept = section === "routes" && report.routes ? filterRoutes(report.routes, input) : filter ? entries.filter((entry) => sectionEntryMatches(section, entry, filter)) : entries;
+			const withSchemas = section === "routes" || section === "models" || section === "resources";
+			return {
+				schemaVersion: report.schemaVersion,
+				[section]: kept,
+				total: entries.length,
+				...withSchemas ? { components: report.components } : {},
+				warnings: report.warnings
+			};
+		}
+	};
+}
+function summarizeRequest(summary, record) {
+	if (!record) return summary;
+	const nPlusOneShapes = new Set(record.warnings.filter((warning) => warning.type === "n+1" && typeof warning.shape === "string").map((warning) => warning.shape));
+	return {
+		...summary,
+		error: record.error ?? null,
+		phases: record.phases,
+		queries: record.queries.map((query) => ({
+			...query,
+			nPlusOne: typeof query.shape === "string" && nPlusOneShapes.has(query.shape)
+		})),
+		warnings: record.warnings,
+		logs: record.logs,
+		cache: record.cache,
+		mails: record.mails,
+		timings: {
+			totalMs: record.durationMs ?? null,
+			phasesMs: record.phases.reduce((totals, phase) => {
+				totals[phase.name] = (totals[phase.name] ?? 0) + phase.durationMs;
+				return totals;
+			}, {}),
+			queriesMs: record.queries.reduce((total, query) => total + (typeof query.durationMs === "number" ? query.durationMs : 0), 0)
+		}
+	};
+}
+function writeProperty() {
+	return { write: {
+		type: "boolean",
+		description: "Write the files into the project. Default false: only return the diff (the generator runs in a throw-away copy of the project)."
+	} };
+}
+function refuseWrite(context) {
+	return (input) => input.write === true && !context.allowWrites ? `WL7005: this MCP server is read-only; restart it with --allow-writes to let generate tools write. Without it they return the diff only.` : null;
+}
+const MAKE_FLAGS = {
+	withValidation: {
+		type: "boolean",
+		description: "controller: also generate a validation schema and bind it (--with-validation)."
+	},
+	withResource: {
+		type: "boolean",
+		description: "model: also generate a resource (--with-resource)."
+	},
+	table: {
+		type: "string",
+		description: "model: the table name (--table)."
+	},
+	minimal: {
+		type: "boolean",
+		description: "module: a minimal skeleton instead of the full CRUD scaffold (--minimal)."
+	},
+	noTimestamps: {
+		type: "boolean",
+		description: "model / migration: no timestamp columns (--no-timestamps)."
+	},
+	add: {
+		type: "string",
+		description: "migration: columns to add, DSL name:type:modifier,… (--add)."
+	},
+	drop: {
+		type: "string",
+		description: "migration: comma-separated columns to drop (--drop)."
+	},
+	rename: {
+		type: "string",
+		description: "migration: columns to rename, old:new,… (--rename)."
+	},
+	force: {
+		type: "boolean",
+		description: "Overwrite files that already exist (--force)."
+	},
+	overwrite: {
+		type: "boolean",
+		description: "module / model: with force, also replace files that differ from the output (--overwrite)."
+	}
+};
+const FLAG_NAMES = {
+	withValidation: "with-validation",
+	withResource: "with-resource",
+	table: "table",
+	minimal: "minimal",
+	noTimestamps: "no-timestamps",
+	add: "add",
+	drop: "drop",
+	rename: "rename",
+	force: "force",
+	overwrite: "overwrite"
+};
+/** The generator spec a `generate_make` call describes. */
+function makeSpecFromInput(input) {
+	const generator = stringArg(input, "generator");
+	const name = stringArg(input, "name");
+	if (!generator || !isMakeGenerator(generator) || !name) throw new Error(`generate_make needs a generator (${MCP_MAKE_GENERATORS.join(", ")}) and a name.`);
+	const flags = {};
+	for (const [key, flag] of Object.entries(FLAG_NAMES)) {
+		const value = input[key];
+		if (value === true) flags[flag] = true;
+		if (typeof value === "string" && value.length > 0) flags[flag] = value;
+	}
+	return {
+		type: "make",
+		generator,
+		name,
+		flags
+	};
+}
+/**
+* The tools `warlock mcp` serves. Read-only unless `context.allowWrites`:
+* generate tools then accept `write: true`; without it they only return the
+* diff a generator would produce.
+*/
+function createWarlockMcpTools(context) {
+	return [
+		{
+			name: "inspect_app",
+			description: "Summary of the app: name, version, Node, environment, how many routes/models/resources/config keys/events/pages/jobs/schedules/packages it has, and inspect warnings (WL codes for modules that failed to load). Start here, then call the inspect_<section> tool you need. Read-only.",
+			input: inputSchema({}),
+			writes: false,
+			async run() {
+				const report = await context.inspect(INSPECT_SECTIONS);
+				const counts = Object.fromEntries(INSPECT_SECTIONS.map((section) => [section, report[section]?.length ?? 0]));
+				return {
+					schemaVersion: report.schemaVersion,
+					app: report.app,
+					counts,
+					warnings: report.warnings
+				};
+			}
+		},
+		...INSPECT_SECTIONS.map((section) => inspectSectionTool(context, section)),
+		{
+			name: "db_schema",
+			description: "The database schema the app's models declare: one entry per table with columns (type, required, primary key, foreign key of belongsTo relations), relations, timestamp columns and delete strategy. Built from the models' Seal schemas — no database connection is opened, so migration-only columns are not listed. Read-only.",
+			input: inputSchema({ model: {
+				type: "string",
+				description: "Only this model (class name) or table."
+			} }),
+			writes: false,
+			async run(input) {
+				const report = await context.inspect(["models"]);
+				return buildDbSchema(report.models ?? [], stringArg(input, "model"));
+			}
+		},
+		{
+			name: "docs_search",
+			description: "Search the documentation of the @warlock.js packages INSTALLED in this app (their skills, README and llms files under node_modules) — offline, so answers match the installed versions. Returns ranked sections with the file, heading, line and an excerpt; read a whole skill with docs_read. Read-only.",
+			input: inputSchema({
+				query: {
+					type: "string",
+					description: "Words to look for, e.g. 'validation schema file upload'."
+				},
+				limit: {
+					type: "integer",
+					description: "Maximum hits (default 8).",
+					minimum: 1,
+					maximum: 25
+				},
+				package: {
+					type: "string",
+					description: "Only this package, e.g. '@warlock.js/cascade'."
+				}
+			}, ["query"]),
+			writes: false,
+			async run(input) {
+				const corpus = await context.docs();
+				const query = stringArg(input, "query") ?? "";
+				return {
+					query,
+					files: corpus.files.length,
+					hits: searchDocs(corpus, query, {
+						limit: integerArg(input, "limit", 8),
+						package: stringArg(input, "package")
+					})
+				};
+			}
+		},
+		{
+			name: "docs_read",
+			description: "Read one file returned by docs_search (a skill, README or llms file of an installed @warlock.js package), whole or one section by its heading. Only files of that corpus can be read. Read-only.",
+			input: inputSchema({
+				file: {
+					type: "string",
+					description: "The `file` of a docs_search hit."
+				},
+				heading: {
+					type: "string",
+					description: "Only the section with this exact heading."
+				}
+			}, ["file"]),
+			writes: false,
+			async run(input) {
+				const corpus = await context.docs();
+				const file = stringArg(input, "file") ?? "";
+				const found = readDocsFile(corpus, context.cwd, file, { heading: stringArg(input, "heading") });
+				if (!found) throw new Error(`"${file}" is not an installed docs file (or has no such heading). Use docs_search first.`);
+				return found;
+			}
+		},
+		{
+			name: "explain",
+			description: "Explain a stable Warlock error code (WL3001, WL7301, WL8003, …): what it means, whether it is your code or this machine, the one-line fix, the skill that covers it and its docs link. Without a code, lists every code. Read-only.",
+			input: inputSchema({ code: {
+				type: "string",
+				description: "The code, e.g. WL3001."
+			} }),
+			writes: false,
+			async run(input) {
+				const code = stringArg(input, "code");
+				if (!code) return Object.values(ERROR_CODES).map((definition) => ({
+					code: definition.code,
+					title: definition.title,
+					category: definition.category
+				}));
+				const definition = explainErrorCode(code);
+				if (!definition) throw new Error(`Unknown error code "${code}". Call explain without a code to list them.`);
+				return {
+					...definition,
+					docs: isWarlockErrorCode(definition.code) ? errorCodeDocsUrl(definition.code) : null
+				};
+			}
+		},
+		{
+			name: "check_run",
+			description: "Run `warlock check`: typecheck, lint, the affected tests and the framework convention checks, as one report with one problem per entry (stable WL code, file:line, fix hint, skill). exitCode 1 means your code, 2 means this machine (missing service, Node version, crashed tool) — do not edit code for a 2. Use changed: true while iterating. Does not write project files.",
+			input: inputSchema({
+				changed: {
+					type: "boolean",
+					description: "Only the files changed against HEAD (plus untracked) and what they affect."
+				},
+				base: {
+					type: "string",
+					description: "Compare with the merge base of this git ref instead (implies changed)."
+				},
+				skip: {
+					type: "array",
+					description: "Steps to skip.",
+					items: {
+						type: "string",
+						enum: CHECK_STEPS
+					}
+				}
+			}),
+			writes: false,
+			async run(input) {
+				const skip = (stringsArg(input, "skip") ?? []).filter((step) => CHECK_STEPS.includes(step));
+				return context.check({
+					changed: booleanArg(input, "changed"),
+					base: stringArg(input, "base"),
+					skip
+				});
+			}
+		},
+		{
+			name: "test_run",
+			description: "Run the app's vitest tests: given test files run as they are; given source files, the tests that import them run (vitest related); changed: true runs the tests related to the files changed in git; neither runs the whole suite. Returns totals and one problem per failure (WL7301 failed test, WL7302 file failed to load, WL8xxx this machine). Does not write project files.",
+			input: inputSchema({
+				files: {
+					type: "array",
+					description: "Project-relative files (tests or sources).",
+					items: { type: "string" }
+				},
+				changed: {
+					type: "boolean",
+					description: "The tests related to the files changed against HEAD."
+				},
+				base: {
+					type: "string",
+					description: "With changed: compare with the merge base of this ref."
+				}
+			}),
+			writes: false,
+			async run(input) {
+				return context.tests({
+					files: stringsArg(input, "files"),
+					changed: booleanArg(input, "changed"),
+					base: stringArg(input, "base")
+				});
+			}
+		},
+		{
+			name: "requests_recent",
+			description: "The most recent HTTP requests the running dev server handled, from @warlock.js/devtools (needs `warlock dev` with devtools installed): method, path, matched route, status, duration, and — with details — the phase timeline (route match, each middleware, validation, handler), every query with its duration and an nPlusOne flag, N+1 warnings, logs, cache operations and captured mails. Request and response bodies are not recorded by devtools; use `warlock trace` for those. Read-only.",
+			input: inputSchema({
+				limit: {
+					type: "integer",
+					description: "How many requests (default 10, newest first).",
+					minimum: 1,
+					maximum: 50
+				},
+				method: {
+					type: "string",
+					description: "Only this HTTP method."
+				},
+				path: {
+					type: "string",
+					description: "Only paths containing this text."
+				},
+				status: {
+					type: "integer",
+					description: "Only this response status.",
+					minimum: 100,
+					maximum: 599
+				},
+				details: {
+					type: "boolean",
+					description: "Include the full timeline of each request (default true)."
+				}
+			}),
+			writes: false,
+			async run(input) {
+				const devtools = await context.devtools();
+				const method = stringArg(input, "method")?.toUpperCase();
+				const pathFilter = stringArg(input, "path");
+				const status = typeof input.status === "number" ? input.status : void 0;
+				const details = input.details !== false;
+				const summaries = (await devtools.listRequests()).filter((summary) => (!method || summary.method === method) && (!pathFilter || summary.path.includes(pathFilter)) && (status === void 0 || summary.status === status)).sort((first, second) => second.startedAt - first.startedAt).slice(0, integerArg(input, "limit", 10));
+				const requests = [];
+				for (const summary of summaries) requests.push(summarizeRequest(summary, details ? await devtools.getRequest(summary.id) : void 0));
+				return {
+					devtools: {
+						url: devtools.url,
+						path: devtools.devtoolsPath
+					},
+					requests
+				};
+			}
+		},
+		{
+			name: "generate_make",
+			description: `Run a \`warlock generate.<generator>\` scaffold (${MCP_MAKE_GENERATORS.join(", ")}) and return the unified diff of every file it would create or change. By default nothing in the project is written: the generator runs in a throw-away copy.${context.allowWrites ? " Pass write: true to write the files into the project." : " This server is read-only (no --allow-writes)."} Names are module/name for everything but module (e.g. posts/create-post) and the model path for migration.`,
+			input: inputSchema({
+				generator: {
+					type: "string",
+					description: "Which generator.",
+					enum: MCP_MAKE_GENERATORS
+				},
+				name: {
+					type: "string",
+					description: "The generator's argument: `posts` for module, `posts/create-post` for the others, the model path for migration."
+				},
+				...MAKE_FLAGS,
+				...context.allowWrites ? writeProperty() : {}
+			}, ["generator", "name"]),
+			writes: context.allowWrites,
+			precheck: refuseWrite(context),
+			async run(input) {
+				const spec = makeSpecFromInput(input);
+				return input.write === true ? context.generation.apply(spec) : context.generation.plan(spec);
+			}
+		},
+		{
+			name: "generate_add",
+			description: `Run \`warlock add <features…>\` (an installable framework feature: a database driver, queue, web, devtools, …) and return the unified diff of every file it would create or change, package.json included. Dependencies are recorded, never installed, in the preview.${context.allowWrites ? " Pass write: true to apply it to the project (this installs the dependencies)." : " This server is read-only (no --allow-writes)."}`,
+			input: inputSchema({
+				features: {
+					type: "array",
+					description: "Feature names, e.g. ['devtools'].",
+					items: context.features?.length ? {
+						type: "string",
+						enum: context.features
+					} : { type: "string" }
+				},
+				...context.allowWrites ? writeProperty() : {}
+			}, ["features"]),
+			writes: context.allowWrites,
+			precheck: refuseWrite(context),
+			async run(input) {
+				const features = stringsArg(input, "features") ?? [];
+				if (features.length === 0) throw new Error("generate_add needs at least one feature name.");
+				const spec = {
+					type: "add",
+					features
+				};
+				return input.write === true ? context.generation.apply(spec) : context.generation.plan(spec);
+			}
+		}
+	];
+}
+/** The message a tool failure reaches the client with: code, message and the fix. */
+function describeToolError(error) {
+	if (error instanceof WarlockError) return `${error.code}: ${error.message} Fix: ${ERROR_CODES[error.code].fix}`;
+	return error instanceof Error ? error.message : String(error);
+}
+
+//#endregion
+export { MCP_MAKE_GENERATORS, createWarlockMcpTools, describeToolError, makeSpecFromInput };
+//# sourceMappingURL=mcp-tools.mjs.map

package/esm/tooling/mcp/mcp-tools.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-tools.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/mcp/mcp-tools.ts"],"sourcesContent":["import {\n  ERROR_CODES,\n  errorCodeDocsUrl,\n  explainErrorCode,\n  isWarlockErrorCode,\n} from \"../../errors/error-codes\";\nimport { WarlockError } from \"../../errors/warlock-error\";\nimport { CHECK_STEPS, type CheckReport, type CheckStepName } from \"../check/check-report.types\";\nimport type { TestRunReport } from \"../check/run-tests\";\nimport type {\n  DevtoolsClient,\n  DevtoolsRequestRecord,\n  DevtoolsRequestSummaryRecord,\n} from \"../devtools/devtools-client\";\nimport { type GeneratorSpec, isMakeGenerator, MAKE_GENERATORS } from \"../generate\";\nimport {\n  INSPECT_SECTIONS,\n  type InspectReport,\n  type InspectRoute,\n  type InspectSection,\n} from \"../inspect/inspect-report.types\";\nimport { buildDbSchema } from \"./db-schema\";\nimport { type DocsCorpus, readDocsFile, searchDocs } from \"./docs-search\";\nimport { inputSchema, type McpInputSchema, type McpInputProperty } from \"./tool-input\";\n\n/**\n * What the `warlock mcp` tools run against. The CLI fills it from a read-only\n * boot of the app; `warlock dev --mcp` fills it from the live dev process;\n * tests pass fakes.\n */\nexport type WarlockMcpContext = {\n  /** Project root. */\n  cwd: string;\n  /** Whether tools may write project files (`--allow-writes`). */\n  allowWrites: boolean;\n  /** Describe the app (see `inspectApp`). */\n  inspect(sections: readonly InspectSection[]): Promise<InspectReport>;\n  /** Run `warlock check`. */\n  check(options: {\n    changed?: boolean;\n    base?: string;\n    skip?: readonly CheckStepName[];\n  }): Promise<CheckReport>;\n  /** Run tests for files, the changed files, or the suite. */\n  tests(options: {\n    files?: readonly string[];\n    changed?: boolean;\n    base?: string;\n  }): Promise<TestRunReport>;\n  /** Connect to the running dev server's devtools API (throws WL8008 / WL8009). */\n  devtools(): Promise<DevtoolsClient>;\n  /** Preview (and, with `allowWrites`, apply) a `make` / `add` generator. */\n  generation: {\n    plan(spec: GeneratorSpec): Promise<unknown>;\n    apply(spec: GeneratorSpec): Promise<unknown>;\n  };\n  /** The installed docs corpus (cached by the caller). */\n  docs(): Promise<DocsCorpus>;\n  /** The `warlock add` feature names, advertised as the `generate_add` enum. */\n  features?: readonly string[];\n};\n\n/** One tool the server exposes. */\nexport type WarlockMcpTool = {\n  /** Underscored, never dotted: model APIs refuse dots in tool names (`^[a-zA-Z0-9_-]{1,128}$`). */\n  name: string;\n  description: string;\n  input: McpInputSchema;\n  /** Whether a call can change project files. Only exposed with `allowWrites`. */\n  writes: boolean;\n  /** A check run before validation; return a message to refuse the call. */\n  precheck?: (input: Record<string, unknown>) => string | null;\n  run(input: Record<string, unknown>): Promise<unknown>;\n};\n\n/** The `make` generators the `generate_make` tool can run (`warlock generate.<name>`). */\nexport const MCP_MAKE_GENERATORS = MAKE_GENERATORS;\n\nfunction stringArg(input: Record<string, unknown>, key: string): string | undefined {\n  const value = input[key];\n\n  return typeof value === \"string\" && value.trim().length > 0 ? value.trim() : undefined;\n}\n\nfunction booleanArg(input: Record<string, unknown>, key: string): boolean {\n  return input[key] === true;\n}\n\nfunction integerArg(input: Record<string, unknown>, key: string, fallback: number): number {\n  const value = input[key];\n\n  return typeof value === \"number\" && Number.isInteger(value) ? value : fallback;\n}\n\nfunction stringsArg(input: Record<string, unknown>, key: string): string[] | undefined {\n  const value = input[key];\n\n  return Array.isArray(value)\n    ? value.filter((item): item is string => typeof item === \"string\")\n    : undefined;\n}\n\nfunction includesText(values: readonly (string | null | undefined)[], needle: string): boolean {\n  const lowered = needle.toLowerCase();\n\n  return values.some((value) => typeof value === \"string\" && value.toLowerCase().includes(lowered));\n}\n\nconst MUTATING = new Set([\"POST\", \"PUT\", \"PATCH\", \"DELETE\"]);\n\nfunction filterRoutes(\n  routes: readonly InspectRoute[],\n  input: Record<string, unknown>,\n): InspectRoute[] {\n  const filter = stringArg(input, \"filter\");\n  const method = stringArg(input, \"method\")?.toUpperCase();\n  const unguarded = booleanArg(input, \"unguardedWrites\");\n\n  return routes.filter(\n    (route) =>\n      (!filter ||\n        includesText([route.path, route.name, route.handler, route.sourceFile], filter)) &&\n      (!method || route.method === method) &&\n      (!unguarded || (MUTATING.has(route.method) && !route.auth.required && !route.isPage)),\n  );\n}\n\n/** The `filter` match of one entry of a section, by the fields an agent would search. */\nfunction sectionEntryMatches(section: InspectSection, entry: unknown, filter: string): boolean {\n  if (typeof entry !== \"object\" || entry === null) return false;\n\n  const fields: Record<InspectSection, readonly string[]> = {\n    routes: [\"path\", \"name\", \"handler\", \"sourceFile\"],\n    models: [\"name\", \"table\", \"sourceFile\"],\n    resources: [\"name\"],\n    config: [\"key\", \"file\"],\n    events: [\"event\"],\n    pages: [\"path\", \"name\", \"file\"],\n    jobs: [\"name\", \"queue\"],\n    schedules: [\"name\"],\n    packages: [\"name\"],\n  };\n\n  return includesText(\n    fields[section].map((field) => {\n      const value = Reflect.get(entry, field);\n      return typeof value === \"string\" ? value : null;\n    }),\n    filter,\n  );\n}\n\nconst SECTION_DESCRIPTIONS: Record<InspectSection, string> = {\n  routes:\n    \"Registered HTTP routes from the booted router: method, path, name, source file, handler, middleware chain in run order, auth guard, CSRF, rate limit, logging policy, request JSON Schemas and declared responses ($refs resolve against `components`).\",\n  models:\n    \"Cascade model classes: table, primary key, data source, columns (from the model's Seal schema), relations, resource, delete strategy and timestamp columns.\",\n  resources:\n    \"Resources reached from route responses or models, with their output shape as JSON Schema and the models that use them.\",\n  config:\n    \"Every loaded config key as a dotted path with its TYPE (never its value) and the src/config file it came from.\",\n  events:\n    \"Event listeners app modules registered while loading, grouped by event, with the registering file.\",\n  pages:\n    \"Pages @warlock.js/web installed: path, name, file, layout chain, loaders, actions and guard.\",\n  jobs: \"Queue jobs defined with defineJob() from @warlock.js/queue: name, queue, attempts, backoff, retention.\",\n  schedules:\n    \"Scheduled tasks from @warlock.js/scheduler: name, cron expression, intervals, next run.\",\n  packages: \"Installed @warlock.js/* packages and their versions.\",\n};\n\nfunction inspectSectionTool(context: WarlockMcpContext, section: InspectSection): WarlockMcpTool {\n  const properties: Record<string, McpInputProperty> = {\n    filter: {\n      type: \"string\",\n      description:\n        \"Case-insensitive substring to keep only matching entries (names, paths, keys, files).\",\n    },\n  };\n\n  if (section === \"routes\") {\n    properties.method = {\n      type: \"string\",\n      description: \"Only routes with this HTTP method (GET, POST, …).\",\n    };\n    properties.unguardedWrites = {\n      type: \"boolean\",\n      description: \"Only POST/PUT/PATCH/DELETE API routes that have no auth guard.\",\n    };\n  }\n\n  return {\n    name: `inspect_${section}`,\n    description: `${SECTION_DESCRIPTIONS[section]} Read from the app's registries (the same data as \\`warlock inspect --json --section ${section}\\`), not from source text. Read-only.`,\n    input: inputSchema(properties),\n    writes: false,\n    async run(input) {\n      const report = await context.inspect([section]);\n      const entries: unknown[] = report[section] ?? [];\n      const filter = stringArg(input, \"filter\");\n      const kept =\n        section === \"routes\" && report.routes\n          ? filterRoutes(report.routes, input)\n          : filter\n            ? entries.filter((entry) => sectionEntryMatches(section, entry, filter))\n            : entries;\n      const withSchemas = section === \"routes\" || section === \"models\" || section === \"resources\";\n\n      return {\n        schemaVersion: report.schemaVersion,\n        [section]: kept,\n        total: entries.length,\n        ...(withSchemas ? { components: report.components } : {}),\n        warnings: report.warnings,\n      };\n    },\n  };\n}\n\nfunction summarizeRequest(summary: DevtoolsRequestSummaryRecord, record?: DevtoolsRequestRecord) {\n  if (!record) return summary;\n\n  const nPlusOneShapes = new Set(\n    record.warnings\n      .filter((warning) => warning.type === \"n+1\" && typeof warning.shape === \"string\")\n      .map((warning) => warning.shape),\n  );\n\n  return {\n    ...summary,\n    error: record.error ?? null,\n    phases: record.phases,\n    queries: record.queries.map((query) => ({\n      ...query,\n      nPlusOne: typeof query.shape === \"string\" && nPlusOneShapes.has(query.shape),\n    })),\n    warnings: record.warnings,\n    logs: record.logs,\n    cache: record.cache,\n    mails: record.mails,\n    timings: {\n      totalMs: record.durationMs ?? null,\n      phasesMs: record.phases.reduce<Record<string, number>>((totals, phase) => {\n        totals[phase.name] = (totals[phase.name] ?? 0) + phase.durationMs;\n        return totals;\n      }, {}),\n      queriesMs: record.queries.reduce(\n        (total, query) => total + (typeof query.durationMs === \"number\" ? query.durationMs : 0),\n        0,\n      ),\n    },\n  };\n}\n\nfunction writeProperty(): Record<string, McpInputProperty> {\n  return {\n    write: {\n      type: \"boolean\",\n      description:\n        \"Write the files into the project. Default false: only return the diff (the generator runs in a throw-away copy of the project).\",\n    },\n  };\n}\n\nfunction refuseWrite(context: WarlockMcpContext) {\n  return (input: Record<string, unknown>): string | null =>\n    input.write === true && !context.allowWrites\n      ? `WL7005: this MCP server is read-only; restart it with --allow-writes to let generate tools write. Without it they return the diff only.`\n      : null;\n}\n\nconst MAKE_FLAGS: Record<string, McpInputProperty> = {\n  withValidation: {\n    type: \"boolean\",\n    description: \"controller: also generate a validation schema and bind it (--with-validation).\",\n  },\n  withResource: {\n    type: \"boolean\",\n    description: \"model: also generate a resource (--with-resource).\",\n  },\n  table: { type: \"string\", description: \"model: the table name (--table).\" },\n  minimal: {\n    type: \"boolean\",\n    description: \"module: a minimal skeleton instead of the full CRUD scaffold (--minimal).\",\n  },\n  noTimestamps: {\n    type: \"boolean\",\n    description: \"model / migration: no timestamp columns (--no-timestamps).\",\n  },\n  add: {\n    type: \"string\",\n    description: \"migration: columns to add, DSL name:type:modifier,… (--add).\",\n  },\n  drop: { type: \"string\", description: \"migration: comma-separated columns to drop (--drop).\" },\n  rename: { type: \"string\", description: \"migration: columns to rename, old:new,… (--rename).\" },\n  force: { type: \"boolean\", description: \"Overwrite files that already exist (--force).\" },\n  overwrite: {\n    type: \"boolean\",\n    description:\n      \"module / model: with force, also replace files that differ from the output (--overwrite).\",\n  },\n};\n\nconst FLAG_NAMES: Record<string, string> = {\n  withValidation: \"with-validation\",\n  withResource: \"with-resource\",\n  table: \"table\",\n  minimal: \"minimal\",\n  noTimestamps: \"no-timestamps\",\n  add: \"add\",\n  drop: \"drop\",\n  rename: \"rename\",\n  force: \"force\",\n  overwrite: \"overwrite\",\n};\n\n/** The generator spec a `generate_make` call describes. */\nexport function makeSpecFromInput(input: Record<string, unknown>): GeneratorSpec {\n  const generator = stringArg(input, \"generator\");\n  const name = stringArg(input, \"name\");\n\n  if (!generator || !isMakeGenerator(generator) || !name) {\n    throw new Error(\n      `generate_make needs a generator (${MCP_MAKE_GENERATORS.join(\", \")}) and a name.`,\n    );\n  }\n\n  const flags: Record<string, string | boolean> = {};\n\n  for (const [key, flag] of Object.entries(FLAG_NAMES)) {\n    const value = input[key];\n\n    if (value === true) flags[flag] = true;\n    if (typeof value === \"string\" && value.length > 0) flags[flag] = value;\n  }\n\n  return {\n    type: \"make\",\n    generator,\n    name,\n    flags,\n  };\n}\n\n/**\n * The tools `warlock mcp` serves. Read-only unless `context.allowWrites`:\n * generate tools then accept `write: true`; without it they only return the\n * diff a generator would produce.\n */\nexport function createWarlockMcpTools(context: WarlockMcpContext): WarlockMcpTool[] {\n  const tools: WarlockMcpTool[] = [\n    {\n      name: \"inspect_app\",\n      description:\n        \"Summary of the app: name, version, Node, environment, how many routes/models/resources/config keys/events/pages/jobs/schedules/packages it has, and inspect warnings (WL codes for modules that failed to load). Start here, then call the inspect_<section> tool you need. Read-only.\",\n      input: inputSchema({}),\n      writes: false,\n      async run() {\n        const report = await context.inspect(INSPECT_SECTIONS);\n        const counts = Object.fromEntries(\n          INSPECT_SECTIONS.map((section) => [section, report[section]?.length ?? 0]),\n        );\n\n        return {\n          schemaVersion: report.schemaVersion,\n          app: report.app,\n          counts,\n          warnings: report.warnings,\n        };\n      },\n    },\n    ...INSPECT_SECTIONS.map((section) => inspectSectionTool(context, section)),\n    {\n      name: \"db_schema\",\n      description:\n        \"The database schema the app's models declare: one entry per table with columns (type, required, primary key, foreign key of belongsTo relations), relations, timestamp columns and delete strategy. Built from the models' Seal schemas — no database connection is opened, so migration-only columns are not listed. Read-only.\",\n      input: inputSchema({\n        model: { type: \"string\", description: \"Only this model (class name) or table.\" },\n      }),\n      writes: false,\n      async run(input) {\n        const report = await context.inspect([\"models\"]);\n\n        return buildDbSchema(report.models ?? [], stringArg(input, \"model\"));\n      },\n    },\n    {\n      name: \"docs_search\",\n      description:\n        \"Search the documentation of the @warlock.js packages INSTALLED in this app (their skills, README and llms files under node_modules) — offline, so answers match the installed versions. Returns ranked sections with the file, heading, line and an excerpt; read a whole skill with docs_read. Read-only.\",\n      input: inputSchema(\n        {\n          query: {\n            type: \"string\",\n            description: \"Words to look for, e.g. 'validation schema file upload'.\",\n          },\n          limit: {\n            type: \"integer\",\n            description: \"Maximum hits (default 8).\",\n            minimum: 1,\n            maximum: 25,\n          },\n          package: {\n            type: \"string\",\n            description: \"Only this package, e.g. '@warlock.js/cascade'.\",\n          },\n        },\n        [\"query\"],\n      ),\n      writes: false,\n      async run(input) {\n        const corpus = await context.docs();\n        const query = stringArg(input, \"query\") ?? \"\";\n\n        return {\n          query,\n          files: corpus.files.length,\n          hits: searchDocs(corpus, query, {\n            limit: integerArg(input, \"limit\", 8),\n            package: stringArg(input, \"package\"),\n          }),\n        };\n      },\n    },\n    {\n      name: \"docs_read\",\n      description:\n        \"Read one file returned by docs_search (a skill, README or llms file of an installed @warlock.js package), whole or one section by its heading. Only files of that corpus can be read. Read-only.\",\n      input: inputSchema(\n        {\n          file: { type: \"string\", description: \"The `file` of a docs_search hit.\" },\n          heading: { type: \"string\", description: \"Only the section with this exact heading.\" },\n        },\n        [\"file\"],\n      ),\n      writes: false,\n      async run(input) {\n        const corpus = await context.docs();\n        const file = stringArg(input, \"file\") ?? \"\";\n        const found = readDocsFile(corpus, context.cwd, file, {\n          heading: stringArg(input, \"heading\"),\n        });\n\n        if (!found)\n          throw new Error(\n            `\"${file}\" is not an installed docs file (or has no such heading). Use docs_search first.`,\n          );\n\n        return found;\n      },\n    },\n    {\n      name: \"explain\",\n      description:\n        \"Explain a stable Warlock error code (WL3001, WL7301, WL8003, …): what it means, whether it is your code or this machine, the one-line fix, the skill that covers it and its docs link. Without a code, lists every code. Read-only.\",\n      input: inputSchema({ code: { type: \"string\", description: \"The code, e.g. WL3001.\" } }),\n      writes: false,\n      async run(input) {\n        const code = stringArg(input, \"code\");\n\n        if (!code) {\n          return Object.values(ERROR_CODES).map((definition) => ({\n            code: definition.code,\n            title: definition.title,\n            category: definition.category,\n          }));\n        }\n\n        const definition = explainErrorCode(code);\n\n        if (!definition)\n          throw new Error(\n            `Unknown error code \"${code}\". Call explain without a code to list them.`,\n          );\n\n        return {\n          ...definition,\n          docs: isWarlockErrorCode(definition.code) ? errorCodeDocsUrl(definition.code) : null,\n        };\n      },\n    },\n    {\n      name: \"check_run\",\n      description:\n        \"Run `warlock check`: typecheck, lint, the affected tests and the framework convention checks, as one report with one problem per entry (stable WL code, file:line, fix hint, skill). exitCode 1 means your code, 2 means this machine (missing service, Node version, crashed tool) — do not edit code for a 2. Use changed: true while iterating. Does not write project files.\",\n      input: inputSchema({\n        changed: {\n          type: \"boolean\",\n          description: \"Only the files changed against HEAD (plus untracked) and what they affect.\",\n        },\n        base: {\n          type: \"string\",\n          description: \"Compare with the merge base of this git ref instead (implies changed).\",\n        },\n        skip: {\n          type: \"array\",\n          description: \"Steps to skip.\",\n          items: { type: \"string\", enum: CHECK_STEPS },\n        },\n      }),\n      writes: false,\n      async run(input) {\n        const skip = (stringsArg(input, \"skip\") ?? []).filter((step): step is CheckStepName =>\n          (CHECK_STEPS as readonly string[]).includes(step),\n        );\n\n        return context.check({\n          changed: booleanArg(input, \"changed\"),\n          base: stringArg(input, \"base\"),\n          skip,\n        });\n      },\n    },\n    {\n      name: \"test_run\",\n      description:\n        \"Run the app's vitest tests: given test files run as they are; given source files, the tests that import them run (vitest related); changed: true runs the tests related to the files changed in git; neither runs the whole suite. Returns totals and one problem per failure (WL7301 failed test, WL7302 file failed to load, WL8xxx this machine). Does not write project files.\",\n      input: inputSchema({\n        files: {\n          type: \"array\",\n          description: \"Project-relative files (tests or sources).\",\n          items: { type: \"string\" },\n        },\n        changed: {\n          type: \"boolean\",\n          description: \"The tests related to the files changed against HEAD.\",\n        },\n        base: {\n          type: \"string\",\n          description: \"With changed: compare with the merge base of this ref.\",\n        },\n      }),\n      writes: false,\n      async run(input) {\n        return context.tests({\n          files: stringsArg(input, \"files\"),\n          changed: booleanArg(input, \"changed\"),\n          base: stringArg(input, \"base\"),\n        });\n      },\n    },\n    {\n      name: \"requests_recent\",\n      description:\n        \"The most recent HTTP requests the running dev server handled, from @warlock.js/devtools (needs `warlock dev` with devtools installed): method, path, matched route, status, duration, and — with details — the phase timeline (route match, each middleware, validation, handler), every query with its duration and an nPlusOne flag, N+1 warnings, logs, cache operations and captured mails. Request and response bodies are not recorded by devtools; use `warlock trace` for those. Read-only.\",\n      input: inputSchema({\n        limit: {\n          type: \"integer\",\n          description: \"How many requests (default 10, newest first).\",\n          minimum: 1,\n          maximum: 50,\n        },\n        method: { type: \"string\", description: \"Only this HTTP method.\" },\n        path: { type: \"string\", description: \"Only paths containing this text.\" },\n        status: {\n          type: \"integer\",\n          description: \"Only this response status.\",\n          minimum: 100,\n          maximum: 599,\n        },\n        details: {\n          type: \"boolean\",\n          description: \"Include the full timeline of each request (default true).\",\n        },\n      }),\n      writes: false,\n      async run(input) {\n        const devtools = await context.devtools();\n        const method = stringArg(input, \"method\")?.toUpperCase();\n        const pathFilter = stringArg(input, \"path\");\n        const status = typeof input.status === \"number\" ? input.status : undefined;\n        const details = input.details !== false;\n        const summaries = (await devtools.listRequests())\n          .filter(\n            (summary) =>\n              (!method || summary.method === method) &&\n              (!pathFilter || summary.path.includes(pathFilter)) &&\n              (status === undefined || summary.status === status),\n          )\n          .sort((first, second) => second.startedAt - first.startedAt)\n          .slice(0, integerArg(input, \"limit\", 10));\n        const requests = [];\n\n        for (const summary of summaries) {\n          requests.push(\n            summarizeRequest(summary, details ? await devtools.getRequest(summary.id) : undefined),\n          );\n        }\n\n        return { devtools: { url: devtools.url, path: devtools.devtoolsPath }, requests };\n      },\n    },\n    {\n      name: \"generate_make\",\n      description: `Run a \\`warlock generate.<generator>\\` scaffold (${MCP_MAKE_GENERATORS.join(\", \")}) and return the unified diff of every file it would create or change. By default nothing in the project is written: the generator runs in a throw-away copy.${context.allowWrites ? \" Pass write: true to write the files into the project.\" : \" This server is read-only (no --allow-writes).\"} Names are module/name for everything but module (e.g. posts/create-post) and the model path for migration.`,\n      input: inputSchema(\n        {\n          generator: { type: \"string\", description: \"Which generator.\", enum: MCP_MAKE_GENERATORS },\n          name: {\n            type: \"string\",\n            description:\n              \"The generator's argument: `posts` for module, `posts/create-post` for the others, the model path for migration.\",\n          },\n          ...MAKE_FLAGS,\n          ...(context.allowWrites ? writeProperty() : {}),\n        },\n        [\"generator\", \"name\"],\n      ),\n      writes: context.allowWrites,\n      precheck: refuseWrite(context),\n      async run(input) {\n        const spec = makeSpecFromInput(input);\n\n        return input.write === true\n          ? context.generation.apply(spec)\n          : context.generation.plan(spec);\n      },\n    },\n    {\n      name: \"generate_add\",\n      description: `Run \\`warlock add <features…>\\` (an installable framework feature: a database driver, queue, web, devtools, …) and return the unified diff of every file it would create or change, package.json included. Dependencies are recorded, never installed, in the preview.${context.allowWrites ? \" Pass write: true to apply it to the project (this installs the dependencies).\" : \" This server is read-only (no --allow-writes).\"}`,\n      input: inputSchema(\n        {\n          features: {\n            type: \"array\",\n            description: \"Feature names, e.g. ['devtools'].\",\n            items: context.features?.length\n              ? { type: \"string\", enum: context.features }\n              : { type: \"string\" },\n          },\n          ...(context.allowWrites ? writeProperty() : {}),\n        },\n        [\"features\"],\n      ),\n      writes: context.allowWrites,\n      precheck: refuseWrite(context),\n      async run(input) {\n        const features = stringsArg(input, \"features\") ?? [];\n\n        if (features.length === 0) throw new Error(\"generate_add needs at least one feature name.\");\n\n        const spec: GeneratorSpec = { type: \"add\", features };\n\n        return input.write === true\n          ? context.generation.apply(spec)\n          : context.generation.plan(spec);\n      },\n    },\n  ];\n\n  return tools;\n}\n\n/** The message a tool failure reaches the client with: code, message and the fix. */\nexport function describeToolError(error: unknown): string {\n  if (error instanceof WarlockError) {\n    return `${error.code}: ${error.message} Fix: ${ERROR_CODES[error.code].fix}`;\n  }\n\n  return error instanceof Error ? error.message : String(error);\n}\n"],"mappings":"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"}

package/esm/tooling/mcp/start-mcp-server.d.mts

@@ -0,0 +1,63 @@
+import { WarlockMcpContext, WarlockMcpTool } from "./mcp-tools.mjs";
+import { AiToolsServeModule, ServeToolContract, ServeTransportOptions } from "./load-ai-tools.mjs";
+//#region ../../packages/core/src/tooling/mcp/start-mcp-server.d.ts
+/** Where the server listens. */
+export type WarlockMcpTransport = {
+  type: "stdio";
+} | {
+  type: "http";
+  /** Default `127.0.0.1`. Any other host requires `token`. */
+  host?: string;
+  /** Default `0` (a free port; read it from the returned `url`). */
+  port?: number;
+  /** Default `/mcp`. */
+  path?: string;
+  /** Bearer token clients must send (`Authorization: Bearer <token>`). */
+  token?: string;
+};
+/** Options of {@link startWarlockMcpServer}. */
+export type StartWarlockMcpServerOptions = {
+  context: WarlockMcpContext;
+  /** Default `{ type: "stdio" }`. */
+  transport?: WarlockMcpTransport;
+  /** Advertised in `initialize`. Default `"warlock"`. */
+  name?: string;
+  version?: string;
+  /** How `@warlock.js/ai-tools` is loaded (tests inject it). */
+  loadServe?: () => Promise<AiToolsServeModule>;
+};
+/** A running server. */
+export type WarlockMcpServerHandle = {
+  /** The endpoint (HTTP only), e.g. `http://127.0.0.1:53211/mcp`. */
+  url?: string;
+  /** The exposed tool names. */
+  tools: string[];
+  close(): Promise<void>;
+};
+/** Whether a bind host is loopback-only. */
+export declare function isLoopbackHost(host: string): boolean;
+/** Resolve the transport, refusing a non-loopback bind without a token (`WL7004`). */
+export declare function resolveMcpTransport(transport?: WarlockMcpTransport): ServeTransportOptions;
+/**
+ * Turn a Warlock tool into the contract `ai.mcp.serve` runs: arguments are
+ * prechecked (a write on a read-only server), validated against the advertised
+ * schema, then run; a failure becomes an `isError` result carrying the WL code
+ * and its fix, never a crashed server.
+ */
+export declare function toServeContract(tool: WarlockMcpTool): ServeToolContract;
+/**
+ * Serve the app's tools over MCP — stdio by default, or Streamable HTTP
+ * through `@warlock.js/ai-tools` (loopback by default; a token is required off
+ * loopback). Read-only unless `context.allowWrites`.
+ *
+ * @example
+ * const server = await startWarlockMcpServer({
+ *   context,
+ *   transport: { type: "http", token: process.env.WARLOCK_MCP_TOKEN },
+ * });
+ * console.error(`MCP at ${server.url}`);
+ * await server.close();
+ */
+export declare function startWarlockMcpServer(options: StartWarlockMcpServerOptions): Promise<WarlockMcpServerHandle>;
+//#endregion
+//# sourceMappingURL=start-mcp-server.d.mts.map

package/esm/tooling/mcp/start-mcp-server.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"start-mcp-server.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/mcp/start-mcp-server.ts"],"mappings":";;;;YAgBY;EACN;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;;YAIM;EACV,SAAS;;EAET,YAAY;;EAEZ;EACA;;EAEA,kBAAkB,QAAQ;;;YAIhB;;EAEV;;EAEA;EACA,SAAS;;;wBAMK,eAAe;;wBAKf,oBACd,YAAW,sBACV;;;;;;;wBAkDa,gBAAgB,MAAM,iBAAiB;;;;;;;;;;;;;;wBAgDjC,sBACpB,SAAS,+BACR,QAAQ"}