# Registry, MCP & AI (/docs/registry)



UploadCN is a standard [shadcn registry](https://ui.shadcn.com/docs/registry). Everything
that works with other registries, the CLI, search, the MCP server, `--diff`, works here.

## Namespace [#namespace]

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npx shadcn@latest registry add @uploadcn=https://uploadcn.dev/r/{style}/{name}.json
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm dlx shadcn@latest registry add @uploadcn=https://uploadcn.dev/r/{style}/{name}.json
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn dlx shadcn@latest registry add @uploadcn=https://uploadcn.dev/r/{style}/{name}.json
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun x shadcn@latest registry add @uploadcn=https://uploadcn.dev/r/{style}/{name}.json
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Then install by name:

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npx shadcn@latest add @uploadcn/file-upload @uploadcn/upload-config
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm dlx shadcn@latest add @uploadcn/file-upload @uploadcn/upload-config
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn dlx shadcn@latest add @uploadcn/file-upload @uploadcn/upload-config
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun x shadcn@latest add @uploadcn/file-upload @uploadcn/upload-config
    ```
  </CodeBlockTab>
</CodeBlockTabs>

| URL                      | What it serves                                          |
| ------------------------ | ------------------------------------------------------- |
| `/r/registry.json`       | The index of every item (used by search and MCP)        |
| `/r/{name}.json`         | An item, compiled for the default style (Nova)          |
| `/r/{style}/{name}.json` | An item for your style, e.g. `/r/base-lyra/upload.json` |

## Browse from the CLI [#browse-from-the-cli]

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npx shadcn@latest search @uploadcn --query image
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm dlx shadcn@latest search @uploadcn --query image
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn dlx shadcn@latest search @uploadcn --query image
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun x shadcn@latest search @uploadcn --query image
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npx shadcn@latest view @uploadcn/product-media-upload
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm dlx shadcn@latest view @uploadcn/product-media-upload
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn dlx shadcn@latest view @uploadcn/product-media-upload
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun x shadcn@latest view @uploadcn/product-media-upload
    ```
  </CodeBlockTab>
</CodeBlockTabs>

`view` prints the files an item will add before you install it. After an update,
`npx shadcn@latest add @uploadcn/upload --diff` shows what changed against your copy.

## MCP server [#mcp-server]

The [shadcn MCP server](https://ui.shadcn.com/docs/mcp) reads UploadCN's registry index,
so your assistant can find, explain and install components.

<Steps>
  <Step>
    ### Add the namespace [#add-the-namespace]

    Run the `registry add` command above so `@uploadcn` is in `components.json`.
  </Step>

  <Step>
    ### Install the MCP server [#install-the-mcp-server]

    <Tabs items="[&#x22;Claude Code&#x22;, &#x22;Cursor&#x22;, &#x22;VS Code&#x22;]">
      <Tab value="Claude Code">
        <CodeBlockTabs defaultValue="npm">
          <CodeBlockTabsList>
            <CodeBlockTabsTrigger value="npm">
              npm
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="pnpm">
              pnpm
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="yarn">
              yarn
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="bun">
              bun
            </CodeBlockTabsTrigger>
          </CodeBlockTabsList>

          <CodeBlockTab value="npm">
            ```bash
            npx shadcn@latest mcp init --client claude
            ```
          </CodeBlockTab>

          <CodeBlockTab value="pnpm">
            ```bash
            pnpm dlx shadcn@latest mcp init --client claude
            ```
          </CodeBlockTab>

          <CodeBlockTab value="yarn">
            ```bash
            yarn dlx shadcn@latest mcp init --client claude
            ```
          </CodeBlockTab>

          <CodeBlockTab value="bun">
            ```bash
            bun x shadcn@latest mcp init --client claude
            ```
          </CodeBlockTab>
        </CodeBlockTabs>
      </Tab>

      <Tab value="Cursor">
        <CodeBlockTabs defaultValue="npm">
          <CodeBlockTabsList>
            <CodeBlockTabsTrigger value="npm">
              npm
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="pnpm">
              pnpm
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="yarn">
              yarn
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="bun">
              bun
            </CodeBlockTabsTrigger>
          </CodeBlockTabsList>

          <CodeBlockTab value="npm">
            ```bash
            npx shadcn@latest mcp init --client cursor
            ```
          </CodeBlockTab>

          <CodeBlockTab value="pnpm">
            ```bash
            pnpm dlx shadcn@latest mcp init --client cursor
            ```
          </CodeBlockTab>

          <CodeBlockTab value="yarn">
            ```bash
            yarn dlx shadcn@latest mcp init --client cursor
            ```
          </CodeBlockTab>

          <CodeBlockTab value="bun">
            ```bash
            bun x shadcn@latest mcp init --client cursor
            ```
          </CodeBlockTab>
        </CodeBlockTabs>
      </Tab>

      <Tab value="VS Code">
        <CodeBlockTabs defaultValue="npm">
          <CodeBlockTabsList>
            <CodeBlockTabsTrigger value="npm">
              npm
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="pnpm">
              pnpm
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="yarn">
              yarn
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="bun">
              bun
            </CodeBlockTabsTrigger>
          </CodeBlockTabsList>

          <CodeBlockTab value="npm">
            ```bash
            npx shadcn@latest mcp init --client vscode
            ```
          </CodeBlockTab>

          <CodeBlockTab value="pnpm">
            ```bash
            pnpm dlx shadcn@latest mcp init --client vscode
            ```
          </CodeBlockTab>

          <CodeBlockTab value="yarn">
            ```bash
            yarn dlx shadcn@latest mcp init --client vscode
            ```
          </CodeBlockTab>

          <CodeBlockTab value="bun">
            ```bash
            bun x shadcn@latest mcp init --client vscode
            ```
          </CodeBlockTab>
        </CodeBlockTabs>
      </Tab>
    </Tabs>
  </Step>

  <Step>
    ### Ask [#ask]

    * “Show me the components in the @uploadcn registry”
    * “Add an image upload with crop from @uploadcn”
    * “Build a KYC page with @uploadcn/identity-verification that uploads to Cloudinary”
  </Step>
</Steps>

## llms.txt [#llmstxt]

Agents that don't use MCP can read [`/llms.txt`](/llms.txt): what UploadCN is, how to set
up the registry, every component with its install command, and the docs index.
[`/llms-full.txt`](/llms-full.txt) has the full documentation in one file, and every docs
page is available as Markdown from the **Copy Markdown** button.

## Quality bar [#quality-bar]

Every item in the registry:

* passes `shadcn registry validate` and the registry-directory rules (flat structure, no
  inline content in `registry.json`);
* declares exactly the npm packages and registry items it imports;
* is compiled for all 8 styles with no style classes left over;
* passes `@shadcn/lint` theme checks;
* renders, uploads and passes an accessibility scan in automated tests;
* installs and type-checks in fresh Radix, Base UI and React Aria projects.

## shadcn registry directory [#shadcn-registry-directory]

To list UploadCN in the [registry directory](https://ui.shadcn.com/docs/directory), add
this entry to `apps/v4/registry/directory.json` in
[shadcn-ui/ui](https://github.com/shadcn-ui/ui), run `pnpm validate:registries`, and open
a pull request:

```json title="apps/v4/registry/directory.json"
{
  "name": "@uploadcn",
  "homepage": "https://uploadcn.dev",
  "url": "https://uploadcn.dev/r/{style}/{name}.json",
  "description": "Production-ready file uploads: dropzones, queues, resumable S3 and R2 uploads, and 58 blocks for every style.",
  "author": "Hanzala",
  "logo": "<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'><rect width='24' height='24' rx='6.5' fill='var(--foreground)'/><g fill='none' stroke='var(--background)' stroke-width='2.4' stroke-linecap='round' stroke-linejoin='round' transform='translate(-0.75 0)'><path d='M7 9v4a5 5 0 0 0 10 0V6'/><path d='m14 9 3-3 3 3'/></g></svg>"
}
```