@lightsage/mcp 0.4.16 → 0.4.18

package/esm/models/v2visibilitycurrentretrieveop.js

@@ -7,6 +7,7 @@ import { HTTPValidationError$zodSchema, } from "./httpvalidationerror.js";
 import { PublicCurrentVisibilityResponse$zodSchema, } from "./publiccurrentvisibilityresponse.js";
 export const V2VisibilityCurrentRetrieveRequest$zodSchema = z.object({
     end_date: z.string().date().describe("Inclusive range end; defaults to today.").optional(),
+    period: z.string().describe("Named period, resolved in UTC by the server: `last_7_days`, `last_14_days`, `last_30_days`, `last_90_days` (N days ending today), `this_week`, `last_week`, an ISO week such as `2026-W43` (Monday to Sunday), `this_month`, `last_month`, a month such as `2026-10`, `this_quarter`, `last_quarter`, or a quarter such as `2026Q4`. A current week, month, or quarter ends today. The response's `period` gives the resolved dates and the matching previous period. Do not combine with `start_date` or `end_date`.").optional(),
     start_date: z.string().date().describe("Inclusive range start; defaults to 30 days before the end date. The range may span at most 90 days.").optional(),
 });
 export const V2VisibilityCurrentRetrieveResponse$zodSchema = z.union([

package/esm/models/v2visibilitycurrentretrieveop.js.map

@@ -1 +1 @@
-{"version":3,"file":"v2visibilitycurrentretrieveop.js","sourceRoot":"","sources":["../../src/models/v2visibilitycurrentretrieveop.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,EAEL,6BAA6B,GAC9B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAEL,yCAAyC,GAC1C,MAAM,sCAAsC,CAAC;AAO9C,MAAM,CAAC,MAAM,4CAA4C,GAErD,CAAC,CAAC,MAAM,CAAC;IACX,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,QAAQ,CAClC,yCAAyC,CAC1C,CAAC,QAAQ,EAAE;IACZ,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,QAAQ,CACpC,qGAAqG,CACtG,CAAC,QAAQ,EAAE;CACb,CAAC,CAAC;AAMH,MAAM,CAAC,MAAM,6CAA6C,GAEtD,CAAC,CAAC,KAAK,CAAC;IACV,yCAAyC;IACzC,6BAA6B;CAC9B,CAAC,CAAC"}
+{"version":3,"file":"v2visibilitycurrentretrieveop.js","sourceRoot":"","sources":["../../src/models/v2visibilitycurrentretrieveop.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,EAEL,6BAA6B,GAC9B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAEL,yCAAyC,GAC1C,MAAM,sCAAsC,CAAC;AAQ9C,MAAM,CAAC,MAAM,4CAA4C,GAErD,CAAC,CAAC,MAAM,CAAC;IACX,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,QAAQ,CAClC,yCAAyC,CAC1C,CAAC,QAAQ,EAAE;IACZ,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CACzB,ufAAuf,CACxf,CAAC,QAAQ,EAAE;IACZ,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,QAAQ,CACpC,qGAAqG,CACtG,CAAC,QAAQ,EAAE;CACb,CAAC,CAAC;AAMH,MAAM,CAAC,MAAM,6CAA6C,GAEtD,CAAC,CAAC,KAAK,CAAC;IACV,yCAAyC;IACzC,6BAA6B;CAC9B,CAAC,CAAC"}

package/esm/models/v2visibilityoverviewretrieveop.d.ts

@@ -4,6 +4,7 @@ import { PublicVisibilityOverviewResponse } from "./publicvisibilityoverviewresp
 export type V2VisibilityOverviewRetrieveRequest = {
     start_date?: string | undefined;
     end_date?: string | undefined;
+    period?: string | undefined;
 };
 export declare const V2VisibilityOverviewRetrieveRequest$zodSchema: z.ZodType<V2VisibilityOverviewRetrieveRequest>;
 export type V2VisibilityOverviewRetrieveResponse = PublicVisibilityOverviewResponse | HTTPValidationError;

package/esm/models/v2visibilityoverviewretrieveop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"v2visibilityoverviewretrieveop.d.ts","sourceRoot":"","sources":["../../src/models/v2visibilityoverviewretrieveop.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,EACL,mBAAmB,EAEpB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,gCAAgC,EAEjC,MAAM,uCAAuC,CAAC;AAE/C,MAAM,MAAM,mCAAmC,GAAG;IAChD,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B,CAAC;AAEF,eAAO,MAAM,6CAA6C,EAAE,CAAC,CAAC,OAAO,CACnE,mCAAmC,CAQnC,CAAC;AAEH,MAAM,MAAM,oCAAoC,GAC5C,gCAAgC,GAChC,mBAAmB,CAAC;AAExB,eAAO,MAAM,8CAA8C,EAAE,CAAC,CAAC,OAAO,CACpE,oCAAoC,CAIpC,CAAC"}
+{"version":3,"file":"v2visibilityoverviewretrieveop.d.ts","sourceRoot":"","sources":["../../src/models/v2visibilityoverviewretrieveop.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,EACL,mBAAmB,EAEpB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,gCAAgC,EAEjC,MAAM,uCAAuC,CAAC;AAE/C,MAAM,MAAM,mCAAmC,GAAG;IAChD,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B,CAAC;AAEF,eAAO,MAAM,6CAA6C,EAAE,CAAC,CAAC,OAAO,CACnE,mCAAmC,CAWnC,CAAC;AAEH,MAAM,MAAM,oCAAoC,GAC5C,gCAAgC,GAChC,mBAAmB,CAAC;AAExB,eAAO,MAAM,8CAA8C,EAAE,CAAC,CAAC,OAAO,CACpE,oCAAoC,CAIpC,CAAC"}

package/esm/models/v2visibilityoverviewretrieveop.js

@@ -7,6 +7,7 @@ import { HTTPValidationError$zodSchema, } from "./httpvalidationerror.js";
 import { PublicVisibilityOverviewResponse$zodSchema, } from "./publicvisibilityoverviewresponse.js";
 export const V2VisibilityOverviewRetrieveRequest$zodSchema = z.object({
     end_date: z.string().date().describe("Inclusive range end; defaults to today.").optional(),
+    period: z.string().describe("Named period, resolved in UTC by the server: `last_7_days`, `last_14_days`, `last_30_days`, `last_90_days` (N days ending today), `this_week`, `last_week`, an ISO week such as `2026-W43` (Monday to Sunday), `this_month`, `last_month`, a month such as `2026-10`, `this_quarter`, `last_quarter`, or a quarter such as `2026Q4`. A current week, month, or quarter ends today. The response's `period` gives the resolved dates and the matching previous period. Do not combine with `start_date` or `end_date`.").optional(),
     start_date: z.string().date().describe("Inclusive range start; defaults to 30 days before the end date. The range may span at most 90 days.").optional(),
 });
 export const V2VisibilityOverviewRetrieveResponse$zodSchema = z.union([

package/esm/models/v2visibilityoverviewretrieveop.js.map

@@ -1 +1 @@
-{"version":3,"file":"v2visibilityoverviewretrieveop.js","sourceRoot":"","sources":["../../src/models/v2visibilityoverviewretrieveop.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,EAEL,6BAA6B,GAC9B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAEL,0CAA0C,GAC3C,MAAM,uCAAuC,CAAC;AAO/C,MAAM,CAAC,MAAM,6CAA6C,GAEtD,CAAC,CAAC,MAAM,CAAC;IACX,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,QAAQ,CAClC,yCAAyC,CAC1C,CAAC,QAAQ,EAAE;IACZ,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,QAAQ,CACpC,qGAAqG,CACtG,CAAC,QAAQ,EAAE;CACb,CAAC,CAAC;AAMH,MAAM,CAAC,MAAM,8CAA8C,GAEvD,CAAC,CAAC,KAAK,CAAC;IACV,0CAA0C;IAC1C,6BAA6B;CAC9B,CAAC,CAAC"}
+{"version":3,"file":"v2visibilityoverviewretrieveop.js","sourceRoot":"","sources":["../../src/models/v2visibilityoverviewretrieveop.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,EAEL,6BAA6B,GAC9B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAEL,0CAA0C,GAC3C,MAAM,uCAAuC,CAAC;AAQ/C,MAAM,CAAC,MAAM,6CAA6C,GAEtD,CAAC,CAAC,MAAM,CAAC;IACX,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,QAAQ,CAClC,yCAAyC,CAC1C,CAAC,QAAQ,EAAE;IACZ,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CACzB,ufAAuf,CACxf,CAAC,QAAQ,EAAE;IACZ,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,QAAQ,CACpC,qGAAqG,CACtG,CAAC,QAAQ,EAAE;CACb,CAAC,CAAC;AAMH,MAAM,CAAC,MAAM,8CAA8C,GAEvD,CAAC,CAAC,KAAK,CAAC;IACV,0CAA0C;IAC1C,6BAA6B;CAC9B,CAAC,CAAC"}

package/esm/models/v2visibilitypromptsretrieveop.d.ts

@@ -4,6 +4,7 @@ import { PublicPromptVisibilityReportResponse } from "./publicpromptvisibilityre
 export type V2VisibilityPromptsRetrieveRequest = {
     start_date?: string | undefined;
     end_date?: string | undefined;
+    period?: string | undefined;
 };
 export declare const V2VisibilityPromptsRetrieveRequest$zodSchema: z.ZodType<V2VisibilityPromptsRetrieveRequest>;
 export type V2VisibilityPromptsRetrieveResponse = PublicPromptVisibilityReportResponse | HTTPValidationError;

package/esm/models/v2visibilitypromptsretrieveop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"v2visibilitypromptsretrieveop.d.ts","sourceRoot":"","sources":["../../src/models/v2visibilitypromptsretrieveop.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,EACL,mBAAmB,EAEpB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,oCAAoC,EAErC,MAAM,2CAA2C,CAAC;AAEnD,MAAM,MAAM,kCAAkC,GAAG;IAC/C,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B,CAAC;AAEF,eAAO,MAAM,4CAA4C,EAAE,CAAC,CAAC,OAAO,CAClE,kCAAkC,CAQlC,CAAC;AAEH,MAAM,MAAM,mCAAmC,GAC3C,oCAAoC,GACpC,mBAAmB,CAAC;AAExB,eAAO,MAAM,6CAA6C,EAAE,CAAC,CAAC,OAAO,CACnE,mCAAmC,CAInC,CAAC"}
+{"version":3,"file":"v2visibilitypromptsretrieveop.d.ts","sourceRoot":"","sources":["../../src/models/v2visibilitypromptsretrieveop.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,EACL,mBAAmB,EAEpB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,oCAAoC,EAErC,MAAM,2CAA2C,CAAC;AAEnD,MAAM,MAAM,kCAAkC,GAAG;IAC/C,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B,CAAC;AAEF,eAAO,MAAM,4CAA4C,EAAE,CAAC,CAAC,OAAO,CAClE,kCAAkC,CAWlC,CAAC;AAEH,MAAM,MAAM,mCAAmC,GAC3C,oCAAoC,GACpC,mBAAmB,CAAC;AAExB,eAAO,MAAM,6CAA6C,EAAE,CAAC,CAAC,OAAO,CACnE,mCAAmC,CAInC,CAAC"}

package/esm/models/v2visibilitypromptsretrieveop.js

@@ -7,6 +7,7 @@ import { HTTPValidationError$zodSchema, } from "./httpvalidationerror.js";
 import { PublicPromptVisibilityReportResponse$zodSchema, } from "./publicpromptvisibilityreportresponse.js";
 export const V2VisibilityPromptsRetrieveRequest$zodSchema = z.object({
     end_date: z.string().date().describe("Inclusive range end; defaults to today.").optional(),
+    period: z.string().describe("Named period, resolved in UTC by the server: `last_7_days`, `last_14_days`, `last_30_days`, `last_90_days` (N days ending today), `this_week`, `last_week`, an ISO week such as `2026-W43` (Monday to Sunday), `this_month`, `last_month`, a month such as `2026-10`, `this_quarter`, `last_quarter`, or a quarter such as `2026Q4`. A current week, month, or quarter ends today. The response's `period` gives the resolved dates and the matching previous period. Do not combine with `start_date` or `end_date`.").optional(),
     start_date: z.string().date().describe("Inclusive range start; defaults to 30 days before the end date. The range may span at most 90 days.").optional(),
 });
 export const V2VisibilityPromptsRetrieveResponse$zodSchema = z.union([

package/esm/models/v2visibilitypromptsretrieveop.js.map

@@ -1 +1 @@
-{"version":3,"file":"v2visibilitypromptsretrieveop.js","sourceRoot":"","sources":["../../src/models/v2visibilitypromptsretrieveop.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,EAEL,6BAA6B,GAC9B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAEL,8CAA8C,GAC/C,MAAM,2CAA2C,CAAC;AAOnD,MAAM,CAAC,MAAM,4CAA4C,GAErD,CAAC,CAAC,MAAM,CAAC;IACX,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,QAAQ,CAClC,yCAAyC,CAC1C,CAAC,QAAQ,EAAE;IACZ,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,QAAQ,CACpC,qGAAqG,CACtG,CAAC,QAAQ,EAAE;CACb,CAAC,CAAC;AAMH,MAAM,CAAC,MAAM,6CAA6C,GAEtD,CAAC,CAAC,KAAK,CAAC;IACV,8CAA8C;IAC9C,6BAA6B;CAC9B,CAAC,CAAC"}
+{"version":3,"file":"v2visibilitypromptsretrieveop.js","sourceRoot":"","sources":["../../src/models/v2visibilitypromptsretrieveop.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AACzB,OAAO,EAEL,6BAA6B,GAC9B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAEL,8CAA8C,GAC/C,MAAM,2CAA2C,CAAC;AAQnD,MAAM,CAAC,MAAM,4CAA4C,GAErD,CAAC,CAAC,MAAM,CAAC;IACX,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,QAAQ,CAClC,yCAAyC,CAC1C,CAAC,QAAQ,EAAE;IACZ,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CACzB,ufAAuf,CACxf,CAAC,QAAQ,EAAE;IACZ,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,QAAQ,CACpC,qGAAqG,CACtG,CAAC,QAAQ,EAAE;CACb,CAAC,CAAC;AAMH,MAAM,CAAC,MAAM,6CAA6C,GAEtD,CAAC,CAAC,KAAK,CAAC;IACV,8CAA8C;IAC9C,6BAA6B;CAC9B,CAAC,CAAC"}

package/esm/tool-names.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-names.d.ts","sourceRoot":"","sources":["../src/tool-names.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,SAAS,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAqQlE,CAAC"}
+{"version":3,"file":"tool-names.d.ts","sourceRoot":"","sources":["../src/tool-names.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,SAAS,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAySlE,CAAC"}

package/esm/tool-names.js

@@ -10,20 +10,24 @@ export const toolNames = [
     },
     {
         "name": "visibility-current-retrieve",
-        "description": "Retrieve Current Visibility\n\nReturns recommendation score, visibility score, ranks, and date-range metadata for the configured primary company. Metrics are computed from active prompts only; when no data exists, values are `null`."
+        "description": "Retrieve Current Visibility\n\nReturns recommendation score, visibility score, ranks, and date-range metadata for the configured primary company, with the same metrics for the previous period, run coverage, and per-run rates. Metrics are computed from active prompts only; when no data exists, values are `null`. Pass `period` (for example `last_30_days` or `2026Q4`) instead of computing dates."
     },
     {
         "name": "visibility-overview-retrieve",
-        "description": "Retrieve Visibility Overview\n\nReturns aggregate snapshot, daily trends, per-platform breakdowns, and competitor comparison. Calculated from active prompts only."
+        "description": "Retrieve Visibility Overview\n\nReturns aggregate snapshot, daily trends, per-platform breakdowns, and competitor comparison, with run coverage and per-run rates against the previous period. Calculated from active prompts only."
     },
     {
         "name": "visibility-citations-list",
-        "description": "List Top Cited Urls\n\nReturns URL-level citation counts ranked from most to least cited. Results can be filtered by platform and to owned or external sources."
+        "description": "List Top Cited Urls\n\nReturns URL-level citation counts ranked from most to least cited. Results can be filtered by platform and to owned or external sources. For totals by URL prefix, domain, or day compared with the previous period, use the citations summary."
     },
     {
         "name": "visibility-prompts-retrieve",
         "description": "Retrieve Prompt Visibility Report\n\nReturns per-topic and per-prompt visibility metrics including recommendation score, rank, visibility score, average position, and citation counts."
     },
+    {
+        "name": "visibility-citations-summary-retrieve",
+        "description": "Retrieve Citation Summary\n\nReturns citation totals grouped by URL prefix (domain and first path segment, such as `example.com/blog`), URL, domain, or day, each compared with the previous period, with per-run rates and run coverage. Filter to one section of a site with `url_prefix`, for example `https://example.com/blog/`. Aggregated in one call; use it instead of paging the citations list."
+    },
     {
         "name": "prompts-list",
         "description": "List Prompts\n\nReturns active and inactive prompts by default. Set `include_archived` to include archived prompts."
@@ -70,12 +74,16 @@ export const toolNames = [
     },
     {
         "name": "prompts-run",
-        "description": "Run Prompts\n\nQueue saved prompts using the organization's configured targets.\n\nProvide `prompt_ids` to run selected prompts, or omit them to run all active\nprompts. Saved prompt run settings apply to coding-agent targets. The\nresponse returns a run ID to poll with\n`GET /v2/prompts/runs/{run_id}/status`."
+        "description": "Run Prompts\n\nQueue saved prompts on answer engines and coding agents.\n\nProvide `prompt_ids` to run selected prompts, or omit them to run all active\nprompts. By default the run uses the organization's configured targets.\nProvide `agent` with IDs from `GET /v2/agents` to run the prompts on\nspecific coding-agent harnesses and models instead, for example to compare\nhow several coding tools answer the same developer question. Results\ninclude mentions and citations. Saved prompt run settings apply to\ncoding-agent targets. The response returns a run ID to poll with\n`GET /v2/prompts/runs/{run_id}/status`."
     },
     {
         "name": "prompts-run-status",
         "description": "Get Prompt Run Status\n\nReturn status and progress for a queued prompt run.\n\nPoll this endpoint until `status` is `completed`, `failed`, or `cancelled`.\nIndividual stored results are available from `GET /v2/prompts/runs`."
     },
+    {
+        "name": "prompts-run-cancel",
+        "description": "Cancel a prompt run\n\nMarks an active prompt run as cancelled and prevents queued prompts from starting. Running coding-agent attempts are stopped asynchronously. Requests already sent to an answer platform cannot be recalled, so prompts already in progress may still finish and store their results, but the run stays cancelled. Prompts that never start use no usage-based credits. The response has the same shape as the status operation, with cancelled prompts counted in `progress.cancelled`. Repeating this request for an already-cancelled run is safe."
+    },
     {
         "name": "opportunities-list",
         "description": "List Opportunities\n\nReturns ranked opportunities computed from stored prompt visibility results. Each includes an `execution_prompt` with context for an AI agent. Default window is 30 days."
@@ -88,6 +96,10 @@ export const toolNames = [
         "name": "tasks-list",
         "description": "List Tasks\n\nReturns persisted daily tasks with execution instructions. Includes per-status counts not narrowed by the `status` filter."
     },
+    {
+        "name": "tasks-create",
+        "description": "Create Task\n\nAdds a task to today's queue and returns it with its execution prompt. New tasks start as `new`."
+    },
     {
         "name": "tasks-retrieve",
         "description": "Retrieve Task\n\nReturns one persisted task and its execution prompt."
@@ -104,13 +116,37 @@ export const toolNames = [
         "name": "site-audits-retrieve",
         "description": "Retrieve Site Audit\n\nReturns one audited page with its score, priority, supporting evidence, and recommended fixes."
     },
+    {
+        "name": "agent-analytics-sites-list",
+        "description": "List Agent Analytics Sites\n\nReturns every site with tracked visits. Use a `site_id` from this list to read that site's agent traffic."
+    },
+    {
+        "name": "agent-analytics-summary-retrieve",
+        "description": "Retrieve Agent Analytics Summary\n\nReturns a site's visits by traffic type (coding agents, user-requested AI fetches, AI search, AI training, other bots, and people) for the date range and for the previous period (the same number of days before it, or the previous calendar week, month, or quarter for a named `period`)."
+    },
+    {
+        "name": "agent-analytics-sources-list",
+        "description": "List Agent Analytics Sources\n\nReturns every coding agent and bot that visited a site in the date range, with its traffic type and visit count, most visits first. Human visits are one `people` row."
+    },
+    {
+        "name": "agent-analytics-pages-list",
+        "description": "List Agent Analytics Pages\n\nReturns the pages AI agents and bots read on a site in the date range, with visits per traffic type. Sorted by AI visits unless `sort` is set. With `type`, returns only pages that traffic type visited. With `agent`, returns only the pages that one coding agent read."
+    },
+    {
+        "name": "agent-analytics-error-pages-list",
+        "description": "List Agent Analytics Error Pages\n\nReturns the pages on a site that returned an error status (400 and up) in the date range, most error requests first, with the agents, bots, and people that got each error. Set `status` to 404 for pages that were not found. Needs server-side tracking that records status codes; `status_codes_tracked` says whether the site has any."
+    },
+    {
+        "name": "agent-analytics-countries-list",
+        "description": "List Agent Analytics Countries\n\nReturns a site's visits from coding agents and AI assistants per country in the date range, most visits first."
+    },
     {
         "name": "evals-list",
         "description": "List Evals\n\nReturns all active eval definitions owned by the organization. Agent Preference evals are not included; list them with `GET /v2/agent-preference/evals`."
     },
     {
         "name": "evals-create",
-        "description": "Create Eval\n\nCreates a reusable simulation definition with one or more task prompts and judges. Optional agents, persona, CLI installations, MCP servers, setup commands, cleanup commands, grounding policy, repeat count, and tags are saved with the eval. `search_grounding` supports `disabled`, `enabled`, and `default`; `default` preserves normal platform behavior. Creating the eval does not start a run and does not accept secret environment values."
+        "description": "Create Eval\n\nCreates a reusable simulation definition with one or more task prompts and judges. Optional agents, persona, CLI installations, MCP servers, setup commands, cleanup commands, grounding policy, repeat count, and tags are saved with the eval. `search_grounding` supports `disabled`, `enabled`, and `default`; `default` preserves normal platform behavior. Creating the eval does not start a run and does not accept secret environment values.\n\nEvals measure how well agents complete tasks with your product. To track how agents and answer engines answer research questions, including which brands they mention and cite, run prompts with `POST /v2/prompts/runs` instead."
     },
     {
         "name": "evals-batch-create",
@@ -150,7 +186,7 @@ export const toolNames = [
     },
     {
         "name": "evals-run",
-        "description": "Start an eval run\n\nQueues a durable eval job and returns immediately with a polling ID. Poll `GET /v2/eval-runs/{run_id}` until its status reaches a terminal value; once finished it also returns the results and analysis. Follow a run live with the monitor operation.\n\nSend one of these flat request forms:\n\n- **Saved eval:** provide `eval_id`; optionally replace its prompts, persona, agents, CLIs, MCPs, setup commands, cleanup commands, or runs for this launch. A saved configuration can still provide repository, environment, skills, and legacy tool selections.\n- **Direct create-and-run:** provide `prompts`, `judges`, and `agent`. You may also provide a persona, tags, repository, write-only environment variables, saved or inline CLIs and MCP servers, skills, setup commands, and cleanup commands.\n\nThe run fans out across prompts × agents × runs. Persona is shared metadata and does not multiply attempts. No separate `mode` field is required. If the organization lacks the estimated credits, the request fails with `402` before dispatching work.\n\nA saved or inline environment containing an empty or placeholder credential is rejected with `400` before any evaluation is dispatched."
+        "description": "Start an eval run\n\nQueues a durable eval job and returns immediately with a polling ID. Poll `GET /v2/eval-runs/{run_id}` until its status reaches a terminal value; once finished it also returns the results and analysis. Follow a run live with the monitor operation.\n\nEval runs measure how well agents complete tasks with your product. To compare how coding agents and answer engines answer the same research question, with mentions and citations, use `POST /v2/prompts/runs` with `agent` instead.\n\nSend one of these flat request forms:\n\n- **Saved eval:** provide `eval_id`; optionally replace its prompts, persona, agents, CLIs, MCPs, setup commands, cleanup commands, or runs for this launch. A saved configuration can still provide repository, environment, skills, and legacy tool selections.\n- **Direct create-and-run:** provide `prompts`, `judges`, and `agent`. You may also provide a persona, tags, repository, write-only environment variables, saved or inline CLIs and MCP servers, skills, setup commands, and cleanup commands.\n\nThe run fans out across prompts × agents × runs. Persona is shared metadata and does not multiply attempts. No separate `mode` field is required. If the organization lacks the estimated credits, the request fails with `402` before dispatching work.\n\nA saved or inline environment containing an empty or placeholder credential is rejected with `400` before any evaluation is dispatched."
     },
     {
         "name": "evals-cancel",
@@ -222,7 +258,7 @@ export const toolNames = [
     },
     {
         "name": "agents-list",
-        "description": "List Agents\n\nReturns the harness-and-model combinations your plan can run, as single agent IDs for use in eval runs."
+        "description": "List Agents\n\nReturns the coding-agent harness-and-model combinations your plan can run, as single agent IDs. Pass them as `agent` to `POST /v2/prompts/runs` to see how coding agents answer your prompts, with mentions and citations; to `POST /v2/agent-preference/evals` to see whether agents recommend your company over one competitor; or to `POST /v2/evals` and `POST /v2/eval-runs` to measure how well agents complete tasks with your product."
     },
     {
         "name": "repositories-list",

package/esm/tool-names.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-names.js","sourceRoot":"","sources":["../src/tool-names.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tool-names.js","sourceRoot":"","sources":["../src/tool-names.ts"],"names":[],"mappings":"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"}

package/lib/tracker.js

@@ -0,0 +1,219 @@
+// Lightsage MCP Analytics: records which agents call which tools.
+//
+// Tracking is on only when LIGHTSAGE_MCP_TRACKER_API_KEY holds an `lsmcp_` key
+// from the MCP Analytics setup page. The key is passed explicitly because the
+// tracker would otherwise read LIGHTSAGE_API_KEY, which this server already
+// uses as a Lightsage public-API key.
+//
+// Hand-written (not Speakeasy-generated) so regeneration does not remove it.
+
+import { createHash } from "node:crypto";
+import { finished } from "node:stream/promises";
+import { Lightsage } from "@lightsage/mcp-tracker";
+import { waitUntil } from "@vercel/functions";
+
+const apiKey = process.env.LIGHTSAGE_MCP_TRACKER_API_KEY?.trim();
+
+// Set by this server, never by the caller (see setVerifiedCaller): who the
+// request was authenticated as, e.g. "oauth:<user id>" or "key:<key hash>".
+export const VERIFIED_CALLER_HEADER = "x-lightsage-verified-caller";
+
+// Sent by the Lightsage in-app agent (backend ai_chat) to attribute its calls.
+const AGENT_USER_HEADER = "x-lightsage-agent-user";
+const AGENT_RUN_HEADER = "x-lightsage-agent-run";
+const AGENT_INTENT_HEADER = "x-lightsage-agent-intent";
+
+// Headers that identify the caller, in the order api/mcp.js accepts them.
+const CALLER_HEADERS = [
+  "x-lightsage-api-key",
+  "lightsage-api-key-auth",
+  "x-sapient-api-key",
+  "sapient-api-key-auth",
+  "authorization",
+];
+
+function sha256(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+/**
+ * Every request gets a fresh stateless transport, so there is no MCP session
+ * ID. Group a caller's requests by who they authenticated as (stable across
+ * OAuth token refreshes) and their client; the credential never leaves this
+ * server.
+ */
+export function callerSessionId({ headers }) {
+  const caller = headers[VERIFIED_CALLER_HEADER]?.trim() ||
+    CALLER_HEADERS.map((name) => headers[name]?.trim()).find(Boolean);
+  if (!caller) return undefined;
+  const digest = sha256(`${caller}\n${headers["user-agent"] ?? ""}`);
+  return `mcp_caller_${digest.slice(0, 32)}`;
+}
+
+function decodeHeader(value) {
+  if (!value) return undefined;
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+/** The end user, agent run and request behind a call, and how it authenticated. */
+export function callerContext({ headers }) {
+  const caller = headers[VERIFIED_CALLER_HEADER] ?? "";
+  const oauthUser = caller.startsWith("oauth:") ? caller.slice(6) : undefined;
+  return {
+    distinctId: headers[AGENT_USER_HEADER] || oauthUser,
+    conversationId: headers[AGENT_RUN_HEADER],
+    intent: decodeHeader(headers[AGENT_INTENT_HEADER]),
+    properties: caller
+      ? {
+        auth: oauthUser
+          ? "oauth"
+          : caller.startsWith("key:")
+          ? "api_key"
+          : caller.split(":")[0],
+      }
+      : undefined,
+  };
+}
+
+// Tools that only describe this server's tool catalog.
+const CATALOG_TOOLS = new Set(["list_tools", "describe_tool_input"]);
+
+/**
+ * Tool results hold callers' own Lightsage data, so keep only failures, which
+ * are needed to debug errors. Catalog tools return tool names and schemas, not
+ * data, and their results are how MCP Analytics spots a search that found
+ * nothing.
+ */
+export function shouldStoreResponse({ toolName, isError }) {
+  return isError || CATALOG_TOOLS.has(toolName);
+}
+
+// One tracker per process; each request's server is instrumented separately.
+const lightsage = apiKey
+  ? new Lightsage({
+    apiKey,
+    sessionIdFromRequest: callerSessionId,
+    requestContext: callerContext,
+    captureResponses: shouldStoreResponse,
+  })
+  : null;
+
+export const trackingEnabled = Boolean(lightsage);
+
+/**
+ * Replace a header on the incoming request. The MCP transport rebuilds the
+ * request from rawHeaders, so both views are updated. Removing any value the
+ * caller sent is what makes VERIFIED_CALLER_HEADER trustworthy.
+ */
+function replaceHeader(req, name, value) {
+  const raw = [];
+  for (let i = 0; i < (req.rawHeaders?.length ?? 0); i += 2) {
+    if (req.rawHeaders[i].toLowerCase() !== name) {
+      raw.push(req.rawHeaders[i], req.rawHeaders[i + 1]);
+    }
+  }
+  delete req.headers[name];
+  if (value !== undefined) {
+    raw.push(name, value);
+    req.headers[name] = value;
+  }
+  req.rawHeaders = raw;
+}
+
+/** Drop any caller-supplied verified-caller header. Call first on every request. */
+export function clearVerifiedCaller(req) {
+  replaceHeader(req, VERIFIED_CALLER_HEADER, undefined);
+}
+
+export function setVerifiedCaller(req, caller) {
+  replaceHeader(req, VERIFIED_CALLER_HEADER, caller);
+}
+
+/** "key:<hash>" identity for an API key, without exposing the key. */
+export function apiKeyCaller(key) {
+  return `key:${sha256(key).slice(0, 32)}`;
+}
+
+const KEY_CHECK_TTL_MS = 5 * 60 * 1000;
+const KEY_CHECK_TIMEOUT_MS = 2000;
+const MAX_CACHED_KEYS = 1000;
+const keyChecks = new Map();
+
+/**
+ * Whether a caller's Lightsage API key is real, so calls with made-up keys are
+ * not recorded. Tools that never call the API (list_tools, describe_tool_input)
+ * would otherwise accept any value. Results are cached per key hash; if the
+ * check itself fails (network, timeout), the call is still recorded rather
+ * than losing analytics during an API incident.
+ */
+export async function isTrackedApiKey(key, serverURL, fetchImpl = fetch) {
+  const id = sha256(key);
+  const cached = keyChecks.get(id);
+  if (cached && Date.now() - cached.at < KEY_CHECK_TTL_MS) return cached.valid;
+
+  let valid;
+  try {
+    const response = await fetchImpl(
+      new URL("/v2/auth/status", serverURL),
+      {
+        headers: { "X-Lightsage-Api-Key": key },
+        signal: AbortSignal.timeout(KEY_CHECK_TIMEOUT_MS),
+      },
+    );
+    if (response.status === 401 || response.status === 403) valid = false;
+    else if (response.ok) valid = true;
+  } catch {
+    // Unknown; not cached
+  }
+  if (valid === undefined) return true;
+
+  keyChecks.delete(id);
+  keyChecks.set(id, { valid, at: Date.now() });
+  if (keyChecks.size > MAX_CACHED_KEYS) {
+    keyChecks.delete(keyChecks.keys().next().value);
+  }
+  return valid;
+}
+
+/** Track tool calls, tool listings and the initialize handshake on a server. */
+export function instrumentServer(mcpServer) {
+  lightsage?.instrument(mcpServer);
+}
+
+// Upper bound on how long a request waits for analytics. The tracker aborts
+// its own sends after 2.5s; this also covers a send that ignores the abort,
+// which would otherwise hold the function until maxDuration.
+const FLUSH_TIMEOUT_MS = 3000;
+
+/**
+ * Wait for the response to finish, then send queued events. A tool call is
+ * recorded when its handler returns, which for streamed responses is after
+ * handleRequest resolves, so the send happens after the response ends. Vercel
+ * suspends a function once its response ends, so the send is registered with
+ * waitUntil to keep the invocation alive until it completes (a no-op off
+ * Vercel). Never throws, so analytics cannot fail a request.
+ */
+export function flushTracking(res) {
+  if (!lightsage) return Promise.resolve();
+  let timer;
+  const timeout = new Promise((resolve) => {
+    timer = setTimeout(resolve, FLUSH_TIMEOUT_MS);
+  });
+  const flush = (async () => {
+    await finished(res).catch(() => {});
+    await lightsage.flush();
+  })().catch(() => {
+    // Tracking is best-effort.
+  });
+  const done = Promise.race([flush, timeout]).finally(() => clearTimeout(timer));
+  try {
+    waitUntil(done);
+  } catch {
+    // Not running on Vercel; awaiting the promise is enough.
+  }
+  return done;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightsage/mcp",
-  "version": "0.4.16",
+  "version": "0.4.18",
   "author": "Speakeasy",
   "type": "module",
   "sideEffects": false,
@@ -23,8 +23,10 @@
   "dependencies": {
     "@clerk/backend": "^3.11.4",
     "@clerk/mcp-tools": "^0.5.0",
+    "@lightsage/mcp-tracker": "^0.2.3",
     "@modelcontextprotocol/sdk": "1.32.1",
     "@stricli/core": "^1.1.2",
+    "@vercel/functions": "3.9.11",
     "express": "^5.1.0",
     "zod": "^4.0.0"
   },

package/src/funcs/agentAnalyticsCountriesList.ts

@@ -0,0 +1,160 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ * @generated-id: ccea98d3ab49
+ */
+
+import { LightsageMcpCore } from "../core.js";
+import { encodeFormQuery, encodeSimple } from "../lib/encodings.js";
+import { compactMap } from "../lib/primitives.js";
+import { safeParse } from "../lib/schemas.js";
+import { RequestOptions } from "../lib/sdks.js";
+import { extractSecurity, resolveGlobalSecurity } from "../lib/security.js";
+import { pathToFunc } from "../lib/url.js";
+import { APIError } from "../models/errors/apierror.js";
+import {
+  ConnectionError,
+  InvalidRequestError,
+  RequestAbortedError,
+  RequestTimeoutError,
+  UnexpectedClientError,
+} from "../models/errors/httpclienterrors.js";
+import { SDKValidationError } from "../models/errors/sdkvalidationerror.js";
+import {
+  V2AgentAnalyticsCountriesListRequest,
+  V2AgentAnalyticsCountriesListRequest$zodSchema,
+} from "../models/v2agentanalyticscountrieslistop.js";
+import { APICall, APIPromise } from "../types/async.js";
+import { Result } from "../types/fp.js";
+
+/**
+ * List Agent Analytics Countries
+ *
+ * @remarks
+ * Returns a site's visits from coding agents and AI assistants per country in the date range, most visits first.
+ */
+export function agentAnalyticsCountriesList(
+  client$: LightsageMcpCore,
+  request: V2AgentAnalyticsCountriesListRequest,
+  options?: RequestOptions,
+): APIPromise<
+  Result<
+    Response,
+    | APIError
+    | SDKValidationError
+    | UnexpectedClientError
+    | InvalidRequestError
+    | RequestAbortedError
+    | RequestTimeoutError
+    | ConnectionError
+  >
+> {
+  return new APIPromise($do(
+    client$,
+    request,
+    options,
+  ));
+}
+
+async function $do(
+  client$: LightsageMcpCore,
+  request: V2AgentAnalyticsCountriesListRequest,
+  options?: RequestOptions,
+): Promise<
+  [
+    Result<
+      Response,
+      | APIError
+      | SDKValidationError
+      | UnexpectedClientError
+      | InvalidRequestError
+      | RequestAbortedError
+      | RequestTimeoutError
+      | ConnectionError
+    >,
+    APICall,
+  ]
+> {
+  const parsed$ = safeParse(
+    request,
+    (value$) => V2AgentAnalyticsCountriesListRequest$zodSchema.parse(value$),
+    "Input validation failed",
+  );
+  if (!parsed$.ok) {
+    return [parsed$, { status: "invalid" }];
+  }
+  const payload$ = parsed$.value;
+  const body$ = null;
+
+  const pathParams$ = {
+    site_id: encodeSimple("site_id", payload$.site_id, {
+      explode: false,
+      charEncoding: "percent",
+    }),
+  };
+  const path$ = pathToFunc("/v2/agent-analytics/sites/{site_id}/countries")(
+    pathParams$,
+  );
+  const query$ = encodeFormQuery({
+    "end_date": payload$.end_date,
+    "limit": payload$.limit,
+    "period": payload$.period,
+    "start_date": payload$.start_date,
+  });
+
+  const headers$ = new Headers(compactMap({
+    Accept: "application/json",
+  }));
+  const securityInput = await extractSecurity(client$._options.security);
+  const requestSecurity = resolveGlobalSecurity(securityInput);
+
+  const context = {
+    options: client$._options,
+    baseURL: options?.serverURL ?? client$._baseURL ?? "",
+    operationID: "v2_agent_analytics_countries_list",
+    oAuth2Scopes: null,
+    resolvedSecurity: requestSecurity,
+    securitySource: client$._options.security,
+    retryConfig: options?.retries
+      || client$._options.retryConfig
+      || { strategy: "none" },
+    retryCodes: options?.retryCodes || [
+      "429",
+      "500",
+      "502",
+      "503",
+      "504",
+    ],
+  };
+
+  const requestRes = client$._createRequest(context, {
+    security: requestSecurity,
+    method: "GET",
+    baseURL: options?.serverURL,
+    path: path$,
+    headers: headers$,
+    query: query$,
+    body: body$,
+    userAgent: client$._options.userAgent,
+    timeoutMs: options?.timeoutMs || client$._options.timeoutMs
+      || -1,
+  }, options);
+  if (!requestRes.ok) {
+    return [requestRes, { status: "invalid" }];
+  }
+  const req$ = requestRes.value;
+
+  const doResult = await client$._do(req$, {
+    context,
+    errorCodes: [],
+    retryConfig: context.retryConfig,
+    retryCodes: context.retryCodes,
+  });
+  if (!doResult.ok) {
+    return [doResult, { status: "request-error", request: req$ }];
+  }
+  return [doResult, {
+    status: "complete",
+    "request": req$,
+    response: doResult.value,
+  }];
+}