# @primeuicom/mcp PrimeUI MCP connects AI agents to PrimeUI so they can discover project pages, create exports, download export artifacts, and automate PrimeUI-powered workflows directly from your coding environment. ## Purpose and goals PrimeUI MCP is the integration layer between PrimeUI and MCP-compatible agents. Core goals: - Give agents a reliable way to read PrimeUI project metadata and page inventory. - Let agents trigger and monitor PrimeUI exports. - Let agents download export bundles into a local workspace for code-level operations. - Provide a stable MCP tool contract for PrimeUI workflows. - Expose additional atomic external API tools for extended scenarios without making the primary import/export flow heavier. ## Requirements - An MCP client that supports `stdio` servers. - A working JavaScript runtime that can launch the server via `npx` or `bunx`. - A valid PrimeUI API key (`PRIMEUI_API_KEY`). - API key format: `pui_<22-char-base64url>`. ## PrimeUI API KEY - PrimeUI provides this key together with the exported project. - In linked/exported projects, the key is stored in `.primeui/project.json` under `apiKey`. - PrimeUI MCP loads `PRIMEUI_API_KEY` from env first, then falls back to `.primeui/project.json`. - `.primeui/project.json` must include: - `projectId` - `apiKey` - `targetProjectPath` for file-oriented import/export flows (relative path such as `"./"` or `"./apps/web"`) Notes: - The additional atomic external API tools can work without `targetProjectPath`. - The primary file-oriented import/export tools still require `targetProjectPath`. ## Your first prompts Try this in your MCP-enabled agent: ```text Use PrimeUI MCP to get my project info, list pages that are ready to export. Compare them with my current pages ``` Next step: ```text Export [X page | XX pages] from PrimeUI and add them to my project. ``` Targeted page inspection: ```text Inspect PrimeUI page /pricing components and compare them with my local /pricing page. ``` Targeted block-level transfer: ```text Inspect PrimeUI page /pricing, then copy the block with blockId pricing-hero-2 and componentId hero--split into my project. ``` ## Tools PrimeUI MCP has two tool groups: 1. Primary import/export flow tools. These are the default tools for page-by-page imports into a local codebase. 2. Additional atomic external API tools. These are optional endpoint-aligned capabilities for extended scenarios and do not replace the primary flow. ### Primary import/export flow tools | Tool | What it does | Input | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | `get_project_info` | Returns project metadata and page list, including export readiness and source paths. | `projectRoot?` | | `inspect_page` | Returns details for one page by slug, raw active-variant components (or `null`), and a formatted component report table for local comparison. | `pageSlug`, `projectRoot?` | | `list_exports` | Lists existing exports with ID, status, and creation time. | `projectRoot?` | | `create_export` | Starts a new export and returns strict API manifest payload (`pages[].manifest.files` + `export.exportables`), then saves sidecar manifest `.primeui/temp/exports/.manifest.json`. | `projectRoot?` | | `download_export` | Downloads and extracts a completed export into `.primeui/temp/exports//` and validates existing local sidecar manifest for this export ID. | `id` (export ID), `projectRoot?` | | `copy_page` | Safely copies one page from downloaded export into user project using only `pages[].manifest.files` (compact file lists + lightweight conflicts; full diffs saved to local copy report file). | `originPageSlug`, `projectRoot?` | | `copy_component` | Safely copies one canonical component file for a selected block instance, adds missing package dependencies, returns exact block props plus `occurrenceIndex` / `contentKey`, and reports page-level follow-up files only as hints. | `originPageSlug`, `blockId`, `componentId`, `projectRoot?` | | `copy_exportable` | Safely copies one shared exportable from downloaded export into user project using only `export.exportables[].manifest.files`, returns `not_available` for disabled exportables, and reports `missedDependencies` instead of copying `package.json`. | `exportableKey`, `projectRoot?` | | `clear_temp` | Clears `.primeui/temp/` and recreates baseline temp layout. | `projectRoot?` | ### Additional atomic external API tools These tools map one-to-one to newer external API endpoints. They are independent operations for advanced or secondary scenarios. They must not be treated as a required chain and they do not replace the standard import/export workflow. | Tool | What it does | Input | | -------------------------------- | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | | `project_description_get` | Returns the current shared project description. | `projectRoot?` | | `project_description_upsert` | Creates, updates, or clears the shared project description. | `projectDescription`, `projectRoot?` | | `project_pages_list` | Returns the current page inventory with lightweight variant summaries. | `projectRoot?` | | `project_page_get` | Returns one page by `pageId` using the same page envelope as the list endpoint. | `pageId`, `projectRoot?` | | `project_page_create` | Creates a new page and its initial variant. | `slug`, `title`, `pageType`, `contentMode`, `componentIds?`, `prompt?`, `projectRoot?` | | `project_page_variants_list` | Returns lightweight variant summaries for one page. | `pageId`, `projectRoot?` | | `project_page_variant_get` | Returns one variant with its component payload. | `pageId`, `variantId`, `projectRoot?` | | `project_page_variant_create` | Creates one new variant for an existing page. | `pageId`, `name?`, `contentMode`, `componentIds?`, `prompt?`, `projectRoot?` | | `project_page_active_variant_set`| Sets the export-selected active variant for one page. | `pageId`, `variantId`, `projectRoot?` | | `project_issue_report_submit` | Submits an issue report for the scoped project. | `reportText`, `tags?`, `projectRoot?` | ## Getting started The setup below works in any MCP client that supports `.mcp.json` with `stdio` command servers (for example: Codex CLI, Cursor, Cline, and other compatible clients). Create or update `.mcp.json`: ```json { "mcpServers": { "primeui": { "type": "stdio", "command": "npx", "args": ["-y", "@primeuicom/mcp@latest"], "env": { "PRIMEUI_API_KEY": "your-primeui-api-key" } } } } ``` Verified `bunx` CLI alternative for direct invocation: ```bash bunx --package @primeuicom/mcp@latest primeui-mcp --version bunx --package @primeuicom/mcp@latest primeui-mcp --health ``` Notes: - Use the explicit binary form with `--package ... primeui-mcp`. ## Install in common MCP clients If your CLI command syntax differs by client version, use the JSON config from Getting started with the same `primeui` server block.
Codex CLI Use the Codex MCP add command to install MCP globally: ```bash codex mcp add primeui -- npx -y @primeuicom/mcp@latest ```
Claude Code Add the server: ```bash claude mcp add primeui -- npx -y @primeuicom/mcp@latest ``` Then configure server environment variables (at minimum `PRIMEUI_API_KEY`).
Cursor Add the same server config to your Cursor MCP configuration: ```json { "mcpServers": { "primeui": { "type": "stdio", "command": "npx", "args": ["-y", "@primeuicom/mcp@latest"], "env": { "PRIMEUI_API_KEY": "your-primeui-api-key" } } } } ```
VS Code MCP-compatible setup If your setup supports VS Code MCP server registration via CLI: ```bash code --add-mcp '{"name":"primeui","command":"npx","args":["-y","@primeuicom/mcp@latest"],"env":{"PRIMEUI_API_KEY":"your-primeui-api-key"}}' ``` If your setup uses JSON config instead, use the same `.mcp.json` example from Getting started.
Cline / other JSON-config clients Use the same `.mcp.json` server block from Getting started and provide `PRIMEUI_API_KEY`.
Gemini CLI Add PrimeUI MCP: ```bash gemini mcp add primeui npx -y @primeuicom/mcp@latest ``` Then configure `PRIMEUI_API_KEY` for that server entry.
Windsurf Use the same JSON server configuration shown in Getting started: ```json { "mcpServers": { "primeui": { "type": "stdio", "command": "npx", "args": ["-y", "@primeuicom/mcp@latest"] } } } ```
## Runtime behavior - PrimeUI MCP uses bearer authentication with `PRIMEUI_API_KEY`. - `--help`, `--version`, and `--health` do not start the MCP server. - If `PRIMEUI_API_KEY` env is missing, PrimeUI MCP reads `.primeui/project.json` (`apiKey`). - Server startup does not require `.primeui/project.json`; project config is resolved lazily per tool call. - Config lookup order on each tool call: - `projectRoot` tool input (if provided), - sticky in-process root resolved by prior successful tool call, - `PRIMEUI_PROJECT_ROOT` env, - upward search for `.primeui/project.json` from current working directory. - If config cannot be resolved, the tool returns a transparent error with actionable hint to pass `projectRoot`. - `clear_temp`, `copy_page`, `copy_component`, and `copy_exportable` always validate project config before running any mutation. - The additional atomic external API tools use the same project config and API key resolution, but they do not depend on `.primeui/temp/`, the export manifest flow, or `targetProjectPath` validation. - The file-oriented import/export tools still require a valid `targetProjectPath` because they operate on the linked local target project. - Missing or invalid `targetProjectPath` is treated as a configuration error. - Downloaded archives are validated as ZIP payloads before extraction. - `create_export` is the source of truth for local sidecar manifest creation in `.primeui/temp/exports/.manifest.json`. - Temporary export files are written under `.primeui/temp/` in user project folder. ## CLI behavior PrimeUI MCP has three execution modes: - `npx @primeuicom/mcp@latest` starts the MCP `stdio` server for use by an MCP-compatible client. - `npx @primeuicom/mcp@latest --help` prints CLI help and exits. - `npx @primeuicom/mcp@latest --version` prints the package version and exits. - `npx @primeuicom/mcp@latest --health` prints runtime diagnostics and exits. - `npx @primeuicom/mcp@latest --health /absolute/project/path` runs the same diagnostics against an explicit project root. Examples: ```bash npx @primeuicom/mcp@latest --help npx @primeuicom/mcp@latest --version npx @primeuicom/mcp@latest --health npx @primeuicom/mcp@latest --health /absolute/project/path ``` Normal MCP client configuration should launch `@primeuicom/mcp` without `--help`, `--version`, or `--health`. ## Local development and testing Configure these environment variables for local development: - `PRIMEUI_API_BASE_URL`: PrimeUI API base URL (for example `http://localhost:3020` when testing against local Studio API). - `PRIMEUI_PROJECT_ROOT`: explicit project root override for `.primeui/project.json` and `.primeui/temp/` location. **tip** to add it to codex globally use: ```console codex mcp add primeui --env PRIMEUI_API_BASE_URL=http://localhost:3020 -- npx -y @primeuicom/mcp@latest ``` Run MCP Inspector: ```bash pnpm inspect ``` This runs `@modelcontextprotocol/inspector` against `tsx src/service.ts`. After startup, open the local Inspector URL shown in the terminal (for example `http://127.0.0.1:`) and interact with the PrimeUI MCP tools from the browser UI. Main scripts: - `pnpm dev`: run the MCP server locally via `tsx src/service.ts`. - `pnpm test`: run unit tests with Vitest. - `pnpm typecheck`: run TypeScript type checks without emitting build artifacts. - `pnpm build`: clean `dist/`, bundle the MCP server with `tsup`, and mark `dist/service.js` executable. - `pnpm prepack`: run build before packaging/publishing. ### Publish Publish flow includes: 1. Update the package version (usually a patch bump). 2. Publish with the `latest` tag: ```bash npm publish --tag latest ``` ## Credits PrimeUI 2026