@knownagents/sdk 1.11.0 → 2.1.0

package/dist/types.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentType = void 0;
+/**
+ * Agent types that can be controlled with robots.txt rules.
+ */
+var AgentType;
+(function (AgentType) {
+    AgentType["AIAgent"] = "AI Agent";
+    AgentType["AIAssistant"] = "AI Assistant";
+    AgentType["AICodingAgent"] = "AI Coding Agent";
+    AgentType["AIDataProvider"] = "AI Data Provider";
+    AgentType["AIDataScraper"] = "AI Data Scraper";
+    AgentType["AISearchCrawler"] = "AI Search Crawler";
+    AgentType["Archiver"] = "Archiver";
+    AgentType["AutomatedAgent"] = "Automated Agent";
+    AgentType["DeveloperHelper"] = "Developer Helper";
+    AgentType["Fetcher"] = "Fetcher";
+    AgentType["IntelligenceGatherer"] = "Intelligence Gatherer";
+    AgentType["Scraper"] = "Scraper";
+    AgentType["SEOCrawler"] = "SEO Crawler";
+    AgentType["SearchEngineCrawler"] = "Search Engine Crawler";
+    AgentType["SecurityScanner"] = "Security Scanner";
+    AgentType["UndocumentedAIAgent"] = "Undocumented AI Agent";
+})(AgentType || (exports.AgentType = AgentType = {}));

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "@knownagents/sdk",
-  "version": "1.11.0",
+  "version": "2.1.0",
   "description": "The official Node.js SDK for Known Agents: AI agent analytics (bot traffic), LLM referral tracking, automatic robots.txt, agent verification",
   "publishConfig": {
     "access": "public"
   },
+  "files": [
+    "dist",
+    "src"
+  ],
   "keywords": [
     "ai analytics",
     "bot traffic",
@@ -16,6 +20,12 @@
     "bot detection",
     "crawler detection",
     "llm analytics",
+    "mcp analytics",
+    "mcp server analytics",
+    "model context protocol",
+    "agentic commerce protocol",
+    "universal commerce protocol",
+    "commerce analytics",
     "robots.txt",
     "automatic robots.txt",
     "robots.txt generator",
@@ -54,5 +64,8 @@
   "devDependencies": {
     "@types/node": "^22.19.17",
     "typescript": "^5.8.2"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0"
   }
 }

package/src/KnownAgents.ts

@@ -0,0 +1,275 @@
+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 type {
+    AgentType,
+    IdentificationRequest,
+    IdentificationResult,
+    TrackPageviewOrRESTCallOptions,
+    VisitRequest
+} from "./types"
+
+/**
+ * Server-side client for Known Agents analytics, robots.txt generation, and agent identification.
+ */
+export class KnownAgents {
+    private readonly accessToken: string
+
+    /**
+     * Creates a new instance of the Known Agents client.
+     * 
+     * @param accessToken - Your project's access token.
+     */
+    constructor(accessToken: string) {
+        this.accessToken = accessToken
+    }
+
+    /**
+     * Tracks a single non-MCP pageview or REST API call for analytics.
+     * The visit is sent after the response finishes so status, headers, and duration are included.
+     * This method is non-blocking and handles 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 {
+        const isMCPCall = getIsMCPCall(request.headers)
+        const path = request.url
+        const method = request.method
+
+        if (isMCPCall || !path || getIsPathExcluded(path) || !method) {
+            return
+        }
+
+        const created = new Date()
+
+        const sendVisit = () => {
+            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,
+                acp_response_body: options?.acpResponseBody,
+                ucp_response_body: options?.ucpResponseBody,
+                created: created.toISOString()
+            }
+
+            this.trackVisits([visitRequest])
+        }
+
+        if (response.writableEnded) {
+            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 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 mcpResponseResult = mcpResponseBody.result?.structuredContent ?? mcpResponseBody.result
+
+            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_tool_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) ? mcpResponseResult : undefined,
+                ucp_response_body: getIsUCPCall(request.headers) ? mcpResponseResult : undefined,
+                created: created.toISOString()
+            }
+
+            this.trackVisits([visitRequest])
+        }
+
+        if (response.writableEnded) {
+            sendVisit()
+        } else {
+            response.once("finish", sendVisit)
+        }
+    }
+    
+    /**
+     * Tracks multiple visits in a batch for analytics.
+     * This method is non-blocking and handles errors internally.
+     * Recommended for high-traffic websites - batch visits and send periodically (e.g. every 30 seconds).
+     *
+     * @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
+        }
+
+        fetch("https://api.knownagents.com/visits", {
+            method: "POST",
+            headers: {
+                "Authorization": `Bearer ${this.accessToken}`,
+                "Content-Type": "application/json"
+            },
+            body: JSON.stringify(filteredRequests)
+        }).catch(error => {
+            console.error(`Known Agents failed to track visits: ${error.message}`)
+        })
+    }
+    
+    /**
+     * Generates a robots.txt file that disallows the specified agent types.
+     * The generated file stays up-to-date with all current and future agents in the specified categories.
+     * Cache and serve the result at your website's `/robots.txt` endpoint.
+     *
+     * @param agentTypes - An array of agent types to disallow.
+     * @param disallow - The path to disallow (default: "/" for all paths).
+     * @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> {
+        const response = await fetch("https://api.knownagents.com/robots-txts", {
+            method: "POST",
+            headers: {
+                "Authorization": `Bearer ${this.accessToken}`,
+                "Content-Type": "application/json"
+            },
+            body: JSON.stringify({
+                agent_types: agentTypes,
+                disallow: disallow
+            })
+        })
+
+        if (response.ok) {
+            return await response.text()
+        } else {
+            throw new Error(`Known Agents failed to generate robots.txt: ${response.status} ${response.statusText}`)
+        }
+    }
+    
+    /**
+     * Identifies and verifies a single agent from an HTTP request.
+     * Uses Web Bot Auth (HTTP message signatures), IP matching, or other available methods.
+     *
+     * @param request - The incoming Node.js HTTP request.
+     * @returns A promise that resolves to the identification result.
+     * @throws {Error} If the API call fails or returns a non-200 status.
+     */
+    async identifyAgent(request: IncomingMessage): Promise<IdentificationResult> {
+        const response = await fetch("https://api.knownagents.com/agent-identifications", {
+            method: "POST",
+            headers: {
+                "Authorization": `Bearer ${this.accessToken}`,
+                "Content-Type": "application/json"
+            },
+            body: JSON.stringify({
+                request_headers: getFilteredHeaders(request.headers)
+            })
+        })
+
+        if (response.ok) {
+            return await response.json()
+        } else {
+            throw new Error(`Known Agents failed to identify agent: ${response.status} ${response.statusText}`)
+        }
+    }
+
+    /**
+     * Identifies and verifies multiple agents from HTTP requests in a batch.
+     * Uses Web Bot Auth (HTTP message signatures), IP matching, or other available methods.
+     *
+     * @param requests - An array of identification requests.
+     * @returns A promise that resolves to an array of identification results.
+     * @throws {Error} If the API call fails or returns a non-200 status.
+     */
+    async identifyAgents(requests: IdentificationRequest[]): Promise<IdentificationResult[]> {
+        const response = await fetch("https://api.knownagents.com/agent-identifications", {
+            method: "POST",
+            headers: {
+                "Authorization": `Bearer ${this.accessToken}`,
+                "Content-Type": "application/json"
+            },
+            body: JSON.stringify(requests.map(request => {
+                return {
+                    ...request,
+                    request_headers: getFilteredHeaders(request.request_headers),
+                }
+            }))
+        })
+
+        if (response.ok) {
+            return await response.json()
+        } else {
+            throw new Error(`Known Agents failed to identify agents: ${response.status} ${response.statusText}`)
+        }
+    }
+
+}

package/src/headers.ts

@@ -0,0 +1,56 @@
+import type { IncomingHttpHeaders, OutgoingHttpHeaders } from "http"
+
+const filteredHeaderNames = [
+    "authorization",
+    "proxy-authorization",
+    "cookie",
+    "set-cookie",
+    "x-api-key",
+    "api-key",
+    "apikey",
+    "x-auth-token",
+    "x-access-token",
+    "x-id-token",
+    "x-refresh-token",
+    "x-session-token",
+    "session-token",
+    "csrf-token",
+    "x-csrf-token",
+    "xsrf-token",
+    "x-xsrf-token",
+    "x-amz-security-token",
+    "x-goog-api-key",
+    "x-client-secret",
+    "client-secret",
+    "private-token"
+]
+
+export function getFilteredHeaders<Headers extends IncomingHttpHeaders | OutgoingHttpHeaders>(headers: Headers): Headers {
+    const filteredHeaders = { ...headers }
+
+    Object.keys(filteredHeaders).forEach((key) => {
+        if (filteredHeaderNames.includes(key.toLowerCase())) {
+            delete filteredHeaders[key]
+        }
+    })
+
+    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 !getIsUCPCall(headers) && Object.keys(headers).some((key) => {
+        return key.toLowerCase() === "api-version"
+    })
+}