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

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,12 @@
+#!/usr/bin/env node
+import { startServer } from "./src-DMEJQckJ.js";
+
+//#region src/cli.ts
+const projectRoot = process.argv[2] || process.env.MUSEA_PROJECT_ROOT || process.cwd();
+console.error(`[musea-mcp] Starting server for project: ${projectRoot}`);
+startServer(projectRoot).catch((error) => {
+	console.error("[musea-mcp] Failed to start:", error);
+	process.exit(1);
+});
+
+//#endregion

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+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[];
+}): Server;
+/**
+ * Start the MCP server with stdio transport.
+ */
+declare function startServer(projectRoot: 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-DMEJQckJ.js";
+
+export { createMuseaServer, src_default as default, startServer };

package/dist/src-DMEJQckJ.js

@@ -0,0 +1,313 @@
+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 };

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@vizejs/musea-mcp-server",
+  "version": "0.0.1-alpha.11",
+  "description": "MCP server for Musea - AI-accessible component gallery",
+  "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",
+    "component-gallery",
+    "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.33"
+  },
+  "devDependencies": {
+    "@types/node": "^22.14.0",
+    "tsdown": "^0.9.0",
+    "typescript": "^5.7.0"
+  },
+  "publishConfig": {
+    "provenance": true,
+    "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"
+  }
+}