mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-10 08:05:14 +02:00
Merge branch 'main' into copy-claude-code-backend-spec
This commit is contained in:
Andrey Avtomonov
GitHub
commit
89b934cefa
32 changed files with 1866 additions and 318 deletions
|
|
@ -4,8 +4,8 @@ description: "Command map and shared options for the KTX CLI."
|
|||
---
|
||||
|
||||
The `ktx` CLI sets up local projects, builds agent-ready context, checks
|
||||
connections, queries semantic-layer sources, searches wiki pages, and manages
|
||||
the bundled Python runtime.
|
||||
connections, queries semantic-layer sources, searches wiki pages, runs the MCP
|
||||
server, and manages the bundled Python runtime.
|
||||
|
||||
## Command Map
|
||||
|
||||
|
|
@ -26,6 +26,11 @@ ktx
|
|||
validate <sourceName>
|
||||
query
|
||||
status
|
||||
mcp
|
||||
start
|
||||
stop
|
||||
status
|
||||
logs
|
||||
dev
|
||||
init [directory]
|
||||
schema
|
||||
|
|
@ -73,4 +78,7 @@ ktx ingest --all
|
|||
# Search semantic-layer sources and wiki pages
|
||||
ktx sl search "revenue"
|
||||
ktx wiki search "revenue recognition"
|
||||
|
||||
# Start the local MCP server for agent clients
|
||||
ktx mcp start
|
||||
```
|
||||
|
|
|
|||
|
|
@ -29,14 +29,16 @@ connections when you use `--all`.
|
|||
| `--deep` | Use AI-enriched database ingest | Stored connection default, or `fast` |
|
||||
| `--query-history` | Include database query-history usage patterns | Stored connection default |
|
||||
| `--no-query-history` | Skip database query-history usage patterns for this run | Stored connection default |
|
||||
| `--query-history-window-days <days>` | Query-history lookback window for this run | Stored connection default |
|
||||
| `--query-history-window-days <days>` | BigQuery/Snowflake query-history lookback window for this run | Stored connection default |
|
||||
| `--plain` | Print plain text output | `true` |
|
||||
| `--json` | Print JSON output | `false` |
|
||||
| `--no-input` | Disable interactive terminal input | — |
|
||||
|
||||
`--fast` and `--deep` are mutually exclusive. Depth flags apply only to
|
||||
database connections. Query-history flags apply only to database connections
|
||||
that support query history. Query-history ingest runs after schema ingest and
|
||||
that support query history. The window flag applies to BigQuery and Snowflake;
|
||||
Postgres reads the current `pg_stat_statements` aggregate data instead of a
|
||||
time-windowed history table. Query-history ingest runs after schema ingest and
|
||||
requires deep ingest readiness.
|
||||
|
||||
When `--all` selects both databases and context sources, database ingest runs
|
||||
|
|
@ -70,6 +72,7 @@ ktx ingest warehouse --deep
|
|||
|
||||
# Include query-history usage patterns
|
||||
ktx ingest warehouse --deep --query-history
|
||||
# Set the lookback window for BigQuery or Snowflake query history
|
||||
ktx ingest warehouse --query-history-window-days 30
|
||||
|
||||
# Build a source connection
|
||||
|
|
|
|||
70
docs-site/content/docs/cli-reference/ktx-mcp.mdx
Normal file
70
docs-site/content/docs/cli-reference/ktx-mcp.mdx
Normal file
|
|
@ -0,0 +1,70 @@
|
|||
---
|
||||
title: "ktx mcp"
|
||||
description: "Run the KTX MCP HTTP server for agent clients."
|
||||
---
|
||||
|
||||
`ktx mcp` starts, stops, inspects, and tails the local KTX MCP server for a KTX
|
||||
project. Use it when an agent client connects through MCP instead of generated
|
||||
CLI instructions.
|
||||
|
||||
## Command signature
|
||||
|
||||
```bash
|
||||
ktx mcp <subcommand> [options]
|
||||
```
|
||||
|
||||
## Subcommands
|
||||
|
||||
| Subcommand | Description |
|
||||
|-----------|-------------|
|
||||
| `start` | Start the KTX MCP HTTP server |
|
||||
| `stop` | Stop the KTX MCP daemon |
|
||||
| `status` | Show daemon status, URL, PID, token mode, and project path |
|
||||
| `logs` | Print the daemon log |
|
||||
|
||||
## `mcp start` Options
|
||||
|
||||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `--host <host>` | Host to bind | `127.0.0.1` |
|
||||
| `--port <n>` | Port to bind | `7878` |
|
||||
| `--token <token>` | Bearer token for non-loopback binding | `KTX_MCP_TOKEN` |
|
||||
| `--foreground` | Run the server in the foreground | `false` |
|
||||
| `--allowed-host <host>` | Additional allowed Host header; repeatable | - |
|
||||
| `--allowed-origin <origin>` | Allowed browser Origin header; repeatable | - |
|
||||
|
||||
## `mcp logs` Options
|
||||
|
||||
| Flag | Description | Default |
|
||||
|------|-------------|---------|
|
||||
| `--follow` | Follow log output | `false` |
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# Start the daemon on localhost
|
||||
ktx mcp start
|
||||
|
||||
# Check status
|
||||
ktx mcp status
|
||||
|
||||
# Tail logs
|
||||
ktx mcp logs --follow
|
||||
|
||||
# Run in the foreground on a custom port
|
||||
ktx mcp start --port 8787 --foreground
|
||||
```
|
||||
|
||||
## Security notes
|
||||
|
||||
The default host is loopback-only. If you bind to a non-loopback host, configure
|
||||
a bearer token with `--token <token>` or `KTX_MCP_TOKEN` and restrict allowed
|
||||
hosts and origins for browser clients.
|
||||
|
||||
## Common errors
|
||||
|
||||
| Error | Cause | Recovery |
|
||||
|-------|-------|----------|
|
||||
| No KTX project found | Current directory has no `ktx.yaml` and `KTX_PROJECT_DIR` is unset | Run from a KTX project or pass `--project-dir <path>` |
|
||||
| Non-loopback host rejected | The server needs token auth before binding beyond localhost | Pass `--token <token>` or set `KTX_MCP_TOKEN` |
|
||||
| Client cannot connect | Host, port, token, allowed host, or allowed origin does not match the client | Check `ktx mcp status`, then restart with explicit `--host`, `--port`, `--allowed-host`, and `--allowed-origin` values |
|
||||
|
|
@ -98,13 +98,16 @@ incomplete.
|
|||
|------|-------------|
|
||||
| `--enable-query-history` | Enable query-history ingest when the selected database supports it |
|
||||
| `--disable-query-history` | Disable query-history ingest for the selected database |
|
||||
| `--query-history-window-days <number>` | Query-history lookback window |
|
||||
| `--query-history-window-days <number>` | BigQuery/Snowflake query-history lookback window |
|
||||
| `--query-history-min-executions <number>` | Minimum executions for a query-history template |
|
||||
| `--query-history-service-account-pattern <pattern>` | Query-history service-account regex; repeatable |
|
||||
| `--query-history-redaction-pattern <pattern>` | Query-history SQL-literal redaction regex; repeatable |
|
||||
|
||||
Query history setup is supported for Postgres, BigQuery, and Snowflake. Enabling
|
||||
query history makes deep ingest readiness matter for later `ktx ingest` runs.
|
||||
Query history setup is supported for Postgres, BigQuery, and Snowflake. The
|
||||
window flag applies to BigQuery and Snowflake; Postgres reads the current
|
||||
`pg_stat_statements` aggregate data instead of a time-windowed history table.
|
||||
Enabling query history makes deep ingest readiness matter for later
|
||||
`ktx ingest` runs.
|
||||
|
||||
### Context Sources
|
||||
|
||||
|
|
|
|||
|
|
@ -9,6 +9,7 @@
|
|||
"ktx-sl",
|
||||
"ktx-wiki",
|
||||
"ktx-status",
|
||||
"ktx-mcp",
|
||||
"ktx-dev"
|
||||
]
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue