Delivery / Docs

Install & integrate

Production pack commands, repo-local MCP wiring, and pinned install paths for getting an Infara app running.

Pinned releasesBootstrap-generated MCPRepo-local contract

MCP setup

Use this exact order in the consumer app.

1. Initialize shadcn

Run this first so the app has a shadcn config and components.json.

bashterminal

npx shadcn@latest init

2. Add the Infara registry to components.json

Use the pinned production release.

jsoncomponents.json

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "",
    "css": "src/app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true,
    "prefix": ""
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks",
    "blocks": "@/components/blocks"
  },
  "registries": {
    "@infara": "https://ui.infara.ai/r/releases/0.1.0/{name}.json"
  }
}

3. Install the Infara theme and registry items

These commands work after components.json knows about @infara.

bashterminal

npx shadcn@latest add @infara/infara-theme
npx shadcn@latest add @infara/button
npx shadcn@latest add @infara/data-table
npx shadcn@latest add @infara/sidebar-layout

4. Import the theme CSS

Make sure the app actually loads the installed theme.

csssrc/app/globals.css

@import "../themes/infara-theme.css";

5. Claude Code

Create this in the repo root.

json.mcp.json

{
  "mcpServers": {
    "shadcn": {
      "command": "npx",
      "args": ["shadcn@latest", "mcp"]
    }
  }
}

6. Codex

Add the shadcn MCP server to the global Codex config.

toml~/.codex/config.toml

[mcp_servers.shadcn]
command = "npx"
args = ["shadcn@latest", "mcp"]

7. Verification

Use a direct MCP prompt after the client restarts.

textverification

Verify the shadcn MCP server can see the @infara registry, then pull DESIGN.md, infara-theme.css, and colors_and_type.css from infara-context before installing @infara/infara-theme and @infara/button.

Full Infara .mcp.json on Windows

Use this when the consumer repo also needs infara-context and next-devtools.

json.mcp.json (Windows)

{
  "mcpServers": {
    "shadcn": {
      "command": "cmd",
      "args": ["/c", "npx", "shadcn@latest", "mcp"]
    },
    "infara-context": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@infara/infara-mcp-server@0.1.0"],
      "env": {
        "INFARA_CONTEXT_DIR": ".infara/context",
        "INFARA_REGISTRY_ORIGIN": "https://ui.infara.ai",
        "INFARA_REGISTRY_RELEASE": "0.1.0"
      }
    },
    "next-devtools": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "next-devtools-mcp@0.3.10"]
    }
  }
}

Full Infara .mcp.json on macOS, Linux, or WSL

POSIX-style version of the same full project MCP stack.

json.mcp.json (POSIX)

{
  "mcpServers": {
    "shadcn": {
      "command": "npx",
      "args": ["shadcn@latest", "mcp"]
    },
    "infara-context": {
      "command": "npx",
      "args": ["-y", "@infara/infara-mcp-server@0.1.0"],
      "env": {
        "INFARA_CONTEXT_DIR": ".infara/context",
        "INFARA_REGISTRY_ORIGIN": "https://ui.infara.ai",
        "INFARA_REGISTRY_RELEASE": "0.1.0"
      }
    },
    "next-devtools": {
      "command": "npx",
      "args": ["-y", "next-devtools-mcp@0.3.10"]
    }
  }
}

Repair before fallback

Do not jump straight to raw URLs. Spend five explicit attempts repairing the MCP path first.

Repair sequence

Work through these in order before considering any fallback.

Check components.json and confirm @infara still points at the pinned release URL pattern.
Check the active client config: .mcp.json for project MCP and ~/.codex/config.toml for Codex shadcn.
Restart the client and confirm shadcn reports connected.
Run npx clear-npx-cache, reload the shadcn server, and retry.
Confirm the registry endpoints are reachable and retry with explicit @infara/... item names.

Fallback after five failures

If every repair attempt failed, the fallback is still deterministic.

Read the bundled files directly from .infara/context, including DESIGN.md and infara-theme.css plus colors_and_type.css.
Install from https://ui.infara.ai/r/releases/<version>/{name}.json.
Record which repair attempt failed so the connection issue can be fixed for real.

Start here

Cross-platform bootstrap

Use @infara/create-infara on macOS, Linux, or Windows to scaffold a pinned Infara consumer repo, then verify MCP before you ask an agent to build UI.

Bootstrap command

Use the latest stable Node.js release, then scaffold against the pinned Infara release on ui.infara.ai.

bash

npx @infara/create-infara@latest my-app
cd my-app && npm run dev

For same-machine testing against the local preview server, swap the registry origin and pin the release explicitly.

bash

npx @infara/create-infara@latest my-app --registry-origin http://localhost:3000 --release <version>
cd my-app && npm run dev

Run it

The CLI bootstraps the repo, runs the initial shadcn setup, installs the default Infara starter set, writes MCP and Infara context files, and runs the production build check unless you pass --skip-build.

Run @infara/create-infara in an empty target folder or give it a new folder name.
Wait for bootstrap to finish the production build check.
Start the app with npm run dev.
Open the generated repo and verify MCP before asking an agent to build UI.

Verify the generated repo

If these files and checks are present, the bootstrap installed correctly and the repo is ready for MCP-first work.

Required output

components.json with @infara pointing at the pinned /r/releases/<version>/{name}.json pattern.
.mcp.json with shadcn, infara-context, and next-devtools.
.infara/context with the bundled Infara contract files, including DESIGN.md and infara-theme.css plus colors_and_type.css.
src/components/blocks/sidebar.tsx and src/components/ui/data-table.tsx from the default starter install set.
src/app and public/assets synced by create-infara.
The bootstrap completed the production build check without errors unless you explicitly used --skip-build.

Re-run checks later

The bootstrap already runs the production build once by default. Re-run these if you change the generated repo.

bash

npm run build
npm run dev

Pinned install path

Production installs pin to /r/releases/<version>/{name}.json on https://ui.infara.ai. Use /r/latest/ for QA only.

urls

https://ui.infara.ai/r/releases/<version>/infara-theme.json
https://ui.infara.ai/r/releases/<version>/button.json
https://ui.infara.ai/r/releases/<version>/data-table.json

Reference

Read these if you need detail

The docs page is the short path. These files hold the deeper contract.

create-infara README

packages/create-infara/README.md

Cross-platform bootstrap command, options, generated files, and MCP checks.

MCP contract

Docs/mcp-integration-contract.md

Pinned registry rules, MCP behavior, and downstream expectations.

Pack MCP workflow

Docs/templates/consumer-agent-pack/registry-mcp-instructions.md

Exact repair order for shadcn, infara-context, and next-devtools.

UI design spec

Docs/ui-design-spec.md

Layout, density, async, accessibility, and release-blocker rules.

First prompt after bootstrap

Make the first prompt a connection check, not a UI request.

Opening prompt checklist

Hand this to the agent before asking for product UI work.

Verify that components.json has @infara and that .mcp.json contains shadcn, infara-context, and next-devtools.
Confirm the shadcn server can see @infara, then query infara-context for DESIGN.md and infara-theme.css plus colors_and_type.css before building.
Use the pinned Infara release and existing registry items before inventing app-local patterns.

Platform note

Keep next dev and the MCP client on the same OS when you can.

Cross-OS development

create-infara works across platforms, but the cheapest setup keeps dev and MCP on one OS.

Same-OS dev plus MCP is the lowest-friction setup.
If you split Windows and WSL2, use mirrored networking so localhost resolves across the boundary.
If mirrored networking is unavailable, set INFARA_DEV_ALLOWED_ORIGINS to the host IPs Next will see.