@primeuicom/mcp 0.1.6 → 0.1.7

package/README.md

@@ -1,22 +1,94 @@
-# @primeui/mcp
+# @primeuicom/mcp
 
-PrimeUI MCP server package.
+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.
 
-## Runtime
+## Purpose and goals
 
-The package uses Studio API v1 with bearer authentication.
+PrimeUI MCP is the integration layer between PrimeUI and MCP-compatible agents.
 
-Required env:
-- `PRIMEUI_API_KEY`
+Core goals:
 
-Optional env:
-- `PRIMEUI_API_BASE_URL`
-  - if set: MCP calls this base URL,
-  - if not set: MCP defaults to `https://app.primeui.com/`.
+- 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.
 
-The API root is normalized to `/api/v1`.
+## Requirements
 
-Example `.mcp.json`:
+- 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`).
+
+## PrimeUI API KEY
+
+- PrimeUI provides this key together with the exported project.
+- In practice, it is preconfigured in the exported project's `.mcp.json` for the `primeui` server entry.
+
+## 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"
+      }
+    }
+  }
+}
+```
+
+Optional environment variables:
+
+- `PRIMEUI_API_BASE_URL`: custom PrimeUI app base URL (default: `https://app.primeui.com/`).
+- `PRIMEUI_PROJECT_ROOT`: absolute path to the target local project root. If omitted, current working directory is used.
+
+Notes:
+
+- API root is normalized to `/api/v1`.
+- Temporary export files are written under `.primeui/temp/`.
+
+## 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:
+
+```bash
+codex mcp add primeui -- npx -y @primeuicom/mcp@latest
+```
+
+Then set `PRIMEUI_API_KEY` in the MCP server env for `primeui`.
+
+</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
 {
@@ -26,24 +98,104 @@ Example `.mcp.json`:
       "command": "npx",
       "args": ["-y", "@primeuicom/mcp@latest"],
       "env": {
-        "PRIMEUI_API_KEY": "<issued-api-key>"
+        "PRIMEUI_API_KEY": "your-primeui-api-key"
       }
     }
   }
 }
 ```
 
-## Token revocation note
+</details>
 
-API keys embed `ver` (token version). Future revocation/rotation is implemented by incrementing `project_api_access.token_version`.
+<details>
+<summary>VS Code MCP-compatible setup</summary>
 
-## Local dev
+If your setup supports VS Code MCP server registration via CLI:
 
 ```bash
-pnpm --filter @primeui/mcp dev
+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
-pnpm inspect
+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"],
+      "env": {
+        "PRIMEUI_API_KEY": "your-primeui-api-key"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+## Tools
+
+Available tools:
 
+| Tool | What it does | Input |
+| --- | --- | --- |
+| `primeui_get_project_info` | Returns project metadata and page list, including export readiness and source paths. | none |
+| `primeui_list_exports` | Lists existing exports with ID, status, and creation time. | none |
+| `primeui_create_export` | Starts a new export and returns created export info plus page snapshot. | none |
+| `primeui_download_export` | Downloads and extracts a completed export into `.primeui/temp/exports/<exportId>/`. | `id` (export ID) |
+| `primeui_clear_temp` | Clears `.primeui/temp/` and recreates baseline temp layout. | none |
+
+## Your first prompt
+
+Try this in your MCP-enabled agent:
+
+```text
+Use PrimeUI MCP to get my project info, list pages that are ready to export, then create a new export and tell me which export ID was created.
+```
+
+Next step:
+
+```text
+Download that export with PrimeUI MCP and show me the local extracted projectPath and pagePath for the /pricing page.
 ```
+
+## Runtime behavior
+
+- PrimeUI MCP uses bearer authentication with `PRIMEUI_API_KEY`.
+- If `PRIMEUI_API_BASE_URL` is not set, it uses `https://app.primeui.com/`.
+- Downloaded archives are validated as ZIP payloads before extraction.
+
+## Troubleshooting
+
+- `PRIMEUI_API_KEY is required`: add or fix `PRIMEUI_API_KEY` in MCP server env.
+- `Failed to extract zip`: verify local file permissions and retry.
+- API contract mismatch errors: your client/server versions may be out of sync; update to latest package and verify PrimeUI backend version.

package/dist/lib/fs.js

@@ -1,8 +1,6 @@
-import { execFile } from "node:child_process";
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { promisify } from "node:util";
-const execFileAsync = promisify(execFile);
+import extractZipArchive from "extract-zip";
 export async function ensureDir(dirPath) {
     await mkdir(dirPath, { recursive: true });
 }
@@ -17,11 +15,11 @@ export async function writeUtf8(filePath, content) {
 export async function extractZip(zipPath, targetDir) {
     await ensureDir(targetDir);
     try {
-        await execFileAsync("unzip", ["-o", zipPath, "-d", targetDir]);
+        await extractZipArchive(zipPath, { dir: targetDir });
     }
     catch (error) {
         const details = error instanceof Error ? error.message : String(error);
-        throw new Error(`Failed to extract zip at "${zipPath}". Ensure "unzip" is installed. ${details}`);
+        throw new Error(`Failed to extract zip at "${zipPath}". ${details}`);
     }
 }
 //# sourceMappingURL=fs.js.map

package/dist/lib/fs.js.map

@@ -1 +1 @@
-{"version":3,"file":"fs.js","sourceRoot":"","sources":["../../src/lib/fs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAC7C,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AACvD,OAAO,IAAI,MAAM,WAAW,CAAA;AAC5B,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAErC,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAA;AAEzC,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,OAAe;IAC7C,MAAM,KAAK,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;AAC3C,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,OAAe;IAC5C,MAAM,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;IACnD,MAAM,KAAK,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;AAC3C,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,QAAgB,EAAE,OAAe;IAC/D,MAAM,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAA;IACvC,MAAM,SAAS,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAA;AAC7C,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,OAAe,EAAE,SAAiB;IACjE,MAAM,SAAS,CAAC,SAAS,CAAC,CAAA;IAE1B,IAAI,CAAC;QACH,MAAM,aAAa,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC,CAAA;IAChE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QACtE,MAAM,IAAI,KAAK,CAAC,6BAA6B,OAAO,mCAAmC,OAAO,EAAE,CAAC,CAAA;IACnG,CAAC;AACH,CAAC"}
+{"version":3,"file":"fs.js","sourceRoot":"","sources":["../../src/lib/fs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AACvD,OAAO,IAAI,MAAM,WAAW,CAAA;AAC5B,OAAO,iBAAiB,MAAM,aAAa,CAAA;AAE3C,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,OAAe;IAC7C,MAAM,KAAK,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;AAC3C,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,OAAe;IAC5C,MAAM,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;IACnD,MAAM,KAAK,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;AAC3C,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,QAAgB,EAAE,OAAe;IAC/D,MAAM,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAA;IACvC,MAAM,SAAS,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAA;AAC7C,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,OAAe,EAAE,SAAiB;IACjE,MAAM,SAAS,CAAC,SAAS,CAAC,CAAA;IAE1B,IAAI,CAAC;QACH,MAAM,iBAAiB,CAAC,OAAO,EAAE,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC,CAAA;IACtD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QACtE,MAAM,IAAI,KAAK,CAAC,6BAA6B,OAAO,MAAM,OAAO,EAAE,CAAC,CAAA;IACtE,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primeuicom/mcp",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "type": "module",
   "main": "dist/service.js",
   "bin": {
@@ -20,6 +20,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.3",
+    "extract-zip": "^2.0.1",
     "zod": "^3.25.76"
   },
   "devDependencies": {