create-better-fullstack 2.0.3 → 2.1.0

package/dist/mcp-entry.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
-import { a as getEffectiveStack, i as writeBtsConfig, l as getGraphSummary, n as readBtsConfig, p as getLatestCLIVersion, t as previewBtsConfigUpdate } from "./bts-config-Bg1Qea9Y.mjs";
+import { f as getEffectiveStack, g as getGraphSummary, n as previewBtsConfigUpdate, o as writeBtsConfig, r as readBtsConfig, s as getLatestCLIVersion } from "./bts-config-InNcw1aJ.mjs";
+import { n as getTemplateDescription, r as generateReproducibleCommand, t as getTemplateConfig } from "./templates-B351F1yX.mjs";
 import z from "zod";
-import { AISchema, APISchema, AddonsSchema, AnalyticsSchema, AnimationSchema, AstroIntegrationSchema, AuthSchema, BackendSchema, CATEGORY_ORDER, CMSSchema, CSSFrameworkSchema, CachingSchema, DatabaseSchema, DatabaseSetupSchema, DotnetApiSchema, DotnetAuthSchema, DotnetCachingSchema, DotnetDeploySchema, DotnetJobQueueSchema, DotnetObservabilitySchema, DotnetOrmSchema, DotnetRealtimeSchema, DotnetTestingSchema, DotnetValidationSchema, DotnetWebFrameworkSchema, EcosystemSchema, EffectSchema, ElixirApiSchema, ElixirAuthSchema, ElixirCachingSchema, ElixirDeploySchema, ElixirEmailSchema, ElixirHttpSchema, ElixirJobsSchema, ElixirJsonSchema, ElixirLibrariesSchema, ElixirObservabilitySchema, ElixirOrmSchema, ElixirQualitySchema, ElixirRealtimeSchema, ElixirTestingSchema, ElixirValidationSchema, ElixirWebFrameworkSchema, EmailSchema, ExamplesSchema, FeatureFlagsSchema, FileStorageSchema, FileUploadSchema, FormsSchema, FrontendSchema, GoApiSchema, GoAuthSchema, GoCachingSchema, GoCliSchema, GoConfigSchema, GoLoggingSchema, GoMessageQueueSchema, GoObservabilitySchema, GoOrmSchema, GoRealtimeSchema, GoTestingSchema, GoWebFrameworkSchema, I18nSchema, JavaApiSchema, JavaAuthSchema, JavaBuildToolSchema, JavaLibrariesSchema, JavaLoggingSchema, JavaOrmSchema, JavaTestingLibrariesSchema, JavaWebFrameworkSchema, JobQueueSchema, LoggingSchema, MobileDeepLinkingSchema, MobileNavigationSchema, MobileOTASchema, MobilePushSchema, MobileStorageSchema, MobileTestingSchema, MobileUISchema, OPTION_CATEGORY_METADATA, ORMSchema, ObservabilitySchema, PackageManagerSchema, PaymentsSchema, PythonAiSchema, PythonApiSchema, PythonAuthSchema, PythonCachingSchema, PythonCliSchema, PythonGraphqlSchema, PythonObservabilitySchema, PythonOrmSchema, PythonQualitySchema, PythonRealtimeSchema, PythonTaskQueueSchema, PythonTestingSchema, PythonValidationSchema, PythonWebFrameworkSchema, RateLimitSchema, RealtimeSchema, RuntimeSchema, RustApiSchema, RustAuthSchema, RustCachingSchema, RustCliSchema, RustErrorHandlingSchema, RustFrontendSchema, RustLibrariesSchema, RustLoggingSchema, RustMessageQueueSchema, RustObservabilitySchema, RustOrmSchema, RustRealtimeSchema, RustTemplatingSchema, RustWebFrameworkSchema, SearchSchema, ServerDeploySchema, StateManagementSchema, TestingSchema, UILibrarySchema, ValidationSchema, WebDeploySchema, analyzeStackCompatibility, formatStackPartSpec, getCategoryOrderForEcosystem, legacyProjectConfigToStackParts } from "@better-fullstack/types";
+import { AISchema, APISchema, AddonsSchema, AiDocsSchema, AnalyticsSchema, AnimationSchema, AstroIntegrationSchema, AuthSchema, BackendSchema, CATEGORY_ORDER, CMSSchema, CSSFrameworkSchema, CachingSchema, DatabaseSchema, DatabaseSetupSchema, DotnetApiSchema, DotnetAuthSchema, DotnetCachingSchema, DotnetDeploySchema, DotnetJobQueueSchema, DotnetObservabilitySchema, DotnetOrmSchema, DotnetRealtimeSchema, DotnetTestingSchema, DotnetValidationSchema, DotnetWebFrameworkSchema, EcosystemSchema, EffectSchema, ElixirApiSchema, ElixirAuthSchema, ElixirCachingSchema, ElixirDeploySchema, ElixirEmailSchema, ElixirHttpSchema, ElixirJobsSchema, ElixirJsonSchema, ElixirLibrariesSchema, ElixirObservabilitySchema, ElixirOrmSchema, ElixirQualitySchema, ElixirRealtimeSchema, ElixirTestingSchema, ElixirValidationSchema, ElixirWebFrameworkSchema, EmailSchema, ExamplesSchema, FeatureFlagsSchema, FileStorageSchema, FileUploadSchema, FormsSchema, FrontendSchema, GoApiSchema, GoAuthSchema, GoCachingSchema, GoCliSchema, GoConfigSchema, GoLoggingSchema, GoMessageQueueSchema, GoObservabilitySchema, GoOrmSchema, GoRealtimeSchema, GoTestingSchema, GoWebFrameworkSchema, I18nSchema, JavaApiSchema, JavaAuthSchema, JavaBuildToolSchema, JavaLibrariesSchema, JavaLoggingSchema, JavaOrmSchema, JavaTestingLibrariesSchema, JavaWebFrameworkSchema, JobQueueSchema, LoggingSchema, MobileDeepLinkingSchema, MobileNavigationSchema, MobileOTASchema, MobilePushSchema, MobileStorageSchema, MobileTestingSchema, MobileUISchema, OPTION_CATEGORY_METADATA, ORMSchema, ObservabilitySchema, PackageManagerSchema, PaymentsSchema, PythonAiSchema, PythonApiSchema, PythonAuthSchema, PythonCachingSchema, PythonCliSchema, PythonGraphqlSchema, PythonObservabilitySchema, PythonOrmSchema, PythonQualitySchema, PythonRealtimeSchema, PythonTaskQueueSchema, PythonTestingSchema, PythonValidationSchema, PythonWebFrameworkSchema, RateLimitSchema, RealtimeSchema, RuntimeSchema, RustApiSchema, RustAuthSchema, RustCachingSchema, RustCliSchema, RustErrorHandlingSchema, RustFrontendSchema, RustLibrariesSchema, RustLoggingSchema, RustMessageQueueSchema, RustObservabilitySchema, RustOrmSchema, RustRealtimeSchema, RustTemplatingSchema, RustWebFrameworkSchema, SearchSchema, ServerDeploySchema, StateManagementSchema, TEMPLATE_VALUES, TestingSchema, UILibrarySchema, ValidationSchema, VectorDbSchema, VersionChannelSchema, WebDeploySchema, analyzeStackCompatibility, evaluateCompatibility, formatStackPartSpec, getCategoryOrderForEcosystem, legacyProjectConfigToStackParts } from "@better-fullstack/types";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
@@ -56,7 +57,8 @@ function getGuidance() {
 			addons: "ARRAY of strings. Monorepo tools, code quality, desktop (tauri), browser extensions (wxt), etc.",
 			email: "String. TypeScript supports multiple providers; Rust, Python, Go, and Java currently support resend or none.",
 			observability: "String. TypeScript supports multiple providers; Rust, Python, Go, and Java currently support sentry or none.",
-			search: "String. TypeScript supports multiple providers; Rust, Python, Go, and Java currently support meilisearch or none."
+			search: "String. TypeScript supports multiple providers; Rust, Python, Go, and Java currently support meilisearch or none.",
+			vectorDb: "String. TypeScript-only vector database for AI embeddings: pgvector, qdrant, chroma, pinecone, or none. Each provider is a standalone service (pgvector connects to a dedicated Postgres+pgvector instance via PGVECTOR_DATABASE_URL). Requires a standalone backend (not convex/none)."
 		},
 		ambiguityRules: [
 			"If the user request leaves major stack choices unspecified, ASK the user before proceeding. Do not guess.",
@@ -245,6 +247,7 @@ const MCP_COMPATIBILITY_DEFAULTS = {
 	shadcnRadius: "default",
 	cms: "none",
 	search: "none",
+	vectorDb: "none",
 	fileStorage: "none",
 	mobileUI: "none",
 	mobileStorage: "none",
@@ -255,7 +258,7 @@ const MCP_COMPATIBILITY_DEFAULTS = {
 	versionChannel: "stable",
 	examples: [],
 	aiSdk: "none",
-	aiDocs: ["claude-md"],
+	aiDocs: ["claude-md", "agents-md"],
 	git: "true",
 	install: "false",
 	api: "none",
@@ -376,8 +379,6 @@ function buildProjectConfig(input, overrides) {
 		cssFramework: input.cssFramework ?? (ecosystem === "react-native" ? "none" : defaults.cssFramework),
 		mobileNavigation: input.mobileNavigation ?? (hasMobileProject ? "expo-router" : "none"),
 		mobileDeepLinking: input.mobileDeepLinking ?? (hasMobileProject ? "expo-linking" : "none"),
-		astroIntegration: "none",
-		versionChannel: "stable",
 		shadcnBase: "radix",
 		shadcnStyle: "nova",
 		shadcnIconLibrary: "lucide",
@@ -385,7 +386,7 @@ function buildProjectConfig(input, overrides) {
 		shadcnBaseColor: "neutral",
 		shadcnFont: "inter",
 		shadcnRadius: "default",
-		aiDocs: ["claude-md"],
+		aiDocs: input.aiDocs ?? ["claude-md", "agents-md"],
 		git: !!overrides,
 		install: false
 	};
@@ -565,6 +566,279 @@ const GETTING_STARTED_MD = `# Getting Started with Better-Fullstack MCP
 2. Provide addons array with features to add (e.g., ["biome", "turborepo"]).
 3. Service categories such as email and observability are scaffold-time options. To add those to an existing app, inspect the generated templates from bfs_plan_project and apply the equivalent dependency, env var, and initialization changes manually.
 `;
+const guidanceOutputSchema = {
+	workflow: z.array(z.string()),
+	ecosystems: z.record(z.string(), z.string()),
+	fieldRules: z.record(z.string(), z.string()),
+	ambiguityRules: z.array(z.string()),
+	criticalConstraints: z.array(z.string())
+};
+const schemaOutputSchema = {
+	category: z.string().optional(),
+	options: z.array(z.string()).optional(),
+	categories: z.record(z.string(), z.array(z.string())).optional(),
+	error: z.string().optional()
+};
+const compatibilityIssueOutputSchema = z.object({
+	code: z.string(),
+	message: z.string(),
+	category: z.string().optional(),
+	optionId: z.string().optional(),
+	provided: z.record(z.string(), z.union([z.string(), z.array(z.string())])).optional(),
+	suggestions: z.array(z.string()).optional()
+});
+const compatibilityOutputSchema = {
+	adjustedStack: z.record(z.string(), z.unknown()).nullable(),
+	changes: z.array(z.object({
+		category: z.string(),
+		message: z.string()
+	})),
+	issues: z.array(compatibilityIssueOutputSchema),
+	hasIssues: z.boolean()
+};
+const graphPreviewOutputShape = {
+	graphSummary: z.string().optional(),
+	effectiveStack: z.record(z.string(), z.string()).optional(),
+	stackPartSpecs: z.array(z.string()).optional()
+};
+const planProjectOutputSchema = {
+	success: z.boolean(),
+	fileCount: z.number().optional(),
+	directoryCount: z.number().optional(),
+	files: z.array(z.string()).optional(),
+	...graphPreviewOutputShape
+};
+const createProjectOutputSchema = {
+	success: z.boolean(),
+	projectDirectory: z.string().optional(),
+	fileCount: z.number().optional(),
+	addonWarnings: z.array(z.string()).optional(),
+	message: z.string().optional(),
+	...graphPreviewOutputShape
+};
+const planAdditionOutputSchema = {
+	success: z.boolean(),
+	existingConfig: z.object({
+		ecosystem: z.string(),
+		frontend: z.array(z.string()).optional(),
+		backend: z.string().optional(),
+		addons: z.array(z.string()).optional(),
+		graphSummary: z.string().optional(),
+		effectiveStack: z.record(z.string(), z.string()).optional(),
+		stackPartSpecs: z.array(z.string())
+	}).optional(),
+	proposedAdditions: z.object({
+		newAddons: z.array(z.string()),
+		webDeploy: z.string().nullable(),
+		serverDeploy: z.string().nullable(),
+		graphSummary: z.string().optional(),
+		effectiveStack: z.record(z.string(), z.string()).optional(),
+		stackPartSpecs: z.array(z.string())
+	}).optional(),
+	alreadyPresent: z.array(z.string()).optional(),
+	compatibilityWarnings: z.array(z.string()).optional()
+};
+const addFeatureOutputSchema = {
+	success: z.boolean(),
+	addedAddons: z.array(z.string()).optional(),
+	projectDir: z.string().optional(),
+	message: z.string().optional(),
+	...graphPreviewOutputShape
+};
+function buildPresetStackSummary(config) {
+	const parts = [];
+	const frontend = (config.frontend ?? []).filter((item) => item !== "none");
+	if (frontend.length > 0) parts.push(`frontend: ${frontend.join("+")}`);
+	if (config.backend && config.backend !== "none") parts.push(`backend: ${config.backend}`);
+	if (config.runtime && config.runtime !== "none") parts.push(`runtime: ${config.runtime}`);
+	if (config.database && config.database !== "none") parts.push(`database: ${config.database}`);
+	if (config.orm && config.orm !== "none") parts.push(`orm: ${config.orm}`);
+	if (config.api && config.api !== "none") parts.push(`api: ${config.api}`);
+	if (config.auth && config.auth !== "none") parts.push(`auth: ${config.auth}`);
+	if (config.payments && config.payments !== "none") parts.push(`payments: ${config.payments}`);
+	const addons = (config.addons ?? []).filter((item) => item !== "none");
+	if (addons.length > 0) parts.push(`addons: ${addons.join("+")}`);
+	return parts.join(", ");
+}
+function listMcpPresets() {
+	const presets = [];
+	for (const id of TEMPLATE_VALUES) {
+		if (id === "none") continue;
+		const config = getTemplateConfig(id);
+		if (!config) continue;
+		const ecosystem = (config.frontend ?? []).some((item) => item.startsWith("native-")) ? "react-native" : "typescript";
+		presets.push({
+			id,
+			name: id.toUpperCase(),
+			description: getTemplateDescription(id),
+			ecosystem,
+			stackSummary: buildPresetStackSummary(config),
+			stack: config
+		});
+	}
+	return presets;
+}
+function briefMatches(text, keywords) {
+	const tokens = new Set(text.split(/[^a-z0-9]+/i).filter(Boolean));
+	return keywords.some((keyword) => keyword.includes(" ") ? text.includes(keyword) : tokens.has(keyword));
+}
+function matchNearestPreset(input) {
+	const signatureKeys = [
+		"database",
+		"backend",
+		"api",
+		"auth"
+	];
+	const inputFrontend = input.frontend?.[0];
+	let best = null;
+	for (const id of TEMPLATE_VALUES) {
+		if (id === "none") continue;
+		const config = getTemplateConfig(id);
+		if (!config) continue;
+		let score = 0;
+		for (const key of signatureKeys) {
+			const value = config[key];
+			if (value !== void 0 && value === input[key]) score += 1;
+		}
+		const presetFrontend = (config.frontend ?? [])[0];
+		if (presetFrontend && presetFrontend === inputFrontend) score += 1;
+		if (!best || score > best.score) best = {
+			id,
+			score
+		};
+	}
+	return best && best.score >= 3 ? best.id : null;
+}
+function recommendStackFromBrief(brief, ecosystemHint) {
+	const text = brief.toLowerCase();
+	const has = (...keywords) => briefMatches(text, keywords);
+	const rationale = [];
+	const input = {};
+	if (ecosystemHint && ecosystemHint !== "typescript") {
+		input.ecosystem = ecosystemHint;
+		rationale.push(`Ecosystem forced to ${ecosystemHint} from the provided hint; using ${ecosystemHint} defaults.`);
+		rationale.push(`Brief keyword analysis (database/auth/payments/AI feature detection) currently applies to the TypeScript ecosystem only — configure those features explicitly for ${ecosystemHint} via bfs_check_compatibility.`);
+		return {
+			input,
+			rationale,
+			matchedPreset: null
+		};
+	}
+	if (has("mobile", "ios", "android", "expo") || text.includes("react native") || text.includes("react-native") || text.includes("app store") || text.includes("play store")) {
+		input.ecosystem = "react-native";
+		input.frontend = ["native-uniwind"];
+		input.backend = "none";
+		input.runtime = "none";
+		input.api = "none";
+		input.database = "none";
+		input.orm = "none";
+		rationale.push("Mobile app detected: React Native (Expo) with the native-uniwind styling preset and no bundled backend.");
+		return {
+			input,
+			rationale,
+			matchedPreset: "uniwind"
+		};
+	}
+	input.ecosystem = "typescript";
+	input.frontend = ["tanstack-router"];
+	input.backend = "hono";
+	input.runtime = "bun";
+	input.database = "sqlite";
+	input.orm = "drizzle";
+	input.api = "trpc";
+	rationale.push("Default TypeScript fullstack baseline: TanStack Router + Hono + tRPC on SQLite/Drizzle (Bun).");
+	if (has("postgres", "postgresql", "supabase", "neon")) {
+		input.database = "postgres";
+		input.orm = "drizzle";
+		rationale.push("Postgres requested: database=postgres, orm=drizzle.");
+	} else if (has("mysql", "planetscale")) {
+		input.database = "mysql";
+		input.orm = "drizzle";
+		rationale.push("MySQL requested: database=mysql, orm=drizzle.");
+	} else if (has("mongo", "mongodb")) {
+		input.database = "mongodb";
+		input.orm = "mongoose";
+		rationale.push("MongoDB requested: database=mongodb, orm=mongoose.");
+	}
+	if (has("saas", "payment", "payments", "billing", "subscription", "subscriptions", "checkout", "stripe", "ecommerce")) {
+		input.payments = "stripe";
+		input.auth = "better-auth";
+		if (input.database === "sqlite") {
+			input.database = "postgres";
+			input.orm = "drizzle";
+		}
+		rationale.push("SaaS/payments detected: Stripe + better-auth, upgraded to Postgres/Drizzle for production data.");
+	} else if (has("auth", "login", "signin", "signup", "account", "accounts", "user", "users", "authentication", "admin", "dashboard", "portal", "members", "rbac", "permissions", "roles")) {
+		input.auth = "better-auth";
+		rationale.push("Authentication requested: auth=better-auth.");
+	}
+	if (has("ai", "chatbot", "llm", "gpt", "rag", "agent", "agents", "openai", "assistant", "copilot")) {
+		input.ai = "vercel-ai";
+		input.examples = ["ai"];
+		rationale.push("AI/chatbot detected: Vercel AI SDK with the bundled AI example.");
+	}
+	if (has("blog", "content", "cms", "marketing", "landing", "publishing")) {
+		input.cms = "sanity";
+		rationale.push("Content/marketing site detected: Sanity CMS.");
+	}
+	if (has("realtime", "collaborative", "collaboration", "multiplayer", "presence") || text.includes("real-time") || text.includes("real time")) {
+		input.realtime = "socket-io";
+		rationale.push("Realtime/collaboration detected: Socket.IO.");
+	}
+	let matchedPreset = null;
+	if (has("t3")) matchedPreset = "t3";
+	else if (has("mern")) matchedPreset = "mern";
+	else if (has("pern")) matchedPreset = "pern";
+	else matchedPreset = matchNearestPreset(input);
+	if (matchedPreset) rationale.push(`Closest ready-made preset: ${matchedPreset}.`);
+	return {
+		input,
+		rationale,
+		matchedPreset
+	};
+}
+function normalizeAdjustedToInput(adjusted, base) {
+	const webFrontend = adjusted.webFrontend ?? [];
+	const nativeFrontend = adjusted.nativeFrontend ?? [];
+	const frontend = [...webFrontend, ...nativeFrontend];
+	const codeQuality = adjusted.codeQuality ?? [];
+	const documentation = adjusted.documentation ?? [];
+	const appPlatforms = adjusted.appPlatforms ?? [];
+	return {
+		...adjusted,
+		projectName: base.projectName,
+		ecosystem: adjusted.ecosystem ?? base.ecosystem,
+		frontend: frontend.length > 0 ? frontend : base.frontend,
+		addons: [
+			...codeQuality,
+			...documentation,
+			...appPlatforms
+		],
+		ai: adjusted.aiSdk ?? base.ai
+	};
+}
+function summarizeRecommendedConfig(config) {
+	const isTsWeb = config.ecosystem === "typescript" || config.ecosystem === "react-native";
+	return {
+		projectName: config.projectName,
+		ecosystem: config.ecosystem,
+		...isTsWeb ? {
+			frontend: config.frontend,
+			backend: config.backend,
+			runtime: config.runtime,
+			api: config.api
+		} : {},
+		database: config.database,
+		orm: config.orm,
+		auth: config.auth,
+		payments: config.payments,
+		ai: config.ai,
+		cms: config.cms,
+		realtime: config.realtime,
+		examples: config.examples,
+		addons: config.addons
+	};
+}
 async function startMcpServer() {
 	const server = new McpServer({
 		name: "better-fullstack",
@@ -573,24 +847,120 @@ async function startMcpServer() {
 		instructions: INSTRUCTIONS,
 		capabilities: { logging: {} }
 	});
-	const registerTool = server.tool.bind(server);
-	registerTool("bfs_get_guidance", "Returns workflow rules, field semantics, ambiguity rules, and critical constraints. Call this FIRST before using other tools.", mcpInputSchema({}), async () => {
+	const registerTool = (name, config, cb) => {
+		server.registerTool(name, config, cb);
+	};
+	registerTool("bfs_get_guidance", {
+		description: "Returns workflow rules, field semantics, ambiguity rules, and critical constraints. Call this FIRST before using other tools.",
+		inputSchema: mcpInputSchema({}),
+		outputSchema: guidanceOutputSchema,
+		annotations: {
+			title: "Get guidance",
+			readOnlyHint: true,
+			idempotentHint: true,
+			openWorldHint: false
+		}
+	}, async () => {
 		const guidance = getGuidance();
-		return { content: [{
-			type: "text",
-			text: JSON.stringify(guidance, null, 2)
-		}] };
+		return {
+			content: [{
+				type: "text",
+				text: JSON.stringify(guidance, null, 2)
+			}],
+			structuredContent: guidance
+		};
 	});
-	registerTool("bfs_get_schema", "Returns valid options for a specific category (e.g., 'database', 'frontend', 'backend') or ALL categories. Use ecosystem to filter to relevant categories only.", mcpInputSchema({
-		category: z.string().optional().describe("Category name (e.g., 'database', 'orm', 'frontend'). Omit for all categories."),
-		ecosystem: EcosystemSchema.optional().describe("Filter categories to this ecosystem (e.g., 'rust' returns only Rust + shared categories).")
-	}), async ({ category, ecosystem }) => {
+	registerTool("bfs_get_schema", {
+		description: "Returns valid options for a specific category (e.g., 'database', 'frontend', 'backend') or ALL categories. Use ecosystem to filter to relevant categories only.",
+		inputSchema: mcpInputSchema({
+			category: z.string().optional().describe("Category name (e.g., 'database', 'orm', 'frontend'). Omit for all categories."),
+			ecosystem: EcosystemSchema.optional().describe("Filter categories to this ecosystem (e.g., 'rust' returns only Rust + shared categories).")
+		}),
+		outputSchema: schemaOutputSchema,
+		annotations: {
+			title: "Get schema options",
+			readOnlyHint: true,
+			idempotentHint: true,
+			openWorldHint: false
+		}
+	}, async ({ category, ecosystem }) => {
 		const result = getSchemaOptions(category, ecosystem);
+		const structuredContent = "error" in result ? { error: result.error } : "category" in result ? {
+			category: result.category,
+			options: result.options
+		} : { categories: result };
+		return {
+			content: [{
+				type: "text",
+				text: JSON.stringify(result, null, 2)
+			}],
+			structuredContent
+		};
+	});
+	registerTool("bfs_list_presets", {
+		description: "Lists the ready-made stack presets available to the CLI (mern, pern, t3, uniwind) with id, name, description, ecosystem, and a stack summary. Use to discover a starting point before bfs_recommend_stack, bfs_plan_project, or bfs_create_project.",
+		inputSchema: mcpInputSchema({}),
+		annotations: {
+			title: "List presets",
+			readOnlyHint: true,
+			idempotentHint: true,
+			openWorldHint: false
+		}
+	}, async () => {
+		const presets = listMcpPresets();
 		return { content: [{
 			type: "text",
-			text: JSON.stringify(result, null, 2)
+			text: JSON.stringify({ presets }, null, 2)
 		}] };
 	});
+	registerTool("bfs_recommend_stack", {
+		description: "Recommends a compatibility-validated stack from a natural-language brief using deterministic keyword rules (no LLM). Returns the config, rationale, any auto-applied compatibility adjustments, the nearest matching preset, and a reproducible CLI command.",
+		inputSchema: mcpInputSchema({
+			brief: z.string().describe("Natural-language description of the app to build (e.g., 'a SaaS with payments and auth')."),
+			ecosystem: EcosystemSchema.optional().describe("Force a language ecosystem. Omit to let the brief decide (defaults to TypeScript)."),
+			projectName: z.string().optional().describe("Project name (kebab-case). Default: 'my-app'.")
+		}),
+		annotations: {
+			title: "Recommend stack",
+			readOnlyHint: true,
+			idempotentHint: false,
+			openWorldHint: false
+		}
+	}, async ({ brief, ecosystem, projectName }) => {
+		try {
+			const { input: recommended, rationale, matchedPreset } = recommendStackFromBrief(brief, ecosystem);
+			const baseInput = {
+				projectName: projectName ?? "my-app",
+				...recommended
+			};
+			const compatResult = analyzeStackCompatibility(buildCompatibilityInput(baseInput));
+			const finalConfig = buildProjectConfig(compatResult.adjustedStack ? normalizeAdjustedToInput(compatResult.adjustedStack, baseInput) : baseInput, { projectDir: `/${baseInput.projectName}` });
+			const adjustments = compatResult.changes.map((change) => `${change.category}: ${change.message}`);
+			const graphPreview = getMcpGraphPreview(finalConfig);
+			const reproducibleCommand = generateReproducibleCommand(finalConfig);
+			return { content: [{
+				type: "text",
+				text: JSON.stringify({
+					brief,
+					config: summarizeRecommendedConfig(finalConfig),
+					rationale,
+					adjustments,
+					matchedPreset,
+					reproducibleCommand,
+					...graphPreview,
+					nextSteps: "Call bfs_plan_project with this config to preview the files, then bfs_create_project to scaffold it."
+				}, null, 2)
+			}] };
+		} catch (error) {
+			return {
+				content: [{
+					type: "text",
+					text: `Recommend stack failed: ${error instanceof Error ? error.message : String(error)}`
+				}],
+				isError: true
+			};
+		}
+	});
 	const mobileInputSchema = {
 		mobileNavigation: MobileNavigationSchema.optional().describe("Mobile navigation"),
 		mobileUI: MobileUISchema.optional().describe("Mobile UI"),
@@ -682,52 +1052,80 @@ async function startMcpServer() {
 		elixirDeploy: ElixirDeploySchema.optional().describe("Elixir deployment target"),
 		elixirLibraries: z.array(ElixirLibrariesSchema).optional().describe("Elixir libraries")
 	};
-	registerTool("bfs_check_compatibility", "Validates a stack combination and returns auto-adjusted selections with warnings. Call BEFORE creating a project to avoid invalid combinations.", mcpInputSchema({
-		ecosystem: EcosystemSchema.describe("Language ecosystem"),
-		frontend: z.array(z.string()).optional().describe("Web frontend frameworks (TypeScript only)"),
-		backend: z.string().optional().describe("Backend framework"),
-		runtime: z.string().optional().describe("JavaScript runtime"),
-		database: z.string().optional().describe("Database type"),
-		orm: z.string().optional().describe("ORM"),
-		api: z.string().optional().describe("API layer"),
-		auth: z.string().optional().describe("Auth provider"),
-		payments: z.string().optional().describe("Payments provider"),
-		email: EmailSchema.optional().describe("Email provider"),
-		fileUpload: FileUploadSchema.optional().describe("File upload provider"),
-		ai: AISchema.optional().describe("AI SDK"),
-		stateManagement: StateManagementSchema.optional().describe("State management"),
-		forms: FormsSchema.optional().describe("Forms library"),
-		validation: ValidationSchema.optional().describe("Validation library"),
-		testing: TestingSchema.optional().describe("Testing framework"),
-		realtime: RealtimeSchema.optional().describe("Realtime library"),
-		jobQueue: JobQueueSchema.optional().describe("Job queue"),
-		animation: AnimationSchema.optional().describe("Animation library"),
-		logging: LoggingSchema.optional().describe("Logging library"),
-		observability: ObservabilitySchema.optional().describe("Observability provider"),
-		featureFlags: FeatureFlagsSchema.optional().describe("Feature flags provider"),
-		analytics: AnalyticsSchema.optional().describe("Analytics provider"),
-		cms: CMSSchema.optional().describe("CMS"),
-		caching: CachingSchema.optional().describe("Caching solution"),
-		rateLimit: RateLimitSchema.optional().describe("Rate limiting solution"),
-		i18n: I18nSchema.optional().describe("Internationalization library"),
-		search: SearchSchema.optional().describe("Search engine"),
-		fileStorage: FileStorageSchema.optional().describe("File storage"),
-		...mobileInputSchema,
-		...deploymentInputSchema,
-		astroIntegration: AstroIntegrationSchema.optional().describe("Astro UI framework integration"),
-		uiLibrary: z.string().optional().describe("UI component library"),
-		cssFramework: z.string().optional().describe("CSS framework"),
-		addons: z.array(AddonsSchema).optional().describe("Addon list"),
-		examples: z.array(ExamplesSchema).optional().describe("Example templates"),
-		packageManager: PackageManagerSchema.optional().describe("Package manager"),
-		...crossEcosystemInputSchema
-	}), async (input) => {
+	registerTool("bfs_check_compatibility", {
+		description: "Validates a stack combination and returns auto-adjusted selections with warnings. Call BEFORE creating a project to avoid invalid combinations.",
+		outputSchema: compatibilityOutputSchema,
+		annotations: {
+			title: "Check stack compatibility",
+			readOnlyHint: true,
+			idempotentHint: true,
+			openWorldHint: false
+		},
+		inputSchema: mcpInputSchema({
+			ecosystem: EcosystemSchema.describe("Language ecosystem"),
+			frontend: z.array(z.string()).optional().describe("Web frontend frameworks (TypeScript only)"),
+			backend: z.string().optional().describe("Backend framework"),
+			runtime: z.string().optional().describe("JavaScript runtime"),
+			database: z.string().optional().describe("Database type"),
+			orm: z.string().optional().describe("ORM"),
+			api: z.string().optional().describe("API layer"),
+			auth: z.string().optional().describe("Auth provider"),
+			payments: z.string().optional().describe("Payments provider"),
+			email: EmailSchema.optional().describe("Email provider"),
+			fileUpload: FileUploadSchema.optional().describe("File upload provider"),
+			ai: AISchema.optional().describe("AI SDK"),
+			stateManagement: StateManagementSchema.optional().describe("State management"),
+			forms: FormsSchema.optional().describe("Forms library"),
+			validation: ValidationSchema.optional().describe("Validation library"),
+			testing: TestingSchema.optional().describe("Testing framework"),
+			realtime: RealtimeSchema.optional().describe("Realtime library"),
+			jobQueue: JobQueueSchema.optional().describe("Job queue"),
+			animation: AnimationSchema.optional().describe("Animation library"),
+			logging: LoggingSchema.optional().describe("Logging library"),
+			observability: ObservabilitySchema.optional().describe("Observability provider"),
+			featureFlags: FeatureFlagsSchema.optional().describe("Feature flags provider"),
+			analytics: AnalyticsSchema.optional().describe("Analytics provider"),
+			cms: CMSSchema.optional().describe("CMS"),
+			caching: CachingSchema.optional().describe("Caching solution"),
+			rateLimit: RateLimitSchema.optional().describe("Rate limiting solution"),
+			i18n: I18nSchema.optional().describe("Internationalization library"),
+			search: SearchSchema.optional().describe("Search engine"),
+			vectorDb: VectorDbSchema.optional().describe("Vector database (TypeScript only)"),
+			fileStorage: FileStorageSchema.optional().describe("File storage"),
+			...mobileInputSchema,
+			...deploymentInputSchema,
+			astroIntegration: AstroIntegrationSchema.optional().describe("Astro UI framework integration"),
+			uiLibrary: z.string().optional().describe("UI component library"),
+			cssFramework: z.string().optional().describe("CSS framework"),
+			addons: z.array(AddonsSchema).optional().describe("Addon list"),
+			examples: z.array(ExamplesSchema).optional().describe("Example templates"),
+			packageManager: PackageManagerSchema.optional().describe("Package manager"),
+			...crossEcosystemInputSchema
+		})
+	}, async (input) => {
 		try {
-			const filtered = filterCompatibilityResult(analyzeStackCompatibility(buildCompatibilityInput(input)), input.ecosystem);
-			return { content: [{
-				type: "text",
-				text: JSON.stringify(filtered, null, 2)
-			}] };
+			const compatInput = buildCompatibilityInput(input);
+			const filtered = filterCompatibilityResult(analyzeStackCompatibility(compatInput), input.ecosystem);
+			const evaluation = evaluateCompatibility(compatInput);
+			const relevantEcosystem = isMcpEcosystem(input.ecosystem) ? input.ecosystem : "typescript";
+			const relevantIssueKeys = new Set([...getMcpCategoryKeysForEcosystem(relevantEcosystem), ...MCP_SHARED_COMPATIBILITY_KEYS]);
+			const issues = evaluation.issues.filter((issue) => !issue.category || relevantIssueKeys.has(issue.category));
+			const structuredContent = {
+				adjustedStack: filtered.adjustedStack,
+				changes: filtered.changes,
+				issues,
+				hasIssues: issues.length > 0
+			};
+			return {
+				content: [{
+					type: "text",
+					text: JSON.stringify({
+						...filtered,
+						issues
+					}, null, 2)
+				}],
+				structuredContent
+			};
 		} catch (error) {
 			return {
 				content: [{
@@ -767,6 +1165,7 @@ async function startMcpServer() {
 		observability: ObservabilitySchema.optional().describe("Observability"),
 		featureFlags: FeatureFlagsSchema.optional().describe("Feature flag provider"),
 		search: SearchSchema.optional().describe("Search engine"),
+		vectorDb: VectorDbSchema.optional().describe("Vector database (TypeScript only)"),
 		caching: CachingSchema.optional().describe("Caching solution"),
 		rateLimit: RateLimitSchema.optional().describe("Rate limiting solution"),
 		i18n: I18nSchema.optional().describe("Internationalization (i18n) library"),
@@ -775,9 +1174,24 @@ async function startMcpServer() {
 		...mobileInputSchema,
 		fileUpload: FileUploadSchema.optional().describe("File upload"),
 		...deploymentInputSchema,
+		effect: EffectSchema.optional().describe("Effect ecosystem (effect, effect-full)"),
+		analytics: AnalyticsSchema.optional().describe("Privacy-focused analytics provider"),
+		astroIntegration: AstroIntegrationSchema.optional().describe("Astro UI framework integration (react, vue, svelte, solid)"),
+		aiDocs: z.array(AiDocsSchema).optional().describe("AI documentation files (claude-md, agents-md, cursorrules)"),
+		versionChannel: VersionChannelSchema.optional().describe("Dependency version channel (stable, latest, beta)"),
 		...crossEcosystemInputSchema
 	};
-	registerTool("bfs_plan_project", "Dry-run: generates a project in-memory and returns the file tree WITHOUT writing to disk. Use this to preview what would be created.", mcpInputSchema(planCreateSchema), async (input) => {
+	registerTool("bfs_plan_project", {
+		description: "Dry-run: generates a project in-memory and returns the file tree WITHOUT writing to disk. Use this to preview what would be created.",
+		inputSchema: mcpInputSchema(planCreateSchema),
+		outputSchema: planProjectOutputSchema,
+		annotations: {
+			title: "Plan project (dry run)",
+			readOnlyHint: true,
+			idempotentHint: true,
+			openWorldHint: false
+		}
+	}, async (input) => {
 		try {
 			const { generateVirtualProject, EMBEDDED_TEMPLATES } = await import("@better-fullstack/template-generator");
 			const config = buildProjectConfig(input);
@@ -788,14 +1202,18 @@ async function startMcpServer() {
 			if (result.success && result.tree) {
 				const summary = summarizeTree(result.tree);
 				const graphPreview = getMcpGraphPreview(config);
-				return { content: [{
-					type: "text",
-					text: JSON.stringify({
-						success: true,
-						...summary,
-						...graphPreview
-					}, null, 2)
-				}] };
+				const payload = {
+					success: true,
+					...summary,
+					...graphPreview
+				};
+				return {
+					content: [{
+						type: "text",
+						text: JSON.stringify(payload, null, 2)
+					}],
+					structuredContent: payload
+				};
 			}
 			return {
 				content: [{
@@ -817,16 +1235,29 @@ async function startMcpServer() {
 			};
 		}
 	});
-	registerTool("bfs_create_project", "Creates a new fullstack project on disk. Dependencies are NOT installed (agent must tell user to install manually). Call bfs_plan_project first to preview.", mcpInputSchema({
-		...planCreateSchema,
-		projectName: z.string().describe("Project name (kebab-case). Will be the directory name.")
-	}), async (input) => {
+	registerTool("bfs_create_project", {
+		description: "Creates a new fullstack project on disk. Dependencies are NOT installed (agent must tell user to install manually). Call bfs_plan_project first to preview.",
+		inputSchema: mcpInputSchema({
+			...planCreateSchema,
+			projectName: z.string().describe("Project name (kebab-case). Will be the directory name."),
+			targetDir: z.string().optional().describe("Absolute path to the parent directory in which to create the project folder (default: current working directory).")
+		}),
+		outputSchema: createProjectOutputSchema,
+		annotations: {
+			title: "Create project",
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: false,
+			openWorldHint: false
+		}
+	}, async (input) => {
 		try {
 			const { generateVirtualProject, EMBEDDED_TEMPLATES } = await import("@better-fullstack/template-generator");
 			const { writeTreeToFilesystem } = await import("@better-fullstack/template-generator/fs-writer");
 			const path = await import("node:path");
 			const projectName = sanitizePath(input.projectName);
-			const projectDir = path.resolve(process.cwd(), projectName);
+			const targetDir = input.targetDir ? sanitizePath(input.targetDir) : void 0;
+			const projectDir = path.resolve(targetDir ?? process.cwd(), projectName);
 			const config = buildProjectConfig(input, { projectDir });
 			await (await import("node:fs/promises")).mkdir(projectDir, { recursive: true });
 			const result = await generateVirtualProject({
@@ -848,21 +1279,25 @@ async function startMcpServer() {
 			const graphPreview = getMcpGraphPreview(config);
 			let addonWarnings = [];
 			if (config.addons.length > 0 && config.addons[0] !== "none") {
-				const { setupAddons } = await import("./addons-setup-CV5uZyhH.mjs");
+				const { setupAddons } = await import("./addons-setup-CSmj5ClW.mjs");
 				addonWarnings = await setupAddons(config);
 			}
 			const installCmd = getInstallCommand(input.ecosystem ?? "typescript", projectName, input.packageManager, input.javaBuildTool, input.javaWebFramework);
-			return { content: [{
-				type: "text",
-				text: JSON.stringify({
-					success: true,
-					projectDirectory: projectDir,
-					fileCount: result.tree.fileCount,
-					...graphPreview,
-					...addonWarnings.length > 0 ? { addonWarnings } : {},
-					message: `Project created at ${projectDir}. Tell the user to run: ${installCmd}`
-				}, null, 2)
-			}] };
+			const payload = {
+				success: true,
+				projectDirectory: projectDir,
+				fileCount: result.tree.fileCount,
+				...graphPreview,
+				...addonWarnings.length > 0 ? { addonWarnings } : {},
+				message: `Project created at ${projectDir}. Tell the user to run: ${installCmd}`
+			};
+			return {
+				content: [{
+					type: "text",
+					text: JSON.stringify(payload, null, 2)
+				}],
+				structuredContent: payload
+			};
 		} catch (error) {
 			return {
 				content: [{
@@ -873,12 +1308,22 @@ async function startMcpServer() {
 			};
 		}
 	});
-	registerTool("bfs_plan_addition", "Validates what would be added to an existing project. Reads the project config (bts.jsonc) and checks which addons are new.", mcpInputSchema({
-		projectDir: z.string().describe("Absolute path to the existing project directory"),
-		addons: z.array(AddonsSchema).optional().describe("Addons to add"),
-		webDeploy: WebDeploySchema.optional().describe("Web deployment option"),
-		serverDeploy: ServerDeploySchema.optional().describe("Server deployment option")
-	}), async ({ projectDir, addons, webDeploy, serverDeploy }) => {
+	registerTool("bfs_plan_addition", {
+		description: "Validates what would be added to an existing project. Reads the project config (bts.jsonc) and checks which addons are new.",
+		inputSchema: mcpInputSchema({
+			projectDir: z.string().describe("Absolute path to the existing project directory"),
+			addons: z.array(AddonsSchema).optional().describe("Addons to add"),
+			webDeploy: WebDeploySchema.optional().describe("Web deployment option"),
+			serverDeploy: ServerDeploySchema.optional().describe("Server deployment option")
+		}),
+		outputSchema: planAdditionOutputSchema,
+		annotations: {
+			title: "Plan feature addition",
+			readOnlyHint: true,
+			idempotentHint: true,
+			openWorldHint: false
+		}
+	}, async ({ projectDir, addons, webDeploy, serverDeploy }) => {
 		try {
 			const safePath = sanitizePath(projectDir);
 			const config = await readBtsConfig(safePath);
@@ -909,31 +1354,35 @@ async function startMcpServer() {
 				serverDeploy: serverDeploy ?? config.serverDeploy
 			}));
 			const compatibilityWarnings = compatResult.changes.length > 0 ? compatResult.changes.map((c) => c.message) : void 0;
-			return { content: [{
-				type: "text",
-				text: JSON.stringify({
-					success: true,
-					existingConfig: {
-						ecosystem: config.ecosystem,
-						frontend: config.frontend,
-						backend: config.backend,
-						addons: config.addons,
-						graphSummary: existingGraphPreview.graphSummary,
-						effectiveStack: existingGraphPreview.effectiveStack,
-						stackPartSpecs: existingGraphPreview.stackPartSpecs
-					},
-					proposedAdditions: {
-						newAddons,
-						webDeploy: webDeploy ?? null,
-						serverDeploy: serverDeploy ?? null,
-						graphSummary: proposedGraphPreview.graphSummary,
-						effectiveStack: proposedGraphPreview.effectiveStack,
-						stackPartSpecs: proposedGraphPreview.stackPartSpecs
-					},
-					alreadyPresent: (addons ?? []).filter((a) => existingAddons.has(a)),
-					...compatibilityWarnings ? { compatibilityWarnings } : {}
-				}, null, 2)
-			}] };
+			const payload = {
+				success: true,
+				existingConfig: {
+					ecosystem: config.ecosystem,
+					frontend: config.frontend,
+					backend: config.backend,
+					addons: config.addons,
+					graphSummary: existingGraphPreview.graphSummary,
+					effectiveStack: existingGraphPreview.effectiveStack,
+					stackPartSpecs: existingGraphPreview.stackPartSpecs
+				},
+				proposedAdditions: {
+					newAddons,
+					webDeploy: webDeploy ?? null,
+					serverDeploy: serverDeploy ?? null,
+					graphSummary: proposedGraphPreview.graphSummary,
+					effectiveStack: proposedGraphPreview.effectiveStack,
+					stackPartSpecs: proposedGraphPreview.stackPartSpecs
+				},
+				alreadyPresent: (addons ?? []).filter((a) => existingAddons.has(a)),
+				...compatibilityWarnings ? { compatibilityWarnings } : {}
+			};
+			return {
+				content: [{
+					type: "text",
+					text: JSON.stringify(payload, null, 2)
+				}],
+				structuredContent: payload
+			};
 		} catch (error) {
 			return {
 				content: [{
@@ -944,13 +1393,24 @@ async function startMcpServer() {
 			};
 		}
 	});
-	registerTool("bfs_add_feature", "Adds addons/features to an existing Better-Fullstack project. Dependencies are NOT installed. Call bfs_plan_addition first to validate.", mcpInputSchema({
-		projectDir: z.string().describe("Absolute path to the existing project directory"),
-		addons: z.array(AddonsSchema).optional().describe("Addons to add"),
-		webDeploy: WebDeploySchema.optional().describe("Web deployment option"),
-		serverDeploy: ServerDeploySchema.optional().describe("Server deployment option"),
-		packageManager: PackageManagerSchema.optional().describe("Package manager to use")
-	}), async (input) => {
+	registerTool("bfs_add_feature", {
+		description: "Adds addons/features to an existing Better-Fullstack project. Dependencies are NOT installed. Call bfs_plan_addition first to validate.",
+		inputSchema: mcpInputSchema({
+			projectDir: z.string().describe("Absolute path to the existing project directory"),
+			addons: z.array(AddonsSchema).optional().describe("Addons to add"),
+			webDeploy: WebDeploySchema.optional().describe("Web deployment option"),
+			serverDeploy: ServerDeploySchema.optional().describe("Server deployment option"),
+			packageManager: PackageManagerSchema.optional().describe("Package manager to use")
+		}),
+		outputSchema: addFeatureOutputSchema,
+		annotations: {
+			title: "Add feature",
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: false,
+			openWorldHint: false
+		}
+	}, async (input) => {
 		try {
 			const safePath = sanitizePath(input.projectDir);
 			const { add } = await import("./index.mjs");
@@ -966,16 +1426,20 @@ async function startMcpServer() {
 				const existingConfig = await readBtsConfig(safePath);
 				const graphPreview = existingConfig ? getMcpGraphPreview(existingConfig) : void 0;
 				const installCmd = getInstallCommand(existingConfig?.ecosystem ?? "typescript", safePath.split("/").pop() ?? "project", input.packageManager, existingConfig?.javaBuildTool, existingConfig?.javaWebFramework);
-				return { content: [{
-					type: "text",
-					text: JSON.stringify({
-						success: true,
-						addedAddons: result.addedAddons,
-						projectDir: result.projectDir,
-						...graphPreview,
-						message: `Added ${result.addedAddons.join(", ")} to project. Tell the user to run: ${installCmd}`
-					}, null, 2)
-				}] };
+				const payload = {
+					success: true,
+					addedAddons: result.addedAddons,
+					projectDir: result.projectDir,
+					...graphPreview,
+					message: `Added ${result.addedAddons.join(", ")} to project. Tell the user to run: ${installCmd}`
+				};
+				return {
+					content: [{
+						type: "text",
+						text: JSON.stringify(payload, null, 2)
+					}],
+					structuredContent: payload
+				};
 			}
 			return {
 				content: [{