Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/gauravsaini/gluestack-ui-mcp-server


https://github.com/gauravsaini/gluestack-ui-mcp-server

Last synced: about 2 months ago
JSON representation

Awesome Lists containing this project

README 

          
# Gluestack UI MCP Server 📱



[![npm version](https://badge.fury.io/js/@gluestack-ui%2Fmcp-server.svg)](https://www.npmjs.com/package/gluestack-ui-mcp-server)

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

[![React Native](https://img.shields.io/badge/React%20Native-61DAFB?logo=react&logoColor=white)](https://reactnative.dev/)

[![Expo](https://img.shields.io/badge/Expo-000020?logo=expo&logoColor=white)](https://expo.dev/)



> **📱 The definitive MCP server for React Native development with Gluestack UI - Build universal apps with AI assistance!**



This Model Context Protocol (MCP) server provides AI assistants with comprehensive access to [Gluestack UI](https://gluestack.io/) - the premier **React Native-first** component library that delivers true cross-platform experiences. Whether you're building for iOS, Android, or the web, this server intelligently provides components, source code, and examples optimized for React Native development workflows.



## Key Features



### 📱 **React Native-First Development**

- **70+ React Native Components**: Production-ready components optimized for mobile-first development

- **Universal Platform Support**: Single codebase runs on iOS, Android, and Web seamlessly

- **Expo Integration**: Perfect compatibility with Expo workflows and managed builds

- **React Native Navigation**: Built-in support for stack, tab, and drawer navigation patterns

- **Platform-Specific Optimizations**: Components automatically adapt to iOS and Android design guidelines



### 🎨 **Multi-Variant Architecture for React Native**

Go beyond basic styling with variants designed for different React Native use cases:

- **🎨 NativeWind**: Tailwind CSS components optimized for React Native with `react-native-css-interop`

- **🎭 Themed**: Native styling with Gluestack's design token system - perfect for branded apps  

- **🔧 Unstyled**: Headless components for maximum customization in React Native projects



### 📋 **React Native-Optimized Intelligence**

- **TypeScript-First**: Complete TypeScript definitions for React Native component props

- **Platform Detection**: Smart handling of `Platform.OS` checks and platform-specific code

- **Expo Examples**: Real-world usage patterns for Expo Router, EAS Build, and Expo dev workflows

- **Performance Patterns**: React Native performance best practices baked into component examples



### 🔄 **Cross-Platform Excellence**

- **Universal Components**: Write once, run on iOS, Android, and Web

- **Responsive Design**: Built-in support for different screen sizes and orientations

- **Native Feel**: Components follow platform-specific design guidelines automatically

- **Web Compatibility**: Seamless React Native Web integration for responsive web apps



### ⚡ **Development Acceleration**

- **GitHub Mode**: Access the latest React Native components directly from the repository

- **Local Development**: Work with local Gluestack UI installations for rapid iteration

- **AI-Powered**: Generate React Native screens, components, and navigation flows with AI assistance

- **Testing Ready**: Components come with accessibility labels and test IDs for React Native testing



## Quick Start



### Prerequisites



- Node.js 18+ 

- **React Native Development Environment**:

  - React Native CLI or Expo CLI

  - iOS Simulator (Mac) and/or Android Emulator

  - Metro bundler for React Native

- **Component Source** (choose one):

  - A local Gluestack UI installation or clone, OR

  - A GitHub Personal Access Token for fetching the latest React Native components



### Installation Options



#### Option 1: From npm (when published)

```bash

npm install -g gluestack-ui-mcp-server

```



#### Option 2: Local Development Setup

```bash

# Clone this repository

git clone https://github.com/gluestack/gluestack-ui-mcp-server

cd gluestack-ui-mcp-server



# Install dependencies

npm install



# Build the project

npm run build



# Set your Gluestack UI path

export GLUESTACK_PATH="/path/to/your/gluestack-ui"



# Test the server

npm test

```



### Usage with Claude Desktop



#### For Published Package

Add to your Claude Desktop configuration file (`~/.config/claude/config.json`):



```json

{

  "mcpServers": {

    "gluestack-ui": {

      "command": "npx",

      "args": ["gluestack-ui-mcp-server"],

      "env": {

        "GLUESTACK_PATH": "/path/to/your/gluestack-ui"

      }

    }

  }

}

```



**Or for GitHub mode:**

```json

{

  "mcpServers": {

    "gluestack-ui": {

      "command": "npx", 

      "args": ["gluestack-ui-mcp-server"],

      "env": {

        "GITHUB_TOKEN": "ghp_your_token_here"

      }

    }

  }

}

```



#### For Local Development

Add to your Claude Desktop configuration file (`~/.config/claude/config.json`):



```json

{

  "mcpServers": {

    "gluestack-ui": {

      "command": "node",

      "args": ["/path/to/gluestack-ui-mcp-server/build/index.js"],

      "env": {

        "GLUESTACK_PATH": "/path/to/your/gluestack-ui"

      }

    }

  }

}

```



**Or for GitHub mode:**

```json

{

  "mcpServers": {

    "gluestack-ui": {

      "command": "node",

      "args": ["/path/to/gluestack-ui-mcp-server/build/index.js"], 

      "env": {

        "GITHUB_TOKEN": "ghp_your_token_here"

      }

    }

  }

}

```



## Available Tools



### 🔍 Component Discovery & Navigation



#### `list_components`

Get a full inventory of all 126+ available Gluestack UI components, including which variants are available for each.



#### `list_component_variants`

Compare and choose the perfect variant by getting detailed information and features for a specific component's `NativeWind`, `Themed`, and `Unstyled` versions.



#### `get_directory_structure`

Navigate the entire `gluestack-ui` monorepo from your AI assistant with a powerful directory browsing tool.



### 📄 Code, Demos & Metadata



#### `get_component`

Retrieve the complete, unmodified source code for any component variant, providing perfect context for code generation.



#### `get_component_demo`

Access battle-tested usage examples directly from Storybook to understand how components are meant to be used in practice.



#### `get_component_metadata`

Go beyond the code to understand its API. This tool extracts TypeScript props, dependencies from import statements, and documentation from comments.



## Configuration Options



### Environment Variables

- `GLUESTACK_PATH`: Path to local Gluestack UI installation.

- `GITHUB_TOKEN`: GitHub Personal Access Token for API access.

- `LOG_LEVEL`: Logging level (`debug`, `info`, `warn`, `error`).



### Command Line Arguments

```bash

# Local mode

gluestack-mcp --gluestack-path /path/to/gluestack-ui --log-level debug



# GitHub mode 

gluestack-mcp --github-token ghp_xxxxxxxxxxxx --log-level debug

```



## GitHub Mode (Fetch Latest Components)



Instead of requiring a local Gluestack UI installation, you can use GitHub mode to fetch the latest components directly from the official repository.



### Setting up GitHub Mode



#### Step 1: Get a GitHub Personal Access Token

1. Go to GitHub Settings → Developer settings → Personal access tokens

2. Generate a new token (classic) with `public_repo` scope

3. Copy the token (starts with `ghp_`)



#### Step 2: Configure Your MCP Client



**For Claude Desktop:**

```json

{

  "mcpServers": {

    "gluestack-ui": {

      "command": "npx",

      "args": ["gluestack-ui-mcp-server"],

      "env": {

        "GITHUB_TOKEN": "ghp_your_token_here"

      }

    }

  }

}

```



**For Command Line:**

```bash

export GITHUB_TOKEN="ghp_your_token_here"

gluestack-mcp

```



### Benefits of GitHub Mode

- 🚀 **Always Up-to-Date**: Access the latest components directly from the main branch

- 📦 **No Local Setup**: No need to clone or maintain a local Gluestack UI repository

- 🔄 **Automatic Updates**: Components are fetched fresh from GitHub on each request

- 📊 **Rate Limit Friendly**: Authenticated requests get higher GitHub API limits (5000/hour vs 60/hour)



## Supported Components



The server provides access to 126+ Gluestack UI components including:



**Layout**: Box, Center, HStack, VStack, Grid, Divider

**Forms**: Input, Textarea, Button, Checkbox, Radio, Select, Slider, Switch  

**Feedback**: Alert, Toast, Progress, Spinner, Skeleton

**Overlay**: Modal, AlertDialog, Popover, Tooltip, ActionSheet

**Data Display**: Avatar, Badge, Card, Image, Table

**Navigation**: Tabs, Menu, Link

**Media**: Image, ImageViewer

**Utilities**: Portal, Pressable, SafeAreaView



## Testing



The server includes comprehensive tests for both local and GitHub modes:



```bash

# Run basic tests

npm test



# Test local mode (requires GLUESTACK_PATH)

npm run test:local



# Test GitHub mode (requires GITHUB_TOKEN)

npm run test:github



# Test both modes

npm run test:both



# Test component discovery

npm run test:components



# Run comprehensive test suite

npm run test:comprehensive

```



### Test Environment Setup



**For Local Mode Testing:**

```bash

export GLUESTACK_PATH=/path/to/gluestack-ui

npm run test:local

```



**For GitHub Mode Testing:**

```bash

export GITHUB_TOKEN=ghp_your_token_here

npm run test:github

```



## Requirements



- Node.js 18+

- Either:

  - Local Gluestack UI installation/clone (for local mode), OR

  - GitHub Personal Access Token (for GitHub mode)

- MCP-compatible AI client (Claude Desktop, Continue.dev, etc.)



## Contributing



We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.



# Gluestack UI MCP Server Implementation Summary



## 🎉 Implementation Complete



The Gluestack UI MCP Server has been successfully implemented with all planned features and capabilities.



## ✅ Completed Features



### 1. **Project Foundation**

- ✅ Complete TypeScript project setup with proper configuration

- ✅ NPM package configuration with all necessary dependencies

- ✅ Build system with TypeScript compilation

- ✅ Executable binary setup with proper shebang



### 2. **Core MCP Server Infrastructure** 

- ✅ MCP Protocol server implementation using `@modelcontextprotocol/sdk`

- ✅ STDIO transport for communication with AI clients

- ✅ Request/response handlers for tool calls

- ✅ Comprehensive error handling and logging

- ✅ Server capabilities registration



### 3. **CLI & Configuration**

- ✅ Command-line argument parsing (`--gluestack-path`, `--log-level`, `--help`)

- ✅ Environment variable support (`GLUESTACK_PATH`, `LOG_LEVEL`)

- ✅ Winston-based logging system with configurable levels

- ✅ Help system with usage examples



### 4. **Component Discovery System**

- ✅ Intelligent component detection across multiple variants

- ✅ Support for NativeWind, Themed, and Unstyled component variants

- ✅ Automatic detection of component features (demos, stories, docs)

- ✅ Metadata extraction from package.json and source files

- ✅ Component relationship analysis and dependency tracking



### 5. **MCP Tools Implementation**

- ✅ **`list_components`** - Lists all 70+ available components

- ✅ **`get_component`** - Retrieves component source code

- ✅ **`get_component_demo`** - Gets component examples and stories

- ✅ **`get_component_metadata`** - Extracts props, dependencies, examples

- ✅ **`list_component_variants`** - Shows all variants for a component



### 6. **TypeScript Integration**

- ✅ Advanced TypeScript interface parsing for component props

- ✅ Dependency extraction from import statements

- ✅ JSDoc comment extraction for component documentation

- ✅ Type-safe API with comprehensive schemas



### 7. **Multi-Variant Support**

- ✅ **NativeWind Variant** - Modern Tailwind CSS styling (primary)

- ✅ **Themed Variant** - Gluestack design system tokens

- ✅ **Unstyled Variant** - Headless components for custom styling

- ✅ Intelligent variant selection with fallbacks



### 8. **Documentation & Testing**

- ✅ Comprehensive README with usage examples

- ✅ API documentation for all tools

- ✅ Integration guides for Claude Desktop, Continue.dev, etc.

- ✅ Test scripts and validation

- ✅ MIT License and contribution guidelines



## 🏗️ Architecture Overview



```

gluestack-ui-mcp-server/

├── src/

│   ├── index.ts                    # Entry point

│   ├── server/                     # MCP server core

│   │   ├── index.ts               # Server startup logic

│   │   ├── createServer.ts        # Server instance creation

│   │   ├── handler.ts             # Request handlers

│   │   ├── capabilities.ts        # Server capabilities

│   │   └── version.ts             # Version management

│   ├── tools/                      # MCP tool implementations

│   │   └── components/            # Component-related tools

│   │       ├── list-components.ts

│   │       ├── get-component.ts

│   │       ├── get-component-demo.ts

│   │       ├── get-component-metadata.ts

│   │       └── list-component-variants.ts

│   ├── utils/                      # Utilities and helpers

│   │   ├── component-discovery.ts  # Component detection engine

│   │   └── logger.ts              # Logging system

│   └── cli/                       # Command-line interface

│       └── args.ts                # Argument parsing

├── build/                          # Compiled JavaScript

└── README.md                      # Complete documentation

```



## 🚀 Key Capabilities



### Component Library Support

- **126 Components**: Complete Gluestack UI component library coverage

- **Cross-Platform**: React Native components that work on iOS, Android, Web

- **Modern Styling**: NativeWind (Tailwind) integration

- **Design System**: Themed variant with design tokens

- **Flexibility**: Unstyled variant for complete customization



### AI Integration Features

- **Rich Context**: Provides complete component source code with TypeScript types

- **Usage Examples**: Real working examples from Storybook demos

- **Metadata Extraction**: Props interfaces, dependencies, documentation

- **Intelligent Search**: Component discovery by name or category

- **Variant Awareness**: Automatically selects best variant for use case



### Developer Experience

- **Zero Configuration**: Works with default paths and settings

- **Flexible Setup**: Supports custom Gluestack UI installations

- **Comprehensive Logging**: Detailed debugging and monitoring

- **Error Handling**: Graceful failures with helpful error messages

- **Security Hardened**: Package overrides and dependency locking for enhanced security

- **Type Safety**: Full TypeScript support throughout



## 🎯 Usage Examples



### Basic Component Retrieval

```bash

# List all components

echo '{"method": "tools/call", "params": {"name": "list_components"}}' | npx gluestack-ui-mcp-server



# Get Button component source

echo '{"method": "tools/call", "params": {"name": "get_component", "arguments": {"componentName": "Button"}}}' | npx gluestack-ui-mcp-server

```



### Claude Desktop Integration

```json

{

  "mcpServers": {

    "gluestack-ui": {

      "command": "npx",

      "args": ["gluestack-ui-mcp-server"],

      "env": {

        "GLUESTACK_PATH": "/path/to/gluestack-ui"

      }

    }

  }

}

```



## 🔧 Technical Decisions



### Component Discovery Strategy

- **Primary Source**: `example/storybook-nativewind/src/components/` for rich examples

- **Fallback Sources**: Core packages for implementation details

- **Caching**: In-memory component registry for performance

- **Multi-Variant**: Concurrent discovery across all variant types



### TypeScript Parsing

- **Regex-Based**: Lightweight interface parsing without AST complexity

- **Prop Extraction**: Automatic detection of component props and types

- **Import Analysis**: Dependency tracking from import statements

- **JSDoc Support**: Comment extraction for documentation



### Error Handling

- **Graceful Degradation**: Continue operation even if some components fail

- **Detailed Logging**: Comprehensive error context for debugging

- **User-Friendly Messages**: Clear error messages for common issues

- **Circuit Breaker**: Prevent cascading failures in component discovery



## 🌟 Benefits for AI Development



### Accelerated Development

- **Instant Access**: Components available to AI assistants immediately

- **Best Practices**: Examples show proper component usage patterns  

- **Type Safety**: TypeScript interfaces ensure correct prop usage

- **Variant Selection**: Automatic selection of most appropriate variant



### Enhanced Code Quality

- **Consistent Styling**: Gluestack UI design system principles

- **Accessibility**: Components built with accessibility best practices

- **Cross-Platform**: Write once, run on iOS, Android, Web

- **Modern Stack**: Latest React Native and styling approaches



### Productivity Boost

- **Reduced Lookup**: No need to manually browse documentation

- **Complete Context**: Source code, examples, and metadata in one request

- **Intelligent Discovery**: Find components by functionality or name

- **Rapid Prototyping**: Quickly scaffold UI components



## 🎊 Ready for Production



The Gluestack UI MCP Server is now complete and ready for:



- **AI Assistant Integration** (Claude Desktop, Continue.dev, Cursor, etc.)

- **NPM Package Publication** (`gluestack-ui-mcp-server`)

- **Community Use** (Open source with MIT license)

- **Enterprise Deployment** (Supports custom installations and configurations)



This implementation provides AI assistants with comprehensive access to the Gluestack UI ecosystem, enabling rapid development of high-quality React Native applications with modern styling and cross-platform compatibility.



## License



MIT



**Built in Melbourne with ❤️ for the Gluestack and AI development communities**