CLAUDE.md@libs/ui · diff
git:20251224.2fef682 to git:20260309.04e295c
37 added, 196 removed. Audit A to A.
# @frontmcp/ui - Development Guidelines
## Overview
- `@frontmcp/ui` provides **React components, hooks, and rendering utilities** for building interactive MCP widgets.
+ `@frontmcp/ui` provides **MUI-based React components, hooks, content renderers, and MCP bridge** for building interactive MCP widgets.
- This package requires React. For React-free utilities (bundling, build tools, platform adapters, theme), use `@frontmcp/uipack`.
+ Shipped to npm and loaded via esm.sh in the browser. Used by developers to build custom MCP resource components.
**Key Principles:**
- - React 18/19 components with TypeScript
- - SSR support via `react-dom/server`
- - Client-side hydration for interactive widgets
+ - MUI (Material UI) components with FrontMCP theming
+ - React 18/19 support with TypeScript
+ - Content renderers for JSX, MDX, HTML, PDF, CSV
- MCP bridge hooks for tool communication
+ - Client-side only (no Node.js native modules)
## Architecture
```text
libs/ui/src/
├── bridge/ # MCP bridge runtime and adapters
- ├── bundler/ # SSR component bundling (re-exports from uipack)
- ├── components/ # HTML string components (button, card, etc.)
- ├── layouts/ # Page layout templates
- ├── react/ # React components and hooks
- │ ├── Card.tsx # Card component
- │ ├── Button.tsx # Button component
- │ ├── Alert.tsx # Alert component
- │ ├── Badge.tsx # Badge component
- │ └── hooks/ # useMcpBridge, useCallTool, useToolInput
- ├── render/ # React 19 static rendering utilities
- ├── renderers/ # React renderer for template processing
- │ ├── react.renderer.ts # SSR renderer (react-dom/server)
- │ ├── react.adapter.ts # Client-side hydration adapter
- │ └── mdx.renderer.ts # MDX server-side renderer
- ├── universal/ # Universal React app shell
- ├── web-components/ # Custom HTML elements
+ ├── theme/ # MUI theme system (FrontMcpThemeProvider)
+ ├── components/ # MUI-based React components (Button, Card, etc.)
+ ├── renderer/ # Content renderers (mdx, html, react, pdf, csv)
+ ├── react/ # MCP bridge hooks (useCallTool, useToolInput, etc.)
+ ├── runtime/ # Content detection and Babel transpilation
└── index.ts # Main barrel exports
```
- ## Package Split
-
- | Package | Purpose | React Required |
- | ------------------ | ----------------------------------------------- | -------------- |
- | `@frontmcp/ui` | React components, hooks, SSR, HTML components | Yes |
- | `@frontmcp/uipack` | Bundling, build tools, platform adapters, theme | No |
-
- ### Import Patterns
+ ## Import Patterns
```typescript
- // React components and hooks (this package)
- import { Button, Card, Alert, Badge } from '@frontmcp/ui/react';
- import { useMcpBridge, useCallTool, useToolInput } from '@frontmcp/ui/react';
+ // Theme
+ import { FrontMcpThemeProvider, createFrontMcpTheme } from '@frontmcp/ui/theme';
- // SSR rendering
- import { ReactRenderer, reactRenderer, MdxRenderer, mdxRenderer } from '@frontmcp/ui/renderers';
+ // Components
+ import { Button, Card, Alert } from '@frontmcp/ui/components';
+ import { Button } from '@frontmcp/ui/components/Button';
- // Universal app shell
- import { UniversalApp, FrontMCPProvider } from '@frontmcp/ui/universal';
+ // Renderer
+ import { renderContent, detectContentType } from '@frontmcp/ui/renderer';
- // HTML string components
- import { button, card, alert, badge } from '@frontmcp/ui/components';
+ // Hooks
+ import { useMcpBridge, useCallTool, useToolInput } from '@frontmcp/ui/react';
- // MCP bridge
+ // Bridge
import { FrontMcpBridge, createBridge } from '@frontmcp/ui/bridge';
-
- // React-free utilities (from @frontmcp/uipack)
- import { buildToolUI } from '@frontmcp/uipack/build';
- import { DEFAULT_THEME } from '@frontmcp/uipack/theme';
- import type { AIPlatformType } from '@frontmcp/uipack/adapters';
```
- ## React Components
-
- ### Available Components
-
- ```typescript
- import { Card, Badge, Button, Alert } from '@frontmcp/ui/react';
-
- // Usage
- <Button variant="primary" onClick={handleClick}>
- Submit
- </Button>
-
- <Card title="Welcome" variant="elevated">
- <p>Card content</p>
- </Card>
-
- <Badge variant="success">Active</Badge>
-
- <Alert variant="warning" title="Warning">
- Please check your input
- </Alert>
- ```
-
- ### MCP Bridge Hooks
-
- ```typescript
- import {
- McpBridgeProvider,
- useMcpBridge,
- useCallTool,
- useToolInput,
- useToolOutput,
- useTheme,
- } from '@frontmcp/ui/react';
-
- function MyWidget() {
- const input = useToolInput<{ location: string }>();
- const theme = useTheme();
- const [getWeather, { data, loading }] = useCallTool('get_weather');
-
- return <Card title={`Weather for ${input?.location}`}>{loading ? 'Loading...' : data?.temperature}</Card>;
- }
-
- // Wrap your app with the provider
- function App() {
- return (
- <McpBridgeProvider>
- <MyWidget />
- </McpBridgeProvider>
- );
- }
- ```
-
- ## React Renderer
-
- ### Server-Side Rendering
-
- ```typescript
- import { ReactRenderer, reactRenderer } from '@frontmcp/ui/renderers';
-
- // Render React component to HTML string
- const html = await reactRenderer.render(MyComponent, context);
- ```
-
- ### MDX Server Rendering
-
- ```typescript
- import { MdxRenderer, mdxRenderer } from '@frontmcp/ui/renderers';
-
- // Render MDX to HTML with React components
- const html = await mdxRenderer.render('# Hello {output.name}', context);
- ```
-
- ### Client-Side Hydration
-
- ```typescript
- import { ReactRendererAdapter, createReactAdapter } from '@frontmcp/ui/renderers';
-
- // Create adapter for client-side rendering
- const adapter = createReactAdapter();
-
- // Hydrate existing SSR content
- await adapter.hydrate(targetElement, context);
-
- // Render new content
- await adapter.renderToDOM(content, targetElement, context);
- ```
-
- ## Universal App
-
- The universal app provides a platform-agnostic React shell:
-
- ```typescript
- import { UniversalApp, FrontMCPProvider } from '@frontmcp/ui/universal';
-
- function App() {
- return (
- <FrontMCPProvider>
- <UniversalApp>
- <MyWidget />
- </UniversalApp>
- </FrontMCPProvider>
- );
- }
- ```
-
- ## SSR Bundling
-
- The bundler re-exports utilities from `@frontmcp/uipack/bundler`:
-
- ```typescript
- import { InMemoryBundler, createBundler } from '@frontmcp/ui/bundler';
-
- // Create bundler for SSR components
- const bundler = createBundler({
- cache: true,
- });
-
- // Bundle a React component for SSR
- const result = await bundler.bundle(componentPath);
- ```
-
## Dependencies
```json
{
"peerDependencies": {
"react": "^18.0.0 || ^19.0.0",
"react-dom": "^18.0.0 || ^19.0.0",
- "@frontmcp/uipack": "^0.6.0"
+ "@mui/material": "^7.0.0",
+ "@emotion/react": "^11.0.0",
+ "@emotion/styled": "^11.0.0"
}
}
```
- ## Testing Requirements
-
- - **Coverage**: 95%+ across statements, branches, functions, lines
- - **React Testing Library**: Use for component tests
- - **SSR Tests**: Test server-side rendering output
- - **Hydration Tests**: Test client-side hydration
-
## Entry Points
- | Path | Purpose |
- | ----------------------------- | ------------------------------------------ |
- | `@frontmcp/ui` | Main exports (React components, renderers) |
- | `@frontmcp/ui/react` | React components and hooks |
- | `@frontmcp/ui/renderers` | ReactRenderer, MdxRenderer, adapters |
- | `@frontmcp/ui/render` | React 19 static rendering |
- | `@frontmcp/ui/universal` | Universal app shell |
- | `@frontmcp/ui/bundler` | SSR component bundler |
- | `@frontmcp/ui/bridge` | MCP bridge runtime |
- | `@frontmcp/ui/components` | HTML string components |
- | `@frontmcp/ui/layouts` | Page layout templates |
- | `@frontmcp/ui/web-components` | Custom HTML elements |
-
- ## Anti-Patterns to Avoid
-
- - Importing React-free utilities from `@frontmcp/ui` (use `@frontmcp/uipack`)
- - Using `any` type without justification
- - Skipping SSR/hydration testing
- - Missing TypeScript types for props
- - Not handling loading/error states in hooks
+ | Path | Purpose |
+ | --------------------------- | -------------------------------------- |
+ | `@frontmcp/ui` | Main exports (bridge, hooks) |
+ | `@frontmcp/ui/theme` | MUI theme provider and config |
+ | `@frontmcp/ui/components` | MUI-based React components |
+ | `@frontmcp/ui/components/*` | Individual components (tree-shakeable) |
+ | `@frontmcp/ui/renderer` | Content renderers (auto-detect) |
+ | `@frontmcp/ui/renderer/*` | Individual renderers |
+ | `@frontmcp/ui/react` | MCP bridge hooks |
+ | `@frontmcp/ui/bridge` | MCP bridge adapters |
+ | `@frontmcp/ui/runtime` | Content detection, Babel runtime |
## Related Packages
- - **@frontmcp/uipack** - React-free bundling, build tools, theme, platform adapters
+ - **@frontmcp/uipack** - Server-side template processor (pure TS, no Node.js)
- **@frontmcp/sdk** - Core FrontMCP SDK
- - **@frontmcp/testing** - E2E testing utilities