@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

Table of Contents

• Installation
• Quick Start
• Commands Reference
  • Root Command
  • MCP Commands
  • Documentation Commands
  • Template Commands
• Interactive Mode
• MCP Server Integration
• Component Categories
• Development
• Architecture
• Roadmap
• License

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-react/cli
bun install
bun run build

Quick Start

# Start interactive mode
asphalt

# Start MCP server for AI integration
asphalt mcp

# Configure MCP for your IDE
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

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
• Logs to stderr (stdout is reserved for MCP messages)
• Graceful shutdown on SIGINT/SIGTERM

Initialize MCP Configuration

asphalt mcp init [options]

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

Options:

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

Supported Clients:

| Client | Config File Location | |--------|---------------------| | claude | ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) | | vscode | VS Code MCP settings | | cursor | Cursor MCP settings | | opencode | OpenCode MCP settings |

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 (global or per-action) |

Actions

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 UI components only
asphalt docs list-components --category ui

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

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 for input-related components
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 (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 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 (with sub-component selection if available)
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 of 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 for your IDE.

skill init

Install Asphalt skill templates.

asphalt skill init [options]

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

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 specific skill
asphalt skill init --platform github --skill asphalt-ui-builder

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

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

Interactive Mode

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

Main Menu

Running asphalt without arguments shows an interactive 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, you'll be guided through:

1. Category selection - Choose from ui, form, layout, data, charts, utilities
2. Component selection - Pick from components in that category

Interactive Features

• Validation: Inline error messages with automatic re-prompting
• Search queries: 2-200 character validation
• Numeric limits: Range validation (1-50 for search results)
• Multi-select: Space to toggle, Enter to confirm
• Graceful exit: Ctrl+C exits cleanly at any prompt
• Type-to-filter: Arrow keys and typing to filter long lists

MCP Server Integration

Claude Desktop Configuration

Add to your Claude Desktop config file:

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

Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Or use automatic configuration:

asphalt mcp init --client claude

Available MCP Tools

| Tool | Description | Input | |------|-------------|-------| | list_components | List all Asphalt components by category | { category?: string } | | search_components | Search components by keywords | { query: string, limit?: number } | | get_component_docs | Fetch full README for a component | { component: string } | | get_component_props | Extract props table (supports sub-components) | { component: string, subComponent?: string } | | get_component_examples | Extract code examples | { component: string } | | get_component_subcomponents | List sub-components | { component: string } |

Testing MCP Communication

# Send a JSON-RPC initialize request
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:

| Category | Components | Description | |----------|------------|-------------| | ui | 12 | Buttons, modals, cards, badges, avatars, loaders, typography, popovers, flags | | form | 10 | Text fields, checkboxes, radios, selects, toggles, sliders, file uploaders, date/time pickers | | layout | 7 | Stack, layout, sidebar, appbar, breadcrumb, logo, content-switcher | | data | 8 | Tables, data-tables, pagination, accordions, tabs, action lists, progress bars, wizards | | charts | 1 | Data visualization charting library | | utilities | 8 | Theme provider, icon packs, context, helpers, SSR support |

Development

Prerequisites

• Bun v1.0.0+ (for development)
• Node.js 18+ (for running the built CLI)

Setup

# Install dependencies
bun install

Running Locally

# Run in development mode (with hot reload)
bun run mcp:dev

# Run in production mode
bun run mcp

# Run CLI commands directly
bun run src/index.ts docs list-components

Testing

# Run 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 JS bundle (~665 KB) for npm/npx usage | | dist/templates/ | Template files for skills, agents, commands | | bin/asphalt-darwin-arm64 | Native binary for macOS Apple Silicon (~66 MB) | | bin/asphalt-darwin-x64 | Native binary for macOS Intel (~72 MB) |

Testing the builds:

# JS bundle (requires Node.js)
node dist/index.js help
node dist/index.js docs list-components

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

Note: Native binaries use help and version commands instead of --help and --version flags (Bun runtime intercepts those flags).

Testing with npm link

# From 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 testing
npm pack

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

# Test the tarball
npx ./asphalt-react-cli-*.tgz --help

# Publish to npm
npm publish

Architecture

asphalt-cli/
├── src/
│   ├── index.ts              # CLI entry point with command routing
│   ├── commands/
│   │   ├── mcp.ts            # MCP server command with init subcommand
│   │   ├── init.ts           # MCP config initializer
│   │   ├── docs.ts           # Documentation CLI (6 actions)
│   │   ├── skill-init.ts     # Skill template installation
│   │   ├── agent-init.ts     # Agent template installation
│   │   ├── command-init.ts   # Slash command template installation
│   │   └── tools/            # MCP tool implementations
│   ├── lib/
│   │   ├── components.ts     # Component registry (46 components)
│   │   ├── doc-fetcher.ts    # CDN documentation fetcher
│   │   ├── markdown-parser.ts # README parsing utilities
│   │   ├── cache.ts          # In-memory doc cache
│   │   ├── retry.ts          # Exponential backoff retry
│   │   ├── search.ts         # Component search utilities
│   │   ├── config-manager.ts # MCP config file manager
│   │   ├── cli-utils.ts      # CLI argument parsing utilities
│   │   ├── interactive-prompt.ts # Interactive CLI prompts
│   │   ├── table-formatter.ts # Markdown table formatter
│   │   ├── template-*.ts     # Template system modules
│   │   └── *-manager.ts      # Template managers (skill, agent, command)
│   ├── types/
│   │   └── template.ts       # Template type definitions
│   └── mcp/
│       └── server.ts         # MCP server factory
├── templates/
│   ├── skills/               # Skill templates
│   ├── agents/               # Agent templates
│   └── slash-commands/       # Command templates
├── build.ts                  # Bun bundler script
└── dist/                     # Built output (Node.js ESM)

Key Design Decisions

• Dual Mode: Single codebase serves both MCP server and standalone CLI
• Lazy Loading: Commands are loaded on-demand to minimize startup time
• Interactive First: Missing options trigger helpful prompts instead of errors
• Shared Library: Core functionality in src/lib/ used by both modes
• Smart Caching: In-memory cache with request deduplication for CDN fetches
• Graceful Degradation: Prefetch errors don't block MCP server startup

Roadmap

Planned Features

The following features are planned for future releases:

Agent Templates (Coming Soon)

Install Asphalt agent templates for enhanced IDE functionality.

asphalt agent init [options]

| Option | Description | |--------|-------------| | --platform <name> | Target platform: github, opencode (can be repeated) | | --agent <name> | Agent template name (can be repeated, or use all) | | --force, -f | Overwrite existing files |

Examples:

# Interactive mode
asphalt agent init

# Install for specific platform
asphalt agent init --platform github

# Install specific agent
asphalt agent init --platform github --agent my-agent

# Install all agents with force overwrite
asphalt agent init --platform github --agent all --force

Slash Command Templates (Coming Soon)

Install custom slash command templates for your IDE.

asphalt command init [options]

| Option | Description | |--------|-------------| | --platform <name> | Target platform: github, opencode (can be repeated) | | --command <name> | Command template name (can be repeated, or use all) | | --force, -f | Overwrite existing files |

Examples:

# Interactive mode
asphalt command init

# Install for specific platform
asphalt command init --platform github

# Install specific command
asphalt command init --platform github --command my-command

# Install all commands
asphalt command init --platform opencode --command all

License

MIT

This project was created using bun init in bun v1.3.4. Bun is a fast all-in-one JavaScript runtime.