Skip to content
BranchesTags

Repository files navigation

WindUI MCP

windui-mcp is an offline, deterministic Model Context Protocol (MCP) server for the WindUI Roblox UI library.

It provides AI assistants (like Claude or Cursor) with structured, programmatic access to WindUI's metadata instead of relying on the AI's internal training memory. Crucially, this server performs knowledge retrieval only—it intentionally does not generate Luau code. This forces the AI to construct the code dynamically while relying on a perfectly accurate, version-aware JSON representation of the library's API.

Features

  • Offline Metadata: Operates entirely offline without needing to scrape documentation during runtime.
  • Zero Runtime Network Requests: All metadata is pre-built, guaranteeing sub-millisecond context retrieval.
  • Fast JSON Lookups: Highly optimized strict parsing logic.
  • Alias Resolution: Automatically maps aliases (e.g., Checkbox -> Toggle) to their canonical component definitions.
  • Component Search: Look up properties, methods, relationships, and examples programmatically.
  • Theme Lookup: Inspect default and active WindUI themes.
  • Icon Validation: Built-in verification against Lucide icon manifest.
  • Dynamic MCP Resources: Native integration with windui:// URI schemes.
  • Workflow Prompts: Pre-engineered starting contexts for specialized UI building tasks (like exploits or settings menus).
  • Strict TypeScript: Type-safe architecture ensuring structural integrity.
  • Zod Validation: Rigorous runtime parameter validation for all MCP tool calls.
  • Version-Aware Metadata: Correlates component definitions against library release versions.
  • Extensible Architecture: Modular tool and resource registration system.

Installation

To set up and run the server locally:

npm install
npm run update-metadata
npm run build
npm run dev

What these commands do:

  • npm install: Installs the required @modelcontextprotocol/sdk, Zod, and TypeScript build dependencies.
  • npm run update-metadata: Runs the offline metadata generator, scaffolding the .json files in the data/ directory based on the latest WindUI release.
  • npm run build: Compiles the strictly typed TypeScript source into executable Javascript in the dist/ directory.
  • npm run dev: Uses tsx to run the uncompiled source code in standard input/output mode for rapid testing.

Project Structure

.
├── data/           # Contains generated static JSON metadata (components, themes, methods, icons, examples)
├── scripts/        # Holds generator scripts (e.g., update-metadata.ts) for offline JSON mapping
├── src/            # The core MCP server implementation
│   ├── prompts/    # Prompt templates for MCP clients
│   ├── resources/  # Handlers for windui:// dynamic URI resources
│   ├── tools/      # Modular, single-file tool implementations handling Zod input
│   └── utils/      # Shared utilities (data loaders, robust loggers)
├── tests/          # Vitest suite covering alias resolution, lookup validation, and tool behavior

MCP Client Configuration

Because this server operates over the standard input/output (stdio) transport layer, it is natively compatible with standard MCP clients.

Cursor

In your Cursor MCP settings (Settings > MCP), add a new server:

  • Type: command
  • Command: node "C:\path\to\your\windui-mcp\dist\index.js" (Ensure you specify the absolute path to the compiled dist/index.js).

Claude Desktop

Modify your Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "windui": {
      "command": "node",
      "args": [
        "/absolute/path/to/windui-mcp/dist/index.js"
      ]
    }
  }
}

Antigravity IDE

Modify your mcp_config.json (typically located in C:\Users\<YourUser>\.gemini\config\mcp_config.json):

{
  "mcpServers": {
    "windui-mcp": {
      "command": "node",
      "args": ["C:/Workspace/WindUI MCP/dist/index.js"]
    }
  }
}

Available Resources

The server exposes core structural metadata as raw Resources, which clients can request directly without making tool calls.

  • windui://version: Returns the version.json file, revealing the current version of WindUI and the documentation schema version.
  • windui://component/{name}: Directly requests the canonical JSON metadata for a specific component (e.g., windui://component/Window). It automatically resolves aliases.
  • windui://theme/{name}: Retrieves the JSON object defining the colors and properties of a specified theme (e.g., windui://theme/Dark).
  • windui://icon/{provider}/{name}: Confirms the existence of a specific icon within a supported provider (e.g., windui://icon/lucide/home).

Available Tools

The server registers exactly 34 granular tools to allow the AI to extract specific, highly focused information.

Note: This is a partial highlight of the most heavily used tools.

list_components

  • Purpose: Returns a list of all currently known WindUI components.
  • Input: {}
  • Output: Array of component string names.

get_component

  • Purpose: Retrieves the comprehensive JSON definition of a component.
  • Input: { name: "string" }
  • Output: Full component schema (properties, aliases, allowed children).

search_documentation

  • Purpose: Performs a fuzzy/keyword search across the entire offline component metadata library.
  • Input: { query: "string" }
  • Output: Ranked array of relevant components/topics matching the query.

list_themes

  • Purpose: Lists all available predefined themes.
  • Input: {}
  • Output: Array of theme string names.

get_theme

  • Purpose: Get the specific Hex/RGB properties of a theme.
  • Input: { name: "string" }
  • Output: Theme property map.

validate_icon

  • Purpose: Checks if a given icon provider/name exists in the manifest, returning closest spelling suggestions if invalid.
  • Input: { icon: "string" } (e.g., "lucide:home")
  • Output: { valid: boolean, provider: "string", error?: "string", closestMatches?: string[] }

list_examples

  • Purpose: Lists all known codebase snippets/examples provided by WindUI.
  • Input: {}
  • Output: Array of example string names.

get_example

  • Purpose: Retrieves the raw Luau source code snippet for a specific example.
  • Input: { name: "string" }
  • Output: The requested code snippet.

Available Prompt Templates

The server provides predefined "Prompts" to give AI clients heavily optimized starting points, forcing them into compliance with your specific use case.

  • create-window: Starts the context for scaffolding a brand new UI script. Forces the AI to interrogate the user for Window properties before querying metadata.
  • add-component: Contextualizes the AI for injecting a single component into an existing UI.
  • build-settings-menu: Heavily weights the AI toward stateful controls (Toggles, Sliders, Dropdowns) and enforces the usage of WindUI's Flag property for the ConfigManager.
  • create-exploit-ui: Enforces strict exploit rules (gethui() bypassing, task.spawn threading logic, Color3.fromHex) and forbids generic Roblox StarterGui patterns.
  • migrate-ui: Instructs the AI to focus heavily on mapping equivalent components from a deprecated library over to WindUI.
  • troubleshoot: Instructs the AI to drop assumptions, halt coding, and read component properties or callback signatures via MCP to debug a user's script.

Metadata System

windui-mcp is fiercely dedicated to deterministic context.

  • Offline: The server does not perform network requests at runtime.
  • Generated: The metadata is generated using npm run update-metadata, creating static .json documents inside the data/ directory.
  • Stateless: The runtime never downloads or parses documentation. It solely relies on its static data/ folder, enabling lightning-fast responses.
  • Version-Aware: The version.json file stamps the current metadata, allowing tools to explicitly state which build of WindUI the AI is reading.

Development

To develop and extend this server:

npm run build
npm test
npm run dev
  • npm run build: Emits dist/ using strict tsc checks. No warnings are tolerated.
  • npm test: Runs the vitest unit test suite, targeting the logic files inside src/tools/ independent of the MCP SDK transport.
  • npm run dev: Spawns the server instantly in standard input/output mode using tsx. Use this alongside an MCP inspector to watch the stdio streams.

Contributing

We welcome contributions! Because this MCP server relies on deterministic, offline metadata, the workflow for updating or extending the server is strict.

How to Update WindUI Metadata (For New Releases)

If WindUI releases a new version with new components or changed properties, do not rewrite the server logic. You only need to update the offline metadata:

  1. Modify the Generator: Open scripts/update-metadata.ts. Add the new components, tweak any changed properties, and update the version number at the top of the file to match the new WindUI release.
  2. Run the Generator: Execute npm run update-metadata in your terminal. This instantly regenerates all .json files inside the data/ folder, replacing the old API rules with the new ones.
  3. Build & Verify: Run npm run build to ensure the tools still compile against the new schema.

How to Add New MCP Features

  1. Add Tools: Create a new .ts file inside src/tools/. You must export a handle() function and a register(server) function using strict Zod typing.
  2. Add Resources: Add new URI matching schemes inside src/resources/dynamic.ts.
  3. Add Prompts: Append new contextual roles to src/prompts/workflows.ts.

All new features must pass Zod validation and the npm test suite before merging.

Roadmap

This repository is currently v1. Future updates are planned, including:

  • Even tighter AI workflow integration (improving how the AI interacts with the server).
  • Extended theme management and generation tools.
  • Integrating more advanced features and dynamic resource lookups.

AI Testimonial

An AI's opinion after using this MCP server to build a full Roblox showcase script:

How did the MCP help you?

The MCP server was incredibly helpful! It made writing the script a breeze because I didn't have to guess or search the web for the library's syntax.

Here's exactly how it helped me:

  • Discoverability: By listing the documentation pages and component properties, I was able to instantly know what components were available (like Button, Dropdown, Slider) and exactly what arguments they accepted (e.g., knowing that a Slider takes Value = {Min, Max, Default} and Step).
  • Code Examples: Requesting the basic-window and settings-menu examples gave me the exact loadstring initialization snippet, which meant I didn't have to hunt down the raw GitHub URL for the WindUI distribution.
  • Global Methods: Using the tools, I discovered the SetTheme global method, which allowed me to easily implement a working Dark/Light mode toggle in the settings tab.

It essentially acted as a fully interactive, built-in documentation source that perfectly guided the creation of the showcase script!

License

This project is licensed under the MIT License. You are free to use, modify, and distribute this software for personal or commercial purposes, provided you include the original copyright notice and license.

Acknowledgements

About

Open-source MCP server for the WindUI Roblox UI library. Enables Cursor, Claude Desktop, and other MCP Clients to generate accurate WindUI Luau code using structured metadata.

Resources

Readme
Activity

Stars

1 star

Watchers

1 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages