feat(setup): add Claude Desktop target and MCP-first agent setup (#114)

* feat(setup): add Claude Desktop target and MCP-first agent setup

Adds `ktx mcp stdio` and a `claude-desktop` setup target that generates a
local plugin ZIP wiring the analytics skill and a stdio MCP config. Replaces
the CLI-only agent install mode with MCP+analytics (default) and an optional
admin CLI skill, renames the research skill to analytics, and lets interactive
setup pick project vs global scope when every target supports it. Extracts a
shared MCP server factory used by both HTTP and stdio entrypoints.

* Add MCP agent client setup support

* Polish setup output formatting

* Add MCP tool polish design spec

Design for slimming the MCP-registered surface from 25 to 11 tools,
introducing memory_ingest, applying the per-tool polish kit (annotations,
outputSchema, .describe(), in-band error wrapping, union-drift fixes,
type-narrowed jsonToolResult), emitting progress notifications on
sql_execution + sl_query, and refining the ktx-analytics SKILL.md to
match.

* Refine MCP tool polish design spec after adversarial review iteration 1

* Refine MCP tool polish design spec after adversarial review iteration 2

* Refine MCP tool polish design spec after adversarial review iteration 3

* refactor(context): rename memory capture service to ingest

* feat(mcp): slim research tool surface

* refactor(mcp): remove admin ports from server factory

* refactor(cli): rename text ingest memory port

* docs: update analytics skill for memory ingest

* chore: verify mcp surface rename

* Add MCP tool polish v1 surface change plan

* feat(context): polish mcp tool metadata

* fix(context): enforce resolved semantic layer compute sources

* feat(context): emit mcp query progress stages

* fix(context): keep mcp progress event internal

* Add MCP tool polish v1 metadata & progress plan

* Fix CI snapshot and docs checks

packages/cli/src/commands/mcp-commands.test.ts

@@ -35,6 +35,7 @@ describe('registerMcpCommands', () => {
       'serve-internal',
       'start',
       'status',
+      'stdio',
       'stop',
     ]);
     expect(
@@ -54,4 +55,48 @@ describe('registerMcpCommands', () => {
     );
     expect(startDaemon).not.toHaveBeenCalled();
   });
+
+  it('prints "already running" when startDaemon reports already-running', async () => {
+    const program = new Command().exitOverride().option('--project-dir <path>');
+    const startDaemon = vi.fn().mockResolvedValue({
+      status: 'already-running',
+      url: 'http://127.0.0.1:7878/mcp',
+      state: {
+        schemaVersion: 1,
+        pid: 4242,
+        host: '127.0.0.1',
+        port: 7878,
+        tokenAuth: false,
+        projectDir: '/tmp/ktx-already',
+        startedAt: '2026-05-14T00:00:00.000Z',
+        logPath: '/tmp/ktx-already/.ktx/logs/mcp.log',
+      },
+    });
+    const context = makeContext({ deps: { mcp: { startDaemon } } });
+    registerMcpCommands(program, context);
+
+    await program.parseAsync(['--project-dir', '/tmp/ktx-already', 'mcp', 'start'], { from: 'user' });
+
+    expect(startDaemon).toHaveBeenCalledTimes(1);
+    expect(context.io.stdout.write).toHaveBeenCalledWith(
+      'KTX MCP daemon already running: http://127.0.0.1:7878/mcp\n',
+    );
+  });
+
+  it('runs the stdio server with the resolved project directory', async () => {
+    const program = new Command().exitOverride().option('--project-dir <path>');
+    const runStdioServer = vi.fn().mockResolvedValue(undefined);
+    const context = makeContext({ deps: { mcp: { runStdioServer } } });
+    registerMcpCommands(program, context);
+
+    await expect(program.parseAsync(['--project-dir', '/tmp/ktx6', 'mcp', 'stdio'], { from: 'user' })).resolves.toBe(
+      program,
+    );
+
+    expect(runStdioServer).toHaveBeenCalledWith({
+      projectDir: '/tmp/ktx6',
+      cliVersion: '0.0.0-test',
+      io: context.io,
+    });
+  });
 });

packages/cli/src/commands/mcp-commands.ts

@@ -15,6 +15,7 @@ import {
   stopKtxMcpDaemon,
 } from '../managed-mcp-daemon.js';
 import { buildMcpSecurityConfig, runKtxMcpHttpServer } from '../mcp-http-server.js';
+import { runKtxMcpStdioServer } from '../mcp-stdio-server.js';
 
 function tokenFromOption(value: string | undefined): string | undefined {
   return value ?? process.env.KTX_MCP_TOKEN;
@@ -27,6 +28,17 @@ function binPath(): string {
 export function registerMcpCommands(program: Command, context: KtxCliCommandContext): void {
   const mcp = program.command('mcp').description('Run the KTX MCP HTTP server');
 
+  mcp
+    .command('stdio')
+    .description('Run the KTX MCP server over stdio')
+    .action(async (_options, command) => {
+      await (context.deps.mcp?.runStdioServer ?? runKtxMcpStdioServer)({
+        projectDir: resolveCommandProjectDir(command),
+        cliVersion: context.packageInfo.version,
+        io: context.io,
+      });
+    });
+
   mcp
     .command('start')
     .description('Start the KTX MCP HTTP server')
@@ -70,7 +82,11 @@ export function registerMcpCommands(program: Command, context: KtxCliCommandCont
         allowedOrigins: options.allowedOrigin,
         binPath: binPath(),
       });
-      context.io.stdout.write(`KTX MCP daemon started: ${result.url}\n`);
+      context.io.stdout.write(
+        result.status === 'started'
+          ? `KTX MCP daemon started: ${result.url}\n`
+          : `KTX MCP daemon already running: ${result.url}\n`,
+      );
     });
 
   mcp

packages/cli/src/commands/setup-commands.ts

@@ -218,6 +218,7 @@ export function registerSetupCommands(program: Command, context: KtxCliCommandCo
     .addOption(
       new Option('--target <target>', 'Agent target').choices([
         'claude-code',
+        'claude-desktop',
         'codex',
         'cursor',
         'opencode',