@asphalt-react/cli

v1.1.0

Published

2 months ago

MCP server for Asphalt React component documentation

0High
0Medium
0Low

mcp asphalt react components documentation model-context-protocol

@asphalt-react/cli

MCP server and CLI for Asphalt React component documentation. Provides AI assistants and command-line access to comprehensive component documentation from the Asphalt Design System.

Package Name: @asphalt-react/cli | Binary: asphalt | Version: 1.0.2

Installation

Via npx (Recommended)

No installation required:

npx @asphalt-react/cli --help

Global Installation

npm install -g @asphalt-react/cli
asphalt --help

Local Development

git clone <repository-url>
cd asphalt-cli
bun install
bun run build

Prerequisites for local development:

Bun v1.0.0+ (build toolchain)
Node.js 18+ (to run the built output)

Quick Start

# Start interactive mode
asphalt

# Start MCP server for AI integration
asphalt mcp

# Configure MCP for your IDE automatically
asphalt mcp init --client claude

# Browse component documentation
asphalt docs list-components
asphalt docs search-components --query "button"
asphalt docs get-component-docs --component modal

# Install the Asphalt skill for your IDE
asphalt skill init --platform github

Commands Reference

Root Command

asphalt [command] [options]

| Command | Description | | ---------------------------- | ------------------------------------- | | (none) | Start interactive mode with main menu | | mcp | MCP server commands | | docs | Component documentation commands | | skill init | Install skill templates | | --help, -h, help | Show help information | | --version, -v, version | Show version information |

MCP Commands

Start MCP Server

asphalt mcp

Starts the MCP server using stdio transport. The server provides AI assistants with tools to access Asphalt React component documentation.

Features:

Prefetches popular components (button, textfield, modal, card, stack) in background on startup
All logs go to stderr (stdout is reserved for the MCP protocol messages)
Graceful shutdown on SIGINT/SIGTERM

Initialize MCP Configuration

asphalt mcp init [options]

Configures MCP integration for your IDE by creating or updating its configuration file.

Options:

| Option | Description | | ----------------- | ------------------------------------------------------- | | --client <name> | Target client: claude, vscode, cursor, opencode |

Supported Clients:

| Client | Config File | | ---------- | ------------------------------------------------------------------------- | | claude | ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) | | cursor | ~/Library/Application Support/Cursor/claude_desktop_config.json (macOS) | | vscode | .vscode/mcp.json (in current project directory) | | opencode | .opencode/opencode.json (in current project directory) |

Examples:

# Interactive mode (prompts for client)
asphalt mcp init

# Direct mode
asphalt mcp init --client claude
asphalt mcp init --client vscode
asphalt mcp init --client cursor
asphalt mcp init --client opencode

Documentation Commands

asphalt docs [action] [options]

Access Asphalt React component documentation from the command line.

Global Options:

| Option | Description | | -------------- | --------------------------------------------------- | | --help, -h | Show help for the docs command or a specific action |

list-components

List all Asphalt React components, optionally filtered by category.

asphalt docs list-components [options]

| Option | Description | | ------------------- | ------------------------------------------------------------------------- | | --category <name> | Filter by category: ui, form, layout, data, charts, utilities |

Examples:

# Interactive mode (prompts for category)
asphalt docs list-components

# List all components
asphalt docs list-components --category all

# List by category
asphalt docs list-components --category ui
asphalt docs list-components --category form
asphalt docs list-components --category layout

search-components

Search components by keywords with relevance scoring.

asphalt docs search-components [options]

| Option | Required | Description | | ------------------ | -------- | ------------------------------- | | --query <text> | Yes | Search query (2–200 characters) | | --limit <number> | No | Max results, 1–50 (default: 10) |

Examples:

# Interactive mode (prompts for query and limit)
asphalt docs search-components

# Search with query
asphalt docs search-components --query "input"

# Search with custom limit
asphalt docs search-components --query "button" --limit 5

get-component-docs

Fetch the full README documentation for a component.

asphalt docs get-component-docs [options]

| Option | Required | Description | | -------------------- | -------- | ---------------------------------------- | | --component <name> | Yes | Component name (e.g., button, modal) |

Examples:

# Interactive mode (two-step category → component selection)
asphalt docs get-component-docs

# Direct mode
asphalt docs get-component-docs --component button
asphalt docs get-component-docs --component modal
asphalt docs get-component-docs --component data-table

get-component-props

Extract the props table for a component or one of its sub-components.

asphalt docs get-component-props [options]

| Option | Required | Description | | ------------------------ | -------- | --------------------------- | | --component <name> | Yes | Component name | | --sub-component <name> | No | Specific sub-component name |

Examples:

# Interactive mode (category → component → sub-component selection)
asphalt docs get-component-props

# Get main component props
asphalt docs get-component-props --component button

# Get sub-component props
asphalt docs get-component-props --component typography --sub-component Heading

get-component-examples

Extract code examples from component documentation.

asphalt docs get-component-examples [options]

| Option | Required | Description | | -------------------- | -------- | -------------- | | --component <name> | Yes | Component name |

Examples:

# Interactive mode
asphalt docs get-component-examples

# Direct mode
asphalt docs get-component-examples --component button
asphalt docs get-component-examples --component modal

get-component-subcomponents

List all sub-components exported by a component.

asphalt docs get-component-subcomponents [options]

| Option | Required | Description | | -------------------- | -------- | -------------- | | --component <name> | Yes | Component name |

Examples:

# Interactive mode
asphalt docs get-component-subcomponents

# Direct mode
asphalt docs get-component-subcomponents --component typography
asphalt docs get-component-subcomponents --component button

Template Commands

Install skills, agents, and slash commands to extend AI assistant capabilities in your IDE.

skill init

Install Asphalt skill templates.

asphalt skill init [options]

| Option | Description | | ------------------- | ------------------------------------------------------------ | | --platform <name> | Target platform: github, opencode, claude (repeatable) | | --skill <name> | Skill template name (repeatable, or use all) | | --force, -f | Overwrite existing files |

Platform installation paths:

| Platform | Install Directory | | ---------- | --------------------------------- | | github | .github/copilot-skills/<skill>/ | | opencode | .opencode/skills/<skill>/ | | claude | .claude/skills/<skill>/ |

Available Skills:

| Skill | Description | | --------- | ----------------------------------------------------------------------------------------------------------------------------------- | | asphalt | Build production-ready TypeScript React components from screenshots or natural language using the Asphalt Design System exclusively |

Examples:

# Interactive mode (prompts for platform and skill selection)
asphalt skill init

# Install for GitHub Copilot
asphalt skill init --platform github

# Install for multiple platforms
asphalt skill init --platform github --platform opencode

# Install a specific skill
asphalt skill init --platform github --skill asphalt

# Install all available skills
asphalt skill init --platform github --skill all

# Force overwrite existing files
asphalt skill init --platform github --force

After installation, commit the generated skill files to version control and reload your IDE to activate the skill.

Interactive Mode

The CLI provides a rich interactive experience when required options are omitted.

Main Menu

Running asphalt without arguments shows an interactive selection menu:

? What would you like to do?
> Browse Component Documentation
  Configure MCP Server
  Install Skills
  Show Help
  Show Version

Docs Action Menu

Running asphalt docs without an action shows:

? What would you like to do?
> List all components
  Search for components
  Get component documentation
  Get component props
  Get code examples
  Get sub-components

Component Selection

When a component is required but not provided, the CLI guides you through two steps:

Category selection — Choose from ui, form, layout, data, charts, utilities
Component selection — Pick from the components in that category

Interactive Features

Automatic re-prompting: Inline validation errors are shown and the prompt retries without exiting
Search queries: Validated to 2–200 characters
Numeric limits: Range-validated (1–50 for search results)
Multi-select prompts: Space to toggle, Enter to confirm
Graceful exit: Ctrl+C exits cleanly at any prompt
Automation-friendly: Providing flags bypasses all prompts — no interactive input is required when all required options are supplied

MCP Server Integration

The Asphalt MCP server uses stdio transport and exposes 6 tools for AI assistants to access Asphalt Design System documentation.

Available MCP Tools

| Tool | Input | Description | | ----------------------------- | ---------------------------------------------- | ---------------------------------------------------- | | list_components | { category?: string } | List all components, optionally by category | | search_components | { query: string, limit?: number } | Search components by keywords with relevance scoring | | get_component_docs | { component: string } | Fetch full README markdown for a component | | get_component_props | { component: string, subComponent?: string } | Extract the props table (supports sub-components) | | get_component_examples | { component: string } | Extract all code examples from a component's docs | | get_component_subcomponents | { component: string } | List available sub-components |

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "asphalt-react": {
      "command": "npx",
      "args": ["-y", "@asphalt-react/cli@latest", "mcp"]
    }
  }
}

Cursor

macOS: ~/Library/Application Support/Cursor/claude_desktop_config.json

Windows: %APPDATA%\Cursor\claude_desktop_config.json

Linux: ~/.config/Cursor/claude_desktop_config.json

{
  "mcpServers": {
    "asphalt-react": {
      "command": "npx",
      "args": ["-y", "@asphalt-react/cli@latest", "mcp"]
    }
  }
}

VS Code

Create or update .vscode/mcp.json in your project root:

{
  "servers": {
    "asphalt-react": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@asphalt-react/cli@latest", "mcp"]
    }
  }
}

OpenCode

Create or update .opencode/opencode.json in your project root:

{
  "mcp": {
    "asphalt-react": {
      "type": "local",
      "command": ["npx", "-y", "@asphalt-react/cli@latest", "mcp"],
      "enabled": true
    }
  }
}

Automatic Configuration

Use the CLI to configure any supported client automatically:

asphalt mcp init --client claude
asphalt mcp init --client vscode
asphalt mcp init --client cursor
asphalt mcp init --client opencode

The command reads the existing config file, deep-merges the Asphalt server entry, and writes the result back without overwriting your other MCP servers.

Testing MCP Communication

echo '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}' | npx @asphalt-react/cli mcp

Component Categories

The CLI provides access to 46 Asphalt React components across 6 categories.

Summary

| Category | Count | Description | | ----------- | ----- | ----------------------------------------------------------------------- | | ui | 12 | Core visual components — buttons, modals, cards, indicators, typography | | form | 10 | Form controls — text fields, checkboxes, sliders, date/time pickers | | layout | 7 | Structural components — stacks, sidebars, app bars, navigation | | data | 8 | Data display — tables, accordions, tabs, wizards, progress bars | | charts | 1 | Data visualization charting library | | utilities | 8 | Cross-cutting concerns — theming, icons, SSR, helpers |

UI (12 components)

| Component | Description | | ------------ | ----------------------------------------------------- | | button | Buttons provide a way to trigger an action | | modal | Modal dialog for confirmations and important messages | | card | Card container for grouping related content | | badge | Badge for status indicators and counts | | tag | Tag for labeling and categorization | | avatar | Avatar for user profile images | | loader | Loading indicator for async operations | | typography | Typography components for text styling | | popover | Popover for contextual overlays | | flag | Flag component for alerts and notifications | | qualifier | Reusable qualifier component for hints | | crater | Crater component for visual elements |

Form (10 components)

| Component | Description | | --------------- | --------------------------------------------- | | textfield | Text input field with various types | | checkbox | Checkbox for multiple selections | | radio | Radio button for single selection | | selection | Selection component for choosing from options | | toggle-switch | Toggle switch for on/off states | | toggle-button | Toggle button for binary choices | | slider | Slider for range value selection | | file-uploader | File uploader for file input | | date-picker | Date picker for date selection | | time-picker | Time picker for time selection |

Layout (7 components)

| Component | Description | | ------------------ | ------------------------------------------------ | | stack | Stack layout for vertical/horizontal arrangement | | layout | Layout component for page structure | | sidebar | Sidebar navigation menu | | appbar | Application header bar | | breadcrumb | Breadcrumb navigation | | logo | Application logo and title | | content-switcher | Content switcher for tab-like navigation |

Data (8 components)

| Component | Description | | -------------- | ------------------------------------------ | | table | Basic table for tabular data | | data-table | Advanced data table with pagination | | pagination | Pagination controls for data navigation | | accordion | Accordion for collapsible content sections | | tab | Tab component for tabbed interfaces | | actionlist | Action list for menu items | | progress-bar | Progress bar for showing completion | | wizard | Wizard for step-by-step flows |

Charts (1 component)

| Component | Description | | ---------- | ----------------------------------- | | data-viz | Data visualization charting library |

Utilities (8 components)

| Component | Description | | ---------------- | ------------------------------------- | | theme-provider | Theme provider for theming support | | iconpack | Icon pack with Asphalt icons | | iconpack-aloha | Aloha icons for Asphalt | | icontuner | Icon tuner for customizing icons | | context | Shared context for Asphalt components | | helper | Common helper utilities | | ssr | Server-side rendering support | | svg-normalizer | SVG normalizer utility |

Development

Prerequisites

Bun v1.0.0+ (required for development and building)
Node.js 18+ (required to run the built CLI output)

Setup

bun install

Running Locally

# Run CLI commands directly with Bun (no build step needed)
bun run src/index.ts docs list-components
bun run src/index.ts mcp

# Start MCP server with hot reload
bun run mcp:dev

# Start MCP server (production mode, from source)
bun run mcp

Testing

# Run all tests
bun test

# Run tests in watch mode
bun test --watch

Building

# Build for distribution (JS bundle + native binaries)
bun run build

The build produces:

| Output | Description | | -------------------------- | ------------------------------------------------------- | | dist/index.js | Minified, bytecode-compiled JS bundle for npm/npx usage | | dist/templates/ | Template files copied for distribution | | bin/asphalt-darwin-arm64 | Standalone native binary for macOS Apple Silicon | | bin/asphalt-darwin-x64 | Standalone native binary for macOS Intel |

Testing the build:

# Test the JS bundle
node dist/index.js --help
node dist/index.js docs list-components

# Test a native binary (standalone, no runtime needed)
./bin/asphalt-darwin-arm64 help
./bin/asphalt-darwin-arm64 docs list-components

Native binaries use help and version as commands instead of --help / --version because the Bun runtime intercepts those flags at the binary level.

Testing with npm link

# Link the package globally from the project root
npm link

# Test from another directory
cd /tmp
asphalt --help
asphalt docs list-components

Publishing

# Build for distribution
bun run build

# Create a tarball for inspection
npm pack

# Inspect tarball contents
tar -tzf asphalt-react-cli-*.tgz

# Publish to npm
npm publish

Architecture

asphalt-cli/
├── src/
│   ├── index.ts              # CLI entry point — command routing, interactive menu, help/version
│   ├── commands/
│   │   ├── mcp.ts            # MCP server startup and mcp init routing
│   │   ├── init.ts           # MCP config file writer for all 4 clients
│   │   ├── docs.ts           # Standalone docs CLI (6 actions, full interactive support)
│   │   ├── skill-init.ts     # Skill template installation
│   │   ├── agent-init.ts     # Agent template installation (coming soon)
│   │   ├── command-init.ts   # Slash command template installation (coming soon)
│   │   └── tools/            # MCP tool implementations (one file per tool)
│   ├── lib/
│   │   ├── components.ts     # Component registry (46 components across 6 categories)
│   │   ├── doc-fetcher.ts    # CDN doc fetcher with in-memory caching and deduplication
│   │   ├── markdown-parser.ts # Extracts props tables, examples, sub-components from README markdown
│   │   ├── cache.ts          # In-memory documentation cache
│   │   ├── retry.ts          # Exponential backoff retry (3 retries, 1 s delay)
│   │   ├── search.ts         # Keyword-based component search with relevance scoring
│   │   ├── schemas.ts        # Shared Zod validation schemas
│   │   ├── config-manager.ts # MCP config file reader/writer for Claude, VS Code, Cursor, OpenCode
│   │   ├── cli-utils.ts      # CLI flag parsing helpers
│   │   ├── table-formatter.ts # Padded markdown table formatter
│   │   ├── template-discovery.ts # Scans templates/ directory for available templates
│   │   ├── template-renderer.ts  # {{variable}} substitution in template files
│   │   ├── template-validator.ts # Validates template.json metadata
│   │   ├── template-manager.ts   # Generic template installation logic
│   │   ├── skill-manager.ts      # Skill-specific wrapper around template-manager
│   │   ├── agent-manager.ts      # Agent-specific wrapper around template-manager
│   │   ├── command-manager.ts    # Command-specific wrapper around template-manager
│   │   ├── interactive-prompt.ts # Re-exports all prompt functions
│   │   ├── config.ts         # Configuration constants (retry count, cache TTL, etc.)
│   │   ├── version.ts        # Version constant (injected at build time)
│   │   ├── errors.ts         # Typed error classes
│   │   └── prompts/          # Modular prompt functions
│   │       ├── main.ts       # Root menu prompt (5 options)
│   │       ├── docs.ts       # Docs action menu (6 actions)
│   │       ├── category.ts   # Category selection
│   │       ├── component.ts  # Two-step category → component selection
│   │       ├── client.ts     # MCP client selection
│   │       ├── platform.ts   # Multi-select platform prompt
│   │       ├── search.ts     # Search query and result limit prompts
│   │       ├── subcomponent.ts # Sub-component selection
│   │       ├── templates.ts  # Template selection prompts
│   │       ├── format.ts     # Category display formatting utilities
│   │       ├── load.ts       # Lazy prompt library loader
│   │       └── index.ts      # Re-exports all prompt functions
│   ├── types/
│   │   └── template.ts       # Template system type definitions
│   └── mcp/
│       └── server.ts         # MCP server factory (registers all 6 tools)
├── templates/
│   ├── skills/
│   │   └── asphalt/          # Asphalt UI Builder skill template
│   │       ├── template.json # Skill metadata
│   │       ├── SKILL.md      # Skill instructions and MCP tool usage guide
│   │       ├── mcp.md        # MCP integration reference
│   │       └── references/   # 12 component reference documents
│   ├── agents/               # Agent templates (coming soon)
│   └── slash-commands/       # Slash command templates (coming soon)
├── build.ts                  # Bun bundler script
├── tsconfig.json             # TypeScript configuration
└── dist/                     # Built output (not committed)

Key Design Decisions

Dual mode: A single codebase serves both the MCP server (stdio) and standalone CLI — tools are shared via src/lib/
Lazy loading: Command modules are dynamically imported on demand to minimize startup time
Interactive first: Missing required options trigger helpful prompts rather than hard errors
Smart caching: In-memory cache with concurrent request deduplication prevents duplicate CDN fetches; cache resets on server restart
Graceful degradation: Background prefetch failures do not block MCP server startup
Zod validation: All tool inputs and CLI flags are validated using shared Zod schemas in src/lib/schemas.ts
Template variables: Template files support {{variable}} substitution (version, author, date, skill name, etc.)

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for guidelines on how to submit bug reports, feature requests, and pull requests.

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@asphalt-react/cli

Table of Contents

Installation

Via npx (Recommended)

Global Installation

Local Development

Quick Start

Commands Reference

Root Command

MCP Commands

Start MCP Server

Initialize MCP Configuration

Documentation Commands

list-components

search-components

get-component-docs

get-component-props

get-component-examples

get-component-subcomponents

Template Commands

skill init

Interactive Mode

Main Menu

Docs Action Menu

Component Selection

Interactive Features

MCP Server Integration

Available MCP Tools

Claude Desktop

Cursor

VS Code

OpenCode

Automatic Configuration

Testing MCP Communication

Component Categories

Summary

UI (12 components)

Form (10 components)

Layout (7 components)

Data (8 components)

Charts (1 component)

Utilities (8 components)

Development

Prerequisites

Setup

Running Locally

Testing

Building

Testing with npm link

Publishing

Architecture

Key Design Decisions

Contributing

License