@primeuicom/mcp 0.1.11 → 0.1.13

package/dist/service.js

@@ -1,77 +1,207 @@
 #!/usr/bin/env node
 
 // src/service.ts
+import path7 from "path";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
+// src/lib/project-link-config.ts
+import { readFile, stat } from "fs/promises";
+import path from "path";
+import { z } from "zod";
+var PRIMEUI_PROJECT_CONFIG_RELATIVE_PATH = ".primeui/project.json";
+var primeUiProjectConfigSchema = z.object({
+  projectId: z.string().trim().min(1),
+  apiKey: z.string().trim().min(1),
+  targetProjectPath: z.string().trim().regex(/^\.\/.*$/)
+}).passthrough();
+async function fileExists(filePath) {
+  try {
+    const fileStats = await stat(filePath);
+    return fileStats.isFile();
+  } catch {
+    return false;
+  }
+}
+function ancestors(startPath) {
+  const resolvedStartPath = path.resolve(startPath);
+  const directories = [];
+  let currentPath = resolvedStartPath;
+  while (true) {
+    directories.push(currentPath);
+    const parentPath = path.dirname(currentPath);
+    if (parentPath === currentPath) {
+      break;
+    }
+    currentPath = parentPath;
+  }
+  return directories;
+}
+async function findPrimeUiProjectConfigPath(startPath) {
+  for (const currentPath of ancestors(startPath)) {
+    const candidatePath = path.join(
+      currentPath,
+      PRIMEUI_PROJECT_CONFIG_RELATIVE_PATH
+    );
+    if (await fileExists(candidatePath)) {
+      return candidatePath;
+    }
+  }
+  return void 0;
+}
+async function readPrimeUiProjectConfig(projectConfigPath) {
+  let projectConfigRaw;
+  try {
+    projectConfigRaw = await readFile(projectConfigPath, "utf-8");
+  } catch (error) {
+    throw new Error(
+      `[primeui-mcp] failed to read ${PRIMEUI_PROJECT_CONFIG_RELATIVE_PATH}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  let projectConfigJson;
+  try {
+    projectConfigJson = JSON.parse(projectConfigRaw);
+  } catch (error) {
+    throw new Error(
+      `[primeui-mcp] invalid JSON in ${PRIMEUI_PROJECT_CONFIG_RELATIVE_PATH}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  const parsedConfig = primeUiProjectConfigSchema.safeParse(projectConfigJson);
+  if (!parsedConfig.success) {
+    const details = parsedConfig.error.issues.map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`).join("; ");
+    throw new Error(
+      `[primeui-mcp] invalid ${PRIMEUI_PROJECT_CONFIG_RELATIVE_PATH} format: ${details}`
+    );
+  }
+  return parsedConfig.data;
+}
+async function resolvePrimeUiProjectConfig(options) {
+  const envProjectRoot = options.projectRootFromEnv?.trim();
+  const projectConfigPath = envProjectRoot ? path.join(
+    path.resolve(envProjectRoot),
+    PRIMEUI_PROJECT_CONFIG_RELATIVE_PATH
+  ) : await findPrimeUiProjectConfigPath(options.cwd);
+  if (!projectConfigPath) {
+    throw new Error(
+      `[primeui-mcp] ${PRIMEUI_PROJECT_CONFIG_RELATIVE_PATH} not found from cwd (${options.cwd}).`
+    );
+  }
+  const projectRoot = path.dirname(path.dirname(projectConfigPath));
+  const projectConfig = await readPrimeUiProjectConfig(projectConfigPath);
+  return {
+    projectRoot,
+    projectConfigPath,
+    projectConfig
+  };
+}
+async function resolvePrimeUiApiKey(options) {
+  const envApiKey = options.apiKeyFromEnv?.trim();
+  if (envApiKey) {
+    return envApiKey;
+  }
+  const projectConfigApiKey = options.projectConfig.apiKey.trim();
+  if (!projectConfigApiKey) {
+    throw new Error(
+      "[primeui-mcp] PRIMEUI_API_KEY is missing in env and .primeui/project.json"
+    );
+  }
+  return projectConfigApiKey;
+}
+
 // src/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
 // src/instructions.ts
-import { z } from "zod/v3";
-var pageSchema = z.object({
-  id: z.string().describe(
+import { z as z2 } from "zod/v3";
+var pageSchema = z2.object({
+  id: z2.string().describe(
     "Stable PrimeUI page identifier. Use this to match the same page across tool responses."
   ),
-  title: z.string().describe(
+  title: z2.string().describe(
     "Human-readable page title. Show this to the user when confirming which pages to import."
   ),
-  slug: z.string().describe(
+  slug: z2.string().describe(
     "PrimeUI route slug, for example '/', '/pricing', '/docs/getting-started'. Use to match user intent."
   ),
-  pageType: z.string().describe(
+  pageType: z2.string().describe(
     "PrimeUI page type classification (for example landing, docs, pricing, blogIndex, legal)."
   ),
-  isReadyToExport: z.boolean().describe(
+  isReadyToExport: z2.boolean().describe(
     "True when this page has an active export-ready variant. Only ready pages are expected in export output."
   ),
-  pagePath: z.string().describe(
+  pagePath: z2.string().describe(
     "Relative file path to the page source inside downloaded export root. Copy page code from this exact path."
   ),
-  componentsPath: z.string().describe(
+  componentsPath: z2.string().describe(
     "Relative directory path inside downloaded export root where page-level components live. Use as dependency copy start."
   )
 }).describe(
   "PrimeUI page descriptor used by project and export tools. Paths are always relative to export project root."
 );
-var exportStatusSchema = z.enum(["in_progress", "completed", "failed"]).describe(
+var exportStatusSchema = z2.enum(["in_progress", "completed", "failed"]).describe(
   "Export lifecycle state. Use 'completed' before calling primeui_download_export."
 );
-var exportItemSchema = z.object({
-  id: z.string().describe(
+var exportItemSchema = z2.object({
+  id: z2.string().describe(
     "Export identifier. Pass this value to primeui_download_export input.id."
   ),
   status: exportStatusSchema,
-  createdAt: z.string().describe("Export creation timestamp in ISO-8601 UTC format.")
+  createdAt: z2.string().describe("Export creation timestamp in ISO-8601 UTC format.")
 }).describe("Single export record from PrimeUI export history.");
-var fileTransferSchema = z.object({
-  sourcePath: z.string().describe("Relative source file path inside downloaded export root."),
-  targetPath: z.string().describe("Relative target file path inside user project root.")
+var fileTransferSchema = z2.object({
+  sourcePath: z2.string().describe("Relative source file path inside downloaded export root."),
+  targetPath: z2.string().describe("Relative target file path inside user project root.")
 });
 var conflictFileSchema = fileTransferSchema.extend({
-  diff: z.string().describe(
+  diff: z2.string().describe(
     "Unified diff between user file and export file. For binary files the diff contains a plain message."
   ),
-  isBinary: z.boolean().describe("True if conflict comparison was treated as binary data.")
+  isBinary: z2.boolean().describe("True if conflict comparison was treated as binary data.")
 });
-var dependencySectionSchema = z.enum([
+var dependencySectionSchema = z2.enum([
   "dependencies",
   "devDependencies",
   "peerDependencies"
 ]);
-var dependencyToAddSchema = z.object({
-  packageName: z.string().describe("Dependency package name that was missing in user package.json."),
-  version: z.string().describe("Version from exported project's package.json."),
+var dependencyToAddSchema = z2.object({
+  packageName: z2.string().describe("Dependency package name that was missing in user package.json."),
+  version: z2.string().describe("Version from exported project's package.json."),
   section: dependencySectionSchema.describe(
     "package.json section where dependency should be added."
   )
 });
-var dependencyVersionConflictSchema = z.object({
-  packageName: z.string().describe("Dependency package name with version mismatch."),
+var dependencyVersionConflictSchema = z2.object({
+  packageName: z2.string().describe("Dependency package name with version mismatch."),
   section: dependencySectionSchema.describe(
     "Section where export expects this dependency."
   ),
-  exportVersion: z.string().describe("Version found in exported project's package.json."),
-  userVersion: z.string().describe("Version currently present in user's package.json.")
+  exportVersion: z2.string().describe("Version found in exported project's package.json."),
+  userVersion: z2.string().describe("Version currently present in user's package.json.")
+});
+var pageDetailsSchema = pageSchema.extend({
+  pageInstruction: z2.string().nullable().describe(
+    "Current instruction text for the active page variant. Null when no active variant is set."
+  )
+});
+var pageVariantSchema = z2.object({
+  id: z2.string().describe("Active variant identifier."),
+  name: z2.string().describe("Active variant display name.")
+}).nullable().describe(
+  "Active page variant. Null when page has no active variant and components are unavailable."
+);
+var pageComponentSchema = z2.object({
+  blockId: z2.string().describe("Stable block identifier. Use as primary component instance ID."),
+  componentId: z2.string().describe("Component key from variant blocks payload (block.key)."),
+  componentGroup: z2.string().describe("Component family/group normalized from component key."),
+  slot: z2.string().nullable().describe("Optional slot value from block payload."),
+  props: z2.record(z2.unknown()).nullable().describe("Raw block props payload from PrimeUI.")
+});
+var inspectPageReportRowSchema = z2.object({
+  number: z2.number().describe("1-based row number matching report order."),
+  componentGroup: z2.string().describe("Component family/group label."),
+  componentId: z2.string().describe("Component key (block key)."),
+  blockId: z2.string().describe("Primary component instance identifier for future operations."),
+  title: z2.string().nullable().describe("Title extracted by MCP from component props."),
+  description: z2.string().nullable().describe("Description extracted by MCP from component props.")
 });
 var TRIGGER_PHRASES = [
   "import page from PrimeUI",
@@ -87,11 +217,12 @@ var WORKFLOW_SUMMARY = `
 WORKFLOW ORDER (always follow this sequence):
 1. primeui_get_project_info -> discover PrimeUI pages
 2. Reconcile PrimeUI pages with local project pages/routes/paths, then confirm target pages with user
-3. primeui_create_export -> generate export snapshot for agreed pages/analysis scope
-4. primeui_download_export -> download to temp directory
-5. primeui_copy_page -> copy one page safely (repeat for each selected page)
-6. Reconcile integration points and resolve reported conflicts, if any
-7. primeui_clear_temp -> cleanup temp files
+3. primeui_inspect_page -> inspect selected page components and produce a structured comparison table
+4. primeui_create_export -> generate export snapshot for agreed pages/analysis scope
+5. primeui_download_export -> download to temp directory
+6. primeui_copy_page -> copy one page safely (repeat for each selected page)
+7. Reconcile integration points and resolve reported conflicts, if any
+8. primeui_clear_temp -> cleanup temp files
 `.trim();
 var initialInstructions = `
 PrimeUI MCP enables importing pages from PrimeUI Studio into your local project.
@@ -109,6 +240,9 @@ CRITICAL RULES FOR PAGE IMPORT:
   - PrimeUI exists, local missing -> import candidate.
   - Local exists, PrimeUI missing -> custom local page, no action unless user asks.
   - Both exist but path mismatch -> ambiguous, export + compare before deciding.
+- For targeted component-level analysis on a specific page, call primeui_inspect_page before export/copy.
+- After primeui_inspect_page returns report table, supplement that table with local project page state:
+  mark what already exists, what is missing, and what differs.
 - Before creating export, ask user which pages to add/update (specific pages or all missing pages) and keep that choice in thread context.
 - The downloaded export in .primeui/temp/ contains a full standalone Next.js project.
   Do NOT copy it wholesale.
@@ -145,16 +279,16 @@ AFTER CALLING:
 ${WORKFLOW_SUMMARY}`,
   inputSchema: {},
   outputSchema: {
-    projectId: z.string().describe(
+    projectId: z2.string().describe(
       "PrimeUI project identifier associated with the API key and current import session context."
     ),
-    projectName: z.string().describe(
+    projectName: z2.string().describe(
       "Human-readable PrimeUI project name for confirmations in chat."
     ),
-    metadata: z.record(z.unknown()).describe(
+    metadata: z2.record(z2.unknown()).describe(
       "Additional project metadata from PrimeUI. May include project-description and other context fields."
     ),
-    pages: z.array(pageSchema).describe(
+    pages: z2.array(pageSchema).describe(
       "All pages visible for this project context. Filter by user request and isReadyToExport before creating export."
     )
   },
@@ -165,6 +299,51 @@ ${WORKFLOW_SUMMARY}`,
     openWorldHint: true
   }
 };
+var toolInspectPage = {
+  title: "PrimeUI Inspect Page",
+  description: `Targeted inspection tool for one PrimeUI page. Returns page details, active variant (if present), raw components payload, and a formatted report table.
+
+WHEN TO USE:
+- Call this after primeui_get_project_info when user wants component-level analysis for a specific page.
+- Use this before export/copy when user asks to compare or selectively update page sections.
+
+AFTER CALLING:
+- Use report + reportRows to present the component table:
+  Number (1-based), ComponentGroup (ComponentId), Title/Description, blockId.
+- Then supplement this table with the CURRENT local project page state:
+  what already exists, what is missing, and what differs.
+- Do not assume componentId is unique. Use blockId as the primary component instance identifier.
+
+If page has no active variant, components is null (not empty array), and report explains why.
+
+${WORKFLOW_SUMMARY}`,
+  inputSchema: {
+    pageSlug: z2.string().describe(
+      "PrimeUI page slug to inspect, for example '/', '/pricing', '/docs/getting-started'."
+    )
+  },
+  outputSchema: {
+    page: pageDetailsSchema.describe(
+      "Single PrimeUI page details resolved by slug with pageInstruction."
+    ),
+    variant: pageVariantSchema,
+    components: z2.array(pageComponentSchema).nullable().describe(
+      "Raw component instances from active variant. Null when page has no active variant."
+    ),
+    report: z2.string().describe(
+      "Formatted report table generated by MCP from component payload (includes extracted title/description summary)."
+    ),
+    reportRows: z2.array(inspectPageReportRowSchema).describe(
+      "Structured report rows with 1-based numbering and extracted title/description fields."
+    )
+  },
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true
+  }
+};
 var toolListExports = {
   title: "PrimeUI Export List",
   description: `Auxiliary tool to list previously created exports with their IDs, statuses, and creation dates. This is NOT the starting point for page import - start with primeui_get_project_info instead.
@@ -181,7 +360,7 @@ Do NOT use this tool as a substitute for primeui_create_export. Always create a
 ${WORKFLOW_SUMMARY}`,
   inputSchema: {},
   outputSchema: {
-    exports: z.array(exportItemSchema).describe(
+    exports: z2.array(exportItemSchema).describe(
       "Available exports sorted by API policy. Use item.id to download a specific prior export if user asks."
     )
   },
@@ -207,13 +386,13 @@ AFTER CALLING:
 ${WORKFLOW_SUMMARY}`,
   inputSchema: {},
   outputSchema: {
-    export: z.object({
-      id: z.string().describe(
+    export: z2.object({
+      id: z2.string().describe(
         "Freshly created export identifier. Use this as primeui_download_export input.id."
       ),
       status: exportStatusSchema
     }).describe("Created export summary."),
-    pages: z.array(pageSchema).describe(
+    pages: z2.array(pageSchema).describe(
       "Page snapshot associated with this export operation. Validate requested pages here before download/import."
     )
   },
@@ -246,21 +425,21 @@ AFTER DOWNLOAD:
 
   ${WORKFLOW_SUMMARY}`,
   inputSchema: {
-    id: z.string().describe(
+    id: z2.string().describe(
       "Export identifier to download. Prefer export.id from primeui_create_export; use primeui_list_exports only on explicit user request."
     )
   },
   outputSchema: {
-    exportId: z.string().describe(
+    exportId: z2.string().describe(
       "Downloaded export identifier. Should match the requested input.id for traceability."
     ),
-    projectPath: z.string().describe(
+    projectPath: z2.string().describe(
       "Absolute local path to extracted export root in .primeui/temp/exports/[exportId]. Read files from here only."
     ),
-    manifestPath: z.string().describe(
+    manifestPath: z2.string().describe(
       "Absolute path to sidecar export manifest file (.primeui/temp/exports/[exportId].manifest.json). primeui_copy_page depends on this file."
     ),
-    pages: z.array(pageSchema).describe(
+    pages: z2.array(pageSchema).describe(
       "Page descriptors for import decisions. Use pagePath/componentsPath from each item when copying code into user project."
     )
   },
@@ -295,44 +474,44 @@ BEHAVIOR:
 
 ${WORKFLOW_SUMMARY}`,
   inputSchema: {
-    originPageSlug: z.string().describe(
+    originPageSlug: z2.string().describe(
       "Source page slug from PrimeUI project pages list, for example '/', '/pricing', '/docs'."
     ),
-    actualPageSlug: z.string().optional().describe(
+    actualPageSlug: z2.string().optional().describe(
       "Optional destination slug in user's project. If omitted, originPageSlug is used."
     )
   },
   outputSchema: {
-    exportId: z.string().describe("Resolved local export identifier used for copy operation."),
-    exportPath: z.string().describe("Absolute path to local extracted export project root."),
-    originPageSlug: z.string().describe("Normalized source page slug requested for copy."),
-    actualPageSlug: z.string().describe("Normalized destination slug used for target route paths."),
-    sourcePagePath: z.string().describe("Source page path relative to export root."),
-    targetPagePath: z.string().describe("Destination page path relative to user project root."),
-    sourceComponentsPath: z.string().describe("Source components directory relative to export root."),
-    targetComponentsPath: z.string().describe(
+    exportId: z2.string().describe("Resolved local export identifier used for copy operation."),
+    exportPath: z2.string().describe("Absolute path to local extracted export project root."),
+    originPageSlug: z2.string().describe("Normalized source page slug requested for copy."),
+    actualPageSlug: z2.string().describe("Normalized destination slug used for target route paths."),
+    sourcePagePath: z2.string().describe("Source page path relative to export root."),
+    targetPagePath: z2.string().describe("Destination page path relative to user project root."),
+    sourceComponentsPath: z2.string().describe("Source components directory relative to export root."),
+    targetComponentsPath: z2.string().describe(
       "Destination components directory relative to user project root."
     ),
-    newFiles: z.array(fileTransferSchema).describe("New files copied into user project without conflicts."),
-    identicalFiles: z.array(fileTransferSchema).describe(
+    newFiles: z2.array(fileTransferSchema).describe("New files copied into user project without conflicts."),
+    identicalFiles: z2.array(fileTransferSchema).describe(
       "Existing files in user project that are byte-identical to export files."
     ),
-    conflictFiles: z.array(conflictFileSchema).describe(
+    conflictFiles: z2.array(conflictFileSchema).describe(
       "Files that already exist and differ from export version. Never overwritten."
     ),
-    addedDependencies: z.array(dependencyToAddSchema).describe(
+    addedDependencies: z2.array(dependencyToAddSchema).describe(
       "Dependencies that were missing and have been added to user's package.json."
     ),
-    dependenciesVersionConflicts: z.array(dependencyVersionConflictSchema).describe(
+    dependenciesVersionConflicts: z2.array(dependencyVersionConflictSchema).describe(
       "Dependencies with version mismatch between export and user project. Report only."
     ),
-    summary: z.object({
-      totalCandidateFiles: z.number().describe("Total number of candidate files considered for page copy."),
-      copiedFiles: z.number().describe("Number of files copied as new."),
-      identicalFiles: z.number().describe("Number of files detected as identical."),
-      conflictFiles: z.number().describe("Number of conflicting files not copied."),
-      addedDependencies: z.number().describe("Count of dependencies added to package.json."),
-      dependenciesVersionConflicts: z.number().describe("Count of dependency version mismatches reported.")
+    summary: z2.object({
+      totalCandidateFiles: z2.number().describe("Total number of candidate files considered for page copy."),
+      copiedFiles: z2.number().describe("Number of files copied as new."),
+      identicalFiles: z2.number().describe("Number of files detected as identical."),
+      conflictFiles: z2.number().describe("Number of conflicting files not copied."),
+      addedDependencies: z2.number().describe("Count of dependencies added to package.json."),
+      dependenciesVersionConflicts: z2.number().describe("Count of dependency version mismatches reported.")
     })
   },
   annotations: {
@@ -355,7 +534,7 @@ Safe to call multiple times. Only affects .primeui/temp/ directory - never touch
 ${WORKFLOW_SUMMARY}`,
   inputSchema: {},
   outputSchema: {
-    success: z.boolean().describe(
+    success: z2.boolean().describe(
       "True when temp cleanup completed and baseline temp structure was recreated."
     )
   },
@@ -403,6 +582,18 @@ function createPrimeUiMcpServer(source) {
       }
     }
   );
+  server.registerTool(
+    "primeui_inspect_page",
+    toolInspectPage,
+    async ({ pageSlug }) => {
+      try {
+        const result = await source.inspectPage(pageSlug);
+        return okResult("primeui_inspect_page", result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
   server.registerTool(
     "primeui_list_exports",
     toolListExports,
@@ -470,12 +661,12 @@ function createPrimeUiMcpServer(source) {
 }
 
 // src/services/project-sync-service.ts
-import path4 from "path";
-import { readFile as readFile3 } from "fs/promises";
+import path5 from "path";
+import { readFile as readFile4 } from "fs/promises";
 
 // src/lib/fs.ts
 import { mkdir, rm, writeFile } from "fs/promises";
-import path from "path";
+import path2 from "path";
 import extractZipArchive from "extract-zip";
 async function ensureDir(dirPath) {
   await mkdir(dirPath, { recursive: true });
@@ -485,7 +676,7 @@ async function resetDir(dirPath) {
   await mkdir(dirPath, { recursive: true });
 }
 async function writeUtf8(filePath, content) {
-  await ensureDir(path.dirname(filePath));
+  await ensureDir(path2.dirname(filePath));
   await writeFile(filePath, content, "utf-8");
 }
 async function extractZip(zipPath, targetDir) {
@@ -499,13 +690,13 @@ async function extractZip(zipPath, targetDir) {
 }
 
 // src/services/page-copy-service.ts
-import { readFile as readFile2, readdir, stat as stat2, writeFile as writeFile2 } from "fs/promises";
-import path3 from "path";
+import { readFile as readFile3, readdir, stat as stat3, writeFile as writeFile2 } from "fs/promises";
+import path4 from "path";
 
 // src/lib/import-graph.ts
-import { readFile, stat } from "fs/promises";
+import { readFile as readFile2, stat as stat2 } from "fs/promises";
 import { builtinModules } from "module";
-import path2 from "path";
+import path3 from "path";
 var INTERNAL_EXTENSIONS = [
   ".ts",
   ".tsx",
@@ -574,14 +765,14 @@ function getExternalPackageName(specifier) {
 }
 async function pathExists(filePath) {
   try {
-    await stat(filePath);
+    await stat2(filePath);
     return true;
   } catch {
     return false;
   }
 }
 async function resolveFileCandidate(candidateBase) {
-  const ext = path2.extname(candidateBase);
+  const ext = path3.extname(candidateBase);
   if (ext) {
     if (await pathExists(candidateBase)) {
       return candidateBase;
@@ -595,13 +786,13 @@ async function resolveFileCandidate(candidateBase) {
     }
   }
   if (await pathExists(candidateBase)) {
-    const stats = await stat(candidateBase);
+    const stats = await stat2(candidateBase);
     if (stats.isFile()) {
       return candidateBase;
     }
     if (stats.isDirectory()) {
       for (const extension of INTERNAL_EXTENSIONS) {
-        const indexCandidate = path2.join(candidateBase, `index${extension}`);
+        const indexCandidate = path3.join(candidateBase, `index${extension}`);
         if (await pathExists(indexCandidate)) {
           return indexCandidate;
         }
@@ -623,13 +814,13 @@ async function resolveImportToFile(projectRoot, importerFilePath, specifier) {
   }
   let candidateBase = null;
   if (specifier.startsWith("@/")) {
-    candidateBase = path2.join(projectRoot, "src", specifier.slice(2));
+    candidateBase = path3.join(projectRoot, "src", specifier.slice(2));
   } else if (specifier.startsWith("@root/")) {
-    candidateBase = path2.join(projectRoot, specifier.slice(6));
+    candidateBase = path3.join(projectRoot, specifier.slice(6));
   } else if (specifier.startsWith(".")) {
-    candidateBase = path2.resolve(path2.dirname(importerFilePath), specifier);
+    candidateBase = path3.resolve(path3.dirname(importerFilePath), specifier);
   } else if (specifier.startsWith("/")) {
-    candidateBase = path2.join(projectRoot, specifier.slice(1));
+    candidateBase = path3.join(projectRoot, specifier.slice(1));
   } else {
     return { kind: "unknown" };
   }
@@ -643,11 +834,11 @@ async function resolveImportToFile(projectRoot, importerFilePath, specifier) {
   };
 }
 function shouldParseFile(filePath) {
-  return PARSEABLE_EXTENSIONS.has(path2.extname(filePath).toLowerCase());
+  return PARSEABLE_EXTENSIONS.has(path3.extname(filePath).toLowerCase());
 }
 async function buildImportGraph(input) {
-  const projectRoot = path2.resolve(input.projectRoot);
-  const queue = input.entryFiles.map((filePath) => path2.resolve(filePath));
+  const projectRoot = path3.resolve(input.projectRoot);
+  const queue = input.entryFiles.map((filePath) => path3.resolve(filePath));
   const visited = /* @__PURE__ */ new Set();
   const internalFiles = /* @__PURE__ */ new Set();
   const externalPackages = /* @__PURE__ */ new Set();
@@ -663,7 +854,7 @@ async function buildImportGraph(input) {
     }
     let content = "";
     try {
-      content = await readFile(currentFilePath, "utf-8");
+      content = await readFile2(currentFilePath, "utf-8");
     } catch {
       continue;
     }
@@ -900,10 +1091,10 @@ function normalizeSlug2(slug) {
   return withLeadingSlash.replace(/\/+$/, "") || "/";
 }
 function toPosixPath(value) {
-  return value.split(path3.sep).join("/");
+  return value.split(path4.sep).join("/");
 }
 function toProjectRelative(rootPath, absolutePath) {
-  return toPosixPath(path3.relative(rootPath, absolutePath));
+  return toPosixPath(path4.relative(rootPath, absolutePath));
 }
 function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -960,7 +1151,7 @@ function buildPlannedSourceBuffer(sourceBuffer, sourceFilePath, importRewritePla
   if (!importRewritePlan) {
     return sourceBuffer;
   }
-  const extension = path3.extname(sourceFilePath).toLowerCase();
+  const extension = path4.extname(sourceFilePath).toLowerCase();
   if (!REWRITABLE_IMPORT_EXTENSIONS.has(extension)) {
     return sourceBuffer;
   }
@@ -968,19 +1159,22 @@ function buildPlannedSourceBuffer(sourceBuffer, sourceFilePath, importRewritePla
     return sourceBuffer;
   }
   const sourceText = sourceBuffer.toString("utf-8");
-  const rewritten = rewriteImportsForRemappedSlug(sourceText, importRewritePlan);
+  const rewritten = rewriteImportsForRemappedSlug(
+    sourceText,
+    importRewritePlan
+  );
   if (rewritten === sourceText) {
     return sourceBuffer;
   }
   return Buffer.from(rewritten, "utf-8");
 }
 async function readJsonFile(filePath) {
-  const content = await readFile2(filePath, "utf-8");
+  const content = await readFile3(filePath, "utf-8");
   return JSON.parse(content);
 }
-async function fileExists(filePath) {
+async function fileExists2(filePath) {
   try {
-    await stat2(filePath);
+    await stat3(filePath);
     return true;
   } catch {
     return false;
@@ -1022,7 +1216,7 @@ async function listFilesRecursively(dirPath) {
     }
     const entries = await readdir(current, { withFileTypes: true });
     for (const entry of entries) {
-      const absolutePath = path3.join(current, entry.name);
+      const absolutePath = path4.join(current, entry.name);
       if (entry.isDirectory()) {
         stack.push(absolutePath);
         continue;
@@ -1050,12 +1244,12 @@ async function resolveSingleExportDirectory(exportsRoot) {
   const exportId = exportDirectories[0] ?? "";
   return {
     exportId,
-    exportPath: path3.join(exportsRoot, exportId)
+    exportPath: path4.join(exportsRoot, exportId)
   };
 }
 function ensureSafeTargetPath(projectRoot, targetPath) {
-  const relative = path3.relative(projectRoot, targetPath);
-  if (relative.startsWith("..") || path3.isAbsolute(relative)) {
+  const relative = path4.relative(projectRoot, targetPath);
+  if (relative.startsWith("..") || path4.isAbsolute(relative)) {
     throw new Error(
       `Refusing to write outside project root. Computed target: ${targetPath}`
     );
@@ -1113,19 +1307,19 @@ function resolveTargetFilePath(input) {
   if (sourceFilePath === sourcePagePath) {
     return targetPagePath;
   }
-  const componentsPrefix = `${sourceComponentsPath}${path3.sep}`;
+  const componentsPrefix = `${sourceComponentsPath}${path4.sep}`;
   if (sourceFilePath === sourceComponentsPath || sourceFilePath.startsWith(componentsPrefix)) {
-    const relativeToComponents = path3.relative(
+    const relativeToComponents = path4.relative(
       sourceComponentsPath,
       sourceFilePath
     );
-    return path3.join(targetComponentsPath, relativeToComponents);
+    return path4.join(targetComponentsPath, relativeToComponents);
   }
-  const relativeToExport = path3.relative(exportRoot, sourceFilePath);
-  if (relativeToExport.startsWith("..") || path3.isAbsolute(relativeToExport)) {
+  const relativeToExport = path4.relative(exportRoot, sourceFilePath);
+  if (relativeToExport.startsWith("..") || path4.isAbsolute(relativeToExport)) {
     throw new Error(`Source file is outside export root: ${sourceFilePath}`);
   }
-  return path3.join(projectRoot, relativeToExport);
+  return path4.join(projectRoot, relativeToExport);
 }
 async function copyPageFromExport(input) {
   const normalizedOriginSlug = normalizeSlug2(input.originPageSlug);
@@ -1136,11 +1330,11 @@ async function copyPageFromExport(input) {
   const { exportId, exportPath } = await resolveSingleExportDirectory(
     input.exportsRoot
   );
-  const manifestPath = path3.join(
+  const manifestPath = path4.join(
     input.exportsRoot,
     `${exportId}.manifest.json`
   );
-  if (!await fileExists(manifestPath)) {
+  if (!await fileExists2(manifestPath)) {
     throw new Error(
       `Export manifest is missing at ${manifestPath}. Run primeui_download_export to regenerate it.`
     );
@@ -1159,13 +1353,13 @@ async function copyPageFromExport(input) {
       `Page not found in manifest for slug: ${normalizedOriginSlug}`
     );
   }
-  const sourcePagePath = path3.join(exportPath, page.pagePath);
-  const sourceComponentsPath = path3.join(exportPath, page.componentsPath);
-  const sourcePageStats = await stat2(sourcePagePath).catch(() => null);
+  const sourcePagePath = path4.join(exportPath, page.pagePath);
+  const sourceComponentsPath = path4.join(exportPath, page.componentsPath);
+  const sourcePageStats = await stat3(sourcePagePath).catch(() => null);
   if (!sourcePageStats?.isFile()) {
     throw new Error(`Source page file not found: ${sourcePagePath}`);
   }
-  const sourceComponentsStats = await stat2(sourceComponentsPath).catch(
+  const sourceComponentsStats = await stat3(sourceComponentsPath).catch(
     () => null
   );
   if (!sourceComponentsStats?.isDirectory()) {
@@ -1180,8 +1374,8 @@ async function copyPageFromExport(input) {
     pageType: page.pageType,
     slug: normalizedActualSlug
   });
-  const targetPagePath = path3.join(input.projectRoot, targetPaths.pagePath);
-  const targetComponentsPath = path3.join(
+  const targetPagePath = path4.join(input.projectRoot, targetPaths.pagePath);
+  const targetComponentsPath = path4.join(
     input.projectRoot,
     targetPaths.componentsPath
   );
@@ -1211,7 +1405,7 @@ async function copyPageFromExport(input) {
       projectRoot: input.projectRoot
     });
     ensureSafeTargetPath(input.projectRoot, targetFilePath);
-    const sourceBuffer = await readFile2(sourceFilePath);
+    const sourceBuffer = await readFile3(sourceFilePath);
     const plannedSourceBuffer = buildPlannedSourceBuffer(
       sourceBuffer,
       sourceFilePath,
@@ -1219,14 +1413,14 @@ async function copyPageFromExport(input) {
     );
     let targetBuffer = null;
     try {
-      targetBuffer = await readFile2(targetFilePath);
+      targetBuffer = await readFile3(targetFilePath);
     } catch {
       targetBuffer = null;
     }
     const sourceRelative = toProjectRelative(exportPath, sourceFilePath);
     const targetRelative = toProjectRelative(input.projectRoot, targetFilePath);
     if (!targetBuffer) {
-      await ensureDir(path3.dirname(targetFilePath));
+      await ensureDir(path4.dirname(targetFilePath));
       await writeFile2(targetFilePath, plannedSourceBuffer);
       newFiles.push({
         sourcePath: sourceRelative,
@@ -1255,12 +1449,12 @@ async function copyPageFromExport(input) {
       isBinary
     });
   }
-  const exportPackageJsonPath = path3.join(exportPath, "package.json");
-  const userPackageJsonPath = path3.join(input.projectRoot, "package.json");
-  if (!await fileExists(exportPackageJsonPath)) {
+  const exportPackageJsonPath = path4.join(exportPath, "package.json");
+  const userPackageJsonPath = path4.join(input.projectRoot, "package.json");
+  if (!await fileExists2(exportPackageJsonPath)) {
     throw new Error(`Export package.json not found: ${exportPackageJsonPath}`);
   }
-  if (!await fileExists(userPackageJsonPath)) {
+  if (!await fileExists2(userPackageJsonPath)) {
     throw new Error(`User package.json not found: ${userPackageJsonPath}`);
   }
   const exportPackageJson = await readJsonFile(
@@ -1338,6 +1532,96 @@ async function copyPageFromExport(input) {
   };
 }
 
+// src/services/page-inspect-report.ts
+function normalizeTextValue(value) {
+  if (typeof value !== "string") {
+    return null;
+  }
+  const trimmed = value.trim();
+  return trimmed ? trimmed : null;
+}
+function extractFirstStringByKey(value, key, seen) {
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+  if (seen.has(value)) {
+    return null;
+  }
+  seen.add(value);
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      const nested = extractFirstStringByKey(item, key, seen);
+      if (nested) {
+        return nested;
+      }
+    }
+    return null;
+  }
+  const record = value;
+  for (const [recordKey, recordValue] of Object.entries(record)) {
+    if (recordKey.toLowerCase() === key) {
+      const normalized = normalizeTextValue(recordValue);
+      if (normalized) {
+        return normalized;
+      }
+    }
+  }
+  for (const nestedValue of Object.values(record)) {
+    const nested = extractFirstStringByKey(nestedValue, key, seen);
+    if (nested) {
+      return nested;
+    }
+  }
+  return null;
+}
+function extractTitleAndDescription(props) {
+  if (!props) {
+    return {
+      title: null,
+      description: null
+    };
+  }
+  return {
+    title: extractFirstStringByKey(props, "title", /* @__PURE__ */ new Set()),
+    description: extractFirstStringByKey(props, "description", /* @__PURE__ */ new Set())
+  };
+}
+function resolveSummaryText(row) {
+  return row.title ?? row.description ?? "";
+}
+function buildInspectPageReport(input) {
+  if (input.components === null) {
+    return {
+      report: "Components are unavailable for this page because no active variant is set (isReadyToExport=false).",
+      reportRows: []
+    };
+  }
+  if (input.components.length === 0) {
+    return {
+      report: "Active variant has no components.",
+      reportRows: []
+    };
+  }
+  const reportRows = input.components.map((component, index) => {
+    const titleDescription = extractTitleAndDescription(component.props);
+    return {
+      number: index + 1,
+      componentGroup: component.componentGroup,
+      componentId: component.componentId,
+      blockId: component.blockId,
+      title: titleDescription.title,
+      description: titleDescription.description
+    };
+  });
+  const report = reportRows.map(
+    (row) => `${row.number}. ${row.componentGroup} (${row.componentId}) | ${resolveSummaryText(row)} | ${row.blockId}`
+  ).join("\n");
+  return {
+    report,
+    reportRows
+  };
+}
+
 // src/services/project-sync-service.ts
 function isProjectPage(value) {
   if (!value || typeof value !== "object") {
@@ -1347,7 +1631,7 @@ function isProjectPage(value) {
   return typeof maybe.id === "string" && typeof maybe.title === "string" && typeof maybe.slug === "string" && typeof maybe.pageType === "string" && typeof maybe.isReadyToExport === "boolean" && typeof maybe.pagePath === "string" && typeof maybe.componentsPath === "string";
 }
 function buildPagesSnapshotPath(exportsRoot, exportId) {
-  return path4.join(exportsRoot, `${exportId}.pages.snapshot.json`);
+  return path5.join(exportsRoot, `${exportId}.pages.snapshot.json`);
 }
 function parsePagesSnapshot(value) {
   if (!value || typeof value !== "object") {
@@ -1370,15 +1654,17 @@ function parsePagesSnapshot(value) {
 var ProjectSyncService = class {
   provider;
   projectRoot;
+  targetProjectRoot;
   primeUiRoot;
   tempRoot;
   exportsRoot;
   constructor(options) {
     this.projectRoot = options.projectRoot;
+    this.targetProjectRoot = options.targetProjectRoot;
     this.provider = options.provider;
-    this.primeUiRoot = path4.join(this.projectRoot, ".primeui");
-    this.tempRoot = path4.join(this.primeUiRoot, "temp");
-    this.exportsRoot = path4.join(this.tempRoot, "exports");
+    this.primeUiRoot = path5.join(this.projectRoot, ".primeui");
+    this.tempRoot = path5.join(this.primeUiRoot, "temp");
+    this.exportsRoot = path5.join(this.tempRoot, "exports");
   }
   async getProjectInfo() {
     await this.ensureTempLayout();
@@ -1415,8 +1701,8 @@ var ProjectSyncService = class {
     if (!selected) {
       throw new Error(`Export not found: ${id}`);
     }
-    const targetZipPath = path4.join(this.exportsRoot, `${id}.zip`);
-    const targetProjectPath = path4.join(this.exportsRoot, id);
+    const targetZipPath = path5.join(this.exportsRoot, `${id}.zip`);
+    const targetProjectPath = path5.join(this.exportsRoot, id);
     await ensureDir(this.exportsRoot);
     await this.provider.downloadExportArchive(id, targetZipPath);
     await resetDir(targetProjectPath);
@@ -1425,7 +1711,7 @@ var ProjectSyncService = class {
     let pagesSnapshot;
     try {
       const snapshotRaw = JSON.parse(
-        await readFile3(pagesSnapshotPath, "utf-8")
+        await readFile4(pagesSnapshotPath, "utf-8")
       );
       pagesSnapshot = parsePagesSnapshot(snapshotRaw);
     } catch (error) {
@@ -1440,7 +1726,7 @@ var ProjectSyncService = class {
       );
     }
     const pages = pagesSnapshot.pages;
-    const manifestPath = path4.join(this.exportsRoot, `${id}.manifest.json`);
+    const manifestPath = path5.join(this.exportsRoot, `${id}.manifest.json`);
     const manifest = {
       schemaVersion: 1,
       generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -1457,10 +1743,20 @@ var ProjectSyncService = class {
       pages
     };
   }
+  async inspectPage(slug) {
+    await this.ensureTempLayout();
+    const pageDetails = await this.provider.getProjectPageBySlug(slug);
+    const reportPayload = buildInspectPageReport(pageDetails);
+    return {
+      ...pageDetails,
+      report: reportPayload.report,
+      reportRows: reportPayload.reportRows
+    };
+  }
   async copyPage(originPageSlug, actualPageSlug) {
     await this.ensureTempLayout();
     return copyPageFromExport({
-      projectRoot: this.projectRoot,
+      projectRoot: this.targetProjectRoot,
       exportsRoot: this.exportsRoot,
       originPageSlug,
       actualPageSlug
@@ -1468,61 +1764,79 @@ var ProjectSyncService = class {
   }
   async clearTemp() {
     await resetDir(this.tempRoot);
-    await writeUtf8(path4.join(this.tempRoot, ".gitkeep"), "");
+    await writeUtf8(path5.join(this.tempRoot, ".gitkeep"), "");
     await ensureDir(this.exportsRoot);
   }
   async ensureTempLayout() {
     await ensureDir(this.primeUiRoot);
     await ensureDir(this.tempRoot);
     await ensureDir(this.exportsRoot);
-    await writeUtf8(path4.join(this.tempRoot, ".gitkeep"), "");
+    await writeUtf8(path5.join(this.tempRoot, ".gitkeep"), "");
   }
 };
 
 // src/sources/api-provider.ts
 import { createWriteStream } from "fs";
 import { unlink } from "fs/promises";
-import path5 from "path";
+import path6 from "path";
 import { Readable, Transform } from "stream";
 import { pipeline } from "stream/promises";
-import { z as z2 } from "zod";
+import { z as z3 } from "zod";
 var DEFAULT_API_BASE_URL = "https://app.primeui.com/";
 var ZIP_CONTENT_TYPES = [
   "application/zip",
   "application/octet-stream",
   "application/x-zip-compressed"
 ];
-var exportStatusSchema2 = z2.enum(["in_progress", "completed", "failed"]);
-var projectPageSchema = z2.object({
-  id: z2.string(),
-  title: z2.string(),
-  slug: z2.string(),
-  pageType: z2.string(),
-  isReadyToExport: z2.boolean(),
-  pagePath: z2.string(),
-  componentsPath: z2.string()
+var exportStatusSchema2 = z3.enum(["in_progress", "completed", "failed"]);
+var projectPageObjectSchema = z3.object({
+  id: z3.string(),
+  title: z3.string(),
+  slug: z3.string(),
+  pageType: z3.string(),
+  isReadyToExport: z3.boolean(),
+  pagePath: z3.string(),
+  componentsPath: z3.string()
+});
+var projectPageSchema = projectPageObjectSchema;
+var projectInfoSchema = z3.object({
+  projectId: z3.string(),
+  projectName: z3.string(),
+  metadata: z3.record(z3.unknown()),
+  pages: z3.array(projectPageSchema)
 });
-var projectInfoSchema = z2.object({
-  projectId: z2.string(),
-  projectName: z2.string(),
-  metadata: z2.record(z2.unknown()),
-  pages: z2.array(projectPageSchema)
+var projectPageComponentSchema = z3.object({
+  blockId: z3.string(),
+  componentId: z3.string(),
+  componentGroup: z3.string(),
+  slot: z3.string().nullable(),
+  props: z3.record(z3.unknown()).nullable()
+});
+var projectPageDetailsSchema = z3.object({
+  page: projectPageObjectSchema.extend({
+    pageInstruction: z3.string().nullable()
+  }),
+  variant: z3.object({
+    id: z3.string(),
+    name: z3.string()
+  }).nullable(),
+  components: z3.array(projectPageComponentSchema).nullable()
 });
-var exportsResponseSchema = z2.object({
-  exports: z2.array(
-    z2.object({
-      id: z2.string(),
+var exportsResponseSchema = z3.object({
+  exports: z3.array(
+    z3.object({
+      id: z3.string(),
       status: exportStatusSchema2,
-      createdAt: z2.string().datetime({ offset: true })
+      createdAt: z3.string().datetime({ offset: true })
     })
   )
 });
-var createExportResponseSchema = z2.object({
-  export: z2.object({
-    id: z2.string(),
+var createExportResponseSchema = z3.object({
+  export: z3.object({
+    id: z3.string(),
     status: exportStatusSchema2
   }),
-  pages: z2.array(projectPageSchema)
+  pages: z3.array(projectPageSchema)
 });
 var PrimeUiApiContractError = class extends Error {
   constructor(endpoint, details) {
@@ -1609,6 +1923,13 @@ var ApiProjectDataProvider = class {
   async getProjectInfo() {
     return this.requestJson("project", projectInfoSchema);
   }
+  async getProjectPageBySlug(slug) {
+    const encodedSlug = encodeURIComponent(slug);
+    return this.requestJson(
+      `project/page?slug=${encodedSlug}`,
+      projectPageDetailsSchema
+    );
+  }
   async listExports() {
     const response = await this.requestJson(
       "project/exports",
@@ -1651,7 +1972,7 @@ var ApiProjectDataProvider = class {
     if (!response.body) {
       throw new PrimeUiApiContractError(endpoint, "response body is empty");
     }
-    await ensureDir(path5.dirname(destinationPath));
+    await ensureDir(path6.dirname(destinationPath));
     const zipStream = Readable.fromWeb(
       response.body
     );
@@ -1739,22 +2060,34 @@ var ApiProjectDataProvider = class {
 
 // src/service.ts
 async function main() {
-  const projectRoot = process.env.PRIMEUI_PROJECT_ROOT || process.cwd();
-  const apiKey = process.env.PRIMEUI_API_KEY;
+  const resolvedProjectConfig = await resolvePrimeUiProjectConfig({
+    cwd: process.cwd(),
+    projectRootFromEnv: process.env.PRIMEUI_PROJECT_ROOT
+  });
+  const projectRoot = resolvedProjectConfig.projectRoot;
+  const targetProjectRoot = path7.resolve(
+    projectRoot,
+    resolvedProjectConfig.projectConfig.targetProjectPath
+  );
+  const apiKey = await resolvePrimeUiApiKey({
+    projectConfig: resolvedProjectConfig.projectConfig,
+    apiKeyFromEnv: process.env.PRIMEUI_API_KEY
+  });
   const provider = new ApiProjectDataProvider({
     apiKey,
     baseUrl: process.env.PRIMEUI_API_BASE_URL
   });
-  if (!apiKey) {
-    console.error(
-      "[primeui-mcp] warning: PRIMEUI_API_KEY is not set; API-backed tools will fail until it is configured."
-    );
-  }
-  const syncService = new ProjectSyncService({ projectRoot, provider });
+  const syncService = new ProjectSyncService({
+    projectRoot,
+    targetProjectRoot,
+    provider
+  });
   const server = createPrimeUiMcpServer(syncService);
   const transport = new StdioServerTransport();
   await server.connect(transport);
-  console.error(`[primeui-mcp] running for root: ${projectRoot}`);
+  console.error(
+    `[primeui-mcp] running for root: ${projectRoot}; target project: ${targetProjectRoot}`
+  );
 }
 main().catch((error) => {
   console.error("[primeui-mcp] failed to start", error);