Agent Playbook

This document gives AI coding agents instructions on how to search, inspect, and install animated UI components and registries using Sora CLI.

MCP Server Connection

To connect Sora CLI’s Model Context Protocol (MCP) server:

npx @soralabs/cli mcp init

Or manually add to your assistant’s MCP configuration:

{
  "mcpServers": {
    "sora": {
      "command": "npx",
      "args": ["-y", "@soralabs/cli", "mcp"]
    }
  }
}

When the server is active, you have access to:

sora_search: Search components by name, keyword, or registry.
sora_info: Fetch detailed component manifest, dependencies, registry files, and peer requirements.
sora_add: Install components into the current workspace with optional flags (--yes, --dry-run, --cwd).
sora_list: List all available components from the active registry.

Check project environment: Verify if the project uses Next.js, Vite, Astro, or a monorepo. Sora CLI will automatically detect tsconfig paths, icon libraries, and Tailwind version (v3 or v4).
Search for components:
npx @soralabs/cli search <keyword>
Install without blocking prompts: Always pass --yes when running from an autonomous agent terminal:
npx @soralabs/cli add <component-name> --yes

Monorepo workspaces: Use --cwd <path> to target a specific package:

npx @soralabs/cli add <component-name> --cwd packages/ui --yes