add telemetry tracking (#85)

Author: gaojude

.gitignore

@@ -16,4 +16,3 @@ _*.md
 test/fixtures/**/pnpm-lock.yaml
 test/fixtures/**/node_modules/
 test/fixtures/**/.next/
-

CLAUDE.md

@@ -75,15 +75,25 @@ All tools, prompts, and resources are explicitly imported and registered in `src
 - `browser-eval-manager.ts`: Manages Playwright MCP server lifecycle
 - `nextjs-runtime-manager.ts`: Discovers and connects to Next.js dev servers with MCP enabled
 
+**Telemetry System** (`src/telemetry/`):
+- `mcp-telemetry-tracker.ts`: Singleton tracker for MCP tool invocations
+- `telemetry-events.ts`: Event schema definitions and factory functions
+- `telemetry-storage.ts`: Handles anonymous ID, session tracking, and API submission
+- `event-queue.ts`: In-memory aggregation of events during session
+- `flush-events.ts`: Background process that sends events after server shutdown
+- `logger.ts`: Synchronous file logging for debugging
+- Telemetry can be disabled via `NEXT_TELEMETRY_DISABLED=1` environment variable
+- Data stored in `~/.next-devtools-mcp/` (telemetry-id, telemetry-salt, mcp.log)
+
 **Resources Architecture**:
 - Knowledge base split into focused sections (12 sections for Cache Components, 2 for Next.js 16, 1 for fundamentals)
 - Each resource exports: `metadata` (uri, name, description, mimeType) and `handler` (function returning content)
 - Resources use URI-based addressing (e.g., `cache-components://overview`)
-- Markdown files in `src/resources/` are copied to `dist/resources/` during build via `scripts/copy-resources.js`
+- Markdown files in `src/resources/` and `src/prompts/` are copied during build via `scripts/copy-resources.js` (to `dist/resources/` and `dist/resources/prompts/` respectively)
 
 ### TypeScript Configuration
 
-- Target: ES2022, ES modules (Node16 module resolution)
+- Target: ES2022, ES modules (NodeNext module resolution)
 - Strict mode enabled
 - Output directory: `dist/`
 - Declaration files generated
@@ -92,7 +102,7 @@ All tools, prompts, and resources are explicitly imported and registered in `src
 ## Build Process
 
 1. TypeScript compilation: `tsc` compiles all TypeScript files from `src/` to `dist/`
-2. Resource copying: `scripts/copy-resources.js` copies markdown files from `src/resources/` and `src/prompts/` to `dist/resources/`
+2. Resource copying: `scripts/copy-resources.js` copies markdown files from `src/resources/` and `src/prompts/` (to `dist/resources/` and `dist/resources/prompts/` respectively)
 
 The `dist/index.js` file is the entry point for the MCP server and includes a shebang for CLI execution.
 

README.md

@@ -294,25 +294,31 @@ proper context and ensures all Next.js queries use official documentation.
 
 ## MCP Resources
 
-Next.js 16 knowledge base resources are automatically available to your coding agent. 
-
-These resources provide comprehensive documentation split into focused sections for efficient context management:
+The knowledge base resources are automatically available to your coding agent and are split into focused sections for efficient context management. Current resource URIs:
 
 <details>
 <summary>📚 Available Knowledge Base Resources (click to expand)</summary>
 
-- **`nextjs16://knowledge/overview`** - Overview and critical errors AI agents make
-- **`nextjs16://knowledge/core-mechanics`** - Fundamental paradigm shift and how cacheComponents works
-- **`nextjs16://knowledge/public-caches`** - Public cache mechanics with 'use cache'
-- **`nextjs16://knowledge/private-caches`** - Private cache patterns with 'use cache: private'
-- **`nextjs16://knowledge/runtime-prefetching`** - Runtime prefetch configuration and patterns
-- **`nextjs16://knowledge/request-apis`** - Async params, searchParams, cookies, headers APIs
-- **`nextjs16://knowledge/cache-invalidation`** - updateTag, revalidateTag, and refresh patterns
-- **`nextjs16://knowledge/advanced-patterns`** - cacheLife, cacheTag, draft mode, and more
-- **`nextjs16://knowledge/build-behavior`** - Prerendering, resume data cache, and metadata
-- **`nextjs16://knowledge/error-patterns`** - Common errors and how to fix them
-- **`nextjs16://knowledge/test-patterns`** - E2E patterns from 125+ test fixtures
-- **`nextjs16://knowledge/reference`** - API reference, checklists, and comprehensive nuances
+- Cache Components (12 sections):
+  - `cache-components://overview`
+  - `cache-components://core-mechanics`
+  - `cache-components://public-caches`
+  - `cache-components://private-caches`
+  - `cache-components://runtime-prefetching`
+  - `cache-components://request-apis`
+  - `cache-components://cache-invalidation`
+  - `cache-components://advanced-patterns`
+  - `cache-components://build-behavior`
+  - `cache-components://error-patterns`
+  - `cache-components://test-patterns`
+  - `cache-components://reference`
+
+- Next.js 16 migration:
+  - `nextjs16://migration/beta-to-stable`
+  - `nextjs16://migration/examples`
+
+- Next.js fundamentals:
+  - `nextjs-fundamentals://use-client`
 
 </details>
 
@@ -325,7 +331,6 @@ Pre-configured prompts to help with common Next.js development tasks:
 <details>
 <summary>💡 Available Prompts (click to expand)</summary>
 
-- **`init`** - Initialize context for Next.js development with MCP tools and documentation requirements
 - **`upgrade-nextjs-16`** - Guide for upgrading to Next.js 16
 - **`enable-cache-components`** - Migrate and enable Cache Components mode for Next.js 16
 
@@ -548,6 +553,40 @@ With other agents or programmatically:
 
 </details>
 
+## Privacy & Telemetry
+
+### What Data is Collected
+
+`next-devtools-mcp` collects anonymous usage telemetry to help improve the tool. The following data is collected:
+
+- **Tool usage**: Which MCP tools are invoked (e.g., `nextjs_runtime`, `browser_eval`, `upgrade_nextjs_16`)
+- **Error events**: Anonymous error messages when tools fail
+- **Session metadata**: Session ID, timestamps, and basic environment info (OS, Node.js version)
+
+**What is NOT collected:**
+- Your project code, file contents, or file paths
+- Personal information or identifiable data
+- API keys, credentials, or sensitive configuration
+- Arguments passed to tools (except tool names)
+
+Local files are written under `~/.next-devtools-mcp/` (anonymous `telemetry-id`, `telemetry-salt`, and a debug log `mcp.log`). Events are sent to the telemetry endpoint in the background to help us understand usage patterns and improve reliability.
+
+### Opt-Out
+
+To disable telemetry completely, set the environment variable:
+
+```bash
+export NEXT_TELEMETRY_DISABLED=1
+```
+
+Add this to your shell configuration file (e.g., `~/.bashrc`, `~/.zshrc`) to make it permanent.
+
+You can also delete your local telemetry data at any time:
+
+```bash
+rm -rf ~/.next-devtools-mcp
+```
+
 ## Local Development
 
 To run the MCP server locally for development:
@@ -580,4 +619,3 @@ To run the MCP server locally for development:
 ## License
 
 MIT License
-

src/index.ts

@@ -10,21 +10,26 @@ import {
   ReadResourceRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js"
 import { z } from "zod"
+import { spawn } from "child_process"
+import { fileURLToPath } from "url"
+import { dirname, join } from "path"
 import pkg from "../package.json" with { type: "json" }
+import type { McpToolName } from "./telemetry/mcp-telemetry-tracker.js"
+import { queueEvent, getSessionAggregationJSON } from "./telemetry/event-queue.js"
+import { log } from "./telemetry/logger.js"
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
 
-// Import tools
 import * as browserEval from "./tools/browser-eval.js"
 import * as enableCacheComponents from "./tools/enable-cache-components.js"
 import * as init from "./tools/init.js"
 import * as nextjsDocs from "./tools/nextjs-docs.js"
 import * as nextjsRuntime from "./tools/nextjs-runtime.js"
 import * as upgradeNextjs16 from "./tools/upgrade-nextjs-16.js"
 
-// Import prompts
 import * as upgradeNextjs16Prompt from "./prompts/upgrade-nextjs-16.js"
 import * as enableCacheComponentsPrompt from "./prompts/enable-cache-components.js"
-
-// Import resources
 import * as cacheComponentsOverview from "./resources/(cache-components)/overview.js"
 import * as cacheComponentsCoreMechanics from "./resources/(cache-components)/core-mechanics.js"
 import * as cacheComponentsPublicCaches from "./resources/(cache-components)/public-caches.js"
@@ -42,13 +47,19 @@ import * as nextjsFundamentalsUseClient from "./resources/(nextjs-fundamentals)/
 import * as nextjs16BetaToStable from "./resources/(nextjs16)/migration/beta-to-stable.js"
 import * as nextjs16Examples from "./resources/(nextjs16)/migration/examples.js"
 
-// Tool registry
 const tools = [browserEval, enableCacheComponents, init, nextjsDocs, nextjsRuntime, upgradeNextjs16]
 
-// Prompt registry
+const toolNameToTelemetryName: Record<string, McpToolName> = {
+  browser_eval: "mcp/browser_eval",
+  enable_cache_components: "mcp/enable_cache_components",
+  init: "mcp/init",
+  nextjs_docs: "mcp/nextjs_docs",
+  nextjs_runtime: "mcp/nextjs_runtime",
+  upgrade_nextjs_16: "mcp/upgrade_nextjs_16",
+}
+
 const prompts = [upgradeNextjs16Prompt, enableCacheComponentsPrompt]
 
-// Resource registry
 const resources = [
   cacheComponentsOverview,
   cacheComponentsCoreMechanics,
@@ -117,11 +128,22 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     throw new Error(`Tool not found: ${name}`)
   }
 
-  // Validate arguments with Zod schema
+  // Queue telemetry event for later batch sending
+  const telemetryName = toolNameToTelemetryName[name]
+  if (telemetryName) {
+    const event = {
+      eventName: "NEXT_MCP_TOOL_USAGE",
+      fields: {
+        toolName: telemetryName,
+        invocationCount: 1,
+      },
+    }
+    queueEvent(event)
+  }
+
   const parsedArgs = parseToolArgs(tool.inputSchema, args || {})
 
-  // Call the tool handler
-  const result = await tool.handler(parsedArgs as never)
+  const result = await (tool.handler as (args: Record<string, unknown>) => Promise<string>)(parsedArgs)
 
   return {
     content: [
@@ -193,7 +215,6 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
     throw new Error(`Resource not found: ${uri}`)
   }
 
-  // Get the resource content
   const content = await resource.handler()
 
   return {
@@ -207,12 +228,9 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
   }
 })
 
-// Helper function to convert Zod schema to JSON Schema (simplified)
 function zodSchemaToJsonSchema(zodSchema: z.ZodTypeAny): JSONSchema {
-  // Get the description
   const description = zodSchema._def?.description
 
-  // Handle different Zod types
   if (zodSchema._def?.typeName === "ZodString") {
     return { type: "string", description }
   }
@@ -244,18 +262,15 @@ function zodSchemaToJsonSchema(zodSchema: z.ZodTypeAny): JSONSchema {
     return zodSchemaToJsonSchema(zodSchema._def.innerType)
   }
   if (zodSchema._def?.typeName === "ZodUnion") {
-    // Handle union types (for boolean | string transforms)
     const options = zodSchema._def.options
     if (options.length === 2) {
       return zodSchemaToJsonSchema(options[0])
     }
   }
 
-  // Default fallback
   return { type: "string", description }
 }
 
-// Helper function to validate tool arguments with Zod
 function parseToolArgs(
   schema: Record<string, z.ZodTypeAny>,
   args: Record<string, unknown>
@@ -264,26 +279,55 @@ function parseToolArgs(
 
   for (const [key, zodSchema] of Object.entries(schema)) {
     if (args[key] !== undefined) {
-      // Let Zod handle the validation and transformation
       const parsed = zodSchema.safeParse(args[key])
       if (parsed.success) {
         result[key] = parsed.data
       } else {
         throw new Error(`Invalid argument '${key}': ${parsed.error.message}`)
       }
     } else if (!zodSchema.isOptional()) {
-      // Check if required
       throw new Error(`Missing required argument: ${key}`)
     }
   }
 
   return result
 }
 
-// Start the server
 async function main() {
   const transport = new StdioServerTransport()
   await server.connect(transport)
+
+  log('Server started')
+
+  const shutdown = () => {
+    log('Server terminated')
+
+    const aggregationJSON = getSessionAggregationJSON()
+
+    if (aggregationJSON) {
+      const flushEventsScript = join(__dirname, "telemetry", "flush-events.js")
+      const child = spawn(
+        process.execPath,
+        [flushEventsScript, aggregationJSON],
+        {
+          detached: true,
+          stdio: 'ignore',
+          windowsHide: true
+        }
+      )
+
+      child.unref()
+
+      log('Event flusher spawned with aggregation data')
+    } else {
+      log('No events to flush')
+    }
+
+    process.exit(0)
+  }
+
+  process.on('SIGINT', shutdown)
+  process.on('SIGTERM', shutdown)
 }
 
 main().catch((error) => {

src/telemetry/event-queue.ts

@@ -0,0 +1,24 @@
+import { log } from "./logger.js"
+import type { TelemetryEvent } from "./telemetry-events.js"
+
+const sessionAggregation = new Map<string, number>()
+
+export function queueEvent(event: TelemetryEvent): void {
+  log("TOOL_INVOCATION", event)
+
+  if (event.eventName === "NEXT_MCP_TOOL_USAGE" && event.fields.toolName) {
+    const toolName = event.fields.toolName
+    const currentCount = sessionAggregation.get(toolName) || 0
+    sessionAggregation.set(toolName, currentCount + event.fields.invocationCount)
+  }
+}
+
+export function getSessionAggregationJSON(): string | null {
+  if (sessionAggregation.size === 0) {
+    return null
+  }
+
+  const aggregationObject = Object.fromEntries(sessionAggregation)
+  return JSON.stringify(aggregationObject)
+}
+