mcpcat/.serena/memories/project_overview.md

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

# MCPcat TypeScript SDK Project Overview

## Purpose
MCPcat is an analytics SDK for MCP (Model Context Protocol) servers that tracks tool usage patterns, provides insights into how MCP tools are used, and captures user intent through context parameters.

## Tech Stack
- **Language**: TypeScript
- **Build Tool**: tsup
- **Package Manager**: pnpm
- **Testing**: Vitest
- **Linting**: ESLint
- **Version**: 0.1.8
- **Package Name**: mcpcat (published to npm)
- **Module Type**: ESM (type: module)

## Key Dependencies
- @modelcontextprotocol/sdk - MCP SDK for server/client implementation
- mcpcat-api - API client for MCPcat backend
- zod - Schema validation
- Third-party KSUID implementation for ID generation

## Project Structure
```
src/
├── index.ts             # Main entry point, exports track() function
├── types.ts             # TypeScript type definitions
├── modules/
│   ├── eventQueue.ts    # Event queue management and publishing
│   ├── session.ts       # Session management
│   ├── internal.ts      # Internal state management
│   ├── tracing.ts       # Tool call tracing (low-level servers)
│   ├── tracingV2.ts     # Tool call tracing (high-level servers)
│   ├── tools.ts         # MCPcat tools setup
│   ├── context-parameters.ts # Context parameter injection
│   ├── exceptions.ts    # Error handling
│   ├── telemetry.ts     # Telemetry management
│   ├── redaction.ts     # Sensitive data redaction
│   └── exporters/       # Telemetry exporters (OTLP, Datadog, Sentry)
└── tests/               # Test files
```

## Core Concepts
- **Events**: Analytics events tracked by MCPcat
- **Sessions**: Series of events grouped together
- **Actor/User Identity**: User identification and tracking
- **Context Parameters**: Injected parameters to capture user intent
- **Server Tracking**: WeakMap-based tracking of server instances