apunkt/ktx

mirror of https://github.com/Kaelio/ktx.git synced 2026-06-07 07:55:13 +02:00

Andrey Avtomonov b759a4a286 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-05-15 02:35:09 +02:00
..
src/ktx_daemon	feat(mcp):added MCP server (#97 )	2026-05-15 02:35:09 +02:00
tests	feat(mcp):added MCP server (#97 )	2026-05-15 02:35:09 +02:00
pyproject.toml	feat: npm-managed Python runtime for @kaelio/ktx (#7 )	2026-05-11 15:50:34 +02:00
README.md	rename klo to ktx	2026-05-10 23:51:24 +02:00

README.md

ktx-daemon

ktx-daemon is the portable Python compute package for KTX.

It supports portable compute in two modes:

One-shot commands, used by default by @ktx/context.
An explicit HTTP server for long-running local MCP sessions.

One-shot semantic query

printf '%s\n' '{"sources":[],"query":{"measures":[],"dimensions":[]},"dialect":"postgres"}' \
  | ktx-daemon semantic-query

One-shot source generation

Generate semantic-layer sources from schema scan data:

printf '%s\n' '{"tables":[{"name":"orders","db":"public","columns":[{"name":"id","type":"integer","primary_key":true}]}],"links":[],"dialect":"postgres"}' \
  | ktx-daemon semantic-generate-sources

One-shot database introspection

Introspect a Postgres database schema:

printf '%s\n' '{"connection_id":"warehouse","driver":"postgres","url":"postgresql://readonly@example.test/warehouse","schemas":["public"]}' \
  | ktx-daemon database-introspect

One-shot LookML parsing

Parse LookML projects into resolved, KSL-ready structures:

printf '%s\n' '{"files":[{"path":"views/orders.view.lkml","content":"view: orders { sql_table_name: public.orders ;; measure: order_count { type: count } }"}],"dialect":"postgres"}' \
  | ktx-daemon lookml-parse

One-shot embeddings

Compute text embeddings locally:

printf '%s\n' '{"text":"hello"}' \
  | ktx-daemon embedding-compute

Compute text embeddings locally in bulk:

printf '%s\n' '{"texts":["hello","world"]}' \
  | ktx-daemon embedding-compute-bulk

One-shot code execution

Execute Python code with the current in-process boundary:

printf '%s\n' '{"code":"result = 1 + 2"}' \
  | ktx-daemon code-execute

HTTP compute server

Start the HTTP compute server with code execution disabled:

ktx-daemon serve-http --host 127.0.0.1 --port 8765

Enable HTTP code execution explicitly:

ktx-daemon serve-http --host 127.0.0.1 --port 8765 --enable-code-execution

Available HTTP endpoints:

GET /health
POST /database/introspect
POST /embeddings/compute
POST /embeddings/compute-bulk
POST /lookml/parse
POST /semantic-layer/generate-sources
POST /semantic-layer/query
POST /semantic-layer/validate
POST /code/execute when --enable-code-execution is passed

The HTTP server exposes Postgres database introspection, LookML parsing, local embedding compute, and semantic-layer compute for source generation, query compilation, and validation. Code execution is off by default. When enabled, it runs Python exec in the daemon process with the same in-process boundary as the one-shot code-execute command and does not provide OS-level sandboxing.

HTTP code execution uses the standalone KTX boundary. It does not forward caller authorization headers to a host app and does not connect scratchpad or visualization helpers to host application APIs.