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>

packages/context/src/sql-analysis/http-sql-analysis-port.test.ts

@@ -108,6 +108,44 @@ describe('createHttpSqlAnalysisPort', () => {
     });
   });
 
+  it('maps read-only SQL validation responses', async () => {
+    const requests: Array<{ path: string; payload: Record<string, unknown> }> = [];
+    const port = createHttpSqlAnalysisPort({
+      baseUrl: 'http://127.0.0.1:8765',
+      requestJson: async (path, payload) => {
+        requests.push({ path, payload });
+        return { ok: false, error: 'SQL contains read/write operation: Insert' };
+      },
+    });
+
+    await expect(
+      port.validateReadOnly('with x as (insert into t values (1)) select * from x', 'postgres'),
+    ).resolves.toEqual({
+      ok: false,
+      error: 'SQL contains read/write operation: Insert',
+    });
+    expect(requests).toEqual([
+      {
+        path: '/sql/validate-read-only',
+        payload: {
+          dialect: 'postgres',
+          sql: 'with x as (insert into t values (1)) select * from x',
+        },
+      },
+    ]);
+  });
+
+  it('rejects malformed read-only validation responses', async () => {
+    const port = createHttpSqlAnalysisPort({
+      baseUrl: 'http://127.0.0.1:8765',
+      requestJson: async () => ({ ok: 'yes' }),
+    });
+
+    await expect(port.validateReadOnly('select 1', 'postgres')).rejects.toThrow(
+      'sql analysis response is missing boolean field ok',
+    );
+  });
+
   it('rejects malformed SQL batch responses instead of inventing defaults', async () => {
     const requestJson = vi.fn(async () => ({
       results: {

packages/context/src/sql-analysis/http-sql-analysis-port.ts

@@ -9,6 +9,7 @@ import type {
   SqlAnalysisLiteralSlot,
   SqlAnalysisLiteralSlotType,
   SqlAnalysisPort,
+  SqlReadOnlyValidationResult,
 } from './ports.js';
 
 export type KtxSqlAnalysisHttpJsonRunner = (
@@ -96,6 +97,14 @@ function requiredStringArray(raw: Record<string, unknown>, field: string): strin
   return value;
 }
 
+function requiredBoolean(raw: Record<string, unknown>, field: string): boolean {
+  const value = raw[field];
+  if (typeof value !== 'boolean') {
+    throw new Error(`sql analysis response is missing boolean field ${field}`);
+  }
+  return value;
+}
+
 function requiredObject(raw: Record<string, unknown>, field: string): Record<string, unknown> {
   const value = raw[field];
   if (!value || typeof value !== 'object' || Array.isArray(value)) {
@@ -187,6 +196,14 @@ function mapBatchResponse(raw: Record<string, unknown>): Map<string, SqlAnalysis
   );
 }
 
+function mapReadOnlyValidation(raw: Record<string, unknown>): SqlReadOnlyValidationResult {
+  const error = optionalString(raw, 'error');
+  return {
+    ok: requiredBoolean(raw, 'ok'),
+    ...(error !== undefined ? { error } : {}),
+  };
+}
+
 export function createHttpSqlAnalysisPort(options: HttpSqlAnalysisPortOptions): SqlAnalysisPort {
   const requestJson = options.requestJson ?? postJson(options.baseUrl);
 
@@ -205,5 +222,12 @@ export function createHttpSqlAnalysisPort(options: HttpSqlAnalysisPortOptions):
       });
       return mapBatchResponse(raw);
     },
+    async validateReadOnly(sql: string, dialect: SqlAnalysisDialect) {
+      const raw = await requestJson('/sql/validate-read-only', {
+        dialect,
+        sql,
+      });
+      return mapReadOnlyValidation(raw);
+    },
   };
 }

packages/context/src/sql-analysis/index.ts

@@ -9,4 +9,5 @@ export type {
   SqlAnalysisLiteralSlot,
   SqlAnalysisLiteralSlotType,
   SqlAnalysisPort,
+  SqlReadOnlyValidationResult,
 } from './ports.js';

packages/context/src/sql-analysis/ports.ts

@@ -38,10 +38,16 @@ export interface SqlAnalysisBatchResult {
   error?: string | null;
 }
 
+export interface SqlReadOnlyValidationResult {
+  ok: boolean;
+  error?: string | null;
+}
+
 export interface SqlAnalysisPort {
   analyzeForFingerprint(sql: string, dialect: SqlAnalysisDialect): Promise<SqlAnalysisFingerprintResult>;
   analyzeBatch(
     items: SqlAnalysisBatchItem[],
     dialect: SqlAnalysisDialect,
   ): Promise<Map<string, SqlAnalysisBatchResult>>;
+  validateReadOnly(sql: string, dialect: SqlAnalysisDialect): Promise<SqlReadOnlyValidationResult>;
 }