npm package: @primeuicom/mcp
Description: MCP server that connects AI agents with PrimeUI project
Author: Oleg
Latest version: 1.0.0

# @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.

## Requirements

- An MCP client that supports `stdio` servers.
- A working Node.js runtime (the server is launched via `npx`).
- 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` (required, relative path such as `"./"` or `"./apps/web"`)

## 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.
```

## Tools

Available 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/<exportId>.manifest.json`. | `projectRoot?`                                      |
| `download_export`  | Downloads and extracts a completed export into `.primeui/temp/exports/<exportId>/` 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?`                    |
| `clear_temp`       | Clears `.primeui/temp/` and recreates baseline temp layout.                                                                                                                                 | `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"
      }
    }
  }
}
```

## 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.

<details>
<summary>Codex CLI</summary>

Use the Codex MCP add command to install MCP globally:

```bash
codex mcp add primeui -- npx -y @primeuicom/mcp@latest
```

</details>

<details>
<summary>Claude Code</summary>

Add the server:

```bash
claude mcp add primeui -- npx -y @primeuicom/mcp@latest
```

Then configure server environment variables (at minimum `PRIMEUI_API_KEY`).

</details>

<details>
<summary>Cursor</summary>

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"
      }
    }
  }
}
```

</details>

<details>
<summary>VS Code MCP-compatible setup</summary>

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.

</details>

<details>
<summary>Cline / other JSON-config clients</summary>

Use the same `.mcp.json` server block from Getting started and provide `PRIMEUI_API_KEY`.

</details>

<details>
<summary>Gemini CLI</summary>

Add PrimeUI MCP:

```bash
gemini mcp add primeui npx -y @primeuicom/mcp@latest
```

Then configure `PRIMEUI_API_KEY` for that server entry.

</details>

<details>
<summary>Windsurf</summary>

Use the same JSON server configuration shown in Getting started:

```json
{
  "mcpServers": {
    "primeui": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@primeuicom/mcp@latest"]
    }
  }
}
```

</details>

## 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` and `copy_page` always validate project config before running any mutation.
- 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/<exportId>.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:<port>`) 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