mcpcat/dist/index.d.ts

Analytics tool for MCP (Model Context Protocol) servers - tracks tool usage patterns and provides insights

interface MCPCatOptions {
    enableReportMissing?: boolean;
    enableTracing?: boolean;
    enableToolCallContext?: boolean;
    identify?: (request: any, extra?: CompatibleRequestHandlerExtra) => Promise<UserIdentity | null>;
    redactSensitiveInformation?: RedactFunction;
}
type RedactFunction = (text: string) => Promise<string>;
interface CompatibleRequestHandlerExtra {
    sessionId?: string;
    headers?: Record<string, string | string[]>;
    [key: string]: any;
}
interface ServerClientInfoLike {
    name?: string;
    version?: string;
}
interface MCPServerLike {
    setRequestHandler(schema: any, handler: (request: any, extra?: CompatibleRequestHandlerExtra) => Promise<any>): void;
    _requestHandlers: Map<string, (request: any, extra?: CompatibleRequestHandlerExtra) => Promise<any>>;
    _serverInfo?: ServerClientInfoLike;
    getClientVersion(): ServerClientInfoLike | undefined;
}
interface UserIdentity {
    userId: string;
    userName?: string;
    userData?: Record<string, any>;
}

/**
 * Integrates MCPCat analytics into an MCP server to track tool usage patterns and user interactions.
 *
 * @param server - The MCP server instance to track. Must be a compatible MCP server implementation.
 * @param projectId - Your MCPCat project ID obtained from mcpcat.io when creating an account.
 * @param options - Optional configuration to customize tracking behavior.
 * @param options.enableReportMissing - Adds a "get_more_tools" tool that allows LLMs to automatically report missing functionality.
 * @param options.enableTracing - Enables tracking of tool calls and usage patterns.
 * @param options.enableToolCallContext - Injects a "context" parameter to existing tools to capture user intent.
 * @param options.identify - Async function to identify users and attach custom data to their sessions.
 * @param options.redactSensitiveInformation - Function to redact sensitive data before sending to MCPCat.
 *
 * @returns The tracked server instance.
 *
 * @remarks
 * **IMPORTANT**: The `track()` function must be called AFTER all tools have been registered on the server.
 * Calling it before tool registration will result in those tools not being tracked.
 *
 * Analytics data and debug information are logged to `~/mcpcat.log` since console logs interfere
 * with STDIO-based MCP servers.
 *
 * Do not call `track()` multiple times on the same server instance as this will cause unexpected behavior.
 *
 * @example
 * ```typescript
 * import * as mcpcat from "mcpcat";
 *
 * const mcpServer = new Server({ name: "my-mcp-server", version: "1.0.0" });
 *
 * // Register your tools first
 * mcpServer.setRequestHandler(ListToolsRequestSchema, async () => ({
 *   tools: [{ name: "my_tool", description: "Does something useful" }]
 * }));
 *
 * // Then call track() after all tools are registered
 * mcpcat.track(mcpServer, "proj_abc123xyz");
 * ```
 *
 * @example
 * ```typescript
 * // With user identification
 * mcpcat.track(mcpServer, "proj_abc123xyz", {
 *   identify: async (request, extra) => {
 *     const user = await getUserFromToken(request.params.arguments.token);
 *     return {
 *       userId: user.id,
 *       userData: { plan: user.plan, company: user.company }
 *     };
 *   }
 * });
 * ```
 *
 * @example
 * ```typescript
 * // With sensitive data redaction
 * mcpcat.track(mcpServer, "proj_abc123xyz", {
 *   redactSensitiveInformation: async (text) => {
 *     return text.replace(/api_key_\w+/g, "[REDACTED]");
 *   }
 * });
 * ```
 */
declare function track(server: any, projectId: string, options?: MCPCatOptions): MCPServerLike;

type IdentifyFunction = MCPCatOptions["identify"];

export { type IdentifyFunction, type MCPCatOptions, type RedactFunction, type UserIdentity, track };