@master/css-mcp 2.0.0-rc.76 → 2.0.0-rc.78

package/README.md

@@ -1,6 +1,6 @@
 # Master CSS MCP Server
 
-Model Context Protocol server for Master CSS tooling. It lets AI clients inspect a Master CSS workspace, read the active project manifest, scan source files, inspect classes, render generated CSS, run lint diagnostics, request syntax suggestions, and apply reviewed fix previews.
+Model Context Protocol server for Master CSS tooling. It lets AI clients inspect a Master CSS workspace, audit setup, read the active project manifest, inspect CSS-first directives, trace classes through extraction and generated CSS, render or compare CSS output, run lint diagnostics, request syntax suggestions, apply reviewed fix previews, and route Master CSS repository contributor work through deterministic context tools.
 
 ## Installation
 
@@ -31,27 +31,57 @@ Most MCP clients accept a command and arguments for stdio servers:
 
 Use an absolute `--root` path so the server resolves the intended workspace.
 
-## Tools
+## Project tools
 
 | Tool | Use |
 | --- | --- |
 | `mastercss_workspace_info` | Report workspace roots, resolved packages, and manifest status. |
+| `mastercss_setup_audit` | Audit package, entry stylesheet, manifest, integration, and package-resolution setup. |
 | `mastercss_inspect_class` | Inspect one class and return generated rules and CSS text. |
+| `mastercss_trace_class` | Trace one class through source extraction, scanner state, missing CSS classification, and generated rules. |
+| `mastercss_extract_classes` | Extract class positions and validation summaries from files or an in-memory source buffer. |
+| `mastercss_inspect_directives` | Inspect CSS-first directives and report manifest, dependency, warning, and CSS effects. |
 | `mastercss_render_css` | Generate CSS from HTML or a class list. |
 | `mastercss_scan_project` | Scan sources, check optional classes, and report scanner state, stylesheet entries, generated CSS metadata, and missing CSS diagnostics. |
+| `mastercss_manifest_query` | Query active manifest tokens, utilities, variants, modes, at-rules, and aliases. |
+| `mastercss_css_compare` | Compare generated CSS for before/after class lists, HTML fragments, or source buffers. |
 | `mastercss_lint_project` | Run class-list diagnostics for workspace files without writing files. |
 | `mastercss_lint_content` | Run class-list diagnostics on an in-memory source buffer without writing files. |
 | `mastercss_suggest_syntax` | Return language-service completions and hover context. |
 | `mastercss_preview_fixes` | Create a diff preview and confirmation token. |
+| `mastercss_preview_directive_format` | Preview Master CSS directive formatting for files, or format in-memory content without writing. |
 | `mastercss_apply_preview` | Apply a preview after token, hash, and workspace checks. |
 
+## Contributor tools
+
+These read-only tools are for Master CSS repository contributors, AI coding agents, review bots, and CI support. They expose repository-specific routing as low-token JSON instead of asking an agent to repeatedly infer package ownership, risk, and validation from raw files. In non-Master CSS workspaces they return limited package data instead of guessing.
+
+| Tool | Use |
+| --- | --- |
+| `mastercss_repo_context` | Route changed paths or a diff to affected packages, required context files, risks, and validation commands. |
+| `mastercss_change_impact` | Summarize contributor change risk for CSS output, runtime, extraction, language tooling, ESLint, docs, and package boundaries. |
+| `mastercss_test_router` | Return focused validation commands for contributor changes. |
+| `mastercss_package_graph` | Report workspace package ownership, scripts, exports, workspace dependencies, and dependents. |
+
+## Prompt templates
+
+| Prompt | Use |
+| --- | --- |
+| `debug-missing-css` | Debug scanner coverage, manifest loading, invalid syntax, native CSS pruning, and stylesheet entry configuration. |
+| `review-mastercss-classes` | Review class lists and propose only safe, scoped write previews. |
+| `migrate-to-mastercss` | Audit an existing styling system and produce an incremental migration plan before editing. |
+
+Use `migrate-to-mastercss` when an MCP-capable AI client is helping migrate CSS, CSS Modules, Sass, Tailwind CSS, CSS-in-JS, component-library styling, or Master CSS v1. The prompt asks the agent to inspect the workspace first, identify stylesheet entries and source extraction coverage, recommend a rendering mode, choose the first reviewable migration batch, and list validation commands and visual review risks.
+
+The migration prompt is a planning workflow, not a one-shot converter. Keep the previous styling system in place until each migrated slice builds, runs, and visually matches the old UI.
+
 ## Machine-readable results
 
-Project scan and lint reports use `version: 1`. Tooling can rely on stable top-level fields such as `version`, `root`, `manifest`, `inputs`, `files`, `diagnostics`, and `summary` when present. Nested diagnostic `data` objects may gain additional fields over time.
+Project scan, lint, setup audit, directive inspection, class extraction, class tracing, CSS comparison, manifest query, and contributor routing reports use `version: 1`. Tooling can rely on stable top-level fields such as `version`, `root`, `manifest`, `inputs`, `files`, `diagnostics`, `risks`, `validation`, and `summary` when present. Nested diagnostic `data` objects may gain additional fields over time.
 
 ## Safety
 
-Read-only tools do not write files. File writes use a two-step preview/apply flow, validate workspace containment, and verify original file hashes before writing.
+Read-only tools do not write files. File writes use a two-step preview/apply flow, validate workspace containment, and verify original file hashes before writing. Lint fixes, generated CSS output writes, and directive formatting for files all use preview tokens before `mastercss_apply_preview` can write anything.
 
 ## Related docs
 

package/dist/bin/index.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import { startStdioServer } from "../server.js";
-import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { readFileSync } from "node:fs";
 //#region src/bin/index.ts
 function readPackageVersion() {
 	const directory = dirname(fileURLToPath(import.meta.url));

package/dist/classes.d.ts

@@ -0,0 +1,237 @@
+import MasterCSSMCPContext from "./context.js";
+
+//#region src/classes.d.ts
+interface ExtractClassesOptions {
+  content?: string;
+  filePath?: string;
+  patterns?: string[];
+  includeRules?: boolean;
+}
+interface TraceClassOptions {
+  className: string;
+  patterns?: string[];
+  includeCss?: boolean;
+  mode?: string;
+}
+declare function extractClasses(context: MasterCSSMCPContext, options?: ExtractClassesOptions): Promise<{
+  version: number;
+  root: string;
+  manifest: {
+    error?: string | undefined;
+    status: "loaded" | "error";
+    entries: string[];
+  };
+  inputs: {
+    mode: string;
+    filePath: string;
+    patterns?: undefined;
+    files?: undefined;
+  };
+  files: {
+    filePath: string;
+    languageId: string;
+    classes: {
+      raw: string;
+      token: string;
+      range: {
+        start: number;
+        end: number;
+      };
+      loc: {
+        start: import("vscode-languageserver-textdocument").Position;
+        end: import("vscode-languageserver-textdocument").Position;
+      };
+      contextRange: {
+        start: number;
+        end: number;
+      };
+      sourceKind: string;
+      status: string;
+      valid: boolean;
+      inspection: {
+        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: ("static" | "pattern" | "key" | "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;
+        }[];
+      };
+    }[];
+  }[];
+  summary: {
+    files: number;
+    classes: number;
+    valid: number;
+    invalid: number;
+    diagnostics?: undefined;
+  };
+  scanner?: undefined;
+  diagnostics?: undefined;
+} | {
+  version: number;
+  root: string;
+  manifest: {
+    error?: string | undefined;
+    status: "loaded" | "error";
+    entries: string[];
+  };
+  inputs: {
+    mode: string;
+    patterns: string[];
+    files: string[];
+    filePath?: undefined;
+  };
+  files: {
+    filePath: string;
+    languageId: string;
+    classes: {
+      raw: string;
+      token: string;
+      range: {
+        start: number;
+        end: number;
+      };
+      loc: {
+        start: import("vscode-languageserver-textdocument").Position;
+        end: import("vscode-languageserver-textdocument").Position;
+      };
+      contextRange: {
+        start: number;
+        end: number;
+      };
+      sourceKind: string;
+      status: string;
+      valid: boolean;
+      inspection: {
+        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: ("static" | "pattern" | "key" | "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;
+        }[];
+      };
+    }[];
+  }[];
+  scanner: {
+    counts: {
+      latent: number;
+      valid: number;
+      invalid: number;
+      native: number;
+      usedNative: number;
+      safelist: number;
+      blocklist: number;
+    };
+  };
+  diagnostics: import("@master/css-diagnostics").MasterCSSInspectionDiagnostic[];
+  summary: {
+    files: number;
+    classes: number;
+    valid: number;
+    invalid: number;
+    diagnostics: number;
+  };
+}>;
+declare function traceClass(context: MasterCSSMCPContext, options: TraceClassOptions): Promise<{
+  version: number;
+  root: string;
+  manifest: {
+    error?: string | undefined;
+    status: "loaded" | "error";
+    entries: string[];
+  };
+  inputs: {
+    className: string;
+    patterns: string[];
+    mode: string | undefined;
+  };
+  className: string;
+  status: "present" | "missing";
+  reason: "generated" | "native-css" | "invalid" | "safelist" | "blocklisted" | "not-detected";
+  detected: boolean;
+  occurrences: {
+    filePath: string;
+    source: string;
+    statuses: string[];
+  }[];
+  inspection: {
+    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: ("static" | "pattern" | "key" | "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;
+    }[];
+  };
+  scanner: {
+    counts: {
+      latent: number;
+      valid: number;
+      invalid: number;
+      native: number;
+      usedNative: number;
+      safelist: number;
+      blocklist: number;
+    };
+    safelist: boolean;
+    blocklist: boolean;
+  };
+  css: {
+    text?: string | undefined;
+    included: boolean;
+    bytes: number;
+    emittedGlobals: {
+      variables: number;
+      animations: number;
+    };
+  };
+  diagnostics: import("@master/css-diagnostics").MasterCSSInspectionDiagnostic[];
+  summary: {
+    status: "present" | "missing";
+    reason: "generated" | "native-css" | "invalid" | "safelist" | "blocklisted" | "not-detected";
+    detected: boolean;
+    valid: boolean;
+    rules: number;
+    diagnostics: number;
+  };
+}>;
+//#endregion
+export { ExtractClassesOptions, TraceClassOptions, extractClasses, traceClass };

package/dist/classes.js

@@ -0,0 +1,224 @@
+import { createMCPTextDocument, getLanguageId } from "./document.js";
+import { loadWorkspaceManifest } from "./project.js";
+import { resolveSourceFiles, scanProject } from "./scan.js";
+import { createRequire } from "node:module";
+import { readFile } from "node:fs/promises";
+import CSSLanguageService from "@master/css-language-service";
+import { inspectMasterCSSClass } from "@master/css-engine/inspect";
+import { createCSSWithNativeDeclarations } from "@master/css-validator/native-declaration";
+//#region src/classes.ts
+const CLASS_EXTRACTION_VERSION = 1;
+const CLASS_TRACE_VERSION = 1;
+const defaultManifest = createRequire(import.meta.url)("@master/css-preset/default-manifest.json");
+async function createCSS(context) {
+	const manifest = await loadWorkspaceManifest(context);
+	return {
+		manifest,
+		css: createCSSWithNativeDeclarations(manifest.status === "loaded" ? manifest.manifest : defaultManifest)
+	};
+}
+function createLanguageService(manifest) {
+	return new CSSLanguageService(manifest.status === "loaded" ? { manifest: manifest.manifest } : void 0);
+}
+function compactInspection(css, className, mode, includeRules = false) {
+	const inspection = inspectMasterCSSClass(css, className, mode);
+	return {
+		valid: inspection.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: includeRules ? inspection.rules.map((rule) => ({
+			className: rule.name,
+			layer: rule.layerName,
+			type: rule.type,
+			text: rule.text
+		})) : inspection.rules.map((rule) => ({
+			className: rule.name,
+			layer: rule.layerName,
+			type: rule.type
+		}))
+	};
+}
+function classifyExtractedClass(token, inspection, discovered) {
+	if (discovered?.valid.includes(token)) return "generated";
+	if (discovered?.usedNative.includes(token)) return "native-css";
+	if (discovered?.invalid.includes(token)) return "invalid";
+	if (discovered?.latent.includes(token)) return "latent";
+	return inspection.valid ? "generated" : "unknown";
+}
+function extractFromContent(service, css, filePath, content, includeRules, discovered) {
+	const document = createMCPTextDocument(filePath, content);
+	return service.getClassPositions(document).map((position) => {
+		const inspection = compactInspection(css, position.token, void 0, includeRules);
+		return {
+			raw: position.raw,
+			token: position.token,
+			range: position.range,
+			loc: {
+				start: document.positionAt(position.range.start),
+				end: document.positionAt(position.range.end)
+			},
+			contextRange: position.contextRange,
+			sourceKind: "class-position",
+			status: classifyExtractedClass(position.token, inspection, discovered),
+			valid: inspection.valid,
+			inspection
+		};
+	});
+}
+async function extractClasses(context, options = {}) {
+	const { manifest, css } = await createCSS(context);
+	const service = createLanguageService(manifest);
+	const includeRules = Boolean(options.includeRules);
+	if (options.content !== void 0) {
+		const filePath = context.resolveVirtualPath(options.filePath || "index.html");
+		const classes = extractFromContent(service, css, filePath, options.content, includeRules);
+		return {
+			version: CLASS_EXTRACTION_VERSION,
+			root: context.root,
+			manifest: {
+				status: manifest.status,
+				entries: manifest.entries,
+				...manifest.status === "error" ? { error: manifest.error } : {}
+			},
+			inputs: {
+				mode: "content",
+				filePath
+			},
+			files: [{
+				filePath,
+				languageId: getLanguageId(filePath),
+				classes
+			}],
+			summary: {
+				files: 1,
+				classes: classes.length,
+				valid: classes.filter((className) => className.valid).length,
+				invalid: classes.filter((className) => !className.valid).length
+			}
+		};
+	}
+	const filePaths = await resolveSourceFiles(context, options.patterns);
+	const scan = await scanProject(context, {
+		patterns: options.patterns,
+		includeCss: false
+	});
+	const scanFileByPath = new Map(scan.files.map((file) => [file.filePath, file]));
+	const files = await Promise.all(filePaths.map(async (filePath) => {
+		const content = await readFile(filePath, "utf8");
+		const discovered = scanFileByPath.get(filePath)?.discovered;
+		return {
+			filePath,
+			languageId: getLanguageId(filePath),
+			classes: extractFromContent(service, css, filePath, content, includeRules, discovered)
+		};
+	}));
+	const classes = files.flatMap((file) => file.classes);
+	return {
+		version: CLASS_EXTRACTION_VERSION,
+		root: context.root,
+		manifest: {
+			status: manifest.status,
+			entries: manifest.entries,
+			...manifest.status === "error" ? { error: manifest.error } : {}
+		},
+		inputs: {
+			mode: "project",
+			patterns: options.patterns ?? scan.inputs.patterns,
+			files: filePaths
+		},
+		files,
+		scanner: { counts: scan.scanner.counts },
+		diagnostics: scan.diagnostics,
+		summary: {
+			files: files.length,
+			classes: classes.length,
+			valid: classes.filter((className) => className.valid).length,
+			invalid: classes.filter((className) => !className.valid).length,
+			diagnostics: scan.summary.diagnostics
+		}
+	};
+}
+function findClassOccurrences(report, className) {
+	return report.files.flatMap((file) => {
+		const discovered = file.discovered;
+		const statuses = [
+			discovered.valid.includes(className) ? "valid" : void 0,
+			discovered.invalid.includes(className) ? "invalid" : void 0,
+			discovered.usedNative.includes(className) ? "used-native" : void 0,
+			discovered.latent.includes(className) ? "latent" : void 0
+		].filter((status) => Boolean(status));
+		return statuses.length ? [{
+			filePath: file.filePath,
+			source: file.source,
+			statuses
+		}] : [];
+	});
+}
+async function traceClass(context, options) {
+	const [scan, state] = await Promise.all([scanProject(context, {
+		patterns: options.patterns,
+		classes: [options.className],
+		includeCss: options.includeCss
+	}), createCSS(context)]);
+	const inspection = compactInspection(state.css, options.className, options.mode, true);
+	const missingResult = [...scan.missingCSS.present, ...scan.missingCSS.missing].find((result) => result.className === options.className);
+	const occurrences = findClassOccurrences(scan, options.className);
+	const status = missingResult?.status ?? (inspection.valid ? "present" : "missing");
+	const reason = missingResult?.reason ?? (inspection.valid ? "generated" : "not-detected");
+	return {
+		version: CLASS_TRACE_VERSION,
+		root: context.root,
+		manifest: {
+			status: state.manifest.status,
+			entries: state.manifest.entries,
+			...state.manifest.status === "error" ? { error: state.manifest.error } : {}
+		},
+		inputs: {
+			className: options.className,
+			patterns: options.patterns ?? scan.inputs.patterns,
+			mode: options.mode
+		},
+		className: options.className,
+		status,
+		reason,
+		detected: occurrences.length > 0,
+		occurrences,
+		inspection,
+		scanner: {
+			counts: scan.scanner.counts,
+			safelist: scan.scanner.classes.safelist.includes(options.className),
+			blocklist: scan.scanner.classes.blocklist.includes(options.className)
+		},
+		css: {
+			included: scan.css.included,
+			bytes: scan.css.bytes,
+			emittedGlobals: scan.css.emittedGlobals,
+			...scan.css.text !== void 0 ? { text: scan.css.text } : {}
+		},
+		diagnostics: scan.diagnostics.filter((diagnostic) => {
+			if (diagnostic.sourceKind === "missing-css") return diagnostic.data?.className === options.className;
+			return diagnostic.message.includes(options.className);
+		}),
+		summary: {
+			status,
+			reason,
+			detected: occurrences.length > 0,
+			valid: inspection.valid,
+			rules: inspection.rules.length,
+			diagnostics: scan.diagnostics.length
+		}
+	};
+}
+//#endregion
+export { extractClasses, traceClass };

package/dist/compare.d.ts

@@ -0,0 +1,71 @@
+import MasterCSSMCPContext from "./context.js";
+
+//#region src/compare.d.ts
+interface CompareCSSOptions {
+  beforeClassList?: string;
+  afterClassList?: string;
+  beforeHtml?: string;
+  afterHtml?: string;
+  beforeContent?: string;
+  afterContent?: string;
+  filePath?: string;
+}
+declare function compareCSS(context: MasterCSSMCPContext, options: CompareCSSOptions): Promise<{
+  version: number;
+  root: string;
+  manifest: {
+    error?: string | undefined;
+    status: "loaded" | "error";
+    entries: string[];
+  };
+  inputs: {
+    filePath: string;
+    before: {
+      classes: number;
+      invalid: number;
+    };
+    after: {
+      classes: number;
+      invalid: number;
+    };
+  };
+  classes: {
+    added: string[];
+    removed: string[];
+    unchanged: string[];
+  };
+  invalid: {
+    before: string[];
+    after: string[];
+    added: string[];
+    removed: string[];
+  };
+  css: {
+    changed: boolean;
+    before: {
+      bytes: number;
+      text: string;
+    };
+    after: {
+      bytes: number;
+      text: string;
+    };
+    bytesDelta: number;
+    diff: string;
+  };
+  rules: {
+    added: string[];
+    removed: string[];
+    unchanged: number;
+  };
+  summary: {
+    changed: boolean;
+    addedClasses: number;
+    removedClasses: number;
+    addedRules: number;
+    removedRules: number;
+    bytesDelta: number;
+  };
+}>;
+//#endregion
+export { CompareCSSOptions, compareCSS };