@vizejs/musea-mcp-server 0.58.0 → 0.60.0

package/README.md

@@ -11,8 +11,10 @@ MCP (Model Context Protocol) server for Musea design system integration.
 
 ## Installation
 
+Install `vp` once from the [Vite+ install guide](https://viteplus.dev/guide/install), then add the server to your project:
+
 ```bash
-npm install -g @vizejs/musea-mcp-server
+vp install -D @vizejs/musea-mcp-server
 ```
 
 ## Usage
@@ -25,8 +27,8 @@ Add to `claude_desktop_config.json`:
 {
   "mcpServers": {
     "musea": {
-      "command": "musea-mcp-server",
-      "args": ["--project", "/path/to/project"]
+      "command": "vp",
+      "args": ["dlx", "@vizejs/musea-mcp-server", "--project", "/path/to/project"]
     }
   }
 }
@@ -35,7 +37,7 @@ Add to `claude_desktop_config.json`:
 ### Standalone
 
 ```bash
-musea-mcp-server --project ./my-vue-app
+vp dlx @vizejs/musea-mcp-server --project ./my-vue-app
 ```
 
 ## MCP Tools

package/dist/cli.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/cli.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { n as startServer } from "./src-DqveCZc0.mjs";
+//#region src/cli.ts
+/**
+* Musea MCP Server CLI.
+*
+* Usage:
+*   musea-mcp [project-root] [--tokens-path <path>]
+*
+* Environment:
+*   MUSEA_PROJECT_ROOT - Project root directory (default: cwd)
+*   MUSEA_TOKENS_PATH  - Path to design tokens file/directory
+*/
+let projectRoot = process.env.MUSEA_PROJECT_ROOT || process.cwd();
+let tokensPath = process.env.MUSEA_TOKENS_PATH;
+const args = process.argv.slice(2);
+for (let i = 0; i < args.length; i++) if (args[i] === "--tokens-path" && i + 1 < args.length) tokensPath = args[++i];
+else if (!args[i].startsWith("--")) projectRoot = args[i];
+console.error(`[musea-mcp] Starting server for project: ${projectRoot}`);
+if (tokensPath) console.error(`[musea-mcp] Tokens path: ${tokensPath}`);
+startServer(projectRoot, { tokensPath }).catch((error) => {
+	console.error("[musea-mcp] Failed to start:", error);
+	process.exit(1);
+});
+//#endregion
+export {};

package/dist/index.d.mts

@@ -0,0 +1,14 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+
+//#region src/index.d.ts
+declare function createMuseaServer(config: {
+  projectRoot: string;
+  include?: string[];
+  exclude?: string[];
+  tokensPath?: string;
+}): Server;
+declare function startServer(projectRoot: string, options?: {
+  tokensPath?: string;
+}): Promise<void>;
+//#endregion
+export { createMuseaServer, createMuseaServer as default, startServer };

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import { n as startServer, t as createMuseaServer } from "./src-DqveCZc0.mjs";
+export { createMuseaServer, createMuseaServer as default, startServer };

package/dist/src-DqveCZc0.mjs

@@ -0,0 +1,780 @@
+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. Useful for understanding a component's public API when building or reviewing a design system.",
+		inputSchema: {
+			type: "object",
+			properties: { path: {
+				type: "string",
+				description: "Path to the .vue component file (relative to project root)"
+			} },
+			required: ["path"]
+		}
+	},
+	{
+		name: "get_palette",
+		description: "Derive an interactive props palette (control types, defaults, ranges, options) for a component described by an Art file. Helps to understand how props can be tweaked in a design system playground.",
+		inputSchema: {
+			type: "object",
+			properties: { path: {
+				type: "string",
+				description: "Path to the .art.vue file (relative to project root)"
+			} },
+			required: ["path"]
+		}
+	},
+	{
+		name: "list_components",
+		description: "List components registered in the design system. Returns titles, categories, tags, and variant counts.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				category: {
+					type: "string",
+					description: "Filter by category"
+				},
+				tag: {
+					type: "string",
+					description: "Filter by tag"
+				}
+			}
+		}
+	},
+	{
+		name: "get_component",
+		description: "Get full details of a design-system component: metadata, variant list, and script/style information.",
+		inputSchema: {
+			type: "object",
+			properties: { path: {
+				type: "string",
+				description: "Path to the .art.vue file (relative to project root)"
+			} },
+			required: ["path"]
+		}
+	},
+	{
+		name: "get_variant",
+		description: "Retrieve a single variant (template and metadata) from a component.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				path: {
+					type: "string",
+					description: "Path to the .art.vue file"
+				},
+				variant: {
+					type: "string",
+					description: "Variant name"
+				}
+			},
+			required: ["path", "variant"]
+		}
+	},
+	{
+		name: "search_components",
+		description: "Full-text search over component titles, descriptions, and tags.",
+		inputSchema: {
+			type: "object",
+			properties: { query: {
+				type: "string",
+				description: "Search query"
+			} },
+			required: ["query"]
+		}
+	},
+	{
+		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"
+			} },
+			required: ["path"]
+		}
+	},
+	{
+		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)"
+				},
+				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: ["path"]
+		}
+	},
+	{
+		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)"
+				}
+			}
+		}
+	}
+];
+//#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 vuePath = args?.path;
+	if (!vuePath) throw new McpError(ErrorCode.InvalidParams, "path is required");
+	if (!binding.analyzeSfc) throw new McpError(ErrorCode.InternalError, "analyzeSfc not available in native binding");
+	const absolutePath = path.resolve(ctx.projectRoot, vuePath);
+	const source = await fs.promises.readFile(absolutePath, "utf-8");
+	const analysis = binding.analyzeSfc(source, { filename: absolutePath });
+	return { content: [{
+		type: "text",
+		text: JSON.stringify({
+			props: analysis.props.map((p) => ({
+				name: p.name,
+				type: p.type,
+				required: p.required,
+				defaultValue: p.default_value
+			})),
+			emits: analysis.emits
+		}, null, 2)
+	}] };
+}
+async function handleGetPalette(ctx, binding, args) {
+	const artPath = args?.path;
+	if (!artPath) throw new McpError(ErrorCode.InvalidParams, "path is required");
+	if (!binding.generateArtPalette) throw new McpError(ErrorCode.InternalError, "generateArtPalette not available in native binding");
+	const absolutePath = path.resolve(ctx.projectRoot, artPath);
+	const source = await fs.promises.readFile(absolutePath, "utf-8");
+	const palette = binding.generateArtPalette(source, { filename: absolutePath });
+	return { content: [{
+		type: "text",
+		text: JSON.stringify({
+			title: palette.title,
+			controls: palette.controls.map((c) => ({
+				name: c.name,
+				control: c.control,
+				defaultValue: c.default_value,
+				description: c.description,
+				required: c.required,
+				options: c.options,
+				range: c.range,
+				group: c.group
+			})),
+			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`, and
+* `search_components` tool calls.
+*/
+async function handleListComponents(ctx, args) {
+	const arts = await ctx.scanArtFiles();
+	let results = Array.from(arts.values());
+	if (args?.category) results = results.filter((a) => a.category?.toLowerCase() === args.category.toLowerCase());
+	if (args?.tag) results = results.filter((a) => a.tags.some((t) => t.toLowerCase() === args.tag.toLowerCase()));
+	return { content: [{
+		type: "text",
+		text: JSON.stringify(results.map((r) => ({
+			path: path.relative(ctx.projectRoot, r.path),
+			title: r.title,
+			description: r.description,
+			component: r.component,
+			category: r.category,
+			tags: r.tags,
+			variantCount: r.variantCount
+		})), null, 2)
+	}] };
+}
+async function handleGetComponent(ctx, binding, args) {
+	const artPath = args?.path;
+	if (!artPath) throw new McpError(ErrorCode.InvalidParams, "path is required");
+	const absolutePath = path.resolve(ctx.projectRoot, artPath);
+	const source = await fs.promises.readFile(absolutePath, "utf-8");
+	const parsed = binding.parseArt(source, { filename: absolutePath });
+	return { content: [{
+		type: "text",
+		text: JSON.stringify({
+			metadata: parsed.metadata,
+			variants: parsed.variants.map((v) => ({
+				name: v.name,
+				template: v.template,
+				isDefault: v.is_default,
+				skipVrt: v.skip_vrt
+			})),
+			hasScriptSetup: parsed.has_script_setup,
+			hasScript: parsed.has_script,
+			styleCount: parsed.style_count
+		}, null, 2)
+	}] };
+}
+async function handleGetVariant(ctx, binding, args) {
+	const artPath = args?.path;
+	const variantName = args?.variant;
+	if (!artPath || !variantName) throw new McpError(ErrorCode.InvalidParams, "path and variant are required");
+	const absolutePath = path.resolve(ctx.projectRoot, artPath);
+	const source = await fs.promises.readFile(absolutePath, "utf-8");
+	const variant = binding.parseArt(source, { filename: absolutePath }).variants.find((v) => v.name.toLowerCase() === variantName.toLowerCase());
+	if (!variant) throw new McpError(ErrorCode.InvalidParams, `Variant "${variantName}" not found`);
+	return { content: [{
+		type: "text",
+		text: JSON.stringify({
+			name: variant.name,
+			template: variant.template,
+			isDefault: variant.is_default,
+			skipVrt: variant.skip_vrt
+		}, null, 2)
+	}] };
+}
+async function handleSearchComponents(ctx, args) {
+	const query = (args?.query)?.toLowerCase();
+	if (!query) throw new McpError(ErrorCode.InvalidParams, "query is required");
+	const arts = await ctx.scanArtFiles();
+	const results = Array.from(arts.values()).filter((a) => a.title.toLowerCase().includes(query) || a.description?.toLowerCase().includes(query) || a.tags.some((t) => t.toLowerCase().includes(query)));
+	return { content: [{
+		type: "text",
+		text: JSON.stringify(results.map((r) => ({
+			path: path.relative(ctx.projectRoot, r.path),
+			title: r.title,
+			description: r.description,
+			component: r.component,
+			category: r.category,
+			tags: r.tags
+		})), 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 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`, and `get_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((p) => ({
+		name: p.name,
+		prop_type: p.type,
+		required: p.required,
+		default_value: p.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({
+			componentName: result.component_name,
+			artFileContent: result.art_file_content,
+			variants: result.variants.map((v) => ({
+				name: v.name,
+				isDefault: v.is_default,
+				props: v.props,
+				description: v.description
+			}))
+		}, null, 2)
+	}] };
+}
+async function handleGenerateCsf(ctx, binding, args) {
+	const artPath = args?.path;
+	if (!artPath) throw new McpError(ErrorCode.InvalidParams, "path is required");
+	const absolutePath = path.resolve(ctx.projectRoot, artPath);
+	const source = await fs.promises.readFile(absolutePath, "utf-8");
+	return { content: [{
+		type: "text",
+		text: binding.artToCsf(source, { filename: absolutePath }).code
+	}] };
+}
+async function handleGenerateDocs(ctx, binding, args) {
+	const artPath = args?.path;
+	if (!artPath) throw new McpError(ErrorCode.InvalidParams, "path is required");
+	if (!binding.generateArtDoc) throw new McpError(ErrorCode.InternalError, "generateArtDoc not available in native binding");
+	const absolutePath = path.resolve(ctx.projectRoot, artPath);
+	const source = await fs.promises.readFile(absolutePath, "utf-8");
+	const doc = binding.generateArtDoc(source, { filename: absolutePath }, {
+		include_source: args?.includeSource,
+		include_templates: args?.includeTemplates,
+		include_metadata: true
+	});
+	return { content: [{
+		type: "text",
+		text: JSON.stringify({
+			markdown: doc.markdown,
+			title: doc.title,
+			category: doc.category,
+			variantCount: doc.variant_count
+		}, null, 2)
+	}] };
+}
+async function handleGenerateCatalog(ctx, binding, args) {
+	if (!binding.generateArtCatalog) throw new McpError(ErrorCode.InternalError, "generateArtCatalog not available in native binding");
+	const arts = await ctx.scanArtFiles();
+	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)
+	}] };
+}
+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);
+	if (format === "markdown") return { content: [{
+		type: "text",
+		text: generateTokensMarkdown(categories)
+	}] };
+	return { content: [{
+		type: "text",
+		text: JSON.stringify({ categories }, 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 "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);
+		default: throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+	}
+}
+//#endregion
+//#region src/resources.ts
+async function listResources(ctx) {
+	const arts = await ctx.scanArtFiles();
+	const resources = [];
+	for (const [filePath, info] of arts) {
+		const relativePath = path.relative(ctx.projectRoot, filePath);
+		resources.push({
+			uri: `musea://component/${encodeURIComponent(relativePath)}`,
+			name: info.title,
+			description: info.description || `${info.category || "Component"} — ${info.variantCount} variant(s)`,
+			mimeType: "application/json"
+		});
+		resources.push({
+			uri: `musea://docs/${encodeURIComponent(relativePath)}`,
+			name: `${info.title} — Documentation`,
+			description: `Markdown docs for ${info.title}`,
+			mimeType: "text/markdown"
+		});
+	}
+	if (await ctx.resolveTokensPath()) resources.push({
+		uri: "musea://tokens",
+		name: "Design Tokens",
+		description: "Project design tokens (colors, spacing, typography, …)",
+		mimeType: "application/json"
+	});
+	return { resources };
+}
+async function readResource(ctx, uri) {
+	if (uri.startsWith("musea://component/")) {
+		const relativePath = decodeURIComponent(uri.slice(18));
+		const absolutePath = path.resolve(ctx.projectRoot, relativePath);
+		try {
+			const source = await fs.promises.readFile(absolutePath, "utf-8");
+			const parsed = ctx.loadNative().parseArt(source, { filename: absolutePath });
+			return { contents: [{
+				uri,
+				mimeType: "application/json",
+				text: JSON.stringify({
+					path: relativePath,
+					metadata: parsed.metadata,
+					variants: parsed.variants.map((v) => ({
+						name: v.name,
+						template: v.template,
+						isDefault: v.is_default,
+						skipVrt: v.skip_vrt
+					})),
+					hasScriptSetup: parsed.has_script_setup,
+					hasScript: parsed.has_script,
+					styleCount: parsed.style_count
+				}, null, 2)
+			}] };
+		} catch (e) {
+			throw new McpError(ErrorCode.InternalError, `Failed to read component: ${String(e)}`);
+		}
+	}
+	if (uri.startsWith("musea://docs/")) {
+		const relativePath = decodeURIComponent(uri.slice(13));
+		const absolutePath = path.resolve(ctx.projectRoot, relativePath);
+		try {
+			const source = await fs.promises.readFile(absolutePath, "utf-8");
+			const binding = ctx.loadNative();
+			if (!binding.generateArtDoc) throw new McpError(ErrorCode.InternalError, "generateArtDoc not available in native binding");
+			return { contents: [{
+				uri,
+				mimeType: "text/markdown",
+				text: binding.generateArtDoc(source, { filename: absolutePath }).markdown
+			}] };
+		} catch (e) {
+			if (e instanceof McpError) throw e;
+			throw new McpError(ErrorCode.InternalError, `Failed to generate docs: ${String(e)}`);
+		}
+	}
+	if (uri === "musea://tokens") {
+		const resolvedTokensPath = await ctx.resolveTokensPath();
+		if (!resolvedTokensPath) throw new McpError(ErrorCode.InternalError, "No tokens path configured or auto-detected");
+		try {
+			const categories = await parseTokensFromPath(resolvedTokensPath);
+			return { contents: [{
+				uri,
+				mimeType: "application/json",
+				text: JSON.stringify({ categories }, null, 2)
+			}] };
+		} catch (e) {
+			throw new McpError(ErrorCode.InternalError, `Failed to read tokens: ${String(e)}`);
+		}
+	}
+	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,
+				variantCount: parsed.variants.length
+			});
+		} 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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizejs/musea-mcp-server",
-  "version": "0.58.0",
+  "version": "0.60.0",
   "description": "MCP server for building Vue.js design systems - component analysis, documentation, variant generation, and design tokens",
   "keywords": [
     "ai",
@@ -38,7 +38,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "0.5.0",
-    "@vizejs/native": "0.58.0"
+    "@vizejs/native": "0.60.0"
   },
   "devDependencies": {
     "@tsdown/css": "0.21.9",