RIO UIKIT MCP

This package provides a Model Context Protocol server for the RIO UIKIT. It ships generated component, example, Foundation, guideline, template, visual, changelog and migration data with the package, so consumers do not need to clone or run the UIKIT repository.

This is the new source-of-truth MCP server that lives inside the rio-uikit repository. It is intentionally published as @rio-cloud/rio-uikit-mcp, separate from the UIKIT runtime package @rio-cloud/rio-uikit and separate from the older @rio-cloud/uikit-mcp crawler-based package.

Keep the split:

• @rio-cloud/rio-uikit is the UIKIT runtime dependency for applications.
• @rio-cloud/rio-uikit-mcp is the agent/documentation context package for MCP clients.
• @rio-cloud/uikit-mcp is the previous standalone MCP package and should not be reused for this implementation.

Setup guides:

• SETUP_GUIDE.md is the recommended no-code Codex app setup guide for designers and product owners who use the published MCP package.
• SETUP_GUIDE_DEVELOPER.md is the code-editor setup guide for developers using MCP-capable assistants in tools such as VS Code or IntelliJ IDEA.
• SETUP_GUIDE_CONTRIBUTOR.md is the local setup guide for UIKIT contributors who develop or publish this MCP server.

The published package also includes the UIKIT skill in skill/rio-uikit/SKILL.md. Install it alongside the MCP server because it teaches the client AI when and how to use the MCP tools, Foundation CSS classes, examples and hard UIKIT rules.

Usage

Add the server to an MCP client configuration:

{
    "mcpServers": {
        "rio-uikit": {
            "command": "npx",
            "args": ["-y", "@rio-cloud/rio-uikit-mcp"]
        }
    }
}

or for a specific version:

{
    "mcpServers": {
        "rio-uikit": {
            "command": "npx",
            "args": ["-y", "@rio-cloud/[email protected]"]
        }
    }
}

For local development from this repository:

npm --prefix uikit-mcp run mcp:server

For MCPJam or another local STDIO client during development, point the server command to:

node /path/to/rio-uikit/uikit-mcp/server/index.mjs

The server/index.mjs wrapper compiles the TypeScript server before startup and keeps stdout clean for MCP JSON-RPC. The published package uses the compiled binary directly.

The MCP server and index generator are TypeScript source in uikit-mcp/server/**/*.ts and uikit-mcp/scripts/**/*.ts. npm --prefix uikit-mcp run build:typescript compiles them to uikit-mcp/dist/**; the published package bin points to dist/server/index.js.

Install the bundled UIKIT skill from the same package version as the MCP server. Remove any existing older rio-uikit skill first because old and new UIKIT skills use the same skill name. See the setup guides above for assistant-specific installation steps.

Source of truth

uikit-mcp/data/** is generated output. Do not maintain files in data by hand; they are recreated by the MCP index build and can be overwritten.

Maintain MCP source data in these locations instead:

• uikit-mcp/content/design/** for design principles, design patterns and quality gates.
• uikit-mcp/content/guidelines/** for curated UIKIT usage, code style and agent rules.
• uikit-mcp/content/components/** for curated component metadata, usage guidance and demo example references. Use subfolders that mirror src/components, for example content/components/table/table-row.json.
• uikit-mcp/content/foundations/topics/** for curated Foundation topic semantics.
• uikit-demo/src/sites/start/migrationGuide/*.tsx for human-readable TSX migration guides used by the demo page and parsed into the generated MCP index. Legacy JSON overrides in uikit-mcp/content/migrations/** remain supported as a fallback.
• uikit-mcp/content/search/synonyms.json for curated search synonyms, preferred results and workflow hints.
• uikit-mcp/content/visuals/** for visual snapshot definitions. Use ownerType: "component" for component visuals and ownerType: "template" for UI Template visuals that combine components, layout and Foundation CSS classes.
• uikit-demo/src/sites/foundations/** for Foundation documentation and canonical Foundation examples.
• uikit-demo/src/sites/start/guidelines/** for guideline pages such as writing, formatting, print CSS, iframe and state-in-URL guidance.
• uikit-demo/src/sites/templates/** for UI template pages and concrete template examples.
• uikit-demo/src/sites/utilities/hooks/** and src/hooks/** for UIKIT hook documentation, examples and source references.
• uikit-demo/src/sites/utilities/** and src/utils/** for UIKIT utility documentation, examples and source references.
• uikit-demo/src/sites/start/Changelog.tsx and uikit-demo/src/sites/start/ChangelogPast.tsx for release changelog entries.
• dist/<version>/*.css for the generated theme CSS contract used by Foundation classes and theme tokens.

After changing one of the source locations, rebuild the generated MCP data:

npm --prefix uikit-mcp run build:index

Use this rule of thumb:

uikit-mcp/content/**        hand maintained MCP content
uikit-demo/**               source docs, demos and examples
src/hooks/**                source hook implementations
src/components/**           source component implementations and prop types
dist/**                     generated CSS contract
uikit-mcp/data/**           generated MCP index

Component metadata

Component metadata lives in uikit-mcp/content/components/**/*.json. Add a content file when a component, public subcomponent or public table/control helper should be available through search_components and get_component.

Keep these files in uikit-mcp/content/components because they are curated MCP knowledge, not component source. They intentionally bridge component source, UIKIT demo routes, examples and usage guidance. The source field still points to the component implementation or type file so the generator can extract public TypeScript props.

Mirror the source folder structure where possible:

uikit-mcp/content/components/
  applicationLayout/
    application-layout.json
    application-layout-body.json
  table/
    table.json
    table-row.json
  button/
    button.json

Use these conventions:

• name: public component or subcomponent name, for example Button, TableHeaderColumn or TableToolbarColumn.
• category: use stable display categories such as Interaction, Data display, Layout, Forms, Feedback, Navigation or Content.
• route: UIKIT demo route that documents the component or family.
• source: source file that contains the public prop types.
• importPath: public consumer import path. For named table subcomponents exported from Table, use @rio-cloud/rio-uikit/Table.
• propTypeNames: exported or local type aliases/interfaces to extract. Keep this focused on public props and related item types.
• description: explain when to use the component, not only what it renders.
• dos and donts: capture usage rules that should steer generated code.
• troubleshooting: capture component-specific symptoms, likely causes and repairs. These entries are included in component search and rendered by get_component; keep them out of the global rules when they only apply to one component family.
• relatedComponents: reference other public components by their name. The MCP build warns when a related component has no metadata yet.
• examples: use stable, globally unique example ids. Reusing the same example file is fine, but every example id must be unique across all generated examples.

The MCP build also compares component metadata with public root component exports from src/*.ts. Root files that re-export from src/components/** or theme component folders are treated as public component import paths. Missing metadata is reported as a warning so new public components can be added incrementally.

Guideline rule rendering limit

The Markdown renderer in server/render-markdown.ts renders at most the first 40 entries of a guideline's rules array. This limit applies to the textual MCP response and generated Markdown resource used by tools such as get_uikit_rules and get_guideline. The JSON returned in structuredContent remains complete, but clients or agents that primarily consume the Markdown text may not see rules after position 40.

Keep content/guidelines/rules.json below this limit and reserve it for concise, globally applicable agent and UIKIT policies. Put component-specific guidance in content/components/**/*.json and domain-specific guidance in the appropriate guideline or Foundation topic. When the global rule count approaches the limit, consolidate or relocate rules instead of relying on an increased renderer limit.

Included tools

• get_manifest
• search_uikit
• search_components
• get_component
• get_component_examples
• get_example
• search_examples
• get_design_tokens
• get_design_principles
• search_design_patterns
• get_design_pattern
• plan_uikit_screen
• get_design_quality_gates
• get_chart_decision_guide
• search_chart_decisions
• get_chart_decision
• get_interaction_decision_guide
• search_interaction_decisions
• get_interaction_decision
• get_navigation_decision_guide
• search_navigation_decisions
• get_navigation_decision
• get_motion_decision_guide
• search_motion_decisions
• get_motion_decision
• get_ux_rule_guide
• search_ux_rules
• get_ux_rule
• search_templates
• get_template
• search_hooks
• get_hook
• search_utilities
• get_utility
• search_icons
• search_foundation_classes
• get_foundation_class
• verify_classnames
• search_foundation_topics
• get_foundation_topic
• get_uikit_rules
• search_guidelines
• get_guideline
• get_code_style
• get_react_best_practices
• search_changelog
• get_changelog
• search_migrations
• get_migration_guide
• search_visuals
• get_component_visuals
• get_template_visuals
• get_guideline_visuals

Agent workflow

Use search_uikit as the broad first step for ambiguous UIKIT implementation tasks. It searches components, examples, templates, Foundation topics/classes, UIKIT icons, hooks, utilities, guidelines, design patterns, decision guidance and UX repair rules, then returns a compact ranked result list plus a short recommended workflow. Follow the returned nextTool calls before implementing.

Use plan_uikit_screen before implementing a new screen. It resolves an existing UIKIT design pattern and returns multiple UIKIT-safe composition variants, states, responsive and accessibility guidance, linked components, templates, Foundation topics, guidelines, chart decisions, interaction decisions, navigation decisions, motion decisions and required follow-up tool calls. Use search_chart_decisions before choosing a visualization; the guide also recommends precise non-chart alternatives such as Table, StatsWidgets and Map. Use search_interaction_decisions for feedback and state behavior, and search_navigation_decisions for the correct navigation hierarchy and context-preservation strategy. Use search_motion_decisions before selecting a ready-made UIKIT motion component or composing custom animation through @rio-cloud/rio-uikit/motion, including a reduced-motion strategy. Use search_ux_rules with a visible symptom or anti-pattern, then follow get_ux_rule for ordered repair and verification steps.

Search tools such as search_templates, search_examples, search_foundation_topics, search_hooks and search_utilities return starter code by default because agents often need code immediately after choosing a domain. Pass includeCode: false for compact discovery-only searches.

Detail tools and broad search results can expose three resource styles:

• resource: JSON resource for structured data.
• markdownResource: generated Markdown rendered from MCP JSON metadata.
• docsResource: source-doc Markdown extracted from UIKIT demo/source pages, examples, source files and curated context.

Use docsResource when an agent needs more documentation-like context before writing code. Use get_example or the domain-specific detail tools when exact code is needed.

Generated data

Build the bundled MCP index:

npm run build:mcp

From inside the uikit-mcp package, use:

npm run build:index

The root build:mcp script builds the generated theme CSS, compiles the TypeScript MCP server, reads component metadata from uikit-mcp/content/components/**/*.json, enriches it with source-derived data such as TypeScript props and demo example code, extracts public Foundation CSS classes from dist/<version>/rio-uikit.css, uses uikit-demo/src/sites/foundations/** as a documentation signal, and writes normalized JSON artifacts to uikit-mcp/data.

The generator is split by responsibility:

• scripts/build-index.ts orchestrates the full MCP index build, creates the manifest and writes generated artifacts.
• scripts/generators/common.ts contains shared file-system, JSON and path helpers.
• scripts/generators/components.ts extracts component metadata, TypeScript props and component examples.
• scripts/generators/foundations.ts extracts theme CSS tokens, Foundation CSS classes, topics and examples.
• scripts/generators/guidelines-design.ts loads curated guidelines, generated demo guidelines, code-style guidance and design guidance.
• scripts/generators/templates-hooks.ts extracts template and hook domains from the UIKIT demo and source files.
• scripts/generators/changelog.ts extracts changelog versions from the UIKIT demo changelog pages and derives migration guides.
• scripts/generators/visuals.ts loads visual snapshot definitions for components, templates, Foundation topics and design patterns.
• scripts/generators/validate-index.ts validates cross-domain consistency and generated files.

Curated Foundation topic semantics live in content/foundations/topics/*.json. The generator merges those descriptions, use cases, Do/Don't guidance, key classes and related topics with the class/source data derived from the demo pages.

Foundation examples are generated from relevant uikit-demo/src/sites/foundations/**/*.tsx pages into examples/foundations/*.json. Each example includes its topic, route, tags, documented class names and full source code.

Guidelines are generated from curated MCP content in content/guidelines/*.json and from the UIKIT demo guideline pages in uikit-demo/src/sites/start/guidelines/**. The generated guideline details include the demo route, source files, extracted text snippets and source code references so MCP clients can retrieve canonical guidance such as writing style, formatting, interaction and feedback, navigation and information architecture, motion and animation, print CSS, iframe, email, browser support and state-in-URL behavior. Demo pages never read MCP files; the MCP build only consumes their documentation source in the opposite direction.

Design guidance lives in content/design/** and is generated into data/design/**. This domain contains RIO UIKIT design principles, screen patterns such as application shells, dashboards, data-table pages, forms, detail pages, settings pages, empty states and error states, a chart decision guide with non-chart alternatives, plus quality gates for reviewing UIKIT design and implementation work. Structured interaction, navigation and motion decisions live with their corresponding human-readable guidelines in content/guidelines/**. Shared screen-planning guidance and composition variants live in content/design/screen-planner.json; pattern-specific decision hints and composition variants are co-located with their owning files in content/design/patterns/**. Searchable UX violations and their concrete UIKIT-compatible repairs live in content/design/ux-rules.json.

Templates are generated from uikit-demo/src/sites/templates/** into data/templates/** and data/examples/templates/**. Templates are concrete UIKIT code start points for screen sections and blocks such as action panels, AI assistant, detail views, forms, lists, progress, stats and tables.

Hooks are generated from uikit-demo/src/sites/utilities/hooks/** and src/hooks/** into data/hooks/** and data/examples/hooks/**. Hooks help agents avoid reimplementing browser effects, observers, timers, storage, postMessage, search, sorting and table-selection behavior.

Utilities are generated from uikit-demo/src/sites/utilities/** and mapped UIKIT utility source files under src/** into data/utilities/** and data/examples/utilities/**. Utilities cover reusable helpers such as class names, device checks, fuel type helpers, route utilities, analytics helpers and URL feature toggles.

Changelog data is generated from uikit-demo/src/sites/start/Changelog.tsx and uikit-demo/src/sites/start/ChangelogPast.tsx into data/changelog/**. The generator extracts version, date, change type, category, text and rough domain references. Migration guides are generated into data/migrations/** from breaking and migration-relevant changelog entries.

For complex releases, add a human-first migration page named uikit-demo/src/sites/start/migrationGuide/<major>.<minor>.<patch>.tsx. For example, migrationGuide/3.0.0.tsx is parsed as the guide for version 3.0.0. Compose the page with the generic components from uikit-demo/src/components/MigrationGuide.tsx and use normal JSX and semantic formatting such as headings, lists, code elements and UIKIT checkboxes. The MCP generator parses the static MigrationSection, MigrationChecklist and MigrationList content into its own generated migration schema. This keeps the dependency directional: MCP consumes demo documentation; the demo does not import MCP data or model its content after the MCP schema. Generated migration data uses the MigrationSection titles as its checklist when no static MigrationChecklist is present. It still keeps the changelog-derived breaking changes, deprecations, removals and renames. Legacy JSON files in uikit-mcp/content/migrations/** remain supported as a fallback, and the demo source wins when both locations define the same version.

Visual metadata is generated from content/visuals/** into data/visuals/**. Component visuals point to component demo examples; UI Template visuals should also list relatedComponents and relatedFoundationClasses because templates are composed from components, layout rules and Foundation CSS classes.

Search metadata is generated from content/search/synonyms.json into data/search/synonyms.json. Keep it focused on domain-level synonyms, preferred results and workflow hints. Do not add one-off rules for every observed prompt; prefer demo menu metadata, generated searchKeywords and component/template/example metadata when possible.

Visual source files follow schemas/visuals.schema.json. Keep visual entries compact: id, title and sourceRoute are enough for the common case. The generator defaults demoId to the visual id, codeExampleId to demoId when present and otherwise to id, selector to .playground-content, theme to rio and breakpoint to desktop. The group-level owner is the component name, template id, Foundation topic id or pattern id used by resources and tools such as get_template_visuals.

Use demoId only when the visual id is not the same as the captured Playground mcpVisualId, for example when one template demo has multiple visual states created by Playwright actions. In that case codeExampleId is normally not needed, because it is derived from demoId and points back to the same base example. Use codeExampleId only for the rare case where the visual should link to a different code example than the captured demo.

Visual screenshots are generated from the running UIKIT demo with Playwright:

npm --prefix uikit-demo run start -- --host 127.0.0.1
UIKIT_MCP_VISUAL_BASE_URL=http://127.0.0.1:8090 npm --prefix uikit-mcp run capture:visuals

If Vite chooses a different port, pass that port in UIKIT_MCP_VISUAL_BASE_URL. To regenerate one visual only:

UIKIT_MCP_VISUAL_BASE_URL=http://127.0.0.1:8090 npm --prefix uikit-mcp run capture:visuals -- --id=button-basic

Validation

The MCP build validates the generated model before writing and validates generated files after writing. The checks currently include:

• component, example, template and hook detail objects exist for their summaries.
• example ids and detail paths are unique.
• every template has at least one example.
• every hook has source code or demo source references.
• template and hook examples point to generated example details.
• design patterns and design principles only reference existing components, templates, hooks, Foundation classes, Foundation topics and guidelines.
• manifest domain paths and file patterns resolve to generated files.
• changelog and migration files are generated from the demo changelog source and included in the manifest.
• visual indexes and visual detail files are generated from curated visual definitions.
• public root component exports from src/*.ts are compared with content/components/** metadata and reported as warnings when missing.

Schema files in schemas/*.schema.json document hand-maintained and generated MCP data shapes, including component metadata, visual definitions, design principles, design patterns, quality gates, generated templates and generated hooks.

The generated artifact inventory is defined by data/manifest.json. Use the manifest as the source of truth for generated domains and file patterns.

components/index.json and examples/index.json are lightweight search indexes. Full component details and full example code are stored in per-item files and loaded by the MCP server when requested.

Theme styling data lives under foundations. Tokens are represented as CSS custom properties exposed by generated theme CSS files such as rio-uikit.css; internal SCSS variables are not treated as public API.

Foundation CSS classes are public CSS building blocks documented by the Foundation demo pages and extracted from generated rio-uikit.css. When prompts mention "utility classes" or "atomic classes", treat that as a request for these Foundation CSS classes. This includes low-level helpers such as spacing, typography, layout, color and sizing classes, and also documented Foundation patterns such as btn, form-control, active, fade, nav-tabs, icon and animation classes.

Component-specific MCP metadata should live in uikit-mcp/content/components. The src/components tree remains focused on component implementation and public prop types.

Publishing

The package is designed to be published from uikit-mcp.

npm pack ./uikit-mcp --dry-run
npm publish ./uikit-mcp --access public

prepack rebuilds and validates the generated index before packaging. The npm package is intentionally limited by the files whitelist in uikit-mcp/package.json; it publishes the compiled dist/server runtime, generated data, curated content, schemas, the agent skill and package docs. It must not include node_modules, the TypeScript source folders or the UIKIT application source.

If the dry run reports a very large package, check the listed files rather than the local folder size. A healthy package should not contain any node_modules/ entries:

npm pack ./uikit-mcp --dry-run --json

If npm fails because of a local cache permission issue, run the check with a temporary cache:

npm_config_cache=/tmp/rio-uikit-npm-cache npm pack ./uikit-mcp --dry-run --json

Do not use npm --prefix uikit-mcp pack or npm --prefix uikit-mcp publish from the repository root. With npm, --prefix is reliable for npm run ... scripts, but npm pack can still package the root UIKIT project. Use the folder package specifier above or run npm pack --dry-run from inside uikit-mcp.

Recommended release model:

• Publish @rio-cloud/rio-uikit and @rio-cloud/rio-uikit-mcp as separate npm packages.
• Keep both packages version-aligned with the UIKIT release when both changed, for example 3.0.0-beta.1.
• The MCP package can publish a new beta without publishing a new UIKIT runtime package when only MCP data, tools, resources, search quality or the bundled skill changed. In that case the MCP package version can be 3.0.0-beta.2 while the generated manifest still points to the UIKIT runtime version the index was built from.
• Do not bundle the MCP server into the normal UIKIT runtime package; application builds do not need MCP server code, generated JSON, screenshots or MCP SDK dependencies.
• Do not replace the old @rio-cloud/uikit-mcp package until the new package is adopted. If needed later, deprecate the old package with a migration message that points to @rio-cloud/rio-uikit-mcp.

Before publishing, run:

npm run build:mcp
npm --prefix uikit-mcp run validate:index
npm --prefix uikit-mcp run lint
npm pack ./uikit-mcp --dry-run

Consumers should configure MCP clients through npx @rio-cloud/rio-uikit-mcp; they should not need a local clone of this repository.