@vizejs/musea-mcp-server 0.61.0 → 0.63.0

package/dist/src-Cp5GZpzj.mjs

@@ -0,0 +1,1840 @@
+import { createRequire } from "node:module";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ErrorCode, ListResourcesRequestSchema, ListToolsRequestSchema, McpError, ReadResourceRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import fs from "node:fs";
+import path from "node:path";
+//#region src/native.ts
+let native = null;
+function loadNative() {
+	if (native) return native;
+	const require = createRequire(import.meta.url);
+	try {
+		native = require("@vizejs/native");
+		return native;
+	} catch (e) {
+		throw new Error(`Failed to load @vizejs/native. Make sure it's installed: ${String(e)}`);
+	}
+}
+//#endregion
+//#region src/scanner.ts
+async function findArtFiles(root, include, exclude) {
+	const files = [];
+	async function scan(dir) {
+		const entries = await fs.promises.readdir(dir, { withFileTypes: true });
+		for (const entry of entries) {
+			const fullPath = path.join(dir, entry.name);
+			const relative = path.relative(root, fullPath);
+			let excluded = false;
+			for (const pattern of exclude) if (matchGlob(relative, pattern) || matchGlob(entry.name, pattern)) {
+				excluded = true;
+				break;
+			}
+			if (excluded) continue;
+			if (entry.isDirectory()) await scan(fullPath);
+			else if (entry.isFile() && entry.name.endsWith(".art.vue")) {
+				for (const pattern of include) if (matchGlob(relative, pattern)) {
+					files.push(fullPath);
+					break;
+				}
+			}
+		}
+	}
+	await scan(root);
+	return files;
+}
+function matchGlob(filepath, pattern) {
+	const regex = pattern.replace(/\*\*/g, "{{DOUBLE_STAR}}").replace(/\*/g, "[^/]*").replace(/{{DOUBLE_STAR}}/g, ".*").replace(/\./g, "\\.");
+	return new RegExp(`^${regex}$`).test(filepath);
+}
+//#endregion
+//#region src/tools/definitions.ts
+/**
+* MCP tool definitions for Musea.
+*
+* Declares the schema (name, description, input parameters) for each tool
+* exposed by the MCP server: component analysis, registry, code generation,
+* documentation, and design tokens.
+*/
+const toolDefinitions = [
+	{
+		name: "analyze_component",
+		description: "Statically analyze a Vue SFC to extract its props and emits. Accepts a Vue component path directly, or an art-file reference that resolves to the linked component source.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				path: {
+					type: "string",
+					description: "Path to the .vue component file or .art.vue file (relative to project root)"
+				},
+				title: {
+					type: "string",
+					description: "Resolve an art file by its display title, then analyze its component source"
+				},
+				component: {
+					type: "string",
+					description: "Resolve an art file by its component reference or component basename, then analyze it"
+				},
+				query: {
+					type: "string",
+					description: "Fuzzy-search an art file, then analyze the linked component source"
+				},
+				ref: {
+					type: "string",
+					description: "Generic art-file reference: path, title, component name, or search text"
+				}
+			},
+			required: []
+		}
+	},
+	{
+		name: "get_palette",
+		description: "Derive an interactive props palette (control types, defaults, ranges, options) for a component described by an Art file. Falls back to SFC analysis when native palette inference is sparse.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				path: {
+					type: "string",
+					description: "Path to the .art.vue file (relative to project root)"
+				},
+				title: {
+					type: "string",
+					description: "Resolve an art file by title instead of path"
+				},
+				component: {
+					type: "string",
+					description: "Resolve an art file by component reference or component basename"
+				},
+				query: {
+					type: "string",
+					description: "Fuzzy-search an art file before generating the palette"
+				},
+				ref: {
+					type: "string",
+					description: "Generic art-file reference: path, title, component name, or search text"
+				}
+			},
+			required: []
+		}
+	},
+	{
+		name: "list_components",
+		description: "List components registered in the design system. Returns titles, categories, tags, status, variant names, and related resource URIs.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				category: {
+					type: "string",
+					description: "Filter by category"
+				},
+				tag: {
+					type: "string",
+					description: "Filter by tag"
+				},
+				status: {
+					type: "string",
+					enum: [
+						"draft",
+						"ready",
+						"deprecated"
+					],
+					description: "Filter by status badge"
+				},
+				component: {
+					type: "string",
+					description: "Filter by component reference or component basename"
+				},
+				limit: {
+					type: "number",
+					description: "Maximum number of components to return (default: all)"
+				},
+				includeVariants: {
+					type: "boolean",
+					description: "Include per-variant metadata in the result (default: false)"
+				},
+				sortBy: {
+					type: "string",
+					enum: [
+						"title",
+						"category",
+						"status",
+						"variants"
+					],
+					description: "Sort order for the result list (default: title)"
+				}
+			}
+		}
+	},
+	{
+		name: "get_component",
+		description: "Get full details of a design-system component: metadata, variants, source-component analysis, palette data, documentation, and related resource URIs.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				path: {
+					type: "string",
+					description: "Path to the .art.vue file (relative to project root)"
+				},
+				title: {
+					type: "string",
+					description: "Resolve an art file by display title instead of path"
+				},
+				component: {
+					type: "string",
+					description: "Resolve an art file by component reference or component basename"
+				},
+				query: {
+					type: "string",
+					description: "Fuzzy-search an art file before loading details"
+				},
+				ref: {
+					type: "string",
+					description: "Generic art-file reference: path, title, component name, or search text"
+				},
+				includeAnalysis: {
+					type: "boolean",
+					description: "Include resolved component props/emits analysis (default: true)"
+				},
+				includePalette: {
+					type: "boolean",
+					description: "Include inferred palette data (default: true)"
+				},
+				includeDocumentation: {
+					type: "boolean",
+					description: "Include generated Markdown docs inline (default: false)"
+				}
+			},
+			required: []
+		}
+	},
+	{
+		name: "get_variant",
+		description: "Retrieve a single variant (template and metadata) from a component, resolving the component by path, title, component name, or fuzzy query.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				path: {
+					type: "string",
+					description: "Path to the .art.vue file"
+				},
+				title: {
+					type: "string",
+					description: "Resolve an art file by title"
+				},
+				component: {
+					type: "string",
+					description: "Resolve an art file by component reference or component basename"
+				},
+				query: {
+					type: "string",
+					description: "Fuzzy-search an art file before looking up the variant"
+				},
+				ref: {
+					type: "string",
+					description: "Generic art-file reference: path, title, component name, or search text"
+				},
+				variant: {
+					type: "string",
+					description: "Variant name"
+				},
+				includeAnalysis: {
+					type: "boolean",
+					description: "Include resolved component props/emits analysis (default: false)"
+				}
+			},
+			required: ["variant"]
+		}
+	},
+	{
+		name: "search_components",
+		description: "Ranked full-text search over component titles, descriptions, categories, tags, component names, and variant names.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				query: {
+					type: "string",
+					description: "Search query"
+				},
+				category: {
+					type: "string",
+					description: "Restrict matches to one category"
+				},
+				tag: {
+					type: "string",
+					description: "Restrict matches to one tag"
+				},
+				status: {
+					type: "string",
+					enum: [
+						"draft",
+						"ready",
+						"deprecated"
+					],
+					description: "Restrict matches to one status"
+				},
+				component: {
+					type: "string",
+					description: "Restrict matches to a component reference/basename before searching"
+				},
+				limit: {
+					type: "number",
+					description: "Maximum number of results to return (default: 10)"
+				}
+			},
+			required: ["query"]
+		}
+	},
+	{
+		name: "recommend_components",
+		description: "Intent-oriented component recommendation. Useful when the user describes a task or UX goal rather than knowing exact component names.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				task: {
+					type: "string",
+					description: "Intent or UI task to solve"
+				},
+				category: {
+					type: "string",
+					description: "Optional category filter"
+				},
+				tag: {
+					type: "string",
+					description: "Optional tag filter"
+				},
+				status: {
+					type: "string",
+					enum: [
+						"draft",
+						"ready",
+						"deprecated"
+					],
+					description: "Optional status filter"
+				},
+				component: {
+					type: "string",
+					description: "Optional component reference/basename filter"
+				},
+				limit: {
+					type: "number",
+					description: "Maximum number of recommendations to return (default: 5)"
+				}
+			},
+			required: ["task"]
+		}
+	},
+	{
+		name: "generate_variants",
+		description: "Analyze a Vue component's props and auto-generate an .art.vue file containing appropriate variant combinations (default, boolean toggles, enum values, etc.).",
+		inputSchema: {
+			type: "object",
+			properties: {
+				componentPath: {
+					type: "string",
+					description: "Path to the .vue component file (relative to project root)"
+				},
+				maxVariants: {
+					type: "number",
+					description: "Maximum number of variants to generate (default: 20)"
+				},
+				includeDefault: {
+					type: "boolean",
+					description: "Include a default variant (default: true)"
+				},
+				includeBooleanToggles: {
+					type: "boolean",
+					description: "Generate variants that toggle each boolean prop (default: true)"
+				},
+				includeEnumVariants: {
+					type: "boolean",
+					description: "Generate one variant per enum/union value (default: true)"
+				}
+			},
+			required: ["componentPath"]
+		}
+	},
+	{
+		name: "generate_csf",
+		description: "Convert an .art.vue file into Storybook CSF 3.0 code for integration with existing Storybook setups.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				path: {
+					type: "string",
+					description: "Path to the .art.vue file"
+				},
+				title: {
+					type: "string",
+					description: "Resolve an art file by title"
+				},
+				component: {
+					type: "string",
+					description: "Resolve an art file by component reference or component basename"
+				},
+				query: {
+					type: "string",
+					description: "Fuzzy-search an art file before converting to CSF"
+				},
+				ref: {
+					type: "string",
+					description: "Generic art-file reference: path, title, component name, or search text"
+				}
+			},
+			required: []
+		}
+	},
+	{
+		name: "generate_docs",
+		description: "Generate Markdown documentation for a design-system component from its .art.vue definition.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				path: {
+					type: "string",
+					description: "Path to the .art.vue file (relative to project root)"
+				},
+				title: {
+					type: "string",
+					description: "Resolve an art file by title"
+				},
+				component: {
+					type: "string",
+					description: "Resolve an art file by component reference or component basename"
+				},
+				query: {
+					type: "string",
+					description: "Fuzzy-search an art file before generating docs"
+				},
+				ref: {
+					type: "string",
+					description: "Generic art-file reference: path, title, component name, or search text"
+				},
+				includeSource: {
+					type: "boolean",
+					description: "Embed source code in the output (default: false)"
+				},
+				includeTemplates: {
+					type: "boolean",
+					description: "Embed variant templates in the output (default: false)"
+				}
+			},
+			required: []
+		}
+	},
+	{
+		name: "generate_catalog",
+		description: "Produce a single Markdown catalog covering every component in the design system, grouped by category.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				includeSource: {
+					type: "boolean",
+					description: "Embed source code in the catalog (default: false)"
+				},
+				includeTemplates: {
+					type: "boolean",
+					description: "Embed variant templates in the catalog (default: false)"
+				}
+			}
+		}
+	},
+	{
+		name: "get_tokens",
+		description: "Read design tokens (colors, spacing, typography, etc.) from a Style Dictionary-compatible JSON file or directory. Auto-detects common paths if not specified.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				tokensPath: {
+					type: "string",
+					description: "Path to tokens JSON file or directory (relative to project root). Auto-detects tokens/, design-tokens/, or style-dictionary/ if omitted."
+				},
+				format: {
+					type: "string",
+					enum: ["json", "markdown"],
+					description: "Output format (default: json)"
+				}
+			}
+		}
+	},
+	{
+		name: "search_tokens",
+		description: "Search flattened design tokens by token name, category path, value, or description. Much more practical than loading the full token tree for large systems.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				query: {
+					type: "string",
+					description: "Search query"
+				},
+				tokensPath: {
+					type: "string",
+					description: "Path to tokens JSON file or directory (relative to project root). Auto-detects common locations if omitted."
+				},
+				type: {
+					type: "string",
+					description: "Optional token type filter, e.g. color, dimension, typography"
+				},
+				limit: {
+					type: "number",
+					description: "Maximum number of matches to return (default: 20)"
+				}
+			},
+			required: ["query"]
+		}
+	}
+];
+//#endregion
+//#region src/musea.ts
+function normalize(value) {
+	return value?.trim().toLowerCase() ?? "";
+}
+function normalizePathLike(value) {
+	return value.replace(/\\/g, "/").toLowerCase();
+}
+function tokenize(query) {
+	return Array.from(new Set(query.toLowerCase().split(/[\s/,_-]+/).map((term) => term.trim()).filter(Boolean)));
+}
+function toProjectPath(projectRoot, absolutePath) {
+	const relativePath = path.relative(projectRoot, absolutePath);
+	if (!relativePath || relativePath.startsWith("..") || path.isAbsolute(relativePath)) return absolutePath;
+	return relativePath;
+}
+function buildResourceUris$1(relativePath, variantNames, hasComponentSource) {
+	const encodedPath = encodeURIComponent(relativePath);
+	return {
+		component: `musea://component/${encodedPath}`,
+		docs: `musea://docs/${encodedPath}`,
+		source: `musea://source/${encodedPath}`,
+		componentSource: hasComponentSource ? `musea://component-source/${encodedPath}` : void 0,
+		variants: variantNames.map((variantName) => ({
+			name: variantName,
+			uri: `musea://variant/${encodedPath}/${encodeURIComponent(variantName)}`
+		}))
+	};
+}
+function addScore(reasons, reason, amount, scoreRef) {
+	reasons.add(reason);
+	scoreRef.value += amount;
+}
+function getComponentCandidates(info) {
+	const candidates = /* @__PURE__ */ new Set();
+	if (info.component) {
+		candidates.add(info.component);
+		candidates.add(path.basename(info.component));
+		candidates.add(path.basename(info.component, path.extname(info.component)));
+	}
+	return Array.from(candidates);
+}
+function scoreArtInfo(projectRoot, info, query) {
+	const normalizedQuery = normalize(query);
+	if (!normalizedQuery) return null;
+	const relativePath = toProjectPath(projectRoot, info.path);
+	const relativePathNorm = normalizePathLike(relativePath);
+	const titleNorm = normalize(info.title);
+	const descriptionNorm = normalize(info.description);
+	const categoryNorm = normalize(info.category);
+	const tagNorms = info.tags.map((tag) => normalize(tag));
+	const variantNorms = info.variantNames.map((variantName) => normalize(variantName));
+	const componentNorms = getComponentCandidates(info).map((component) => normalizePathLike(component));
+	const reasons = /* @__PURE__ */ new Set();
+	const scoreRef = { value: 0 };
+	if (relativePathNorm === normalizePathLike(query)) addScore(reasons, "exact path match", 220, scoreRef);
+	else if (relativePathNorm.includes(normalizePathLike(query))) addScore(reasons, "path match", 70, scoreRef);
+	if (titleNorm === normalizedQuery) addScore(reasons, "exact title match", 200, scoreRef);
+	else if (titleNorm.startsWith(normalizedQuery)) addScore(reasons, "title prefix match", 140, scoreRef);
+	else if (titleNorm.includes(normalizedQuery)) addScore(reasons, "title match", 110, scoreRef);
+	if (categoryNorm === normalizedQuery) addScore(reasons, "exact category match", 120, scoreRef);
+	else if (categoryNorm.includes(normalizedQuery)) addScore(reasons, "category match", 55, scoreRef);
+	if (descriptionNorm.includes(normalizedQuery)) addScore(reasons, "description match", 60, scoreRef);
+	for (const tag of tagNorms) {
+		if (tag === normalizedQuery) {
+			addScore(reasons, "exact tag match", 130, scoreRef);
+			break;
+		}
+		if (tag.includes(normalizedQuery)) {
+			addScore(reasons, "tag match", 80, scoreRef);
+			break;
+		}
+	}
+	for (const variant of variantNorms) {
+		if (variant === normalizedQuery) {
+			addScore(reasons, "exact variant match", 130, scoreRef);
+			break;
+		}
+		if (variant.includes(normalizedQuery)) {
+			addScore(reasons, "variant match", 90, scoreRef);
+			break;
+		}
+	}
+	for (const component of componentNorms) {
+		if (component === normalizePathLike(query)) {
+			addScore(reasons, "exact component match", 180, scoreRef);
+			break;
+		}
+		if (component.includes(normalizePathLike(query))) {
+			addScore(reasons, "component match", 100, scoreRef);
+			break;
+		}
+	}
+	const terms = tokenize(query);
+	for (const term of terms) {
+		if (term === normalizedQuery) continue;
+		if (titleNorm.includes(term)) addScore(reasons, `title contains "${term}"`, 18, scoreRef);
+		if (descriptionNorm.includes(term)) addScore(reasons, `description contains "${term}"`, 10, scoreRef);
+		if (categoryNorm.includes(term)) addScore(reasons, `category contains "${term}"`, 10, scoreRef);
+		if (tagNorms.some((tag) => tag.includes(term))) addScore(reasons, `tag contains "${term}"`, 16, scoreRef);
+		if (variantNorms.some((variant) => variant.includes(term))) addScore(reasons, `variant contains "${term}"`, 14, scoreRef);
+		if (componentNorms.some((component) => component.includes(term))) addScore(reasons, `component contains "${term}"`, 14, scoreRef);
+	}
+	if (scoreRef.value <= 0) return null;
+	return {
+		info,
+		relativePath,
+		score: scoreRef.value,
+		reasons: Array.from(reasons).slice(0, 5)
+	};
+}
+function compareArtResults(left, right) {
+	return right.score - left.score || (left.info.order ?? Number.MAX_SAFE_INTEGER) - (right.info.order ?? Number.MAX_SAFE_INTEGER) || left.info.title.localeCompare(right.info.title);
+}
+async function searchArtInfos(ctx, query, filters) {
+	const arts = Array.from((await ctx.scanArtFiles()).values());
+	const category = normalize(filters?.category);
+	const tag = normalize(filters?.tag);
+	const status = normalize(filters?.status);
+	const componentFilter = normalize(filters?.component);
+	return arts.filter((info) => {
+		if (category && normalize(info.category) !== category) return false;
+		if (tag && !info.tags.some((item) => normalize(item) === tag)) return false;
+		if (status && normalize(info.status) !== status) return false;
+		if (componentFilter && !getComponentCandidates(info).some((candidate) => normalizePathLike(candidate).includes(componentFilter))) return false;
+		return true;
+	}).map((info) => scoreArtInfo(ctx.projectRoot, info, query)).filter((result) => result != null).sort(compareArtResults).slice(0, filters?.limit ?? 10);
+}
+function buildAlternatives(results) {
+	return results.slice(1, 4).map((result) => ({
+		path: result.relativePath,
+		title: result.info.title,
+		component: result.info.component,
+		score: result.score,
+		reasons: result.reasons
+	}));
+}
+async function resolveArtReference(ctx, args) {
+	const arts = Array.from((await ctx.scanArtFiles()).values());
+	const pathArg = typeof args?.path === "string" ? args.path : void 0;
+	const titleArg = typeof args?.title === "string" ? args.title : void 0;
+	const componentArg = typeof args?.component === "string" ? args.component : void 0;
+	const queryArg = typeof args?.query === "string" ? args.query : void 0;
+	const refArg = typeof args?.ref === "string" ? args.ref : void 0;
+	if (pathArg) {
+		const resolvedPath = path.isAbsolute(pathArg) ? pathArg : path.resolve(ctx.projectRoot, pathArg);
+		const normalizedResolvedPath = normalizePathLike(resolvedPath);
+		const normalizedRelativePath = normalizePathLike(path.relative(ctx.projectRoot, resolvedPath));
+		const directMatch = arts.find((info) => {
+			const infoRelativePath = normalizePathLike(path.relative(ctx.projectRoot, info.path));
+			return normalizePathLike(info.path) === normalizedResolvedPath || infoRelativePath === normalizedRelativePath;
+		});
+		if (directMatch) return {
+			info: directMatch,
+			absolutePath: directMatch.path,
+			relativePath: toProjectPath(ctx.projectRoot, directMatch.path),
+			matchedBy: "path",
+			matchValue: pathArg,
+			score: 999,
+			reasons: ["exact path match"],
+			alternatives: []
+		};
+	}
+	if (titleArg) {
+		const matches = arts.filter((info) => normalize(info.title) === normalize(titleArg));
+		if (matches.length > 0) {
+			const primary = matches[0];
+			return {
+				info: primary,
+				absolutePath: primary.path,
+				relativePath: toProjectPath(ctx.projectRoot, primary.path),
+				matchedBy: "title",
+				matchValue: titleArg,
+				score: 950,
+				reasons: ["exact title match"],
+				alternatives: matches.slice(1, 4).map((info) => ({
+					path: toProjectPath(ctx.projectRoot, info.path),
+					title: info.title,
+					component: info.component,
+					score: 900,
+					reasons: ["exact title match"]
+				}))
+			};
+		}
+	}
+	if (componentArg) {
+		const normalizedComponent = normalizePathLike(componentArg);
+		const matches = arts.filter((info) => getComponentCandidates(info).some((candidate) => normalizePathLike(candidate) === normalizedComponent));
+		if (matches.length > 0) {
+			const primary = matches[0];
+			return {
+				info: primary,
+				absolutePath: primary.path,
+				relativePath: toProjectPath(ctx.projectRoot, primary.path),
+				matchedBy: "component",
+				matchValue: componentArg,
+				score: 930,
+				reasons: ["exact component match"],
+				alternatives: matches.slice(1, 4).map((info) => ({
+					path: toProjectPath(ctx.projectRoot, info.path),
+					title: info.title,
+					component: info.component,
+					score: 880,
+					reasons: ["exact component match"]
+				}))
+			};
+		}
+	}
+	const queryValue = queryArg ?? refArg ?? pathArg ?? titleArg ?? componentArg;
+	if (!queryValue) throw new McpError(ErrorCode.InvalidParams, "Provide one of: path, title, component, query, or ref");
+	const results = await searchArtInfos(ctx, queryValue, { limit: 4 });
+	if (results.length === 0) throw new McpError(ErrorCode.InvalidParams, `No component matched "${queryValue}". Try list_components or search_components first.`);
+	const primary = results[0];
+	return {
+		info: primary.info,
+		absolutePath: primary.info.path,
+		relativePath: primary.relativePath,
+		matchedBy: queryArg ? "query" : "ref",
+		matchValue: queryValue,
+		score: primary.score,
+		reasons: primary.reasons,
+		alternatives: buildAlternatives(results)
+	};
+}
+function resolveComponentSourcePath(artAbsolutePath, componentReference) {
+	if (!componentReference) return null;
+	if (path.isAbsolute(componentReference)) return componentReference;
+	return path.resolve(path.dirname(artAbsolutePath), componentReference);
+}
+async function getComponentSourceDescriptor(ctx, resolved) {
+	const componentPath = resolveComponentSourcePath(resolved.absolutePath, resolved.info.component);
+	if (!componentPath) return {
+		reference: resolved.info.component,
+		exists: false,
+		error: "This art file does not declare a component source."
+	};
+	try {
+		await fs.promises.access(componentPath, fs.constants.R_OK);
+		return {
+			reference: resolved.info.component,
+			absolutePath: componentPath,
+			path: toProjectPath(ctx.projectRoot, componentPath),
+			exists: true
+		};
+	} catch {
+		return {
+			reference: resolved.info.component,
+			absolutePath: componentPath,
+			path: toProjectPath(ctx.projectRoot, componentPath),
+			exists: false,
+			error: `Component source not found: ${toProjectPath(ctx.projectRoot, componentPath)}`
+		};
+	}
+}
+function normalizeDefaultValue(value) {
+	if (value === "true") return true;
+	if (value === "false") return false;
+	if (typeof value === "string" && (value.startsWith("\"") && value.endsWith("\"") || value.startsWith("'") && value.endsWith("'"))) return value.slice(1, -1);
+	return value;
+}
+function inferControlType(type) {
+	const normalizedType = type.toLowerCase();
+	if (normalizedType === "boolean") return "boolean";
+	if (normalizedType === "number") return "number";
+	if (normalizedType.includes("|") && !normalizedType.includes("=>")) return "select";
+	return "text";
+}
+function extractOptionsFromType(type) {
+	const options = [];
+	for (const match of type.matchAll(/["']([^"']+)["']/g)) options.push({
+		label: match[1],
+		value: match[1]
+	});
+	return options;
+}
+function buildPaletteFromAnalysis(title, analysis) {
+	const controls = analysis.props.map((prop) => {
+		const control = inferControlType(prop.type);
+		return {
+			name: prop.name,
+			control,
+			defaultValue: normalizeDefaultValue(prop.defaultValue),
+			description: void 0,
+			required: prop.required,
+			options: control === "select" ? extractOptionsFromType(prop.type) : [],
+			range: void 0,
+			group: void 0
+		};
+	});
+	return {
+		title,
+		controls,
+		groups: [],
+		json: JSON.stringify({
+			title,
+			controls
+		}, null, 2),
+		typescript: `export interface ${title.replace(/\s+/g, "")}Props {\n${controls.map((control) => {
+			const type = control.control === "boolean" ? "boolean" : control.control === "number" ? "number" : control.control === "select" && control.options.length > 0 ? control.options.map((option) => `"${String(option.value)}"`).join(" | ") : "string";
+			return `  ${control.name}${control.required ? "" : "?"}: ${type};`;
+		}).join("\n")}\n}\n`
+	};
+}
+async function analyzeResolvedComponent(ctx, binding, resolved) {
+	const sourceDescriptor = await getComponentSourceDescriptor(ctx, resolved);
+	if (!sourceDescriptor.exists || !sourceDescriptor.absolutePath) return {
+		source: sourceDescriptor,
+		analysis: null
+	};
+	if (!binding.analyzeSfc) return {
+		source: {
+			...sourceDescriptor,
+			error: "analyzeSfc is not available in the native binding."
+		},
+		analysis: null
+	};
+	const source = await fs.promises.readFile(sourceDescriptor.absolutePath, "utf-8");
+	const analysis = binding.analyzeSfc(source, { filename: sourceDescriptor.absolutePath });
+	return {
+		source: sourceDescriptor,
+		analysis: {
+			path: sourceDescriptor.path ?? sourceDescriptor.absolutePath,
+			props: analysis.props.map((prop) => ({
+				name: prop.name,
+				type: prop.type,
+				required: prop.required,
+				defaultValue: prop.default_value
+			})),
+			emits: analysis.emits
+		}
+	};
+}
+function formatGeneratedMarkdown(markdown, componentName) {
+	let formatted = markdown.replace(/<Self(\s|>|\/)/g, `<${componentName}$1`).replace(/<\/Self>/g, `</${componentName}>`);
+	formatted = formatted.replace(/```(\w*)\n([\s\S]*?)```/g, (_match, lang, code) => {
+		const lines = code.split("\n");
+		let minIndent = Infinity;
+		for (const line of lines) if (line.trim()) {
+			const indent = line.match(/^(\s*)/)?.[1].length ?? 0;
+			minIndent = Math.min(minIndent, indent);
+		}
+		if (minIndent === Infinity) minIndent = 0;
+		return `\`\`\`${lang}\n${(minIndent > 0 ? lines.map((line) => line.slice(minIndent)) : lines).join("\n")}\`\`\``;
+	});
+	return formatted;
+}
+async function buildPalette(ctx, binding, resolved, source) {
+	let palette = null;
+	if (binding.generateArtPalette) {
+		const generated = binding.generateArtPalette(source, { filename: resolved.absolutePath });
+		palette = {
+			title: generated.title,
+			controls: generated.controls.map((control) => ({
+				name: control.name,
+				control: control.control,
+				defaultValue: control.default_value,
+				description: control.description,
+				required: control.required,
+				options: control.options,
+				range: control.range,
+				group: control.group
+			})),
+			groups: generated.groups,
+			json: generated.json,
+			typescript: generated.typescript
+		};
+	}
+	if (palette && palette.controls.length > 0) return palette;
+	const { analysis } = await analyzeResolvedComponent(ctx, binding, resolved);
+	if (!analysis || analysis.props.length === 0) return palette;
+	return buildPaletteFromAnalysis(resolved.info.title, analysis);
+}
+async function buildDocumentation(binding, resolved, source, options) {
+	if (!binding.generateArtDoc) return null;
+	const doc = binding.generateArtDoc(source, { filename: resolved.absolutePath }, {
+		include_source: options?.includeSource,
+		include_templates: options?.includeTemplates,
+		include_metadata: true
+	});
+	return {
+		markdown: formatGeneratedMarkdown(doc.markdown, resolved.info.title || "Component"),
+		title: doc.title,
+		category: doc.category,
+		variantCount: doc.variant_count
+	};
+}
+async function buildComponentDetails(ctx, binding, resolved, options) {
+	const source = await fs.promises.readFile(resolved.absolutePath, "utf-8");
+	const parsed = binding.parseArt(source, { filename: resolved.absolutePath });
+	const componentState = await analyzeResolvedComponent(ctx, binding, resolved);
+	const palette = options?.includePalette === false ? null : await buildPalette(ctx, binding, resolved, source);
+	const documentation = options?.includeDocumentation === true ? await buildDocumentation(binding, resolved, source) : null;
+	const resourceUris = buildResourceUris$1(resolved.relativePath, parsed.variants.map((variant) => variant.name), Boolean(componentState.source.reference));
+	return {
+		path: resolved.relativePath,
+		match: {
+			matchedBy: resolved.matchedBy,
+			matchValue: resolved.matchValue,
+			score: resolved.score,
+			reasons: resolved.reasons,
+			alternatives: resolved.alternatives
+		},
+		metadata: parsed.metadata,
+		variants: parsed.variants.map((variant) => ({
+			name: variant.name,
+			template: variant.template,
+			isDefault: variant.is_default,
+			skipVrt: variant.skip_vrt
+		})),
+		defaultVariant: parsed.variants.find((variant) => variant.is_default)?.name,
+		variantNames: parsed.variants.map((variant) => variant.name),
+		hasScriptSetup: parsed.has_script_setup,
+		hasScript: parsed.has_script,
+		styleCount: parsed.style_count,
+		componentSource: componentState.source,
+		componentAnalysis: options?.includeAnalysis === false ? void 0 : componentState.analysis ?? {
+			path: componentState.source.path,
+			props: [],
+			emits: [],
+			error: componentState.source.error
+		},
+		palette,
+		documentation,
+		resources: resourceUris
+	};
+}
+function buildCatalogMarkdown(arts, projectRoot) {
+	const grouped = /* @__PURE__ */ new Map();
+	for (const art of arts) {
+		const category = art.category || "Uncategorized";
+		const list = grouped.get(category) ?? [];
+		list.push(art);
+		grouped.set(category, list);
+	}
+	let markdown = "# Musea Component Catalog\n\n";
+	for (const [category, items] of Array.from(grouped.entries()).sort(([left], [right]) => left.localeCompare(right))) {
+		markdown += `## ${category}\n\n`;
+		for (const item of items.sort((left, right) => left.title.localeCompare(right.title))) {
+			const relativePath = toProjectPath(projectRoot, item.path);
+			markdown += `- **${item.title}** \`${relativePath}\``;
+			if (item.description) markdown += ` — ${item.description}`;
+			markdown += "\n";
+			if (item.variantNames.length > 0) markdown += `  Variants: ${item.variantNames.join(", ")}\n`;
+			if (item.tags.length > 0) markdown += `  Tags: ${item.tags.join(", ")}\n`;
+		}
+		markdown += "\n";
+	}
+	return markdown;
+}
+function buildIndexSummary(ctx, arts) {
+	const categories = /* @__PURE__ */ new Map();
+	const tags = /* @__PURE__ */ new Map();
+	for (const art of arts) {
+		categories.set(art.category || "Uncategorized", (categories.get(art.category || "Uncategorized") ?? 0) + 1);
+		for (const tag of art.tags) tags.set(tag, (tags.get(tag) ?? 0) + 1);
+	}
+	return {
+		componentCount: arts.length,
+		categories: Array.from(categories.entries()).map(([name, count]) => ({
+			name,
+			count
+		})).sort((left, right) => left.name.localeCompare(right.name)),
+		tags: Array.from(tags.entries()).map(([name, count]) => ({
+			name,
+			count
+		})).sort((left, right) => right.count - left.count || left.name.localeCompare(right.name)),
+		components: arts.slice().sort((left, right) => left.title.localeCompare(right.title)).map((art) => ({
+			path: toProjectPath(ctx.projectRoot, art.path),
+			title: art.title,
+			description: art.description,
+			component: art.component,
+			category: art.category,
+			status: art.status,
+			tags: art.tags,
+			variantCount: art.variantCount,
+			variantNames: art.variantNames,
+			defaultVariant: art.defaultVariant
+		}))
+	};
+}
+function getProjectPath(projectRoot, absolutePath) {
+	return toProjectPath(projectRoot, absolutePath);
+}
+//#endregion
+//#region src/tools/handler/analysis.ts
+/**
+* MCP tool handlers for component analysis.
+*
+* Handles `analyze_component` and `get_palette` tool calls.
+*/
+async function handleAnalyzeComponent(ctx, binding, args) {
+	const directPath = args?.path;
+	if (directPath?.endsWith(".vue") && !directPath.endsWith(".art.vue")) {
+		if (!binding.analyzeSfc) throw new McpError(ErrorCode.InternalError, "analyzeSfc not available in native binding");
+		const absolutePath = path.resolve(ctx.projectRoot, directPath);
+		const source = await fs.promises.readFile(absolutePath, "utf-8");
+		const analysis = binding.analyzeSfc(source, { filename: absolutePath });
+		return { content: [{
+			type: "text",
+			text: JSON.stringify({
+				path: directPath,
+				props: analysis.props.map((prop) => ({
+					name: prop.name,
+					type: prop.type,
+					required: prop.required,
+					defaultValue: prop.default_value
+				})),
+				emits: analysis.emits
+			}, null, 2)
+		}] };
+	}
+	const resolved = await resolveArtReference(ctx, args);
+	const { source, analysis } = await analyzeResolvedComponent(ctx, binding, resolved);
+	if (!analysis) throw new McpError(ErrorCode.InvalidParams, source.error ?? `Could not analyze component source for "${resolved.info.title}"`);
+	return { content: [{
+		type: "text",
+		text: JSON.stringify({
+			component: {
+				title: resolved.info.title,
+				artPath: resolved.relativePath,
+				componentReference: resolved.info.component,
+				componentPath: source.path
+			},
+			match: {
+				matchedBy: resolved.matchedBy,
+				matchValue: resolved.matchValue,
+				score: resolved.score,
+				reasons: resolved.reasons,
+				alternatives: resolved.alternatives
+			},
+			props: analysis.props,
+			emits: analysis.emits
+		}, null, 2)
+	}] };
+}
+async function handleGetPalette(ctx, binding, args) {
+	const resolved = await resolveArtReference(ctx, args);
+	const palette = await buildPalette(ctx, binding, resolved, await fs.promises.readFile(resolved.absolutePath, "utf-8"));
+	if (!palette) throw new McpError(ErrorCode.InvalidParams, `Could not infer a palette for "${resolved.info.title}"`);
+	return { content: [{
+		type: "text",
+		text: JSON.stringify({
+			component: {
+				title: resolved.info.title,
+				path: resolved.relativePath,
+				componentReference: resolved.info.component
+			},
+			match: {
+				matchedBy: resolved.matchedBy,
+				matchValue: resolved.matchValue,
+				score: resolved.score,
+				reasons: resolved.reasons,
+				alternatives: resolved.alternatives
+			},
+			title: palette.title,
+			controls: palette.controls,
+			groups: palette.groups,
+			json: palette.json,
+			typescript: palette.typescript
+		}, null, 2)
+	}] };
+}
+//#endregion
+//#region src/tools/handler/registry.ts
+/**
+* MCP tool handlers for the component registry.
+*
+* Handles `list_components`, `get_component`, `get_variant`, `search_components`,
+* and `recommend_components` tool calls.
+*/
+function buildResourceUris(relativePath, variantNames, hasComponent) {
+	const encodedPath = encodeURIComponent(relativePath);
+	return {
+		component: `musea://component/${encodedPath}`,
+		docs: `musea://docs/${encodedPath}`,
+		source: `musea://source/${encodedPath}`,
+		componentSource: hasComponent ? `musea://component-source/${encodedPath}` : void 0,
+		variants: variantNames.map((variantName) => ({
+			name: variantName,
+			uri: `musea://variant/${encodedPath}/${encodeURIComponent(variantName)}`
+		}))
+	};
+}
+async function handleListComponents(ctx, args) {
+	const arts = Array.from((await ctx.scanArtFiles()).values());
+	const category = typeof args?.category === "string" ? args.category.toLowerCase() : void 0;
+	const tag = typeof args?.tag === "string" ? args.tag.toLowerCase() : void 0;
+	const status = typeof args?.status === "string" ? args.status.toLowerCase() : void 0;
+	const component = typeof args?.component === "string" ? args.component.toLowerCase() : void 0;
+	const limit = typeof args?.limit === "number" ? args.limit : void 0;
+	const includeVariants = args?.includeVariants === true;
+	const sortBy = typeof args?.sortBy === "string" ? args.sortBy : "title";
+	let results = arts.filter((info) => {
+		if (category && info.category?.toLowerCase() !== category) return false;
+		if (tag && !info.tags.some((item) => item.toLowerCase() === tag)) return false;
+		if (status && info.status.toLowerCase() !== status) return false;
+		if (component && ![
+			info.component,
+			info.component ? info.component.split("/").at(-1) : void 0,
+			info.component ? info.component.split("/").at(-1)?.replace(/\.\w+$/, "") : void 0
+		].filter((value) => Boolean(value)).some((value) => value.toLowerCase().includes(component))) return false;
+		return true;
+	});
+	results = results.sort((left, right) => {
+		if (sortBy === "category") return (left.category || "").localeCompare(right.category || "") || left.title.localeCompare(right.title);
+		if (sortBy === "status") return left.status.localeCompare(right.status) || left.title.localeCompare(right.title);
+		if (sortBy === "variants") return right.variantCount - left.variantCount || left.title.localeCompare(right.title);
+		return left.title.localeCompare(right.title);
+	});
+	if (typeof limit === "number") results = results.slice(0, limit);
+	return { content: [{
+		type: "text",
+		text: JSON.stringify(results.map((info) => {
+			const relativePath = getProjectPath(ctx.projectRoot, info.path);
+			return {
+				path: relativePath,
+				title: info.title,
+				description: info.description,
+				component: info.component,
+				category: info.category,
+				status: info.status,
+				order: info.order,
+				tags: info.tags,
+				variantCount: info.variantCount,
+				variantNames: info.variantNames,
+				defaultVariant: info.defaultVariant,
+				variants: includeVariants ? info.variantNames.map((variantName) => ({
+					name: variantName,
+					isDefault: variantName === info.defaultVariant,
+					uri: `musea://variant/${encodeURIComponent(relativePath)}/${encodeURIComponent(variantName)}`
+				})) : void 0,
+				resources: buildResourceUris(relativePath, info.variantNames, Boolean(info.component))
+			};
+		}), null, 2)
+	}] };
+}
+async function handleGetComponent(ctx, binding, args) {
+	const details = await buildComponentDetails(ctx, binding, await resolveArtReference(ctx, args), {
+		includeAnalysis: args?.includeAnalysis !== false,
+		includePalette: args?.includePalette !== false,
+		includeDocumentation: args?.includeDocumentation === true
+	});
+	return { content: [{
+		type: "text",
+		text: JSON.stringify(details, null, 2)
+	}] };
+}
+async function handleGetVariant(ctx, binding, args) {
+	const variantName = args?.variant;
+	if (!variantName) throw new McpError(ErrorCode.InvalidParams, "variant is required");
+	const resolved = await resolveArtReference(ctx, args);
+	const source = await fs.promises.readFile(resolved.absolutePath, "utf-8");
+	const parsed = binding.parseArt(source, { filename: resolved.absolutePath });
+	const variant = parsed.variants.find((item) => item.name.toLowerCase() === variantName.toLowerCase());
+	if (!variant) throw new McpError(ErrorCode.InvalidParams, `Variant "${variantName}" not found in "${resolved.info.title}"`);
+	const analysis = args?.includeAnalysis === true ? await analyzeResolvedComponent(ctx, binding, resolved) : null;
+	return { content: [{
+		type: "text",
+		text: JSON.stringify({
+			component: {
+				title: resolved.info.title,
+				path: resolved.relativePath,
+				componentReference: resolved.info.component
+			},
+			match: {
+				matchedBy: resolved.matchedBy,
+				matchValue: resolved.matchValue,
+				score: resolved.score,
+				reasons: resolved.reasons,
+				alternatives: resolved.alternatives
+			},
+			variant: {
+				name: variant.name,
+				template: variant.template,
+				isDefault: variant.is_default,
+				skipVrt: variant.skip_vrt
+			},
+			relatedVariants: parsed.variants.map((item) => item.name),
+			componentAnalysis: analysis?.analysis == null ? void 0 : {
+				path: analysis.analysis.path,
+				props: analysis.analysis.props,
+				emits: analysis.analysis.emits
+			}
+		}, null, 2)
+	}] };
+}
+async function handleSearchComponents(ctx, args) {
+	const query = args?.query;
+	if (!query) throw new McpError(ErrorCode.InvalidParams, "query is required");
+	const results = await searchArtInfos(ctx, query, {
+		category: args?.category,
+		tag: args?.tag,
+		status: args?.status,
+		component: args?.component,
+		limit: args?.limit ?? 10
+	});
+	return { content: [{
+		type: "text",
+		text: JSON.stringify(results.map((result) => ({
+			score: result.score,
+			reasons: result.reasons,
+			path: result.relativePath,
+			title: result.info.title,
+			description: result.info.description,
+			component: result.info.component,
+			category: result.info.category,
+			status: result.info.status,
+			tags: result.info.tags,
+			variantCount: result.info.variantCount,
+			variantNames: result.info.variantNames,
+			defaultVariant: result.info.defaultVariant,
+			resources: buildResourceUris(result.relativePath, result.info.variantNames, Boolean(result.info.component))
+		})), null, 2)
+	}] };
+}
+async function handleRecommendComponents(ctx, args) {
+	const task = args?.task;
+	if (!task) throw new McpError(ErrorCode.InvalidParams, "task is required");
+	const results = await searchArtInfos(ctx, task, {
+		category: args?.category,
+		tag: args?.tag,
+		status: args?.status,
+		component: args?.component,
+		limit: args?.limit ?? 5
+	});
+	return { content: [{
+		type: "text",
+		text: JSON.stringify({
+			task,
+			recommendations: results.map((result) => ({
+				title: result.info.title,
+				path: result.relativePath,
+				component: result.info.component,
+				category: result.info.category,
+				status: result.info.status,
+				tags: result.info.tags,
+				variantNames: result.info.variantNames,
+				defaultVariant: result.info.defaultVariant,
+				score: result.score,
+				why: result.reasons,
+				resources: buildResourceUris(result.relativePath, result.info.variantNames, Boolean(result.info.component))
+			}))
+		}, null, 2)
+	}] };
+}
+//#endregion
+//#region src/tokens.ts
+async function parseTokensFromPath(tokensPath) {
+	if ((await fs.promises.stat(tokensPath)).isDirectory()) {
+		const entries = await fs.promises.readdir(tokensPath, { withFileTypes: true });
+		const categories = [];
+		for (const entry of entries) if (entry.isFile() && (entry.name.endsWith(".json") || entry.name.endsWith(".tokens.json"))) {
+			const filePath = path.join(tokensPath, entry.name);
+			const content = await fs.promises.readFile(filePath, "utf-8");
+			const tokens = JSON.parse(content);
+			const categoryName = path.basename(entry.name, path.extname(entry.name)).replace(".tokens", "");
+			categories.push({
+				name: formatCategoryName(categoryName),
+				tokens: extractTokenValues(tokens),
+				subcategories: extractSubcats(tokens)
+			});
+		}
+		return categories;
+	}
+	const content = await fs.promises.readFile(tokensPath, "utf-8");
+	return flattenTokenStructure(JSON.parse(content));
+}
+function generateTokensMarkdown(categories) {
+	const renderCategory = (category, level = 2) => {
+		let md = `\n${"#".repeat(level)} ${category.name}\n\n`;
+		if (Object.keys(category.tokens).length > 0) {
+			md += "| Token | Value | Description |\n";
+			md += "|-------|-------|-------------|\n";
+			for (const [name, token] of Object.entries(category.tokens)) md += `| \`${name}\` | \`${token.value}\` | ${token.description || "-"} |\n`;
+			md += "\n";
+		}
+		if (category.subcategories) for (const sub of category.subcategories) md += renderCategory(sub, level + 1);
+		return md;
+	};
+	let markdown = "# Design Tokens\n";
+	for (const category of categories) markdown += renderCategory(category);
+	return markdown;
+}
+function flattenTokenCategories(categories, parentPath = []) {
+	const flattened = [];
+	for (const category of categories) {
+		const categoryPath = [...parentPath, category.name];
+		for (const [name, token] of Object.entries(category.tokens)) flattened.push({
+			name,
+			path: [...categoryPath, name].join("."),
+			categoryPath,
+			value: token.value,
+			type: token.type,
+			description: token.description
+		});
+		if (category.subcategories) flattened.push(...flattenTokenCategories(category.subcategories, categoryPath));
+	}
+	return flattened;
+}
+function isTokenLeaf(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const obj = value;
+	return "value" in obj && (typeof obj.value === "string" || typeof obj.value === "number");
+}
+function extractTokenValues(obj) {
+	const tokens = {};
+	for (const [key, value] of Object.entries(obj)) if (isTokenLeaf(value)) {
+		const raw = value;
+		tokens[key] = {
+			value: raw.value,
+			type: raw.type,
+			description: raw.description
+		};
+	}
+	return tokens;
+}
+function extractSubcats(obj) {
+	const subcategories = [];
+	for (const [key, value] of Object.entries(obj)) if (!isTokenLeaf(value) && typeof value === "object" && value !== null) {
+		const tokens = extractTokenValues(value);
+		const nested = extractSubcats(value);
+		if (Object.keys(tokens).length > 0 || nested && nested.length > 0) subcategories.push({
+			name: formatCategoryName(key),
+			tokens,
+			subcategories: nested
+		});
+	}
+	return subcategories.length > 0 ? subcategories : void 0;
+}
+function flattenTokenStructure(tokens) {
+	const categories = [];
+	for (const [key, value] of Object.entries(tokens)) {
+		if (isTokenLeaf(value)) continue;
+		if (typeof value === "object" && value !== null) {
+			const categoryTokens = extractTokenValues(value);
+			const subcategories = flattenTokenStructure(value);
+			if (Object.keys(categoryTokens).length > 0 || subcategories.length > 0) categories.push({
+				name: formatCategoryName(key),
+				tokens: categoryTokens,
+				subcategories: subcategories.length > 0 ? subcategories : void 0
+			});
+		}
+	}
+	return categories;
+}
+function formatCategoryName(name) {
+	return name.replace(/[-_]/g, " ").replace(/([a-z])([A-Z])/g, "$1 $2").split(" ").map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()).join(" ");
+}
+//#endregion
+//#region src/tools/handler/generation.ts
+/**
+* MCP tool handlers for code generation.
+*
+* Handles `generate_variants`, `generate_csf`, `generate_docs`,
+* `generate_catalog`, `get_tokens`, and `search_tokens` tool calls.
+*/
+async function handleGenerateVariants(ctx, binding, args) {
+	const componentRelPath = args?.componentPath;
+	if (!componentRelPath) throw new McpError(ErrorCode.InvalidParams, "componentPath is required");
+	if (!binding.analyzeSfc) throw new McpError(ErrorCode.InternalError, "analyzeSfc not available in native binding");
+	if (!binding.generateVariants) throw new McpError(ErrorCode.InternalError, "generateVariants not available in native binding");
+	const absolutePath = path.resolve(ctx.projectRoot, componentRelPath);
+	const source = await fs.promises.readFile(absolutePath, "utf-8");
+	const props = binding.analyzeSfc(source, { filename: absolutePath }).props.map((prop) => ({
+		name: prop.name,
+		prop_type: prop.type,
+		required: prop.required,
+		default_value: prop.default_value
+	}));
+	const relPath = `./${path.basename(absolutePath)}`;
+	const result = binding.generateVariants(relPath, props, {
+		max_variants: args?.maxVariants,
+		include_default: args?.includeDefault,
+		include_boolean_toggles: args?.includeBooleanToggles,
+		include_enum_variants: args?.includeEnumVariants
+	});
+	return { content: [{
+		type: "text",
+		text: JSON.stringify({
+			componentPath: componentRelPath,
+			componentName: result.component_name,
+			artFileContent: result.art_file_content,
+			variants: result.variants.map((variant) => ({
+				name: variant.name,
+				isDefault: variant.is_default,
+				props: variant.props,
+				description: variant.description
+			}))
+		}, null, 2)
+	}] };
+}
+async function handleGenerateCsf(ctx, binding, args) {
+	const resolved = await resolveArtReference(ctx, args);
+	const source = await fs.promises.readFile(resolved.absolutePath, "utf-8");
+	const csf = binding.artToCsf(source, { filename: resolved.absolutePath });
+	return { content: [{
+		type: "text",
+		text: JSON.stringify({
+			component: {
+				title: resolved.info.title,
+				path: resolved.relativePath
+			},
+			match: {
+				matchedBy: resolved.matchedBy,
+				matchValue: resolved.matchValue,
+				score: resolved.score,
+				reasons: resolved.reasons,
+				alternatives: resolved.alternatives
+			},
+			filename: csf.filename,
+			code: csf.code
+		}, null, 2)
+	}] };
+}
+async function handleGenerateDocs(ctx, binding, args) {
+	const resolved = await resolveArtReference(ctx, args);
+	const source = await fs.promises.readFile(resolved.absolutePath, "utf-8");
+	if (!binding.generateArtDoc) throw new McpError(ErrorCode.InternalError, "generateArtDoc not available in native binding");
+	const doc = binding.generateArtDoc(source, { filename: resolved.absolutePath }, {
+		include_source: args?.includeSource,
+		include_templates: args?.includeTemplates,
+		include_metadata: true
+	});
+	const formattedDoc = await buildDocumentation(binding, resolved, source, {
+		includeSource: args?.includeSource,
+		includeTemplates: args?.includeTemplates
+	});
+	return { content: [{
+		type: "text",
+		text: JSON.stringify({
+			component: {
+				title: resolved.info.title,
+				path: resolved.relativePath
+			},
+			match: {
+				matchedBy: resolved.matchedBy,
+				matchValue: resolved.matchValue,
+				score: resolved.score,
+				reasons: resolved.reasons,
+				alternatives: resolved.alternatives
+			},
+			markdown: formattedDoc?.markdown ?? doc.markdown,
+			title: doc.title,
+			category: doc.category,
+			variantCount: doc.variant_count
+		}, null, 2)
+	}] };
+}
+async function handleGenerateCatalog(ctx, binding, args) {
+	const arts = await ctx.scanArtFiles();
+	if (binding.generateArtCatalog) {
+		const sources = [];
+		for (const [filePath] of arts) {
+			const source = await fs.promises.readFile(filePath, "utf-8");
+			sources.push(source);
+		}
+		const catalog = binding.generateArtCatalog(sources, {
+			include_source: args?.includeSource,
+			include_templates: args?.includeTemplates,
+			include_metadata: true
+		});
+		return { content: [{
+			type: "text",
+			text: JSON.stringify({
+				markdown: catalog.markdown,
+				componentCount: catalog.component_count,
+				categories: catalog.categories,
+				tags: catalog.tags
+			}, null, 2)
+		}] };
+	}
+	const allArts = Array.from(arts.values());
+	return { content: [{
+		type: "text",
+		text: JSON.stringify({
+			markdown: buildCatalogMarkdown(allArts, ctx.projectRoot),
+			componentCount: allArts.length,
+			categories: Array.from(new Set(allArts.map((art) => art.category || "Uncategorized"))),
+			tags: Array.from(new Set(allArts.flatMap((art) => art.tags)))
+		}, null, 2)
+	}] };
+}
+async function handleGetTokens(ctx, args) {
+	const inputPath = args?.tokensPath;
+	const format = args?.format ?? "json";
+	let resolvedPath;
+	if (inputPath) resolvedPath = path.resolve(ctx.projectRoot, inputPath);
+	else resolvedPath = await ctx.resolveTokensPath();
+	if (!resolvedPath) throw new McpError(ErrorCode.InvalidParams, "No tokens path provided and none auto-detected. Looked for: tokens/, design-tokens/, style-dictionary/ directories.");
+	const categories = await parseTokensFromPath(resolvedPath);
+	const flattened = flattenTokenCategories(categories);
+	if (format === "markdown") return { content: [{
+		type: "text",
+		text: generateTokensMarkdown(categories)
+	}] };
+	return { content: [{
+		type: "text",
+		text: JSON.stringify({
+			source: path.relative(ctx.projectRoot, resolvedPath),
+			categoryCount: categories.length,
+			tokenCount: flattened.length,
+			categories
+		}, null, 2)
+	}] };
+}
+async function handleSearchTokens(ctx, args) {
+	const query = args?.query;
+	if (!query) throw new McpError(ErrorCode.InvalidParams, "query is required");
+	const inputPath = args?.tokensPath;
+	const typeFilter = typeof args?.type === "string" ? args.type.toLowerCase() : void 0;
+	const limit = typeof args?.limit === "number" ? args.limit : 20;
+	const resolvedPath = inputPath ? path.resolve(ctx.projectRoot, inputPath) : await ctx.resolveTokensPath();
+	if (!resolvedPath) throw new McpError(ErrorCode.InvalidParams, "No tokens path provided and none auto-detected. Looked for: tokens/, design-tokens/, style-dictionary/ directories.");
+	const flattened = flattenTokenCategories(await parseTokensFromPath(resolvedPath));
+	const normalizedQuery = query.toLowerCase();
+	const allMatches = flattened.filter((token) => {
+		if (typeFilter && token.type?.toLowerCase() !== typeFilter) return false;
+		return token.name.toLowerCase().includes(normalizedQuery) || token.path.toLowerCase().includes(normalizedQuery) || token.categoryPath.some((segment) => segment.toLowerCase().includes(normalizedQuery)) || String(token.value).toLowerCase().includes(normalizedQuery) || token.description?.toLowerCase().includes(normalizedQuery);
+	});
+	const matches = allMatches.slice(0, limit);
+	return { content: [{
+		type: "text",
+		text: JSON.stringify({
+			query,
+			source: path.relative(ctx.projectRoot, resolvedPath),
+			totalMatches: allMatches.length,
+			matches
+		}, null, 2)
+	}] };
+}
+//#endregion
+//#region src/tools/handler/index.ts
+/**
+* MCP tool call handler for Musea.
+*
+* Routes incoming tool calls to the appropriate handler logic based on
+* the tool name, using the native Rust binding and server context.
+*/
+async function handleToolCall(ctx, name, args) {
+	const binding = ctx.loadNative();
+	switch (name) {
+		case "analyze_component": return handleAnalyzeComponent(ctx, binding, args);
+		case "get_palette": return handleGetPalette(ctx, binding, args);
+		case "list_components": return handleListComponents(ctx, args);
+		case "get_component": return handleGetComponent(ctx, binding, args);
+		case "get_variant": return handleGetVariant(ctx, binding, args);
+		case "search_components": return handleSearchComponents(ctx, args);
+		case "recommend_components": return handleRecommendComponents(ctx, args);
+		case "generate_variants": return handleGenerateVariants(ctx, binding, args);
+		case "generate_csf": return handleGenerateCsf(ctx, binding, args);
+		case "generate_docs": return handleGenerateDocs(ctx, binding, args);
+		case "generate_catalog": return handleGenerateCatalog(ctx, binding, args);
+		case "get_tokens": return handleGetTokens(ctx, args);
+		case "search_tokens": return handleSearchTokens(ctx, args);
+		default: throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+	}
+}
+//#endregion
+//#region src/resources.ts
+function componentUri(relativePath) {
+	return `musea://component/${encodeURIComponent(relativePath)}`;
+}
+function docsUri(relativePath) {
+	return `musea://docs/${encodeURIComponent(relativePath)}`;
+}
+function sourceUri(relativePath) {
+	return `musea://source/${encodeURIComponent(relativePath)}`;
+}
+function componentSourceUri(relativePath) {
+	return `musea://component-source/${encodeURIComponent(relativePath)}`;
+}
+function variantUri(relativePath, variantName) {
+	return `musea://variant/${encodeURIComponent(relativePath)}/${encodeURIComponent(variantName)}`;
+}
+async function listResources(ctx) {
+	const arts = Array.from((await ctx.scanArtFiles()).values());
+	const resources = [{
+		uri: "musea://index",
+		name: "Component Index",
+		description: "JSON summary of the project component registry",
+		mimeType: "application/json"
+	}, {
+		uri: "musea://catalog",
+		name: "Component Catalog",
+		description: "Markdown catalog for the whole design system",
+		mimeType: "text/markdown"
+	}];
+	for (const info of arts) {
+		const relativePath = getProjectPath(ctx.projectRoot, info.path);
+		resources.push({
+			uri: componentUri(relativePath),
+			name: info.title,
+			description: info.description || `${info.category || "Component"} • ${info.variantCount} variant(s) • ${info.status}`,
+			mimeType: "application/json"
+		});
+		resources.push({
+			uri: docsUri(relativePath),
+			name: `${info.title} — Documentation`,
+			description: `Generated Markdown docs for ${info.title}`,
+			mimeType: "text/markdown"
+		});
+		resources.push({
+			uri: sourceUri(relativePath),
+			name: `${info.title} — Art Source`,
+			description: `Raw .art.vue source for ${info.title}`,
+			mimeType: "text/plain"
+		});
+		if (info.component) resources.push({
+			uri: componentSourceUri(relativePath),
+			name: `${info.title} — Component Source`,
+			description: `Resolved Vue component source for ${info.title}`,
+			mimeType: "text/plain"
+		});
+		for (const variantName of info.variantNames) resources.push({
+			uri: variantUri(relativePath, variantName),
+			name: `${info.title} — ${variantName}`,
+			description: `Variant details for ${variantName}`,
+			mimeType: "application/json"
+		});
+	}
+	if (await ctx.resolveTokensPath()) {
+		resources.push({
+			uri: "musea://tokens",
+			name: "Design Tokens",
+			description: "Project design tokens as JSON",
+			mimeType: "application/json"
+		});
+		resources.push({
+			uri: "musea://tokens/markdown",
+			name: "Design Tokens — Markdown",
+			description: "Project design tokens as Markdown tables",
+			mimeType: "text/markdown"
+		});
+	}
+	return { resources };
+}
+async function readResource(ctx, uri) {
+	if (uri === "musea://index") {
+		const arts = Array.from((await ctx.scanArtFiles()).values());
+		return { contents: [{
+			uri,
+			mimeType: "application/json",
+			text: JSON.stringify(buildIndexSummary(ctx, arts), null, 2)
+		}] };
+	}
+	if (uri === "musea://catalog") {
+		const binding = ctx.loadNative();
+		const arts = Array.from((await ctx.scanArtFiles()).values());
+		if (binding.generateArtCatalog) {
+			const sources = await Promise.all(arts.map((art) => fs.promises.readFile(art.path, "utf-8")));
+			return { contents: [{
+				uri,
+				mimeType: "text/markdown",
+				text: binding.generateArtCatalog(sources, { include_metadata: true }).markdown
+			}] };
+		}
+		return { contents: [{
+			uri,
+			mimeType: "text/markdown",
+			text: buildCatalogMarkdown(arts, ctx.projectRoot)
+		}] };
+	}
+	if (uri.startsWith("musea://component/")) {
+		const relativePath = decodeURIComponent(uri.slice(18));
+		const details = await buildComponentDetails(ctx, ctx.loadNative(), await resolveArtReference(ctx, { path: relativePath }), {
+			includeAnalysis: true,
+			includePalette: true,
+			includeDocumentation: false
+		});
+		return { contents: [{
+			uri,
+			mimeType: "application/json",
+			text: JSON.stringify(details, null, 2)
+		}] };
+	}
+	if (uri.startsWith("musea://docs/")) {
+		const relativePath = decodeURIComponent(uri.slice(13));
+		const binding = ctx.loadNative();
+		const resolved = await resolveArtReference(ctx, { path: relativePath });
+		const documentation = await buildDocumentation(binding, resolved, await fs.promises.readFile(resolved.absolutePath, "utf-8"));
+		if (!documentation) throw new McpError(ErrorCode.InternalError, "generateArtDoc not available in native binding");
+		return { contents: [{
+			uri,
+			mimeType: "text/markdown",
+			text: documentation.markdown
+		}] };
+	}
+	if (uri.startsWith("musea://source/")) {
+		const relativePath = decodeURIComponent(uri.slice(15));
+		const absolutePath = path.resolve(ctx.projectRoot, relativePath);
+		return { contents: [{
+			uri,
+			mimeType: "text/plain",
+			text: await fs.promises.readFile(absolutePath, "utf-8")
+		}] };
+	}
+	if (uri.startsWith("musea://component-source/")) {
+		const relativePath = decodeURIComponent(uri.slice(25));
+		const componentSource = (await buildComponentDetails(ctx, ctx.loadNative(), await resolveArtReference(ctx, { path: relativePath }), {
+			includeAnalysis: false,
+			includePalette: false,
+			includeDocumentation: false
+		})).componentSource;
+		if (!componentSource?.path || componentSource.exists !== true) throw new McpError(ErrorCode.InvalidRequest, componentSource?.error ?? "Component source not available for this art file");
+		const absolutePath = path.resolve(ctx.projectRoot, componentSource.path);
+		return { contents: [{
+			uri,
+			mimeType: "text/plain",
+			text: await fs.promises.readFile(absolutePath, "utf-8")
+		}] };
+	}
+	if (uri.startsWith("musea://variant/")) {
+		const rest = uri.slice(16);
+		const separatorIndex = rest.indexOf("/");
+		if (separatorIndex === -1) throw new McpError(ErrorCode.InvalidRequest, `Unknown resource URI: ${uri}`);
+		const relativePath = decodeURIComponent(rest.slice(0, separatorIndex));
+		const variantName = decodeURIComponent(rest.slice(separatorIndex + 1));
+		const binding = ctx.loadNative();
+		const resolved = await resolveArtReference(ctx, { path: relativePath });
+		const source = await fs.promises.readFile(resolved.absolutePath, "utf-8");
+		const parsed = binding.parseArt(source, { filename: resolved.absolutePath });
+		const variant = parsed.variants.find((item) => item.name.toLowerCase() === variantName.toLowerCase());
+		if (!variant) throw new McpError(ErrorCode.InvalidRequest, `Variant "${variantName}" not found in "${resolved.info.title}"`);
+		return { contents: [{
+			uri,
+			mimeType: "application/json",
+			text: JSON.stringify({
+				component: {
+					title: resolved.info.title,
+					path: resolved.relativePath,
+					componentReference: resolved.info.component
+				},
+				variant: {
+					name: variant.name,
+					template: variant.template,
+					isDefault: variant.is_default,
+					skipVrt: variant.skip_vrt
+				},
+				relatedVariants: parsed.variants.map((item) => item.name)
+			}, null, 2)
+		}] };
+	}
+	if (uri === "musea://tokens" || uri === "musea://tokens/markdown") {
+		const resolvedTokensPath = await ctx.resolveTokensPath();
+		if (!resolvedTokensPath) throw new McpError(ErrorCode.InternalError, "No tokens path configured or auto-detected");
+		const categories = await parseTokensFromPath(resolvedTokensPath);
+		if (uri === "musea://tokens/markdown") return { contents: [{
+			uri,
+			mimeType: "text/markdown",
+			text: generateTokensMarkdown(categories)
+		}] };
+		return { contents: [{
+			uri,
+			mimeType: "application/json",
+			text: JSON.stringify({
+				source: path.relative(ctx.projectRoot, resolvedTokensPath),
+				categoryCount: categories.length,
+				tokenCount: flattenTokenCategories(categories).length,
+				categories
+			}, null, 2)
+		}] };
+	}
+	throw new McpError(ErrorCode.InvalidRequest, `Unknown resource URI: ${uri}`);
+}
+//#endregion
+//#region src/index.ts
+/**
+* Musea MCP Server — Vue.js design system toolkit.
+*
+* Provides AI assistants with tools to:
+* - Analyze Vue SFC components (props, emits)
+* - Browse and search a component registry
+* - Generate documentation, variants, and Storybook stories
+* - Read and format design tokens
+*/
+function createMuseaServer(config) {
+	const server = new Server({
+		name: "musea-mcp-server",
+		version: "0.0.1-alpha.11"
+	}, { capabilities: {
+		resources: {},
+		tools: {}
+	} });
+	const projectRoot = config.projectRoot;
+	const include = config.include ?? ["**/*.art.vue"];
+	const exclude = config.exclude ?? ["node_modules/**", "dist/**"];
+	const tokensPath = config.tokensPath;
+	let artCache = /* @__PURE__ */ new Map();
+	let lastScanTime = 0;
+	async function scanArtFiles() {
+		const now = Date.now();
+		if (now - lastScanTime < 5e3 && artCache.size > 0) return artCache;
+		const binding = loadNative();
+		const files = await findArtFiles(projectRoot, include, exclude);
+		artCache = /* @__PURE__ */ new Map();
+		for (const file of files) try {
+			const source = await fs.promises.readFile(file, "utf-8");
+			const parsed = binding.parseArt(source, { filename: file });
+			artCache.set(file, {
+				path: file,
+				title: parsed.metadata.title,
+				description: parsed.metadata.description,
+				component: parsed.metadata.component,
+				category: parsed.metadata.category,
+				tags: parsed.metadata.tags,
+				status: parsed.metadata.status,
+				order: parsed.metadata.order,
+				variantCount: parsed.variants.length,
+				variantNames: parsed.variants.map((variant) => variant.name),
+				defaultVariant: parsed.variants.find((variant) => variant.is_default)?.name
+			});
+		} catch (e) {
+			console.error(`Failed to parse ${file}:`, e);
+		}
+		lastScanTime = now;
+		return artCache;
+	}
+	async function resolveTokensPath() {
+		if (tokensPath) return path.resolve(projectRoot, tokensPath);
+		for (const dir of [
+			"tokens",
+			"design-tokens",
+			"style-dictionary"
+		]) {
+			const candidate = path.join(projectRoot, dir);
+			try {
+				const stat = await fs.promises.stat(candidate);
+				if (stat.isDirectory() || stat.isFile()) return candidate;
+			} catch {}
+		}
+		return null;
+	}
+	const ctx = {
+		projectRoot,
+		loadNative,
+		scanArtFiles,
+		resolveTokensPath
+	};
+	server.setRequestHandler(ListResourcesRequestSchema, () => listResources(ctx));
+	server.setRequestHandler(ReadResourceRequestSchema, (req) => readResource(ctx, req.params.uri));
+	server.setRequestHandler(ListToolsRequestSchema, () => Promise.resolve({ tools: toolDefinitions }));
+	server.setRequestHandler(CallToolRequestSchema, (req) => handleToolCall(ctx, req.params.name, req.params.arguments));
+	return server;
+}
+async function startServer(projectRoot, options) {
+	const server = createMuseaServer({
+		projectRoot,
+		tokensPath: options?.tokensPath
+	});
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+	console.error("[musea-mcp] Server started");
+}
+//#endregion
+export { startServer as n, createMuseaServer as t };