diff --git a/packages/cli/src/context/mcp/__snapshots__/mcp-tools-list.json b/packages/cli/src/context/mcp/__snapshots__/mcp-tools-list.json deleted file mode 100644 index 10cb0b77..00000000 --- a/packages/cli/src/context/mcp/__snapshots__/mcp-tools-list.json +++ /dev/null @@ -1,1620 +0,0 @@ -[ - { - "name": "connection_list", - "title": "Connection List", - "description": "List configured read-only data connections available to this KTX project. Use this before connection-scoped tools when the project may have multiple warehouses.", - "inputSchema": { - "type": "object", - "properties": {}, - "$schema": "http://json-schema.org/draft-07/schema#" - }, - "outputSchema": { - "type": "object", - "properties": { - "connections": { - "type": "array", - "items": { - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "name": { - "type": "string" - }, - "connectionType": { - "type": "string" - } - }, - "required": [ - "id", - "name", - "connectionType" - ], - "additionalProperties": false - } - } - }, - "required": [ - "connections" - ], - "$schema": "http://json-schema.org/draft-07/schema#", - "additionalProperties": false - }, - "annotations": { - "title": "Connection List", - "readOnlyHint": true, - "idempotentHint": true, - "openWorldHint": false - }, - "execution": { - "taskSupport": "forbidden" - } - }, - { - "name": "wiki_search", - "title": "Wiki Search", - "description": "Search KTX wiki pages for reusable business context. Example: wiki_search({ query: \"revenue recognition\", limit: 5 }).", - "inputSchema": { - "type": "object", - "properties": { - "query": { - "type": "string", - "minLength": 1, - "description": "Natural-language wiki search query, e.g. \"revenue recognition policy\"." - }, - "limit": { - "default": 10, - "description": "Maximum wiki pages to return. Defaults to 10.", - "type": "integer", - "minimum": 1, - "maximum": 50 - } - }, - "required": [ - "query" - ], - "$schema": "http://json-schema.org/draft-07/schema#" - }, - "outputSchema": { - "type": "object", - "properties": { - "results": { - "type": "array", - "items": { - "type": "object", - "properties": { - "key": { - "type": "string" - }, - "path": { - "type": "string" - }, - "scope": { - "type": "string", - "enum": [ - "GLOBAL", - "USER" - ] - }, - "summary": { - "type": "string" - }, - "score": { - "type": "number" - }, - "matchReasons": { - "type": "array", - "items": { - "type": "string" - } - }, - "lanes": { - "type": "array", - "items": { - "type": "object", - "properties": { - "lane": { - "type": "string" - }, - "status": { - "type": "string" - }, - "requestedCandidatePoolLimit": { - "type": "number" - }, - "effectiveCandidatePoolLimit": { - "type": "number" - }, - "returnedCandidateCount": { - "type": "number" - }, - "weight": { - "type": "number" - }, - "reason": { - "type": "string" - } - }, - "required": [ - "lane", - "status", - "requestedCandidatePoolLimit", - "effectiveCandidatePoolLimit", - "returnedCandidateCount", - "weight" - ], - "additionalProperties": false - } - } - }, - "required": [ - "key", - "path", - "scope", - "summary", - "score" - ], - "additionalProperties": false - } - }, - "totalFound": { - "type": "number" - } - }, - "required": [ - "results", - "totalFound" - ], - "$schema": "http://json-schema.org/draft-07/schema#", - "additionalProperties": false - }, - "annotations": { - "title": "Wiki Search", - "readOnlyHint": true, - "openWorldHint": false - }, - "execution": { - "taskSupport": "forbidden" - } - }, - { - "name": "wiki_read", - "title": "Wiki Read", - "description": "Read a KTX wiki page by key returned from wiki_search. Example: wiki_read({ key: \"global/revenue\" }).", - "inputSchema": { - "type": "object", - "properties": { - "key": { - "type": "string", - "minLength": 1, - "description": "Wiki page key returned by wiki_search, e.g. \"global/revenue\"." - } - }, - "required": [ - "key" - ], - "$schema": "http://json-schema.org/draft-07/schema#" - }, - "outputSchema": { - "type": "object", - "properties": { - "key": { - "type": "string" - }, - "summary": { - "type": "string" - }, - "content": { - "type": "string" - }, - "scope": { - "type": "string", - "enum": [ - "GLOBAL", - "USER" - ] - }, - "tags": { - "type": "array", - "items": { - "type": "string" - } - }, - "refs": { - "type": "array", - "items": { - "type": "string" - } - }, - "slRefs": { - "type": "array", - "items": { - "type": "string" - } - } - }, - "required": [ - "key", - "summary", - "content", - "scope" - ], - "$schema": "http://json-schema.org/draft-07/schema#", - "additionalProperties": false - }, - "annotations": { - "title": "Wiki Read", - "readOnlyHint": true, - "idempotentHint": true, - "openWorldHint": false - }, - "execution": { - "taskSupport": "forbidden" - } - }, - { - "name": "sl_read_source", - "title": "Semantic Layer Read Source", - "description": "Read a semantic-layer YAML source by connection id and source name. Example: sl_read_source({ connectionId: \"warehouse\", sourceName: \"orders\" }).", - "inputSchema": { - "type": "object", - "properties": { - "connectionId": { - "type": "string", - "minLength": 1, - "description": "Connection id that owns the semantic-layer source." - }, - "sourceName": { - "type": "string", - "minLength": 1, - "description": "Semantic-layer source name without \".yaml\", e.g. \"orders\"." - } - }, - "required": [ - "connectionId", - "sourceName" - ], - "$schema": "http://json-schema.org/draft-07/schema#" - }, - "outputSchema": { - "type": "object", - "properties": { - "sourceName": { - "type": "string" - }, - "yaml": { - "type": "string" - } - }, - "required": [ - "sourceName", - "yaml" - ], - "$schema": "http://json-schema.org/draft-07/schema#", - "additionalProperties": false - }, - "annotations": { - "title": "Semantic Layer Read Source", - "readOnlyHint": true, - "idempotentHint": true, - "openWorldHint": false - }, - "execution": { - "taskSupport": "forbidden" - } - }, - { - "name": "sl_query", - "title": "Semantic Layer Query", - "description": "Execute a semantic-layer query and return rows, headers, generated SQL, and plan details. Example: sl_query({ connectionId: \"warehouse\", measures: [\"orders.order_count\"], dimensions: [{ field: \"orders.created_at\", granularity: \"month\" }] }).", - "inputSchema": { - "type": "object", - "properties": { - "connectionId": { - "description": "Connection id to query. Omit only when the project has exactly one configured connection.", - "type": "string", - "minLength": 1 - }, - "measures": { - "minItems": 1, - "type": "array", - "items": { - "anyOf": [ - { - "type": "string", - "description": "Semantic-layer measure key, e.g. \"orders.order_count\"." - }, - { - "type": "object", - "properties": { - "expr": { - "type": "string", - "minLength": 1, - "description": "Ad hoc aggregate expression, e.g. \"sum(orders.amount)\"." - }, - "name": { - "type": "string", - "minLength": 1, - "description": "Alias for the ad hoc measure, e.g. \"gross_revenue\"." - } - }, - "required": [ - "expr", - "name" - ] - } - ] - }, - "description": "Measures to select. Use semantic-layer keys when available." - }, - "dimensions": { - "default": [], - "description": "Dimensions to group by. Use {field, granularity?} entries.", - "type": "array", - "items": { - "type": "object", - "properties": { - "field": { - "type": "string", - "minLength": 1, - "description": "Dimension to group by, e.g. \"orders.created_at\" or \"orders.status\"." - }, - "granularity": { - "description": "Time grain for time dimensions: day, week, month, quarter, or year.", - "type": "string", - "minLength": 1 - } - }, - "required": [ - "field" - ] - } - }, - "filters": { - "default": [], - "description": "Semantic-layer filter expressions to apply.", - "type": "array", - "items": { - "type": "string", - "description": "Semantic-layer filter expression, e.g. \"orders.status = paid\"." - } - }, - "segments": { - "default": [], - "description": "Semantic-layer segment keys to apply.", - "type": "array", - "items": { - "type": "string", - "description": "Semantic-layer segment key to apply." - } - }, - "order_by": { - "default": [], - "description": "Sort clauses. Use {field, direction?} entries.", - "type": "array", - "items": { - "type": "object", - "properties": { - "field": { - "type": "string", - "minLength": 1, - "description": "Field/measure/dimension id to order by, e.g. \"orders.created_at\", a dimension key like \"mart_nrr_quarterly.quarter_label\", or a measure alias." - }, - "direction": { - "default": "asc", - "description": "Sort direction: \"asc\" or \"desc\". Defaults to \"asc\".", - "type": "string", - "enum": [ - "asc", - "desc" - ] - } - }, - "required": [ - "field" - ] - } - }, - "limit": { - "default": 1000, - "description": "Maximum rows to return. Defaults to 1000.", - "type": "integer", - "minimum": 0, - "maximum": 9007199254740991 - }, - "include_empty": { - "default": true, - "description": "Whether to include empty dimension groups. Defaults to true.", - "type": "boolean" - } - }, - "required": [ - "measures" - ], - "$schema": "http://json-schema.org/draft-07/schema#" - }, - "outputSchema": { - "type": "object", - "properties": { - "connectionId": { - "type": "string" - }, - "dialect": { - "type": "string" - }, - "sql": { - "type": "string" - }, - "headers": { - "type": "array", - "items": { - "type": "string" - } - }, - "rows": { - "type": "array", - "items": { - "type": "array", - "items": {} - } - }, - "totalRows": { - "type": "number" - }, - "plan": { - "type": "object", - "propertyNames": { - "type": "string" - }, - "additionalProperties": {} - } - }, - "required": [ - "sql", - "headers", - "rows", - "totalRows" - ], - "$schema": "http://json-schema.org/draft-07/schema#", - "additionalProperties": false - }, - "annotations": { - "title": "Semantic Layer Query", - "readOnlyHint": true, - "openWorldHint": false - }, - "execution": { - "taskSupport": "forbidden" - } - }, - { - "name": "entity_details", - "title": "Entity Details", - "description": "Read table and column metadata from the latest live-database scan snapshot. Example: entity_details({ connectionId: \"warehouse\", entities: [{ table: { catalog: null, db: \"public\", name: \"orders\" }, columns: [\"id\"] }] }).", - "inputSchema": { - "type": "object", - "properties": { - "connectionId": { - "type": "string", - "minLength": 1, - "description": "Connection id whose latest scan snapshot should be read." - }, - "entities": { - "minItems": 1, - "maxItems": 20, - "type": "array", - "items": { - "type": "object", - "properties": { - "table": { - "anyOf": [ - { - "type": "string", - "minLength": 1 - }, - { - "type": "object", - "properties": { - "catalog": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "description": "Catalog/project/database. Use null when not applicable." - }, - "db": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "description": "Schema/database/dataset. Use null when not applicable." - }, - "name": { - "type": "string", - "minLength": 1, - "description": "Table name." - } - }, - "required": [ - "catalog", - "db", - "name" - ] - } - ], - "description": "Table display string or canonical object ref." - }, - "columns": { - "description": "Optional column filter.", - "type": "array", - "items": { - "type": "string", - "minLength": 1, - "description": "Column name to inspect." - } - } - }, - "required": [ - "table" - ] - }, - "description": "Tables or columns to inspect. Maximum 20 entities." - } - }, - "required": [ - "connectionId", - "entities" - ], - "$schema": "http://json-schema.org/draft-07/schema#" - }, - "outputSchema": { - "type": "object", - "properties": { - "results": { - "type": "array", - "items": { - "anyOf": [ - { - "type": "object", - "properties": { - "ok": { - "type": "boolean", - "const": true - }, - "connectionId": { - "type": "string" - }, - "tableRef": { - "type": "object", - "properties": { - "catalog": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - }, - "db": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - }, - "name": { - "type": "string" - } - }, - "required": [ - "catalog", - "db", - "name" - ], - "additionalProperties": false - }, - "display": { - "type": "string" - }, - "kind": { - "type": "string", - "enum": [ - "table", - "view", - "external", - "event_stream" - ] - }, - "comment": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - }, - "estimatedRows": { - "anyOf": [ - { - "type": "number" - }, - { - "type": "null" - } - ] - }, - "columns": { - "type": "array", - "items": { - "type": "object", - "properties": { - "name": { - "type": "string" - }, - "nativeType": { - "type": "string" - }, - "normalizedType": { - "type": "string" - }, - "dimensionType": { - "type": "string", - "enum": [ - "time", - "string", - "number", - "boolean" - ] - }, - "nullable": { - "type": "boolean" - }, - "primaryKey": { - "type": "boolean" - }, - "comment": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - } - }, - "required": [ - "name", - "nativeType", - "normalizedType", - "dimensionType", - "nullable", - "primaryKey", - "comment" - ], - "additionalProperties": false - } - }, - "foreignKeys": { - "type": "array", - "items": { - "type": "object", - "properties": { - "fromColumn": { - "type": "string" - }, - "toCatalog": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - }, - "toDb": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - }, - "toTable": { - "type": "string" - }, - "toColumn": { - "type": "string" - }, - "constraintName": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - } - }, - "required": [ - "fromColumn", - "toCatalog", - "toDb", - "toTable", - "toColumn", - "constraintName" - ], - "additionalProperties": false - } - }, - "snapshot": { - "type": "object", - "properties": { - "syncId": { - "type": "string" - }, - "extractedAt": { - "type": "string" - }, - "scanRunId": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - } - }, - "required": [ - "syncId", - "extractedAt", - "scanRunId" - ], - "additionalProperties": false - } - }, - "required": [ - "ok", - "connectionId", - "tableRef", - "display", - "kind", - "comment", - "estimatedRows", - "columns", - "foreignKeys", - "snapshot" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "ok": { - "type": "boolean", - "const": false - }, - "connectionId": { - "type": "string" - }, - "table": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "object", - "properties": { - "catalog": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - }, - "db": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - }, - "name": { - "type": "string" - } - }, - "required": [ - "catalog", - "db", - "name" - ], - "additionalProperties": false - } - ] - }, - "snapshot": { - "type": "object", - "properties": { - "syncId": { - "type": "string" - }, - "extractedAt": { - "type": "string" - }, - "scanRunId": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - } - }, - "required": [ - "syncId", - "extractedAt", - "scanRunId" - ], - "additionalProperties": false - }, - "error": { - "type": "object", - "properties": { - "code": { - "type": "string", - "enum": [ - "scan_missing", - "table_not_found", - "ambiguous_table", - "column_not_found" - ] - }, - "message": { - "type": "string" - }, - "candidates": { - "anyOf": [ - { - "type": "array", - "items": { - "type": "object", - "properties": { - "tableRef": { - "type": "object", - "properties": { - "catalog": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - }, - "db": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - }, - "name": { - "type": "string" - } - }, - "required": [ - "catalog", - "db", - "name" - ], - "additionalProperties": false - }, - "display": { - "type": "string" - } - }, - "required": [ - "tableRef", - "display" - ], - "additionalProperties": false - } - }, - { - "type": "array", - "items": { - "type": "string" - } - } - ] - } - }, - "required": [ - "code", - "message" - ], - "additionalProperties": false - } - }, - "required": [ - "ok", - "connectionId", - "table", - "error" - ], - "additionalProperties": false - } - ] - } - } - }, - "required": [ - "results" - ], - "$schema": "http://json-schema.org/draft-07/schema#", - "additionalProperties": false - }, - "annotations": { - "title": "Entity Details", - "readOnlyHint": true, - "idempotentHint": true, - "openWorldHint": false - }, - "execution": { - "taskSupport": "forbidden" - } - }, - { - "name": "dictionary_search", - "title": "Dictionary Search", - "description": "Search profile-sampled warehouse values to locate likely source columns for business values. Example: dictionary_search({ values: [\"Acme Corp\"], connectionId: \"warehouse\" }).", - "inputSchema": { - "type": "object", - "properties": { - "values": { - "minItems": 1, - "maxItems": 20, - "type": "array", - "items": { - "type": "string", - "minLength": 1, - "description": "Business value to locate, e.g. \"Acme Corp\" or \"enterprise\"." - }, - "description": "Values to search for in sampled warehouse dictionaries." - }, - "connectionId": { - "description": "Optional connection id. Pass it when user intent pins a specific warehouse.", - "type": "string", - "minLength": 1 - } - }, - "required": [ - "values" - ], - "$schema": "http://json-schema.org/draft-07/schema#" - }, - "outputSchema": { - "type": "object", - "properties": { - "searched": { - "type": "array", - "items": { - "type": "object", - "properties": { - "connectionId": { - "type": "string" - }, - "coverage": { - "type": "object", - "properties": { - "sampledRows": { - "anyOf": [ - { - "type": "number" - }, - { - "type": "null" - } - ] - }, - "valuesPerColumn": { - "anyOf": [ - { - "type": "number" - }, - { - "type": "null" - } - ] - }, - "profiledColumns": { - "type": "number" - }, - "syncId": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - }, - "profiledAt": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - } - }, - "required": [ - "sampledRows", - "valuesPerColumn", - "profiledColumns", - "syncId", - "profiledAt" - ], - "additionalProperties": false - }, - "status": { - "type": "string", - "enum": [ - "ready", - "no_profile_artifact", - "no_candidate_columns" - ] - } - }, - "required": [ - "connectionId", - "coverage", - "status" - ], - "additionalProperties": false - } - }, - "results": { - "type": "array", - "items": { - "type": "object", - "properties": { - "value": { - "type": "string" - }, - "matches": { - "type": "array", - "items": { - "type": "object", - "properties": { - "connectionId": { - "type": "string" - }, - "sourceName": { - "type": "string" - }, - "columnName": { - "type": "string" - }, - "matchedValue": { - "type": "string" - }, - "cardinality": { - "anyOf": [ - { - "type": "number" - }, - { - "type": "null" - } - ] - } - }, - "required": [ - "connectionId", - "sourceName", - "columnName", - "matchedValue", - "cardinality" - ], - "additionalProperties": false - } - }, - "misses": { - "type": "array", - "items": { - "type": "object", - "properties": { - "connectionId": { - "type": "string" - }, - "reason": { - "type": "string", - "enum": [ - "no_profile_artifact", - "no_candidate_columns", - "value_not_in_sample" - ] - } - }, - "required": [ - "connectionId", - "reason" - ], - "additionalProperties": false - } - } - }, - "required": [ - "value", - "matches", - "misses" - ], - "additionalProperties": false - } - } - }, - "required": [ - "searched", - "results" - ], - "$schema": "http://json-schema.org/draft-07/schema#", - "additionalProperties": false - }, - "annotations": { - "title": "Dictionary Search", - "readOnlyHint": true, - "openWorldHint": false - }, - "execution": { - "taskSupport": "forbidden" - } - }, - { - "name": "discover_data", - "title": "Discover Data", - "description": "Search across KTX wiki pages, semantic-layer sources, measures, dimensions, raw tables, and columns. Example: discover_data({ query: \"monthly orders by customer\", connectionId: \"warehouse\", kinds: [\"sl_source\", \"table\"] }).", - "inputSchema": { - "type": "object", - "properties": { - "query": { - "type": "string", - "minLength": 1, - "description": "Natural-language discovery query, e.g. \"monthly orders by customer\"." - }, - "connectionId": { - "description": "Optional connection id. Pass it when user intent pins a specific warehouse.", - "type": "string", - "minLength": 1 - }, - "kinds": { - "description": "Optional kind filter.", - "type": "array", - "items": { - "type": "string", - "enum": [ - "wiki", - "sl_source", - "sl_measure", - "sl_dimension", - "table", - "column" - ], - "description": "Reference kind to include." - } - }, - "limit": { - "description": "Maximum refs to return. Defaults to 15.", - "default": 15, - "type": "integer", - "minimum": 1, - "maximum": 50 - } - }, - "required": [ - "query" - ], - "$schema": "http://json-schema.org/draft-07/schema#" - }, - "outputSchema": { - "type": "object", - "properties": { - "refs": { - "type": "array", - "items": { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": [ - "wiki", - "sl_source", - "sl_measure", - "sl_dimension", - "table", - "column" - ] - }, - "id": { - "type": "string" - }, - "score": { - "type": "number" - }, - "summary": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - }, - "snippet": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - }, - "matchedOn": { - "type": "string", - "enum": [ - "name", - "display", - "description", - "comment", - "expr", - "sample_value", - "body" - ] - }, - "connectionId": { - "type": "string" - }, - "tableRef": { - "type": "object", - "properties": { - "catalog": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - }, - "db": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - }, - "name": { - "type": "string" - } - }, - "required": [ - "catalog", - "db", - "name" - ], - "additionalProperties": false - }, - "columnName": { - "type": "string" - } - }, - "required": [ - "kind", - "id", - "score", - "summary", - "snippet", - "matchedOn" - ], - "additionalProperties": false - } - } - }, - "required": [ - "refs" - ], - "$schema": "http://json-schema.org/draft-07/schema#", - "additionalProperties": false - }, - "annotations": { - "title": "Discover Data", - "readOnlyHint": true, - "openWorldHint": false - }, - "execution": { - "taskSupport": "forbidden" - } - }, - { - "name": "sql_execution", - "title": "SQL Execution", - "description": "Execute one parser-validated read-only SQL query against a configured KTX connection. Example: sql_execution({ connectionId: \"warehouse\", sql: \"select count(*) from public.orders\", maxRows: 100 }).", - "inputSchema": { - "type": "object", - "properties": { - "connectionId": { - "type": "string", - "minLength": 1, - "description": "Connection id to execute against. Required for raw SQL." - }, - "sql": { - "type": "string", - "minLength": 1, - "description": "Parser-validated read-only SQL, e.g. \"select count(*) from public.orders\"." - }, - "maxRows": { - "description": "Maximum rows to return. Defaults to 1000.", - "default": 1000, - "type": "integer", - "minimum": 1, - "maximum": 10000 - } - }, - "required": [ - "connectionId", - "sql" - ], - "$schema": "http://json-schema.org/draft-07/schema#" - }, - "outputSchema": { - "type": "object", - "properties": { - "headers": { - "type": "array", - "items": { - "type": "string" - } - }, - "headerTypes": { - "type": "array", - "items": { - "type": "string" - } - }, - "rows": { - "type": "array", - "items": { - "type": "array", - "items": {} - } - }, - "rowCount": { - "type": "number" - } - }, - "required": [ - "headers", - "rows", - "rowCount" - ], - "$schema": "http://json-schema.org/draft-07/schema#", - "additionalProperties": false - }, - "annotations": { - "title": "SQL Execution", - "readOnlyHint": true, - "openWorldHint": false - }, - "execution": { - "taskSupport": "forbidden" - } - }, - { - "name": "memory_ingest", - "title": "Memory Ingest", - "description": "Ingest free-form markdown knowledge into durable KTX memory. Use this for business rules, metric definitions, schema gotchas, recurring findings, or explicit user requests to remember something. Example: memory_ingest({ connectionId: \"warehouse\", content: \"ARR is reported in cents in this warehouse.\" }).", - "inputSchema": { - "type": "object", - "properties": { - "content": { - "type": "string", - "minLength": 1, - "description": "Free-form markdown to ingest. Include the knowledge itself plus any context (source, the user question, why this came up) that the memory agent should consider when triaging into wiki/SL." - }, - "connectionId": { - "description": "Scope this memory to a specific connection. Required when the knowledge is warehouse-specific, including measure definitions, schema gotchas, or anything tied to a particular warehouse. Omit only for global wiki knowledge.", - "type": "string", - "minLength": 1 - } - }, - "required": [ - "content" - ], - "$schema": "http://json-schema.org/draft-07/schema#" - }, - "outputSchema": { - "type": "object", - "properties": { - "runId": { - "type": "string" - } - }, - "required": [ - "runId" - ], - "$schema": "http://json-schema.org/draft-07/schema#", - "additionalProperties": false - }, - "annotations": { - "title": "Memory Ingest", - "destructiveHint": true, - "openWorldHint": false - }, - "execution": { - "taskSupport": "forbidden" - } - }, - { - "name": "memory_ingest_status", - "title": "Memory Ingest Status", - "description": "Read the current or final status for a memory ingest run. Example: memory_ingest_status({ runId: \"memory-run-1\" }).", - "inputSchema": { - "type": "object", - "properties": { - "runId": { - "type": "string", - "minLength": 1, - "description": "The memory ingest run id returned by memory_ingest." - } - }, - "required": [ - "runId" - ], - "$schema": "http://json-schema.org/draft-07/schema#" - }, - "outputSchema": { - "type": "object", - "properties": { - "runId": { - "type": "string" - }, - "status": { - "type": "string", - "enum": [ - "running", - "done", - "error" - ] - }, - "stage": { - "type": "string" - }, - "done": { - "type": "boolean" - }, - "captured": { - "type": "object", - "properties": { - "wiki": { - "type": "array", - "items": { - "type": "string" - } - }, - "sl": { - "type": "array", - "items": { - "type": "string" - } - }, - "xrefs": { - "type": "array", - "items": { - "type": "string" - } - } - }, - "required": [ - "wiki", - "sl", - "xrefs" - ], - "additionalProperties": false - }, - "error": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - }, - "commitHash": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - }, - "skillsLoaded": { - "type": "array", - "items": { - "type": "string" - } - }, - "signalDetected": { - "type": "boolean" - } - }, - "required": [ - "runId", - "status", - "stage", - "done", - "captured", - "error", - "commitHash", - "skillsLoaded", - "signalDetected" - ], - "$schema": "http://json-schema.org/draft-07/schema#", - "additionalProperties": false - }, - "annotations": { - "title": "Memory Ingest Status", - "readOnlyHint": true, - "openWorldHint": false - }, - "execution": { - "taskSupport": "forbidden" - } - } -] diff --git a/packages/cli/src/context/mcp/context-tools.ts b/packages/cli/src/context/mcp/context-tools.ts index aa593f7f..057e570b 100644 --- a/packages/cli/src/context/mcp/context-tools.ts +++ b/packages/cli/src/context/mcp/context-tools.ts @@ -12,6 +12,7 @@ import type { KtxMcpToolHandlerContext, KtxMcpToolResult, KtxMcpUserContext, + KtxSemanticLayerQueryResponse, NonArrayObject, } from './types.js'; @@ -60,7 +61,7 @@ const toolDescriptions = { sl_read_source: 'Read a semantic-layer YAML source by connection id and source name. Example: sl_read_source({ connectionId: "warehouse", sourceName: "orders" }).', sl_query: - 'Execute a semantic-layer query and return rows, headers, generated SQL, and plan details. Example: sl_query({ connectionId: "warehouse", measures: ["orders.order_count"], dimensions: [{ field: "orders.created_at", granularity: "month" }] }).', + 'Execute a semantic-layer query and return headers, rows, and total row count, plus correctness notes (e.g. compile-only or fan-out) when relevant. The generated SQL and full query plan are omitted by default; request them with include: ["sql"] and/or include: ["plan"]. Example: sl_query({ connectionId: "warehouse", measures: ["orders.order_count"], dimensions: [{ field: "orders.created_at", granularity: "month" }], include: ["sql"] }).', sql_execution: 'Execute one parser-validated read-only SQL query against a configured KTX connection. Example: sql_execution({ connectionId: "warehouse", sql: "select count(*) from public.orders", maxRows: 100 }).', memory_ingest: @@ -73,7 +74,7 @@ const connectionListSchema = z.object({}); const knowledgeSearchSchema = z.object({ query: z.string().min(1).describe('Natural-language wiki search query, e.g. "revenue recognition policy".'), - limit: z.number().int().min(1).max(50).default(10).describe('Maximum wiki pages to return. Defaults to 10.'), + limit: z.number().int().min(1).max(50).default(10).describe('Maximum wiki pages to return.'), }); const knowledgeReadSchema = z.object({ @@ -109,10 +110,7 @@ const slQueryOrderBySchema = z.object({ .describe( 'Field/measure/dimension id to order by, e.g. "orders.created_at", a dimension key like "mart_nrr_quarterly.quarter_label", or a measure alias.', ), - direction: z - .enum(['asc', 'desc']) - .default('asc') - .describe('Sort direction: "asc" or "desc". Defaults to "asc".'), + direction: z.enum(['asc', 'desc']).default('asc').describe('Sort direction for this field.'), }); const slQuerySchema = z.object({ @@ -136,8 +134,12 @@ const slQuerySchema = z.object({ .array(slQueryOrderBySchema) .default([]) .describe('Sort clauses. Use {field, direction?} entries.'), - limit: z.number().int().min(0).default(1000).describe('Maximum rows to return. Defaults to 1000.'), - include_empty: z.boolean().default(true).describe('Whether to include empty dimension groups. Defaults to true.'), + limit: z.number().int().min(0).default(1000).describe('Maximum rows to return.'), + include_empty: z.boolean().default(true).describe('Whether to include empty dimension groups.'), + include: z + .array(z.enum(['plan', 'sql'])) + .default([]) + .describe('Extra detail to attach to the response: "sql" for the generated SQL, "plan" for the full query plan.'), }); const entityDetailsTableRefSchema = z.object({ @@ -184,13 +186,13 @@ const discoverDataSchema = z.object({ .optional() .describe('Optional connection id. Pass it when user intent pins a specific warehouse.'), kinds: z.array(discoverDataKindSchema.describe('Reference kind to include.')).optional().describe('Optional kind filter.'), - limit: z.number().int().min(1).max(50).default(15).optional().describe('Maximum refs to return. Defaults to 15.'), + limit: z.number().int().min(1).max(50).default(10).optional().describe('Maximum refs to return.'), }); const sqlExecutionSchema = z.object({ connectionId: connectionIdSchema.describe('Connection id to execute against. Required for raw SQL.'), sql: z.string().min(1).describe('Parser-validated read-only SQL, e.g. "select count(*) from public.orders".'), - maxRows: z.number().int().min(1).max(10_000).default(1000).optional().describe('Maximum rows to return. Defaults to 1000.'), + maxRows: z.number().int().min(1).max(10_000).default(1000).optional().describe('Maximum rows to return.'), }); const memoryIngestSchema = z.object({ @@ -266,10 +268,14 @@ const slReadSourceOutputSchema = z.object({ const slQueryOutputSchema = z.object({ connectionId: z.string().optional(), dialect: z.string().optional(), - sql: z.string(), headers: z.array(z.string()), rows: z.array(z.array(z.unknown())), totalRows: z.number(), + // Correctness signals hoisted out of `plan` so they survive default projection (e.g. compile-only + // status, fan-out warnings). Present only when there is something to report. + notes: z.array(z.string()).optional(), + // Opt-in detail, attached only when requested via the `include` input. + sql: z.string().optional(), plan: unknownRecordSchema.optional(), }); @@ -411,12 +417,59 @@ const memoryIngestStatusOutputSchema = z.object({ /** @internal */ export function jsonToolResult(structuredContent: T): KtxMcpToolResult { + // Compact (non-indented) JSON: this `content` text is the copy the model reads. Pretty-printing + // arrays-of-arrays (every `rows` payload) puts one scalar per line, inflating tabular results by + // a large constant factor. `structuredContent` carries the same data for structured-output clients. return { - content: [{ type: 'text', text: JSON.stringify(structuredContent, null, 2) }], + content: [{ type: 'text', text: JSON.stringify(structuredContent) }], structuredContent, }; } +/** + * Pull the correctness-critical signals out of a query plan so they survive even when the caller + * did not opt into the full `plan`. Returns an empty list when there is nothing to flag. + */ +function slQueryNotes(plan: Record | undefined): string[] { + if (!plan) { + return []; + } + const notes: string[] = []; + const execution = plan.execution; + if ( + execution && + typeof execution === 'object' && + (execution as Record).mode === 'compile_only' + ) { + const reason = (execution as Record).reason; + notes.push(typeof reason === 'string' ? reason : 'Compiled SQL only; no rows were executed.'); + } + if (plan.has_fan_out === true) { + const description = typeof plan.fan_out_description === 'string' ? plan.fan_out_description.trim() : ''; + notes.push(description.length > 0 ? description : 'Fan-out detected: measure totals may be inflated by joins.'); + } + return notes; +} + +/** + * Default sl_query response is the minimum the agent needs to read the result: connection, headers, + * rows, totals, plus any correctness notes. The generated `sql` and the full `plan` are attached only + * when explicitly requested via `include`, since both are large and echo information the caller already has. + */ +function projectSlQueryResult(result: KtxSemanticLayerQueryResponse, include: ('plan' | 'sql')[]) { + const notes = slQueryNotes(result.plan); + return { + ...(result.connectionId !== undefined ? { connectionId: result.connectionId } : {}), + ...(result.dialect !== undefined ? { dialect: result.dialect } : {}), + headers: result.headers, + rows: result.rows, + totalRows: result.totalRows, + ...(notes.length > 0 ? { notes } : {}), + ...(include.includes('sql') ? { sql: result.sql } : {}), + ...(include.includes('plan') && result.plan ? { plan: result.plan } : {}), + }; +} + function jsonErrorToolResult(text: string): KtxMcpToolResult> { return { content: [{ type: 'text', text }], @@ -618,23 +671,22 @@ export function registerKtxContextTools(deps: RegisterKtxContextToolsDeps): void slQuerySchema, async (input, context) => { const onProgress = mcpProgressCallback(context); - return jsonToolResult( - await semanticLayer.query( - { - connectionId: input.connectionId, - query: { - measures: input.measures, - dimensions: input.dimensions, - filters: input.filters, - segments: input.segments, - order_by: input.order_by, - limit: input.limit, - include_empty: input.include_empty, - }, + const result = await semanticLayer.query( + { + connectionId: input.connectionId, + query: { + measures: input.measures, + dimensions: input.dimensions, + filters: input.filters, + segments: input.segments, + order_by: input.order_by, + limit: input.limit, + include_empty: input.include_empty, }, - onProgress ? { onProgress } : undefined, - ), + }, + onProgress ? { onProgress } : undefined, ); + return jsonToolResult(projectSlQueryResult(result, input.include)); }, ); } diff --git a/packages/cli/src/context/mcp/types.ts b/packages/cli/src/context/mcp/types.ts index 29a8c069..e9fc0ff2 100644 --- a/packages/cli/src/context/mcp/types.ts +++ b/packages/cli/src/context/mcp/types.ts @@ -110,7 +110,10 @@ interface KtxSemanticLayerReadResponse { yaml: string; } -interface KtxSemanticLayerQueryResponse { +/** @internal */ +export interface KtxSemanticLayerQueryResponse { + connectionId?: string; + dialect?: string; sql: string; headers: string[]; rows: unknown[][]; diff --git a/packages/cli/src/context/search/discover.ts b/packages/cli/src/context/search/discover.ts index b3456459..9a572daf 100644 --- a/packages/cli/src/context/search/discover.ts +++ b/packages/cli/src/context/search/discover.ts @@ -167,7 +167,7 @@ async function wikiCandidates( query: input.query, userId: options.userId, embeddingService: options.embeddingService ?? null, - limit: Math.max(input.limit ?? 15, 25), + limit: Math.max(input.limit ?? 10, 25), }); const records: CandidateRecord[] = []; for (const result of searchResults) { @@ -421,7 +421,8 @@ function hydrate( } return { ...ref, - score: maxScore > 0 ? Number((candidate.score / maxScore).toFixed(6)) : 0, + // 3 decimals is plenty for a relative-rank hint; 6 just spent bytes on noise. + score: maxScore > 0 ? Number((candidate.score / maxScore).toFixed(3)) : 0, }; }) .filter((result): result is KtxDiscoverDataRef => result !== null); @@ -433,7 +434,7 @@ export function createKtxDiscoverDataService( ): { search(input: KtxDiscoverDataInput): Promise } { return { async search(input) { - const limit = Math.max(1, Math.min(input.limit ?? 15, 50)); + const limit = Math.max(1, Math.min(input.limit ?? 10, 50)); const query = input.query.trim(); if (!query) { return []; diff --git a/packages/cli/src/skills/analytics/SKILL.md b/packages/cli/src/skills/analytics/SKILL.md index e4aa86d2..e6857e56 100644 --- a/packages/cli/src/skills/analytics/SKILL.md +++ b/packages/cli/src/skills/analytics/SKILL.md @@ -28,7 +28,12 @@ You have access to KTX MCP tools for data discovery, semantic-layer analysis, ra - Read entity details before writing SQL against an unfamiliar table. Do not assume column names. - Treat `sql_execution` as read-only. Writes are rejected by the server. - Validate value mentions with `dictionary_search` instead of guessing case or spelling. Treat a `dictionary_search` miss as non-authoritative. The index is built from profile-sampled values, so a missing value may simply have been outside the sample. Follow up with `sql_execution` against the most plausible columns before concluding the value is absent. -- When `connection_list` shows multiple connections, pass an explicit `connectionId` to every tool that takes one and where user intent pins a specific warehouse. Required: `entity_details`, `sl_read_source`, and `sql_execution`. Required when user intent is warehouse-specific, including wording like "in our warehouse" or "this warehouse": `memory_ingest`; without `connectionId`, the memory agent cannot update the semantic layer and the knowledge lands as wiki-only. Pass `connectionId` when intent pins a warehouse, otherwise omit for unscoped discovery: `sl_query`, `discover_data`, and `dictionary_search`. Never pass `connectionId` to `connection_list`, `wiki_search`, `wiki_read`, or `memory_ingest_status`. If intent is ambiguous for a required-or-scoped tool, ask the user which warehouse before calling. +- `connectionId` scoping when `connection_list` shows multiple connections: + - Always pass it: `entity_details`, `sl_read_source`, `sql_execution`. + - Pass it when intent pins a warehouse, otherwise omit for unscoped discovery: `sl_query`, `discover_data`, `dictionary_search`. + - `memory_ingest`: pass it for warehouse-specific knowledge (e.g. "in our warehouse"); without it the memory lands as wiki-only and cannot update the semantic layer. + - Never pass it: `connection_list`, `wiki_search`, `wiki_read`, `memory_ingest_status`. + - If scoping is required but intent is ambiguous, ask which warehouse before calling. - Show compact result tables for small outputs. For broad results, summarize the top findings and mention the applied limit. - Ask a concise clarification only when the metric, date range, entity, or grain is genuinely ambiguous and cannot be inferred from context. diff --git a/packages/cli/test/context/mcp/__snapshots__/mcp-tools-list.json b/packages/cli/test/context/mcp/__snapshots__/mcp-tools-list.json index 10cb0b77..b38851f4 100644 --- a/packages/cli/test/context/mcp/__snapshots__/mcp-tools-list.json +++ b/packages/cli/test/context/mcp/__snapshots__/mcp-tools-list.json @@ -65,7 +65,7 @@ }, "limit": { "default": 10, - "description": "Maximum wiki pages to return. Defaults to 10.", + "description": "Maximum wiki pages to return.", "type": "integer", "minimum": 1, "maximum": 50 @@ -307,7 +307,7 @@ { "name": "sl_query", "title": "Semantic Layer Query", - "description": "Execute a semantic-layer query and return rows, headers, generated SQL, and plan details. Example: sl_query({ connectionId: \"warehouse\", measures: [\"orders.order_count\"], dimensions: [{ field: \"orders.created_at\", granularity: \"month\" }] }).", + "description": "Execute a semantic-layer query and return headers, rows, and total row count, plus correctness notes (e.g. compile-only or fan-out) when relevant. The generated SQL and full query plan are omitted by default; request them with include: [\"sql\"] and/or include: [\"plan\"]. Example: sl_query({ connectionId: \"warehouse\", measures: [\"orders.order_count\"], dimensions: [{ field: \"orders.created_at\", granularity: \"month\" }], include: [\"sql\"] }).", "inputSchema": { "type": "object", "properties": { @@ -403,7 +403,7 @@ }, "direction": { "default": "asc", - "description": "Sort direction: \"asc\" or \"desc\". Defaults to \"asc\".", + "description": "Sort direction for this field.", "type": "string", "enum": [ "asc", @@ -418,15 +418,27 @@ }, "limit": { "default": 1000, - "description": "Maximum rows to return. Defaults to 1000.", + "description": "Maximum rows to return.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "include_empty": { "default": true, - "description": "Whether to include empty dimension groups. Defaults to true.", + "description": "Whether to include empty dimension groups.", "type": "boolean" + }, + "include": { + "default": [], + "description": "Extra detail to attach to the response: \"sql\" for the generated SQL, \"plan\" for the full query plan.", + "type": "array", + "items": { + "type": "string", + "enum": [ + "plan", + "sql" + ] + } } }, "required": [ @@ -443,9 +455,6 @@ "dialect": { "type": "string" }, - "sql": { - "type": "string" - }, "headers": { "type": "array", "items": { @@ -462,6 +471,15 @@ "totalRows": { "type": "number" }, + "notes": { + "type": "array", + "items": { + "type": "string" + } + }, + "sql": { + "type": "string" + }, "plan": { "type": "object", "propertyNames": { @@ -471,7 +489,6 @@ } }, "required": [ - "sql", "headers", "rows", "totalRows" @@ -1241,8 +1258,8 @@ } }, "limit": { - "description": "Maximum refs to return. Defaults to 15.", - "default": 15, + "description": "Maximum refs to return.", + "default": 10, "type": "integer", "minimum": 1, "maximum": 50 @@ -1396,7 +1413,7 @@ "description": "Parser-validated read-only SQL, e.g. \"select count(*) from public.orders\"." }, "maxRows": { - "description": "Maximum rows to return. Defaults to 1000.", + "description": "Maximum rows to return.", "default": 1000, "type": "integer", "minimum": 1, diff --git a/packages/cli/test/context/mcp/server.test.ts b/packages/cli/test/context/mcp/server.test.ts index f6d3e37e..38bc4af9 100644 --- a/packages/cli/test/context/mcp/server.test.ts +++ b/packages/cli/test/context/mcp/server.test.ts @@ -307,16 +307,12 @@ describe('createKtxMcpServer', () => { content: [ { type: 'text', - text: JSON.stringify( - { - headers: ['status', 'count'], - headerTypes: ['text', 'bigint'], - rows: [['paid', 42]], - rowCount: 1, - }, - null, - 2, - ), + text: JSON.stringify({ + headers: ['status', 'count'], + headerTypes: ['text', 'bigint'], + rows: [['paid', 42]], + rowCount: 1, + }), }, ], structuredContent: { @@ -598,6 +594,92 @@ describe('createKtxMcpServer', () => { ); }); + it('sl_query default response omits plan and sql but keeps compile-only and fan-out notes', async () => { + const fake = makeFakeServer(); + const semanticLayer: KtxSemanticLayerMcpPort = { + readSource: vi.fn(), + query: vi.fn().mockResolvedValue({ + connectionId: 'warehouse', + dialect: 'postgres', + sql: 'select count(*) from public.orders', + headers: ['order_count'], + rows: [], + totalRows: 0, + plan: { + sources_used: ['orders'], + has_fan_out: true, + fan_out_description: 'orders fans out across line_items', + execution: { mode: 'compile_only', reason: 'No execution adapter configured.' }, + }, + }), + }; + + createKtxMcpServer({ + server: fake.server, + userContext: { userId: 'local-user' }, + contextTools: { semanticLayer }, + }); + + const result = await getTool(fake.tools, 'sl_query').handler({ + connectionId: 'warehouse', + measures: ['orders.order_count'], + }); + + expect(result).toMatchObject({ + structuredContent: { + connectionId: 'warehouse', + dialect: 'postgres', + headers: ['order_count'], + rows: [], + totalRows: 0, + notes: ['No execution adapter configured.', 'orders fans out across line_items'], + }, + }); + const structured = (result as { structuredContent: Record }).structuredContent; + expect(structured.sql).toBeUndefined(); + expect(structured.plan).toBeUndefined(); + }); + + it('sl_query attaches sql and plan only when include requests them', async () => { + const fake = makeFakeServer(); + const plan = { sources_used: ['orders'], execution: { mode: 'executed' } }; + const semanticLayer: KtxSemanticLayerMcpPort = { + readSource: vi.fn(), + query: vi.fn().mockResolvedValue({ + connectionId: 'warehouse', + dialect: 'postgres', + sql: 'select count(*) from public.orders', + headers: ['order_count'], + rows: [[3]], + totalRows: 1, + plan, + }), + }; + + createKtxMcpServer({ + server: fake.server, + userContext: { userId: 'local-user' }, + contextTools: { semanticLayer }, + }); + + const result = await getTool(fake.tools, 'sl_query').handler({ + connectionId: 'warehouse', + measures: ['orders.order_count'], + include: ['plan', 'sql'], + }); + + expect(result).toMatchObject({ + structuredContent: { + sql: 'select count(*) from public.orders', + plan, + rows: [[3]], + totalRows: 1, + }, + }); + const structured = (result as { structuredContent: Record }).structuredContent; + expect(structured.notes).toBeUndefined(); + }); + it('entity_details rejects sql-style schema table ref aliases', async () => { const fake = makeFakeServer(); const entityDetails = makeAllContextTools().entityDetails!; @@ -798,7 +880,7 @@ describe('createKtxMcpServer', () => { connectionId: '00000000-0000-4000-8000-000000000001', }), ).resolves.toEqual({ - content: [{ type: 'text', text: JSON.stringify({ runId: 'run-1' }, null, 2) }], + content: [{ type: 'text', text: JSON.stringify({ runId: 'run-1' }) }], structuredContent: { runId: 'run-1' }, }); expect(ingest.ingest).toHaveBeenCalledWith({ @@ -825,21 +907,17 @@ describe('createKtxMcpServer', () => { content: [ { type: 'text', - text: JSON.stringify( - { - runId: 'run-1', - status: 'done', - stage: 'done', - done: true, - captured: { wiki: ['revenue'], sl: [], xrefs: [] }, - error: null, - commitHash: 'abc123', - skillsLoaded: ['wiki_capture'], - signalDetected: true, - }, - null, - 2, - ), + text: JSON.stringify({ + runId: 'run-1', + status: 'done', + stage: 'done', + done: true, + captured: { wiki: ['revenue'], sl: [], xrefs: [] }, + error: null, + commitHash: 'abc123', + skillsLoaded: ['wiki_capture'], + signalDetected: true, + }), }, ], structuredContent: { @@ -1047,19 +1125,15 @@ describe('createKtxMcpServer', () => { content: [ { type: 'text', - text: JSON.stringify( - { - connections: [ - { - id: '00000000-0000-4000-8000-000000000001', - name: 'Warehouse', - connectionType: 'POSTGRES', - }, - ], - }, - null, - 2, - ), + text: JSON.stringify({ + connections: [ + { + id: '00000000-0000-4000-8000-000000000001', + name: 'Warehouse', + connectionType: 'POSTGRES', + }, + ], + }), }, ], structuredContent: {