UICP Monorepo

UICP (User Interface Context Protocol) enables LLM-based agents to describe and render UI components dynamically. This monorepo contains framework-agnostic packages for parsing and creating UICP components, plus a Next.js example application.

Packages

@uicp/parser

Core parsing library for extracting and rendering UICP blocks from LLM output.

npm install @uicp/parser

Features:

• Extract UICP blocks from markdown
• Validate blocks against component definitions
• Dynamic component loading with configurable base path
• React component rendering
• TypeScript support

@uicp/tools

Framework-agnostic AI tools for component discovery and creation.

npm install @uicp/tools

Features:

• Discover available UI components
• Create UICP blocks with validation
• Load definitions from URLs or file paths
• Built-in caching for performance
• Works with any LLM framework

Example Application

nextjs-chat

A full-featured Next.js chat application demonstrating UICP with Vercel AI SDK.

Features:

• Real-time chat with streaming responses
• Dynamic UI component rendering
• Two example components (SimpleCard, DataTable)
• Vercel AI SDK integration

Quick Start

1. Clone and Install

git clone https://github.com/uicp/uicp.git
cd uicp
npm install

2. Build Packages

npm run build

3. Run Example

cd examples/nextjs-chat
cp .env.example .env
# Add your OPENAI_API_KEY to .env
npm run dev

Visit http://localhost:3000 and try asking:

• "Create a card with a welcome message"
• "Show me sales data in a table"

Development

Workspace Structure

uicp/
├── packages/
│   ├── parser/          # @uicp/parser
│   └── tools/           # @uicp/tools
└── examples/
    └── nextjs-chat/     # Example Next.js app

Commands

# Build all packages
npm run build

# Build specific package
npm run build:parser
npm run build:tools

# Run example in dev mode
npm run dev:example

# Clean all builds
npm run clean

# Lint all packages
npm run lint

How It Works

1. Define Components

Create a definitions.json with your UI components:

{
  "version": "1.0.0",
  "components": [
    {
      "uid": "SimpleCard",
      "type": "card",
      "description": "A card component",
      "componentPath": "components/uicp/simple-card",
      "inputs": {
        "title": {
          "type": "string",
          "required": true
        }
      }
    }
  ]
}

2. Use Tools in Your Agent

import { getUIComponents, createUIComponent } from '@uicp/tools';

// Discover components
const components = await getUIComponents('./definitions.json');

// Create a UICP block
const result = await createUIComponent('./definitions.json', {
  uid: 'SimpleCard',
  data: { title: 'Hello World' }
});

3. Parse and Render

import { parseUICPContent, registerComponent } from '@uicp/parser';
import { SimpleCard } from './components/simple-card';

// Register your component
registerComponent('SimpleCard', SimpleCard);

// Parse content from LLM
const parsed = await parseUICPContent(content, {
  definitions: './definitions.json',
  componentsBasePath: '/components/uicp'
});

Key Principles

1. Dynamic Definitions: Components are defined in JSON, allowing updates without code changes
2. Framework Agnostic: Core tools work with any LLM framework (OpenAI, Anthropic, LangChain, etc.)
3. Type Safe: Full TypeScript support with generated types
4. Flexible Loading: Load components dynamically or pre-register for performance
5. Validation: Built-in schema validation for component data

Documentation

• Parser Package
• Tools Package
• Example App
• Local Development & Testing Guide

Local Testing

Want to test the packages locally before publishing? We've got you covered!

Quick Link (Recommended)

# Build and link packages
./scripts/link-local.sh         # Unix/Mac
.\scripts\link-local.ps1        # Windows

# In your test project
cd /path/to/your/test-project
npm link @uicp/parser @uicp/tools

Development Mode

# Terminal 1: Auto-rebuild parser
cd packages/parser && npm run dev

# Terminal 2: Auto-rebuild tools
cd packages/tools && npm run dev

# Terminal 3: Run your test project
cd /path/to/your/test-project
npm run dev

For detailed testing strategies, troubleshooting, and alternative methods (npm pack, file protocol), see the Local Development Guide.

Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Ensure all packages build successfully
6. Submit a pull request

Development Setup

npm install
npm run build

License

MIT License - see LICENSE for details.

Links

• GitHub Repository
• Issue Tracker
• NPM Organization

---

Built with ❤️ by the UICP community