@knownagents/sdk 2.5.0 → 3.1.0

package/README.md

@@ -33,86 +33,90 @@ const knownAgents = new KnownAgents("YOUR_ACCESS_TOKEN", {
 
 The entire visit event queue is uploaded when it reaches `flushQueueSize` or when the flush interval elapses after the first visit event enters an empty queue.
 
-## Send Visit Events ([Agent Analytics](https://knownagents.com/products/agent-analytics), [LLM Referral Tracking](https://knownagents.com/products/llm-referral-tracking))
-
-Get realtime insight into how [AI agents and other bots](https://knownagents.com/agents) browse your web pages, call your [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) endpoints, and purchase products through your [ACP (Agentic Commerce Protocol)](https://www.agenticcommerce.dev/) and [UCP (Universal Commerce Protocol)](https://ucp.dev/) shopping flows. Measure human traffic from AI chat and search platforms like ChatGPT, Claude, and Gemini.
-
-### Pageviews and REST Calls
-
-Call `trackPageviewOrRESTCall` with the incoming request and outgoing response. If you can, do this in middleware. This method skips MCP calls automatically.
+Before your application shuts down, call `flush` to upload any queued visit events:
 
 ```ts
-knownAgents.trackPageviewOrRESTCall(request, response)
+await knownAgents.flush()
 ```
 
-### MCP Calls (Optional)
+## Track Pageviews and API Calls ([Agent Analytics](https://knownagents.com/products/agent-analytics), [LLM Referral Tracking](https://knownagents.com/products/llm-referral-tracking))
 
-For MCP servers that use `StreamableHTTPServerTransport`, call `trackMCPCall` after connecting the transport and before the transport handles the request.
-
-```ts
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js"
+Get realtime insight into how [AI agents and other bots](https://knownagents.com/agents) browse your web pages, use your [MCP](https://modelcontextprotocol.io/) (Model Context Protocol) server, and purchase products through your [ACP](https://www.agenticcommerce.dev/) (Agentic Commerce Protocol) and [UCP](https://ucp.dev/) (Universal Commerce Protocol) shopping flows. Measure human traffic from AI chat and search platforms like ChatGPT, Claude, and Gemini.
 
-// ...
+Call `trackVisit` with the incoming request and outgoing response.
 
-const mcpServer = new McpServer({
-    name: SERVER_NAME,
-    version: SERVER_VERSION,
-})
-
-const transport = new StreamableHTTPServerTransport({
-    sessionIdGenerator: undefined
-})
+```ts
+knownAgents.trackVisit(request, response)
+```
 
-// ...
+If you can, do this in middleware.
 
-await mcpServer.connect(transport)
+### MCP
 
-knownAgents.trackMCPCall(request, response, transport)
+For MCP endpoints, call `trackVisit` from each tool handler.
 
-await transport.handleRequest(request, response, parsedBody)
+```ts
+import { createMcpHandler, McpServer } from "@modelcontextprotocol/server"
+
+const mcpHandler = createMcpHandler(({ requestInfo }) => {
+    const server = new McpServer({
+        name: SERVER_NAME,
+        version: SERVER_VERSION,
+    })
+
+    server.registerTool("ping", { description: "Check whether the server is available" }, async (context) => {
+        const result = {
+            content: [{ type: "text", text: "pong" }]
+        }
+
+        knownAgents.trackVisit(requestInfo, undefined, {
+            mcp: {
+                context: context,
+                result: result
+            }
+        })
+
+        return result
+    })
+
+    return server
+})
 ```
 
-### Agentic Commerce Interactions (Optional)
+### Agentic Commerce
 
-For REST implementations of ACP and UCP, include the response body in `trackPageviewOrRESTCall`.
+For ACP and UCP endpoints, include the response body in `trackVisit`.
 
 ```ts
 // For ACP calls ...
 
-knownAgents.trackPageviewOrRESTCall(request, response, {
-    acpResponseBody: acpResponseBody
+knownAgents.trackVisit(request, response, {
+    acp: {
+        responseBody: acpResponseBody
+    }
 })
 ```
 
 ```ts
 // For UCP calls ...
 
-knownAgents.trackPageviewOrRESTCall(request, response, {
-    ucpResponseBody: ucpResponseBody
+knownAgents.trackVisit(request, response, {
+    ucp: {
+        responseBody: ucpResponseBody
+    }
 })
 ```
 
-`trackMCPCall` will track MCP implementations of ACP and UCP automatically.
-
-### Test Your Integration
-
-- Open your project's settings page
-- Click **Send a Test Visit**
-- Click **Realtime**
-
-If your website is correctly connected, you should see visits from a test agent in the realtime timeline within a few seconds.
-
-## Set Up Automatic Robots.txt ([Automatic Robots.txt](https://knownagents.com/products/automatic-robots-txt))
+## Serve an Automatic Robots.txt ([Automatic Robots.txt](https://knownagents.com/products/automatic-robots-txt))
 
-Serve a robots.txt that continuously updates with rules for new [crawlers, scrapers, AI agents, and other bots](https://knownagents.com/agents) as they're discovered.
+Generate a robots.txt that continuously updates with rules for new [crawlers, scrapers, AI agents, and other bots](https://knownagents.com/agents) as they're discovered.
 
-Use the `generateRobotsTXT` method. Select which `AgentType`s you want to block, and a string specifying which URLs are disallowed (e.g. `"/"` to disallow all paths).
+Use the `generateRobotsTxt` method. Select which `AgentType`s you want to block, and a string specifying which URLs are disallowed (e.g. `"/"` to disallow all paths).
 
 ```ts
 import { AgentType } from "@knownagents/sdk"
 
-const robotsTxt = await knownAgents.generateRobotsTXT([
+const robotsTxt = await knownAgents.generateRobotsTxt([
     AgentType.AIDataScraper,
     AgentType.AIDataProvider,
     AgentType.Scraper,
@@ -122,7 +126,7 @@ const robotsTxt = await knownAgents.generateRobotsTXT([
 
 The return value is a plain text robots.txt string. Generate a `robotsTxt` periodically (e.g. once per day, using a cron job). Then, serve it from your website's `/robots.txt` endpoint.
 
-## Use the Agent Identification API ([Agent Identification API](https://knownagents.com/products/agent-identification-api))
+## Identify & Verify Agents ([Agent Identification](https://knownagents.com/products/agent-identification-api))
 
 Identify and verify [AI agents and other bots](https://knownagents.com/agents) in your own products, from incoming network requests. Authentication uses Web Bot Auth (HTTP message signatures), IP matching, or other available methods. This API can be useful for implementing access policies based on verified agent identity or enriching your own datasets.
 
@@ -194,7 +198,7 @@ TypeScript >= 4.7 is supported.
 
 The following runtimes are supported:
 
-- Node.js 18 LTS or later ([non-EOL](https://endoflife.date/nodejs))
+- Node.js 20 or later (Node.js 24 LTS recommended)
 
 ## Support
 

package/dist/KnownAgents.d.ts

@@ -1,6 +1,5 @@
 import type { IncomingMessage, ServerResponse } from "http";
-import type { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import type { AgentType, IdentificationRequest, IdentificationResult, KnownAgentsOptions, TrackPageviewOrRESTCallOptions, VisitRequest } from "./types";
+import type { AgentType, IdentificationRequest, IdentificationResult, KnownAgentsOptions, TrackVisitOptions } from "./types";
 /**
  * Server-side client for Known Agents analytics, robots.txt generation, and agent identification.
  */
@@ -19,34 +18,15 @@ export declare class KnownAgents {
      */
     constructor(accessToken: string, options?: KnownAgentsOptions);
     /**
-     * Tracks a single non-MCP pageview or REST API call for analytics.
-     * The visit is added to the visit event queue after the response finishes so status, headers, and duration are included.
+     * Tracks a single pageview or API call for analytics.
+     * For Node.js responses, the visit is added to the visit event queue after the response finishes so status, headers, and duration are included.
      * This method is non-blocking and handles upload errors internally.
      *
-     * @param request - The incoming Node.js HTTP request.
-     * @param response - The outgoing Node.js HTTP response.
-     * @param options - Optional ACP or UCP response metadata for REST API calls.
-     */
-    trackPageviewOrRESTCall(request: IncomingMessage, response: ServerResponse, options?: TrackPageviewOrRESTCallOptions): void;
-    /**
-     * Tracks a single MCP call handled by `StreamableHTTPServerTransport`.
-     * Call this after connecting the transport and before the transport processes the request so request and response metadata can be captured.
-     * Do not use this with transport instances shared across concurrent requests; use `trackVisits()` instead.
-     * This method is non-blocking and handles upload errors internally.
-     *
-     * @param request - The incoming Node.js HTTP request.
-     * @param response - The outgoing Node.js HTTP response.
-     * @param transport - The MCP streamable HTTP transport handling the request.
-     */
-    trackMCPCall(request: IncomingMessage, response: ServerResponse, transport: StreamableHTTPServerTransport): void;
-    /**
-     * Adds multiple visits to the visit event queue for analytics.
-     * This method is non-blocking and handles upload errors internally.
-     * All visit events are uploaded together when the queue size reaches the configured threshold or the flush interval elapses.
-     *
-     * @param requests - An array of visits.
+     * @param request - The incoming HTTP request.
+     * @param response - The outgoing HTTP response.
+     * @param options - Optional protocol metadata.
      */
-    trackVisits(requests: VisitRequest[]): void;
+    trackVisit(request: IncomingMessage | Request, response?: ServerResponse | Response, options?: TrackVisitOptions): void;
     /**
      * Uploads all events currently in the visit event queue and waits for pending uploads to finish.
      * This method handles upload errors internally.
@@ -64,7 +44,7 @@ export declare class KnownAgents {
      * @returns A promise that resolves to the generated robots.txt content as a string.
      * @throws {Error} If the API call fails or returns a non-200 status.
      */
-    generateRobotsTXT(agentTypes: AgentType[], disallow?: string): Promise<string>;
+    generateRobotsTxt(agentTypes: AgentType[], disallow?: string): Promise<string>;
     /**
      * Identifies and verifies a single agent from an HTTP request.
      * Uses Web Bot Auth (HTTP message signatures), IP matching, or other available methods.
@@ -83,6 +63,7 @@ export declare class KnownAgents {
      * @throws {Error} If the API call fails or returns a non-200 status.
      */
     identifyAgents(requests: IdentificationRequest[]): Promise<IdentificationResult[]>;
+    private enqueueVisit;
     private scheduleFlush;
     private sendVisits;
 }

package/dist/KnownAgents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"KnownAgents.d.ts","sourceRoot":"","sources":["../src/KnownAgents.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,MAAM,CAAA;AAC3D,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,oDAAoD,CAAA;AAGvG,OAAO,KAAK,EACR,SAAS,EACT,qBAAqB,EACrB,oBAAoB,EACpB,kBAAkB,EAClB,8BAA8B,EAC9B,YAAY,EACf,MAAM,SAAS,CAAA;AAKhB;;GAEG;AACH,qBAAa,WAAW;IACpB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAQ;IACpC,OAAO,CAAC,QAAQ,CAAC,2BAA2B,CAAQ;IACpD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAQ;IACvC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;IAChD,OAAO,CAAC,YAAY,CAA4B;IAChD,OAAO,CAAC,mBAAmB,CAAmC;IAE9D;;;;;OAKG;gBACS,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB;IAMjE;;;;;;;;OAQG;IACH,uBAAuB,CAAC,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,8BAA8B,GAAG,IAAI;IAoC3H;;;;;;;;;OASG;IACH,YAAY,CAAC,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,cAAc,EAAE,SAAS,EAAE,6BAA6B,GAAG,IAAI;IAoEhH;;;;;;OAMG;IACH,WAAW,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,IAAI;IA2B3C;;;;;OAKG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAmBtB;;;;;;;;;OASG;IACG,iBAAiB,CAAC,UAAU,EAAE,SAAS,EAAE,EAAE,QAAQ,GAAE,MAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IAoBzF;;;;;;;OAOG;IACG,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAqB5E;;;;;;;OAOG;IACG,cAAc,CAAC,QAAQ,EAAE,qBAAqB,EAAE,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAsBxF,OAAO,CAAC,aAAa;YAaP,UAAU;CAmB3B"}
+{"version":3,"file":"KnownAgents.d.ts","sourceRoot":"","sources":["../src/KnownAgents.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,MAAM,CAAA;AAI3D,OAAO,KAAK,EACR,SAAS,EACT,qBAAqB,EACrB,oBAAoB,EACpB,kBAAkB,EAClB,iBAAiB,EAEpB,MAAM,SAAS,CAAA;AAMhB;;GAEG;AACH,qBAAa,WAAW;IACpB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAQ;IACpC,OAAO,CAAC,QAAQ,CAAC,2BAA2B,CAAQ;IACpD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAQ;IACvC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;IAChD,OAAO,CAAC,YAAY,CAA4B;IAChD,OAAO,CAAC,mBAAmB,CAAmC;IAE9D;;;;;OAKG;gBACS,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB;IAMjE;;;;;;;;OAQG;IACH,UAAU,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,EAAE,QAAQ,CAAC,EAAE,cAAc,GAAG,QAAQ,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,IAAI;IAsDvH;;;;;OAKG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAmBtB;;;;;;;;;OASG;IACG,iBAAiB,CAAC,UAAU,EAAE,SAAS,EAAE,EAAE,QAAQ,GAAE,MAAY,GAAG,OAAO,CAAC,MAAM,CAAC;IAqBzF;;;;;;;OAOG;IACG,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAsB5E;;;;;;;OAOG;IACG,cAAc,CAAC,QAAQ,EAAE,qBAAqB,EAAE,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAuBxF,OAAO,CAAC,YAAY;IAepB,OAAO,CAAC,aAAa;YAaP,UAAU;CAwB3B"}

package/dist/KnownAgents.js

@@ -1,10 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KnownAgents = void 0;
+const server_1 = require("@modelcontextprotocol/server");
 const headers_1 = require("./headers");
 const paths_1 = require("./paths");
 const DEFAULT_FLUSH_INTERVAL_IN_MILLISECONDS = 10000;
 const DEFAULT_FLUSH_QUEUE_SIZE = 1;
+const NODE_PACKAGE_VERSION = "3.1.0";
 /**
  * Server-side client for Known Agents analytics, robots.txt generation, and agent identification.
  */
@@ -23,103 +25,52 @@ class KnownAgents {
         this.flushQueueSize = options.flushQueueSize ?? DEFAULT_FLUSH_QUEUE_SIZE;
     }
     /**
-     * Tracks a single non-MCP pageview or REST API call for analytics.
-     * The visit is added to the visit event queue after the response finishes so status, headers, and duration are included.
+     * Tracks a single pageview or API call for analytics.
+     * For Node.js responses, the visit is added to the visit event queue after the response finishes so status, headers, and duration are included.
      * This method is non-blocking and handles upload errors internally.
      *
-     * @param request - The incoming Node.js HTTP request.
-     * @param response - The outgoing Node.js HTTP response.
-     * @param options - Optional ACP or UCP response metadata for REST API calls.
+     * @param request - The incoming HTTP request.
+     * @param response - The outgoing HTTP response.
+     * @param options - Optional protocol metadata.
      */
-    trackPageviewOrRESTCall(request, response, options) {
-        const isMCPCall = (0, headers_1.getIsMCPCall)(request.headers);
-        const path = request.url;
+    trackVisit(request, response, options) {
+        const url = request instanceof Request ? new URL(request.url) : undefined;
+        const requestHeaders = request instanceof Request ? Object.fromEntries(request.headers) : request.headers;
+        const mcpRequestName = (0, headers_1.getHeaderValue)(requestHeaders, "mcp-name");
+        const path = url ? `${url.pathname}${url.search}` : request.url;
         const method = request.method;
-        if (isMCPCall || !path || (0, paths_1.getIsPathExcluded)(path) || !method) {
+        if (!path || (0, paths_1.isPathExcluded)(path) || !method) {
             return;
         }
         const created = new Date();
         const sendVisit = () => {
-            const responseDurationInMilliseconds = Date.now() - created.getTime();
+            const responseHeaders = response instanceof Response ? Object.fromEntries(response.headers.entries()) : response?.getHeaders() ?? {};
+            const responseStatusCode = response instanceof Response ? response.status : response?.statusCode;
+            const responseDurationInMilliseconds = options?.responseDurationInMilliseconds ?? (!response || response instanceof Response ? undefined : Date.now() - created.getTime());
+            const mcp = options?.mcp;
+            const clientInfo = mcp?.context?.mcpReq.envelope?.[server_1.CLIENT_INFO_META_KEY];
             const visitRequest = {
                 request_path: path,
                 request_method: method,
-                request_headers: request.headers,
-                response_status_code: response?.statusCode,
-                response_headers: response.getHeaders(),
+                request_headers: requestHeaders,
+                response_status_code: responseStatusCode,
+                response_headers: responseHeaders,
                 response_duration_in_milliseconds: responseDurationInMilliseconds,
-                acp_response_body: options?.acpResponseBody,
-                ucp_response_body: options?.ucpResponseBody,
+                mcp_request_method: mcp?.context?.mcpReq.method,
+                mcp_request_name: mcpRequestName,
+                mcp_request_client_info_name: clientInfo?.name,
+                mcp_request_client_info_version: clientInfo?.version,
+                mcp_response_result_is_error: mcp?.result?.isError,
+                acp_response_body: options?.acp?.responseBody,
+                ucp_response_body: options?.ucp?.responseBody,
                 created: created.toISOString()
             };
-            this.trackVisits([visitRequest]);
+            this.enqueueVisit(visitRequest);
         };
-        if (response.writableEnded) {
+        if (!response || response instanceof Response) {
             sendVisit();
-        }
-        else {
-            response.once("finish", sendVisit);
-        }
-    }
-    /**
-     * Tracks a single MCP call handled by `StreamableHTTPServerTransport`.
-     * Call this after connecting the transport and before the transport processes the request so request and response metadata can be captured.
-     * Do not use this with transport instances shared across concurrent requests; use `trackVisits()` instead.
-     * This method is non-blocking and handles upload errors internally.
-     *
-     * @param request - The incoming Node.js HTTP request.
-     * @param response - The outgoing Node.js HTTP response.
-     * @param transport - The MCP streamable HTTP transport handling the request.
-     */
-    trackMCPCall(request, response, transport) {
-        const path = request.url;
-        const method = request.method;
-        if (!path || (0, paths_1.getIsPathExcluded)(path) || !method) {
             return;
         }
-        const created = new Date();
-        let mcpRequestBody;
-        let mcpResponseBody;
-        const originalTransportOnMessage = transport.onmessage;
-        transport.onmessage = (message, extra) => {
-            mcpRequestBody = message;
-            originalTransportOnMessage?.(message, extra);
-        };
-        const originalTransportSend = transport.send;
-        transport.send = async (message, options) => {
-            mcpResponseBody = message;
-            await originalTransportSend.call(transport, message, options);
-        };
-        const restoreTransport = () => {
-            transport.onmessage = originalTransportOnMessage;
-            transport.send = originalTransportSend;
-        };
-        const sendVisit = () => {
-            restoreTransport();
-            if (!mcpRequestBody || !mcpResponseBody) {
-                return;
-            }
-            const responseDurationInMilliseconds = Date.now() - created.getTime();
-            const visitRequest = {
-                request_path: path,
-                request_method: method,
-                request_headers: request.headers,
-                response_status_code: response?.statusCode,
-                response_headers: response.getHeaders(),
-                response_duration_in_milliseconds: responseDurationInMilliseconds,
-                mcp_request_method: mcpRequestBody.method,
-                mcp_request_name: mcpRequestBody.params?.name,
-                mcp_request_client_info_name: mcpRequestBody.params?.clientInfo?.name,
-                mcp_request_client_info_version: mcpRequestBody.params?.clientInfo?.version,
-                mcp_response_result_is_error: mcpResponseBody.result?.isError,
-                mcp_response_error_code: mcpResponseBody.error?.code,
-                mcp_response_error_message: mcpResponseBody.error?.message,
-                acp_response_body: (0, headers_1.getIsACPCall)(request.headers) ? mcpResponseBody.result : undefined,
-                ucp_response_body: (0, headers_1.getIsUCPCall)(request.headers) ? mcpResponseBody.result : undefined,
-                created: created.toISOString()
-            };
-            this.trackVisits([visitRequest]);
-        };
         if (response.writableEnded) {
             sendVisit();
         }
@@ -127,35 +78,6 @@ class KnownAgents {
             response.once("finish", sendVisit);
         }
     }
-    /**
-     * Adds multiple visits to the visit event queue for analytics.
-     * This method is non-blocking and handles upload errors internally.
-     * All visit events are uploaded together when the queue size reaches the configured threshold or the flush interval elapses.
-     *
-     * @param requests - An array of visits.
-     */
-    trackVisits(requests) {
-        const filteredRequests = requests
-            .filter((request) => {
-            return !(0, paths_1.getIsPathExcluded)(request.request_path);
-        })
-            .map((request) => {
-            return {
-                ...request,
-                request_headers: (0, headers_1.getFilteredHeaders)(request.request_headers),
-                response_headers: request.response_headers ? (0, headers_1.getFilteredHeaders)(request.response_headers) : undefined,
-            };
-        });
-        if (filteredRequests.length === 0) {
-            return;
-        }
-        this.visitQueue.push(...filteredRequests);
-        if (this.visitQueue.length >= this.flushQueueSize) {
-            void this.flush();
-            return;
-        }
-        this.scheduleFlush();
-    }
     /**
      * Uploads all events currently in the visit event queue and waits for pending uploads to finish.
      * This method handles upload errors internally.
@@ -186,7 +108,7 @@ class KnownAgents {
      * @returns A promise that resolves to the generated robots.txt content as a string.
      * @throws {Error} If the API call fails or returns a non-200 status.
      */
-    async generateRobotsTXT(agentTypes, disallow = "/") {
+    async generateRobotsTxt(agentTypes, disallow = "/") {
         const response = await fetch("https://api.knownagents.com/robots-txts", {
             method: "POST",
             headers: {
@@ -195,7 +117,8 @@ class KnownAgents {
             },
             body: JSON.stringify({
                 agent_types: agentTypes,
-                disallow: disallow
+                disallow: disallow,
+                node_package_version: NODE_PACKAGE_VERSION
             })
         });
         if (response.ok) {
@@ -221,9 +144,10 @@ class KnownAgents {
                 "Content-Type": "application/json"
             },
             body: JSON.stringify({
-                request_headers: (0, headers_1.getFilteredHeaders)(request.headers),
+                request_headers: (0, headers_1.filterHeaders)(request.headers),
                 request_ip: request.socket.remoteAddress,
-                request_path: request.url
+                request_path: request.url,
+                node_package_version: NODE_PACKAGE_VERSION
             })
         });
         if (response.ok) {
@@ -251,7 +175,8 @@ class KnownAgents {
             body: JSON.stringify(requests.map((request) => {
                 return {
                     ...request,
-                    request_headers: (0, headers_1.getFilteredHeaders)(request.request_headers),
+                    request_headers: (0, headers_1.filterHeaders)(request.request_headers),
+                    node_package_version: NODE_PACKAGE_VERSION
                 };
             }))
         });
@@ -262,6 +187,18 @@ class KnownAgents {
             throw new Error(`Known Agents failed to identify agents: ${response.status} ${response.statusText}`);
         }
     }
+    enqueueVisit(request) {
+        this.visitQueue.push({
+            ...request,
+            request_headers: (0, headers_1.filterHeaders)(request.request_headers),
+            response_headers: request.response_headers ? (0, headers_1.filterHeaders)(request.response_headers) : undefined,
+        });
+        if (this.visitQueue.length >= this.flushQueueSize) {
+            void this.flush();
+            return;
+        }
+        this.scheduleFlush();
+    }
     scheduleFlush() {
         if (this.flushTimeout) {
             return;
@@ -280,7 +217,12 @@ class KnownAgents {
                     "Authorization": `Bearer ${this.accessToken}`,
                     "Content-Type": "application/json"
                 },
-                body: JSON.stringify(requests)
+                body: JSON.stringify(requests.map((request) => {
+                    return {
+                        ...request,
+                        node_package_version: NODE_PACKAGE_VERSION
+                    };
+                }))
             });
             if (!response.ok) {
                 throw new Error(`${response.status} ${response.statusText}`);

package/dist/headers.d.ts

@@ -1,6 +1,4 @@
 import type { IncomingHttpHeaders, OutgoingHttpHeaders } from "http";
-export declare function getFilteredHeaders<Headers extends IncomingHttpHeaders | OutgoingHttpHeaders>(headers: Headers): Headers;
-export declare function getIsMCPCall(headers: IncomingHttpHeaders): boolean;
-export declare function getIsUCPCall(headers: IncomingHttpHeaders): boolean;
-export declare function getIsACPCall(headers: IncomingHttpHeaders): boolean;
+export declare function getHeaderValue(headers: IncomingHttpHeaders | OutgoingHttpHeaders, headerName: string): string | undefined;
+export declare function filterHeaders<Headers extends IncomingHttpHeaders | OutgoingHttpHeaders>(headers: Headers): Headers;
 //# sourceMappingURL=headers.d.ts.map

package/dist/headers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"headers.d.ts","sourceRoot":"","sources":["../src/headers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,MAAM,CAAA;AA2BpE,wBAAgB,kBAAkB,CAAC,OAAO,SAAS,mBAAmB,GAAG,mBAAmB,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAUvH;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAIlE;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAIlE;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAIlE"}
+{"version":3,"file":"headers.d.ts","sourceRoot":"","sources":["../src/headers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,MAAM,CAAA;AA2BpE,wBAAgB,cAAc,CAAC,OAAO,EAAE,mBAAmB,GAAG,mBAAmB,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAiBzH;AAED,wBAAgB,aAAa,CAAC,OAAO,SAAS,mBAAmB,GAAG,mBAAmB,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAUlH"}

package/dist/headers.js

@@ -1,9 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getFilteredHeaders = getFilteredHeaders;
-exports.getIsMCPCall = getIsMCPCall;
-exports.getIsUCPCall = getIsUCPCall;
-exports.getIsACPCall = getIsACPCall;
+exports.getHeaderValue = getHeaderValue;
+exports.filterHeaders = filterHeaders;
 const filteredHeaderNames = [
     "authorization",
     "proxy-authorization",
@@ -28,7 +26,21 @@ const filteredHeaderNames = [
     "client-secret",
     "private-token"
 ];
-function getFilteredHeaders(headers) {
+function getHeaderValue(headers, headerName) {
+    const normalizedHeaderName = headerName.toLowerCase();
+    const matchingHeaderName = Object.keys(headers).find((candidate) => {
+        return candidate.toLowerCase() === normalizedHeaderName;
+    });
+    if (!matchingHeaderName) {
+        return undefined;
+    }
+    const headerValue = headers[matchingHeaderName];
+    if (Array.isArray(headerValue)) {
+        return headerValue[0];
+    }
+    return headerValue?.toString();
+}
+function filterHeaders(headers) {
     const filteredHeaders = { ...headers };
     Object.keys(filteredHeaders).forEach((key) => {
         if (filteredHeaderNames.includes(key.toLowerCase())) {
@@ -37,18 +49,3 @@ function getFilteredHeaders(headers) {
     });
     return filteredHeaders;
 }
-function getIsMCPCall(headers) {
-    return Object.keys(headers).some((key) => {
-        return key.toLowerCase() === "mcp-protocol-version";
-    });
-}
-function getIsUCPCall(headers) {
-    return Object.keys(headers).some((key) => {
-        return key.toLowerCase() === "ucp-agent";
-    });
-}
-function getIsACPCall(headers) {
-    return Object.keys(headers).some((key) => {
-        return key.toLowerCase() === "api-version";
-    });
-}

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 export { KnownAgents } from "./KnownAgents";
-export { AgentType, type IdentificationRequest, type IdentificationResult, type KnownAgentsOptions, type TrackPageviewOrRESTCallOptions, type VisitRequest } from "./types";
+export { AgentType, type IdentificationRequest, type IdentificationResult, type KnownAgentsOptions, type TrackVisitOptions } from "./types";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,EACH,SAAS,EACT,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACvB,KAAK,8BAA8B,EACnC,KAAK,YAAY,EACpB,MAAM,SAAS,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,EACH,SAAS,EACT,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACzB,MAAM,SAAS,CAAA"}

package/dist/paths.d.ts

@@ -1,2 +1,2 @@
-export declare function getIsPathExcluded(path: string): boolean;
+export declare function isPathExcluded(path: string): boolean;
 //# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAuEvD"}
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAuEpD"}

package/dist/paths.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getIsPathExcluded = getIsPathExcluded;
-function getIsPathExcluded(path) {
+exports.isPathExcluded = isPathExcluded;
+function isPathExcluded(path) {
     const pathWithoutQueryString = path.split(/[?#]/)[0];
     const lowercasedPath = pathWithoutQueryString.toLowerCase();
     const excludedPrefixes = [

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 import type { IncomingHttpHeaders, OutgoingHttpHeaders } from "http";
+import type { CallToolResult, ServerContext } from "@modelcontextprotocol/server";
 /**
  * Batching configuration for the Known Agents client.
  */
@@ -9,17 +10,23 @@ export interface KnownAgentsOptions {
     flushQueueSize?: number;
 }
 /**
- * Additional metadata to include when tracking a pageview or REST API call.
+ * Additional metadata to include when tracking a visit.
  */
-export interface TrackPageviewOrRESTCallOptions {
-    /** The ACP response body. */
-    acpResponseBody?: Record<string, unknown>;
-    /** The UCP response body. */
-    ucpResponseBody?: Record<string, unknown>;
+export interface TrackVisitOptions {
+    responseDurationInMilliseconds?: number;
+    mcp?: {
+        context?: ServerContext;
+        result?: CallToolResult;
+    };
+    acp?: {
+        responseBody: Record<string, unknown>;
+    };
+    ucp?: {
+        responseBody: Record<string, unknown>;
+    };
 }
 /**
- * A normalized visit payload for the Known Agents API.
- * Use this with `trackVisits()` to manually add visit events to the queue.
+ * The normalized visit payload sent to the Known Agents API.
  */
 export interface VisitRequest {
     /** The URL path and query string of the request (e.g. "/about?foo=bar") */
@@ -44,10 +51,6 @@ export interface VisitRequest {
     mcp_request_client_info_version?: string;
     /** Whether the MCP response result is an error */
     mcp_response_result_is_error?: boolean;
-    /** The MCP response error code */
-    mcp_response_error_code?: number;
-    /** The MCP response error message */
-    mcp_response_error_message?: string;
     /** The ACP response body */
     acp_response_body?: Record<string, unknown>;
     /** The UCP response body */

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,MAAM,CAAA;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAA;AAEjF;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAC/B,yGAAyG;IACzG,2BAA2B,CAAC,EAAE,MAAM,CAAA;IACpC,sFAAsF;IACtF,cAAc,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAC9B,8BAA8B,CAAC,EAAE,MAAM,CAAA;IACvC,GAAG,CAAC,EAAE;QACF,OAAO,CAAC,EAAE,aAAa,CAAA;QACvB,MAAM,CAAC,EAAE,cAAc,CAAA;KAC1B,CAAA;IACD,GAAG,CAAC,EAAE;QACF,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KACxC,CAAA;IACD,GAAG,CAAC,EAAE;QACF,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KACxC,CAAA;CACJ;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IACzB,2EAA2E;IAC3E,YAAY,EAAE,MAAM,CAAA;IACpB,2CAA2C;IAC3C,cAAc,EAAE,MAAM,CAAA;IACtB,8EAA8E;IAC9E,eAAe,EAAE,mBAAmB,CAAA;IACpC,oDAAoD;IACpD,oBAAoB,CAAC,EAAE,MAAM,CAAA;IAC7B,+EAA+E;IAC/E,gBAAgB,CAAC,EAAE,mBAAmB,CAAA;IACtC,4CAA4C;IAC5C,iCAAiC,CAAC,EAAE,MAAM,CAAA;IAC1C,sCAAsC;IACtC,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,gCAAgC;IAChC,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,kCAAkC;IAClC,4BAA4B,CAAC,EAAE,MAAM,CAAA;IACrC,qCAAqC;IACrC,+BAA+B,CAAC,EAAE,MAAM,CAAA;IACxC,kDAAkD;IAClD,4BAA4B,CAAC,EAAE,OAAO,CAAA;IACtC,4BAA4B;IAC5B,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC3C,4BAA4B;IAC5B,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC3C,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IAClC,4IAA4I;IAC5I,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,iQAAiQ;IACjQ,eAAe,EAAE,mBAAmB,CAAA;IACpC,0JAA0J;IAC1J,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,iEAAiE;IACjE,YAAY,CAAC,EAAE,MAAM,CAAA;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACjC,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;;OAMG;IACH,MAAM,EAAE,UAAU,GAAG,qBAAqB,GAAG,gBAAgB,GAAG,gBAAgB,CAAA;IAChF,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,iEAAiE;IACjE,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,4EAA4E;IAC5E,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,kGAAkG;IAClG,2BAA2B,CAAC,EAAE,OAAO,CAAA;IACrC,6EAA6E;IAC7E,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,iGAAiG;IACjG,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,KAAK,GAAG,SAAS,GAAG,UAAU,GAAG,WAAW,GAAG,YAAY,CAAA;IACtE,sSAAsS;IACtS,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB;;;;;;;OAOG;IACH,kBAAkB,CAAC,EAAE,KAAK,CACtB,gBAAgB,GACd,eAAe,GACf,aAAa,GACb,mBAAmB,GACnB,wBAAwB,CAC7B,CAAA;CACJ;AAED;;GAEG;AACH,oBAAY,SAAS;IACjB,OAAO,aAAa;IACpB,WAAW,iBAAiB;IAC5B,aAAa,oBAAoB;IACjC,cAAc,qBAAqB;IACnC,aAAa,oBAAoB;IACjC,eAAe,sBAAsB;IACrC,QAAQ,aAAa;IACrB,cAAc,oBAAoB;IAClC,eAAe,qBAAqB;IACpC,OAAO,YAAY;IACnB,oBAAoB,0BAA0B;IAC9C,OAAO,YAAY;IACnB,UAAU,gBAAgB;IAC1B,mBAAmB,0BAA0B;IAC7C,eAAe,qBAAqB;IACpC,mBAAmB,0BAA0B;CAChD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knownagents/sdk",
-  "version": "2.5.0",
+  "version": "3.1.0",
   "description": "The official Node.js SDK for Known Agents: AI agent analytics (bot traffic), LLM referral tracking, automatic robots.txt, agent identification",
   "publishConfig": {
     "access": "public"
@@ -59,13 +59,13 @@
   },
   "homepage": "https://github.com/knownagents/node-sdk#readme",
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "devDependencies": {
     "@types/node": "^22.19.17",
-    "typescript": "^5.8.2"
+    "typescript": "^6.0.3"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0"
+    "@modelcontextprotocol/server": "^2.3.1"
   }
 }

package/src/KnownAgents.ts

@@ -1,18 +1,19 @@
 import type { IncomingMessage, ServerResponse } from "http"
-import type { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js"
-import { getFilteredHeaders, getIsACPCall, getIsMCPCall, getIsUCPCall } from "./headers"
-import { getIsPathExcluded } from "./paths"
+import { CLIENT_INFO_META_KEY, type Implementation } from "@modelcontextprotocol/server"
+import { filterHeaders, getHeaderValue } from "./headers"
+import { isPathExcluded } from "./paths"
 import type {
     AgentType,
     IdentificationRequest,
     IdentificationResult,
     KnownAgentsOptions,
-    TrackPageviewOrRESTCallOptions,
+    TrackVisitOptions,
     VisitRequest
 } from "./types"
 
 const DEFAULT_FLUSH_INTERVAL_IN_MILLISECONDS = 10000
 const DEFAULT_FLUSH_QUEUE_SIZE = 1
+const NODE_PACKAGE_VERSION = "3.1.0"
 
 /**
  * Server-side client for Known Agents analytics, robots.txt generation, and agent identification.
@@ -38,121 +39,61 @@ export class KnownAgents {
     }
 
     /**
-     * Tracks a single non-MCP pageview or REST API call for analytics.
-     * The visit is added to the visit event queue after the response finishes so status, headers, and duration are included.
+     * Tracks a single pageview or API call for analytics.
+     * For Node.js responses, the visit is added to the visit event queue after the response finishes so status, headers, and duration are included.
      * This method is non-blocking and handles upload errors internally.
      *
-     * @param request - The incoming Node.js HTTP request.
-     * @param response - The outgoing Node.js HTTP response.
-     * @param options - Optional ACP or UCP response metadata for REST API calls.
+     * @param request - The incoming HTTP request.
+     * @param response - The outgoing HTTP response.
+     * @param options - Optional protocol metadata.
      */
-    trackPageviewOrRESTCall(request: IncomingMessage, response: ServerResponse, options?: TrackPageviewOrRESTCallOptions): void {
-        const isMCPCall = getIsMCPCall(request.headers)
-        const path = request.url
+    trackVisit(request: IncomingMessage | Request, response?: ServerResponse | Response, options?: TrackVisitOptions): void {
+        const url = request instanceof Request ? new URL(request.url) : undefined
+        const requestHeaders = request instanceof Request ? Object.fromEntries(request.headers) : request.headers
+        const mcpRequestName = getHeaderValue(requestHeaders, "mcp-name")
+        const path = url ? `${url.pathname}${url.search}` : request.url
         const method = request.method
 
-        if (isMCPCall || !path || getIsPathExcluded(path) || !method) {
+        if (!path || isPathExcluded(path) || !method) {
             return
         }
 
         const created = new Date()
 
         const sendVisit = () => {
-            const responseDurationInMilliseconds = Date.now() - created.getTime()
+            const responseHeaders = response instanceof Response ? Object.fromEntries(response.headers.entries()) : response?.getHeaders() ?? {}
+            const responseStatusCode = response instanceof Response ? response.status : response?.statusCode
+            const responseDurationInMilliseconds = options?.responseDurationInMilliseconds ?? (!response || response instanceof Response ? undefined : Date.now() - created.getTime())
+            const mcp = options?.mcp
+            const clientInfo = (mcp?.context?.mcpReq.envelope as {
+                [CLIENT_INFO_META_KEY]?: Implementation
+            } | undefined)?.[CLIENT_INFO_META_KEY]
 
             const visitRequest: VisitRequest = {
                 request_path: path,
                 request_method: method,
-                request_headers: request.headers,
-                response_status_code: response?.statusCode,
-                response_headers: response.getHeaders(),
+                request_headers: requestHeaders,
+                response_status_code: responseStatusCode,
+                response_headers: responseHeaders,
                 response_duration_in_milliseconds: responseDurationInMilliseconds,
-                acp_response_body: options?.acpResponseBody,
-                ucp_response_body: options?.ucpResponseBody,
+                mcp_request_method: mcp?.context?.mcpReq.method,
+                mcp_request_name: mcpRequestName,
+                mcp_request_client_info_name: clientInfo?.name,
+                mcp_request_client_info_version: clientInfo?.version,
+                mcp_response_result_is_error: mcp?.result?.isError,
+                acp_response_body: options?.acp?.responseBody,
+                ucp_response_body: options?.ucp?.responseBody,
                 created: created.toISOString()
             }
 
-            this.trackVisits([visitRequest])
+            this.enqueueVisit(visitRequest)
         }
 
-        if (response.writableEnded) {
+        if (!response || response instanceof Response) {
             sendVisit()
-        } else {
-            response.once("finish", sendVisit)
-        }
-    }
-
-    /**
-     * Tracks a single MCP call handled by `StreamableHTTPServerTransport`.
-     * Call this after connecting the transport and before the transport processes the request so request and response metadata can be captured.
-     * Do not use this with transport instances shared across concurrent requests; use `trackVisits()` instead.
-     * This method is non-blocking and handles upload errors internally.
-     *
-     * @param request - The incoming Node.js HTTP request.
-     * @param response - The outgoing Node.js HTTP response.
-     * @param transport - The MCP streamable HTTP transport handling the request.
-     */
-    trackMCPCall(request: IncomingMessage, response: ServerResponse, transport: StreamableHTTPServerTransport): void {
-        const path = request.url
-        const method = request.method
-
-        if (!path || getIsPathExcluded(path) || !method) {
             return
         }
 
-        const created = new Date()
-
-        let mcpRequestBody: any
-        let mcpResponseBody: any
-
-        const originalTransportOnMessage = transport.onmessage
-        transport.onmessage = (message, extra): void => {
-            mcpRequestBody = message
-            originalTransportOnMessage?.(message, extra)
-        }
-
-        const originalTransportSend = transport.send
-        transport.send = async (message, options): Promise<void> => {
-            mcpResponseBody = message
-            await originalTransportSend.call(transport, message, options)
-        }
-
-        const restoreTransport = () => {
-            transport.onmessage = originalTransportOnMessage
-            transport.send = originalTransportSend
-        }
-
-        const sendVisit = () => {
-            restoreTransport()
-
-            if (!mcpRequestBody || !mcpResponseBody) {
-                return
-            }
-
-            const responseDurationInMilliseconds = Date.now() - created.getTime()
-
-            const visitRequest: VisitRequest = {
-                request_path: path,
-                request_method: method,
-                request_headers: request.headers,
-                response_status_code: response?.statusCode,
-                response_headers: response.getHeaders(),
-                response_duration_in_milliseconds: responseDurationInMilliseconds,
-                mcp_request_method: mcpRequestBody.method,
-                mcp_request_name: mcpRequestBody.params?.name,
-                mcp_request_client_info_name: mcpRequestBody.params?.clientInfo?.name,
-                mcp_request_client_info_version: mcpRequestBody.params?.clientInfo?.version,
-                mcp_response_result_is_error: mcpResponseBody.result?.isError,
-                mcp_response_error_code: mcpResponseBody.error?.code,
-                mcp_response_error_message: mcpResponseBody.error?.message,
-                acp_response_body: getIsACPCall(request.headers) ? mcpResponseBody.result : undefined,
-                ucp_response_body: getIsUCPCall(request.headers) ? mcpResponseBody.result : undefined,
-                created: created.toISOString()
-            }
-
-            this.trackVisits([visitRequest])
-        }
-
         if (response.writableEnded) {
             sendVisit()
         } else {
@@ -160,40 +101,6 @@ export class KnownAgents {
         }
     }
 
-    /**
-     * Adds multiple visits to the visit event queue for analytics.
-     * This method is non-blocking and handles upload errors internally.
-     * All visit events are uploaded together when the queue size reaches the configured threshold or the flush interval elapses.
-     *
-     * @param requests - An array of visits.
-     */
-    trackVisits(requests: VisitRequest[]): void {
-        const filteredRequests = requests
-            .filter((request) => {
-                return !getIsPathExcluded(request.request_path)
-            })
-            .map((request) => {
-                return {
-                    ...request,
-                    request_headers: getFilteredHeaders(request.request_headers),
-                    response_headers: request.response_headers ? getFilteredHeaders(request.response_headers) : undefined,
-                }
-            })
-
-        if (filteredRequests.length === 0) {
-            return
-        }
-
-        this.visitQueue.push(...filteredRequests)
-
-        if (this.visitQueue.length >= this.flushQueueSize) {
-            void this.flush()
-            return
-        }
-
-        this.scheduleFlush()
-    }
-
     /**
      * Uploads all events currently in the visit event queue and waits for pending uploads to finish.
      * This method handles upload errors internally.
@@ -229,7 +136,7 @@ export class KnownAgents {
      * @returns A promise that resolves to the generated robots.txt content as a string.
      * @throws {Error} If the API call fails or returns a non-200 status.
      */
-    async generateRobotsTXT(agentTypes: AgentType[], disallow: string = "/"): Promise<string> {
+    async generateRobotsTxt(agentTypes: AgentType[], disallow: string = "/"): Promise<string> {
         const response = await fetch("https://api.knownagents.com/robots-txts", {
             method: "POST",
             headers: {
@@ -238,7 +145,8 @@ export class KnownAgents {
             },
             body: JSON.stringify({
                 agent_types: agentTypes,
-                disallow: disallow
+                disallow: disallow,
+                node_package_version: NODE_PACKAGE_VERSION
             })
         })
 
@@ -265,9 +173,10 @@ export class KnownAgents {
                 "Content-Type": "application/json"
             },
             body: JSON.stringify({
-                request_headers: getFilteredHeaders(request.headers),
+                request_headers: filterHeaders(request.headers),
                 request_ip: request.socket.remoteAddress,
-                request_path: request.url
+                request_path: request.url,
+                node_package_version: NODE_PACKAGE_VERSION
             })
         })
 
@@ -296,7 +205,8 @@ export class KnownAgents {
             body: JSON.stringify(requests.map((request) => {
                 return {
                     ...request,
-                    request_headers: getFilteredHeaders(request.request_headers),
+                    request_headers: filterHeaders(request.request_headers),
+                    node_package_version: NODE_PACKAGE_VERSION
                 }
             }))
         })
@@ -308,6 +218,21 @@ export class KnownAgents {
         }
     }
 
+    private enqueueVisit(request: VisitRequest): void {
+        this.visitQueue.push({
+            ...request,
+            request_headers: filterHeaders(request.request_headers),
+            response_headers: request.response_headers ? filterHeaders(request.response_headers) : undefined,
+        })
+
+        if (this.visitQueue.length >= this.flushQueueSize) {
+            void this.flush()
+            return
+        }
+
+        this.scheduleFlush()
+    }
+
     private scheduleFlush(): void {
         if (this.flushTimeout) {
             return
@@ -329,7 +254,12 @@ export class KnownAgents {
                     "Authorization": `Bearer ${this.accessToken}`,
                     "Content-Type": "application/json"
                 },
-                body: JSON.stringify(requests)
+                body: JSON.stringify(requests.map((request) => {
+                    return {
+                        ...request,
+                        node_package_version: NODE_PACKAGE_VERSION
+                    }
+                }))
             })
 
             if (!response.ok) {

package/src/headers.ts

@@ -25,7 +25,26 @@ const filteredHeaderNames = [
     "private-token"
 ]
 
-export function getFilteredHeaders<Headers extends IncomingHttpHeaders | OutgoingHttpHeaders>(headers: Headers): Headers {
+export function getHeaderValue(headers: IncomingHttpHeaders | OutgoingHttpHeaders, headerName: string): string | undefined {
+    const normalizedHeaderName = headerName.toLowerCase()
+    const matchingHeaderName = Object.keys(headers).find((candidate) => {
+        return candidate.toLowerCase() === normalizedHeaderName
+    })
+
+    if (!matchingHeaderName) {
+        return undefined
+    }
+
+    const headerValue = headers[matchingHeaderName]
+
+    if (Array.isArray(headerValue)) {
+        return headerValue[0]
+    }
+
+    return headerValue?.toString()
+}
+
+export function filterHeaders<Headers extends IncomingHttpHeaders | OutgoingHttpHeaders>(headers: Headers): Headers {
     const filteredHeaders = { ...headers }
 
     Object.keys(filteredHeaders).forEach((key) => {
@@ -36,21 +55,3 @@ export function getFilteredHeaders<Headers extends IncomingHttpHeaders | Outgoin
 
     return filteredHeaders
 }
-
-export function getIsMCPCall(headers: IncomingHttpHeaders): boolean {
-    return Object.keys(headers).some((key) => {
-        return key.toLowerCase() === "mcp-protocol-version"
-    })
-}
-
-export function getIsUCPCall(headers: IncomingHttpHeaders): boolean {
-    return Object.keys(headers).some((key) => {
-        return key.toLowerCase() === "ucp-agent"
-    })
-}
-
-export function getIsACPCall(headers: IncomingHttpHeaders): boolean {
-    return Object.keys(headers).some((key) => {
-        return key.toLowerCase() === "api-version"
-    })
-}

package/src/index.ts

@@ -4,6 +4,5 @@ export {
     type IdentificationRequest,
     type IdentificationResult,
     type KnownAgentsOptions,
-    type TrackPageviewOrRESTCallOptions,
-    type VisitRequest
+    type TrackVisitOptions
 } from "./types"

package/src/paths.ts

@@ -1,4 +1,4 @@
-export function getIsPathExcluded(path: string): boolean {
+export function isPathExcluded(path: string): boolean {
     const pathWithoutQueryString = path.split(/[?#]/)[0]
     const lowercasedPath = pathWithoutQueryString.toLowerCase()
 

package/src/types.ts

@@ -1,4 +1,5 @@
 import type { IncomingHttpHeaders, OutgoingHttpHeaders } from "http"
+import type { CallToolResult, ServerContext } from "@modelcontextprotocol/server"
 
 /**
  * Batching configuration for the Known Agents client.
@@ -11,18 +12,24 @@ export interface KnownAgentsOptions {
 }
 
 /**
- * Additional metadata to include when tracking a pageview or REST API call.
+ * Additional metadata to include when tracking a visit.
  */
-export interface TrackPageviewOrRESTCallOptions {
-    /** The ACP response body. */
-    acpResponseBody?: Record<string, unknown>
-    /** The UCP response body. */
-    ucpResponseBody?: Record<string, unknown>
+export interface TrackVisitOptions {
+    responseDurationInMilliseconds?: number
+    mcp?: {
+        context?: ServerContext
+        result?: CallToolResult
+    }
+    acp?: {
+        responseBody: Record<string, unknown>
+    }
+    ucp?: {
+        responseBody: Record<string, unknown>
+    }
 }
 
 /**
- * A normalized visit payload for the Known Agents API.
- * Use this with `trackVisits()` to manually add visit events to the queue.
+ * The normalized visit payload sent to the Known Agents API.
  */
 export interface VisitRequest {
     /** The URL path and query string of the request (e.g. "/about?foo=bar") */
@@ -47,10 +54,6 @@ export interface VisitRequest {
     mcp_request_client_info_version?: string
     /** Whether the MCP response result is an error */
     mcp_response_result_is_error?: boolean
-    /** The MCP response error code */
-    mcp_response_error_code?: number
-    /** The MCP response error message */
-    mcp_response_error_message?: string
     /** The ACP response body */
     acp_response_body?: Record<string, unknown>
     /** The UCP response body */