feat: report MCP client telemetry (#242)

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

@@ -47,10 +47,10 @@ function makeFakeServer() {
   };
 }
 
-function makeIo() {
+function makeIo(stdoutIsTTY = true) {
   let stderr = '';
   return {
-    stdout: { isTTY: true, write() {} },
+    stdout: { isTTY: stdoutIsTTY, write() {} },
     stderr: {
       write(chunk: string) {
         stderr += chunk;
@@ -272,8 +272,48 @@ describe('createKtxMcpServer', () => {
 
     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()).toContain('"sampleRate":1');
     expect(io.stderrText()).not.toContain(projectDir);
+    // No client connected through the SDK here, so getClientInfo is absent: the
+    // event still emits and the optional client fields are simply omitted.
+    expect(io.stderrText()).not.toContain('mcpClientName');
+    expect(io.stderrText()).not.toContain('mcpClientVersion');
+  });
+
+  it('captures the connecting MCP client name and version', async () => {
+    vi.stubEnv('KTX_TELEMETRY_DEBUG', '1');
+    vi.stubEnv('CI', '');
+    // Non-TTY io keeps the test hermetic (no ~/.ktx/telemetry.json is created)
+    // and mirrors a real headless MCP server; debug mode still emits the payload.
+    const io = makeIo(false);
+
+    const server = createDefaultKtxMcpServer({
+      name: 'ktx-test',
+      version: '0.0.0-test',
+      userContext: { userId: 'mcp-user' },
+      projectDir: '/tmp/ktx-mcp-client-telemetry',
+      io,
+      contextTools: {
+        knowledge: {
+          search: vi.fn<KtxKnowledgeMcpPort['search']>().mockResolvedValue({ results: [], totalFound: 0 }),
+          read: vi.fn<KtxKnowledgeMcpPort['read']>().mockResolvedValue(null),
+        },
+      },
+    });
+    const client = new Client({ name: 'test-agent', version: '9.9.9' });
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
+
+    try {
+      await client.callTool({ name: 'wiki_search', arguments: { query: 'revenue recognition', limit: 5 } });
+    } finally {
+      await client.close();
+      await server.close();
+    }
+
+    expect(io.stderrText()).toContain('"event":"mcp_request_completed"');
+    expect(io.stderrText()).toContain('"mcpClientName":"test-agent"');
+    expect(io.stderrText()).toContain('"mcpClientVersion":"9.9.9"');
   });
 
   it('registers parser-gated sql_execution when the host provides a SQL execution port', async () => {

packages/cli/test/telemetry/events.snapshot.test.ts

@@ -128,7 +128,9 @@ describe('telemetry privacy snapshot', () => {
         outcome: 'error',
         errorClass: 'KtxProjectMissingAbortError',
         durationMs: 12,
-        sampleRate: 0.1,
+        sampleRate: 1,
+        mcpClientName: 'Claude Desktop',
+        mcpClientVersion: '0.7.1',
       }),
     ];
 

packages/cli/test/telemetry/identity.test.ts

@@ -146,6 +146,75 @@ describe('telemetry identity', () => {
     });
   });
 
+  it('enables a consented identity without a TTY (MCP servers run headless)', async () => {
+    await mkdir(join(homeDir, '.ktx'), { recursive: true });
+    await writeFile(
+      join(homeDir, '.ktx', 'telemetry.json'),
+      JSON.stringify(
+        {
+          installId: '00000000-0000-4000-8000-000000000000',
+          enabled: true,
+          noticeShownAt: '2026-05-22T14:33:02.000Z',
+          noticeShownVersion: 1,
+          createdAt: '2026-05-22T14:33:02.000Z',
+        },
+        null,
+        2,
+      ) + '\n',
+      'utf-8',
+    );
+    const testIo = makeIo(false);
+
+    await expect(
+      loadTelemetryIdentity({
+        homeDir,
+        env,
+        stdoutIsTTY: false,
+        stderr: testIo.io.stderr,
+        now: () => new Date('2026-05-22T15:00:00.000Z'),
+      }),
+    ).resolves.toMatchObject({
+      installId: '00000000-0000-4000-8000-000000000000',
+      enabled: true,
+      createdFile: false,
+      noticeShown: false,
+    });
+    // The one-time notice belongs to interactive surfaces only; a headless load
+    // must never write it (the MCP stdio protocol shares the process streams).
+    expect(testIo.stderr()).toBe('');
+  });
+
+  it('keeps opt-outs suppressing a consented identity without a TTY', async () => {
+    await mkdir(join(homeDir, '.ktx'), { recursive: true });
+    await writeFile(
+      join(homeDir, '.ktx', 'telemetry.json'),
+      JSON.stringify(
+        {
+          installId: '00000000-0000-4000-8000-000000000000',
+          enabled: true,
+          noticeShownAt: '2026-05-22T14:33:02.000Z',
+          noticeShownVersion: 1,
+          createdAt: '2026-05-22T14:33:02.000Z',
+        },
+        null,
+        2,
+      ) + '\n',
+      'utf-8',
+    );
+
+    for (const optOut of [{ KTX_TELEMETRY_DISABLED: '1' }, { DO_NOT_TRACK: '1' }, { CI: '1' }]) {
+      await expect(
+        loadTelemetryIdentity({
+          homeDir,
+          env: optOut,
+          stdoutIsTTY: false,
+          stderr: makeIo(false).io.stderr,
+          now: () => new Date('2026-05-22T15:00:00.000Z'),
+        }),
+      ).resolves.toMatchObject({ enabled: false });
+    }
+  });
+
   it('recreates a corrupted file instead of surfacing an error to users', async () => {
     await mkdir(join(homeDir, '.ktx'), { recursive: true });
     await writeFile(join(homeDir, '.ktx', 'telemetry.json'), '{bad json', 'utf-8');