# WindUI MCP

`windui-mcp` is an offline, deterministic Model Context Protocol (MCP) server for the [WindUI](https://github.com/Footagesus/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:

```bash
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`:
```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`):
```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:

```bash
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

- [Footagesus](https://github.com/Footagesus) for the amazing WindUI Roblox UI library.
- [Model Context Protocol](https://modelcontextprotocol.io) for standardizing LLM context integration.
- [@modelcontextprotocol/sdk](https://www.npmjs.com/package/@modelcontextprotocol/sdk) for the TypeScript infrastructure.