@sentientui/mcp 0.8.1 → 0.9.0

package/dist/{chunk-TLBLOBSB.js → chunk-QESH43WV.js}

@@ -47,7 +47,6 @@ var ApiClient = class {
 };
 
 // src/server.ts
-import { createRequire } from "module";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
 // src/tools/projects.ts
@@ -56,7 +55,10 @@ import { z as z2 } from "zod";
 // src/tools/common.ts
 import { z } from "zod";
 var projectIdSchema = z.string().uuid().describe("The project UUID");
-function apiErrorGuidance(err) {
+function apiErrorGuidance(err, extra) {
+  if (extra && Object.prototype.hasOwnProperty.call(extra, err.message)) {
+    return extra[err.message];
+  }
   switch (err.message) {
     case "insufficient_scope":
       return "This action needs an account login. Connect via the hosted MCP URL (https://api.sentient-ui.com/mcp) and sign in \u2014 a project-scoped server key (sk_\u2026) or anonymous demo token cannot do this.";
@@ -75,13 +77,13 @@ function apiErrorGuidance(err) {
   }
   return null;
 }
-function withApiErrorGuidance(fn) {
+function withApiErrorGuidance(fn, extra) {
   return async (args) => {
     try {
       return await fn(args);
     } catch (err) {
       if (err instanceof ApiError) {
-        const guidance = apiErrorGuidance(err);
+        const guidance = apiErrorGuidance(err, extra);
         if (guidance) {
           return { content: [{ type: "text", text: guidance }], isError: true };
         }
@@ -92,22 +94,10 @@ function withApiErrorGuidance(fn) {
 }
 
 // src/tools/projects.ts
-function createProjectGuidance(err) {
-  switch (err.message) {
-    case "insufficient_scope":
-      return "Creating a project needs an account login. Connect via the hosted MCP URL (https://api.sentient-ui.com/mcp) and sign in \u2014 a project-scoped server key (sk_\u2026) cannot create projects.";
-    case "demo_read_only":
-      return "Demo mode is read-only. Create a SentientUI account and sign in to make projects.";
-    case "insufficient_role":
-      return "Your account role cannot create projects \u2014 this needs the account owner or an admin.";
-    case "project_limit_reached":
-      return "You've reached your plan's project limit. Upgrade your plan or remove an existing project, then try again.";
-    case "name_required":
-      return "A project name is required to create a project.";
-    default:
-      return null;
-  }
-}
+var CREATE_PROJECT_GUIDANCE = {
+  project_limit_reached: "You've reached your plan's project limit. Upgrade your plan or remove an existing project, then try again.",
+  name_required: "A project name is required to create a project."
+};
 function registerProjectTools(server, client) {
   server.registerTool(
     "create_project",
@@ -133,41 +123,31 @@ function registerProjectTools(server, client) {
         openWorldHint: false
       }
     },
-    async ({ name, contextType, framework, websiteUrl }) => {
-      try {
-        const created = await client.post("/projects", {
+    withApiErrorGuidance(async ({ name, contextType, framework, websiteUrl }) => {
+      const created = await client.post("/projects", {
+        name,
+        contextType,
+        framework,
+        origin: websiteUrl
+      });
+      const resolvedContextType = contextType != null ? contextType : "saas";
+      return {
+        content: [{
+          type: "text",
+          text: [
+            `Created project "${name}" (id: ${created.id}, type: ${resolvedContextType}).`,
+            `Public key: ${created.apiKey}`,
+            `Next: install @sentientui/react with this key. Ask me to pull the setup guide (get_integration_guide) and I'll wrap your first component.`
+          ].join("\n")
+        }],
+        structuredContent: {
+          projectId: created.id,
+          publicKey: created.apiKey,
           name,
-          contextType,
-          framework,
-          origin: websiteUrl
-        });
-        const resolvedContextType = contextType != null ? contextType : "saas";
-        return {
-          content: [{
-            type: "text",
-            text: [
-              `Created project "${name}" (id: ${created.id}, type: ${resolvedContextType}).`,
-              `Public key: ${created.apiKey}`,
-              `Next: install @sentientui/react with this key. Ask me to pull the setup guide (get_integration_guide) and I'll wrap your first component.`
-            ].join("\n")
-          }],
-          structuredContent: {
-            projectId: created.id,
-            publicKey: created.apiKey,
-            name,
-            contextType: resolvedContextType
-          }
-        };
-      } catch (err) {
-        if (err instanceof ApiError) {
-          const guidance = createProjectGuidance(err);
-          if (guidance) {
-            return { content: [{ type: "text", text: guidance }], isError: true };
-          }
+          contextType: resolvedContextType
         }
-        throw err;
-      }
-    }
+      };
+    }, CREATE_PROJECT_GUIDANCE)
   );
   server.registerTool(
     "list_projects",
@@ -919,13 +899,16 @@ function registerVariantWriteTools(server, client) {
       description: "Create a NO-CODE managed text variant for a component (content stored in SentientUI, rendered by <AdaptiveText>). Use this ONLY for text-only variants the user wants without a code change. For variants that will live in the codebase (full components \u2014 copy, markup, styling), use get_variant_brief and write the variant in code instead; those auto-register on deploy and do not need create_variant. Requires a paid plan (server keys are Starter+; anonymous demo tokens are read-only).",
       inputSchema: {
         projectId: projectIdSchema,
-        componentId: z9.string().describe("The component ID to add a variant to"),
-        displayName: z9.string().describe("Human-readable name for the new variant"),
-        content: z9.string().optional().describe("The text content for this managed variant (rendered by <AdaptiveText>). Generate it from get_variant_brief context; omit only to create an empty placeholder to fill in from the dashboard.")
+        componentId: z9.string().min(1).max(200).describe("The component ID to add a variant to"),
+        displayName: z9.string().min(1).max(200).describe("Human-readable name for the new variant"),
+        content: z9.string().max(1e4).optional().describe("The text content for this managed variant (rendered by <AdaptiveText>). Generate it from get_variant_brief context; omit only to create an empty placeholder to fill in from the dashboard.")
       },
       outputSchema: {
         variantId: z9.string().describe("The new variant ID"),
-        displayName: z9.string(),
+        // API returns `body.displayName ?? null`, so a successful create can
+        // carry a null name — match that contract or outputSchema validation
+        // would reject an otherwise-successful response.
+        displayName: z9.string().nullable(),
         componentId: z9.string(),
         state: z9.literal("draft").describe("New managed variants start in draft state"),
         hasContent: z9.boolean().describe("Whether text content was provided at creation")
@@ -1418,9 +1401,113 @@ function registerIntegrationGuideTools(server) {
   );
 }
 
+// src/tools/agent-traffic.ts
+import { z as z13 } from "zod";
+var PLAN_GATE_GUIDANCE = {
+  agent_analytics_requires_paid_plan: "Agent analytics requires a paid SentientUI plan (Starter or above). Upgrade at https://sentient-ui.com, then try again."
+};
+function registerAgentTrafficTools(server, client) {
+  server.registerTool(
+    "get_agent_traffic",
+    {
+      title: "Agent traffic",
+      description: "Which AI agents and crawlers are reading this site: totals by type (passive crawlers, agentic browsers, agent API calls), engine breakdown, and the paths they fetch most. Agent traffic is tracked separately and never counted in conversion rate.",
+      inputSchema: { projectId: projectIdSchema },
+      outputSchema: {
+        totals: z13.object({ crawler: z13.number(), api: z13.number(), browser: z13.number() }),
+        engines: z13.array(
+          z13.object({
+            engine: z13.string(),
+            count: z13.number(),
+            sharePct: z13.number(),
+            lastSeen: z13.string(),
+            firstSeenInRange: z13.boolean().describe("First observed within the queried period")
+          })
+        ),
+        topPaths: z13.array(z13.object({ path: z13.string(), count: z13.number(), engines: z13.number() }))
+      },
+      annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
+    },
+    withApiErrorGuidance(async ({ projectId }) => {
+      const id = encodeURIComponent(projectId);
+      const s = await client.get(`/projects/${id}/agent-activity/summary`);
+      const structuredContent = { totals: s.totals, engines: s.engines, topPaths: s.topPaths };
+      const total = s.totals.crawler + s.totals.api + s.totals.browser;
+      if (total === 0) {
+        return {
+          content: [{
+            type: "text",
+            text: "No agent traffic observed yet. Passive crawlers (GPTBot, ClaudeBot, \u2026) run no JavaScript \u2014 install sentientAgentMiddleware from @sentientui/react/next to capture them server-side."
+          }],
+          structuredContent
+        };
+      }
+      const lines = [
+        `Agent traffic: ${s.totals.crawler} crawler fetches, ${s.totals.api} agent API calls, ${s.totals.browser} agentic browser sessions.`,
+        "",
+        "Engines:",
+        ...s.engines.map((e) => `- ${e.engine}: ${e.count} fetches (${e.sharePct}%)${e.firstSeenInRange ? " \u2014 NEW this period" : ""}`),
+        "",
+        "Most-fetched paths:",
+        ...s.topPaths.map((p) => `- ${p.path}: ${p.count} fetches by ${p.engines} engine(s)`)
+      ];
+      return { content: [{ type: "text", text: lines.join("\n") }], structuredContent };
+    }, PLAN_GATE_GUIDANCE)
+  );
+  server.registerTool(
+    "get_agent_legibility",
+    {
+      title: "Agent legibility",
+      description: "Whether the pages AI agents actually read are machine-legible: per-path checks for price, product name, positioning, and CTA in the server HTML, plus agent API blocks served without agent data. Each failure comes with a concrete fix.",
+      inputSchema: { projectId: projectIdSchema },
+      outputSchema: {
+        paths: z13.array(
+          z13.object({
+            path: z13.string(),
+            score: z13.number().describe("0\u2013100, 25 per passing check"),
+            checks: z13.object({
+              price: z13.boolean(),
+              name: z13.boolean(),
+              positioning: z13.boolean(),
+              cta: z13.boolean(),
+              notes: z13.array(z13.string())
+            }),
+            lastChecked: z13.string()
+          })
+        ),
+        emptyBlocks: z13.array(z13.object({ block: z13.string(), variant: z13.string(), occurrences: z13.number() }))
+      },
+      annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
+    },
+    withApiErrorGuidance(async ({ projectId }) => {
+      const id = encodeURIComponent(projectId);
+      const l = await client.get(`/projects/${id}/agent-activity/legibility`);
+      const structuredContent = { paths: l.paths, emptyBlocks: l.emptyBlocks };
+      if (l.paths.length === 0 && l.emptyBlocks.length === 0) {
+        return {
+          content: [{ type: "text", text: "No legibility results yet \u2014 they appear once AI crawlers start fetching pages (checked daily)." }],
+          structuredContent
+        };
+      }
+      const lines = [
+        "Legibility of agent-read paths:",
+        ...l.paths.map((p) => {
+          const failed = ["price", "name", "positioning", "cta"].filter((k) => !p.checks[k]);
+          return `- ${p.path}: ${p.score}/100${failed.length ? ` \u2014 missing: ${failed.join(", ")}` : " \u2014 fully legible"}`;
+        }),
+        ...l.paths.flatMap((p) => p.checks.notes.map((n) => `  fix (${p.path}): ${n}`))
+      ];
+      if (l.emptyBlocks.length > 0) {
+        lines.push("", "Agent API blocks served without agent data (add agentDataByVariant):");
+        lines.push(...l.emptyBlocks.map((b) => `- ${b.block} (variant ${b.variant}): ${b.occurrences} calls`));
+      }
+      return { content: [{ type: "text", text: lines.join("\n") }], structuredContent };
+    }, PLAN_GATE_GUIDANCE)
+  );
+}
+
 // src/server.ts
-var import_meta = {};
-var { version: PKG_VERSION } = createRequire(import_meta.url)("../package.json");
+var PKG_VERSION = true ? "0.9.0" : "0.0.0-dev";
 function createMcpServer(client) {
   const server = new McpServer(
     {
@@ -1453,6 +1540,7 @@ function createMcpServer(client) {
   registerTestBriefTools(server, client);
   registerVariantWriteTools(server, client);
   registerIntegrationGuideTools(server);
+  registerAgentTrafficTools(server, client);
   return server;
 }
 

package/dist/index.cjs

@@ -1,10 +1,6 @@
 #!/usr/bin/env node
 "use strict";
 
-// ../../node_modules/.pnpm/tsup@8.5.1_jiti@1.21.7_postcss@8.5.14_tsx@4.22.1_typescript@5.9.3_yaml@2.9.0/node_modules/tsup/assets/cjs_shims.js
-var getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${__filename}`).href : document.currentScript && document.currentScript.tagName.toUpperCase() === "SCRIPT" ? document.currentScript.src : new URL("main.js", document.baseURI).href;
-var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
-
 // src/index.ts
 var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
 
@@ -55,7 +51,6 @@ var ApiClient = class {
 };
 
 // src/server.ts
-var import_node_module = require("module");
 var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
 
 // src/tools/projects.ts
@@ -64,7 +59,10 @@ var import_zod2 = require("zod");
 // src/tools/common.ts
 var import_zod = require("zod");
 var projectIdSchema = import_zod.z.string().uuid().describe("The project UUID");
-function apiErrorGuidance(err) {
+function apiErrorGuidance(err, extra) {
+  if (extra && Object.prototype.hasOwnProperty.call(extra, err.message)) {
+    return extra[err.message];
+  }
   switch (err.message) {
     case "insufficient_scope":
       return "This action needs an account login. Connect via the hosted MCP URL (https://api.sentient-ui.com/mcp) and sign in \u2014 a project-scoped server key (sk_\u2026) or anonymous demo token cannot do this.";
@@ -83,13 +81,13 @@ function apiErrorGuidance(err) {
   }
   return null;
 }
-function withApiErrorGuidance(fn) {
+function withApiErrorGuidance(fn, extra) {
   return async (args) => {
     try {
       return await fn(args);
     } catch (err) {
       if (err instanceof ApiError) {
-        const guidance = apiErrorGuidance(err);
+        const guidance = apiErrorGuidance(err, extra);
         if (guidance) {
           return { content: [{ type: "text", text: guidance }], isError: true };
         }
@@ -100,22 +98,10 @@ function withApiErrorGuidance(fn) {
 }
 
 // src/tools/projects.ts
-function createProjectGuidance(err) {
-  switch (err.message) {
-    case "insufficient_scope":
-      return "Creating a project needs an account login. Connect via the hosted MCP URL (https://api.sentient-ui.com/mcp) and sign in \u2014 a project-scoped server key (sk_\u2026) cannot create projects.";
-    case "demo_read_only":
-      return "Demo mode is read-only. Create a SentientUI account and sign in to make projects.";
-    case "insufficient_role":
-      return "Your account role cannot create projects \u2014 this needs the account owner or an admin.";
-    case "project_limit_reached":
-      return "You've reached your plan's project limit. Upgrade your plan or remove an existing project, then try again.";
-    case "name_required":
-      return "A project name is required to create a project.";
-    default:
-      return null;
-  }
-}
+var CREATE_PROJECT_GUIDANCE = {
+  project_limit_reached: "You've reached your plan's project limit. Upgrade your plan or remove an existing project, then try again.",
+  name_required: "A project name is required to create a project."
+};
 function registerProjectTools(server, client) {
   server.registerTool(
     "create_project",
@@ -141,41 +127,31 @@ function registerProjectTools(server, client) {
         openWorldHint: false
       }
     },
-    async ({ name, contextType, framework, websiteUrl }) => {
-      try {
-        const created = await client.post("/projects", {
+    withApiErrorGuidance(async ({ name, contextType, framework, websiteUrl }) => {
+      const created = await client.post("/projects", {
+        name,
+        contextType,
+        framework,
+        origin: websiteUrl
+      });
+      const resolvedContextType = contextType != null ? contextType : "saas";
+      return {
+        content: [{
+          type: "text",
+          text: [
+            `Created project "${name}" (id: ${created.id}, type: ${resolvedContextType}).`,
+            `Public key: ${created.apiKey}`,
+            `Next: install @sentientui/react with this key. Ask me to pull the setup guide (get_integration_guide) and I'll wrap your first component.`
+          ].join("\n")
+        }],
+        structuredContent: {
+          projectId: created.id,
+          publicKey: created.apiKey,
           name,
-          contextType,
-          framework,
-          origin: websiteUrl
-        });
-        const resolvedContextType = contextType != null ? contextType : "saas";
-        return {
-          content: [{
-            type: "text",
-            text: [
-              `Created project "${name}" (id: ${created.id}, type: ${resolvedContextType}).`,
-              `Public key: ${created.apiKey}`,
-              `Next: install @sentientui/react with this key. Ask me to pull the setup guide (get_integration_guide) and I'll wrap your first component.`
-            ].join("\n")
-          }],
-          structuredContent: {
-            projectId: created.id,
-            publicKey: created.apiKey,
-            name,
-            contextType: resolvedContextType
-          }
-        };
-      } catch (err) {
-        if (err instanceof ApiError) {
-          const guidance = createProjectGuidance(err);
-          if (guidance) {
-            return { content: [{ type: "text", text: guidance }], isError: true };
-          }
+          contextType: resolvedContextType
         }
-        throw err;
-      }
-    }
+      };
+    }, CREATE_PROJECT_GUIDANCE)
   );
   server.registerTool(
     "list_projects",
@@ -927,13 +903,16 @@ function registerVariantWriteTools(server, client) {
       description: "Create a NO-CODE managed text variant for a component (content stored in SentientUI, rendered by <AdaptiveText>). Use this ONLY for text-only variants the user wants without a code change. For variants that will live in the codebase (full components \u2014 copy, markup, styling), use get_variant_brief and write the variant in code instead; those auto-register on deploy and do not need create_variant. Requires a paid plan (server keys are Starter+; anonymous demo tokens are read-only).",
       inputSchema: {
         projectId: projectIdSchema,
-        componentId: import_zod9.z.string().describe("The component ID to add a variant to"),
-        displayName: import_zod9.z.string().describe("Human-readable name for the new variant"),
-        content: import_zod9.z.string().optional().describe("The text content for this managed variant (rendered by <AdaptiveText>). Generate it from get_variant_brief context; omit only to create an empty placeholder to fill in from the dashboard.")
+        componentId: import_zod9.z.string().min(1).max(200).describe("The component ID to add a variant to"),
+        displayName: import_zod9.z.string().min(1).max(200).describe("Human-readable name for the new variant"),
+        content: import_zod9.z.string().max(1e4).optional().describe("The text content for this managed variant (rendered by <AdaptiveText>). Generate it from get_variant_brief context; omit only to create an empty placeholder to fill in from the dashboard.")
       },
       outputSchema: {
         variantId: import_zod9.z.string().describe("The new variant ID"),
-        displayName: import_zod9.z.string(),
+        // API returns `body.displayName ?? null`, so a successful create can
+        // carry a null name — match that contract or outputSchema validation
+        // would reject an otherwise-successful response.
+        displayName: import_zod9.z.string().nullable(),
         componentId: import_zod9.z.string(),
         state: import_zod9.z.literal("draft").describe("New managed variants start in draft state"),
         hasContent: import_zod9.z.boolean().describe("Whether text content was provided at creation")
@@ -1426,8 +1405,113 @@ function registerIntegrationGuideTools(server) {
   );
 }
 
+// src/tools/agent-traffic.ts
+var import_zod13 = require("zod");
+var PLAN_GATE_GUIDANCE = {
+  agent_analytics_requires_paid_plan: "Agent analytics requires a paid SentientUI plan (Starter or above). Upgrade at https://sentient-ui.com, then try again."
+};
+function registerAgentTrafficTools(server, client) {
+  server.registerTool(
+    "get_agent_traffic",
+    {
+      title: "Agent traffic",
+      description: "Which AI agents and crawlers are reading this site: totals by type (passive crawlers, agentic browsers, agent API calls), engine breakdown, and the paths they fetch most. Agent traffic is tracked separately and never counted in conversion rate.",
+      inputSchema: { projectId: projectIdSchema },
+      outputSchema: {
+        totals: import_zod13.z.object({ crawler: import_zod13.z.number(), api: import_zod13.z.number(), browser: import_zod13.z.number() }),
+        engines: import_zod13.z.array(
+          import_zod13.z.object({
+            engine: import_zod13.z.string(),
+            count: import_zod13.z.number(),
+            sharePct: import_zod13.z.number(),
+            lastSeen: import_zod13.z.string(),
+            firstSeenInRange: import_zod13.z.boolean().describe("First observed within the queried period")
+          })
+        ),
+        topPaths: import_zod13.z.array(import_zod13.z.object({ path: import_zod13.z.string(), count: import_zod13.z.number(), engines: import_zod13.z.number() }))
+      },
+      annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
+    },
+    withApiErrorGuidance(async ({ projectId }) => {
+      const id = encodeURIComponent(projectId);
+      const s = await client.get(`/projects/${id}/agent-activity/summary`);
+      const structuredContent = { totals: s.totals, engines: s.engines, topPaths: s.topPaths };
+      const total = s.totals.crawler + s.totals.api + s.totals.browser;
+      if (total === 0) {
+        return {
+          content: [{
+            type: "text",
+            text: "No agent traffic observed yet. Passive crawlers (GPTBot, ClaudeBot, \u2026) run no JavaScript \u2014 install sentientAgentMiddleware from @sentientui/react/next to capture them server-side."
+          }],
+          structuredContent
+        };
+      }
+      const lines = [
+        `Agent traffic: ${s.totals.crawler} crawler fetches, ${s.totals.api} agent API calls, ${s.totals.browser} agentic browser sessions.`,
+        "",
+        "Engines:",
+        ...s.engines.map((e) => `- ${e.engine}: ${e.count} fetches (${e.sharePct}%)${e.firstSeenInRange ? " \u2014 NEW this period" : ""}`),
+        "",
+        "Most-fetched paths:",
+        ...s.topPaths.map((p) => `- ${p.path}: ${p.count} fetches by ${p.engines} engine(s)`)
+      ];
+      return { content: [{ type: "text", text: lines.join("\n") }], structuredContent };
+    }, PLAN_GATE_GUIDANCE)
+  );
+  server.registerTool(
+    "get_agent_legibility",
+    {
+      title: "Agent legibility",
+      description: "Whether the pages AI agents actually read are machine-legible: per-path checks for price, product name, positioning, and CTA in the server HTML, plus agent API blocks served without agent data. Each failure comes with a concrete fix.",
+      inputSchema: { projectId: projectIdSchema },
+      outputSchema: {
+        paths: import_zod13.z.array(
+          import_zod13.z.object({
+            path: import_zod13.z.string(),
+            score: import_zod13.z.number().describe("0\u2013100, 25 per passing check"),
+            checks: import_zod13.z.object({
+              price: import_zod13.z.boolean(),
+              name: import_zod13.z.boolean(),
+              positioning: import_zod13.z.boolean(),
+              cta: import_zod13.z.boolean(),
+              notes: import_zod13.z.array(import_zod13.z.string())
+            }),
+            lastChecked: import_zod13.z.string()
+          })
+        ),
+        emptyBlocks: import_zod13.z.array(import_zod13.z.object({ block: import_zod13.z.string(), variant: import_zod13.z.string(), occurrences: import_zod13.z.number() }))
+      },
+      annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
+    },
+    withApiErrorGuidance(async ({ projectId }) => {
+      const id = encodeURIComponent(projectId);
+      const l = await client.get(`/projects/${id}/agent-activity/legibility`);
+      const structuredContent = { paths: l.paths, emptyBlocks: l.emptyBlocks };
+      if (l.paths.length === 0 && l.emptyBlocks.length === 0) {
+        return {
+          content: [{ type: "text", text: "No legibility results yet \u2014 they appear once AI crawlers start fetching pages (checked daily)." }],
+          structuredContent
+        };
+      }
+      const lines = [
+        "Legibility of agent-read paths:",
+        ...l.paths.map((p) => {
+          const failed = ["price", "name", "positioning", "cta"].filter((k) => !p.checks[k]);
+          return `- ${p.path}: ${p.score}/100${failed.length ? ` \u2014 missing: ${failed.join(", ")}` : " \u2014 fully legible"}`;
+        }),
+        ...l.paths.flatMap((p) => p.checks.notes.map((n) => `  fix (${p.path}): ${n}`))
+      ];
+      if (l.emptyBlocks.length > 0) {
+        lines.push("", "Agent API blocks served without agent data (add agentDataByVariant):");
+        lines.push(...l.emptyBlocks.map((b) => `- ${b.block} (variant ${b.variant}): ${b.occurrences} calls`));
+      }
+      return { content: [{ type: "text", text: lines.join("\n") }], structuredContent };
+    }, PLAN_GATE_GUIDANCE)
+  );
+}
+
 // src/server.ts
-var { version: PKG_VERSION } = (0, import_node_module.createRequire)(importMetaUrl)("../package.json");
+var PKG_VERSION = true ? "0.9.0" : "0.0.0-dev";
 function createMcpServer(client) {
   const server = new import_mcp.McpServer(
     {
@@ -1460,6 +1544,7 @@ function createMcpServer(client) {
   registerTestBriefTools(server, client);
   registerVariantWriteTools(server, client);
   registerIntegrationGuideTools(server);
+  registerAgentTrafficTools(server, client);
   return server;
 }
 

package/dist/index.js

@@ -2,7 +2,7 @@
 import {
   ApiClient,
   createMcpServer
-} from "./chunk-TLBLOBSB.js";
+} from "./chunk-QESH43WV.js";
 
 // src/index.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

package/dist/lib.cjs

@@ -27,17 +27,15 @@ __export(lib_exports, {
 });
 module.exports = __toCommonJS(lib_exports);
 
-// ../../node_modules/.pnpm/tsup@8.5.1_jiti@1.21.7_postcss@8.5.14_tsx@4.22.1_typescript@5.9.3_yaml@2.9.0/node_modules/tsup/assets/cjs_shims.js
-var getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${__filename}`).href : document.currentScript && document.currentScript.tagName.toUpperCase() === "SCRIPT" ? document.currentScript.src : new URL("main.js", document.baseURI).href;
-var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
-
 // src/server.ts
-var import_node_module = require("module");
 var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
 
 // src/tools/projects.ts
 var import_zod2 = require("zod");
 
+// src/tools/common.ts
+var import_zod = require("zod");
+
 // src/api-client.ts
 var ApiError = class extends Error {
   constructor(status, message) {
@@ -85,9 +83,11 @@ var ApiClient = class {
 };
 
 // src/tools/common.ts
-var import_zod = require("zod");
 var projectIdSchema = import_zod.z.string().uuid().describe("The project UUID");
-function apiErrorGuidance(err) {
+function apiErrorGuidance(err, extra) {
+  if (extra && Object.prototype.hasOwnProperty.call(extra, err.message)) {
+    return extra[err.message];
+  }
   switch (err.message) {
     case "insufficient_scope":
       return "This action needs an account login. Connect via the hosted MCP URL (https://api.sentient-ui.com/mcp) and sign in \u2014 a project-scoped server key (sk_\u2026) or anonymous demo token cannot do this.";
@@ -106,13 +106,13 @@ function apiErrorGuidance(err) {
   }
   return null;
 }
-function withApiErrorGuidance(fn) {
+function withApiErrorGuidance(fn, extra) {
   return async (args) => {
     try {
       return await fn(args);
     } catch (err) {
       if (err instanceof ApiError) {
-        const guidance = apiErrorGuidance(err);
+        const guidance = apiErrorGuidance(err, extra);
         if (guidance) {
           return { content: [{ type: "text", text: guidance }], isError: true };
         }
@@ -123,22 +123,10 @@ function withApiErrorGuidance(fn) {
 }
 
 // src/tools/projects.ts
-function createProjectGuidance(err) {
-  switch (err.message) {
-    case "insufficient_scope":
-      return "Creating a project needs an account login. Connect via the hosted MCP URL (https://api.sentient-ui.com/mcp) and sign in \u2014 a project-scoped server key (sk_\u2026) cannot create projects.";
-    case "demo_read_only":
-      return "Demo mode is read-only. Create a SentientUI account and sign in to make projects.";
-    case "insufficient_role":
-      return "Your account role cannot create projects \u2014 this needs the account owner or an admin.";
-    case "project_limit_reached":
-      return "You've reached your plan's project limit. Upgrade your plan or remove an existing project, then try again.";
-    case "name_required":
-      return "A project name is required to create a project.";
-    default:
-      return null;
-  }
-}
+var CREATE_PROJECT_GUIDANCE = {
+  project_limit_reached: "You've reached your plan's project limit. Upgrade your plan or remove an existing project, then try again.",
+  name_required: "A project name is required to create a project."
+};
 function registerProjectTools(server, client) {
   server.registerTool(
     "create_project",
@@ -164,41 +152,31 @@ function registerProjectTools(server, client) {
         openWorldHint: false
       }
     },
-    async ({ name, contextType, framework, websiteUrl }) => {
-      try {
-        const created = await client.post("/projects", {
+    withApiErrorGuidance(async ({ name, contextType, framework, websiteUrl }) => {
+      const created = await client.post("/projects", {
+        name,
+        contextType,
+        framework,
+        origin: websiteUrl
+      });
+      const resolvedContextType = contextType != null ? contextType : "saas";
+      return {
+        content: [{
+          type: "text",
+          text: [
+            `Created project "${name}" (id: ${created.id}, type: ${resolvedContextType}).`,
+            `Public key: ${created.apiKey}`,
+            `Next: install @sentientui/react with this key. Ask me to pull the setup guide (get_integration_guide) and I'll wrap your first component.`
+          ].join("\n")
+        }],
+        structuredContent: {
+          projectId: created.id,
+          publicKey: created.apiKey,
           name,
-          contextType,
-          framework,
-          origin: websiteUrl
-        });
-        const resolvedContextType = contextType != null ? contextType : "saas";
-        return {
-          content: [{
-            type: "text",
-            text: [
-              `Created project "${name}" (id: ${created.id}, type: ${resolvedContextType}).`,
-              `Public key: ${created.apiKey}`,
-              `Next: install @sentientui/react with this key. Ask me to pull the setup guide (get_integration_guide) and I'll wrap your first component.`
-            ].join("\n")
-          }],
-          structuredContent: {
-            projectId: created.id,
-            publicKey: created.apiKey,
-            name,
-            contextType: resolvedContextType
-          }
-        };
-      } catch (err) {
-        if (err instanceof ApiError) {
-          const guidance = createProjectGuidance(err);
-          if (guidance) {
-            return { content: [{ type: "text", text: guidance }], isError: true };
-          }
+          contextType: resolvedContextType
         }
-        throw err;
-      }
-    }
+      };
+    }, CREATE_PROJECT_GUIDANCE)
   );
   server.registerTool(
     "list_projects",
@@ -950,13 +928,16 @@ function registerVariantWriteTools(server, client) {
       description: "Create a NO-CODE managed text variant for a component (content stored in SentientUI, rendered by <AdaptiveText>). Use this ONLY for text-only variants the user wants without a code change. For variants that will live in the codebase (full components \u2014 copy, markup, styling), use get_variant_brief and write the variant in code instead; those auto-register on deploy and do not need create_variant. Requires a paid plan (server keys are Starter+; anonymous demo tokens are read-only).",
       inputSchema: {
         projectId: projectIdSchema,
-        componentId: import_zod9.z.string().describe("The component ID to add a variant to"),
-        displayName: import_zod9.z.string().describe("Human-readable name for the new variant"),
-        content: import_zod9.z.string().optional().describe("The text content for this managed variant (rendered by <AdaptiveText>). Generate it from get_variant_brief context; omit only to create an empty placeholder to fill in from the dashboard.")
+        componentId: import_zod9.z.string().min(1).max(200).describe("The component ID to add a variant to"),
+        displayName: import_zod9.z.string().min(1).max(200).describe("Human-readable name for the new variant"),
+        content: import_zod9.z.string().max(1e4).optional().describe("The text content for this managed variant (rendered by <AdaptiveText>). Generate it from get_variant_brief context; omit only to create an empty placeholder to fill in from the dashboard.")
       },
       outputSchema: {
         variantId: import_zod9.z.string().describe("The new variant ID"),
-        displayName: import_zod9.z.string(),
+        // API returns `body.displayName ?? null`, so a successful create can
+        // carry a null name — match that contract or outputSchema validation
+        // would reject an otherwise-successful response.
+        displayName: import_zod9.z.string().nullable(),
         componentId: import_zod9.z.string(),
         state: import_zod9.z.literal("draft").describe("New managed variants start in draft state"),
         hasContent: import_zod9.z.boolean().describe("Whether text content was provided at creation")
@@ -1449,8 +1430,113 @@ function registerIntegrationGuideTools(server) {
   );
 }
 
+// src/tools/agent-traffic.ts
+var import_zod13 = require("zod");
+var PLAN_GATE_GUIDANCE = {
+  agent_analytics_requires_paid_plan: "Agent analytics requires a paid SentientUI plan (Starter or above). Upgrade at https://sentient-ui.com, then try again."
+};
+function registerAgentTrafficTools(server, client) {
+  server.registerTool(
+    "get_agent_traffic",
+    {
+      title: "Agent traffic",
+      description: "Which AI agents and crawlers are reading this site: totals by type (passive crawlers, agentic browsers, agent API calls), engine breakdown, and the paths they fetch most. Agent traffic is tracked separately and never counted in conversion rate.",
+      inputSchema: { projectId: projectIdSchema },
+      outputSchema: {
+        totals: import_zod13.z.object({ crawler: import_zod13.z.number(), api: import_zod13.z.number(), browser: import_zod13.z.number() }),
+        engines: import_zod13.z.array(
+          import_zod13.z.object({
+            engine: import_zod13.z.string(),
+            count: import_zod13.z.number(),
+            sharePct: import_zod13.z.number(),
+            lastSeen: import_zod13.z.string(),
+            firstSeenInRange: import_zod13.z.boolean().describe("First observed within the queried period")
+          })
+        ),
+        topPaths: import_zod13.z.array(import_zod13.z.object({ path: import_zod13.z.string(), count: import_zod13.z.number(), engines: import_zod13.z.number() }))
+      },
+      annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
+    },
+    withApiErrorGuidance(async ({ projectId }) => {
+      const id = encodeURIComponent(projectId);
+      const s = await client.get(`/projects/${id}/agent-activity/summary`);
+      const structuredContent = { totals: s.totals, engines: s.engines, topPaths: s.topPaths };
+      const total = s.totals.crawler + s.totals.api + s.totals.browser;
+      if (total === 0) {
+        return {
+          content: [{
+            type: "text",
+            text: "No agent traffic observed yet. Passive crawlers (GPTBot, ClaudeBot, \u2026) run no JavaScript \u2014 install sentientAgentMiddleware from @sentientui/react/next to capture them server-side."
+          }],
+          structuredContent
+        };
+      }
+      const lines = [
+        `Agent traffic: ${s.totals.crawler} crawler fetches, ${s.totals.api} agent API calls, ${s.totals.browser} agentic browser sessions.`,
+        "",
+        "Engines:",
+        ...s.engines.map((e) => `- ${e.engine}: ${e.count} fetches (${e.sharePct}%)${e.firstSeenInRange ? " \u2014 NEW this period" : ""}`),
+        "",
+        "Most-fetched paths:",
+        ...s.topPaths.map((p) => `- ${p.path}: ${p.count} fetches by ${p.engines} engine(s)`)
+      ];
+      return { content: [{ type: "text", text: lines.join("\n") }], structuredContent };
+    }, PLAN_GATE_GUIDANCE)
+  );
+  server.registerTool(
+    "get_agent_legibility",
+    {
+      title: "Agent legibility",
+      description: "Whether the pages AI agents actually read are machine-legible: per-path checks for price, product name, positioning, and CTA in the server HTML, plus agent API blocks served without agent data. Each failure comes with a concrete fix.",
+      inputSchema: { projectId: projectIdSchema },
+      outputSchema: {
+        paths: import_zod13.z.array(
+          import_zod13.z.object({
+            path: import_zod13.z.string(),
+            score: import_zod13.z.number().describe("0\u2013100, 25 per passing check"),
+            checks: import_zod13.z.object({
+              price: import_zod13.z.boolean(),
+              name: import_zod13.z.boolean(),
+              positioning: import_zod13.z.boolean(),
+              cta: import_zod13.z.boolean(),
+              notes: import_zod13.z.array(import_zod13.z.string())
+            }),
+            lastChecked: import_zod13.z.string()
+          })
+        ),
+        emptyBlocks: import_zod13.z.array(import_zod13.z.object({ block: import_zod13.z.string(), variant: import_zod13.z.string(), occurrences: import_zod13.z.number() }))
+      },
+      annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
+    },
+    withApiErrorGuidance(async ({ projectId }) => {
+      const id = encodeURIComponent(projectId);
+      const l = await client.get(`/projects/${id}/agent-activity/legibility`);
+      const structuredContent = { paths: l.paths, emptyBlocks: l.emptyBlocks };
+      if (l.paths.length === 0 && l.emptyBlocks.length === 0) {
+        return {
+          content: [{ type: "text", text: "No legibility results yet \u2014 they appear once AI crawlers start fetching pages (checked daily)." }],
+          structuredContent
+        };
+      }
+      const lines = [
+        "Legibility of agent-read paths:",
+        ...l.paths.map((p) => {
+          const failed = ["price", "name", "positioning", "cta"].filter((k) => !p.checks[k]);
+          return `- ${p.path}: ${p.score}/100${failed.length ? ` \u2014 missing: ${failed.join(", ")}` : " \u2014 fully legible"}`;
+        }),
+        ...l.paths.flatMap((p) => p.checks.notes.map((n) => `  fix (${p.path}): ${n}`))
+      ];
+      if (l.emptyBlocks.length > 0) {
+        lines.push("", "Agent API blocks served without agent data (add agentDataByVariant):");
+        lines.push(...l.emptyBlocks.map((b) => `- ${b.block} (variant ${b.variant}): ${b.occurrences} calls`));
+      }
+      return { content: [{ type: "text", text: lines.join("\n") }], structuredContent };
+    }, PLAN_GATE_GUIDANCE)
+  );
+}
+
 // src/server.ts
-var { version: PKG_VERSION } = (0, import_node_module.createRequire)(importMetaUrl)("../package.json");
+var PKG_VERSION = true ? "0.9.0" : "0.0.0-dev";
 function createMcpServer(client) {
   const server = new import_mcp.McpServer(
     {
@@ -1483,6 +1569,7 @@ function createMcpServer(client) {
   registerTestBriefTools(server, client);
   registerVariantWriteTools(server, client);
   registerIntegrationGuideTools(server);
+  registerAgentTrafficTools(server, client);
   return server;
 }
 // Annotate the CommonJS export names for ESM import in node:

package/dist/lib.js

@@ -3,7 +3,7 @@ import {
   ApiClient,
   ApiError,
   createMcpServer
-} from "./chunk-TLBLOBSB.js";
+} from "./chunk-QESH43WV.js";
 export {
   ApiClient,
   ApiError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentientui/mcp",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "MCP server for SentientUI — exposes project data and actions to AI agents",
   "license": "MIT",
   "homepage": "https://sentient-ui.com",