> ## Documentation Index
> Fetch the complete documentation index at: https://docs.leanmcp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# UI Components

> MCP-native React components for building MCP Apps

# MCP Components

React components designed for seamless integration with MCP tools. Each component provides built-in loading states, error handling, and host theming support.

## ToolButton

Button that executes an MCP tool on click with optional confirmation, loading states, and result display.

### Basic Usage

```tsx theme={null}
<ToolButton tool="refresh-data">
  Refresh
</ToolButton>
```

### With Result Display

```tsx theme={null}
<ToolButton 
  tool="create-order" 
  args={{ product: 'shoes' }}
  resultDisplay="toast"
  successMessage="Order created!"
  onToolSuccess={(order) => console.log('Created:', order.id)}
>
  Place Order
</ToolButton>
```

### With Confirmation Dialog

```tsx theme={null}
<ToolButton 
  tool="delete-item" 
  args={{ id: item.id }}
  confirm={{ 
    title: 'Delete Item?',
    description: 'This action cannot be undone.' 
  }}
  variant="destructive"
>
  Delete
</ToolButton>
```

### Props Reference

| Prop            | Type                                                 | Description                        |
| --------------- | ---------------------------------------------------- | ---------------------------------- |
| `tool`          | `string \| ToolBinding`                              | Tool name or binding config        |
| `args`          | `Record<string, unknown>`                            | Arguments to pass to the tool      |
| `resultDisplay` | `'inline' \| 'toast' \| 'modal' \| 'none'`           | How to display results             |
| `confirm`       | `boolean \| ConfirmConfig`                           | Show confirmation before executing |
| `variant`       | `'default' \| 'destructive' \| 'outline' \| 'ghost'` | Button style variant               |
| `loadingText`   | `string`                                             | Text to show while loading         |
| `onToolSuccess` | `(result) => void`                                   | Called on successful execution     |
| `onToolError`   | `(error) => void`                                    | Called on error                    |

***

## ToolDataGrid

Data grid with server-side pagination, sorting, and row actions - all powered by MCP tools.

### Basic Usage

```tsx theme={null}
<ToolDataGrid
  dataTool="list-users"
  columns={[
    { key: 'name', header: 'Name', sortable: true },
    { key: 'email', header: 'Email' },
    { key: 'status', header: 'Status' }
  ]}
  transformData={(result) => ({
    rows: result.users,
    total: result.total
  })}
/>
```

### With Row Actions

```tsx theme={null}
<ToolDataGrid
  dataTool="list-orders"
  columns={columns}
  rowActions={[
    { 
      label: 'Edit', 
      tool: 'edit-order',
      getArgs: (row) => ({ id: row.id })
    },
    { 
      label: 'Delete', 
      tool: 'delete-order',
      variant: 'destructive',
      confirm: true
    }
  ]}
  pagination
  defaultPageSize={25}
/>
```

### Props Reference

| Prop              | Type                          | Description                        |
| ----------------- | ----------------------------- | ---------------------------------- |
| `dataTool`        | `string \| ToolBinding`       | Tool to fetch data from            |
| `columns`         | `ToolDataGridColumn[]`        | Column definitions                 |
| `transformData`   | `(result) => { rows, total }` | Transform tool result to grid data |
| `rowActions`      | `ToolDataGridRowAction[]`     | Actions for each row               |
| `pagination`      | `boolean`                     | Enable pagination (default: true)  |
| `defaultPageSize` | `number`                      | Initial page size                  |
| `refreshInterval` | `number`                      | Auto-refresh interval in ms        |
| `onRowClick`      | `(row, index) => void`        | Row click handler                  |

### Column Definition

```typescript theme={null}
interface ToolDataGridColumn {
  key: string;           // Field key (dot notation supported)
  header: string;        // Column header text
  sortable?: boolean;    // Enable sorting
  render?: (value, row, index) => ReactNode;  // Custom renderer
  width?: string;        // CSS width
  align?: 'left' | 'center' | 'right';
}
```

***

## ToolForm

Form component that submits data to an MCP tool with built-in field types and validation.

### Basic Usage

```tsx theme={null}
<ToolForm
  toolName="create-user"
  fields={[
    { name: 'name', label: 'Name', required: true },
    { name: 'email', label: 'Email', type: 'email', required: true },
    { name: 'role', label: 'Role', type: 'select', 
      options: [
        { value: 'admin', label: 'Admin' },
        { value: 'user', label: 'User' }
      ] 
    },
    { name: 'notify', label: 'Send welcome email', type: 'switch' }
  ]}
  submitText="Create User"
  showSuccessToast
  onSuccess={(user) => console.log('Created:', user)}
/>
```

### Field Types

| Type       | Description                   |
| ---------- | ----------------------------- |
| `text`     | Standard text input (default) |
| `number`   | Numeric input with min/max    |
| `email`    | Email input with validation   |
| `password` | Password input                |
| `textarea` | Multi-line text               |
| `select`   | Dropdown selection            |
| `checkbox` | Boolean checkbox              |
| `switch`   | Toggle switch                 |
| `slider`   | Range slider                  |

### Props Reference

| Prop               | Type                         | Description              |
| ------------------ | ---------------------------- | ------------------------ |
| `toolName`         | `string`                     | Tool to call on submit   |
| `fields`           | `ToolFormField[]`            | Field definitions        |
| `submitText`       | `string`                     | Submit button text       |
| `showSuccessToast` | `boolean`                    | Show toast on success    |
| `resetOnSuccess`   | `boolean`                    | Reset form after success |
| `onSuccess`        | `(result) => void`           | Success callback         |
| `onError`          | `(error) => void`            | Error callback           |
| `layout`           | `'vertical' \| 'horizontal'` | Form layout              |

***

## ToolSelect

Select component that can fetch options from a tool and/or trigger a tool on selection.

### Fetch Options from Tool

```tsx theme={null}
<ToolSelect
  optionsTool="list-categories"
  transformOptions={(result) => result.categories.map(c => ({
    value: c.id,
    label: c.name
  }))}
  placeholder="Select category"
/>
```

### Call Tool on Selection

```tsx theme={null}
<ToolSelect
  options={[
    { value: 'asc', label: 'Ascending' },
    { value: 'desc', label: 'Descending' }
  ]}
  onSelectTool="set-sort-order"
  argName="order"
/>
```

### Props Reference

| Prop               | Type                    | Description                      |
| ------------------ | ----------------------- | -------------------------------- |
| `optionsTool`      | `string \| ToolBinding` | Tool to fetch options from       |
| `transformOptions` | `(result) => Option[]`  | Transform result to options      |
| `onSelectTool`     | `string \| ToolBinding` | Tool to call on selection        |
| `argName`          | `string`                | Argument name for selected value |
| `options`          | `ToolSelectOption[]`    | Static options                   |
| `value`            | `string`                | Controlled value                 |
| `onValueChange`    | `(value) => void`       | Change handler                   |

***

## ToolInput

Text input with debounced tool calls for search/autocomplete scenarios.

```tsx theme={null}
<ToolInput
  searchTool="search-items"
  argName="query"
  debounceMs={300}
  placeholder="Search items..."
  onResults={(items) => setSearchResults(items)}
/>
```

***

## ResourceView

Display an MCP resource with auto-refresh support.

```tsx theme={null}
<ResourceView
  uri="config://settings"
  refreshInterval={30000}
  render={(data) => (
    <pre>{JSON.stringify(data, null, 2)}</pre>
  )}
/>
```

***

## Utility Components

### RequireConnection

Guard wrapper that shows loading/error states until MCP connection is established.

```tsx theme={null}
<AppProvider appInfo={{ name: 'MyApp', version: '1.0.0' }}>
  <RequireConnection 
    loadingContent={<Spinner />}
    errorContent={(error) => <Alert>{error.message}</Alert>}
  >
    <MyMCPContent />
  </RequireConnection>
</AppProvider>
```

### ToolErrorBoundary

Error boundary with retry functionality for tool-related errors.

```tsx theme={null}
<ToolErrorBoundary onRetry={() => refetch()}>
  <ToolDataGrid dataTool="list-items" columns={columns} />
</ToolErrorBoundary>
```

### StreamingContent

Render streaming/partial tool data as it arrives.

```tsx theme={null}
<StreamingContent
  render={(partial) => <MarkdownPreview content={partial.text} />}
/>
```