@primeuicom/mcp 1.2.2 → 1.2.3

package/dist/service.js

@@ -229,6 +229,7 @@ function buildProjectRootHint() {
 var primeUiProjectConfigSchema = z2.object({
   projectId: z2.string().trim().min(1),
   apiKey: z2.string().trim().min(1),
+  apiBaseUrl: z2.string().trim().url().optional(),
   targetProjectPath: z2.string().trim().regex(/^\.\/.*$/).optional()
 }).passthrough();
 var primeUiProjectConfigWithTargetPathSchema = primeUiProjectConfigSchema.superRefine((value, ctx) => {
@@ -519,6 +520,23 @@ async function resolvePrimeUiApiKey(options) {
     hint: "Set PRIMEUI_API_KEY or ensure apiKey is present in .primeui/project.json."
   });
 }
+function resolvePrimeUiApiBaseUrlDetails(options) {
+  const envBaseUrl = options.baseUrlFromEnv?.trim();
+  const configBaseUrl = options.projectConfig?.apiBaseUrl?.trim();
+  const envProvided = Boolean(envBaseUrl);
+  const configProvided = Boolean(configBaseUrl);
+  const resolvedBaseUrl = envBaseUrl || configBaseUrl;
+  return {
+    baseUrl: resolvedBaseUrl,
+    source: envProvided ? "env" : configProvided ? "config" : "default",
+    envProvided,
+    configProvided,
+    valuesMatch: envProvided && configProvided ? envBaseUrl === configBaseUrl : void 0
+  };
+}
+function resolvePrimeUiApiBaseUrl(options) {
+  return resolvePrimeUiApiBaseUrlDetails(options).baseUrl;
+}
 
 // src/sources/api-provider.ts
 import { createWriteStream } from "fs";
@@ -529,6 +547,9 @@ import { pipeline } from "stream/promises";
 
 // src/lib/api-v1-contract.ts
 import { z as z3 } from "zod";
+var primeUiPageSlugInputSchema = z3.string().refine((value) => value.trim().length > 0, {
+  message: "pageSlug must be a non-empty string"
+});
 var primeUiExportStatusSchema = z3.enum(
   ["in_progress", "completed", "failed"]
 );
@@ -639,6 +660,105 @@ var primeUiPageGenerationTypeSchema = z3.enum([
   "docs",
   "legal"
 ]);
+var primeUiComponentCandidateOperationSchema = z3.discriminatedUnion("type", [
+  z3.object({
+    type: z3.literal("append")
+  }),
+  z3.object({
+    type: z3.literal("insert"),
+    index: z3.number().int()
+  }),
+  z3.object({
+    type: z3.literal("replace"),
+    index: z3.number().int()
+  })
+]);
+var primeUiComponentCandidateConstraintsSchema = z3.object({
+  spreadDegree: z3.enum(["any-group", "same-group", "same-family"]).optional(),
+  allowedGroups: z3.array(z3.string()).optional(),
+  excludedGroups: z3.array(z3.string()).optional(),
+  excludeComponentIds: z3.array(z3.string()).optional()
+});
+var primeUiComponentCandidatesInputSchema = z3.object({
+  pageSlug: primeUiPageSlugInputSchema,
+  pageType: primeUiPageGenerationTypeSchema,
+  blocks: z3.array(
+    z3.object({
+      componentId: z3.string()
+    })
+  ),
+  operation: primeUiComponentCandidateOperationSchema,
+  count: z3.number().int().positive().optional(),
+  constraints: primeUiComponentCandidateConstraintsSchema.optional()
+});
+var primeUiComponentCandidateRequestEchoSchema = z3.object({
+  pageSlug: z3.string(),
+  pageType: z3.string(),
+  operation: primeUiComponentCandidateOperationSchema,
+  count: z3.number()
+});
+var requiredUnknownSchema = z3.custom((value) => value !== void 0);
+var primeUiComponentCandidateLayoutObjectSchema = z3.object({
+  container: requiredUnknownSchema,
+  textAlignment: requiredUnknownSchema,
+  bottomWeight: requiredUnknownSchema,
+  entryWidth: requiredUnknownSchema,
+  exitWidth: requiredUnknownSchema,
+  orientation: requiredUnknownSchema,
+  structure: requiredUnknownSchema
+});
+var primeUiComponentCandidateLayoutSchema = z3.custom(
+  (value) => primeUiComponentCandidateLayoutObjectSchema.safeParse(value).success
+);
+var primeUiComponentCandidateObjectSchema = z3.object({
+  componentId: z3.string(),
+  name: z3.string(),
+  group: z3.string(),
+  familyId: z3.string(),
+  uxScore: z3.number(),
+  insertionScore: z3.number(),
+  followingScore: z3.number(),
+  layout: primeUiComponentCandidateLayoutSchema,
+  defaultProps: requiredUnknownSchema,
+  exportReady: z3.boolean(),
+  copyHints: z3.object({
+    deliveryToolchain: z3.array(z3.string())
+  }),
+  description: z3.string().nullable().optional(),
+  functionality: z3.string().nullable().optional(),
+  impression: z3.string().nullable().optional(),
+  visualStyle: z3.unknown().optional(),
+  compactSchema: z3.string().nullable().optional(),
+  jsonSchema: z3.record(z3.unknown()).nullable().optional()
+});
+var primeUiComponentCandidateSchema = z3.custom(
+  (value) => primeUiComponentCandidateObjectSchema.safeParse(value).success
+);
+var primeUiComponentCandidatesResponseSchema = z3.object({
+  request: primeUiComponentCandidateRequestEchoSchema,
+  candidates: z3.array(primeUiComponentCandidateSchema)
+});
+var primeUiComponentPropsValidateInputSchema = z3.object({
+  pageSlug: primeUiPageSlugInputSchema,
+  componentId: z3.string(),
+  props: z3.record(z3.unknown())
+});
+var primeUiComponentPropsValidationErrorSchema = z3.object({
+  path: z3.string(),
+  message: z3.string()
+});
+var primeUiComponentPropsRenderCheckSchema = z3.object({
+  attempted: z3.boolean(),
+  passed: z3.boolean(),
+  message: z3.string()
+});
+var primeUiComponentPropsValidateResponseSchema = z3.object({
+  valid: z3.boolean(),
+  normalizedProps: z3.record(z3.unknown()).nullable(),
+  errors: z3.array(primeUiComponentPropsValidationErrorSchema),
+  hints: z3.array(z3.string()),
+  renderCheck: primeUiComponentPropsRenderCheckSchema
+});
 var primeUiProjectApiWireframeStatusSchema = z3.enum(["pending", "generating", "ready", "error"]);
 var primeUiProjectApiVariantSummarySchema = z3.object({
   id: z3.string(),
@@ -1145,6 +1265,20 @@ var ApiProjectDataProvider = class {
       primeUiProjectPageDetailsSchema
     );
   }
+  async getComponentCandidates(input) {
+    return this.requestJson(
+      "component-planning/candidates",
+      primeUiComponentCandidatesResponseSchema,
+      this.buildJsonRequestInit(input)
+    );
+  }
+  async validateComponentProps(input) {
+    return this.requestJson(
+      "component-planning/props/validate",
+      primeUiComponentPropsValidateResponseSchema,
+      this.buildJsonRequestInit(input)
+    );
+  }
   async listExports() {
     const response = await this.requestJson(
       "project/exports",
@@ -1856,19 +1990,23 @@ async function runHealthCheck(options) {
     apiKeyFromEnv: env.PRIMEUI_API_KEY
   });
   const configApiKeyState = resolvedProjectConfig ? "set" : configStatus === "missing" || configStatus === "unresolved" ? "missing" : "unknown";
-  const apiBaseUrlSource = env.PRIMEUI_API_BASE_URL?.trim() ? "env" : "default";
+  const apiBaseUrlDetails = resolvePrimeUiApiBaseUrlDetails({
+    projectConfig: resolvedProjectConfig?.projectConfig,
+    baseUrlFromEnv: env.PRIMEUI_API_BASE_URL
+  });
+  const apiBaseUrlSource = apiBaseUrlDetails.source;
   const defaultApiRoot = normalizePrimeUiApiRoot(DEFAULT_API_BASE_URL);
   let apiRoot;
   let projectInfoUrl;
   let apiCheck;
   try {
-    apiRoot = normalizePrimeUiApiRoot(env.PRIMEUI_API_BASE_URL);
+    apiRoot = normalizePrimeUiApiRoot(apiBaseUrlDetails.baseUrl);
     projectInfoUrl = buildPrimeUiApiUrl(apiRoot, "project");
   } catch (error) {
     apiCheck = {
       status: "skipped",
       apiBaseUrlSource,
-      nonStandardBaseUrl: Boolean(env.PRIMEUI_API_BASE_URL?.trim()),
+      nonStandardBaseUrl: Boolean(apiBaseUrlDetails.baseUrl?.trim()),
       message: error instanceof Error ? error.message : String(error),
       errorKind: "configuration"
     };
@@ -1886,10 +2024,10 @@ async function runHealthCheck(options) {
     } else {
       const provider = options.createProvider?.({
         apiKey: apiKeyDetails.apiKey,
-        baseUrl: env.PRIMEUI_API_BASE_URL
+        baseUrl: apiBaseUrlDetails.baseUrl
       }) ?? new ApiProjectDataProvider({
         apiKey: apiKeyDetails.apiKey,
-        baseUrl: env.PRIMEUI_API_BASE_URL
+        baseUrl: apiBaseUrlDetails.baseUrl
       });
       try {
         await provider.getProjectInfo();
@@ -4160,7 +4298,9 @@ async function copyRegistryComponentFromExport(input) {
     graphInternalFiles,
     referencedPublicFiles
   });
-  const copyableSourceFiles = fileTransfers.map((transfer) => transfer.sourcePath);
+  const copyableSourceFiles = fileTransfers.map(
+    (transfer) => transfer.sourcePath
+  );
   const copyableFiles = fileTransfers.map((transfer) => transfer.targetPath);
   const transferBySourcePath = new Map(
     fileTransfers.map((transfer) => [transfer.sourcePath, transfer])
@@ -4510,6 +4650,12 @@ var ProjectSyncService = class {
       notes: guidanceNotes
     };
   }
+  async getComponentCandidates(input, _context) {
+    return this.provider.getComponentCandidates(input);
+  }
+  async validateComponentProps(input, _context) {
+    return this.provider.validateComponentProps(input);
+  }
   async listExports(_context) {
     await this.ensureTempLayout();
     return this.provider.listExports();
@@ -4768,10 +4914,14 @@ var LazyProjectSyncSource = class {
       projectConfig: resolvedProjectConfig.projectConfig,
       apiKeyFromEnv: this.env.PRIMEUI_API_KEY
     });
+    const baseUrl = resolvePrimeUiApiBaseUrl({
+      projectConfig: resolvedProjectConfig.projectConfig,
+      baseUrlFromEnv: this.env.PRIMEUI_API_BASE_URL
+    });
     this.stickyProjectRoot = projectRoot;
     const provider = this.createProvider({
       apiKey,
-      baseUrl: this.env.PRIMEUI_API_BASE_URL
+      baseUrl
     });
     return new ProjectSyncService({
       projectRoot,
@@ -4954,6 +5104,24 @@ var LazyProjectSyncSource = class {
       (service) => service.syncSearchEnvironment(environmentSlug, context)
     );
   }
+  async getComponentCandidates(input, context) {
+    return this.withService(
+      context,
+      (service) => service.getComponentCandidates(input, context),
+      {
+        requireTargetProjectRoot: false
+      }
+    );
+  }
+  async validateComponentProps(input, context) {
+    return this.withService(
+      context,
+      (service) => service.validateComponentProps(input, context),
+      {
+        requireTargetProjectRoot: false
+      }
+    );
+  }
   async listExports(context) {
     return this.withService(context, (service) => service.listExports(context));
   }
@@ -5248,7 +5416,8 @@ ${WORKFLOW_SUMMARY}
 
 ADDITIONAL CAPABILITIES:
 - PrimeUI MCP also exposes atomic external API tools for project description, project pages, page variants, active-variant selection, and issue reports.
-- These atomic tools are OPTIONAL additional capabilities for extended scenarios.
+- PrimeUI MCP also exposes component planning tools such as component_candidates_get and component_props_validate for exported-project page building.
+- These additional tools are OPTIONAL capabilities for extended scenarios.
 - They are NOT part of the primary import/export workflow above.
 - Do not replace get_project_info/create_export/download_export/copy_* with the additional API tools when the user wants the standard page import/export flow.
 
@@ -6042,6 +6211,122 @@ var pageGenerationTypeSchema = z4.enum([
 ]).describe(
   "Supported PrimeUI page type. Must match the external API page type enum."
 );
+var componentCandidateOperationSchema = z4.discriminatedUnion("type", [
+  z4.object({
+    type: z4.literal("append")
+  }),
+  z4.object({
+    type: z4.literal("insert"),
+    index: z4.number().int().describe("Zero-based insertion index in the ordered blocks list.")
+  }),
+  z4.object({
+    type: z4.literal("replace"),
+    index: z4.number().int().describe("Zero-based index of the block being replaced.")
+  })
+]);
+var componentCandidatesGetInputSchema = z4.object({
+  projectRoot: projectRootInputSchema,
+  pageSlug: z4.string().refine((value) => value.trim().length > 0, {
+    message: "pageSlug must be a non-empty string"
+  }).describe(
+    "Stable PrimeUI page slug used for candidate scoring and automatic diagnostics, for example '/pricing'."
+  ),
+  pageType: pageGenerationTypeSchema,
+  blocks: z4.array(
+    z4.object({
+      componentId: z4.string().describe("PrimeUI component id already present in page order.")
+    })
+  ).describe(
+    "Current ordered page composition before applying the requested operation."
+  ),
+  operation: componentCandidateOperationSchema.optional().default({ type: "append" }).describe(
+    "Candidate placement operation. Omit for the normal append flow."
+  ),
+  count: z4.number().int().positive().optional().describe("Optional maximum candidate count. Studio defaults to 8."),
+  constraints: z4.object({
+    spreadDegree: z4.enum(["any-group", "same-group", "same-family"]).optional().describe("Optional UX scoring spread override."),
+    allowedGroups: z4.array(z4.string()).optional().describe("Optional allow-list of candidate groups."),
+    excludedGroups: z4.array(z4.string()).optional().describe("Optional deny-list of candidate groups."),
+    excludeComponentIds: z4.array(z4.string()).optional().describe("Optional component ids to remove from the candidate pool.")
+  }).optional().describe("Optional advanced candidate pool and spread constraints.")
+});
+var componentCandidatesGetValidationSchema = componentCandidatesGetInputSchema;
+var componentPropsValidateInputSchema = z4.object({
+  projectRoot: projectRootInputSchema,
+  pageSlug: z4.string().refine((value) => value.trim().length > 0, {
+    message: "pageSlug must be a non-empty string"
+  }).describe(
+    "Stable PrimeUI page slug used for validation diagnostics, for example '/pricing'. Use the same pageSlug as candidate retrieval."
+  ),
+  componentId: z4.string().describe("PrimeUI component registry identifier selected by the agent."),
+  props: z4.record(z4.unknown()).describe(
+    "Agent-authored props payload to validate against PrimeUI's registry schema."
+  )
+});
+var componentPropsValidateValidationSchema = componentPropsValidateInputSchema;
+var componentCandidateLayoutSchema = z4.object({
+  container: z4.unknown().describe("Layout container metadata."),
+  textAlignment: z4.unknown().describe("Text alignment metadata."),
+  bottomWeight: z4.unknown().describe("Bottom visual weight metadata."),
+  entryWidth: z4.unknown().describe("Incoming width rhythm metadata."),
+  exitWidth: z4.unknown().describe("Outgoing width rhythm metadata."),
+  orientation: z4.unknown().describe("Optional orientation metadata."),
+  structure: z4.unknown().describe("Optional structure metadata.")
+});
+var componentCandidateSchema = z4.object({
+  componentId: z4.string().describe("PrimeUI component registry identifier to choose or export."),
+  name: z4.string().describe("Human-readable component name."),
+  group: z4.string().describe("Component group used by candidate scoring."),
+  familyId: z4.string().describe("Component family identifier from catalog."),
+  uxScore: z4.number().describe("Total UX score used for ranking."),
+  insertionScore: z4.number().describe("Score for inserting this candidate at the requested position."),
+  followingScore: z4.number().describe("Neighbor compatibility score with the following block."),
+  layout: componentCandidateLayoutSchema.describe(
+    "Layout metadata useful for choosing visual rhythm."
+  ),
+  defaultProps: z4.unknown().describe("Registry default props, when available from PrimeUI."),
+  exportReady: z4.boolean().describe("True when the component is expected to be exportable."),
+  copyHints: z4.object({
+    deliveryToolchain: z4.array(z4.string()).describe(
+      "Recommended tool sequence for delivering this registry component locally."
+    )
+  }).describe("Machine-readable delivery hints for the selected candidate."),
+  description: z4.string().nullable().optional(),
+  functionality: z4.string().nullable().optional(),
+  impression: z4.string().nullable().optional(),
+  visualStyle: z4.unknown().optional(),
+  compactSchema: z4.string().nullable().optional(),
+  jsonSchema: z4.record(z4.unknown()).nullable().optional()
+});
+var componentCandidatesGetOutputSchema = z4.object({
+  request: z4.object({
+    pageSlug: z4.string(),
+    pageType: z4.string(),
+    operation: componentCandidateOperationSchema,
+    count: z4.number()
+  }).describe("Normalized request echo returned by PrimeUI."),
+  candidates: z4.array(componentCandidateSchema).describe("Ranked rich candidate shortlist returned by PrimeUI.")
+});
+var componentPropsValidationErrorSchema = z4.object({
+  path: z4.string().describe("JSON path or root path for the invalid props location."),
+  message: z4.string().describe("Actionable validation message returned by PrimeUI.")
+});
+var componentPropsRenderCheckSchema = z4.object({
+  attempted: z4.boolean().describe("True when PrimeUI attempted a render smoke check."),
+  passed: z4.boolean().describe("True when the render smoke check passed."),
+  message: z4.string().describe("Human-readable render check status or skip reason.")
+});
+var componentPropsValidateOutputSchema = z4.object({
+  valid: z4.boolean().describe("True when props passed schema validation."),
+  normalizedProps: z4.record(z4.unknown()).nullable().describe(
+    "Props normalized by PrimeUI when valid; null when validation failed."
+  ),
+  errors: z4.array(componentPropsValidationErrorSchema).describe("Structured validation errors for invalid props."),
+  hints: z4.array(z4.string()).describe("Agent-facing guidance for correcting invalid props."),
+  renderCheck: componentPropsRenderCheckSchema.describe(
+    "Optional render-smoke status returned by PrimeUI."
+  )
+});
 var projectApiPageResourceSchema = z4.object({
   id: z4.string().describe("Stable PrimeUI page identifier."),
   title: z4.string().describe("Human-readable page title."),
@@ -6475,6 +6760,51 @@ WHEN TO USE:
     openWorldHint: true
   }
 };
+var toolComponentCandidatesGet = {
+  title: "PrimeUI Component Candidates Get",
+  description: `External planning helper. Returns a ranked rich candidate shortlist for adding, inserting, or replacing one PrimeUI component in an exported-project page composition.
+
+WHEN TO USE:
+- Use this when building or editing a local exported-project page and you need PrimeUI scoring guidance for which componentId to choose next.
+- The normal flow is append: pass the current ordered blocks and omit operation, which defaults to { "type": "append" }.
+- Use insert or replace only when the caller is intentionally editing a specific position in the ordered blocks list.
+- Use the returned copyHints.deliveryToolchain when the chosen candidate must be delivered locally: create_component_export, download_component_export, then copy_registry_component.
+
+AFTER CALLING:
+- Choose from candidates using uxScore, insertionScore, followingScore, group/family/layout rhythm, descriptions, defaults, and schemas.
+- Do not mutate Prime page state from this tool result. This is planning guidance only.
+- Keep the same pageSlug across later planning and validation calls so PrimeUI diagnostics stay correlated.`,
+  inputSchema: componentCandidatesGetInputSchema,
+  outputSchema: componentCandidatesGetOutputSchema,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  }
+};
+var toolComponentPropsValidate = {
+  title: "PrimeUI Component Props Validate",
+  description: `External planning helper. Validates agent-authored props for one selected PrimeUI component before editing local exported-project files.
+
+WHEN TO USE:
+- Use this after choosing a component candidate and drafting props from the user's brief, candidate metadata, defaultProps, compactSchema, or jsonSchema.
+- Keep pageSlug stable across candidate retrieval and validation so PrimeUI diagnostics stay correlated.
+- Treat valid: false as actionable feedback, not a transport failure. Fix the props from errors and hints, then call this tool again.
+
+AFTER CALLING:
+- If valid is true, use normalizedProps for local page edits.
+- If valid is false, correct props using errors[].path, errors[].message, and hints before editing local files.
+- Do not mutate Prime page state from this tool result. This is validation guidance only.`,
+  inputSchema: componentPropsValidateInputSchema,
+  outputSchema: componentPropsValidateOutputSchema,
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  }
+};
 var toolProjectIssueReportSubmit = {
   title: "PrimeUI Project Issue Report Submit",
   description: `Atomic external API helper. Submits an issue report for the scoped PrimeUI project.
@@ -6885,6 +7215,32 @@ function createPrimeUiMcpServer(source) {
       }
     }
   );
+  server.registerTool(
+    "component_candidates_get",
+    toolComponentCandidatesGet,
+    async (args) => {
+      try {
+        const { projectRoot, ...input } = componentCandidatesGetValidationSchema.parse(args);
+        const result = await source.getComponentCandidates(input, { projectRoot });
+        return okResult("component_candidates_get", result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+  server.registerTool(
+    "component_props_validate",
+    toolComponentPropsValidate,
+    async (args) => {
+      try {
+        const { projectRoot, ...input } = componentPropsValidateValidationSchema.parse(args);
+        const result = await source.validateComponentProps(input, { projectRoot });
+        return okResult("component_props_validate", result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
   server.registerTool(
     "list_exports",
     toolListExports,