Agentic Workflows

MCP Server for Master CSS

Connect AI clients to Master CSS project context, diagnostics, generated CSS previews, and safe write previews through the Model Context Protocol.

The Master CSS MCP server gives AI clients a project-aware interface for Master CSS. It runs locally over stdio, reads the workspace you point it at, and exposes tools for setup audits, manifest inspection, directive inspection, class diagnostics, generated CSS previews, syntax suggestions, CSS output comparison, and safe fix previews.

Use it when an AI coding agent should reason from the same Master CSS setup as the project: the CSS entry manifest, theme tokens, component classes, scanner state, stylesheet entries, and lint policy. It is not a replacement for editor completions, ESLint, or CI commands. It is a tool surface for AI clients that speak the Model Context Protocol.

Install and start

Install the package in the project or run it with npx. The server uses stdio, so it is usually started by an MCP client rather than by a long-running terminal session.

npx -y @master/css-mcp@rc --root /absolute/path/to/project

Use an absolute --root path so the server can resolve the intended workspace. When --root is omitted, the current working directory becomes the workspace root.

You can also set the preview confirmation token lifetime:

npx -y @master/css-mcp@rc --root /absolute/path/to/project --preview-ttl 300000

Ask an agent to set it up

You can ask a local AI coding agent to register the MCP server for you. The agent should identify the MCP client first, then use that client's native setup path instead of assuming every client reads the same project config file.

Set up the Master CSS MCP server for this project.Project root: /absolute/path/to/projectPackage: @master/css-mcp@rcFirst identify which MCP client is being configured. Use the client's native registration path:- Codex App: use `codex mcp add`- Claude Code: use `claude mcp add --transport stdio`- Clients that accept `mcpServers` JSON: add the command/args shape to that client's configUse this stdio command:npx -y @master/css-mcp@rc --root /absolute/path/to/projectDo not assume a project `mcp.json` is read automatically by every client. Do not commit machine-specific absolute paths unless I explicitly ask for a project-scoped team config.After setup, verify the server is registered, restart or open a new client session if needed, then call `mastercss_workspace_info` to confirm the MCP server is connected to the intended project root.

Configure an MCP client

MCP clients that accept mcpServers JSON can use the same command you would run from the terminal. Treat this as a copyable config shape, not a universal project file that every client automatically reads. For example, Claude Desktop uses this shape in claude_desktop_config.json and requires a restart after config changes.

{  "mcpServers": {    "master-css": {      "command": "npx",      "args": ["-y", "@master/css-mcp@rc", "--root", "/absolute/path/to/project"]    }  }}

Use with Codex App

Codex App can register stdio MCP servers through the Codex CLI:

codex mcp add master-css -- npx -y @master/css-mcp@rc --root /absolute/path/to/project

This writes an equivalent entry to ~/.codex/config.toml:

[mcp_servers.master-css]command = "npx"args = ["-y", "@master/css-mcp@rc", "--root", "/absolute/path/to/project"]startup_timeout_sec = 120

Restart Codex App or open a new thread after changing MCP settings. Verify the server is registered with:

codex mcp listcodex mcp get master-css

If codex mcp cannot read the configuration, fix the local Codex config parse error first, then run the add command again.

Use with Claude Code

Claude Code can register the same local stdio server through its MCP CLI:

claude mcp add --transport stdio master-css -- npx -y @master/css-mcp@rc --root /absolute/path/to/project

For a team-maintained project config, use project scope:

claude mcp add --transport stdio --scope project master-css -- npx -y @master/css-mcp@rc --root /absolute/path/to/project

Review the generated .mcp.json before committing it because absolute --root paths are machine-specific.

After connecting, ask the client to inspect the workspace before editing. Good first tasks include scanning the project, inspecting one class, linting changed files, and previewing fixes without applying them.

Use the Master CSS MCP server to inspect this workspace before editing.Check the project manifest, scan source files, lint the affected class strings, and inspect any classes whose generated CSS is unclear. If fixes are needed, create a preview first and explain the diff before applying it.

Available tools

The server exposes focused tools instead of asking the agent to infer Master CSS behavior from files alone.

Project tools

Tool	Use
`mastercss_workspace_info`	Report workspace roots, resolved Master CSS package locations, and manifest status.
`mastercss_setup_audit`	Audit package, entry stylesheet, manifest, integration, and package-resolution setup.
`mastercss_inspect_class`	Inspect one class and return semantic parts, generated rules, variables, 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 project 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 an HTML fragment or a whitespace-separated class list.
`mastercss_scan_project`	Scan source files, register stylesheet entries, check optional classes, and report scanner state, generated CSS metadata, and missing CSS diagnostics.
`mastercss_manifest_query`	Query active manifest tokens, utilities, variants, modes, conditions, and aliases.
`mastercss_css_compare`	Compare generated CSS for before/after class lists, HTML fragments, or source buffers.
`mastercss_lint_project`	Run Master CSS class-list diagnostics for workspace files and return fix proposals without writing files.
`mastercss_lint_content`	Run Master CSS class-list diagnostics on an in-memory source buffer without writing files.
`mastercss_suggest_syntax`	Return language-service completions and hover context for a document position.
`mastercss_preview_fixes`	Create a diff preview for lint fixes or generated CSS output and return a 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 previously generated preview after validating the token, file hashes, and workspace containment.

Contributor tools

These read-only tools are for Master CSS repository contributors, AI coding agents, review bots, and CI support. They return repository-specific routing as compact JSON: affected packages, required context files, risk flags, and focused validation commands. 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.

The server also exposes workspace resources for the loaded manifest, entry files, and resolved Master CSS package locations.

Prompt templates

Prompt templates guide common AI workflows without asking the client to infer the right tool sequence.

Prompt	Use
`debug-missing-css`	Inspect scanner coverage, manifest loading, syntax, native CSS pruning, and stylesheet entry configuration when classes do not produce CSS.
`review-mastercss-classes`	Run class diagnostics 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 a project is moving from CSS, CSS Modules, Sass, Tailwind CSS, CSS-in-JS, component-library styling, or Master CSS v1. The prompt should make the agent inspect the workspace first, then return a plan with:

the current framework, package manager, and styling systems
stylesheet entries, source extraction coverage, and existing Master CSS tokens or component classes
the recommended rendering mode and first reviewable migration batch
CSS output risks, validation commands, and manual visual checks

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. Use write previews only for safe, scoped changes that can be reviewed before applying.

Use the Master CSS MCP prompt `migrate-to-mastercss` for this workspace.Inspect the project with MCP tools first. Do not edit yet. Return an incremental migration plan with the current styling inventory, recommended rendering mode, first migration batch, validation commands, and visual review risks.

Machine-readable results

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 and generated detail objects may gain fields as diagnostics become more precise.

For CLI fallback reports, cwd is the command root. For MCP reports, root is the configured workspace root.

Safe write previews

Read-only tools never write files. Tools that can lead to writes use a two-step flow:

A preview tool such as mastercss_preview_fixes or mastercss_preview_directive_format creates a diff preview and returns a confirmation token.
The client shows or explains the preview.
mastercss_apply_preview applies the preview only after validating the token, workspace containment, and the original file hash.

This keeps AI-assisted edits reviewable. If a file changes after the preview is created, applying the preview fails instead of overwriting newer work.

Use includeDirectiveFixes only when structural @compose rewrites are acceptable. Class-list fixes are safer because they replace class-list text in place; directive fixes can rewrite CSS directive structure. Directive formatting previews are separate from lint fixes and use the same preview/apply safety checks.

Choose the right tool

Use each Master CSS tool surface for the workflow it owns.

Surface	Best for
MCP server	AI client tool calls with project context, setup audits, scanner diagnostics, class tracing, manifest queries, CSS comparison, syntax suggestions, and safe fix previews.
CLI JSON output	Terminal, CI, scripts, and native preflight checks that need machine-readable lint or scan reports.
ESLint	Human development workflow, editor diagnostics through ESLint extensions, team policy, and JavaScript/framework CI linting.
Language Service	Editor completion, hover previews, color tools, directive formatting, highlighting, and manifest diagnostics.

When an AI client supports MCP, prefer the MCP server because it can call specific tools and keep write previews explicit. When a client cannot use MCP, use CLI JSON output as the fallback:

npx @master/css-cli lint --format json --exit-code never

For scanner state, stylesheet entry metadata, generated CSS size, or explicit missing CSS checks, use:

npx @master/css-cli inspect --format json --exit-code never

Next steps

Use AI Coding for prompts and review habits around AI-generated styling.
Use Project agent rules when you want a reusable rules block for local AI coding agents.
Use Code Linting for the ESLint rules that enforce class policy in normal development.
Use Language Service for editor intelligence and generated CSS previews.
Use Scanning latent classes when generated CSS is missing because source discovery needs inspection.