feat(mcp):added MCP server (#97)

* docs(specs): design research-agent MCP tools and ktx mcp daemon Adds the 2026-05-14 design spec for exposing four new MCP tools (discover_data, entity_details, dictionary_search, sql_execution), shipping a ktx-research skill, and introducing an HTTP-only ktx mcp daemon so external agents can use KTX as a research-capable context layer. * Refine research-agent MCP tools spec after adversarial review iteration 1 * Refine research-agent MCP tools spec after adversarial review iteration 2 * Refine research-agent MCP tools spec after adversarial review iteration 3 * Refine spec: drop connectionName compat carve-out and ground summary/snippet provenance per kind * feat(daemon): validate read-only SQL with sqlglot * feat(context): expose read-only SQL validation port * feat(context): register MCP sql execution tool * feat(context): execute MCP SQL through validated connector path * test(context): update SQL analysis port fixtures * docs: add research-agent MCP sql execution foundation plan * feat(context): add scan-backed entity details service * feat(context): register MCP entity details tool * feat(context): expose local MCP entity details * test(context): align entity details scan fixtures * docs: add research-agent MCP entity_details plan * feat(context): add dictionary search service * feat(context): register MCP dictionary search tool * feat(context): expose local MCP dictionary search * docs: add research-agent MCP dictionary_search plan * feat: add MCP discover data service * feat: expose discover data MCP tool * feat: wire local discover data MCP port * docs: add research-agent MCP discover_data plan * feat(cli): add mcp http security helpers * feat(cli): host mcp over streamable http * feat(cli): manage mcp daemon lifecycle * feat(cli): add ktx mcp commands * fix(cli): stabilize mcp daemon verification * docs: add research-agent MCP http daemon plan * feat(cli): install KTX research skill * feat(cli): configure MCP clients in setup agents * feat(cli): support Claude local MCP setup scope * docs: add research-agent MCP setup-agents plan * refactor(context): use connectionId in warehouse verification tools * docs(context): update ingest verification prompts for connectionId * docs: add research-agent MCP ingest contract convergence plan * chore: build runtime artifacts in conductor setup --------- Co-authored-by: Andrey Avtomonov <7889985+andreybavt@users.noreply.github.com>
2026-07-13 11:22:11 +02:00 · 2026-05-15 02:35:09 +02:00 · 2026-05-15 02:35:09 +02:00 · b759a4a286
commit b759a4a286
parent c7b64379bf
78 changed files with 13689 additions and 190 deletions
--- a/packages/cli/src/managed-mcp-daemon.test.ts
+++ b/packages/cli/src/managed-mcp-daemon.test.ts
@ -0,0 +1,133 @@
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  mcpDaemonLayout,
+  readKtxMcpDaemonStatus,
+  startKtxMcpDaemon,
+  stopKtxMcpDaemon,
+  type KtxMcpDaemonChild,
+  type KtxMcpDaemonState,
+} from './managed-mcp-daemon.js';
+
+function child(pid = 4242): KtxMcpDaemonChild {
+  return { pid, unref: vi.fn() };
+}
+
+function state(projectDir: string, overrides: Partial<KtxMcpDaemonState> = {}): KtxMcpDaemonState {
+  return {
+    schemaVersion: 1,
+    pid: 4242,
+    host: '127.0.0.1',
+    port: 7878,
+    tokenAuth: false,
+    projectDir,
+    startedAt: '2026-05-14T00:00:00.000Z',
+    logPath: join(projectDir, '.ktx/logs/mcp.log'),
+    ...overrides,
+  };
+}
+
+describe('managed MCP daemon lifecycle', () => {
+  let tempDir: string;
+  let projectDir: string;
+
+  beforeEach(async () => {
+    tempDir = await mkdtemp(join(tmpdir(), 'ktx-mcp-daemon-'));
+    projectDir = join(tempDir, 'project');
+    await mkdir(projectDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  it('uses the spec state and log paths', () => {
+    expect(mcpDaemonLayout(projectDir)).toEqual({
+      statePath: join(projectDir, '.ktx/mcp.json'),
+      logPath: join(projectDir, '.ktx/logs/mcp.log'),
+    });
+  });
+
+  it('starts a detached child and writes state without the token value', async () => {
+    const spawnDaemon = vi.fn(() => child(5555));
+    await startKtxMcpDaemon({
+      projectDir,
+      cliVersion: '0.0.0-test',
+      host: '0.0.0.0',
+      port: 7879,
+      token: 'secret-token',
+      allowedHosts: ['mcp.example.test'],
+      allowedOrigins: ['https://mcp.example.test'],
+      binPath: '/repo/packages/cli/dist/bin.js',
+      spawnDaemon,
+      processAlive: vi.fn(() => false),
+      portAvailable: vi.fn(async () => true),
+      now: () => new Date('2026-05-14T00:00:00.000Z'),
+    });
+
+    expect(spawnDaemon).toHaveBeenCalledWith(
+      process.execPath,
+      [
+        '/repo/packages/cli/dist/bin.js',
+        '--project-dir',
+        projectDir,
+        'mcp',
+        'serve-internal',
+        '--host',
+        '0.0.0.0',
+        '--port',
+        '7879',
+        '--allowed-host',
+        'mcp.example.test',
+        '--allowed-origin',
+        'https://mcp.example.test',
+      ],
+      expect.objectContaining({
+        detached: true,
+        env: expect.objectContaining({ KTX_MCP_TOKEN: 'secret-token' }),
+      }),
+    );
+    expect(JSON.stringify(JSON.parse(await readFile(join(projectDir, '.ktx/mcp.json'), 'utf8')))).not.toContain(
+      'secret-token',
+    );
+  });
+
+  it('reports running when the process is alive and health passes', async () => {
+    await mkdir(join(projectDir, '.ktx'), { recursive: true });
+    await writeFile(join(projectDir, '.ktx/mcp.json'), `${JSON.stringify(state(projectDir), null, 2)}\n`);
+
+    const status = await readKtxMcpDaemonStatus({
+      projectDir,
+      processAlive: vi.fn(() => true),
+      fetchHealth: vi.fn(async () => ({ ok: true, body: { status: 'ok', projectDir, port: 7878 } })),
+    });
+
+    expect(status.kind).toBe('running');
+    if (status.kind !== 'running') {
+      throw new Error(`Expected running status, received ${status.kind}`);
+    }
+    expect(status.url).toBe('http://127.0.0.1:7878/mcp');
+  });
+
+  it('stops a recorded daemon and removes state', async () => {
+    await mkdir(join(projectDir, '.ktx'), { recursive: true });
+    await writeFile(join(projectDir, '.ktx/mcp.json'), `${JSON.stringify(state(projectDir), null, 2)}\n`);
+    const alive = new Set([4242]);
+    const killProcess = vi.fn((pid: number) => alive.delete(pid));
+
+    await expect(
+      stopKtxMcpDaemon({
+        projectDir,
+        processAlive: vi.fn((pid) => alive.has(pid)),
+        killProcess,
+        stopGraceMs: 1,
+        pollIntervalMs: 1,
+      }),
+    ).resolves.toEqual({ status: 'stopped' });
+
+    expect(killProcess).toHaveBeenCalledWith(4242, 'SIGTERM');
+    await expect(readFile(join(projectDir, '.ktx/mcp.json'), 'utf8')).rejects.toThrow();
+  });
+});