@primeuicom/mcp 1.0.0 → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +63 -14
- package/dist/service.js +2632 -490
- package/dist/service.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -12,11 +12,12 @@ Core goals:
|
|
|
12
12
|
- Let agents trigger and monitor PrimeUI exports.
|
|
13
13
|
- Let agents download export bundles into a local workspace for code-level operations.
|
|
14
14
|
- Provide a stable MCP tool contract for PrimeUI workflows.
|
|
15
|
+
- Expose additional atomic external API tools for extended scenarios without making the primary import/export flow heavier.
|
|
15
16
|
|
|
16
17
|
## Requirements
|
|
17
18
|
|
|
18
19
|
- An MCP client that supports `stdio` servers.
|
|
19
|
-
- A working
|
|
20
|
+
- A working JavaScript runtime that can launch the server via `npx` or `bunx`.
|
|
20
21
|
- A valid PrimeUI API key (`PRIMEUI_API_KEY`).
|
|
21
22
|
- API key format: `pui_<22-char-base64url>`.
|
|
22
23
|
|
|
@@ -28,7 +29,12 @@ Core goals:
|
|
|
28
29
|
- `.primeui/project.json` must include:
|
|
29
30
|
- `projectId`
|
|
30
31
|
- `apiKey`
|
|
31
|
-
- `targetProjectPath` (
|
|
32
|
+
- `targetProjectPath` for file-oriented import/export flows (relative path such as `"./"` or `"./apps/web"`)
|
|
33
|
+
|
|
34
|
+
Notes:
|
|
35
|
+
|
|
36
|
+
- The additional atomic external API tools can work without `targetProjectPath`.
|
|
37
|
+
- The primary file-oriented import/export tools still require `targetProjectPath`.
|
|
32
38
|
|
|
33
39
|
## Your first prompts
|
|
34
40
|
|
|
@@ -50,19 +56,49 @@ Targeted page inspection:
|
|
|
50
56
|
Inspect PrimeUI page /pricing components and compare them with my local /pricing page.
|
|
51
57
|
```
|
|
52
58
|
|
|
53
|
-
|
|
59
|
+
Targeted block-level transfer:
|
|
54
60
|
|
|
55
|
-
|
|
61
|
+
```text
|
|
62
|
+
Inspect PrimeUI page /pricing, then copy the block with blockId pricing-hero-2 and componentId hero--split into my project.
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## Tools
|
|
56
66
|
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
|
65
|
-
|
|
|
67
|
+
PrimeUI MCP has two tool groups:
|
|
68
|
+
|
|
69
|
+
1. Primary import/export flow tools. These are the default tools for page-by-page imports into a local codebase.
|
|
70
|
+
2. Additional atomic external API tools. These are optional endpoint-aligned capabilities for extended scenarios and do not replace the primary flow.
|
|
71
|
+
|
|
72
|
+
### Primary import/export flow tools
|
|
73
|
+
|
|
74
|
+
| Tool | What it does | Input |
|
|
75
|
+
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
|
|
76
|
+
| `get_project_info` | Returns project metadata and page list, including export readiness and source paths. | `projectRoot?` |
|
|
77
|
+
| `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?` |
|
|
78
|
+
| `list_exports` | Lists existing exports with ID, status, and creation time. | `projectRoot?` |
|
|
79
|
+
| `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?` |
|
|
80
|
+
| `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?` |
|
|
81
|
+
| `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?` |
|
|
82
|
+
| `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?` |
|
|
83
|
+
| `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?` |
|
|
84
|
+
| `clear_temp` | Clears `.primeui/temp/` and recreates baseline temp layout. | `projectRoot?` |
|
|
85
|
+
|
|
86
|
+
### Additional atomic external API tools
|
|
87
|
+
|
|
88
|
+
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.
|
|
89
|
+
|
|
90
|
+
| Tool | What it does | Input |
|
|
91
|
+
| -------------------------------- | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
|
|
92
|
+
| `project_description_get` | Returns the current shared project description. | `projectRoot?` |
|
|
93
|
+
| `project_description_upsert` | Creates, updates, or clears the shared project description. | `projectDescription`, `projectRoot?` |
|
|
94
|
+
| `project_pages_list` | Returns the current page inventory with lightweight variant summaries. | `projectRoot?` |
|
|
95
|
+
| `project_page_get` | Returns one page by `pageId` using the same page envelope as the list endpoint. | `pageId`, `projectRoot?` |
|
|
96
|
+
| `project_page_create` | Creates a new page and its initial variant. | `slug`, `title`, `pageType`, `contentMode`, `componentIds?`, `prompt?`, `projectRoot?` |
|
|
97
|
+
| `project_page_variants_list` | Returns lightweight variant summaries for one page. | `pageId`, `projectRoot?` |
|
|
98
|
+
| `project_page_variant_get` | Returns one variant with its component payload. | `pageId`, `variantId`, `projectRoot?` |
|
|
99
|
+
| `project_page_variant_create` | Creates one new variant for an existing page. | `pageId`, `name?`, `contentMode`, `componentIds?`, `prompt?`, `projectRoot?` |
|
|
100
|
+
| `project_page_active_variant_set`| Sets the export-selected active variant for one page. | `pageId`, `variantId`, `projectRoot?` |
|
|
101
|
+
| `project_issue_report_submit` | Submits an issue report for the scoped project. | `reportText`, `tags?`, `projectRoot?` |
|
|
66
102
|
|
|
67
103
|
## Getting started
|
|
68
104
|
|
|
@@ -85,6 +121,17 @@ Create or update `.mcp.json`:
|
|
|
85
121
|
}
|
|
86
122
|
```
|
|
87
123
|
|
|
124
|
+
Verified `bunx` CLI alternative for direct invocation:
|
|
125
|
+
|
|
126
|
+
```bash
|
|
127
|
+
bunx --package @primeuicom/mcp@latest primeui-mcp --version
|
|
128
|
+
bunx --package @primeuicom/mcp@latest primeui-mcp --health
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
Notes:
|
|
132
|
+
|
|
133
|
+
- Use the explicit binary form with `--package ... primeui-mcp`.
|
|
134
|
+
|
|
88
135
|
## Install in common MCP clients
|
|
89
136
|
|
|
90
137
|
If your CLI command syntax differs by client version, use the JSON config from Getting started with the same `primeui` server block.
|
|
@@ -199,7 +246,9 @@ Use the same JSON server configuration shown in Getting started:
|
|
|
199
246
|
- `PRIMEUI_PROJECT_ROOT` env,
|
|
200
247
|
- upward search for `.primeui/project.json` from current working directory.
|
|
201
248
|
- If config cannot be resolved, the tool returns a transparent error with actionable hint to pass `projectRoot`.
|
|
202
|
-
- `clear_temp` and `
|
|
249
|
+
- `clear_temp`, `copy_page`, `copy_component`, and `copy_exportable` always validate project config before running any mutation.
|
|
250
|
+
- 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.
|
|
251
|
+
- The file-oriented import/export tools still require a valid `targetProjectPath` because they operate on the linked local target project.
|
|
203
252
|
- Missing or invalid `targetProjectPath` is treated as a configuration error.
|
|
204
253
|
- Downloaded archives are validated as ZIP payloads before extraction.
|
|
205
254
|
- `create_export` is the source of truth for local sidecar manifest creation in `.primeui/temp/exports/<exportId>.manifest.json`.
|