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 manifest inspection, class diagnostics, generated CSS previews, syntax suggestions, 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.

Tool	Use
`mastercss_workspace_info`	Report workspace roots, resolved Master CSS package locations, and manifest status.
`mastercss_inspect_class`	Inspect one class and return semantic parts, generated rules, variables, and CSS text.
`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_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_apply_preview`	Apply a previously generated preview after validating the token, file hashes, and workspace containment.

The server also exposes workspace resources for the loaded manifest, entry files, and resolved Master CSS package locations. Prompt templates guide common workflows such as debugging missing CSS, reviewing class strings, and planning migrations.

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 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:

mastercss_preview_fixes 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.

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, scanner diagnostics, class inspection, 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.