@vizejs/musea-mcp-server 0.0.1-alpha.74 → 0.0.1-alpha.75

package/dist/cli.js

@@ -1,10 +1,15 @@
 #!/usr/bin/env node
-import { startServer } from "./src-DMEJQckJ.js";
+import { startServer } from "./src-ZT3oDiIm.js";
 
 //#region src/cli.ts
-const projectRoot = process.argv[2] || process.env.MUSEA_PROJECT_ROOT || process.cwd();
+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}`);
-startServer(projectRoot).catch((error) => {
+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);
 });

package/dist/index.d.ts

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

package/dist/index.js

@@ -1,3 +1,3 @@
-import { createMuseaServer, src_default, startServer } from "./src-DMEJQckJ.js";
+import { createMuseaServer, src_default, startServer } from "./src-ZT3oDiIm.js";
 
 export { createMuseaServer, src_default as default, startServer };

package/dist/src-ZT3oDiIm.js

@@ -0,0 +1,740 @@
+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";
+import { createRequire } from "node:module";
+
+//#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/tokens.ts
+async function parseTokensFromPath(tokensPath) {
+	const stat = await fs.promises.stat(tokensPath);
+	if (stat.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$1 = await fs.promises.readFile(filePath, "utf-8");
+			const tokens$1 = JSON.parse(content$1);
+			const categoryName = path.basename(entry.name, path.extname(entry.name)).replace(".tokens", "");
+			categories.push({
+				name: formatCategoryName(categoryName),
+				tokens: extractTokenValues(tokens$1),
+				subcategories: extractSubcats(tokens$1)
+			});
+		}
+		return categories;
+	}
+	const content = await fs.promises.readFile(tokensPath, "utf-8");
+	const tokens = JSON.parse(content);
+	return flattenTokenStructure(tokens);
+}
+function generateTokensMarkdown(categories) {
+	const renderCategory = (category, level = 2) => {
+		const heading = "#".repeat(level);
+		let md = `\n${heading} ${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.ts
+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)"
+				}
+			}
+		}
+	}
+];
+async function handleToolCall(ctx, name, args) {
+	const binding = ctx.loadNative();
+	switch (name) {
+		case "analyze_component": {
+			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)
+			}] };
+		}
+		case "get_palette": {
+			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)
+			}] };
+		}
+		case "list_components": {
+			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)
+			}] };
+		}
+		case "get_component": {
+			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)
+			}] };
+		}
+		case "get_variant": {
+			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 parsed = binding.parseArt(source, { filename: absolutePath });
+			const variant = parsed.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)
+			}] };
+		}
+		case "search_components": {
+			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)
+			}] };
+		}
+		case "generate_variants": {
+			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 analysis = binding.analyzeSfc(source, { filename: absolutePath });
+			const props = analysis.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)
+			}] };
+		}
+		case "generate_csf": {
+			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 csf = binding.artToCsf(source, { filename: absolutePath });
+			return { content: [{
+				type: "text",
+				text: csf.code
+			}] };
+		}
+		case "generate_docs": {
+			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)
+			}] };
+		}
+		case "generate_catalog": {
+			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)
+			}] };
+		}
+		case "get_tokens": {
+			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)
+			}] };
+		}
+		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"
+		});
+	}
+	const resolvedTokensPath = await ctx.resolveTokensPath();
+	if (resolvedTokensPath) 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 binding = ctx.loadNative();
+			const parsed = binding.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");
+			const doc = binding.generateArtDoc(source, { filename: absolutePath });
+			return { contents: [{
+				uri,
+				mimeType: "text/markdown",
+				text: doc.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
+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 = 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 = 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);
+		const candidates = [
+			"tokens",
+			"design-tokens",
+			"style-dictionary"
+		];
+		for (const dir of candidates) {
+			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");
+}
+var src_default = createMuseaServer;
+
+//#endregion
+export { createMuseaServer, src_default, startServer };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vizejs/musea-mcp-server",
-  "version": "0.0.1-alpha.74",
-  "description": "MCP server for Musea - AI-accessible component gallery",
+  "version": "0.0.1-alpha.75",
+  "description": "MCP server for building Vue.js design systems - component analysis, documentation, variant generation, and design tokens",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -21,7 +21,8 @@
     "mcp",
     "model-context-protocol",
     "vue",
-    "component-gallery",
+    "design-system",
+    "component-analysis",
     "musea",
     "ai"
   ],
@@ -34,7 +35,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^0.5.0",
-    "@vizejs/native": "0.0.1-alpha.74"
+    "@vizejs/native": "0.0.1-alpha.75"
   },
   "devDependencies": {
     "@types/node": "^22.14.0",

package/dist/src-DMEJQckJ.js

@@ -1,313 +0,0 @@
-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";
-import { createRequire } from "node:module";
-
-//#region src/index.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)}`);
-	}
-}
-/**
-* Create and configure the MCP server.
-*/
-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/**"];
-	let artCache = 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 = 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,
-				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;
-	}
-	server.setRequestHandler(ListResourcesRequestSchema, async () => {
-		const arts = await scanArtFiles();
-		const resources = [];
-		for (const [filePath, info] of arts) {
-			const relativePath = path.relative(projectRoot, filePath);
-			resources.push({
-				uri: `musea://art/${encodeURIComponent(relativePath)}`,
-				name: info.title,
-				description: info.description || `${info.category || "Component"} with ${info.variantCount} variants`,
-				mimeType: "application/json"
-			});
-		}
-		return { resources };
-	});
-	server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
-		const { uri } = request.params;
-		if (!uri.startsWith("musea://art/")) throw new McpError(ErrorCode.InvalidRequest, `Unknown resource URI: ${uri}`);
-		const relativePath = decodeURIComponent(uri.slice(12));
-		const absolutePath = path.resolve(projectRoot, relativePath);
-		try {
-			const source = await fs.promises.readFile(absolutePath, "utf-8");
-			const binding = loadNative();
-			const parsed = binding.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 art file: ${String(e)}`);
-		}
-	});
-	server.setRequestHandler(ListToolsRequestSchema, async () => {
-		return { tools: [
-			{
-				name: "list_components",
-				description: "List all components (Art files) in the project with their metadata",
-				inputSchema: {
-					type: "object",
-					properties: {
-						category: {
-							type: "string",
-							description: "Filter by category"
-						},
-						tag: {
-							type: "string",
-							description: "Filter by tag"
-						}
-					}
-				}
-			},
-			{
-				name: "get_component",
-				description: "Get detailed information about a specific component",
-				inputSchema: {
-					type: "object",
-					properties: { path: {
-						type: "string",
-						description: "Path to the Art file (relative to project root)"
-					} },
-					required: ["path"]
-				}
-			},
-			{
-				name: "get_variant",
-				description: "Get a specific variant from a component",
-				inputSchema: {
-					type: "object",
-					properties: {
-						path: {
-							type: "string",
-							description: "Path to the Art file"
-						},
-						variant: {
-							type: "string",
-							description: "Name of the variant"
-						}
-					},
-					required: ["path", "variant"]
-				}
-			},
-			{
-				name: "generate_csf",
-				description: "Generate Storybook CSF 3.0 code from an Art file",
-				inputSchema: {
-					type: "object",
-					properties: { path: {
-						type: "string",
-						description: "Path to the Art file"
-					} },
-					required: ["path"]
-				}
-			},
-			{
-				name: "search_components",
-				description: "Search components by title, description, or tags",
-				inputSchema: {
-					type: "object",
-					properties: { query: {
-						type: "string",
-						description: "Search query"
-					} },
-					required: ["query"]
-				}
-			}
-		] };
-	});
-	server.setRequestHandler(CallToolRequestSchema, async (request) => {
-		const { name, arguments: args } = request.params;
-		const binding = loadNative();
-		switch (name) {
-			case "list_components": {
-				const arts = await 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(projectRoot, r.path),
-						title: r.title,
-						description: r.description,
-						category: r.category,
-						tags: r.tags,
-						variantCount: r.variantCount
-					})), null, 2)
-				}] };
-			}
-			case "get_component": {
-				const artPath = args?.path;
-				if (!artPath) throw new McpError(ErrorCode.InvalidParams, "path is required");
-				const absolutePath = path.resolve(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)
-				}] };
-			}
-			case "get_variant": {
-				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(projectRoot, artPath);
-				const source = await fs.promises.readFile(absolutePath, "utf-8");
-				const parsed = binding.parseArt(source, { filename: absolutePath });
-				const variant = parsed.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)
-				}] };
-			}
-			case "generate_csf": {
-				const artPath = args?.path;
-				if (!artPath) throw new McpError(ErrorCode.InvalidParams, "path is required");
-				const absolutePath = path.resolve(projectRoot, artPath);
-				const source = await fs.promises.readFile(absolutePath, "utf-8");
-				const csf = binding.artToCsf(source, { filename: absolutePath });
-				return { content: [{
-					type: "text",
-					text: csf.code
-				}] };
-			}
-			case "search_components": {
-				const query = (args?.query)?.toLowerCase();
-				if (!query) throw new McpError(ErrorCode.InvalidParams, "query is required");
-				const arts = await 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(projectRoot, r.path),
-						title: r.title,
-						description: r.description,
-						category: r.category,
-						tags: r.tags
-					})), null, 2)
-				}] };
-			}
-			default: throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
-		}
-	});
-	return server;
-}
-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);
-}
-/**
-* Start the MCP server with stdio transport.
-*/
-async function startServer(projectRoot) {
-	const server = createMuseaServer({ projectRoot });
-	const transport = new StdioServerTransport();
-	await server.connect(transport);
-	console.error("[musea-mcp] Server started");
-}
-var src_default = createMuseaServer;
-
-//#endregion
-export { createMuseaServer, src_default, startServer };