@primeuicom/mcp 1.2.2 → 1.2.4

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"]
 );
@@ -601,6 +622,14 @@ var primeUiComponentExportPageSchema = z3.object({
   isReadyToExport: z3.boolean(),
   manifest: primeUiExportPageManifestSchema
 });
+var primeUiComponentExportSelectedBlockSchema = z3.object({
+  blockId: z3.string(),
+  componentId: z3.string(),
+  contentKey: z3.string(),
+  occurrenceIndex: z3.number().int().positive(),
+  props: z3.record(z3.unknown()).nullable(),
+  slot: z3.string().nullable()
+});
 var primeUiProjectInfoSchema = z3.object(
   {
     projectId: z3.string(),
@@ -639,6 +668,115 @@ 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({
+  blockId: z3.string().refine((value) => value.trim().length > 0, {
+    message: "blockId must be a non-empty string"
+  }),
+  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(),
+  propsValidationId: z3.string().nullable(),
+  block: z3.object({
+    blockId: z3.string(),
+    componentId: z3.string(),
+    contentKey: z3.string(),
+    props: 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(),
@@ -867,6 +1005,7 @@ var primeUiExportManifestSchema = primeUiCreateExportResponseSchema;
 var primeUiComponentExportResponseSchema = z3.object({
   exportId: z3.string(),
   export: primeUiPostExportPayloadExportSchema,
+  block: primeUiComponentExportSelectedBlockSchema.optional(),
   component: primeUiComponentExportComponentSchema,
   page: primeUiComponentExportPageSchema,
   pages: z3.array(primeUiComponentExportPageSchema)
@@ -963,6 +1102,16 @@ var normalizePrimeUiApiRoot = (rawBaseUrl) => {
 var buildPrimeUiApiUrl = (apiRoot, endpoint) => new URL(endpoint, apiRoot).toString();
 var isJsonContentType = (contentType) => contentType.includes("application/json") || contentType.includes("+json");
 var isZipContentType = (contentType) => ZIP_CONTENT_TYPES.some((allowedType) => contentType.includes(allowedType));
+function normalizePropsValidationId(propsValidationId) {
+  if (typeof propsValidationId === "undefined") {
+    return void 0;
+  }
+  const trimmed = propsValidationId.trim();
+  if (!trimmed) {
+    throw new Error("propsValidationId must be a non-empty string.");
+  }
+  return trimmed;
+}
 var looksLikeZipArchive = (buffer) => {
   if (buffer.length < 4) {
     return false;
@@ -1145,6 +1294,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",
@@ -1161,11 +1324,14 @@ var ApiProjectDataProvider = class {
       }
     );
   }
-  async createComponentExport(componentId) {
+  async createComponentExport(componentId, options = {}) {
+    const propsValidationId = normalizePropsValidationId(
+      options.propsValidationId
+    );
     return this.requestJson(
       `component-registry/components/${encodeURIComponent(componentId)}/exports`,
       primeUiComponentExportResponseSchema,
-      {
+      propsValidationId ? this.buildJsonRequestInit({ propsValidationId }) : {
         method: "POST"
       }
     );
@@ -1856,19 +2022,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 +2056,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();
@@ -3782,6 +3952,11 @@ function isVirtualRouteFile(relativePath) {
   const segments = relativePath.split("/");
   return segments[0] === "src" && segments[1] === "app" && segments.includes(VIRTUAL_ROUTE_SEGMENT);
 }
+function isVirtualComponentExportPageFile(relativePath) {
+  const segments = relativePath.split("/");
+  const virtualRouteIndex = segments.indexOf(VIRTUAL_ROUTE_SEGMENT);
+  return isVirtualRouteFile(relativePath) && virtualRouteIndex >= 0 && segments.length === virtualRouteIndex + 3 && segments[virtualRouteIndex + 2] === "page.tsx";
+}
 function getVirtualComponentRelativePath(relativePath, componentId) {
   const prefix = `${COMPONENT_PAGES_PREFIX}${VIRTUAL_ROUTE_SEGMENT}/${componentId}/`;
   if (!relativePath.startsWith(prefix)) {
@@ -3847,6 +4022,44 @@ function toImportPath(relativePath) {
   const withoutIndex = withoutExtension.replace(/\/index$/u, "");
   return `@/${withoutIndex.replace(/^src\//u, "")}`;
 }
+function toPascalComponentName(componentId) {
+  return componentId.split(/[^a-zA-Z0-9]+/u).filter(Boolean).map((part) => `${part.charAt(0).toUpperCase()}${part.slice(1)}`).join("");
+}
+function toVariableName(componentName) {
+  if (!componentName) {
+    return "componentProps";
+  }
+  return `${componentName.charAt(0).toLowerCase()}${componentName.slice(1)}Props`;
+}
+function toSafeCamelIdentifier(input, fallback) {
+  const parts = input.trim().split(/[^a-zA-Z0-9]+/u).filter(Boolean);
+  if (parts.length === 0) {
+    return fallback;
+  }
+  const pascalName = parts.map((part) => {
+    const normalizedPart = part.toLowerCase();
+    return `${normalizedPart.charAt(0).toUpperCase()}${normalizedPart.slice(1)}`;
+  }).join("");
+  if (!pascalName) {
+    return fallback;
+  }
+  if (/^[0-9]/u.test(pascalName)) {
+    return `block${pascalName}`;
+  }
+  return `${pascalName.charAt(0).toLowerCase()}${pascalName.slice(1)}`;
+}
+function isDefaultComponentExportBlock(selectedBlock) {
+  return selectedBlock.blockId === `component-export:${selectedBlock.componentId}:block`;
+}
+function toPropsVariableName(input) {
+  if (isDefaultComponentExportBlock(input.selectedBlock)) {
+    return toVariableName(input.componentName);
+  }
+  return `${toSafeCamelIdentifier(
+    input.selectedBlock.blockId,
+    input.componentName ? toVariableName(input.componentName).replace(/Props$/u, "") : "component"
+  )}Props`;
+}
 function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
 }
@@ -4086,6 +4299,113 @@ function buildMessage(input) {
   );
   return parts.join(" ");
 }
+function getDefaultSelectedBlock(manifest) {
+  const componentId = manifest.component.componentId;
+  return {
+    blockId: `component-export:${componentId}:block`,
+    componentId,
+    contentKey: componentId,
+    occurrenceIndex: 1,
+    props: null,
+    slot: null
+  };
+}
+function getSelectedBlock(manifest) {
+  return manifest.block ?? getDefaultSelectedBlock(manifest);
+}
+function getVirtualRouteFile(manifestFiles) {
+  return manifestFiles.find(isVirtualComponentExportPageFile) ?? manifestFiles.find(isVirtualRouteFile) ?? null;
+}
+function readBalancedObjectLiteral(input, startIndex) {
+  if (input[startIndex] !== "{") {
+    return null;
+  }
+  let depth = 0;
+  let quote = null;
+  let escaped = false;
+  for (let index = startIndex; index < input.length; index += 1) {
+    const char = input[index];
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (quote) {
+      if (char === "\\") {
+        escaped = true;
+        continue;
+      }
+      if (char === quote) {
+        quote = null;
+      }
+      continue;
+    }
+    if (char === '"' || char === "'" || char === "`") {
+      quote = char;
+      continue;
+    }
+    if (char === "{") {
+      depth += 1;
+      continue;
+    }
+    if (char !== "}") {
+      continue;
+    }
+    depth -= 1;
+    if (depth === 0) {
+      return input.slice(startIndex, index + 1);
+    }
+  }
+  return null;
+}
+function extractContentDataPropsCode(input) {
+  const contentDataIndex = input.source.indexOf("const contentData");
+  if (contentDataIndex < 0) {
+    return null;
+  }
+  const keyPattern = new RegExp(
+    `["']${escapeRegExp(input.contentKey)}["']\\s*:`,
+    "u"
+  );
+  const keyMatch = keyPattern.exec(input.source.slice(contentDataIndex));
+  if (!keyMatch) {
+    return null;
+  }
+  const valueStartSearchIndex = contentDataIndex + keyMatch.index + keyMatch[0].length;
+  const objectStartIndex = input.source.indexOf("{", valueStartSearchIndex);
+  if (objectStartIndex < 0) {
+    return null;
+  }
+  return readBalancedObjectLiteral(input.source, objectStartIndex);
+}
+async function buildRegistryComponentInsertion(input) {
+  const componentName = toPascalComponentName(input.selectedBlock.componentId);
+  const propsVariableName = toPropsVariableName({
+    componentName,
+    selectedBlock: input.selectedBlock
+  });
+  const virtualRouteFile = getVirtualRouteFile(input.manifestFiles);
+  const referenceFiles = virtualRouteFile ? [virtualRouteFile] : [];
+  let materializedPropsCode = input.selectedBlock.props ? JSON.stringify(input.selectedBlock.props, null, 2) : "{}";
+  if (virtualRouteFile) {
+    try {
+      const virtualRouteSource = await readFile7(
+        path13.join(input.exportPath, virtualRouteFile),
+        "utf-8"
+      );
+      materializedPropsCode = extractContentDataPropsCode({
+        source: virtualRouteSource,
+        contentKey: input.selectedBlock.contentKey
+      }) ?? materializedPropsCode;
+    } catch {
+    }
+  }
+  return {
+    imports: [`import ${componentName} from "${input.componentImportPath}";`],
+    propsCode: `const ${propsVariableName} = ${materializedPropsCode};`,
+    jsx: `<${componentName} {...${propsVariableName}} />`,
+    referenceFiles
+  };
+}
 async function copyRegistryComponentFromExport(input) {
   const normalizedComponentId = normalizeComponentId(input.componentId);
   const { exportId, exportPath } = await resolveSingleExportDirectory(
@@ -4160,7 +4480,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])
@@ -4176,6 +4498,13 @@ async function copyRegistryComponentFromExport(input) {
     componentId: normalizedComponentId,
     copyableFiles: copyableSourceFiles
   });
+  const selectedBlock = getSelectedBlock(manifest);
+  const insertion = await buildRegistryComponentInsertion({
+    componentImportPath,
+    exportPath,
+    manifestFiles,
+    selectedBlock
+  });
   const candidateFiles = await resolveManifestCandidateFiles({
     exportPath,
     manifestOwnerLabel: `registry component "${normalizedComponentId}"`,
@@ -4267,8 +4596,10 @@ async function copyRegistryComponentFromExport(input) {
     exportId,
     componentId: normalizedComponentId,
     componentImportPath,
+    insertion,
     manifestFiles,
     copyableFiles,
+    selectedBlock,
     skippedFiles,
     conflicts: sortedConflictEntries,
     missingManifestFiles: missingManifestFileList
@@ -4305,8 +4636,10 @@ async function copyRegistryComponentFromExport(input) {
     manifestPath,
     component: manifest.component,
     componentImportPath,
+    insertion,
     manifestFiles,
     copyableFiles,
+    selectedBlock,
     newFiles: sortedNewFiles,
     identicalFiles: sortedIdenticalFiles,
     conflictFiles: sortedConflictFiles,
@@ -4510,6 +4843,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();
@@ -4528,9 +4867,11 @@ var ProjectSyncService = class {
       }
     };
   }
-  async createComponentExport(componentId, _context) {
+  async createComponentExport(componentId, options = {}, _context) {
     await this.ensureTempLayout();
-    const result = await this.provider.createComponentExport(componentId);
+    const result = await this.provider.createComponentExport(componentId, {
+      propsValidationId: options.propsValidationId
+    });
     const manifestPath = buildManifestPath(this.exportsRoot, result.export.id);
     await writeUtf8(manifestPath, `${JSON.stringify(result, null, 2)}
 `);
@@ -4768,10 +5109,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 +5299,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));
   }
@@ -4963,10 +5326,10 @@ var LazyProjectSyncSource = class {
       (service) => service.createExport(context)
     );
   }
-  async createComponentExport(componentId, context) {
+  async createComponentExport(componentId, options, context) {
     return this.withService(
       context,
-      (service) => service.createComponentExport(componentId, context)
+      (service) => service.createComponentExport(componentId, options, context)
     );
   }
   async downloadExportById(id, context) {
@@ -5186,6 +5549,16 @@ var copyComponentGuidanceSchema = z4.object({
   requiredActions: z4.array(z4.string()).describe("Concrete next actions for finishing component transfer."),
   notes: z4.array(z4.string()).describe("Important semantics and caveats for this transfer result.")
 });
+var registryComponentInsertionSchema = z4.object({
+  imports: z4.array(z4.string()).describe("Import statements needed for inserting the copied component."),
+  propsCode: z4.string().describe(
+    "Materialized props source derived from the downloaded virtual component export."
+  ),
+  jsx: z4.string().describe("JSX snippet for rendering the materialized component instance."),
+  referenceFiles: z4.array(z4.string()).describe(
+    "Downloaded export files used as the source of truth for materialized insertion."
+  )
+});
 var pageDetailsSchema = pageSchema.extend({
   pageInstruction: z4.string().nullable().describe(
     "Current instruction text for the active page variant. Null when no active variant is set."
@@ -5248,7 +5621,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.
 
@@ -5473,6 +5847,7 @@ WHEN TO USE: Use this only for the component-registry import track when the user
 AFTER CALLING:
 - Verify component.componentId matches the requested componentId.
 - Verify component.isReadyToExport is true and page.manifest.files is present.
+- Pass propsValidationId from component_props_validate when exporting a validated instance. Omit it only for the intentional default-props component export path.
 - Local component sidecar manifest is saved to .primeui/temp/exports/[exportId].manifest.json.
 - Use the returned export ID to call download_component_export.
 - Use copy_registry_component after download_component_export for this component-track manifest. Do not use page copy tools for component-track manifests.
@@ -5481,7 +5856,10 @@ AFTER CALLING:
 ${WORKFLOW_SUMMARY}`,
   inputSchema: {
     projectRoot: projectRootInputSchema,
-    componentId: z4.string().min(1).describe("PrimeUI component registry identifier to export.")
+    componentId: z4.string().min(1).describe("PrimeUI component registry identifier to export."),
+    propsValidationId: z4.string().trim().min(1).optional().describe(
+      "Optional props validation handoff id returned by component_props_validate. Omit to export registry defaultProps."
+    )
   },
   outputSchema: z4.object({
     exportId: z4.string().describe(
@@ -5500,6 +5878,9 @@ ${WORKFLOW_SUMMARY}`,
       exportables: z4.array(exportableSchema).describe("Shared exportables included in this export payload.")
     }).describe("Created component export summary."),
     component: componentExportComponentSchema,
+    block: copyComponentSelectedBlockSchema.optional().describe(
+      "Selected virtual component-export block metadata when the export used a propsValidationId handoff."
+    ),
     page: componentExportPageSchema.describe(
       "Virtual page manifest for this component export."
     ),
@@ -5813,6 +6194,7 @@ BEHAVIOR:
 - Copies only the selected registry component import graph, narrowly referenced public assets, and safe support files from the component sidecar manifest/export.
 - Remaps component-local files into src/components/shared/** and returns componentImportPath for manual insertion.
 - Skips virtual route files that include __primeui-component-export, because those are reference/insertion hints and must not be installed as normal app routes.
+- Returns selectedBlock and insertion artifacts derived from the downloaded virtual component export. Treat insertion.propsCode and insertion.jsx as the materialized instance source of truth.
 - Skips app/search/layout/header/footer/env/project-shell files instead of copying whole exportable buckets.
 - Never copies package.json directly. package.json is used only to add missing dependency entries and report dependency version conflicts.
 - Keeps safe support files on their natural target paths, such as src/components/ui/**, src/lib/**, src/types/**, and src/contexts/**.
@@ -5849,6 +6231,12 @@ ${WORKFLOW_SUMMARY}`,
     componentImportPath: z4.string().describe(
       "Canonical import path for the copied registry component entrypoint, for example @/components/shared/hero--pricing."
     ),
+    selectedBlock: copyComponentSelectedBlockSchema.describe(
+      "Selected virtual component-export block metadata. First-instance contentKey semantics match page export."
+    ),
+    insertion: registryComponentInsertionSchema.describe(
+      "Materialized insertion artifact for adding this component instance to a real local page."
+    ),
     manifestFiles: z4.array(z4.string()).describe(
       "Normalized component sidecar manifest files considered by the copy service."
     ),
@@ -6042,6 +6430,136 @@ 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."),
+  blockId: z4.string().trim().min(1).describe(
+    "Stable local block identifier for this planned component instance. Required for propsValidationId handoff records."
+  ),
+  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."
+  ),
+  propsValidationId: z4.string().nullable().describe(
+    "Durable validation handoff id for create_component_export; null when props are invalid."
+  ),
+  block: z4.object({
+    blockId: z4.string(),
+    componentId: z4.string(),
+    contentKey: z4.string(),
+    props: z4.record(z4.unknown())
+  }).nullable().describe(
+    "Selected validated block identity and normalized props; null when props are invalid."
+  ),
+  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 +6993,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, pass propsValidationId to create_component_export so copy_registry_component can return materialized insertion artifacts.
+- 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 +7448,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,
@@ -6918,11 +7507,17 @@ function createPrimeUiMcpServer(source) {
   server.registerTool(
     "create_component_export",
     toolCreateComponentExport,
-    async ({ componentId, projectRoot }) => {
+    async ({
+      componentId,
+      projectRoot,
+      propsValidationId
+    }) => {
       try {
-        const result = await source.createComponentExport(componentId, {
-          projectRoot
-        });
+        const result = await source.createComponentExport(
+          componentId,
+          { propsValidationId },
+          { projectRoot }
+        );
         return okResult("create_component_export", result);
       } catch (error) {
         return errorResult(error);