@master/css-mcp 2.0.0-rc.76

package/dist/project.d.ts

@@ -0,0 +1,32 @@
+import MasterCSSMCPContext from "./context.js";
+
+//#region src/project.d.ts
+declare function loadWorkspaceManifest(context: MasterCSSMCPContext): Promise<{
+  status: "loaded";
+  manifest: import("@master/css-engine").MasterCSSManifest;
+  entries: string[];
+  dependencies: string[];
+  warnings: string[];
+  error?: undefined;
+} | {
+  status: "error";
+  entries: string[];
+  dependencies: string[];
+  warnings: string[];
+  error: string;
+  manifest?: undefined;
+}>;
+declare function getWorkspaceInfo(context: MasterCSSMCPContext): Promise<{
+  root: string;
+  roots: string[];
+  packages: import("@master/css-project/workspace").MasterCSSWorkspacePackageResolution;
+  manifest: {
+    error?: string | undefined;
+    status: "loaded" | "error";
+    entries: string[];
+    dependencies: string[];
+    warnings: string[];
+  };
+}>;
+//#endregion
+export { getWorkspaceInfo, loadWorkspaceManifest };

package/dist/project.js

@@ -0,0 +1,42 @@
+import { getErrorMessage } from "./result.js";
+import { loadProjectManifest } from "@master/css-project/manifest";
+import { findCSSManifestEntryFiles } from "@master/css-project/entries";
+import { resolveMasterCSSWorkspacePackages } from "@master/css-project/workspace";
+//#region src/project.ts
+async function loadWorkspaceManifest(context) {
+	try {
+		const result = await loadProjectManifest(context.root);
+		return {
+			status: "loaded",
+			manifest: result.manifest,
+			entries: result.entries,
+			dependencies: result.dependencies ?? [],
+			warnings: result.warnings ?? []
+		};
+	} catch (error) {
+		return {
+			status: "error",
+			entries: [],
+			dependencies: [],
+			warnings: [],
+			error: getErrorMessage(error)
+		};
+	}
+}
+async function getWorkspaceInfo(context) {
+	const [manifest, entries] = await Promise.all([loadWorkspaceManifest(context), findCSSManifestEntryFiles(context.root).catch(() => [])]);
+	return {
+		root: context.root,
+		roots: context.roots,
+		packages: resolveMasterCSSWorkspacePackages(context.root),
+		manifest: {
+			status: manifest.status,
+			entries: manifest.status === "loaded" ? manifest.entries : entries,
+			dependencies: manifest.dependencies,
+			warnings: manifest.warnings,
+			...manifest.status === "error" ? { error: manifest.error } : {}
+		}
+	};
+}
+//#endregion
+export { getWorkspaceInfo, loadWorkspaceManifest };

package/dist/result.d.ts

@@ -0,0 +1,9 @@
+import { CallToolResult, ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
+
+//#region src/result.d.ts
+declare function toJSONText(value: unknown): string;
+declare function jsonToolResult(value: unknown): CallToolResult;
+declare function jsonResourceResult(uri: URL | string, value: unknown): ReadResourceResult;
+declare function getErrorMessage(error: unknown): string;
+//#endregion
+export { getErrorMessage, jsonResourceResult, jsonToolResult, toJSONText };

package/dist/result.js

@@ -0,0 +1,22 @@
+//#region src/result.ts
+function toJSONText(value) {
+	return JSON.stringify(value, null, 2);
+}
+function jsonToolResult(value) {
+	return { content: [{
+		type: "text",
+		text: toJSONText(value)
+	}] };
+}
+function jsonResourceResult(uri, value) {
+	return { contents: [{
+		uri: String(uri),
+		mimeType: "application/json",
+		text: toJSONText(value)
+	}] };
+}
+function getErrorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+//#endregion
+export { getErrorMessage, jsonResourceResult, jsonToolResult, toJSONText };

package/dist/scan.d.ts

@@ -0,0 +1,157 @@
+import MasterCSSMCPContext from "./context.js";
+
+//#region src/scan.d.ts
+interface ScanProjectOptions {
+  patterns?: string[];
+  classes?: string[];
+  includeCss?: boolean;
+}
+interface RenderCSSOptions {
+  html?: string;
+  classList?: string;
+}
+interface InspectClassOptions {
+  className: string;
+  mode?: string;
+}
+declare function resolveSourceFiles(context: MasterCSSMCPContext, patterns?: string[], ignore?: string[]): Promise<string[]>;
+declare function scanProject(context: MasterCSSMCPContext, options?: ScanProjectOptions): Promise<{
+  root: string;
+  manifest: {
+    error?: string | undefined;
+    status: "loaded" | "error";
+    entries: string[];
+    dependencies: string[];
+    warnings: string[];
+  };
+  version: typeof import("@master/css-diagnostics").MASTER_CSS_INSPECTION_REPORT_VERSION;
+  cwd: string;
+  inputs: {
+    patterns: string[];
+    files: string[];
+    classes: string[];
+  };
+  scanner: {
+    counts: {
+      latent: number;
+      valid: number;
+      invalid: number;
+      native: number;
+      usedNative: number;
+      safelist: number;
+      blocklist: number;
+    };
+    classes: {
+      latent: string[];
+      valid: string[];
+      invalid: string[];
+      native: string[];
+      usedNative: string[];
+      safelist: string[];
+      blocklist: string[];
+    };
+    resetDependencies: string[];
+  };
+  stylesheets: {
+    entries: import("@master/css-diagnostics").MasterCSSStylesheetInspection[];
+    dependencies: string[];
+    warnings: string[];
+    errors: import("@master/css-diagnostics").MasterCSSStylesheetError[];
+  };
+  css: {
+    bytes: number;
+    included: boolean;
+    text?: string;
+    emittedGlobals: {
+      variables: number;
+      animations: number;
+    };
+  };
+  missingCSS: {
+    checked: string[];
+    present: import("@master/css-diagnostics").MasterCSSMissingCSSResult[];
+    missing: import("@master/css-diagnostics").MasterCSSMissingCSSResult[];
+  };
+  files: import("@master/css-diagnostics").MasterCSSSourceInspection[];
+  diagnostics: import("@master/css-diagnostics").MasterCSSInspectionDiagnostic[];
+  summary: {
+    files: number;
+    stylesheets: number;
+    diagnostics: number;
+    errors: number;
+    warnings: number;
+    missingCSS: number;
+    invalidClasses: number;
+  };
+}>;
+declare function renderCSS(context: MasterCSSMCPContext, options: RenderCSSOptions): Promise<{
+  manifest: {
+    error?: string | undefined;
+    status: "loaded" | "error";
+    entries: string[];
+  };
+  classes: string[];
+  invalid: string[];
+  css: {
+    bytes: number;
+    text: string;
+  };
+}>;
+declare function inspectClass(context: MasterCSSMCPContext, options: InspectClassOptions): Promise<{
+  manifest: {
+    error?: string | undefined;
+    status: "loaded" | "error";
+    entries: string[];
+  };
+  className: string;
+  mode: string | undefined;
+  valid: boolean;
+  base: string;
+  suffix: string;
+  key: string | undefined;
+  value: string | undefined;
+  keyToken: string | undefined;
+  valueToken: string | undefined;
+  stateToken: string | undefined;
+  important: boolean | undefined;
+  matcherTypes: ("key" | "static" | "pattern" | "variable" | "value")[];
+  variables: {
+    key: string;
+    variable: import("@master/css-language").Variable;
+  }[];
+  rules: {
+    className: string;
+    layer: import("@master/css-engine").MasterCSSManifestUtilityLayerName;
+    type: import("@master/css-language").UtilityType;
+    text: string;
+  }[];
+  css: string;
+}>;
+declare function previewGeneratedCSS(context: MasterCSSMCPContext, options: ScanProjectOptions & {
+  outputPath: string;
+  ttlMs?: number;
+}): Promise<{
+  mode: string;
+  outputPath: string;
+  preview: import("./context.js").PreviewResult;
+  scan: {
+    summary: {
+      files: number;
+      stylesheets: number;
+      diagnostics: number;
+      errors: number;
+      warnings: number;
+      missingCSS: number;
+      invalidClasses: number;
+    };
+    css: {
+      bytes: number;
+      emittedGlobals: {
+        variables: number;
+        animations: number;
+      };
+    };
+  };
+}>;
+//#endregion
+export { InspectClassOptions, RenderCSSOptions, ScanProjectOptions, inspectClass, previewGeneratedCSS, renderCSS, resolveSourceFiles, scanProject };

package/dist/scan.js

@@ -0,0 +1,126 @@
+import { loadWorkspaceManifest } from "./project.js";
+import { createRequire } from "node:module";
+import { resolve } from "node:path";
+import fg from "fast-glob";
+import { createMasterCSSInspectionReport } from "@master/css-diagnostics";
+import { inspectMasterCSSClass } from "@master/css-engine/inspect";
+import { createCSSWithNativeDeclarations } from "@master/css-validator/native-declaration";
+import { parseHTML } from "@master/css-server";
+//#region src/scan.ts
+const DEFAULT_SOURCE_PATTERNS = ["**/*.{html,htm,js,jsx,cjs,ts,tsx,mts,cts,svelte,astro,vue,md,mdx,pug,php}"];
+const DEFAULT_IGNORE_PATTERNS = ["**/node_modules/**", "node_modules"];
+const defaultManifest = createRequire(import.meta.url)("@master/css-preset/default-manifest.json");
+async function resolveSourceFiles(context, patterns = DEFAULT_SOURCE_PATTERNS, ignore = DEFAULT_IGNORE_PATTERNS) {
+	context.validateGlobPatterns(patterns);
+	const sources = await fg(patterns, {
+		cwd: context.root,
+		ignore,
+		onlyFiles: true
+	});
+	return Promise.all(sources.map((source) => context.resolveExistingFile(source)));
+}
+async function scanProject(context, options = {}) {
+	const [report, manifest] = await Promise.all([createMasterCSSInspectionReport({
+		cwd: context.root,
+		patterns: options.patterns,
+		classes: options.classes,
+		includeCss: options.includeCss,
+		resolveExistingFile: (filePath) => context.resolveExistingFile(filePath),
+		validatePatterns: (patterns) => context.validateGlobPatterns(patterns)
+	}), loadWorkspaceManifest(context)]);
+	return {
+		...report,
+		root: context.root,
+		manifest: {
+			status: manifest.status,
+			entries: manifest.entries,
+			dependencies: manifest.dependencies,
+			warnings: manifest.warnings,
+			...manifest.status === "error" ? { error: manifest.error } : {}
+		}
+	};
+}
+async function renderCSS(context, options) {
+	const manifest = await loadWorkspaceManifest(context);
+	const css = createCSSWithNativeDeclarations(manifest.status === "loaded" ? manifest.manifest : defaultManifest);
+	const classes = options.html ? parseHTML(options.html).classes : (options.classList ?? "").split(/\s+/).map((className) => className.trim()).filter(Boolean);
+	const invalid = [];
+	for (const className of classes) {
+		const rules = css.generate(className);
+		if (rules.length) for (const rule of rules) rule.layer.insert(rule);
+		else invalid.push(className);
+	}
+	return {
+		manifest: {
+			status: manifest.status,
+			entries: manifest.entries,
+			...manifest.status === "error" ? { error: manifest.error } : {}
+		},
+		classes,
+		invalid,
+		css: {
+			bytes: css.text.length,
+			text: css.text
+		}
+	};
+}
+async function inspectClass(context, options) {
+	const manifest = await loadWorkspaceManifest(context);
+	const inspection = inspectMasterCSSClass(createCSSWithNativeDeclarations(manifest.status === "loaded" ? manifest.manifest : defaultManifest), options.className, options.mode);
+	const rules = inspection.rules.map((rule) => ({
+		className: rule.name,
+		layer: rule.layerName,
+		type: rule.type,
+		text: rule.text
+	}));
+	return {
+		manifest: {
+			status: manifest.status,
+			entries: manifest.entries,
+			...manifest.status === "error" ? { error: manifest.error } : {}
+		},
+		className: options.className,
+		mode: options.mode,
+		valid: rules.length > 0,
+		base: inspection.base,
+		suffix: inspection.suffix,
+		key: inspection.key,
+		value: inspection.value,
+		keyToken: inspection.keyToken,
+		valueToken: inspection.valueToken,
+		stateToken: inspection.stateToken,
+		important: inspection.important,
+		matcherTypes: inspection.matcherTypes,
+		variables: inspection.variableEntries.map(({ key, variable }) => ({
+			key,
+			variable
+		})),
+		rules,
+		css: rules.map((rule) => rule.text).join("")
+	};
+}
+async function previewGeneratedCSS(context, options) {
+	const report = await scanProject(context, {
+		patterns: options.patterns,
+		classes: options.classes,
+		includeCss: true
+	});
+	const preview = await context.createPreview([{
+		filePath: resolve(context.root, options.outputPath),
+		afterText: report.css.text ?? ""
+	}], options.ttlMs);
+	return {
+		mode: "generated-css",
+		outputPath: await context.resolveWritableFile(options.outputPath),
+		preview,
+		scan: {
+			summary: report.summary,
+			css: {
+				bytes: report.css.bytes,
+				emittedGlobals: report.css.emittedGlobals
+			}
+		}
+	};
+}
+//#endregion
+export { inspectClass, previewGeneratedCSS, renderCSS, resolveSourceFiles, scanProject };

package/dist/server.d.ts

@@ -0,0 +1,12 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import MasterCSSMCPContext, { MasterCSSMCPContextOptions } from "./context.js";
+
+//#region src/server.d.ts
+interface MasterCSSMCPServerInstance {
+  server: McpServer;
+  context: MasterCSSMCPContext;
+}
+declare function createMasterCSSMCPServer(options?: MasterCSSMCPContextOptions): MasterCSSMCPServerInstance;
+declare function startStdioServer(options?: MasterCSSMCPContextOptions): Promise<McpServer>;
+//#endregion
+export { MasterCSSMCPServerInstance, createMasterCSSMCPServer, startStdioServer };

package/dist/server.js

@@ -0,0 +1,244 @@
+import MasterCSSMCPContext from "./context.js";
+import { jsonResourceResult, jsonToolResult } from "./result.js";
+import { getWorkspaceInfo, loadWorkspaceManifest } from "./project.js";
+import { inspectClass, previewGeneratedCSS, renderCSS, scanProject } from "./scan.js";
+import { suggestSyntax } from "./language.js";
+import { lintContent, lintProject, previewLintFixes } from "./lint.js";
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import * as z from "zod/v4";
+//#region src/server.ts
+function readPackageVersion() {
+	const directory = dirname(fileURLToPath(import.meta.url));
+	try {
+		return JSON.parse(readFileSync(resolve(directory, "../package.json"), "utf8")).version || "0.0.0";
+	} catch {
+		return "0.0.0";
+	}
+}
+function registerResources(server, context) {
+	server.registerResource("mastercss-workspace-manifest", "mastercss://workspace/manifest", {
+		title: "Master CSS Workspace Manifest",
+		description: "Loaded Master CSS project manifest status and entries.",
+		mimeType: "application/json"
+	}, async (uri) => jsonResourceResult(uri, await loadWorkspaceManifest(context)));
+	server.registerResource("mastercss-workspace-entries", "mastercss://workspace/entries", {
+		title: "Master CSS Workspace Entries",
+		description: "Discovered Master CSS manifest entry files.",
+		mimeType: "application/json"
+	}, async (uri) => {
+		const manifest = await loadWorkspaceManifest(context);
+		return jsonResourceResult(uri, {
+			root: context.root,
+			entries: manifest.entries
+		});
+	});
+	server.registerResource("mastercss-workspace-packages", "mastercss://workspace/packages", {
+		title: "Master CSS Workspace Packages",
+		description: "Resolved Master CSS package locations for this workspace.",
+		mimeType: "application/json"
+	}, async (uri) => {
+		return jsonResourceResult(uri, (await getWorkspaceInfo(context)).packages);
+	});
+}
+function registerPrompts(server) {
+	server.registerPrompt("debug-missing-css", {
+		title: "Debug Missing CSS",
+		description: "Guide an assistant through debugging classes that are not producing CSS."
+	}, () => ({ messages: [{
+		role: "user",
+		content: {
+			type: "text",
+			text: "Use the Master CSS MCP tools to scan the project, inspect the missing class names, compare generated CSS, and identify whether the issue is extraction, manifest loading, invalid syntax, native CSS pruning, or stylesheet entry configuration."
+		}
+	}] }));
+	server.registerPrompt("review-mastercss-classes", {
+		title: "Review Master CSS Classes",
+		description: "Review class lists for invalid, conflicting, non-canonical, or unsorted classes."
+	}, () => ({ messages: [{
+		role: "user",
+		content: {
+			type: "text",
+			text: "Run Master CSS lint diagnostics through the MCP server, lead with bugs or CSS output risks, and only propose write previews when fixes are safe and scoped to the workspace."
+		}
+	}] }));
+	server.registerPrompt("migrate-to-mastercss", {
+		title: "Migrate To Master CSS",
+		description: "Plan a migration from existing markup/styles to Master CSS classes."
+	}, () => ({ messages: [{
+		role: "user",
+		content: {
+			type: "text",
+			text: "Inspect the workspace with Master CSS MCP tools, identify current stylesheet entries and class extraction coverage, then plan migration steps that preserve CSS output unless a deliberate behavior change is requested."
+		}
+	}] }));
+}
+function registerTools(server, context) {
+	server.registerTool("mastercss_workspace_info", {
+		title: "Master CSS Workspace Info",
+		description: "Report workspace roots, resolved Master CSS packages, and project manifest status.",
+		annotations: {
+			readOnlyHint: true,
+			destructiveHint: false,
+			idempotentHint: true,
+			openWorldHint: false
+		}
+	}, async () => jsonToolResult(await getWorkspaceInfo(context)));
+	server.registerTool("mastercss_inspect_class", {
+		title: "Inspect Master CSS Class",
+		description: "Inspect one Master CSS class and return semantic parts, generated rules, variables, and CSS text.",
+		inputSchema: {
+			className: z.string().min(1),
+			mode: z.string().optional()
+		},
+		annotations: {
+			readOnlyHint: true,
+			destructiveHint: false,
+			idempotentHint: true,
+			openWorldHint: false
+		}
+	}, async (input) => jsonToolResult(await inspectClass(context, input)));
+	server.registerTool("mastercss_render_css", {
+		title: "Render Master CSS",
+		description: "Generate CSS from an HTML fragment or a whitespace-separated class list.",
+		inputSchema: {
+			html: z.string().optional(),
+			classList: z.string().optional()
+		},
+		annotations: {
+			readOnlyHint: true,
+			destructiveHint: false,
+			idempotentHint: true,
+			openWorldHint: false
+		}
+	}, async (input) => jsonToolResult(await renderCSS(context, input)));
+	server.registerTool("mastercss_scan_project", {
+		title: "Scan Master CSS Project",
+		description: "Scan source files, register stylesheet entries, and report scanner state and generated CSS metadata.",
+		inputSchema: {
+			patterns: z.array(z.string()).optional(),
+			classes: z.array(z.string()).optional(),
+			includeCss: z.boolean().optional()
+		},
+		annotations: {
+			readOnlyHint: true,
+			destructiveHint: false,
+			idempotentHint: true,
+			openWorldHint: false
+		}
+	}, async (input) => jsonToolResult(await scanProject(context, input)));
+	server.registerTool("mastercss_lint_project", {
+		title: "Lint Master CSS Project",
+		description: "Run Master CSS class-list diagnostics and return fix proposals without writing files.",
+		inputSchema: {
+			patterns: z.array(z.string()).optional(),
+			rules: z.string().optional()
+		},
+		annotations: {
+			readOnlyHint: true,
+			destructiveHint: false,
+			idempotentHint: true,
+			openWorldHint: false
+		}
+	}, async (input) => jsonToolResult(await lintProject(context, input)));
+	server.registerTool("mastercss_lint_content", {
+		title: "Lint Master CSS Content",
+		description: "Run Master CSS class-list diagnostics on an in-memory source buffer without writing files.",
+		inputSchema: {
+			content: z.string(),
+			filePath: z.string(),
+			rules: z.string().optional()
+		},
+		annotations: {
+			readOnlyHint: true,
+			destructiveHint: false,
+			idempotentHint: true,
+			openWorldHint: false
+		}
+	}, async (input) => jsonToolResult(await lintContent(context, input)));
+	server.registerTool("mastercss_suggest_syntax", {
+		title: "Suggest Master CSS Syntax",
+		description: "Return language-service completions and hover context for a document position.",
+		inputSchema: {
+			content: z.string(),
+			filePath: z.string(),
+			position: z.object({
+				line: z.number().int().min(0),
+				character: z.number().int().min(0)
+			}),
+			triggerCharacter: z.string().optional(),
+			limit: z.number().int().min(1).max(200).optional()
+		},
+		annotations: {
+			readOnlyHint: true,
+			destructiveHint: false,
+			idempotentHint: true,
+			openWorldHint: false
+		}
+	}, async (input) => jsonToolResult(await suggestSyntax(context, input)));
+	server.registerTool("mastercss_preview_fixes", {
+		title: "Preview Master CSS Fixes",
+		description: "Create a diff preview for lint fixes or generated CSS output and return a confirmation token.",
+		inputSchema: {
+			mode: z.enum(["lint-fixes", "generated-css"]).optional(),
+			patterns: z.array(z.string()).optional(),
+			rules: z.string().optional(),
+			includeDirectiveFixes: z.boolean().optional(),
+			outputPath: z.string().optional(),
+			ttlMs: z.number().int().min(1e3).max(3600 * 1e3).optional()
+		},
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: false,
+			openWorldHint: false
+		}
+	}, async (input) => {
+		if (input.mode === "generated-css") {
+			if (!input.outputPath) throw new Error("outputPath is required when mode is \"generated-css\".");
+			return jsonToolResult(await previewGeneratedCSS(context, {
+				patterns: input.patterns,
+				includeCss: true,
+				outputPath: input.outputPath,
+				ttlMs: input.ttlMs
+			}));
+		}
+		return jsonToolResult(await previewLintFixes(context, input));
+	});
+	server.registerTool("mastercss_apply_preview", {
+		title: "Apply Master CSS Preview",
+		description: "Apply a previously generated preview token after validating hashes and workspace containment.",
+		inputSchema: { confirmToken: z.string().min(1) },
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: true,
+			idempotentHint: false,
+			openWorldHint: false
+		}
+	}, async (input) => jsonToolResult(await context.applyPreview(input.confirmToken)));
+}
+function createMasterCSSMCPServer(options = {}) {
+	const context = new MasterCSSMCPContext(options);
+	const server = new McpServer({
+		name: "@master/css-mcp",
+		version: readPackageVersion()
+	});
+	registerResources(server, context);
+	registerPrompts(server);
+	registerTools(server, context);
+	return {
+		server,
+		context
+	};
+}
+async function startStdioServer(options = {}) {
+	const { server } = createMasterCSSMCPServer(options);
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+	return server;
+}
+//#endregion
+export { createMasterCSSMCPServer, startStdioServer };