# UIBlocks instructions for coding assistants

UIBlocks is a public React design library. Its catalog website uses TanStack Start and TanStack Router. All current distributed blocks are framework-independent React + Tailwind CSS 4.

## Connect once

Endpoint: https://uiblocks.org/mcp (Streamable HTTP). It is public and read-only; no API key is needed.

Codex: `codex mcp add uiblocks --url https://uiblocks.org/mcp`, then `codex mcp list`.
Cursor: merge `{ "mcpServers": { "uiblocks": { "url": "https://uiblocks.org/mcp" } } }` into the consumer project's .cursor/mcp.json.
Claude Code: `claude mcp add --transport http --scope project uiblocks https://uiblocks.org/mcp`.

Refresh the client's tool connections or start a new chat when required. The assistant can call only tools enabled by its client. Connecting the library does not change unrelated chats.

## Choose, inspect, install, verify

1. Identify the page goal, real content, host framework, and required states.
2. Start with list_recipes and get_recipe when a complete page fits. Use search_blocks with English/Chinese keywords or a full page goal such as 视频压缩工具 or a landing page with pricing and login. It ranks blocks and matching recipes while honoring category/pageType/featured filters; inspect queryInfo, match reasons, and suggestions.
3. Call get_preview on any recipe or block candidate. All 93 blocks and two recipes have actual PNG image content for vision-capable models, with capture provenance. Read capture.state and viewport: some images show an opened dialog or menu. Use the live preview to inspect additional states and responsive behavior.
4. Read get_block for content boundaries, recommended neighbors, source author/revision, pinned dependencies, installed entry, and export name. source=entry returns entry code; source=all returns the bundled source; source=none returns metadata.
5. Keep one clean-saas design language. Preserve the selected recipe's content width, typography, section spacing, borders, and violet accent. Customize props and content before rewriting structure.
6. Merge @uiblocks into the existing components.json registries without overwriting aliases or other registries. Execute the returned shadcn CLI commands only in the user's authorized consuming project. The remote MCP server itself never writes local files.
7. A recipe is an installable complete page component. Execute its single installCommand, import its meta.entry/exportName using the consumer components alias, and follow install.usage and propsContract. Its selected blocks/helpers and MIT notices are bundled. get_recipe source=all returns the complete bundle; source=none returns metadata. Workspace controlled mode is the safe default; mode="demo" explicitly enables local simulation. Connect real upload/result controls and processing callbacks to the host service.
8. The blocks have no Next.js or TanStack router dependency. Adapt anchor destinations or onNavigate callbacks for the host. Keep MIT notices and source modification records.
9. Verify desktop and mobile, real English/Chinese copy, long filenames, loading, empty, error, and completed states. Inspect rendered results before calling the UI finished.
10. Frame branding, demo prices, usage, and downloads are illustrative. The workspace does not upload or convert video, bill users, or run a model service.

## Without MCP

Read https://uiblocks.org/llms.txt and https://uiblocks.org/catalog.json with HTTP tools. Fetch a recipe JSON, its actual preview, and the selected /r/{id}.json source bundles. Every block and recipe has a screenshot URL and capture metadata; https://uiblocks.org/previews/manifest.json records all 95 exact images, captured states, source dependencies, viewport/dimensions, and image hashes. Use the same installation and verification rules. The standard registry remains compatible with the official shadcn MCP.