MCP Server

The Hubtel Design System MCP Server allows AI assistants to discover, search, and use Hubtel components autonomously — so agents can build UIs that follow the design system without needing Figma links or manual guidance.

What is MCP?

Model Context Protocol

is an open protocol that lets AI assistants connect to external tools and data sources. With the Hubtel MCP server, your AI assistant gains direct access to:

• Browse Components - List all available components with descriptions and import paths

• Search by Use Case - Find components by describing what you need (“file upload”, “navigation bar”)

• Get Full Documentation - Props, slots, events, and code examples for any component

• Setup Instructions - Framework-specific install commands, Tailwind config, and CSS imports

• Composition Patterns - Page-level layouts combining multiple components (dashboards, forms, settings)

• Design Tokens - Brand colours, spacing, typography, and semantic tokens

• Theme Selection - Browse and apply any of the 8 Hubtel themes

How It Works

The MCP server runs locally as a stdio process started by your IDE. Your AI assistant communicates with it through the MCP protocol to query component documentation, patterns, and setup instructions — all without leaving your editor.

1. IDE launches the server
   

   When you open your project, the IDE starts the MCP server via npx

2. Agent queries tools
   

   When building UI, the agent calls tools like search_components or get_component

3. Agent builds with Hubtel
   

   Using the returned props, examples, and patterns, the agent writes code that follows the design system

Available Tools

The MCP server provides 12 tools:

Tool	Description
list_components	List all components with optional category filter
search_components	Fuzzy search by use case or description
get_component	Full docs for a component — props, slots, events, example
get_setup_instructions	Install commands, Tailwind config, and CSS imports
check_setup	Diagnose existing project setup (deps, Tailwind v4, CSS directives)
get_composition_pattern	Page-level patterns (dashboard, form, settings, payment flow, etc.)
get_design_tokens	Brand colours, spacing, typography tokens
get_design_principles	Hubtel design language (chrome, surfaces, radius, anti-patterns, etc.)
get_themes	Browse all themes (no slug) or get setup for one theme (with slug)
find_icons	Find Hubtel icons by concept (omit query for a preview)
validate_imports	Validate import statements — catches barrel imports & typos
get_cursor_rule	Get the Cursor rule file content for agent self-install

---

Installation

There are two ways to install the Hubtel Design System MCP server. Aqua CLI is the recommended path — it’s Hubtel’s internal developer tool that registers the MCP across your agents/IDEs in a few prompts. The npx method is a manual alternative if you don’t have Aqua installed or need finer control over the config files.

Method 1 — Aqua CLI (recommended)

Aqua is Hubtel’s internal CLI for developer workflows — installing MCP servers, scaffolding projects, and more. It handles everything end-to-end so you don’t have to touch JSON config files.

1

Run Aqua in your project

From your project root, run:

aqua

Don’t have Aqua yet? Install it from the Aqua CLI documentation and re-run the command.

npm install -g @hubtel/aqua-cli

yarn global add @hubtel/aqua-cli

2

Walk through the prompts

Answer the interactive prompts in order:

1. Section — choose AI Workflows

2. Action — choose Install MCP Server

3. MCP server — choose Hubtel Design System

4. Agents/IDEs — pick Cursor, VS Code, Claude Code, Windsurf, or any combination

Aqua writes the right MCP config for each agent you selected (for example .cursor/mcp.json for Cursor) and, where supported, the matching agent rule file (.cursor/rules/hubtel-design-system.mdc).

A successful run looks like this:

✔ Installing Hubtel Design System MCP
✔ Registered Hubtel Design System with 1 agent(s)

Installation complete

3

Restart and try it out

Restart your IDE so the MCP server is picked up, then try one of these prompts:

• “Show me all available Hubtel components"
• "Build a dashboard page using the Hubtel design system"
• "What themes are available in Hubtel?”

In Cursor, go to Settings > MCP and verify the hubtel-design-system server shows a green dot.

---

Method 2 — Manual install via npx

If you don’t have Aqua, or you want to wire the MCP server up by hand (for example in a non-Hubtel project, or in CI), use the init command shipped with @hubtel/design-system-mcp. It writes the same config files Aqua does — just one client at a time.

1

Run the init command

Run the following command in your project root for the agent/IDE you use:

Cursor

npx @hubtel/design-system-mcp init --client cursor

This creates:

• .cursor/mcp.json — MCP server configuration
• .cursor/rules/hubtel-design-system.mdc — Agent rule for MCP-first workflow

VS Code (GitHub Copilot)

npx @hubtel/design-system-mcp init --client vscode

This creates .vscode/mcp.json. After running, open the file and click Start next to the hubtel-ds server.

Claude Code

npx @hubtel/design-system-mcp init --client claude

This creates .mcp.json. Restart Claude Code and run /mcp to verify the server is connected.

Windsurf

npx @hubtel/design-system-mcp init --client windsurf

This creates .windsurf/mcp.json.

2

Restart and try it out

Restart your IDE and try one of these prompts:

• “Show me all available Hubtel components"
• "Build a dashboard page using the Hubtel design system"
• "What themes are available in Hubtel?”

In Cursor, go to Settings > MCP and verify the hubtel-design-system server shows a green dot.

---

Available Prompts

In addition to the tools listed above, the MCP server ships prompts — pre-built instruction templates you can invoke from your AI client. They inject Hubtel’s core directives, the recommended MCP workflow, and the right guard-rails for the task — so the agent doesn’t have to rediscover the rules every time.

In Cursor and Claude Code, prompts show up as slash commands in the chat input (e.g. /build-hubtel-ui). In VS Code (Copilot) and Windsurf, they appear in the MCP prompt picker.

Prompt	Use it when…
build-hubtel-ui	You want the agent to build a UI (page, dashboard, form, modal) using Hubtel components instead of raw HTML or 3rd-party libs.
setup-hubtel-project	You’re bootstrapping a new project and need the right packages, theme, and the Tailwind v4 @import + @source CSS wired up.
audit-hubtel-ui	You want to review existing code for Hubtel compliance — raw HTML, 3rd-party libs, barrel imports, hex colors, missing @source, etc.

build-hubtel-ui

Builds a UI using the Hubtel Design System. Injects the core directives (no raw HTML, no 3rd-party UI libs, subpath imports only, Hubtel icons, semantic tokens, full loading/empty lifecycle) and walks the agent through the recommended MCP workflow before it writes any code.

Arguments

• task (required) — what to build, e.g. “a finance dashboard with a transactions table and KPI cards” or “a settings page with profile and notifications tabs”.

• framework (optional) — vue or react . If omitted, the agent detects it from package.json (vue/nuxt → vue, react/next → react).

Example

/build-hubtel-ui task="a finance dashboard with a KPI row, transactions table, and a filters drawer" framework="vue"

setup-hubtel-project

Installs and configures the Hubtel Design System in a project. Picks the right packages for the framework, applies the chosen theme to the <html> element (so portaled components like Modal, Sheet, DropdownMenu pick it up), and ensures the main CSS file has both @import "@hubtel/shared-styles" and the @source directive Tailwind v4 needs to scan the component library.

Arguments

• framework (required) — vue (Nuxt/Vite) or react (Next.js/Vite).

• theme (optional) — one of the Hubtel theme slugs ( default, mtn-blue, mtn-yellow, old-teal, black, yale-blue, purple, green, red, blue ). If omitted, the agent will call get_themes and ask you to pick one before continuing.

• package_manager (optional) — npm, pnpm, yarn, or bun. Defaults to whatever the project already uses.

Example

/setup-hubtel-project framework="react" theme="mtn-blue" package_manager="pnpm"

audit-hubtel-ui

Audits a codebase for Hubtel Design System compliance. Flags raw HTML where a Hubtel component exists, 3rd-party UI/icon libraries, barrel imports, cross-framework imports, raw hex colors and arbitrary Tailwind palette utilities, missing @source directives, and data-loading screens missing Shimmer/Loader/EmptyState lifecycles. For every violation it reports the file/line, the rule that was broken, and the recommended Hubtel replacement with its import path.

Arguments

• focus (optional) — narrow the audit, e.g. “imports only”, “styling only”, or a specific file path. Defaults to a full audit across the files currently in context.

Example

/audit-hubtel-ui focus="src/pages/dashboard"