@sentientui/mcp 0.8.2 → 0.9.0

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

@@ -1401,8 +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 PKG_VERSION = true ? "0.8.2" : "0.0.0-dev";
+var PKG_VERSION = true ? "0.9.0" : "0.0.0-dev";
 function createMcpServer(client) {
   const server = new McpServer(
     {
@@ -1435,6 +1540,7 @@ function createMcpServer(client) {
   registerTestBriefTools(server, client);
   registerVariantWriteTools(server, client);
   registerIntegrationGuideTools(server);
+  registerAgentTrafficTools(server, client);
   return server;
 }
 

package/dist/index.cjs

@@ -1405,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 PKG_VERSION = true ? "0.8.2" : "0.0.0-dev";
+var PKG_VERSION = true ? "0.9.0" : "0.0.0-dev";
 function createMcpServer(client) {
   const server = new import_mcp.McpServer(
     {
@@ -1439,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-GLL5CMBY.js";
+} from "./chunk-QESH43WV.js";
 
 // src/index.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

package/dist/lib.cjs

@@ -1430,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 PKG_VERSION = true ? "0.8.2" : "0.0.0-dev";
+var PKG_VERSION = true ? "0.9.0" : "0.0.0-dev";
 function createMcpServer(client) {
   const server = new import_mcp.McpServer(
     {
@@ -1464,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-GLL5CMBY.js";
+} from "./chunk-QESH43WV.js";
 export {
   ApiClient,
   ApiError,

package/package.json

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