feat(telemetry): anonymous posthog usage telemetry across node cli and python daemon (#205)

* feat: add telemetry phase 1

* feat: add node telemetry event catalog

* feat: add telemetry event helpers

* feat: emit setup and connection telemetry

* feat: emit connection and stack telemetry

* feat: emit ingest and scan telemetry

* feat: emit query telemetry

* feat: emit sampled mcp telemetry

* docs: expand telemetry event catalog

* feat: add telemetry schema sync artifact

* feat: pass telemetry project id to semantic daemon

* feat: add daemon telemetry foundation

* feat: emit semantic daemon telemetry

* feat: emit daemon lifecycle telemetry

* docs: document full telemetry event catalog

* feat(telemetry): dim first-run notice

* feat(telemetry): show first-run notice before command output

* feat(telemetry): wire ktx PostHog project for live ingestion

* docs(telemetry): drop posthog project name and host from storage section

* docs(telemetry): trim to general overview and disclaimer

* docs(agents): add short telemetry guidelines

* feat(telemetry): enable posthog geoip enrichment

* docs(telemetry): drop ip-geoip note from public overview

* refactor(telemetry): drop no-op groupIdentify, rely on capture groups field

* fix(telemetry): respect CI kill switch in python daemon identity

* fix(sql): route table-count analysis to existing analyze-batch endpoint

* fix(telemetry): emit install_first_run from notice path and derive flagsPresent from commander

* fix(telemetry): read package info via getKtxCliPackageInfo to satisfy boundary check

* fix(telemetry): make python identity env={} bypass os.environ and unset CI in tests

* fix(telemetry): unset CI kill switch in cli-program-telemetry tests

packages/cli/src/context/daemon/semantic-layer-compute.test.ts

@@ -106,7 +106,10 @@ describe('createPythonSemanticLayerComputePort', () => {
       columns: [{ name: 'orders.order_count' }],
       plan: { sources_used: ['orders'] },
     }));
-    const port = createPythonSemanticLayerComputePort({ runJson });
+    const port = createPythonSemanticLayerComputePort({
+      runJson,
+      projectId: 'hashed-project-id',
+    });
 
     await expect(
       port.query({
@@ -125,6 +128,7 @@ describe('createPythonSemanticLayerComputePort', () => {
       sources: [source],
       dialect: 'postgres',
       query: { measures: ['orders.order_count'], dimensions: [] },
+      projectId: 'hashed-project-id',
     });
   });
 

packages/cli/src/context/daemon/semantic-layer-compute.ts

@@ -90,6 +90,7 @@ export interface PythonSemanticLayerComputeOptions {
   cwd?: string;
   env?: NodeJS.ProcessEnv;
   runJson?: KtxDaemonJsonRunner;
+  projectId?: string;
 }
 
 /** @internal */
@@ -238,6 +239,7 @@ export function createPythonSemanticLayerComputePort(
   const command = options.command ?? 'python';
   const args = options.args ?? ['-m', 'ktx_daemon'];
   const runJson = options.runJson ?? runProcessJson({ command, args, cwd: options.cwd, env: options.env });
+  const projectId = options.projectId;
 
   return {
     async query(input) {
@@ -245,6 +247,7 @@ export function createPythonSemanticLayerComputePort(
         sources: input.sources,
         dialect: input.dialect,
         query: input.query,
+        ...(projectId ? { projectId } : {}),
       });
       return {
         sql: typeof raw.sql === 'string' ? raw.sql : '',

packages/cli/src/context/mcp/context-tools.ts

@@ -1,7 +1,10 @@
 import { randomUUID } from 'node:crypto';
 import type { ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
+import type { KtxCliIo } from '../../cli-runtime.js';
 import type { MemoryAgentInput } from '../../context/memory/types.js';
+import { emitTelemetryEvent, mcpTelemetrySampleRate, shouldEmitMcpTelemetry } from '../../telemetry/index.js';
+import { scrubErrorClass } from '../../telemetry/scrubber.js';
 import type {
   KtxMcpContextPorts,
   KtxMcpProgressCallback,
@@ -16,6 +19,8 @@ export interface RegisterKtxContextToolsDeps {
   server: KtxMcpServerLike;
   ports: KtxMcpContextPorts;
   userContext: KtxMcpUserContext;
+  projectDir?: string;
+  io?: KtxCliIo;
 }
 
 const connectionIdSchema = z.string().min(1);
@@ -509,8 +514,58 @@ function registerParsedTool<TSchema extends z.ZodType>(
   });
 }
 
+function instrumentMcpServer(
+  server: KtxMcpServerLike,
+  telemetry: { projectDir?: string; io?: KtxCliIo },
+): KtxMcpServerLike {
+  return {
+    registerTool(name, config, handler) {
+      server.registerTool(name, config, async (input, context) => {
+        const startedAt = performance.now();
+        try {
+          const result = await handler(input, context);
+          if (telemetry.io && telemetry.projectDir && shouldEmitMcpTelemetry()) {
+            const isError =
+              typeof result === 'object' && result !== null && 'isError' in result && result.isError === true;
+            await emitTelemetryEvent({
+              name: 'mcp_request_completed',
+              projectDir: telemetry.projectDir,
+              io: telemetry.io,
+              fields: {
+                toolName: name,
+                outcome: isError ? 'error' : 'ok',
+                durationMs: Math.max(0, performance.now() - startedAt),
+                sampleRate: mcpTelemetrySampleRate(),
+              },
+            });
+          }
+          return result;
+        } catch (error) {
+          if (telemetry.io && telemetry.projectDir && shouldEmitMcpTelemetry()) {
+            const errorClass = scrubErrorClass(error);
+            await emitTelemetryEvent({
+              name: 'mcp_request_completed',
+              projectDir: telemetry.projectDir,
+              io: telemetry.io,
+              fields: {
+                toolName: name,
+                outcome: 'error',
+                ...(errorClass ? { errorClass } : {}),
+                durationMs: Math.max(0, performance.now() - startedAt),
+                sampleRate: mcpTelemetrySampleRate(),
+              },
+            });
+          }
+          throw error;
+        }
+      });
+    },
+  };
+}
+
 export function registerKtxContextTools(deps: RegisterKtxContextToolsDeps): void {
-  const { ports, server, userContext } = deps;
+  const { ports, userContext } = deps;
+  const server = instrumentMcpServer(deps.server, { projectDir: deps.projectDir, io: deps.io });
 
   if (ports.connections) {
     const connections = ports.connections;

packages/cli/src/context/mcp/server.test.ts

@@ -3,7 +3,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
-import { describe, expect, it, vi } from 'vitest';
+import { afterEach, describe, expect, it, vi } from 'vitest';
 import { createLocalProjectMemoryIngest } from '../../context/memory/local-memory.js';
 import { detectCaptureSignals } from '../../context/memory/capture-signals.js';
 import type { MemoryAgentInput } from '../../context/memory/types.js';
@@ -47,6 +47,19 @@ function makeFakeServer() {
   };
 }
 
+function makeIo() {
+  let stderr = '';
+  return {
+    stdout: { isTTY: true, write() {} },
+    stderr: {
+      write(chunk: string) {
+        stderr += chunk;
+      },
+    },
+    stderrText: () => stderr,
+  };
+}
+
 function getTool(tools: RegisteredTool[], name: string): RegisteredTool {
   const found = tools.find((tool) => tool.name === name);
   if (!found) {
@@ -153,6 +166,11 @@ async function listToolsThroughSdk(contextTools: KtxMcpContextPorts) {
 }
 
 describe('createKtxMcpServer', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    vi.restoreAllMocks();
+  });
+
   it('registers annotations and output schemas for every retained tool', async () => {
     const fake = makeFakeServer();
     createKtxMcpServer({
@@ -227,6 +245,37 @@ describe('createKtxMcpServer', () => {
     });
   });
 
+  it('emits sampled debug telemetry for MCP tool requests', async () => {
+    vi.spyOn(Math, 'random').mockReturnValue(0);
+    vi.stubEnv('KTX_TELEMETRY_DEBUG', '1');
+    vi.stubEnv('CI', '');
+    const fake = makeFakeServer();
+    const io = makeIo();
+    const projectDir = '/tmp/ktx-mcp-telemetry';
+
+    createKtxMcpServer({
+      server: fake.server,
+      userContext: { userId: 'local-user' },
+      projectDir,
+      io,
+      contextTools: {
+        knowledge: {
+          search: vi.fn<KtxKnowledgeMcpPort['search']>().mockResolvedValue({ results: [], totalFound: 0 }),
+          read: vi.fn<KtxKnowledgeMcpPort['read']>().mockResolvedValue(null),
+        },
+      },
+    });
+
+    await expect(getTool(fake.tools, 'wiki_search').handler({ query: 'revenue recognition', limit: 5 })).resolves.toMatchObject({
+      structuredContent: { results: [], totalFound: 0 },
+    });
+
+    expect(io.stderrText()).toContain('"event":"mcp_request_completed"');
+    expect(io.stderrText()).toContain('"toolName":"wiki_search"');
+    expect(io.stderrText()).toContain('"sampleRate":0.1');
+    expect(io.stderrText()).not.toContain(projectDir);
+  });
+
   it('registers parser-gated sql_execution when the host provides a SQL execution port', async () => {
     const fake = makeFakeServer();
     const response: KtxSqlExecutionResponse = {

packages/cli/src/context/mcp/server.ts

@@ -9,6 +9,8 @@ export function createKtxMcpServer(deps: KtxMcpServerDeps): KtxMcpServerDeps['se
       server: deps.server,
       ports: deps.contextTools,
       userContext: deps.userContext,
+      projectDir: deps.projectDir,
+      io: deps.io,
     });
   }
 
@@ -26,6 +28,8 @@ export function createDefaultKtxMcpServer(
     server: server as KtxMcpServerLike,
     userContext: deps.userContext,
     contextTools: deps.contextTools,
+    projectDir: deps.projectDir,
+    io: deps.io,
   });
   return server;
 }

packages/cli/src/context/mcp/types.ts

@@ -1,4 +1,5 @@
 import type { MemoryIngestService } from '../../context/memory/memory-runs.js';
+import type { KtxCliIo } from '../../cli-runtime.js';
 import type { KtxEntityDetailsInput, KtxEntityDetailsResponse } from '../scan/entity-details.js';
 import type { KtxDiscoverDataInput, KtxDiscoverDataResponse } from '../../context/search/discover.js';
 import type { KtxDictionarySearchInput, KtxDictionarySearchResponse } from '../../context/sl/dictionary-search.js';
@@ -171,4 +172,6 @@ export interface KtxMcpServerDeps {
   server: KtxMcpServerLike;
   userContext: KtxMcpUserContext;
   contextTools?: KtxMcpContextPorts;
+  projectDir?: string;
+  io?: KtxCliIo;
 }