@vizejs/musea-mcp-server 0.0.1-alpha.100

package/README.md

@@ -0,0 +1,50 @@
+# @vizejs/musea-mcp-server
+
+MCP (Model Context Protocol) server for Musea design system integration.
+
+## Features
+
+- **AI Integration** - Connect Musea to AI assistants
+- **Component Discovery** - Query available components
+- **Design Token Access** - Retrieve design system tokens
+- **Documentation** - Access component docs via MCP
+
+## Installation
+
+```bash
+npm install -g @vizejs/musea-mcp-server
+```
+
+## Usage
+
+### With Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "musea": {
+      "command": "musea-mcp-server",
+      "args": ["--project", "/path/to/project"]
+    }
+  }
+}
+```
+
+### Standalone
+
+```bash
+musea-mcp-server --project ./my-vue-app
+```
+
+## MCP Tools
+
+- `list_components` - List all components
+- `get_component` - Get component details
+- `get_variants` - Get component variants
+- `get_tokens` - Get design tokens
+
+## License
+
+MIT

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { startServer } from "./src-ZT3oDiIm.js";
+
+//#region src/cli.ts
+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

package/dist/index.d.ts

@@ -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.js

@@ -0,0 +1,3 @@
+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

@@ -0,0 +1,57 @@
+{
+  "name": "@vizejs/musea-mcp-server",
+  "version": "0.0.1-alpha.100",
+  "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",
+  "bin": {
+    "musea-mcp": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "vue",
+    "design-system",
+    "component-analysis",
+    "musea",
+    "ai"
+  ],
+  "author": "ubugeeei",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ubugeeei/vize.git",
+    "directory": "npm/musea-mcp-server"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^0.5.0",
+    "@vizejs/native": "0.0.1-alpha.100"
+  },
+  "devDependencies": {
+    "@types/node": "^22.14.0",
+    "tsdown": "^0.9.0",
+    "typescript": "^5.7.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "start": "node dist/cli.js",
+    "lint": "oxlint --deny-warnings --type-aware --tsconfig tsconfig.json",
+    "lint:fix": "oxlint --type-aware --tsconfig tsconfig.json --fix",
+    "fmt": "oxfmt --write src",
+    "fmt:check": "oxfmt src"
+  }
+}